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//! - **Payload fields** — by Rust type source text:
33//!   `String` → a `%str` literal; the integer types → `%int`;
34//!   `bool` → `true` / `false`. Any other payload type fails
35//!   generation with [`codes::UNSUPPORTED_FIELD`] — loudly, per
36//!   variant, rather than silently dropping the variant from the
37//!   grammar — unless a [`SyntaxOverrides`] entry supplies its value
38//!   production.
39//!
40//! # Syntax overrides
41//!
42//! [`grammar_from_schema_with`] accepts a [`SyntaxOverrides`] carrying
43//! value productions for payload types the built-in mapping rejects
44//! (e.g. `Option<JoinPolicy>`), keyed by type source text or pinned to
45//! one `(variant, field)` site. The override supplies only the value
46//! [`Peg`] — the surrounding `name: value` argument shape stays
47//! canonical — and its matched text becomes the field's production, so
48//! the override author owns making that text consumable downstream
49//! (typically `FromStr` on the field type, via
50//! [`build_field`](crate::build_field)).
51//!
52//! # Guarantees
53//!
54//! The generated grammar is left-recursion-free by construction (every
55//! variant rule starts with its keyword token) and contains no nullable
56//! repeats; `GrammarCheck`'s `check_left_recursion` /
57//! `check_nullable_repeat` / `check_schema_consistency` all pass
58//! against it — the tests pin this. Trees produced by parsing satisfy
59//! [`check_conformance`](crate::check_conformance) against the source
60//! schema.
61
62use std::collections::HashMap;
63
64use crate::grammar_check;
65use crate::peg::{Grammar, Peg, choice, field, node, repeat, rule, rule_ref, seq, token};
66use crate::{BuildError, Diagnostic};
67use dsl_kit_core::IdGen;
68use dsl_kit_schema::{ChildSchema, FieldSchema, Multiplicity, NodeSchema, VariantSchema};
69
70/// Diagnostic codes emitted by grammar generation.
71pub mod codes {
72    /// A payload field's Rust type has no canonical-syntax mapping.
73    pub const UNSUPPORTED_FIELD: &str = "dsl_kit::schema_gen::unsupported_field";
74    /// The schema declares no variants — there is nothing to parse.
75    pub const EMPTY_SCHEMA: &str = "dsl_kit::schema_gen::empty_schema";
76}
77
78/// Name of the generated start rule.
79pub const START_RULE: &str = "node";
80
81/// A deferred value-production constructor: overrides are registered
82/// before the [`IdGen`] doing the generation exists, so each entry is a
83/// factory invoked with the generator's `ids` at build time.
84type PegFactory = Box<dyn Fn(&IdGen) -> Peg>;
85
86/// Value-production overrides for payload fields whose Rust type has no
87/// built-in canonical-syntax mapping (see the module docs).
88///
89/// Two granularities, resolved most-specific-first:
90///
91/// 1. **Per field** ([`Self::for_field`]) — pinned to one
92///    `(variant, field)` site.
93/// 2. **Per type** ([`Self::for_type`]) — keyed by the field's Rust
94///    type source text; whitespace is ignored, so
95///    `"Option<JoinPolicy>"` matches the derive-extracted
96///    `"Option < JoinPolicy >"` spelling.
97///
98/// A field with neither entry falls back to the built-in mapping, and
99/// failing that still fails generation loudly with
100/// [`codes::UNSUPPORTED_FIELD`].
101///
102/// The factory builds only the **value** production; the enclosing
103/// `name ':' <value>` argument shape (and the `Field` sink binding the
104/// matched text to the field name) stays canonical, which keeps the
105/// generated grammar's `GrammarCheck` guarantees intact.
106#[derive(Default)]
107pub struct SyntaxOverrides {
108    by_type: HashMap<String, PegFactory>,
109    by_field: HashMap<(String, String), PegFactory>,
110}
111
112impl SyntaxOverrides {
113    /// An empty override set (equivalent to the built-in mapping only).
114    pub fn new() -> Self {
115        Self::default()
116    }
117
118    /// Registers a value production for every payload field of Rust
119    /// type `ty` (source-text comparison, whitespace-insensitive).
120    pub fn for_type(
121        mut self,
122        ty: impl AsRef<str>,
123        value: impl Fn(&IdGen) -> Peg + 'static,
124    ) -> Self {
125        self.by_type.insert(strip_ws(ty.as_ref()), Box::new(value));
126        self
127    }
128
129    /// Registers a value production for the single field `field` of
130    /// variant `variant`, winning over any [`Self::for_type`] entry.
131    pub fn for_field(
132        mut self,
133        variant: impl Into<String>,
134        field: impl Into<String>,
135        value: impl Fn(&IdGen) -> Peg + 'static,
136    ) -> Self {
137        self.by_field
138            .insert((variant.into(), field.into()), Box::new(value));
139        self
140    }
141
142    /// Most-specific matching factory for `field` of `variant`, if any.
143    fn resolve(&self, variant: &str, field: &FieldSchema) -> Option<&PegFactory> {
144        self.by_field
145            .get(&(variant.to_string(), field.name.clone()))
146            .or_else(|| self.by_type.get(&strip_ws(&field.ty)))
147    }
148}
149
150/// Whitespace-insensitive type key: `Option < JoinPolicy >` (the
151/// token-stream spelling `#[derive(DslSchema)]` extracts) and
152/// `Option<JoinPolicy>` (what an author writes) must compare equal.
153fn strip_ws(ty: &str) -> String {
154    ty.chars().filter(|c| !c.is_whitespace()).collect()
155}
156
157impl Grammar {
158    /// Generates the canonical-syntax grammar for `schema`. See
159    /// [`grammar_from_schema`].
160    pub fn from_schema(schema: &NodeSchema, ids: &IdGen) -> Result<Grammar, BuildError> {
161        grammar_from_schema(schema, ids)
162    }
163}
164
165/// Generates a [`Grammar`] for the canonical named-argument syntax of
166/// `schema` (see the module docs for the syntax), built-in field
167/// mapping only.
168///
169/// Fails with one [`codes::UNSUPPORTED_FIELD`] diagnostic per
170/// unmappable payload field (collected across all variants, so the
171/// author sees the full list at once). To map such fields instead of
172/// failing, use [`grammar_from_schema_with`].
173pub fn grammar_from_schema(schema: &NodeSchema, ids: &IdGen) -> Result<Grammar, BuildError> {
174    grammar_from_schema_with(schema, ids, &SyntaxOverrides::default())
175}
176
177/// [`grammar_from_schema`] with [`SyntaxOverrides`] consulted before
178/// the built-in field mapping (per-field entries win over per-type
179/// entries win over built-ins).
180pub fn grammar_from_schema_with(
181    schema: &NodeSchema,
182    ids: &IdGen,
183    overrides: &SyntaxOverrides,
184) -> Result<Grammar, BuildError> {
185    if schema.variants.is_empty() {
186        return Err(BuildError::single(Diagnostic::error(
187            codes::EMPTY_SCHEMA,
188            format!("schema `{}` declares no variants", schema.name),
189        )));
190    }
191
192    let mut bad_fields = Vec::new();
193    for v in &schema.variants {
194        for f in &v.fields {
195            if resolved_field_value_peg(&v.name, f, ids, overrides).is_none() {
196                bad_fields.push(Diagnostic::error(
197                    codes::UNSUPPORTED_FIELD,
198                    format!(
199                        "variant `{}` field `{}`: type `{}` has no canonical-syntax \
200                         mapping (supported: String, bool, the integer types; or \
201                         register a `SyntaxOverrides` value production)",
202                        v.name, f.name, f.ty
203                    ),
204                ));
205            }
206        }
207    }
208    if !bad_fields.is_empty() {
209        return Err(BuildError::new(bad_fields));
210    }
211
212    let mut rules = Vec::with_capacity(schema.variants.len() + 1);
213    rules.push(rule(
214        ids,
215        START_RULE,
216        choice(
217            ids,
218            schema
219                .variants
220                .iter()
221                .map(|v| rule_ref(ids, v.name.clone()))
222                .collect(),
223        ),
224    ));
225    for v in &schema.variants {
226        rules.push(variant_rule(v, ids, overrides));
227    }
228    Ok(Grammar::new(rules, START_RULE))
229}
230
231/// Builds the rule for one variant. Two shapes:
232///
233/// - **Strict-order** (default, variant has no optional fields):
234///   `%kw:V "(" arg ("," arg)* ")"` with arguments emitted in schema
235///   order (fields, then children). Preserves the pre-0.3 canonical
236///   spelling for variants that never omit.
237/// - **Free-order** (variant has ≥ 1 optional field): `%kw:V "(" (arg
238///   ("," arg)*)? ")"` where each arg is `arg_1 | arg_2 | ...` and
239///   every alternative carries its own `%kw:name` prefix. Args are
240///   distinguishable by that name-keyword, so the DSL author may
241///   omit any subset of optional arguments (or even all of them),
242///   and `check_conformance` remains the authority on required /
243///   duplicate / unknown-slot diagnostics.
244fn variant_rule(v: &VariantSchema, ids: &IdGen, overrides: &SyntaxOverrides) -> Peg {
245    let has_optional = v.fields.iter().any(|f| f.optional);
246    let mut args: Vec<Peg> = Vec::new();
247    for f in &v.fields {
248        let value = resolved_field_value_peg(&v.name, f, ids, overrides)
249            .expect("unsupported field types were rejected before rule generation");
250        args.push(seq(
251            ids,
252            vec![
253                token(ids, format!("%kw:{}", f.name)),
254                token(ids, ":"),
255                field(ids, f.name.clone(), value),
256            ],
257        ));
258    }
259    for c in &v.children {
260        args.push(child_arg_peg(c, ids));
261    }
262
263    let mut items = vec![token(ids, format!("%kw:{}", v.name)), token(ids, "(")];
264    if has_optional && !args.is_empty() {
265        // Free-order: any of the argument shapes, comma-separated,
266        // whole list optional. Each argument-slot is a Field capture
267        // in its own right (built above), and the name-keyword prefix
268        // keeps the alternation unambiguous at the byte level.
269        let arg_choice = choice(ids, args);
270        // The tail repeats `("," arg_choice)`; we rebuild arg_choice
271        // per position so each Choice node gets a fresh id (Peg nodes
272        // are id-unique in a grammar).
273        let tail_alt = |ids: &IdGen| -> Peg {
274            let mut alts: Vec<Peg> = Vec::new();
275            for f in &v.fields {
276                let value = resolved_field_value_peg(&v.name, f, ids, overrides)
277                    .expect("unsupported field types were rejected before rule generation");
278                alts.push(seq(
279                    ids,
280                    vec![
281                        token(ids, format!("%kw:{}", f.name)),
282                        token(ids, ":"),
283                        field(ids, f.name.clone(), value),
284                    ],
285                ));
286            }
287            for c in &v.children {
288                alts.push(child_arg_peg(c, ids));
289            }
290            choice(ids, alts)
291        };
292        let tail = repeat(ids, seq(ids, vec![token(ids, ","), tail_alt(ids)]), 0, None);
293        let full = seq(ids, vec![arg_choice, tail]);
294        items.push(repeat(ids, full, 0, Some(1)));
295    } else {
296        for (i, arg) in args.into_iter().enumerate() {
297            if i > 0 {
298                items.push(token(ids, ","));
299            }
300            items.push(arg);
301        }
302    }
303    items.push(token(ids, ")"));
304
305    rule(
306        ids,
307        v.name.clone(),
308        node(ids, v.name.clone(), seq(ids, items)),
309    )
310}
311
312/// Value production for a payload field: the most specific
313/// [`SyntaxOverrides`] entry if registered, else the built-in mapping.
314fn resolved_field_value_peg(
315    variant: &str,
316    f: &FieldSchema,
317    ids: &IdGen,
318    overrides: &SyntaxOverrides,
319) -> Option<Peg> {
320    match overrides.resolve(variant, f) {
321        Some(factory) => Some(factory(ids)),
322        None => field_value_peg(f, ids),
323    }
324}
325
326/// Built-in value production for a payload field, by Rust type source
327/// text. `None` when the type has no canonical-syntax mapping.
328///
329/// Recognised (whitespace-insensitive on the type-source spelling):
330///
331/// - `String` → `%str`
332/// - the integer types → `%int`
333/// - `bool` → `true` / `false`
334/// - `Option<String>` → `none` | `%str`
335/// - `Vec<String>` → `[ %str ("," %str)* ]`, empty list allowed
336///
337/// The last two entries realise Layer 2 of the "built-in optional
338/// payload fields" contract — downstream DSLs no longer need to
339/// register a [`SyntaxOverrides`] entry (nor a paired
340/// `#[dsl_build(with = ...)]` converter) for these shapes.
341fn field_value_peg(f: &FieldSchema, ids: &IdGen) -> Option<Peg> {
342    const INT_TYPES: &[&str] = &[
343        "i8", "i16", "i32", "i64", "i128", "u8", "u16", "u32", "u64", "u128", "usize", "isize",
344    ];
345    let ty = strip_ws(&f.ty);
346    if ty == "String" {
347        Some(token(ids, "%str"))
348    } else if INT_TYPES.contains(&ty.as_str()) {
349        Some(token(ids, "%int"))
350    } else if ty == "bool" {
351        Some(choice(
352            ids,
353            vec![token(ids, "%kw:true"), token(ids, "%kw:false")],
354        ))
355    } else if ty == "Option<String>" {
356        // Canonical spelling of an absent Option-payload; mirrors the
357        // `Multiplicity::Optional` child idiom.
358        Some(choice(
359            ids,
360            vec![token(ids, "%kw:none"), token(ids, "%str")],
361        ))
362    } else if ty == "Vec<String>" {
363        // `[ %str_raw ("," %str_raw)* ]` with empty list allowed.
364        // `%str_raw` (peg-level primitive) contributes the raw
365        // source slice for each element — quotes and escapes intact —
366        // so the joined field text is a JSON-compatible array literal
367        // that `build_field_vec` can hand straight to
368        // `serde_json::from_str`.
369        let elems = seq(
370            ids,
371            vec![
372                token(ids, "%str_raw"),
373                repeat(
374                    ids,
375                    seq(ids, vec![token(ids, ","), token(ids, "%str_raw")]),
376                    0,
377                    None,
378                ),
379            ],
380        );
381        Some(seq(
382            ids,
383            vec![
384                token(ids, "["),
385                repeat(ids, elems, 0, Some(1)),
386                token(ids, "]"),
387            ],
388        ))
389    } else {
390        None
391    }
392}
393
394/// Argument production for one child slot, by multiplicity.
395fn child_arg_peg(c: &ChildSchema, ids: &IdGen) -> Peg {
396    let name_kw = token(ids, format!("%kw:{}", c.name));
397    let colon = token(ids, ":");
398    match c.multiplicity {
399        Multiplicity::One => seq(
400            ids,
401            vec![
402                name_kw,
403                colon,
404                field(ids, c.name.clone(), rule_ref(ids, START_RULE)),
405            ],
406        ),
407        // `name: <node>` or `name: none`. The Field arm is tried first,
408        // so a variant literally named `none` still wins when followed
409        // by `(`. The bare-`none` arm sits *outside* any Field: its
410        // matched text lands on the enclosing Node sink where it is
411        // dropped as syntactic noise, leaving the slot absent.
412        Multiplicity::Optional => seq(
413            ids,
414            vec![
415                name_kw,
416                colon,
417                choice(
418                    ids,
419                    vec![
420                        field(ids, c.name.clone(), rule_ref(ids, START_RULE)),
421                        token(ids, "%kw:none"),
422                    ],
423                ),
424            ],
425        ),
426        // `name: [ <node> ("," <node>)* ]`, empty list allowed. The
427        // list commas live inside the Field body; the mixed-field
428        // "trees win" fallback drops them as noise.
429        Multiplicity::Many => {
430            let elems = seq(
431                ids,
432                vec![
433                    rule_ref(ids, START_RULE),
434                    repeat(
435                        ids,
436                        seq(ids, vec![token(ids, ","), rule_ref(ids, START_RULE)]),
437                        0,
438                        None,
439                    ),
440                ],
441            );
442            seq(
443                ids,
444                vec![
445                    name_kw,
446                    colon,
447                    token(ids, "["),
448                    field(ids, c.name.clone(), repeat(ids, elems, 0, Some(1))),
449                    token(ids, "]"),
450                ],
451            )
452        }
453    }
454}
455
456/// Convenience: generate and immediately assert the grammar is clean
457/// under `GrammarCheck` (left recursion, nullable repeats, schema
458/// consistency). Intended for tests and one-shot setup paths; returns
459/// the same grammar as [`grammar_from_schema`].
460pub fn checked_grammar_from_schema(
461    schema: &NodeSchema,
462    ids: &IdGen,
463) -> Result<Grammar, BuildError> {
464    checked_grammar_from_schema_with(schema, ids, &SyntaxOverrides::default())
465}
466
467/// [`checked_grammar_from_schema`] with [`SyntaxOverrides`] consulted
468/// before the built-in field mapping.
469pub fn checked_grammar_from_schema_with(
470    schema: &NodeSchema,
471    ids: &IdGen,
472    overrides: &SyntaxOverrides,
473) -> Result<Grammar, BuildError> {
474    let grammar = grammar_from_schema_with(schema, ids, overrides)?;
475    let mut diags = grammar_check::check_left_recursion(&grammar);
476    diags.extend(grammar_check::check_nullable_repeat(&grammar));
477    diags.extend(
478        grammar_check::check_schema_consistency(&grammar, schema)
479            .into_iter()
480            .filter(|d| d.severity == crate::Severity::Error),
481    );
482    if diags.is_empty() {
483        Ok(grammar)
484    } else {
485        Err(BuildError::new(diags))
486    }
487}
488
489#[cfg(test)]
490mod tests {
491    use super::*;
492    use crate::{RawValue, check_conformance};
493
494    /// Expr-flavoured schema exercising every supported shape: int /
495    /// string / bool fields, One / Optional / Many children, and a
496    /// zero-argument variant.
497    fn demo_schema() -> NodeSchema {
498        NodeSchema {
499            name: "Expr".into(),
500            variants: vec![
501                VariantSchema {
502                    name: "Lit".into(),
503                    fields: vec![FieldSchema {
504                        name: "value".into(),
505                        ty: "i64".into(),
506                        optional: false,
507                    }],
508                    children: vec![],
509                },
510                VariantSchema {
511                    name: "Name".into(),
512                    fields: vec![
513                        FieldSchema {
514                            name: "text".into(),
515                            ty: "String".into(),
516                            optional: false,
517                        },
518                        FieldSchema {
519                            name: "quoted".into(),
520                            ty: "bool".into(),
521                            optional: false,
522                        },
523                    ],
524                    children: vec![],
525                },
526                VariantSchema {
527                    name: "Add".into(),
528                    fields: vec![],
529                    children: vec![
530                        ChildSchema {
531                            name: "lhs".into(),
532                            multiplicity: Multiplicity::One,
533                        },
534                        ChildSchema {
535                            name: "rhs".into(),
536                            multiplicity: Multiplicity::One,
537                        },
538                    ],
539                },
540                VariantSchema {
541                    name: "Neg".into(),
542                    fields: vec![],
543                    children: vec![ChildSchema {
544                        name: "body".into(),
545                        multiplicity: Multiplicity::Optional,
546                    }],
547                },
548                VariantSchema {
549                    name: "List".into(),
550                    fields: vec![],
551                    children: vec![ChildSchema {
552                        name: "items".into(),
553                        multiplicity: Multiplicity::Many,
554                    }],
555                },
556                VariantSchema {
557                    name: "Unit".into(),
558                    fields: vec![],
559                    children: vec![],
560                },
561            ],
562        }
563    }
564
565    fn demo_grammar() -> Grammar {
566        checked_grammar_from_schema(&demo_schema(), &IdGen::new())
567            .expect("demo schema generates a clean grammar")
568    }
569
570    /// Parse + conformance-check against the demo schema in one go.
571    fn parse_ok(input: &str) -> crate::ParseTree {
572        let g = demo_grammar();
573        let tree = g
574            .parse(input)
575            .unwrap_or_else(|e| panic!("parse failed for {input:?}: {:?}", e.diagnostics));
576        let diags = check_conformance(&tree, &demo_schema());
577        assert!(
578            diags.is_empty(),
579            "conformance clean for {input:?}: {diags:?}"
580        );
581        tree
582    }
583
584    #[test]
585    fn generated_grammar_passes_all_static_checks() {
586        // checked_grammar_from_schema already runs the three checks;
587        // this test pins that it succeeds for the full shape matrix.
588        demo_grammar();
589    }
590
591    #[test]
592    fn parses_int_field_variant() {
593        let tree = parse_ok("Lit(value: -42)");
594        assert_eq!(tree.variant, "Lit");
595        assert_eq!(tree.field("value"), Some(&RawValue::Text("-42".into())));
596    }
597
598    #[test]
599    fn parses_string_and_bool_fields_with_escapes() {
600        let tree = parse_ok(r#"Name(text: "hello \"world\"\n", quoted: true)"#);
601        assert_eq!(
602            tree.field("text"),
603            Some(&RawValue::Text("hello \"world\"\n".into()))
604        );
605        assert_eq!(tree.field("quoted"), Some(&RawValue::Text("true".into())));
606    }
607
608    #[test]
609    fn parses_nested_one_children() {
610        let tree = parse_ok("Add(lhs: Lit(value: 1), rhs: Neg(body: none))");
611        let lhs = tree.child_slot("lhs").unwrap();
612        assert_eq!(lhs.len(), 1);
613        assert_eq!(lhs[0].variant, "Lit");
614        let rhs = tree.child_slot("rhs").unwrap();
615        assert_eq!(rhs[0].variant, "Neg");
616    }
617
618    #[test]
619    fn optional_child_none_leaves_slot_absent() {
620        let tree = parse_ok("Neg(body: none)");
621        assert!(
622            tree.child_slot("body").is_none(),
623            "bare `none` = absent slot"
624        );
625    }
626
627    #[test]
628    fn optional_child_present_binds_one_tree() {
629        let tree = parse_ok("Neg(body: Lit(value: 3))");
630        assert_eq!(tree.child_slot("body").unwrap().len(), 1);
631    }
632
633    #[test]
634    fn many_child_list_binds_in_order_and_drops_commas() {
635        let tree = parse_ok("List(items: [Lit(value: 1), Lit(value: 2), Unit()])");
636        let items = tree.child_slot("items").unwrap();
637        let variants: Vec<&str> = items.iter().map(|t| t.variant.as_str()).collect();
638        assert_eq!(variants, ["Lit", "Lit", "Unit"]);
639    }
640
641    #[test]
642    fn many_child_empty_list_is_conformant() {
643        let tree = parse_ok("List(items: [])");
644        assert!(
645            tree.child_slot("items").is_none_or(<[_]>::is_empty),
646            "empty list = zero children"
647        );
648    }
649
650    #[test]
651    fn zero_argument_variant_parses() {
652        let tree = parse_ok("Unit()");
653        assert_eq!(tree.variant, "Unit");
654        assert!(tree.fields.is_empty() && tree.children.is_empty());
655    }
656
657    #[test]
658    fn whitespace_and_newlines_are_tolerated() {
659        let tree = parse_ok("Add(\n  lhs: Lit( value : 7 ),\n  rhs: Unit()\n)");
660        assert_eq!(tree.child_slot("lhs").unwrap()[0].variant, "Lit");
661    }
662
663    #[test]
664    fn unsupported_field_type_fails_generation_with_full_list() {
665        let schema = NodeSchema {
666            name: "Bad".into(),
667            variants: vec![VariantSchema {
668                name: "Par".into(),
669                fields: vec![
670                    FieldSchema {
671                        name: "policy".into(),
672                        ty: "Option<JoinPolicy>".into(),
673                        optional: false,
674                    },
675                    FieldSchema {
676                        name: "reducer".into(),
677                        ty: "ReducerId".into(),
678                        optional: false,
679                    },
680                ],
681                children: vec![],
682            }],
683        };
684        let err = grammar_from_schema(&schema, &IdGen::new()).unwrap_err();
685        assert_eq!(err.diagnostics.len(), 2, "one diagnostic per bad field");
686        assert!(
687            err.diagnostics
688                .iter()
689                .all(|d| d.code == codes::UNSUPPORTED_FIELD)
690        );
691    }
692
693    /// Flow-shaped schema whose `Par` payload fields the built-in
694    /// mapping rejects — the override motivating case.
695    fn par_schema() -> NodeSchema {
696        NodeSchema {
697            name: "Flow".into(),
698            variants: vec![
699                VariantSchema {
700                    name: "Par".into(),
701                    fields: vec![
702                        FieldSchema {
703                            name: "policy".into(),
704                            // Token-stream spelling, as the derive extracts it.
705                            ty: "Option < JoinPolicy >".into(),
706                            optional: false,
707                        },
708                        FieldSchema {
709                            name: "reducer_id".into(),
710                            ty: "Option < String >".into(),
711                            optional: false,
712                        },
713                    ],
714                    children: vec![ChildSchema {
715                        name: "children".into(),
716                        multiplicity: Multiplicity::Many,
717                    }],
718                },
719                VariantSchema {
720                    name: "Call".into(),
721                    fields: vec![FieldSchema {
722                        name: "label".into(),
723                        ty: "String".into(),
724                        optional: false,
725                    }],
726                    children: vec![],
727                },
728            ],
729        }
730    }
731
732    fn par_overrides() -> SyntaxOverrides {
733        SyntaxOverrides::new()
734            .for_type("Option<JoinPolicy>", |ids| {
735                choice(
736                    ids,
737                    vec![
738                        token(ids, "%kw:none"),
739                        token(ids, "%kw:all_failfast"),
740                        token(ids, "%kw:any_failfast"),
741                    ],
742                )
743            })
744            .for_type("Option<String>", |ids| {
745                choice(ids, vec![token(ids, "%kw:none"), token(ids, "%str")])
746            })
747    }
748
749    #[test]
750    fn type_overrides_unlock_exotic_payload_fields() {
751        // Without overrides the Flow-shaped schema fails generation
752        // (pinned by unsupported_field_type_fails_generation_with_full_list);
753        // with them it generates check-clean and parses. Note the
754        // override keys are written without whitespace while the schema
755        // carries the token-stream spelling.
756        let g = checked_grammar_from_schema_with(&par_schema(), &IdGen::new(), &par_overrides())
757            .expect("overridden Flow schema generates a clean grammar");
758        let tree = g
759            .parse(
760                r#"Par(policy: all_failfast, reducer_id: "reduce_all_ordered",
761                     children: [Call(label: "a"), Call(label: "b")])"#,
762            )
763            .expect("canonical Par text parses");
764        let diags = check_conformance(&tree, &par_schema());
765        assert!(diags.is_empty(), "conformance clean: {diags:?}");
766        assert_eq!(
767            tree.field("policy"),
768            Some(&RawValue::Text("all_failfast".into()))
769        );
770        assert_eq!(
771            tree.field("reducer_id"),
772            Some(&RawValue::Text("reduce_all_ordered".into()))
773        );
774        assert_eq!(tree.child_slot("children").unwrap().len(), 2);
775    }
776
777    #[test]
778    fn field_override_wins_over_type_override() {
779        // Same type in both entries; the (variant, field)-pinned one
780        // must decide the syntax.
781        let overrides = par_overrides().for_field("Par", "policy", |ids| token(ids, "%kw:pinned"));
782        let g = checked_grammar_from_schema_with(&par_schema(), &IdGen::new(), &overrides)
783            .expect("clean grammar with field-level override");
784        let tree = g
785            .parse(r#"Par(policy: pinned, reducer_id: none, children: [])"#)
786            .expect("field-level syntax parses");
787        assert_eq!(tree.field("policy"), Some(&RawValue::Text("pinned".into())));
788        // The type-level spelling is no longer accepted at that site.
789        assert!(
790            g.parse(r#"Par(policy: all_failfast, reducer_id: none, children: [])"#)
791                .is_err(),
792            "type-level syntax rejected once the field is pinned"
793        );
794    }
795
796    #[test]
797    fn unrelated_override_leaves_builtin_mapping_and_failure_intact() {
798        // An override for some other type neither rescues the
799        // unsupported fields nor perturbs built-in ones. Note that
800        // `Option<String>` on `reducer_id` is now a built-in mapping
801        // (Layer 2 of the "built-in optional payload fields"
802        // contract), so only the `Option<JoinPolicy>` field on
803        // `policy` remains unmapped without a `SyntaxOverrides` entry.
804        let overrides = SyntaxOverrides::new().for_type("Uuid", |ids| token(ids, "%str"));
805        let err = grammar_from_schema_with(&par_schema(), &IdGen::new(), &overrides).unwrap_err();
806        assert_eq!(
807            err.diagnostics.len(),
808            1,
809            "policy is the only Par field still unmapped without overrides",
810        );
811        assert!(
812            err.diagnostics
813                .iter()
814                .all(|d| d.code == codes::UNSUPPORTED_FIELD)
815        );
816        assert!(
817            err.diagnostics[0].message.contains("policy"),
818            "unmapped-field diagnostic points at `policy`",
819        );
820        // Built-in demo schema is unaffected by the stray entry.
821        let g = checked_grammar_from_schema_with(&demo_schema(), &IdGen::new(), &overrides)
822            .expect("demo schema still generates");
823        assert_eq!(g.parse("Lit(value: 7)").unwrap().variant, "Lit");
824    }
825
826    /// Layer 2: `Option<String>` payload maps to `none | %str` via the
827    /// built-in mapping (no `SyntaxOverrides` entry needed). Canonical
828    /// text parses both spellings and both build through the derive's
829    /// `build_field_optional` route.
830    #[test]
831    fn builtin_option_string_mapping_accepts_none_and_str() {
832        let schema = NodeSchema {
833            name: "Meta".into(),
834            variants: vec![VariantSchema {
835                name: "Row".into(),
836                fields: vec![FieldSchema {
837                    name: "description".into(),
838                    ty: "Option<String>".into(),
839                    optional: true,
840                }],
841                children: vec![],
842            }],
843        };
844        let g = checked_grammar_from_schema(&schema, &IdGen::new())
845            .expect("Option<String> is a built-in mapping");
846        // `none` spelling.
847        let t1 = g.parse(r#"Row(description: none)"#).expect("none parses");
848        assert_eq!(
849            t1.field("description"),
850            Some(&RawValue::Text("none".into())),
851        );
852        // `%str` spelling.
853        let t2 = g.parse(r#"Row(description: "hi")"#).expect("string parses");
854        assert_eq!(t2.field("description"), Some(&RawValue::Text("hi".into())));
855        // Omitted entirely (Layer 1 optional PEG wrap).
856        let t3 = g.parse(r#"Row()"#).expect("omitted parses");
857        assert!(t3.field("description").is_none());
858        // check_conformance is clean for all three.
859        for t in [&t1, &t2, &t3] {
860            assert!(
861                check_conformance(t, &schema).is_empty(),
862                "conformance clean for {t:?}",
863            );
864        }
865    }
866
867    /// Layer 2: `Vec<String>` payload maps to `[ %str ("," %str)* ]`
868    /// via the built-in mapping. Empty list, single item, and multi
869    /// item all parse; captured text is JSON-parsable so
870    /// `build_field_vec` reads it directly.
871    #[test]
872    fn builtin_vec_string_mapping_accepts_bracketed_list() {
873        let schema = NodeSchema {
874            name: "Meta".into(),
875            variants: vec![VariantSchema {
876                name: "Row".into(),
877                fields: vec![FieldSchema {
878                    name: "tags".into(),
879                    ty: "Vec<String>".into(),
880                    optional: true,
881                }],
882                children: vec![],
883            }],
884        };
885        let g = checked_grammar_from_schema(&schema, &IdGen::new())
886            .expect("Vec<String> is a built-in mapping");
887        // Empty list.
888        let t1 = g.parse(r#"Row(tags: [])"#).expect("empty list parses");
889        assert_eq!(t1.field("tags"), Some(&RawValue::Text("[]".into())));
890        // Multi item. The PEG runtime's implicit whitespace-skip
891        // strips inter-token spaces from the captured text, so the
892        // field carries the compact form `["a","b"]` (still valid
893        // JSON — `serde_json::from_str` accepts it).
894        let t2 = g
895            .parse(r#"Row(tags: ["a", "b"])"#)
896            .expect("two items parses");
897        assert_eq!(
898            t2.field("tags"),
899            Some(&RawValue::Text(r#"["a","b"]"#.into())),
900        );
901        // Omitted.
902        let t3 = g.parse(r#"Row()"#).expect("omitted parses");
903        assert!(t3.field("tags").is_none());
904        for t in [&t1, &t2, &t3] {
905            assert!(
906                check_conformance(t, &schema).is_empty(),
907                "conformance clean for {t:?}",
908            );
909        }
910    }
911
912    #[test]
913    fn empty_schema_fails_generation() {
914        let schema = NodeSchema {
915            name: "Void".into(),
916            variants: vec![],
917        };
918        let err = grammar_from_schema(&schema, &IdGen::new()).unwrap_err();
919        assert_eq!(err.diagnostics[0].code, codes::EMPTY_SCHEMA);
920    }
921
922    #[test]
923    fn parse_error_reports_expected_set() {
924        let g = demo_grammar();
925        let err = g.parse("Lit(value: banana)").unwrap_err();
926        assert!(!err.diagnostics.is_empty());
927    }
928}