tree-sitter-ggsql/ — grammar package

The Tree-sitter grammar for ggsql. Consumed by the Rust parser in /src/parser/, by editor highlighters, and by language-aware tooling. Workspace member, also published to npm and PyPI.

Layout

tree-sitter-ggsql/
├── grammar.js              Source of truth — the grammar definition
├── tree-sitter.json        Tree-sitter project config
├── package.json            Node/npm bindings (default consumer)
├── Cargo.toml              Rust binding (path = bindings/rust/lib.rs)
├── pyproject.toml          Python binding
├── setup.py                Python build helper
├── binding.gyp             node-gyp config for the Node binding
├── src/
│   ├── grammar.json        Generated — JSON form of grammar.js
│   ├── parser.c            Generated — the parser
│   └── tree_sitter/        Generated parser headers
├── bindings/
│   ├── rust/               lib.rs + build.rs (used by the workspace)
│   ├── node/               JS binding glue
│   ├── python/             Python binding glue
│   └── c/                  C binding glue
├── queries/
│   └── highlights.scm      Highlight queries used by editors
└── test/
    └── corpus/             Tree-sitter test corpus (parser test cases)

The files under src/ are generated by tree-sitter generate from grammar.js — they are committed so downstream consumers don't need the tree-sitter CLI to build.

Grammar at a glance

grammar.js defines a query rule that is optional(sql_portion) + repeat(visualise_statement). The SQL portion is recognised structurally enough to know where it ends (statement boundaries, recursive subqueries, WITH compound statements) without re-implementing a SQL parser — the actual SQL is handed off to the configured Reader. The VISUALISE side is parsed in detail (clauses, layer types, mappings, settings, scales, facets, projections, labels) so /src/parser/builder.rs can build a typed AST from it.

For ggsql language semantics, see /doc/syntax/ — this package only defines how text is parsed, not what the resulting tree means.

Workflow

# Regenerate src/grammar.json + parser.c after editing grammar.js
npx tree-sitter generate

# Run the corpus tests in test/
npx tree-sitter test

# All tests via npm (corpus + the Node binding smoke test)
npm test

In editors with tree-sitter support: npx tree-sitter playground to interactively probe the parser.

Adding new ggsql syntax

1. Edit grammar.js. Pick node names that downstream code can match against.
2. Add corpus tests under test/corpus/ covering the new construct (and any conflicts).
3. npx tree-sitter generate to regenerate src/grammar.json and parser.c. Commit those.
4. Update /src/parser/builder.rs to produce the matching AST nodes.
5. If the new syntax should be highlighted, update queries/highlights.scm.
6. Document the syntax under /doc/syntax/.

Bindings

See also

• /CLAUDE.md — workspace overview.
• /src/parser/ (covered in /src/CLAUDE.md) — the consumer that turns the CST into typed Plot values.
• /doc/syntax/ — authoritative ggsql syntax reference.