# AGENTS

## Scope

This repository is a CLI-first Rust project (`mehen`). Prefer changes that keep behavior centered on the `mehen` binary.

## Build and Test

Use these commands from the repo root:

```bash
cargo build
cargo check
cargo fmt --all
cargo clippy --all-targets --all-features --locked
```

## Recommended Test Runner

Use `nextest` as the default test runner for local and CI work.

```bash
cargo nextest run --all-features
```

## Snapshot Tests (insta)

`insta` is used heavily in metric tests. Prefer running snapshot checks via `cargo insta` on top of `nextest`:

```bash
cargo insta test --all-features --check --workspace --unreferenced reject --test-runner nextest --no-test-runner-fallback --disable-nextest-doctest
```

## Notes for Code Changes

- Keep metric behavior deterministic across platforms.
- Avoid introducing dead code paths; this project is consumed as a CLI.
- Never edit `crates/mehen-*/src/grammar.rs` directly: these files are generated by `cargo xtask tree-sitter generate <language>`. This applies only to tree-sitter-backed crates; `mehen-markdown` is `pulldown-cmark`-backed and has no `grammar.rs` — its node-kind enum in `crates/mehen-markdown/src/kind.rs` is hand-authored and edited directly.
- For grammar bumps or new tree-sitter-backed languages, update the pin in both `xtask/Cargo.toml` and the owning `crates/mehen-<lang>/Cargo.toml`, then regenerate with `cargo xtask tree-sitter generate --all`.
- Keep the workspace `antlr-rust-runtime` and `antlr-rust-codegen` pins in lockstep. xtask links codegen directly; after either pin changes, run `cargo xtask antlr generate --all` and commit every generated parser artifact.
