@willbooster/tree-sitter-dart

Dart grammar for tree-sitter, forked from nielsenko/tree-sitter-dart. We are grateful to its authors and contributors. This is not an official release of that project.

This fork extends upstream's version 0.2.0 grammar, uses an external scanner, and generates the parser with the WillBooster/tree-sitter generator. The parser carries that fork's own ABI number (0x5742000c), so it loads only with the fork's runtime, version 17.0.1 or later in the 17.x series; upstream's runtime rejects it, and the fork's runtime rejects parsers generated by upstream's CLI.

Differences from upstream's parser

Known differences from upstream's 0.2.0 parser include:

• If-case statements and collection elements expose an if_case_clause containing case, the complete pattern, and its optional guard. Consequence and alternative fields remain on the containing if node.

• Arrow function bodies include trailing selectors. For (x) => a.b(x), the call belongs inside the function_expression_body; upstream attaches it to the arrow function instead. Nested arrow functions follow the same rule. Block-bodied function literals still support immediate calls and member access. Public node names and the parameters: and body: fields are preserved.

• Error recovery on invalid input can differ from upstream. Issue #4 tracks these differences.

• A NUL character in a line comment or between tokens parses as ordinary text, where upstream's lexer reports an error.

Support Scope

This fork maintains only full parsing: valid input yields a correct tree, and invalid input yields ERROR or MISSING nodes without crashing, hanging, or taking more than linear time. Incremental parsing works as in upstream tree-sitter but is not tested here, and no queries (highlights, locals, injections, tags) are shipped. Node types, field names, and the trees that error recovery produces may change; such changes are released as new major versions.

Usage

The npm package ships tree-sitter-dart.wasm for @willbooster/web-tree-sitter version 17.0.1 or later in the 17.x series, which runs in Node.js, Bun, browsers, and Cloudflare Workers. In Node.js and Bun, load the grammar from its path:

import { fileURLToPath } from 'node:url';

import { Language, Parser } from '@willbooster/web-tree-sitter';

await Parser.init();
const parser = new Parser();
const wasmPath = fileURLToPath(import.meta.resolve('@willbooster/tree-sitter-dart/tree-sitter-dart.wasm'));
parser.setLanguage(await Language.load(wasmPath));
const tree = parser.parse('void main() {}\n');

In browsers, serve both .wasm files and load them by URL (the example uses Vite's ?url imports):

import grammarUrl from '@willbooster/tree-sitter-dart/tree-sitter-dart.wasm?url';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtimeUrl from '@willbooster/web-tree-sitter/web-tree-sitter.wasm?url';

await Parser.init({ locateFile: () => runtimeUrl });
const parser = new Parser();
parser.setLanguage(await Language.load(grammarUrl));

Cloudflare Workers do not allow compiling Wasm at run time, so import both .wasm files as modules, with or without Node.js compatibility:

import grammar from '@willbooster/tree-sitter-dart/tree-sitter-dart.wasm';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtime from '@willbooster/web-tree-sitter/web-tree-sitter.wasm';

await Parser.init({ wasmModule: runtime });
const parser = new Parser();
parser.setLanguage(await Language.load(grammar));

The package also ships grammar.js and the node types in src/node-types.json.

In Rust, depend on the crate and on willbooster-tree-sitter, the runtime this package is tested and fuzzed with:

cargo add [email protected] --rename tree-sitter
cargo add willbooster-tree-sitter-dart --rename tree-sitter-dart

let mut parser = tree_sitter::Parser::new();
parser.set_language(&tree_sitter_dart::LANGUAGE.into())?;

Development

mise install
bun install --frozen-lockfile
bun run test/ci-setup # installs Chromium for the browser test
bun run build/ci
bun run test
script/parse-examples
cargo test

The scripts and tests generate, build, test, and parse with script/tree-sitter, the tree-sitter CLI of the WillBooster/tree-sitter runtime version locked in Cargo.lock, since the generator and the runtime of upstream's CLI are not the ones this package ships with. Its first run downloads that CLI from the runtime's GitHub Release, or builds it with cargo (whose build runs the CMake that mise.toml pins) when the download fails or the release has no binary that runs here. Run other CLI commands through it as well (e.g. script/tree-sitter parse --grammar-path . file.dart).

bun run generate records a fresh generation profile from the applicable test/corpus cases, then generates compact parser tables. It would also profile files tracked in examples/, but this repository tracks none: the directory holds only the clones script/parse-examples makes. The parser also embeds metadata from tree-sitter.json. After changing a grammar, tree-sitter.json, or a corpus case, regenerate and commit src/. Profiles in .tmp/generation-profiles/ are temporary and must not be committed. bun run build-wasm, bun run build/ci, and the release build regenerate the parsers before compiling them.

bun run test runs:

• the corpus in test/corpus, with the native build and with the Wasm build (the first run downloads the WASI SDK);
• a check that the real-world Dart files in examples/ fail to parse exactly as listed in script/known-failures.txt, which is empty now. The first run clones the repositories. The example repositories are pinned to commits in script/parse-examples. After a grammar change or a moved pin alters that list, script/parse-examples rewrites it; review its diff before committing;
• a performance check (test/unit/performance.test.ts) that recovering from an error on each line takes linear time, since consumers parse files while they are being edited. It loads the Wasm build through @willbooster/web-tree-sitter, which bun run build/ci rebuilds after regenerating the parser;
• a check (test/unit/runtimeVersion.test.ts) that @willbooster/web-tree-sitter in package.json and willbooster-tree-sitter in Cargo.lock are the same version, since the Wasm tests run on the former and the Rust tests, the fuzzer, and the CLI on the latter;
• tests that load the Wasm build with @willbooster/web-tree-sitter in Chromium (test/e2e/browser.test.ts) and in Cloudflare Workers with and without Node.js compatibility (test/e2e/workers.test.ts).

The tests and script/parse-examples compile the parser into .tmp/tree-sitter-lib rather than the CLI's cache shared by every checkout.

CI also runs these tests on Linux arm64 and macOS, where the CLI compiles the parser and the scanner with the platform's C compiler as the crate does for its users, and fuzzes the parser with libFuzzer and sanitizers (.github/workflows/robustness.yml).

References

• Dart language specification