@gitkraken/tree-sitter-wasm

Tree-sitter grammars compiled to WASM, with multiple versions of a grammar shipped side by side where a language's syntax has drifted across editions.

Why this exists

Off-the-shelf grammar bundles (tree-sitter-wasms, @vscode/tree-sitter-wasm) ship a single grammar version per language, and no single version parses both the legacy and modern syntax of an evolving language. Building the grammars here lets us ship multiple versions of the same grammar and pin everything against a known ABI.

Rust is the clearest case. Measured on a 1059-file corpus of valid Rust (false positive = grammar reports an error on valid code):

| grammar | false positives | |---|---| | old only (try!-friendly) | 1.8% | | latest only | 3.3% (rejects pre-2018 try!) | | newest → oldest | 0.0% |

try! (removed when try became reserved in edition 2018) only parses on the old grammar; let-else (1.65) only on the new one. Shipping both and trying newest-first, oldest-as-fallback covers the union.

ABI

Grammars build at ABI 14/15 (current tree-sitter-cli). Both load under [email protected] and 0.26.x (verified). 0.26 raised the ABI floor, but that only orphans third-party ABI-13 wasm built with tree-sitter-cli 0.20.x; grammars built here are ABI 14/15, so they load on the latest runtime. 0.26 also renamed the engine wasm asset to web-tree-sitter/web-tree-sitter.wasm (was tree-sitter.wasm).

Install

Published to public npm (private source repo, public artifact). No registry config or auth needed.

pnpm add @gitkraken/tree-sitter-wasm

The tarball ships the compiled out/*.wasm plus out/manifest.json. Releases publish on a v* tag via .github/workflows/publish.yml (uses the NPM_TOKEN_GITKRAKEN org secret).

Build

pnpm install
pnpm build      # clones each grammar at its pinned ref, compiles to out/*.wasm
pnpm test       # contract test: files load, ABI in range, edition invariants hold

Outputs out/tree-sitter-<lang>.wasm (single version) or out/tree-sitter-<lang>.<label>.wasm (multi-version), plus out/manifest.json recording ref + resolved SHA per grammar.

Toolchain: tree-sitter build --wasm auto-downloads wasi-sdk. No manual emscripten setup.

Grammars

Configured in grammars.json. A language with edition/version syntax drift (currently Rust) ships latest + legacy; a consumer parses with the newest and falls back to older versions.

Multi-version only helps when the false positives come from edition drift. For C, C++ and C# the dominant cause is instead the C preprocessor / conditional compilation (#if, #region), which a context-free grammar cannot resolve: measured ~50%+ on C/C++ and 6.73% on C# (60% of it preprocessor-driven). That is intrinsic to parsing those languages with tree-sitter, not grammar age, so no combination of versions fixes it. Those grammars ship a single version.