Decodal/doc/manual/souce/development.md

Development

This document describes the development workflow for Decodal itself.

Rust checks

Run the normal Rust checks from the repository root.

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.

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

Web site and playground

The Svelte documentation site and browser playground are kept in:

site/decodal-site/

The site imports Markdown files from doc/manual/souce/ and renders them as mdBook-style pages. The playground loads decodal-wasm and evaluates DCDL entirely in the browser.

Important files:

site/decodal-site/src/App.svelte
site/decodal-site/src/Playground.svelte
site/decodal-site/src/lib/docs.js
crates/decodal-wasm/src/lib.rs

Build the WebAssembly package before building the site:

cd site/decodal-site
npm install
npm run build:wasm
npm run build

npm run build:wasm writes generated files into:

site/decodal-site/src/wasm/

These generated files are committed so the site can be built without requiring every consumer to regenerate the wasm package first.

To run the site locally:

cd site/decodal-site
npm run dev

Tree-sitter grammar

The Tree-sitter grammar is kept in:

editors/tree-sitter-decodal/

Important files:

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:

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

To inspect a parse tree:

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, Tree-sitter CLI tooling, and wasm-pack tooling.

nix develop

The shell provides:

• cargo
• rustc
• rustfmt
• clippy
• node
• npm
• wasm-pack
• lld
• tree-sitter
• nixfmt