tree-sitter-wax

A tree-sitter grammar for the Wax language (a Rust-like syntax for WebAssembly).

It produces a concrete syntax tree for editor tooling: syntax highlighting, structural selection, folding, indentation, and symbol navigation, across every tree-sitter host (Neovim, Helix, Zed, GitHub, …).

Editor setup lives next to the other editor integrations: editors/nvim/, editors/helix/, and editors/emacs/.

Status

The grammar is validated by a differential check against the reference wax compiler over the repository's .wax corpora (docs examples, test/cram-tests, test/wasmoo/wax): it accepts a file if and only if the compiler's parser does, with a small set of documented, value-level exceptions (see below).

Layout

| Path | What | |------|------| | grammar.js | The grammar (the source of truth for this package). | | src/scanner.c | External scanner — nested block comments only. | | src/parser.c, src/grammar.json, src/node-types.json | Generated by tree-sitter generate; committed. | | queries/highlights.scm | Highlight captures, nvim-treesitter conventions (mirroring editors/vscode/syntaxes/wax.tmLanguage.json). | | queries/locals.scm, queries/injections.scm | Scope/reference queries; injections (none). | | test/corpus/*.txt | S-expression unit tests (tree-sitter test). | | test/expected-errors.txt | Fixtures that must be rejected (negative tests). | | scripts/smoke-parse.sh | Parse the whole curated corpus; assert zero ERROR/MISSING. | | scripts/extract-doc-blocks.sh | Pull ```wax blocks out of docs/src/examples.md. | | bindings/ | Node and Rust bindings. |

Developing

Requires a modern tree-sitter-cli (0.24+; pinned as a dev dependency) and a C compiler for the external scanner. Node bindings additionally need node-gyp.

npm install
npx tree-sitter generate      # regenerate src/parser.c from grammar.js
npx tree-sitter test          # run test/corpus/*.txt
./scripts/smoke-parse.sh      # differential/zero-error check over the corpus
npx tree-sitter parse FILE    # parse one file

After editing grammar.js, always re-run tree-sitter generate and commit the regenerated src/ files.

Relationship to the compiler

This grammar re-encodes the surface syntax defined by src/lib-wax/parser.mly and src/lib-wax/lexer.ml. It intentionally does not reproduce the compiler's semantic analysis, and diverges from it in a few well-scoped, tooling-appropriate ways:

1. No type or semantic checking. Syntactically well-formed but ill-typed programs parse cleanly (they are positive parse tests).
2. No value-range checks. A page size that is not a power of two, a \u{…} escape beyond U+10FFFF, or an exact marker on an abstract heap type (&!any) parse here but are rejected by the compiler's parser.
3. Comparisons are left-associative. The compiler makes them non-associative (chaining is a type error); tree-sitter has no non-associativity, so a == b == c parses (as (a == b) == c) and would fail type-checking.
4. #[if] / #[else] are not paired. They are emitted as independent sibling nodes; consumers that need the pairing walk the siblings.
5. Error recovery. Invalid input yields ERROR/MISSING nodes rather than a hard failure — the right behavior for a live editor.