Expand description
§decl-lang
Decl is a declarative language for describing, generating, and validating structured data — a JSON superset with a strong static type system, constraints with first-class diagnostics, references, physical quantities, generics, and modules. Pure, deterministic, terminating.
This crate is the native Rust implementation of the whole language:
the tree-sitter grammar is compiled in, decl checks, evaluates,
validates, and formats modules (packages included), and decl-lsp is
the language server — no Node.js or wasm involved.
cargo install decl-lang§Command line
decl check schema.decl # static checks, module-aware (exit 1 on errors)
decl evaluate site.decl # evaluate every output -> {"name": value, ...}
decl evaluate site.decl --output site # one output -> its canonical JSON on stdout
decl evaluate site.decl --json # {"ok", "value", "diagnostics"} report
decl evaluate cfg.decl --input deployed=doc.json --output deployed=out.json # bind a document, write its completed value
decl evaluate cfg.decl --input deployed=doc.yaml --format yaml --pretty # a document in YAML in, the outputs as YAML out
decl evaluate site.decl --output gateway # a root in the form its @render declares: YAML, a template's text, one file per element
decl evaluate site.decl --output units=out --template units=unit.j2 # …or with the template and the destination given here
decl validate cfg.decl --input deployed=doc.json # bind a document to an input root (diagnostics only)
decl validate tests/validation # judge a fixture corpus
decl fmt src/*.decl # canonical formatting in place (--check: exit 1 if not canonical)
decl repl site.decl # an interactive session: expressions, bindings, edits, undo
decl-lsp # language server over stdioDiagnostics go to stderr as file: severity [code] id at path: message,
or into the JSON report with --json. The exit code is 1 when any error
was reported. An output declares the form it is emitted in with
@render({ format, indent, template, file, each }) — canonical or
indented JSON, YAML, or the text of a template in a small Jinja-like
dialect with Decl expressions inside, one file per element — and
--format, --indent, --template, --output override it
(docs/tooling/05_render.md in the repository).
§Library
use decl_lang::{check, evaluate, format_source, render, to_yaml, validate, DeclError, Document, EvaluateOptions, RenderOptions, Rendered, TemplateSource};
fn example() -> Result<(), DeclError> {
// the exported outputs, by name in declaration order, as canonical JSON text
let docs = evaluate("site.decl", &EvaluateOptions::default())?;
let site = &evaluate("site.decl", &EvaluateOptions { outputs: vec!["site".into()], ..Default::default() })?["site"];
// a document bound to an input root, and that root returned completed (a .yaml file is read as YAML)
let done = evaluate("cfg.decl", &EvaluateOptions {
inputs: vec![("deployed".into(), Document::File("doc.yaml".into()))], // or Document::Json(text)
outputs: vec!["deployed".into()],
})?;
// each root in the form its @render declares: a text, or a fan-out root's files by path
let texts = render("site.decl", &RenderOptions::default())?;
if let Rendered::Text(yaml) = &texts["site"] { println!("{yaml}"); }
let conf = render("site.decl", &RenderOptions {
outputs: vec!["site".into()],
templates: vec![("site".into(), TemplateSource::File("nginx.conf.j2".into()))], // or TemplateSource::Text(text)
..Default::default()
})?;
let problems = check(&["schema.decl"]); // empty when clean
let report = validate("cfg.decl", &[("deployed".into(), Document::Json("{\"host\":\"h\"}".into()))])?;
let text = format_source("const x=1+2\n")?; // "const x = 1 + 2\n"
let y = to_yaml("{\"a\":[1,2]}", 2)?; // "a:\n - 1\n - 2" — the layouts, as pure functions over JSON text
assert_eq!(text, "const x = 1 + 2\n");
Ok(())
}The functions are the decl command line in its own vocabulary:
inputs binds documents by input name (a JSON or YAML file, or JSON
text), outputs names the roots to return — outputs, or inputs bound
here or demanded through their fallback — and defaults to the entry
module’s exported outputs; render returns each root’s text in its
declared form (Rendered::Text, or Rendered::Files by path for a
fan-out root) with RenderOptions as the overrides, to_json and
to_yaml lay a document’s text out; a failure is a DeclError whose
diagnostics carry the report. The npm package (evaluate, …) and the PyPI package
(decl.evaluate, …) offer the same functions with the same semantics;
the modules the functions are built from are public as well.
The high-level functions above and the CLI formats are the crate’s contract.
The representation inside those modules is chosen for performance and changes
between releases without a migration path: the Engine’s query graph is private
behind inspection methods, and slots, containers, paths and values share
storage behind copy-on-write accessors. Their contracts are in the API
documentation;
Rust runtime representation
says what code that uses them directly can rely on, and
Runtime diagnostics describes the
optional runtime-diagnostics Cargo feature.
§Library layout
The crate is the same modules as the reference implementation, one
language rule in the same-named file everywhere (AGENTS.md in the
repository), and each is public:
| Module | Holds |
|---|---|
api | the high-level API above: evaluate, render, check, validate, evaluate_source, format_source, to_json, to_yaml, DeclError, Diagnostic, Document, EvaluateOptions, RenderOptions, Rendered, TemplateSource, Report |
ast | the syntax tree (specification chapter 11): declarations, types, members, expressions, source ranges |
parse | the tree-sitter binding: parse_source, source text to ast |
semantics | values, the environment (Env), resolved types (RT), diagnostics (Diag), canonical paths, the JSON reader and writers |
yaml | documents in YAML: the YAML 1.2 core-schema reader into the JSON model, the block-style writer, the JSON layouts |
render | the renderer: @render’s form, the template dialect, the fan-out — one root to its text or files |
subsume | the subsumption judgment ⊑ (§3.17) and structural emptiness (§3.19) |
infer | expression inference and the static assignability of §4 |
checker | the static checks of a module (check_module) |
engine | binding, lazy evaluation, validation, serialization (Engine) |
pipeline | one module end to end (run_pipeline, evaluate_source) |
module | modules and the universe (load_modules, run_universe) |
package | manifests, the resolver, the lock file (§8.6–8.7) |
fmt | the canonical formatter (format) |
conformance | the fixture corpus judge (judge_corpus) |
session | the evaluation session behind the REPL and the server (Session) |
repl | decl repl |
lsp | decl-lsp |
cli | decl |
§Scope
The crate covers the whole language: parsing, the static checks of
chapters 3–4 (type resolution with generics and dimension algebra,
inference, assignability, the absence discipline, match
exhaustiveness), binding with lazy slots and cycle detection,
$referrers, assertions with diagnostic templates, canonical
serialization, modules and packages (decl.toml, decl.lock), the
canonical formatter, and the language server. Its output is
byte-identical to the reference implementation — the repository’s
parity harness (tests/parity/differential.py, run by make verify)
diffs the Rust and Python runtimes against the reference over every
example and fixture that produces output.
§Building from source
The grammar’s C sources are compiled by build.rs. Inside the
repository they come from ../tree-sitter-decl/src; the published crate
carries a copy under grammar/ (generated by npm run build in
decl-ts/).
cargo build --release # from the repository root (Cargo workspace)
./target/release/decl evaluate docs/examples/02_config.decl --output prod§License
MIT — see LICENSE.
Re-exports§
pub use api::check;pub use api::evaluate;pub use api::evaluate_source;pub use api::format_source;pub use api::render;pub use api::to_json;pub use api::to_yaml;pub use api::validate;pub use api::DeclError;pub use api::Diagnostic;pub use api::Document;pub use api::EvaluateOptions;pub use api::RenderOptions;pub use api::Rendered;pub use api::Report;pub use api::TemplateSource;
Modules§
- allocation_
diagnostics - Rust requested-allocation counters for separate diagnostic helpers.
Counts requests to MiMalloc, not its capacity, C allocations or RSS.
This module is compiled only with
runtime-diagnostics; feature-empty native builds do not include these counters. - api
- The high-level API of the crate: the operations the
declcommand line offers, in the same vocabulary —evaluatebinds inputs and returns outputs,check,validate,evaluate_source,format_source— for programs that would otherwise assemble parser, checker, and engine by hand (those modules are public too). The npm package and the Python package offer the same functions with the same semantics. - ast
- AST of the runtime — the shape the tree-sitter CST lowers into (parse.rs), mirroring the reference implementation’s ast.ts.
- checker
- Static checks over the AST + resolved types — a port of the reference implementation’s checker.ts (chapters 3–4). Implemented: E3001 duplicate module name E3003 unknown type name E4010 mixed range endpoints E4011 empty range / array size E4012 structurally empty intersection E4013 non-discriminable record union arms E4014 more than one non-record object arm in a union E4015 map key not string-shaped E4030 inheritance widening E4032 illegal member-kind transition E4052 ?? mixed with &&/|| unparenthesized E4094 context variable without / with an invalid context declaration plus the expression pass of infer.rs (inference, assignability, absence).
- cli
decl check/decl evaluate/decl validate/decl fmt(cli.ts). Output is byte-identical to the reference implementation’s CLI so the three implementations can be diffed (tests/parity/differential.py).- conformance
- Conformance judging — a port of the reference implementation’s conformance.ts: judges fixtures by their declared phase. valid/* -> parse + checks clean + outputs evaluate clean invalid @expect-phase: parsing -> must fail to parse invalid @expect-phase: checking -> parses; static checks report @expect-error invalid @expect-phase: binding -> parses; the pipeline reports @expect-error
- engine
- Binding, evaluation, validation, and serialization — a port of the reference implementation’s engine.ts. Semantics are the spec’s: lazy slots with cycle detection, taint / root-cause diagnostics, $referrers universe ordering, canonical JSON output.
- evaluation_
diagnostics - Scalar-only, separately compiled evaluation phase diagnostics.
- expression_
diagnostics - Bounded, source-selected comprehension observations for diagnostic builds. Records contain scalars only. Inclusive nested intervals are not additive; returned lazy heads can be forced after the recorded expression has ended.
- fmt
- Canonical formatter — a port of the reference implementation’s fmt.ts (ROADMAP Phase 4; §2.1/D1): LF, 4-space indentation, no tabs, normalized intra-line spacing. The original line structure is preserved — §2.9 makes newlines separators, so where a construct breaks lines is the author’s statement — and the formatter re-derives indentation and token spacing deterministically, which makes it idempotent by construction.
- infer
- Expression-level static analysis — a port of the reference
implementation’s infer.ts: type inference, assignability (§3.18,
strict S ⊑ T), the absence discipline (§4.10) with its two narrowing
rules, and the
matchstatic checks (§4.7). Inference is conservative: a form whose type cannot be determined yieldsunknown(rt None) and suppresses downstream judgments rather than guessing. - lsp
- decl-lsp (docs/tooling/03_lsp.md): the language server over stdio — a port of the reference implementation’s lsp.ts. Every answer comes from the same checker, inference, and engine as the command line, driven through the session object (session.rs) with the open buffers overriding the disk; positions come from the source ranges every AST node carries, and the types and resolutions recorded while the checker runs (infer.rs hooks). Messages are handled strictly in order, and the server exits when its input closes.
- module
- Module loading, linking, and universe evaluation (module.ts, §8.1–8.5, §8.8): files are modules, the import graph is acyclic, exports are explicit; packages (§8.6–8.7) plug in through the resolver hook.
- package
- Packages, decl.toml, and decl.lock (§8.6–8.7) — a port of the
reference implementation’s package.ts: exact-pinned dependencies,
fail-closed manifests, content-hashed reproducibility. Conventions:
dependency packages live under
<root>/decl_modules/<name>/in a flat layout, and the lock file is line-basedname version sha256in name order. - parse
- CST -> AST lowering over the compiled tree-sitter grammar (parse.ts).
- phase_
events - Bounded, opt-in phase breadcrumbs which survive an interrupted evaluation.
- pipeline
- The single-module pipeline — a port of the reference implementation’s pipeline.ts: bind and evaluate every output of one module’s declarations (the judgment the conformance runner applies), and the source-level report that front-ends and embedders consume.
- qengine
- The query engine (qengine/DESIGN.md): a from-scratch incremental, memoized
evaluator, a faithful port of decl-ts/src/qengine.
dbis the generic incremental core;qevaldrives the shared programs and retained slot graph. - render
- The renderer (docs/tooling/05_render.md): the form a module declares
for an output with
@render— a format and a layout, a template, a destination, a fan-out — read from the annotation (§3), the structured text of a document in that form (§4), and the templates (§5) and the fan-out (§6) that turn one evaluated root into text or files. The command line, the REPL, the library, and the editor preview all emit through here, so that the three implementations print the same bytes. A port of the reference’s render.ts. - repl
- The REPL (docs/tooling/02_repl.md) — a port of the reference
implementation’s repl.ts: an interactive session over a universe —
expressions evaluated partially, session outputs and declarations,
documents bound and edited with exact undo, and the command-line verbs
root for root. Everything it prints goes to standard output; a scripted
session (
--script) prints the transcript the terminal would show, so the three implementations can be diffed. - retention_
diagnostics - External runtime-diagnostics only: fixed scalar traffic counters, no owner graph.
- root_
binding_ diagnostics - Feature-only root-binding boundaries, stored separately from evaluation spans.
- semantics
- Value model, environment, and type resolution — a port of the reference implementation’s semantics.ts.
- serialization_
diagnostics - Feature-only census of the value graph that canonical serialization emits.
- session
- The session object (docs/tooling/02_repl.md §1) — a port of the
reference implementation’s session.ts: a universe — the modules loaded
from an entry file, their texts taken as a snapshot — plus an operation
log (bindings, document edits, session declarations, reloads). The
state is the universe with the log applied, recomputed deterministically
from the snapshot, which is what makes
:undoexact and a scripted session reproducible. The REPL (repl.rs) drives it; nothing here prints, and every answer is the same checker, inference, and engine the command line runs. - subsume
- The subsumption judgment ⊑ (§3.17) — the runtime needs it for
matcharm selection over bound records and generic value-argument checks. - yaml
- YAML for documents (docs/tooling/05_render.md §2, §4): a reader of
YAML 1.2 with the core schema into the JSON data model — the values
read_jsonproduces, so that a document written in YAML is indistinguishable from the same document written in JSON from the reader on — and a writer of the block-style form that every YAML 1.2 reader (and no YAML 1.1 reader) reads back as the canonical JSON document. Beside them, the JSON layouts of §4.1. The reader accepts exactly what the document says and refuses the rest with the reason and the line, so that the three implementations refuse the same texts with the same words. A port of the reference’s yaml.ts.