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