> ## Documentation Index
> Fetch the complete documentation index at: https://mehen.ophi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Update grammars

> Bump pinned tree-sitter grammar versions and regenerate the kind enums.

The languages that go through tree-sitter (Go, C, and PowerShell) are parsed via pinned
`tree-sitter-<lang>` crates. Grammars change over time and need periodic updates — both for bug fixes
and to keep up with new syntax.

<Note>
  Kotlin is **not** tree-sitter-backed — it uses an ANTLR grammar. To regenerate the Kotlin parser,
  see [Add a new language → Adding an ANTLR-backed language](/developers/new-language) and
  `cargo xtask antlr generate kotlin`, not the tree-sitter flow below.
</Note>

Grammars can be updated on **Linux** and **macOS** natively, or on **Windows** using **WSL**.

## Currently pinned tree-sitter grammars

Each grammar is **inline-pinned in its owning `crates/mehen-<lang>/Cargo.toml`** — the analyzer crate
is the single source of truth. `xtask` never pins a grammar itself; the kind-enum generator reaches
each grammar through the analyzer crate's `__grammar_language()` accessor (a path dependency), so the
codegen and the runtime parser always link the exact same revision. Bumping the pin in the analyzer's
`Cargo.toml` is therefore enough — there is no second `[workspace.dependencies]` line to keep in sync.

| Grammar            | Owning crate       | Generated `grammar.rs`?                 |
| ------------------ | ------------------ | --------------------------------------- |
| `tree-sitter-c`    | `mehen-c`          | Yes — codegen target `c`                |
| `tree-sitter-go`   | `mehen-go`         | Yes — codegen target `go`               |
| `tree-sitter-pwsh` | `mehen-powershell` | No — matches string node-kinds directly |

<Note>
  PowerShell is tree-sitter-backed but has **no** generated `grammar.rs` and is **not** an `xtask`
  codegen target. `mehen-powershell` matches node kinds by their string names against
  `tree_sitter_pwsh::LANGUAGE` at runtime, so bumping `tree-sitter-pwsh` needs no kind-enum
  regeneration — only C and Go do.
</Note>

The Python, TypeScript / JavaScript / TSX / JSX, PHP, Ruby, Rust, Kotlin, Java, SQL, and Markdown
analyzers do **not** use tree-sitter; they have no `grammar.rs` and need no kind-enum regeneration.
(Kotlin and Java are ANTLR-backed — see the note above; SQL uses sqruff and Markdown uses
pulldown-cmark.)

## Update process

<Steps>
  <Step title="Bump the pin">
    Update the single inline pin in the owning `crates/mehen-<lang>/Cargo.toml`:

    ```toml theme={null}
    tree-sitter-c = "=x.xx.x"
    ```

    `xtask` picks up the new revision automatically through the `mehen-<lang>` path dependency, so
    there is no separate `xtask/Cargo.toml` or `[workspace.dependencies]` line to bump.
  </Step>

  <Step title="Regenerate kind enums">
    ```bash theme={null}
    cargo xtask tree-sitter generate --all
    ```

    This rewrites every codegen-target crate's `grammar.rs` (C and Go) from the pinned grammar's
    `node-kind` table. CI runs `cargo xtask tree-sitter check-generated` to ensure pinned-grammar
    bumps without a regenerate are caught at PR time. (PowerShell has no `grammar.rs`, so bumping
    `tree-sitter-pwsh` skips this step.)
  </Step>

  <Step title="Fix breakage">
    New node kinds may appear (and need handling), and existing node kinds may be renamed or
    restructured. Update analyzer code accordingly.
  </Step>

  <Step title="Run validation">
    ```bash theme={null}
    cargo nextest run --all-features
    cargo insta test --workspace --all-features --check --unreferenced reject \
        --test-runner nextest --no-test-runner-fallback --disable-nextest-doctest
    cargo clippy --all-targets --all-features --locked
    ```
  </Step>

  <Step title="Open a PR">
    Commit the updated `Cargo.toml`, `Cargo.lock`, and any regenerated `grammar.rs` files.
  </Step>
</Steps>

## Automation

Dependabot raises grammar bump PRs automatically. The `regenerate-grammars` workflow detects those
PRs (branch name contains `tree-sitter`) and runs `cargo xtask tree-sitter generate --all` plus the
test suite, then commits the regenerated files back to the PR branch. Reviewers should still verify
analyzer code still handles any renamed kinds.

## See also

* [How-to: Add a new language](/developers/new-language).