dsl-kit-parse 0.12.0

Parser trunk for dsl-kit DSLs (ParseTree, schema conformance, serde bridge, DslBuild consumer).
Documentation
# dsl-kit

An engine kit for building small, AI-native DSLs in Rust.

Write your AST as a Rust enum and derive the rest: from a few derives,
the kit supplies a schema, a text parser, a JSON front-end, a typed
builder, lints, a debugger-grade interpreter that executes the enum
directly, and an MCP surface an AI can drive. The Rust type is the
single source of truth — everything user-facing (grammar, examples,
diagnostics, tool schemas, execution) is generated from it, so none of
it can drift.

```rust
use dsl_kit::{IdGen, NodeId};
use dsl_kit_macros::{DslBuild, DslExec, DslNode, DslSchema};

#[derive(Debug, DslNode, DslSchema, DslBuild, DslExec)]
enum Expr {
    #[dsl_exec(value)]
    Lit { id: NodeId, value: i64 },
    #[dsl_exec(apply = "add")]
    Add { id: NodeId, lhs: Box<Expr>, rhs: Box<Expr> },
    #[dsl_exec(branch)]
    If { id: NodeId, cond: Box<Expr>, then_branch: Box<Expr>, else_branch: Box<Expr> },
}
```

That single declaration already gives you:

```rust
use dsl_kit_parse::{DslBuild as _, schema_gen};
use dsl_kit_schema::DslSchema as _;

// A grammar for a canonical text syntax, generated from the schema —
// left-recursion-free by construction and verified by static checks.
let grammar = schema_gen::checked_grammar_from_schema(&Expr::schema(), &IdGen::new())?;

// Parse canonical text, then build the typed AST back out of it.
let tree = grammar.parse("Add(lhs: Lit(value: 40), rhs: Lit(value: 2))")?;
let expr = Expr::from_parse_tree(&tree, &IdGen::new())?;

// Machine-derived examples that parse by construction — few-shot
// material for an AI writing your DSL.
let examples = dsl_kit_parse::example_gen::examples_from_grammar(&grammar)?;
```

A JSON front-end (`{"type": "Add", "lhs": ...}`) targets the same
`ParseTree`, so both surfaces share one conformance check and one typed
builder. Payload types the canonical syntax cannot spell get per-field
hooks on both sides: `schema_gen::SyntaxOverrides` for the grammar,
`#[dsl_build(with = ...)]` for the builder.

## The engine

`dsl-kit-core` interprets effect-oriented, value-bearing programs —
`Seq` / `Par` / `Call` / `Scope` / `Maybe` for orchestration, `Apply` /
`Branch` / `Bind` / `Read` / `Loop` / `Lit` for computation — with the
runtime mechanics a real host needs:

- **Structured fan-out**: `Par` with join policies (`All` / `Any` /
  `FirstK`, fail-fast or collect-all) folded by pluggable reducers.
- **Suspend / resume**: every `Call` yields a suspension the host
  resolves with `Ok(value)` or `Err(effect_error)`; cancellation is
  cooperative and observable.
- **Debugger-grade breakpoints**: every spawn passes through one
  schedule, so a breakpoint halts *before* the matched frame spawns —
  at any depth, including mid-`Par`-cascade — and the frame tree
  faithfully exposes the partially spawned state.
- **Sans-io drive layer**: `drive` (sync) and `drive_async` (any
  executor; the core has zero runtime dependencies) run the
  resolve loop for you when you don't want to hand-roll it.
- **Value semantics, interpreted**: `Apply` folds evaluated children
  through a registered op, `Branch` selects on a value (the untaken
  side never spawns), `Bind` / `Read` carry a lexical env chain,
  `Loop` respawns its body per iteration — all inside the same frame
  machinery, so breakpoints halt on branch selection and on every
  loop iteration, and an unbound `Read` suspends like any other
  effect. You register what `"add"` *means*; the engine does the
  rest. No hand-written eval loop — `expr-example` runs entirely on
  the engine.

## MCP: let an AI debug your DSL

`dsl-kit-mcp` wraps any `DslHost` in a stdio MCP server with a
debugger-style tool surface: `load`, `ast`, `step` (one / to-yield /
to-done), `breakpoint add/list/remove`, `state`, `pending`, `resolve`,
`schema`, `lint`, `explain`. The `custom-mcp-example` shows how to ship
your own DSL as its own MCP server binary.

## Conformance vs lint

Two layers inspect a document, and only one of them can stop it.

