Developing Decodal

Development notes live here rather than in the public manual. The manual describes released language behavior and public integration APIs; implementation plans and unresolved design work belong in issues or pull requests.

Repository map

crates/decodal-core: parser, evaluator, public Rust API, and tests.
crates/decodal-derive: Decodal derive macros.
crates/decodal-language-service: host-configurable semantic analysis and completion.
crates/decodal-language-tools: source-preserving formatter and tooling.
crates/decodal-lsp: LSP transport and document synchronization.
crates/decodal-wasm: WebAssembly bindings.
packages/decodal-wasm: generated npm and JSR runtime package.
packages/decodal-codemirror: CodeMirror language support and formatter WebAssembly.
editors/lezer-decodal and editors/tree-sitter-decodal: downstream editor grammars.
site/decodal-site: documentation site and playground.
doc/manual/source: English public manual consumed by the site.
doc/manual/source/jp: Japanese translation of the public manual.

Runtime architecture

The host owns I/O. ImportLoader turns an import specifier into DCDL source or a structured Value, and HostEnvironment installs the same loader and globals for production and editor tooling.

Evaluation proceeds through parse, lazy expression evaluation, and materialization. Object fields, module roots, imports, arguments, and defaults are represented by memoized thunks. A thunk re-entered while it is being evaluated produces a cycle diagnostic.

Runtime values distinguish concrete values from abstract ranges. Composition and as preserve that distinction; materialization selects defaults and rejects unresolved ranges or functions. Data is the output-only representation.

Diagnostics retain Decodal source spans. Structured host values use their stable import key and logical value path rather than synthetic source spans.

Checks

Run the release validation commands documented in RELEASING.md. For a focused change, run the tests for the affected crate or package first, then the full workspace and site checks before release.

The documentation site can be checked without regenerating committed WebAssembly artifacts:

npm --prefix site/decodal-site test
npm --prefix site/decodal-site run build

Use npm --prefix site/decodal-site run build:wasm when Rust bindings or formatter behavior changed.

Syntax changes

When syntax changes:

Update the public EBNF in doc/manual/source/language/grammar.md and the relevant language page.
Update the Rust lexer/parser and tests.
Update the Lezer and Tree-sitter grammars and regenerate their committed outputs.
Update formatter, playground, and language-service tests as applicable.
Run the validation commands in RELEASING.md.

The Rust parser is authoritative for evaluation. Lezer and Tree-sitter are downstream editor integrations and are not runtime or formatter dependencies.

Releases

Package versions, validation commands, publish order, and registry commands are maintained only in RELEASING.md.