# tree-sitter-zuzu

Tree-sitter grammar for ZuzuScript.

This project provides the concrete syntax layer for editors and structural
tools. It is intentionally separate from the runtime parsers in `zuzu-perl`,
`zuzu-rust`, and `zuzu-js`: the runtimes remain the source of truth for
execution semantics, while this grammar is optimised for incremental parsing,
highlighting, navigation, folding, indentation, and language-server indexing.
It also includes textobject queries for selection-aware editors.

## Current Scope

The grammar covers:

- `.zzs` scripts and `.zzm` modules;
- extensionless scripts with a `zuzu` shebang;
- embedded POD blocks, including POD that continues to end of file;
- comments;
- imports, including `try import` and conditional imports;
- variable and destructuring declarations;
- functions, methods, classes, compact class declarations, and traits;
- block, conditional, loop, switch, try/catch, return, throw, and built-in
  output/debug statements;
- expression precedence from the user guide operator table;
- call, member, index, slice, dict access, path, chain, ternary, and assignment
  expressions;
- string, interpolated template, regexp, number, boolean, null, list, dict,
  PairList, bag, and set literals;
- Unicode operator spellings.

Current verification baseline:

- `npm test` passes the generated parser corpus and highlight assertions.
- The corpus includes a focused malformed-source recovery fixture.
- `languagetests` parse smoke: 125/125 files currently parse without `ERROR`
  or `MISSING` nodes.
- `stdlib/modules` parse smoke: 86/86 files currently parse without `ERROR`
  or `MISSING` nodes.

Known gaps before a 1.0 grammar:

- Broaden corpus coverage from the user guide, examples, `languagetests`, and
  `stdlib/modules` so future grammar work has smaller focused fixtures.
- Queryable highlighting for comparison and collection word operators should be
  revisited if the grammar later exposes them through aliases or named tokens.
- Zed integration exists as a grammar-only local extension in `../zed-zuzu`.
- Pulsar migration is currently audit-only; see `docs/pulsar-migration.md`.

## Commands

```sh
npm install
npm test
npm run parse:examples
npm run parse:smoke
```

`npm test` runs `tree-sitter generate` and `tree-sitter test`. The parse smoke
script parses representative source files, internal smoke fixtures, and sibling
`languagetests`/`stdlib/modules` directories when they are available. It fails
if the generated parser emits `ERROR` or `MISSING` nodes.

## Repository Layout

```text
grammar.js
queries/
test/corpus/
test/highlight/
test/smoke/
examples/
scripts/
docs/editor-install.md
docs/node-names.md
docs/syntax-inventory.md
```

## Pulsar

The current Pulsar package is still TextMate/CSON-based. The migration path is
documented in `docs/pulsar-migration.md`; the short version is that this grammar
is currently useful for auditing the CSON grammar, but the Pulsar package should
not drop its existing grammar until a dedicated registration spike proves
current Pulsar can load the generated parser and queries without regressing
package behaviour.