**Conformance is the compiler.** The `from_parse_tree` that
`#[derive(DslBuild)]` generates runs `check_conformance` before it
builds anything, so a non-conforming document never becomes an AST: an
unknown variant, a missing or duplicated field, a slot that breaks its
declared multiplicity, an empty slot declared
`#[dsl_schema(non_empty)]` — every one of them is a hard error.
Neither the document nor the host can suppress them, and both
front-ends (canonical text and JSON) go through the same check.

**Lint is advisory and opt-in.** `Linter` sits outside parsing and
loading: it runs only where a host wires it up explicitly
(`DslHost::lint_json`, surfaced over MCP as the `dsl_kit_lint` tool).
A document with lint findings still loads and still runs — findings
are material for an author or an agent to act on, not a gate. A DSL
that never wires a linter simply reports itself as unwired.

There is no ignore-file layer. The most local lever belongs to the
document: a node names the rules it accepts at that spot — `"$allow":
["max-fan-out"]` in JSON, `@allow("max-fan-out") <node>` in canonical
text once the host has opted the grammar in — and the annotation
covers that node and its subtree, so `["*"]` on the root quiets the
whole document. Correctness and contract findings stand regardless:
the first says the program is wrong, the second that it breaks a
ceiling its caller imposed, and neither is the document's to waive.
The remaining levers — declare the constraint in the schema, compose
the rule set, filter the output — are documented on the `dsl-kit-lint`
crate.

## Crates

| crate | role |
|---|---|
| `dsl-kit` | facade — re-exports the kit surface |
| `dsl-kit-core` | engine: frames, fan-out, cancellation, events, breakpoints, drive |
| `dsl-kit-macros` | `#[derive(DslNode)]` / `#[derive(DslSchema)]` / `#[derive(DslBuild)]` / `#[derive(DslExec)]` |
| `dsl-kit-schema` | type-level schema consumed by parsers, editors, AI clients; JSON Schema export |
| `dsl-kit-parse` | `ParseTree`, conformance, JSON bridge, PEG interpreter, grammar generation, example synthesis |
| `dsl-kit-lint` | walk-driven, schema-aware, author-extensible lints |
| `dsl-kit-mcp` | stdio MCP framework over any `DslHost` |

## Examples

```sh
cargo run -p expr-example   # expression DSL: text + JSON round trips, schema-generated grammar
cargo run -p flow-example   # orchestration DSL: fan-out, value-gated Branch, breakpoints, drive layer, text round trip
cargo run -p cfg-example    # configuration DSL: keyed child slots (BTreeMap), override folds, host-resolved references
cargo run -p query-example  # IR + parser only: a Web API query language, OpenAPI doc, SQL lowering — no engine
```

The examples double as reference implementations: `flow-dsl` shows the
per-field hooks on a DSL with exotic payload types, `expr-dsl` shows
the plain derive-only path end to end, and `cfg-dsl` shows keyed child
slots — named children rather than positional ones — through both
front-ends and over MCP (see
[examples/cfg-example](examples/cfg-example/README.md)).

## IR + parser only

The engine is optional. A DSL that is really an *interface* — a query
language for a Web API, a configuration format, a request schema — can
stop at the typed AST: derive `DslNode + DslSchema + DslBuild +
DslDump`, and the kit still supplies both front-ends, conformance, the
canonical dump, machine-derived examples, and the schema in the
standard dialect:

```rust
use dsl_kit_schema::json_schema::{RefStyle, TypeMap};

// JSON Schema 2020-12 of the JSON front-end's document shape — one
// `oneOf` arm per variant, `type` pinned, recursion through `$ref`.
// It is rendered from the same derived schema the parser enforces,
// so a published OpenAPI contract cannot drift from the enum.
let component = Query::schema().to_json_schema(&TypeMap::new(), RefStyle::OpenApiComponent)?;
```

Whatever consumes the typed AST afterwards is yours — `query-example`
lowers it to a parameterized SQL `WHERE` clause and serves the schema
as an OpenAPI request body (see
[examples/query-example](examples/query-example/README.md)).

## Documentation

API documentation is the source of truth and is written to be read:

```sh
cargo doc --open
```

## Status

The kit is young and the API is still moving. The engine semantics
(fan-out, cancellation, halt-before-spawn breakpoints) and the derive
contracts are test-pinned; surface ergonomics may change between minor
versions. See [CHANGELOG.md](CHANGELOG.md) for the release history.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE]LICENSE-APACHE)
- MIT license ([LICENSE-MIT]LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the
Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.