Refocus manual on public language usage

2026-08-14 08:17:25 +09:00
parent e0a9a8efb7
commit e0970acdcc
41 changed files with 611 additions and 1982 deletions
@@ -0,0 +1,56 @@
+# 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/souce`: public manual consumed by the site.
+
+## 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`](../../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:
+
+```sh
+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:
+
+1. Update the public EBNF in `doc/manual/souce/language/grammar.md` and the relevant language page.
+2. Update the Rust lexer/parser and tests.
+3. Update the Lezer and Tree-sitter grammars and regenerate their committed outputs.
+4. Update formatter, playground, and language-service tests as applicable.
+5. 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`](../../RELEASING.md).