# @willbooster/tree-sitter-ruby
[](https://www.npmjs.com/package/@willbooster/tree-sitter-ruby)
[](https://www.npmjs.com/package/@willbooster/tree-sitter-ruby)
[](https://github.com/WillBooster/tree-sitter-ruby/actions/workflows/test.yml)
[](https://github.com/WillBooster/tree-sitter-ruby/actions/workflows/test-rust.yml)
[](https://github.com/semantic-release/semantic-release)
[](https://github.com/WillBooster/shared/tree/main/packages/wbfy)
[](https://crates.io/crates/willbooster-tree-sitter-ruby)
Ruby grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter), forked from
[tree-sitter/tree-sitter-ruby](https://github.com/tree-sitter/tree-sitter-ruby). We are grateful
to its authors and contributors. This is not an official release of that project.
This fork extends the upstream grammar to parse anonymous block forwarding, spaced block arguments, and command calls in endless methods, with a parser generated by
[WillBooster/tree-sitter](https://github.com/WillBooster/tree-sitter), whose compact parse tables make the
parser smaller. The parser carries that fork's own ABI number (`0x5742000b`), so it loads only with the WillBooster
runtime 15.x; upstream's tree-sitter runtime and other major versions of the fork's runtime reject it.
The scanner preserves long heredoc identifiers
when their state fits the runtime's serialization buffer. If the open heredocs cannot fit, their bodies are parsed as
code instead of aborting the process.
## 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. Parse each input without a previous tree; reusing
an old tree is unsupported. 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-ruby.wasm` for
[@willbooster/web-tree-sitter](https://www.npmjs.com/package/@willbooster/web-tree-sitter), which runs in Node.js, Bun,
browsers, and Cloudflare Workers. The parser requires runtime 15.x.
In Node.js and Bun, load the grammar from its path:
```js
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-ruby/tree-sitter-ruby.wasm'));
parser.setLanguage(await Language.load(wasmPath));
const tree = parser.parse('puts "Hello"\n');
```
In browsers, load the grammar from its URL. With Vite:
```js
import rubyUrl from '@willbooster/tree-sitter-ruby/tree-sitter-ruby.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(rubyUrl));
```
In Cloudflare Workers, which do not allow compiling Wasm at run time, import both `.wasm` files as modules:
```js
import ruby from '@willbooster/tree-sitter-ruby/tree-sitter-ruby.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(ruby));
```
The package also ships the node types in `src/node-types.json`.
In Rust, depend on the [crate](https://crates.io/crates/willbooster-tree-sitter-ruby) and on
[willbooster-tree-sitter](https://crates.io/crates/willbooster-tree-sitter), the runtime this package is tested and
fuzzed with. The parser requires runtime 15.x:
```sh
cargo add willbooster-tree-sitter@15.0.0 --rename tree-sitter
cargo add willbooster-tree-sitter-ruby --rename tree-sitter-ruby
```
```rust
let mut parser = tree_sitter::Parser::new();
parser.set_language(&tree_sitter_ruby::LANGUAGE.into())?;
```
## Development
```sh
mise install
bun install --frozen-lockfile
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 file.rb`).
`bun run generate` records a fresh generation profile from the applicable `test/corpus` cases and Git-tracked
files in `examples/`, then generates compact parser tables. The parser also embeds metadata from `tree-sitter.json`.
After changing the grammar, `tree-sitter.json`, a corpus case, or a tracked example, regenerate and commit `src/`. Stage
added or removed examples with `git add -A examples` before generation so the profile uses the intended file list.
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 parser before compiling it.
`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);
- included-range comment checks (`test/unit/includedRanges.test.ts`), which load the Wasm build produced by
`bun run build/ci`;
- a check that the real-world Ruby files of [ruby/spec](https://github.com/ruby/spec) cloned into `examples/` fail to
parse exactly as listed in `script/known-failures.txt`. The first run clones the repository, which is pinned to a
commit 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;
- bounded CPU-growth checks for error recovery and comment chains (`test/unit/performance.test.ts`);
- a check that `package.json` and `Cargo.lock` test the same runtime version (`test/unit/runtimeVersion.test.ts`);
- checks that the Wasm build parses in Chromium (`test/unit/browser/`) and in Cloudflare Workers with and without
Node.js compatibility (`test/unit/workerd.test.ts`). Run `bun run test/ci-setup` once to install Chromium.
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 Rust binding compiles the parser natively, and fuzzes the
parser with libFuzzer and sanitizers (`.github/workflows/robustness.yml`).
### References
- [AST Format of the Whitequark parser](https://github.com/whitequark/parser/blob/master/doc/AST_FORMAT.md)