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