# Development

This document describes the development workflow for Decodal itself.

## Rust checks

Run the normal Rust checks from the repository root.

```sh
cargo fmt --check
cargo test
cargo check -p decodal-core --no-default-features
nix flake check
```

Regex support is optional and should be tested explicitly when touched.

```sh
cargo test -p decodal-core --features regex
cargo run -q -p decodal --features regex -- examples/regex/main.dcdl
```

## Tree-sitter grammar

The Tree-sitter grammar is kept in:

```text
editors/tree-sitter-decodal/
```

Important files:

```text
editors/tree-sitter-decodal/grammar.js
editors/tree-sitter-decodal/queries/highlights.scm
editors/tree-sitter-decodal/queries/locals.scm
editors/tree-sitter-decodal/corpus/basic.txt
```

The grammar is intended to be portable across editors such as Zed, Neovim, Helix, and Emacs.
Zed support should consume this grammar rather than relying on a TextMate grammar.

## Tree-sitter commands

From the grammar directory:

```sh
cd editors/tree-sitter-decodal
npm install
npx tree-sitter generate
npx tree-sitter test
```

To inspect a parse tree:

```sh
npx tree-sitter parse ../../examples/advanced/main.dcdl
```

The generated parser files under `editors/tree-sitter-decodal/src/` are committed so editor integrations can consume the grammar without regenerating it first.
`node_modules/` is ignored and must not be committed.

## Updating the grammar

When the Decodal syntax changes:

1. Update `grammar.js`.
2. Run `npx tree-sitter generate`.
3. Add or update corpus tests in `corpus/`.
4. Update highlight queries in `queries/highlights.scm` if token names changed.
5. Run `npx tree-sitter test`.
6. Run Rust checks from the repository root if the language parser or examples also changed.

## Development shell

The Nix development shell includes Rust tooling, Node.js, and Tree-sitter CLI tooling.

```sh
nix develop
```

The shell provides:

- `cargo`
- `rustc`
- `rustfmt`
- `clippy`
- `node`
- `npm`
- `tree-sitter`
- `nixfmt`