Skip to main content

dsl_kit_parse/
schema_gen.rs

1//! Schema-driven grammar generation (item N).
2//!
3//! The kit's identity axis is "write the AST in Rust, the toolchain
4//! supplies the rest". [`grammar_from_schema`] converts the type-level
5//! shape a `#[derive(DslSchema)]` already extracts into a working
6//! [`Grammar`] for a canonical text syntax — the DSL author writes two
7//! derives and gets an external-format parser for free, instead of
8//! hand-authoring a grammar (in Rust or, worse, in a Bison-style JSON
9//! blob nobody wants to write).
10//!
11//! # Canonical syntax
12//!
13//! One form per variant: the variant name as a keyword, followed by a
14//! parenthesised, comma-separated argument list. Arguments appear in
15//! schema order — payload fields first, then child slots — each spelled
16//! `name: value`:
17//!
18//! ```text
19//! Add(lhs: Lit(value: 1), rhs: Neg(body: none))
20//! List(items: [Lit(value: 1), Lit(value: 2)])
21//! Name(text: "hello world")
22//! Unit()
23//! ```
24//!
25//! - **`One` child** — `name: <node>`.
26//! - **`Optional` child** — `name: <node>` or `name: none`. (If a
27//!   variant is literally called `none`, PEG ordered choice still
28//!   parses `name: none(...)` as that variant; bare `none` means
29//!   absent.)
30//! - **`Many` child** — `name: [<node>, <node>, ...]`, empty list
31//!   allowed.
32//! - **`Map` child** — `name: { <key>: <node>, <key>: <node> }`, empty
33//!   map allowed. Braces (not the `Many` brackets) mark the slot as
34//!   keyed, matching the JSON bridge's object spelling. A key is
35//!   either a `%str` literal or a bare `%ident`, so `"a b": …` and
36//!   `path: …` are both writable. Entries may be written in any
37//!   order — the parser sorts them into the canonical
38//!   ascending-by-key form the `ParseTree` requires.
39//! - **Payload fields** — by Rust type source text:
40//!   `String` → a `%str` literal; the integer types → `%int`;
41//!   `bool` → `true` / `false`. Any other payload type fails
42//!   generation with [`codes::UNSUPPORTED_FIELD`] — loudly, per
43//!   variant, rather than silently dropping the variant from the
44//!   grammar — unless a [`SyntaxOverrides`] entry supplies its value
45//!   production.
46//! - **Optional payload fields** (`Option<T>` / `Vec<T>`, i.e.
47//!   [`FieldSchema::optional`](dsl_kit_schema::FieldSchema::optional))
48//!   — may be omitted, at their schema position: `Row(name: "x")` and
49//!   `Row(name: "x", tags: ["a"])` both parse for
50//!   `Row { name: String, tags: Vec<String> }`. Required arguments are
51//!   enforced by the grammar itself, so `Row()` is a parse error, not
52//!   a later conformance failure — which keeps
53//!   [`example_gen`](crate::example_gen)'s synthesized examples
54//!   conformant by construction. A variant whose arguments are *all*
55//!   optional accepts them in any order.
56//!
57//! # Syntax overrides
58//!
59//! [`grammar_from_schema_with`] accepts a [`SyntaxOverrides`] carrying
60//! value productions for payload types the built-in mapping rejects
61//! (e.g. `Option<JoinPolicy>`), keyed by type source text or pinned to
62//! one `(variant, field)` site. The override supplies only the value
63//! [`Peg`] — the surrounding `name: value` argument shape stays
64//! canonical — and its matched text becomes the field's production, so
65//! the override author owns making that text consumable downstream
66//! (typically `FromStr` on the field type, via
67//! [`build_field`](crate::build_field)).
68//!
69//! # Guarantees
70//!
71//! The generated grammar is left-recursion-free by construction (every
72//! variant rule starts with its keyword token) and contains no nullable
73//! repeats; `GrammarCheck`'s `check_left_recursion` /
74//! `check_nullable_repeat` / `check_schema_consistency` all pass
75//! against it — the tests pin this. Trees produced by parsing satisfy
76//! [`check_conformance`](crate::check_conformance) against the source
77//! schema.
78
79use std::collections::HashMap;
80
81use crate::grammar_check;
82use crate::peg::{
83    Grammar, Peg, choice, field, keyed_entry, node, repeat, rule, rule_ref, seq, token,
84};
85use crate::{BuildError, Diagnostic};
86use dsl_kit_core::IdGen;
87use dsl_kit_schema::{
88    ChildSchema, ChildValueShape, FieldSchema, Multiplicity, NodeSchema, ScalarKind,
89    ScalarShorthand, VariantSchema,
90};
91
92/// Diagnostic codes emitted by grammar generation.
93pub mod codes {
94    /// A payload field's Rust type has no canonical-syntax mapping.
95    pub const UNSUPPORTED_FIELD: &str = "dsl_kit::schema_gen::unsupported_field";
96    /// The schema declares no variants — there is nothing to parse.
97    pub const EMPTY_SCHEMA: &str = "dsl_kit::schema_gen::empty_schema";
98    /// A child slot's multiplicity is a variant this build of
99    /// `dsl-kit-parse` does not recognise (added to the schema crate's
100    /// `#[non_exhaustive]` enum ahead of parse-side support). Emitted
101    /// by the pre-flight check in
102    /// [`grammar_from_schema_with`] so `child_arg_peg` never sees an
103    /// unknown variant.
104    pub const UNKNOWN_MULTIPLICITY: &str = "dsl_kit::schema_gen::unknown_multiplicity";
105    /// A keyed child slot declares a value shape the canonical text
106    /// syntax has not yet grown a production for. Emitted by the
107    /// pre-flight check so a scalar-valued keyed slot fails loudly
108    /// at grammar-generation time rather than silently producing a
109    /// grammar that expects each entry's value to be a full AST
110    /// node — the shape mismatch would otherwise surface as an
111    /// opaque parse failure on the DSL author's first document.
112    pub const UNSUPPORTED_MAP_VALUE_SHAPE: &str =
113        "dsl_kit::schema_gen::unsupported_map_value_shape";
114    /// A child slot declares a [`ScalarShorthand`](dsl_kit_schema::ScalarShorthand)
115    /// this build cannot honour: wrong multiplicity / value shape for
116    /// a shorthand, a duplicate kind, an unknown target variant or
117    /// field, a target field whose type does not match the declared
118    /// kind, or a kind this build does not recognise. Emitted by the
119    /// pre-flight check so an incoherent declaration fails loudly at
120    /// grammar-generation time — the same declaration drives the JSON
121    /// bridge, so silently dropping it here would let the two
122    /// front-ends drift apart.
123    pub const UNSUPPORTED_SCALAR_SHORTHAND: &str =
124        "dsl_kit::schema_gen::unsupported_scalar_shorthand";
125    /// A child slot declares
126    /// [`non_empty`](dsl_kit_schema::ChildSchema::non_empty) on a
127    /// multiplicity that has no empty collection to forbid (`One` /
128    /// `Optional`). Emitted by the pre-flight check so an incoherent
129    /// hand-written declaration fails loudly at grammar-generation
130    /// time — the derive macro rejects the same combination at
131    /// compile time.
132    pub const INVALID_NON_EMPTY: &str = "dsl_kit::schema_gen::invalid_non_empty";
133}
134
135/// Integer payload types with a built-in `%int` production. Shared by
136/// the payload-field mapping ([`field_value_peg`]) and the scalar
137/// shorthand kind check so the two stay in step.
138const INT_TYPES: &[&str] = &[
139    "i8", "i16", "i32", "i64", "i128", "u8", "u16", "u32", "u64", "u128", "usize", "isize",
140];
141
142/// Name of the generated start rule.
143pub const START_RULE: &str = "node";
144
145/// A deferred value-production constructor: overrides are registered
146/// before the [`IdGen`] doing the generation exists, so each entry is a
147/// factory invoked with the generator's `ids` at build time.
148type PegFactory = Box<dyn Fn(&IdGen) -> Peg>;
149
150/// Value-production overrides for payload fields whose Rust type has no
151/// built-in canonical-syntax mapping (see the module docs).
152///
153/// Two granularities, resolved most-specific-first:
154///
155/// 1. **Per field** ([`Self::for_field`]) — pinned to one
156///    `(variant, field)` site.
157/// 2. **Per type** ([`Self::for_type`]) — keyed by the field's Rust
158///    type source text; whitespace is ignored, so
159///    `"Option<JoinPolicy>"` matches the derive-extracted
160///    `"Option < JoinPolicy >"` spelling.
161///
162/// A field with neither entry falls back to the built-in mapping, and
163/// failing that still fails generation loudly with
164/// [`codes::UNSUPPORTED_FIELD`].
165///
166/// The factory builds only the **value** production; the enclosing
167/// `name ':' <value>` argument shape (and the `Field` sink binding the
168/// matched text to the field name) stays canonical, which keeps the
169/// generated grammar's `GrammarCheck` guarantees intact.
170#[derive(Default)]
171pub struct SyntaxOverrides {
172    by_type: HashMap<String, PegFactory>,
173    by_field: HashMap<(String, String), PegFactory>,
174}
175
176impl SyntaxOverrides {
177    /// An empty override set (equivalent to the built-in mapping only).
178    pub fn new() -> Self {
179        Self::default()
180    }
181
182    /// Registers a value production for every payload field of Rust
183    /// type `ty` (source-text comparison, whitespace-insensitive).
184    pub fn for_type(
185        mut self,
186        ty: impl AsRef<str>,
187        value: impl Fn(&IdGen) -> Peg + 'static,
188    ) -> Self {
189        self.by_type.insert(strip_ws(ty.as_ref()), Box::new(value));
190        self
191    }
192
193    /// Registers a value production for the single field `field` of
194    /// variant `variant`, winning over any [`Self::for_type`] entry.
195    pub fn for_field(
196        mut self,
197        variant: impl Into<String>,
198        field: impl Into<String>,
199        value: impl Fn(&IdGen) -> Peg + 'static,
200    ) -> Self {
201        self.by_field
202            .insert((variant.into(), field.into()), Box::new(value));
203        self
204    }
205
206    /// Most-specific matching factory for `field` of `variant`, if any.
207    fn resolve(&self, variant: &str, field: &FieldSchema) -> Option<&PegFactory> {
208        self.by_field
209            .get(&(variant.to_string(), field.name.clone()))
210            .or_else(|| self.by_type.get(&strip_ws(&field.ty)))
211    }
212}
213
214/// Whitespace-insensitive type key: `Option < JoinPolicy >` (the
215/// token-stream spelling `#[derive(DslSchema)]` extracts) and
216/// `Option<JoinPolicy>` (what an author writes) must compare equal.
217fn strip_ws(ty: &str) -> String {
218    ty.chars().filter(|c| !c.is_whitespace()).collect()
219}
220
221impl Grammar {
222    /// Generates the canonical-syntax grammar for `schema`. See
223    /// [`grammar_from_schema`].
224    pub fn from_schema(schema: &NodeSchema, ids: &IdGen) -> Result<Grammar, BuildError> {
225        grammar_from_schema(schema, ids)
226    }
227}
228
229/// Generates a [`Grammar`] for the canonical named-argument syntax of
230/// `schema` (see the module docs for the syntax), built-in field
231/// mapping only.
232///
233/// Fails with one [`codes::UNSUPPORTED_FIELD`] diagnostic per
234/// unmappable payload field (collected across all variants, so the
235/// author sees the full list at once). To map such fields instead of
236/// failing, use [`grammar_from_schema_with`].
237pub fn grammar_from_schema(schema: &NodeSchema, ids: &IdGen) -> Result<Grammar, BuildError> {
238    grammar_from_schema_with(schema, ids, &SyntaxOverrides::default())
239}
240
241/// [`grammar_from_schema`] with [`SyntaxOverrides`] consulted before
242/// the built-in field mapping (per-field entries win over per-type
243/// entries win over built-ins).
244pub fn grammar_from_schema_with(
245    schema: &NodeSchema,
246    ids: &IdGen,
247    overrides: &SyntaxOverrides,
248) -> Result<Grammar, BuildError> {
249    if schema.variants.is_empty() {
250        return Err(BuildError::single(Diagnostic::error(
251            codes::EMPTY_SCHEMA,
252            format!("schema `{}` declares no variants", schema.name),
253        )));
254    }
255
256    // Pre-flight: collect every diagnostic that must block rule
257    // generation, then return in one shot. A single pass means an
258    // author with both a bad payload type and a `Multiplicity::Map`
259    // slot sees both errors on the first build instead of paying two
260    // edit-compile cycles for one report.
261    //
262    // Grouping:
263    //   - `UNSUPPORTED_FIELD` for payload types with no canonical-syntax
264    //     mapping (and no `SyntaxOverrides` entry).
265    //   - `UNKNOWN_MULTIPLICITY` for child slots whose multiplicity
266    //     this build does not know, which is what keeps
267    //     `child_arg_peg`'s catch-all arm from ever running.
268    let mut pre_flight = Vec::new();
269    for v in &schema.variants {
270        for f in &v.fields {
271            if resolved_field_value_peg(&v.name, f, ids, overrides).is_none() {
272                pre_flight.push(Diagnostic::error(
273                    codes::UNSUPPORTED_FIELD,
274                    format!(
275                        "variant `{}` field `{}`: type `{}` has no canonical-syntax \
276                         mapping (supported: String, bool, the integer types; or \
277                         register a `SyntaxOverrides` value production)",
278                        v.name, f.name, f.ty
279                    ),
280                ));
281            }
282        }
283        for c in &v.children {
284            match c.multiplicity {
285                // Every shape `child_arg_peg` knows how to emit.
286                Multiplicity::One | Multiplicity::Optional | Multiplicity::Many => {}
287                // Keyed slots come in two value shapes at derive
288                // level: recursive (`BTreeMap<String, Self>` /
289                // `BTreeMap<String, Box<Self>>`) and scalar
290                // (`ChildValueShape::Scalar { .. }`, Shape 1 of the
291                // tracking issue). Both are supported by the
292                // canonical text syntax as of dsl-kit 0.7; scalar
293                // values reuse the built-in payload-type mapping
294                // (`field_value_peg`) — same names, same productions
295                // — so any type the payload path can spell
296                // (`String` / integer / `bool` / …) works in a keyed
297                // slot too. A scalar value with no built-in mapping
298                // is still an error here: `child_arg_peg`'s
299                // downstream `.expect(...)` would panic otherwise,
300                // and the DSL author needs a pointer to
301                // `SyntaxOverrides` or a real bug report either way.
302                Multiplicity::Map => {
303                    if let ChildValueShape::Scalar { ty } = &c.value_shape {
304                        let synthetic = FieldSchema {
305                            name: "value".into(),
306                            ty: ty.clone(),
307                            optional: false,
308                        };
309                        if field_value_peg(&synthetic, ids).is_none() {
310                            pre_flight.push(Diagnostic::error(
311                                codes::UNSUPPORTED_MAP_VALUE_SHAPE,
312                                format!(
313                                    "variant `{}` child slot `{}`: keyed scalar value type \
314                                     `{}` has no canonical-syntax mapping (supported: \
315                                     String, bool, the integer types, Option<String>, \
316                                     Vec<String>). Register a `SyntaxOverrides` value \
317                                     production for the surrounding payload field of the \
318                                     same type, or use the JSON front-end where scalar \
319                                     entries are dispatched through serde",
320                                    v.name, c.name, ty
321                                ),
322                            ));
323                        }
324                    }
325                }
326                // `#[non_exhaustive]` catch-all: a future Multiplicity
327                // variant added to dsl-kit-schema before this crate is
328                // updated must also be rejected here — that's what
329                // keeps `child_arg_peg`'s `_ => unreachable!()` arm
330                // honest.
331                _ => {
332                    pre_flight.push(Diagnostic::error(
333                        codes::UNKNOWN_MULTIPLICITY,
334                        format!(
335                            "variant `{}` child slot `{}`: unrecognised Multiplicity \
336                             variant (upgrade dsl-kit-parse to a version that knows about it)",
337                            v.name, c.name
338                        ),
339                    ));
340                }
341            }
342            pre_flight.extend(check_scalar_shorthands(schema, v, c));
343            if c.non_empty && matches!(c.multiplicity, Multiplicity::One | Multiplicity::Optional) {
344                pre_flight.push(Diagnostic::error(
345                    codes::INVALID_NON_EMPTY,
346                    format!(
347                        "variant `{}` child slot `{}`: `non_empty` is only meaningful \
348                         on `Many` / `Map` collection slots (`One` is inherently \
349                         non-empty, `Optional` inherently permits absence)",
350                        v.name, c.name
351                    ),
352                ));
353            }
354        }
355    }
356    if !pre_flight.is_empty() {
357        return Err(BuildError::new(pre_flight));
358    }
359
360    let mut rules = Vec::with_capacity(schema.variants.len() + 1);
361    rules.push(rule(
362        ids,
363        START_RULE,
364        choice(
365            ids,
366            schema
367                .variants
368                .iter()
369                .map(|v| rule_ref(ids, v.name.clone()))
370                .collect(),
371        ),
372    ));
373    for v in &schema.variants {
374        rules.push(variant_rule(v, ids, overrides));
375    }
376    Ok(Grammar::new(rules, START_RULE))
377}
378
379/// Pre-flight validation of one slot's declared scalar shorthands.
380///
381/// The declaration is the single source both front-ends lower from, so
382/// every way it can be incoherent is rejected here in one pass:
383/// shorthands on a slot shape that has no bare-scalar position
384/// (non-`One`/`Optional` multiplicity, or a non-recursive value),
385/// duplicate kinds (kind dispatch must be unambiguous), an unknown
386/// target variant or field, a target field whose type cannot carry the
387/// kind, and a kind this build does not recognise (the schema crate's
388/// `#[non_exhaustive]` escape hatch — rejecting it keeps
389/// `scalar_shorthand_value_peg`'s `_` arm from ever running).
390fn check_scalar_shorthands(
391    schema: &NodeSchema,
392    v: &VariantSchema,
393    c: &ChildSchema,
394) -> Vec<Diagnostic> {
395    let mut diags = Vec::new();
396    if c.scalar_shorthands.is_empty() {
397        return diags;
398    }
399    let site = format!("variant `{}` child slot `{}`", v.name, c.name);
400    if !matches!(c.multiplicity, Multiplicity::One | Multiplicity::Optional) {
401        diags.push(Diagnostic::error(
402            codes::UNSUPPORTED_SCALAR_SHORTHAND,
403            format!("{site}: scalar shorthands are only supported on `One` / `Optional` slots"),
404        ));
405        return diags;
406    }
407    if !matches!(c.value_shape, ChildValueShape::Recursive) {
408        diags.push(Diagnostic::error(
409            codes::UNSUPPORTED_SCALAR_SHORTHAND,
410            format!("{site}: scalar shorthands require a recursive value shape"),
411        ));
412        return diags;
413    }
414    let mut seen: Vec<ScalarKind> = Vec::new();
415    for sh in &c.scalar_shorthands {
416        if seen.contains(&sh.kind) {
417            diags.push(Diagnostic::error(
418                codes::UNSUPPORTED_SCALAR_SHORTHAND,
419                format!(
420                    "{site}: duplicate shorthand for kind `{}` — each kind may map to \
421                     at most one target so dispatch stays unambiguous",
422                    sh.kind.as_str()
423                ),
424            ));
425            continue;
426        }
427        seen.push(sh.kind);
428        let Some(target) = schema.variant(&sh.variant) else {
429            diags.push(Diagnostic::error(
430                codes::UNSUPPORTED_SCALAR_SHORTHAND,
431                format!(
432                    "{site}: shorthand target variant `{}` is not declared in schema `{}`",
433                    sh.variant, schema.name
434                ),
435            ));
436            continue;
437        };
438        let Some(field) = target.fields.iter().find(|f| f.name == sh.field) else {
439            diags.push(Diagnostic::error(
440                codes::UNSUPPORTED_SCALAR_SHORTHAND,
441                format!(
442                    "{site}: shorthand target variant `{}` has no payload field `{}`",
443                    sh.variant, sh.field
444                ),
445            ));
446            continue;
447        };
448        let ty = strip_ws(&field.ty);
449        let compatible = match sh.kind {
450            ScalarKind::Str => ty == "String",
451            ScalarKind::Int => INT_TYPES.contains(&ty.as_str()),
452            ScalarKind::Bool => ty == "bool",
453            // `#[non_exhaustive]` catch-all: reject kinds this build
454            // does not know rather than generating a grammar that
455            // silently drops them.
456            _ => {
457                diags.push(Diagnostic::error(
458                    codes::UNSUPPORTED_SCALAR_SHORTHAND,
459                    format!(
460                        "{site}: unrecognised ScalarKind (upgrade dsl-kit-parse to a \
461                         version that knows about it)"
462                    ),
463                ));
464                continue;
465            }
466        };
467        if !compatible {
468            diags.push(Diagnostic::error(
469                codes::UNSUPPORTED_SCALAR_SHORTHAND,
470                format!(
471                    "{site}: shorthand kind `{}` cannot target `{}::{}` of type `{}`",
472                    sh.kind.as_str(),
473                    sh.variant,
474                    sh.field,
475                    field.ty
476                ),
477            ));
478        }
479    }
480    diags
481}
482
483/// Builds the rule for one variant. Three shapes, all keeping schema
484/// order (payload fields, then child slots):
485///
486/// - **Strict** (no optional fields): `%kw:V "(" arg ("," arg)* ")"`.
487///   Preserves the pre-0.3 canonical spelling for variants that never
488///   omit.
489/// - **Mixed** (some optional fields, at least one required argument):
490///   an argument is *omittable* exactly when `check_conformance`
491///   accepts its absence — an optional payload field, or an `Optional`
492///   / `Many` / `Map` child slot not declared `non_empty`. Required
493///   arguments stay mandatory at their position; each omittable one
494///   becomes an optional clause at *its* position with the separating
495///   comma folded in — `("," name ":" value)?` after a required
496///   argument, `(name ":" value ",")?` before the first one. The
497///   grammar itself rejects a missing required argument, so
498///   `example_gen`'s minimal derivation conforms by construction.
499/// - **All-omittable** (every argument may be absent): `%kw:V "(" (arg
500///   ("," arg)*)? ")"` where `arg` is `arg_1 | arg_2 | ...`, each
501///   alternative carrying its own `%kw:name` prefix. Nothing is
502///   required, so the free-order list is exact.
503///
504/// Child slots count as omittable only once a variant has an optional
505/// payload field: the strict shape keeps `items: []` / `body: none`
506/// mandatory, as it always has. `check_conformance` remains the
507/// authority on duplicate / unknown slot diagnostics in every shape.
508fn variant_rule(v: &VariantSchema, ids: &IdGen, overrides: &SyntaxOverrides) -> Peg {
509    // `(argument production, omittable?)` in schema order.
510    let build_args = |ids: &IdGen| -> Vec<(Peg, bool)> {
511        let mut args = Vec::new();
512        for f in &v.fields {
513            let value = resolved_field_value_peg(&v.name, f, ids, overrides)
514                .expect("unsupported field types were rejected before rule generation");
515            let arg = seq(
516                ids,
517                vec![
518                    token(ids, format!("%kw:{}", f.name)),
519                    token(ids, ":"),
520                    field(ids, f.name.clone(), value),
521                ],
522            );
523            args.push((arg, f.optional));
524        }
525        for c in &v.children {
526            let omittable = matches!(
527                c.multiplicity,
528                Multiplicity::Optional | Multiplicity::Many | Multiplicity::Map
529            ) && !c.non_empty;
530            args.push((child_arg_peg(c, ids), omittable));
531        }
532        args
533    };
534    let args = build_args(ids);
535    let has_optional_field = v.fields.iter().any(|f| f.optional);
536    let any_required = args.iter().any(|(_, opt)| !*opt);
537
538    let mut items = vec![token(ids, format!("%kw:{}", v.name)), token(ids, "(")];
539    if !has_optional_field {
540        // Strict.
541        for (i, (arg, _)) in args.into_iter().enumerate() {
542            if i > 0 {
543                items.push(token(ids, ","));
544            }
545            items.push(arg);
546        }
547    } else if any_required {
548        // Mixed: optional clauses carry their own comma, on the side
549        // facing the nearest required argument.
550        let mut seen_required = false;
551        for (arg, optional) in args {
552            if optional {
553                let clause = if seen_required {
554                    seq(ids, vec![token(ids, ","), arg])
555                } else {
556                    seq(ids, vec![arg, token(ids, ",")])
557                };
558                items.push(repeat(ids, clause, 0, Some(1)));
559            } else {
560                if seen_required {
561                    items.push(token(ids, ","));
562                }
563                items.push(arg);
564                seen_required = true;
565            }
566        }
567    } else {
568        // All-omittable: free-order list. The tail repeats `("," arg)`;
569        // arguments are rebuilt per position so each Peg node gets a
570        // fresh id (nodes are id-unique in a grammar).
571        let head = choice(ids, args.into_iter().map(|(a, _)| a).collect());
572        let tail_alt = choice(ids, build_args(ids).into_iter().map(|(a, _)| a).collect());
573        let tail = repeat(ids, seq(ids, vec![token(ids, ","), tail_alt]), 0, None);
574        let full = seq(ids, vec![head, tail]);
575        items.push(repeat(ids, full, 0, Some(1)));
576    }
577    items.push(token(ids, ")"));
578
579    rule(
580        ids,
581        v.name.clone(),
582        node(ids, v.name.clone(), seq(ids, items)),
583    )
584}
585
586/// Value production for a payload field: the most specific
587/// [`SyntaxOverrides`] entry if registered, else the built-in mapping.
588fn resolved_field_value_peg(
589    variant: &str,
590    f: &FieldSchema,
591    ids: &IdGen,
592    overrides: &SyntaxOverrides,
593) -> Option<Peg> {
594    match overrides.resolve(variant, f) {
595        Some(factory) => Some(factory(ids)),
596        None => field_value_peg(f, ids),
597    }
598}
599
600/// Built-in value production for a payload field, by Rust type source
601/// text. `None` when the type has no canonical-syntax mapping.
602///
603/// Recognised (whitespace-insensitive on the type-source spelling):
604///
605/// - `String` → `%str`
606/// - the integer types → `%int`
607/// - `bool` → `true` / `false`
608/// - `Option<String>` → `none` | `%str`
609/// - `Vec<String>` → `[ %str ("," %str)* ]`, empty list allowed
610///
611/// The last two entries realise Layer 2 of the "built-in optional
612/// payload fields" contract — downstream DSLs no longer need to
613/// register a [`SyntaxOverrides`] entry (nor a paired
614/// `#[dsl_build(with = ...)]` converter) for these shapes.
615fn field_value_peg(f: &FieldSchema, ids: &IdGen) -> Option<Peg> {
616    let ty = strip_ws(&f.ty);
617    if ty == "String" {
618        Some(token(ids, "%str"))
619    } else if INT_TYPES.contains(&ty.as_str()) {
620        Some(token(ids, "%int"))
621    } else if ty == "bool" {
622        Some(choice(
623            ids,
624            vec![token(ids, "%kw:true"), token(ids, "%kw:false")],
625        ))
626    } else if ty == "Option<String>" {
627        // Canonical spelling of an absent Option-payload; mirrors the
628        // `Multiplicity::Optional` child idiom.
629        Some(choice(
630            ids,
631            vec![token(ids, "%kw:none"), token(ids, "%str")],
632        ))
633    } else if ty == "Vec<String>" {
634        // `[ %str_raw ("," %str_raw)* ]` with empty list allowed.
635        // `%str_raw` (peg-level primitive) contributes the raw
636        // source slice for each element — quotes and escapes intact —
637        // so the joined field text is a JSON-compatible array literal
638        // that `build_field_vec` can hand straight to
639        // `serde_json::from_str`.
640        let elems = seq(
641            ids,
642            vec![
643                token(ids, "%str_raw"),
644                repeat(
645                    ids,
646                    seq(ids, vec![token(ids, ","), token(ids, "%str_raw")]),
647                    0,
648                    None,
649                ),
650            ],
651        );
652        Some(seq(
653            ids,
654            vec![
655                token(ids, "["),
656                repeat(ids, elems, 0, Some(1)),
657                token(ids, "]"),
658            ],
659        ))
660    } else {
661        None
662    }
663}
664
665/// Value production for one declared scalar shorthand: a synthetic
666/// node of the target variant whose single field captures the scalar
667/// token. Structurally identical to what the explicit node spelling
668/// produces, so the two spellings land on the same `ParseTree` — the
669/// lowering is expressed in the grammar itself, no post-pass needed.
670fn scalar_shorthand_value_peg(sh: &ScalarShorthand, ids: &IdGen) -> Peg {
671    let scalar = match sh.kind {
672        ScalarKind::Str => token(ids, "%str"),
673        ScalarKind::Int => token(ids, "%int"),
674        ScalarKind::Bool => choice(ids, vec![token(ids, "%kw:true"), token(ids, "%kw:false")]),
675        // Unreachable in a generated grammar: the pre-flight check
676        // (`check_scalar_shorthands`) rejects unrecognised kinds with
677        // `UNSUPPORTED_SCALAR_SHORTHAND` before rule generation runs.
678        _ => unreachable!(
679            "pre-flight rejects unrecognised ScalarKind; child_arg_peg must not see it"
680        ),
681    };
682    node(
683        ids,
684        sh.variant.clone(),
685        field(ids, sh.field.clone(), scalar),
686    )
687}
688
689/// Value production for a `One` / `Optional` slot: the explicit node
690/// spelling, plus one alternative per declared scalar shorthand. The
691/// node arm is tried first so the explicit spelling always wins;
692/// a bare scalar cannot open a node production (`ident '('`), so the
693/// alternatives never overlap.
694fn one_slot_value_peg(c: &ChildSchema, ids: &IdGen) -> Peg {
695    if c.scalar_shorthands.is_empty() {
696        return rule_ref(ids, START_RULE);
697    }
698    let mut alts = vec![rule_ref(ids, START_RULE)];
699    for sh in &c.scalar_shorthands {
700        alts.push(scalar_shorthand_value_peg(sh, ids));
701    }
702    choice(ids, alts)
703}
704
705/// Argument production for one child slot, by multiplicity.
706fn child_arg_peg(c: &ChildSchema, ids: &IdGen) -> Peg {
707    let name_kw = token(ids, format!("%kw:{}", c.name));
708    let colon = token(ids, ":");
709    match c.multiplicity {
710        Multiplicity::One => seq(
711            ids,
712            vec![
713                name_kw,
714                colon,
715                field(ids, c.name.clone(), one_slot_value_peg(c, ids)),
716            ],
717        ),
718        // `name: <node>` or `name: none`. The Field arm is tried first,
719        // so a variant literally named `none` still wins when followed
720        // by `(`. The bare-`none` arm sits *outside* any Field: its
721        // matched text lands on the enclosing Node sink where it is
722        // dropped as syntactic noise, leaving the slot absent.
723        Multiplicity::Optional => seq(
724            ids,
725            vec![
726                name_kw,
727                colon,
728                choice(
729                    ids,
730                    vec![
731                        field(ids, c.name.clone(), one_slot_value_peg(c, ids)),
732                        token(ids, "%kw:none"),
733                    ],
734                ),
735            ],
736        ),
737        // `name: [ <node> ("," <node>)* ]`, empty list allowed. The
738        // list commas live inside the Field body; the mixed-field
739        // "trees win" fallback drops them as noise. A slot declared
740        // `non_empty` drops the outer 0..1 wrap so the grammar itself
741        // requires at least one element — which also makes the
742        // synthesized minimal example carry one (example_gen walks
743        // the grammar, so the constraint propagates for free).
744        Multiplicity::Many => {
745            let elems = seq(
746                ids,
747                vec![
748                    rule_ref(ids, START_RULE),
749                    repeat(
750                        ids,
751                        seq(ids, vec![token(ids, ","), rule_ref(ids, START_RULE)]),
752                        0,
753                        None,
754                    ),
755                ],
756            );
757            let list = if c.non_empty {
758                field(ids, c.name.clone(), elems)
759            } else {
760                field(ids, c.name.clone(), repeat(ids, elems, 0, Some(1)))
761            };
762            seq(
763                ids,
764                vec![name_kw, colon, token(ids, "["), list, token(ids, "]")],
765            )
766        }
767        // `name: { <key>: <node> ("," <key>: <node>)* }`, empty map
768        // allowed. Braces rather than the `Many` idiom's brackets so
769        // the two shapes are distinguishable at a glance, and matching
770        // the JSON bridge's object spelling so a DSL reads the same
771        // way in both front-ends.
772        //
773        // The key token is `%str | %ident`: keys are arbitrary strings
774        // at the `ParseTree` level, so a quoted form has to exist, but
775        // requiring quotes around every `PATH`-style key would be
776        // noise. `%str` is tried first — a quoted key is unambiguous,
777        // while `%ident` cannot start with `"` — and its production is
778        // the decoded content, so `"a b"` and `a` both arrive as plain
779        // key text.
780        Multiplicity::Map => {
781            //
782            // The `:` separator rides on the *value* half, not the
783            // key half: every token matched inside the key production
784            // contributes to the key text, so a `:` there would land
785            // in the key itself. On the value side it is dropped as
786            // syntactic noise, the same way the `Many` list's commas
787            // are.
788            //
789            // The value half branches on `value_shape`:
790            //
791            // - `Recursive` (`BTreeMap<String, Self>` /
792            //   `BTreeMap<String, Box<Self>>`) → the value is a full
793            //   AST node, produced by `rule_ref(START_RULE)`.
794            //
795            // - `Scalar { ty }` (`BTreeMap<String, String>` /
796            //   `BTreeMap<String, i64>` / …) → the value is a scalar
797            //   payload wrapped in a synthetic leaf `Node` whose
798            //   single `Field` is named `value`. That matches the
799            //   canonical entry shape the JSON bridge emits (see
800            //   `serde_bridge::build_scalar_keyed_slot`) so
801            //   `build_scalar_map` reads `.field("value")` from each
802            //   entry regardless of front-end.
803            //
804            // The `_ =>` fallback keeps the recursive spelling for
805            // any future `ChildValueShape` variant this build does
806            // not yet know about; the pre-flight check in
807            // `grammar_from_schema_with` rejects those cases with
808            // `UNSUPPORTED_MAP_VALUE_SHAPE`, so `child_arg_peg` never
809            // sees an unrecognised shape at run time.
810            let value_prod = |ids: &IdGen| -> Peg {
811                match &c.value_shape {
812                    ChildValueShape::Recursive => rule_ref(ids, START_RULE),
813                    ChildValueShape::Scalar { ty } => {
814                        let synthetic = FieldSchema {
815                            name: "value".into(),
816                            ty: ty.clone(),
817                            optional: false,
818                        };
819                        let scalar = field_value_peg(&synthetic, ids).expect(
820                            "scalar-map value type rejected by pre-flight; \
821                             child_arg_peg must not see it",
822                        );
823                        node(ids, "", field(ids, "value", scalar))
824                    }
825                    _ => rule_ref(ids, START_RULE),
826                }
827            };
828            let entry = |ids: &IdGen| -> Peg {
829                keyed_entry(
830                    ids,
831                    c.name.clone(),
832                    choice(ids, vec![token(ids, "%str"), token(ids, "%ident")]),
833                    seq(ids, vec![token(ids, ":"), value_prod(ids)]),
834                )
835            };
836            let entries = seq(
837                ids,
838                vec![
839                    entry(ids),
840                    repeat(ids, seq(ids, vec![token(ids, ","), entry(ids)]), 0, None),
841                ],
842            );
843            // A `non_empty` map drops the outer 0..1 wrap, same as
844            // the `Many` arm above: the grammar requires at least one
845            // entry and the synthesized minimal example follows.
846            let body = if c.non_empty {
847                entries
848            } else {
849                repeat(ids, entries, 0, Some(1))
850            };
851            seq(
852                ids,
853                vec![name_kw, colon, token(ids, "{"), body, token(ids, "}")],
854            )
855        }
856        // `#[non_exhaustive]` catch-all: a future Multiplicity variant
857        // added to dsl-kit-schema before this crate is updated would
858        // land here. The pre-flight check in
859        // `grammar_from_schema_with` should be extended in lockstep to
860        // reject unknown variants; if that extension is missed the
861        // panic here surfaces the omission loudly instead of emitting
862        // a silently-wrong grammar rule.
863        _ => unreachable!(
864            "child_arg_peg encountered an unrecognised Multiplicity variant on slot \
865             `{}` — extend the pre-flight check in grammar_from_schema_with to reject it",
866            c.name
867        ),
868    }
869}
870
871/// Convenience: generate and immediately assert the grammar is clean
872/// under `GrammarCheck` (left recursion, nullable repeats, schema
873/// consistency). Intended for tests and one-shot setup paths; returns
874/// the same grammar as [`grammar_from_schema`].
875pub fn checked_grammar_from_schema(
876    schema: &NodeSchema,
877    ids: &IdGen,
878) -> Result<Grammar, BuildError> {
879    checked_grammar_from_schema_with(schema, ids, &SyntaxOverrides::default())
880}
881
882/// [`checked_grammar_from_schema`] with [`SyntaxOverrides`] consulted
883/// before the built-in field mapping.
884pub fn checked_grammar_from_schema_with(
885    schema: &NodeSchema,
886    ids: &IdGen,
887    overrides: &SyntaxOverrides,
888) -> Result<Grammar, BuildError> {
889    let grammar = grammar_from_schema_with(schema, ids, overrides)?;
890    let mut diags = grammar_check::check_left_recursion(&grammar);
891    diags.extend(grammar_check::check_nullable_repeat(&grammar));
892    diags.extend(
893        grammar_check::check_schema_consistency(&grammar, schema)
894            .into_iter()
895            .filter(|d| d.severity == crate::Severity::Error),
896    );
897    if diags.is_empty() {
898        Ok(grammar)
899    } else {
900        Err(BuildError::new(diags))
901    }
902}
903
904#[cfg(test)]
905mod tests {
906    use super::*;
907    use crate::{RawValue, check_conformance};
908    use dsl_kit_schema::ChildValueShape;
909
910    /// Expr-flavoured schema exercising every supported shape: int /
911    /// string / bool fields, One / Optional / Many children, and a
912    /// zero-argument variant.
913    fn demo_schema() -> NodeSchema {
914        NodeSchema {
915            name: "Expr".into(),
916            variants: vec![
917                VariantSchema {
918                    name: "Lit".into(),
919                    fields: vec![FieldSchema {
920                        name: "value".into(),
921                        ty: "i64".into(),
922                        optional: false,
923                    }],
924                    children: vec![],
925                },
926                VariantSchema {
927                    name: "Name".into(),
928                    fields: vec![
929                        FieldSchema {
930                            name: "text".into(),
931                            ty: "String".into(),
932                            optional: false,
933                        },
934                        FieldSchema {
935                            name: "quoted".into(),
936                            ty: "bool".into(),
937                            optional: false,
938                        },
939                    ],
940                    children: vec![],
941                },
942                VariantSchema {
943                    name: "Add".into(),
944                    fields: vec![],
945                    children: vec![
946                        ChildSchema {
947                            name: "lhs".into(),
948                            multiplicity: Multiplicity::One,
949                            value_shape: ChildValueShape::Recursive,
950                            scalar_shorthands: vec![],
951                            non_empty: false,
952                        },
953                        ChildSchema {
954                            name: "rhs".into(),
955                            multiplicity: Multiplicity::One,
956                            value_shape: ChildValueShape::Recursive,
957                            scalar_shorthands: vec![],
958                            non_empty: false,
959                        },
960                    ],
961                },
962                VariantSchema {
963                    name: "Neg".into(),
964                    fields: vec![],
965                    children: vec![ChildSchema {
966                        name: "body".into(),
967                        multiplicity: Multiplicity::Optional,
968                        value_shape: ChildValueShape::Recursive,
969                        scalar_shorthands: vec![],
970                        non_empty: false,
971                    }],
972                },
973                VariantSchema {
974                    name: "List".into(),
975                    fields: vec![],
976                    children: vec![ChildSchema {
977                        name: "items".into(),
978                        multiplicity: Multiplicity::Many,
979                        value_shape: ChildValueShape::Recursive,
980                        scalar_shorthands: vec![],
981                        non_empty: false,
982                    }],
983                },
984                VariantSchema {
985                    name: "Env".into(),
986                    fields: vec![],
987                    children: vec![ChildSchema {
988                        name: "entries".into(),
989                        multiplicity: Multiplicity::Map,
990                        value_shape: ChildValueShape::Recursive,
991                        scalar_shorthands: vec![],
992                        non_empty: false,
993                    }],
994                },
995                VariantSchema {
996                    name: "Unit".into(),
997                    fields: vec![],
998                    children: vec![],
999                },
1000            ],
1001        }
1002    }
1003
1004    fn demo_grammar() -> Grammar {
1005        checked_grammar_from_schema(&demo_schema(), &IdGen::new())
1006            .expect("demo schema generates a clean grammar")
1007    }
1008
1009    /// Parse + conformance-check against the demo schema in one go.
1010    fn parse_ok(input: &str) -> crate::ParseTree {
1011        let g = demo_grammar();
1012        let tree = g
1013            .parse(input)
1014            .unwrap_or_else(|e| panic!("parse failed for {input:?}: {:?}", e.diagnostics));
1015        let diags = check_conformance(&tree, &demo_schema());
1016        assert!(
1017            diags.is_empty(),
1018            "conformance clean for {input:?}: {diags:?}"
1019        );
1020        tree
1021    }
1022
1023    #[test]
1024    fn generated_grammar_passes_all_static_checks() {
1025        // checked_grammar_from_schema already runs the three checks;
1026        // this test pins that it succeeds for the full shape matrix.
1027        demo_grammar();
1028    }
1029
1030    #[test]
1031    fn parses_int_field_variant() {
1032        let tree = parse_ok("Lit(value: -42)");
1033        assert_eq!(tree.variant, "Lit");
1034        assert_eq!(tree.field("value"), Some(&RawValue::Text("-42".into())));
1035    }
1036
1037    #[test]
1038    fn parses_string_and_bool_fields_with_escapes() {
1039        let tree = parse_ok(r#"Name(text: "hello \"world\"\n", quoted: true)"#);
1040        assert_eq!(
1041            tree.field("text"),
1042            Some(&RawValue::Text("hello \"world\"\n".into()))
1043        );
1044        assert_eq!(tree.field("quoted"), Some(&RawValue::Text("true".into())));
1045    }
1046
1047    #[test]
1048    fn parses_nested_one_children() {
1049        let tree = parse_ok("Add(lhs: Lit(value: 1), rhs: Neg(body: none))");
1050        let lhs = tree.child_slot("lhs").unwrap();
1051        assert_eq!(lhs.len(), 1);
1052        assert_eq!(lhs[0].variant, "Lit");
1053        let rhs = tree.child_slot("rhs").unwrap();
1054        assert_eq!(rhs[0].variant, "Neg");
1055    }
1056
1057    #[test]
1058    fn optional_child_none_leaves_slot_absent() {
1059        let tree = parse_ok("Neg(body: none)");
1060        assert!(
1061            tree.child_slot("body").is_none(),
1062            "bare `none` = absent slot"
1063        );
1064    }
1065
1066    #[test]
1067    fn optional_child_present_binds_one_tree() {
1068        let tree = parse_ok("Neg(body: Lit(value: 3))");
1069        assert_eq!(tree.child_slot("body").unwrap().len(), 1);
1070    }
1071
1072    #[test]
1073    fn many_child_list_binds_in_order_and_drops_commas() {
1074        let tree = parse_ok("List(items: [Lit(value: 1), Lit(value: 2), Unit()])");
1075        let items = tree.child_slot("items").unwrap();
1076        let variants: Vec<&str> = items.iter().map(|t| t.variant.as_str()).collect();
1077        assert_eq!(variants, ["Lit", "Lit", "Unit"]);
1078    }
1079
1080    #[test]
1081    fn many_child_empty_list_is_conformant() {
1082        let tree = parse_ok("List(items: [])");
1083        assert!(
1084            tree.child_slot("items").is_none_or(<[_]>::is_empty),
1085            "empty list = zero children"
1086        );
1087    }
1088
1089    #[test]
1090    fn keyed_map_binds_entries_sorted_by_key() {
1091        // Written deliberately out of order, with one quoted key that
1092        // could not be spelled as a bare identifier: the parser is
1093        // responsible for landing both in canonical order.
1094        let tree = parse_ok(r#"Env(entries: { zeta: Unit(), "a b": Lit(value: 1) })"#);
1095        let entries = tree.keyed_child_slot("entries").expect("keyed slot bound");
1096        let keys: Vec<&str> = entries.iter().map(|(k, _)| k.as_str()).collect();
1097        assert_eq!(keys, ["a b", "zeta"]);
1098        let variants: Vec<&str> = entries.iter().map(|(_, t)| t.variant.as_str()).collect();
1099        assert_eq!(variants, ["Lit", "Unit"]);
1100        assert!(
1101            tree.children.is_empty(),
1102            "keyed entries must not leak into the positional half: {:?}",
1103            tree.children
1104        );
1105    }
1106
1107    #[test]
1108    fn keyed_map_source_order_does_not_change_the_tree() {
1109        let forward = parse_ok("Env(entries: { a: Unit(), b: Lit(value: 1) })");
1110        let reversed = parse_ok("Env(entries: { b: Lit(value: 1), a: Unit() })");
1111        // Spans differ (the two spellings put the subtrees at
1112        // different offsets), so compare the keyed payload rather than
1113        // the whole tree.
1114        let keys = |t: &crate::ParseTree| -> Vec<String> {
1115            t.keyed_child_slot("entries")
1116                .unwrap()
1117                .iter()
1118                .map(|(k, v)| format!("{k}={}", v.variant))
1119                .collect()
1120        };
1121        assert_eq!(keys(&forward), keys(&reversed));
1122    }
1123
1124    #[test]
1125    fn keyed_map_empty_is_conformant() {
1126        let tree = parse_ok("Env(entries: {})");
1127        assert!(
1128            tree.keyed_child_slot("entries").is_none_or(<[_]>::is_empty),
1129            "empty map = zero entries"
1130        );
1131    }
1132
1133    #[test]
1134    fn keyed_map_duplicate_key_parses_but_fails_conformance() {
1135        // The grammar has no reason to reject it — duplicate detection
1136        // is the schema's job, and `parse_ok` would hide the split, so
1137        // this test drives the two stages apart deliberately.
1138        let g = demo_grammar();
1139        let tree = g
1140            .parse("Env(entries: { k: Unit(), k: Lit(value: 1) })")
1141            .expect("grammar accepts a repeated key");
1142        let diags = check_conformance(&tree, &demo_schema());
1143        assert!(
1144            diags.iter().any(|d| d.code == crate::codes::DUPLICATE_KEY),
1145            "expected DUPLICATE_KEY; got {:?}",
1146            diags.iter().map(|d| d.code.as_str()).collect::<Vec<_>>()
1147        );
1148    }
1149
1150    #[test]
1151    fn zero_argument_variant_parses() {
1152        let tree = parse_ok("Unit()");
1153        assert_eq!(tree.variant, "Unit");
1154        assert!(tree.fields.is_empty() && tree.children.is_empty());
1155    }
1156
1157    #[test]
1158    fn whitespace_and_newlines_are_tolerated() {
1159        let tree = parse_ok("Add(\n  lhs: Lit( value : 7 ),\n  rhs: Unit()\n)");
1160        assert_eq!(tree.child_slot("lhs").unwrap()[0].variant, "Lit");
1161    }
1162
1163    #[test]
1164    fn unsupported_field_type_fails_generation_with_full_list() {
1165        let schema = NodeSchema {
1166            name: "Bad".into(),
1167            variants: vec![VariantSchema {
1168                name: "Par".into(),
1169                fields: vec![
1170                    FieldSchema {
1171                        name: "policy".into(),
1172                        ty: "Option<JoinPolicy>".into(),
1173                        optional: false,
1174                    },
1175                    FieldSchema {
1176                        name: "reducer".into(),
1177                        ty: "ReducerId".into(),
1178                        optional: false,
1179                    },
1180                ],
1181                children: vec![],
1182            }],
1183        };
1184        let err = grammar_from_schema(&schema, &IdGen::new()).unwrap_err();
1185        assert_eq!(err.diagnostics.len(), 2, "one diagnostic per bad field");
1186        assert!(
1187            err.diagnostics
1188                .iter()
1189                .all(|d| d.code == codes::UNSUPPORTED_FIELD)
1190        );
1191    }
1192
1193    /// A scalar-valued keyed slot whose value type has a built-in
1194    /// canonical-syntax mapping (`String`, integer, `bool`, …)
1195    /// generates a grammar cleanly — the same built-in mapping the
1196    /// payload path already uses is reused for the keyed-entry
1197    /// value slot, wrapped in a synthetic leaf node carrying the
1198    /// `value` field so `build_scalar_map` reads it back
1199    /// canonically. Pins the "text syntax landed for Shape 1"
1200    /// contract so a regression to the pre-0.7 "loud fail" spelling
1201    /// is impossible to ship.
1202    #[test]
1203    fn scalar_keyed_slot_with_builtin_type_generates_grammar() {
1204        let schema = NodeSchema {
1205            name: "Cfg".into(),
1206            variants: vec![VariantSchema {
1207                name: "Env".into(),
1208                fields: vec![],
1209                children: vec![ChildSchema::scalar_map("entries", "String")],
1210            }],
1211        };
1212        grammar_from_schema(&schema, &IdGen::new()).expect(
1213            "String is a built-in scalar; the pre-flight must accept it and \
1214             child_arg_peg must emit a grammar rule that wraps each entry's \
1215             value as a `value`-field leaf",
1216        );
1217    }
1218
1219    /// A scalar-valued keyed slot whose value type has no built-in
1220    /// mapping (and no `SyntaxOverrides` entry — `child_arg_peg`
1221    /// does not yet thread overrides into the keyed-entry value
1222    /// slot) still fails loudly at grammar-generation time with
1223    /// [`codes::UNSUPPORTED_MAP_VALUE_SHAPE`]. The diagnostic
1224    /// message points the DSL author at the JSON front-end and the
1225    /// override path so they never see the raw
1226    /// `child_arg_peg` `.expect(...)` panic downstream.
1227    #[test]
1228    fn scalar_keyed_slot_with_unmapped_type_fails_grammar_generation_loudly() {
1229        let schema = NodeSchema {
1230            name: "Cfg".into(),
1231            variants: vec![VariantSchema {
1232                name: "Env".into(),
1233                fields: vec![],
1234                children: vec![ChildSchema::scalar_map("entries", "JoinPolicy")],
1235            }],
1236        };
1237        let err = grammar_from_schema(&schema, &IdGen::new()).unwrap_err();
1238        assert_eq!(err.diagnostics.len(), 1);
1239        assert_eq!(err.diagnostics[0].code, codes::UNSUPPORTED_MAP_VALUE_SHAPE);
1240        assert!(
1241            err.diagnostics[0].message.contains("entries"),
1242            "diagnostic mentions the slot name: {}",
1243            err.diagnostics[0].message
1244        );
1245        assert!(
1246            err.diagnostics[0].message.contains("JoinPolicy"),
1247            "diagnostic mentions the scalar value type: {}",
1248            err.diagnostics[0].message
1249        );
1250    }
1251
1252    /// Recursive keyed slots still generate cleanly — the scalar
1253    /// gate must not accidentally reject the pre-0.6 keyed shape.
1254    #[test]
1255    fn recursive_keyed_slot_still_generates_grammar() {
1256        let schema = NodeSchema {
1257            name: "Cfg".into(),
1258            variants: vec![
1259                VariantSchema {
1260                    name: "Env".into(),
1261                    fields: vec![],
1262                    children: vec![ChildSchema::recursive("entries", Multiplicity::Map)],
1263                },
1264                VariantSchema {
1265                    name: "Unit".into(),
1266                    fields: vec![],
1267                    children: vec![],
1268                },
1269            ],
1270        };
1271        grammar_from_schema(&schema, &IdGen::new())
1272            .expect("recursive keyed shape still supported end-to-end in the text front-end");
1273    }
1274
1275    /// Flow-shaped schema whose `Par` payload fields the built-in
1276    /// mapping rejects — the override motivating case.
1277    fn par_schema() -> NodeSchema {
1278        NodeSchema {
1279            name: "Flow".into(),
1280            variants: vec![
1281                VariantSchema {
1282                    name: "Par".into(),
1283                    fields: vec![
1284                        FieldSchema {
1285                            name: "policy".into(),
1286                            // Token-stream spelling, as the derive extracts it.
1287                            ty: "Option < JoinPolicy >".into(),
1288                            optional: false,
1289                        },
1290                        FieldSchema {
1291                            name: "reducer_id".into(),
1292                            ty: "Option < String >".into(),
1293                            optional: false,
1294                        },
1295                    ],
1296                    children: vec![ChildSchema {
1297                        name: "children".into(),
1298                        multiplicity: Multiplicity::Many,
1299                        value_shape: ChildValueShape::Recursive,
1300                        scalar_shorthands: vec![],
1301                        non_empty: false,
1302                    }],
1303                },
1304                VariantSchema {
1305                    name: "Call".into(),
1306                    fields: vec![FieldSchema {
1307                        name: "label".into(),
1308                        ty: "String".into(),
1309                        optional: false,
1310                    }],
1311                    children: vec![],
1312                },
1313            ],
1314        }
1315    }
1316
1317    fn par_overrides() -> SyntaxOverrides {
1318        SyntaxOverrides::new()
1319            .for_type("Option<JoinPolicy>", |ids| {
1320                choice(
1321                    ids,
1322                    vec![
1323                        token(ids, "%kw:none"),
1324                        token(ids, "%kw:all_failfast"),
1325                        token(ids, "%kw:any_failfast"),
1326                    ],
1327                )
1328            })
1329            .for_type("Option<String>", |ids| {
1330                choice(ids, vec![token(ids, "%kw:none"), token(ids, "%str")])
1331            })
1332    }
1333
1334    #[test]
1335    fn type_overrides_unlock_exotic_payload_fields() {
1336        // Without overrides the Flow-shaped schema fails generation
1337        // (pinned by unsupported_field_type_fails_generation_with_full_list);
1338        // with them it generates check-clean and parses. Note the
1339        // override keys are written without whitespace while the schema
1340        // carries the token-stream spelling.
1341        let g = checked_grammar_from_schema_with(&par_schema(), &IdGen::new(), &par_overrides())
1342            .expect("overridden Flow schema generates a clean grammar");
1343        let tree = g
1344            .parse(
1345                r#"Par(policy: all_failfast, reducer_id: "reduce_all_ordered",
1346                     children: [Call(label: "a"), Call(label: "b")])"#,
1347            )
1348            .expect("canonical Par text parses");
1349        let diags = check_conformance(&tree, &par_schema());
1350        assert!(diags.is_empty(), "conformance clean: {diags:?}");
1351        assert_eq!(
1352            tree.field("policy"),
1353            Some(&RawValue::Text("all_failfast".into()))
1354        );
1355        assert_eq!(
1356            tree.field("reducer_id"),
1357            Some(&RawValue::Text("reduce_all_ordered".into()))
1358        );
1359        assert_eq!(tree.child_slot("children").unwrap().len(), 2);
1360    }
1361
1362    #[test]
1363    fn field_override_wins_over_type_override() {
1364        // Same type in both entries; the (variant, field)-pinned one
1365        // must decide the syntax.
1366        let overrides = par_overrides().for_field("Par", "policy", |ids| token(ids, "%kw:pinned"));
1367        let g = checked_grammar_from_schema_with(&par_schema(), &IdGen::new(), &overrides)
1368            .expect("clean grammar with field-level override");
1369        let tree = g
1370            .parse(r#"Par(policy: pinned, reducer_id: none, children: [])"#)
1371            .expect("field-level syntax parses");
1372        assert_eq!(tree.field("policy"), Some(&RawValue::Text("pinned".into())));
1373        // The type-level spelling is no longer accepted at that site.
1374        assert!(
1375            g.parse(r#"Par(policy: all_failfast, reducer_id: none, children: [])"#)
1376                .is_err(),
1377            "type-level syntax rejected once the field is pinned"
1378        );
1379    }
1380
1381    #[test]
1382    fn unrelated_override_leaves_builtin_mapping_and_failure_intact() {
1383        // An override for some other type neither rescues the
1384        // unsupported fields nor perturbs built-in ones. Note that
1385        // `Option<String>` on `reducer_id` is now a built-in mapping
1386        // (Layer 2 of the "built-in optional payload fields"
1387        // contract), so only the `Option<JoinPolicy>` field on
1388        // `policy` remains unmapped without a `SyntaxOverrides` entry.
1389        let overrides = SyntaxOverrides::new().for_type("Uuid", |ids| token(ids, "%str"));
1390        let err = grammar_from_schema_with(&par_schema(), &IdGen::new(), &overrides).unwrap_err();
1391        assert_eq!(
1392            err.diagnostics.len(),
1393            1,
1394            "policy is the only Par field still unmapped without overrides",
1395        );
1396        assert!(
1397            err.diagnostics
1398                .iter()
1399                .all(|d| d.code == codes::UNSUPPORTED_FIELD)
1400        );
1401        assert!(
1402            err.diagnostics[0].message.contains("policy"),
1403            "unmapped-field diagnostic points at `policy`",
1404        );
1405        // Built-in demo schema is unaffected by the stray entry.
1406        let g = checked_grammar_from_schema_with(&demo_schema(), &IdGen::new(), &overrides)
1407            .expect("demo schema still generates");
1408        assert_eq!(g.parse("Lit(value: 7)").unwrap().variant, "Lit");
1409    }
1410
1411    /// Layer 2: `Option<String>` payload maps to `none | %str` via the
1412    /// built-in mapping (no `SyntaxOverrides` entry needed). Canonical
1413    /// text parses both spellings and both build through the derive's
1414    /// `build_field_optional` route.
1415    #[test]
1416    fn builtin_option_string_mapping_accepts_none_and_str() {
1417        let schema = NodeSchema {
1418            name: "Meta".into(),
1419            variants: vec![VariantSchema {
1420                name: "Row".into(),
1421                fields: vec![FieldSchema {
1422                    name: "description".into(),
1423                    ty: "Option<String>".into(),
1424                    optional: true,
1425                }],
1426                children: vec![],
1427            }],
1428        };
1429        let g = checked_grammar_from_schema(&schema, &IdGen::new())
1430            .expect("Option<String> is a built-in mapping");
1431        // `none` spelling.
1432        let t1 = g.parse(r#"Row(description: none)"#).expect("none parses");
1433        assert_eq!(
1434            t1.field("description"),
1435            Some(&RawValue::Text("none".into())),
1436        );
1437        // `%str` spelling.
1438        let t2 = g.parse(r#"Row(description: "hi")"#).expect("string parses");
1439        assert_eq!(t2.field("description"), Some(&RawValue::Text("hi".into())));
1440        // Omitted entirely (Layer 1 optional PEG wrap).
1441        let t3 = g.parse(r#"Row()"#).expect("omitted parses");
1442        assert!(t3.field("description").is_none());
1443        // check_conformance is clean for all three.
1444        for t in [&t1, &t2, &t3] {
1445            assert!(
1446                check_conformance(t, &schema).is_empty(),
1447                "conformance clean for {t:?}",
1448            );
1449        }
1450    }
1451
1452    /// Layer 2: `Vec<String>` payload maps to `[ %str ("," %str)* ]`
1453    /// via the built-in mapping. Empty list, single item, and multi
1454    /// item all parse; captured text is JSON-parsable so
1455    /// `build_field_vec` reads it directly.
1456    #[test]
1457    fn builtin_vec_string_mapping_accepts_bracketed_list() {
1458        let schema = NodeSchema {
1459            name: "Meta".into(),
1460            variants: vec![VariantSchema {
1461                name: "Row".into(),
1462                fields: vec![FieldSchema {
1463                    name: "tags".into(),
1464                    ty: "Vec<String>".into(),
1465                    optional: true,
1466                }],
1467                children: vec![],
1468            }],
1469        };
1470        let g = checked_grammar_from_schema(&schema, &IdGen::new())
1471            .expect("Vec<String> is a built-in mapping");
1472        // Empty list.
1473        let t1 = g.parse(r#"Row(tags: [])"#).expect("empty list parses");
1474        assert_eq!(t1.field("tags"), Some(&RawValue::Text("[]".into())));
1475        // Multi item. The PEG runtime's implicit whitespace-skip
1476        // strips inter-token spaces from the captured text, so the
1477        // field carries the compact form `["a","b"]` (still valid
1478        // JSON — `serde_json::from_str` accepts it).
1479        let t2 = g
1480            .parse(r#"Row(tags: ["a", "b"])"#)
1481            .expect("two items parses");
1482        assert_eq!(
1483            t2.field("tags"),
1484            Some(&RawValue::Text(r#"["a","b"]"#.into())),
1485        );
1486        // Omitted.
1487        let t3 = g.parse(r#"Row()"#).expect("omitted parses");
1488        assert!(t3.field("tags").is_none());
1489        for t in [&t1, &t2, &t3] {
1490            assert!(
1491                check_conformance(t, &schema).is_empty(),
1492                "conformance clean for {t:?}",
1493            );
1494        }
1495    }
1496
1497    /// Mixed shape: a required field next to optional ones. The
1498    /// grammar itself enforces the required argument (no reliance on
1499    /// `check_conformance`), optional arguments may be omitted at
1500    /// their position, and the synthesized minimal example conforms.
1501    #[test]
1502    fn mixed_required_and_optional_fields_keep_required_in_the_grammar() {
1503        let schema = NodeSchema {
1504            name: "Q".into(),
1505            variants: vec![VariantSchema {
1506                name: "In".into(),
1507                fields: vec![
1508                    FieldSchema::required("field", "String"),
1509                    FieldSchema::optional("values", "Vec<String>"),
1510                ],
1511                children: vec![],
1512            }],
1513        };
1514        let g = checked_grammar_from_schema(&schema, &IdGen::new()).expect("generates");
1515        for ok in [
1516            r#"In(field: "x")"#,
1517            r#"In(field: "x", values: [])"#,
1518            r#"In(field: "x", values: ["a", "b"])"#,
1519        ] {
1520            let t = g.parse(ok).unwrap_or_else(|e| panic!("`{ok}`: {e:?}"));
1521            assert!(check_conformance(&t, &schema).is_empty(), "{ok}");
1522        }
1523        // The required argument is a grammar-level obligation now.
1524        let err = g.parse("In()").expect_err("required field omitted");
1525        assert!(
1526            err.diagnostics
1527                .iter()
1528                .all(|d| d.code == crate::peg::codes::UNEXPECTED),
1529            "{:?}",
1530            err.diagnostics
1531        );
1532        // Optional arguments live at their schema position; reordering
1533        // is not part of the canonical spelling.
1534        assert!(g.parse(r#"In(values: ["a"], field: "x")"#).is_err());
1535
1536        let ex = crate::example_gen::examples_from_grammar(&g).expect("examples");
1537        assert_eq!(ex.per_rule[0].text, r#"In(field: "example")"#);
1538        let t = g
1539            .parse(&ex.per_rule[0].text)
1540            .expect("minimal example parses");
1541        assert!(check_conformance(&t, &schema).is_empty());
1542    }
1543
1544    /// Mixed shape with the optional field *before* the required one
1545    /// and a child slot after: the optional clause carries a trailing
1546    /// comma, the child stays mandatory.
1547    #[test]
1548    fn mixed_shape_with_leading_optional_and_child_slot() {
1549        let schema = NodeSchema {
1550            name: "Q".into(),
1551            variants: vec![
1552                VariantSchema {
1553                    name: "Row".into(),
1554                    fields: vec![
1555                        FieldSchema::optional("description", "Option<String>"),
1556                        FieldSchema::required("name", "String"),
1557                    ],
1558                    children: vec![ChildSchema::recursive("items", Multiplicity::Many)],
1559                },
1560                VariantSchema {
1561                    name: "Unit".into(),
1562                    fields: vec![],
1563                    children: vec![],
1564                },
1565            ],
1566        };
1567        let g = checked_grammar_from_schema(&schema, &IdGen::new()).expect("generates");
1568        for ok in [
1569            r#"Row(name: "x", items: [])"#,
1570            r#"Row(name: "x")"#,
1571            r#"Row(description: "d", name: "x", items: [Unit()])"#,
1572            r#"Row(description: none, name: "x", items: [])"#,
1573        ] {
1574            let t = g.parse(ok).unwrap_or_else(|e| panic!("`{ok}`: {e:?}"));
1575            assert!(check_conformance(&t, &schema).is_empty(), "{ok}");
1576        }
1577        assert!(g.parse(r#"Row(description: "d", items: [])"#).is_err());
1578        let ex = crate::example_gen::examples_from_grammar(&g).expect("examples");
1579        assert_eq!(ex.per_rule[0].text, r#"Row(name: "example")"#);
1580    }
1581
1582    /// A `non_empty` child slot next to an optional field is required
1583    /// by the grammar: its absence is a conformance failure, so the
1584    /// mixed shape must not let it be omitted.
1585    #[test]
1586    fn non_empty_child_slot_is_required_in_the_mixed_shape() {
1587        let mut items = ChildSchema::recursive("items", Multiplicity::Many);
1588        items.non_empty = true;
1589        let schema = NodeSchema {
1590            name: "Q".into(),
1591            variants: vec![
1592                VariantSchema {
1593                    name: "All".into(),
1594                    fields: vec![FieldSchema::optional("label", "Option<String>")],
1595                    children: vec![items],
1596                },
1597                VariantSchema {
1598                    name: "Unit".into(),
1599                    fields: vec![],
1600                    children: vec![],
1601                },
1602            ],
1603        };
1604        let g = checked_grammar_from_schema(&schema, &IdGen::new()).expect("generates");
1605        assert!(g.parse("All(items: [Unit()])").is_ok());
1606        assert!(g.parse(r#"All(label: "l", items: [Unit()])"#).is_ok());
1607        assert!(g.parse("All()").is_err());
1608        assert!(g.parse(r#"All(label: "l")"#).is_err());
1609        let ex = crate::example_gen::examples_from_grammar(&g).expect("examples");
1610        assert_eq!(ex.per_rule[0].text, "All(items: [Unit()])");
1611        let t = g.parse(&ex.per_rule[0].text).unwrap();
1612        assert!(check_conformance(&t, &schema).is_empty());
1613    }
1614
1615    #[test]
1616    fn empty_schema_fails_generation() {
1617        let schema = NodeSchema {
1618            name: "Void".into(),
1619            variants: vec![],
1620        };
1621        let err = grammar_from_schema(&schema, &IdGen::new()).unwrap_err();
1622        assert_eq!(err.diagnostics[0].code, codes::EMPTY_SCHEMA);
1623    }
1624
1625    #[test]
1626    fn parse_error_reports_expected_set() {
1627        let g = demo_grammar();
1628        let err = g.parse("Lit(value: banana)").unwrap_err();
1629        assert!(!err.diagnostics.is_empty());
1630    }
1631}