From 709555a9581940e1876600c0c6c47e48a0f2bdcd Mon Sep 17 00:00:00 2001 From: Kyuhwan Lee <145569428+wtdlee@users.noreply.github.com> Date: Fri, 26 Dec 2025 19:54:25 +0900 Subject: [PATCH 1/4] fix(web): add early version check in Language.load() Add ABI version compatibility check immediately after loading a WASM language file in Language.load(). This provides: 1. Earlier failure detection - fails at load time instead of setLanguage() 2. More helpful error message - indicates WASM file may be built with incompatible tree-sitter-cli version 3. Better developer experience - clearer guidance on how to fix the issue This helps users who use pre-built WASM files from third-party packages (like tree-sitter-wasms) that may be built with older tree-sitter-cli versions incompatible with newer web-tree-sitter releases. Relates to #5171 --- lib/binding_web/src/language.ts | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/lib/binding_web/src/language.ts b/lib/binding_web/src/language.ts index 664e355b..8e54b676 100644 --- a/lib/binding_web/src/language.ts +++ b/lib/binding_web/src/language.ts @@ -1,7 +1,7 @@ import { C, INTERNAL, Internal, assertInternal, SIZE_OF_INT, SIZE_OF_SHORT } from './constants'; import { LookaheadIterator } from './lookahead_iterator'; import { unmarshalLanguageMetadata } from './marshal'; -import { TRANSFER_BUFFER } from './parser'; +import { TRANSFER_BUFFER, LANGUAGE_VERSION, MIN_COMPATIBLE_VERSION } from './parser'; const LANGUAGE_FUNCTION_REGEX = /^tree_sitter_\w+$/; @@ -226,6 +226,8 @@ export class Language { /** * Load a language from a WebAssembly module. * The module can be provided as a path to a file or as a buffer. + * + * @throws {Error} If the WASM file was built with an incompatible version of tree-sitter-cli. */ static async load(input: string | Uint8Array): Promise { let binary: Uint8Array | WebAssembly.Module; @@ -263,6 +265,19 @@ export class Language { throw new Error('Language.load failed: no language function found in Wasm file'); } const languageAddress = mod[functionName](); - return new Language(INTERNAL, languageAddress); + const language = new Language(INTERNAL, languageAddress); + + // Early version compatibility check + const version = language.abiVersion; + if (version < MIN_COMPATIBLE_VERSION || LANGUAGE_VERSION < version) { + throw new Error( + `Incompatible language version ${version}. ` + + `Compatibility range ${MIN_COMPATIBLE_VERSION} through ${LANGUAGE_VERSION}. ` + + `The WASM file may have been built with an incompatible version of tree-sitter-cli. ` + + `Please regenerate the WASM file using a compatible tree-sitter-cli version.` + ); + } + + return language; } } From baf427467c618c12a5805c640ec148f5d35dc683 Mon Sep 17 00:00:00 2001 From: Kyuhwan Lee <145569428+wtdlee@users.noreply.github.com> Date: Fri, 26 Dec 2025 21:35:38 +0900 Subject: [PATCH 2/4] Update lib/binding_web/src/language.ts Co-authored-by: ObserverOfTime --- lib/binding_web/src/language.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/binding_web/src/language.ts b/lib/binding_web/src/language.ts index 8e54b676..a8a5d6fe 100644 --- a/lib/binding_web/src/language.ts +++ b/lib/binding_web/src/language.ts @@ -227,7 +227,7 @@ export class Language { * Load a language from a WebAssembly module. * The module can be provided as a path to a file or as a buffer. * - * @throws {Error} If the WASM file was built with an incompatible version of tree-sitter-cli. + * @throws {RangeError} If the Wasm file was built with an incompatible version of tree-sitter-cli. */ static async load(input: string | Uint8Array): Promise { let binary: Uint8Array | WebAssembly.Module; From 2d48d4db899813ec1df1aa02b8c6ee9dd82bcf18 Mon Sep 17 00:00:00 2001 From: Kyuhwan Lee <145569428+wtdlee@users.noreply.github.com> Date: Fri, 26 Dec 2025 21:35:44 +0900 Subject: [PATCH 3/4] Update lib/binding_web/src/language.ts Co-authored-by: ObserverOfTime --- lib/binding_web/src/language.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/binding_web/src/language.ts b/lib/binding_web/src/language.ts index a8a5d6fe..39623f1a 100644 --- a/lib/binding_web/src/language.ts +++ b/lib/binding_web/src/language.ts @@ -270,7 +270,7 @@ export class Language { // Early version compatibility check const version = language.abiVersion; if (version < MIN_COMPATIBLE_VERSION || LANGUAGE_VERSION < version) { - throw new Error( + throw new RangeError( `Incompatible language version ${version}. ` + `Compatibility range ${MIN_COMPATIBLE_VERSION} through ${LANGUAGE_VERSION}. ` + `The WASM file may have been built with an incompatible version of tree-sitter-cli. ` + From a7eff029cd4c151af9f9874df89f783aff6e120e Mon Sep 17 00:00:00 2001 From: Kyuhwan Lee <145569428+wtdlee@users.noreply.github.com> Date: Fri, 26 Dec 2025 21:35:50 +0900 Subject: [PATCH 4/4] Update lib/binding_web/src/language.ts Co-authored-by: ObserverOfTime --- lib/binding_web/src/language.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/binding_web/src/language.ts b/lib/binding_web/src/language.ts index 39623f1a..d59ace42 100644 --- a/lib/binding_web/src/language.ts +++ b/lib/binding_web/src/language.ts @@ -273,8 +273,7 @@ export class Language { throw new RangeError( `Incompatible language version ${version}. ` + `Compatibility range ${MIN_COMPATIBLE_VERSION} through ${LANGUAGE_VERSION}. ` + - `The WASM file may have been built with an incompatible version of tree-sitter-cli. ` + - `Please regenerate the WASM file using a compatible tree-sitter-cli version.` + `The Wasm file may have been built with an incompatible version of tree-sitter-cli. ` ); }