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::{ChildSchema, FieldSchema, Multiplicity, NodeSchema, VariantSchema};
78
79/// Diagnostic codes emitted by grammar generation.
80pub mod codes {
81    /// A payload field's Rust type has no canonical-syntax mapping.
82    pub const UNSUPPORTED_FIELD: &str = "dsl_kit::schema_gen::unsupported_field";
83    /// The schema declares no variants — there is nothing to parse.
84    pub const EMPTY_SCHEMA: &str = "dsl_kit::schema_gen::empty_schema";
85    /// A child slot's multiplicity is a variant this build of
86    /// `dsl-kit-parse` does not recognise (added to the schema crate's
87    /// `#[non_exhaustive]` enum ahead of parse-side support). Emitted
88    /// by the pre-flight check in
89    /// [`grammar_from_schema_with`] so `child_arg_peg` never sees an
90    /// unknown variant.
91    pub const UNKNOWN_MULTIPLICITY: &str = "dsl_kit::schema_gen::unknown_multiplicity";
92}
93
94/// Name of the generated start rule.
95pub const START_RULE: &str = "node";
96
97/// A deferred value-production constructor: overrides are registered
98/// before the [`IdGen`] doing the generation exists, so each entry is a
99/// factory invoked with the generator's `ids` at build time.
100type PegFactory = Box<dyn Fn(&IdGen) -> Peg>;
101
102/// Value-production overrides for payload fields whose Rust type has no
103/// built-in canonical-syntax mapping (see the module docs).
104///
105/// Two granularities, resolved most-specific-first:
106///
107/// 1. **Per field** ([`Self::for_field`]) — pinned to one
108///    `(variant, field)` site.
109/// 2. **Per type** ([`Self::for_type`]) — keyed by the field's Rust
110///    type source text; whitespace is ignored, so
111///    `"Option<JoinPolicy>"` matches the derive-extracted
112///    `"Option < JoinPolicy >"` spelling.
113///
114/// A field with neither entry falls back to the built-in mapping, and
115/// failing that still fails generation loudly with
116/// [`codes::UNSUPPORTED_FIELD`].
117///
118/// The factory builds only the **value** production; the enclosing
119/// `name ':' <value>` argument shape (and the `Field` sink binding the
120/// matched text to the field name) stays canonical, which keeps the
121/// generated grammar's `GrammarCheck` guarantees intact.
122#[derive(Default)]
123pub struct SyntaxOverrides {
124    by_type: HashMap<String, PegFactory>,
125    by_field: HashMap<(String, String), PegFactory>,
126}
127
128impl SyntaxOverrides {
129    /// An empty override set (equivalent to the built-in mapping only).
130    pub fn new() -> Self {
131        Self::default()
132    }
133
134    /// Registers a value production for every payload field of Rust
135    /// type `ty` (source-text comparison, whitespace-insensitive).
136    pub fn for_type(
137        mut self,
138        ty: impl AsRef<str>,
139        value: impl Fn(&IdGen) -> Peg + 'static,
140    ) -> Self {
141        self.by_type.insert(strip_ws(ty.as_ref()), Box::new(value));
142        self
143    }
144
145    /// Registers a value production for the single field `field` of
146    /// variant `variant`, winning over any [`Self::for_type`] entry.
147    pub fn for_field(
148        mut self,
149        variant: impl Into<String>,
150        field: impl Into<String>,
151        value: impl Fn(&IdGen) -> Peg + 'static,
152    ) -> Self {
153        self.by_field
154            .insert((variant.into(), field.into()), Box::new(value));
155        self
156    }
157
158    /// Most-specific matching factory for `field` of `variant`, if any.
159    fn resolve(&self, variant: &str, field: &FieldSchema) -> Option<&PegFactory> {
160        self.by_field
161            .get(&(variant.to_string(), field.name.clone()))
162            .or_else(|| self.by_type.get(&strip_ws(&field.ty)))
163    }
164}
165
166/// Whitespace-insensitive type key: `Option < JoinPolicy >` (the
167/// token-stream spelling `#[derive(DslSchema)]` extracts) and
168/// `Option<JoinPolicy>` (what an author writes) must compare equal.
169fn strip_ws(ty: &str) -> String {
170    ty.chars().filter(|c| !c.is_whitespace()).collect()
171}
172
173impl Grammar {
174    /// Generates the canonical-syntax grammar for `schema`. See
175    /// [`grammar_from_schema`].
176    pub fn from_schema(schema: &NodeSchema, ids: &IdGen) -> Result<Grammar, BuildError> {
177        grammar_from_schema(schema, ids)
178    }
179}
180
181/// Generates a [`Grammar`] for the canonical named-argument syntax of
182/// `schema` (see the module docs for the syntax), built-in field
183/// mapping only.
184///
185/// Fails with one [`codes::UNSUPPORTED_FIELD`] diagnostic per
186/// unmappable payload field (collected across all variants, so the
187/// author sees the full list at once). To map such fields instead of
188/// failing, use [`grammar_from_schema_with`].
189pub fn grammar_from_schema(schema: &NodeSchema, ids: &IdGen) -> Result<Grammar, BuildError> {
190    grammar_from_schema_with(schema, ids, &SyntaxOverrides::default())
191}
192
193/// [`grammar_from_schema`] with [`SyntaxOverrides`] consulted before
194/// the built-in field mapping (per-field entries win over per-type
195/// entries win over built-ins).
196pub fn grammar_from_schema_with(
197    schema: &NodeSchema,
198    ids: &IdGen,
199    overrides: &SyntaxOverrides,
200) -> Result<Grammar, BuildError> {
201    if schema.variants.is_empty() {
202        return Err(BuildError::single(Diagnostic::error(
203            codes::EMPTY_SCHEMA,
204            format!("schema `{}` declares no variants", schema.name),
205        )));
206    }
207
208    // Pre-flight: collect every diagnostic that must block rule
209    // generation, then return in one shot. A single pass means an
210    // author with both a bad payload type and a `Multiplicity::Map`
211    // slot sees both errors on the first build instead of paying two
212    // edit-compile cycles for one report.
213    //
214    // Grouping:
215    //   - `UNSUPPORTED_FIELD` for payload types with no canonical-syntax
216    //     mapping (and no `SyntaxOverrides` entry).
217    //   - `UNKNOWN_MULTIPLICITY` for child slots whose multiplicity
218    //     this build does not know, which is what keeps
219    //     `child_arg_peg`'s catch-all arm from ever running.
220    let mut pre_flight = Vec::new();
221    for v in &schema.variants {
222        for f in &v.fields {
223            if resolved_field_value_peg(&v.name, f, ids, overrides).is_none() {
224                pre_flight.push(Diagnostic::error(
225                    codes::UNSUPPORTED_FIELD,
226                    format!(
227                        "variant `{}` field `{}`: type `{}` has no canonical-syntax \
228                         mapping (supported: String, bool, the integer types; or \
229                         register a `SyntaxOverrides` value production)",
230                        v.name, f.name, f.ty
231                    ),
232                ));
233            }
234        }
235        for c in &v.children {
236            match c.multiplicity {
237                // Every shape `child_arg_peg` knows how to emit.
238                Multiplicity::One
239                | Multiplicity::Optional
240                | Multiplicity::Many
241                | Multiplicity::Map => {}
242                // `#[non_exhaustive]` catch-all: a future Multiplicity
243                // variant added to dsl-kit-schema before this crate is
244                // updated must also be rejected here — that's what
245                // keeps `child_arg_peg`'s `_ => unreachable!()` arm
246                // honest.
247                _ => {
248                    pre_flight.push(Diagnostic::error(
249                        codes::UNKNOWN_MULTIPLICITY,
250                        format!(
251                            "variant `{}` child slot `{}`: unrecognised Multiplicity \
252                             variant (upgrade dsl-kit-parse to a version that knows about it)",
253                            v.name, c.name
254                        ),
255                    ));
256                }
257            }
258        }
259    }
260    if !pre_flight.is_empty() {
261        return Err(BuildError::new(pre_flight));
262    }
263
264    let mut rules = Vec::with_capacity(schema.variants.len() + 1);
265    rules.push(rule(
266        ids,
267        START_RULE,
268        choice(
269            ids,
270            schema
271                .variants
272                .iter()
273                .map(|v| rule_ref(ids, v.name.clone()))
274                .collect(),
275        ),
276    ));
277    for v in &schema.variants {
278        rules.push(variant_rule(v, ids, overrides));
279    }
280    Ok(Grammar::new(rules, START_RULE))
281}
282
283/// Builds the rule for one variant. Two shapes:
284///
285/// - **Strict-order** (default, variant has no optional fields):
286///   `%kw:V "(" arg ("," arg)* ")"` with arguments emitted in schema
287///   order (fields, then children). Preserves the pre-0.3 canonical
288///   spelling for variants that never omit.
289/// - **Free-order** (variant has ≥ 1 optional field): `%kw:V "(" (arg
290///   ("," arg)*)? ")"` where each arg is `arg_1 | arg_2 | ...` and
291///   every alternative carries its own `%kw:name` prefix. Args are
292///   distinguishable by that name-keyword, so the DSL author may
293///   omit any subset of optional arguments (or even all of them),
294///   and `check_conformance` remains the authority on required /
295///   duplicate / unknown-slot diagnostics.
296fn variant_rule(v: &VariantSchema, ids: &IdGen, overrides: &SyntaxOverrides) -> Peg {
297    let has_optional = v.fields.iter().any(|f| f.optional);
298    let mut args: Vec<Peg> = Vec::new();
299    for f in &v.fields {
300        let value = resolved_field_value_peg(&v.name, f, ids, overrides)
301            .expect("unsupported field types were rejected before rule generation");
302        args.push(seq(
303            ids,
304            vec![
305                token(ids, format!("%kw:{}", f.name)),
306                token(ids, ":"),
307                field(ids, f.name.clone(), value),
308            ],
309        ));
310    }
311    for c in &v.children {
312        args.push(child_arg_peg(c, ids));
313    }
314
315    let mut items = vec![token(ids, format!("%kw:{}", v.name)), token(ids, "(")];
316    if has_optional && !args.is_empty() {
317        // Free-order: any of the argument shapes, comma-separated,
318        // whole list optional. Each argument-slot is a Field capture
319        // in its own right (built above), and the name-keyword prefix
320        // keeps the alternation unambiguous at the byte level.
321        let arg_choice = choice(ids, args);
322        // The tail repeats `("," arg_choice)`; we rebuild arg_choice
323        // per position so each Choice node gets a fresh id (Peg nodes
324        // are id-unique in a grammar).
325        let tail_alt = |ids: &IdGen| -> Peg {
326            let mut alts: Vec<Peg> = Vec::new();
327            for f in &v.fields {
328                let value = resolved_field_value_peg(&v.name, f, ids, overrides)
329                    .expect("unsupported field types were rejected before rule generation");
330                alts.push(seq(
331                    ids,
332                    vec![
333                        token(ids, format!("%kw:{}", f.name)),
334                        token(ids, ":"),
335                        field(ids, f.name.clone(), value),
336                    ],
337                ));
338            }
339            for c in &v.children {
340                alts.push(child_arg_peg(c, ids));
341            }
342            choice(ids, alts)
343        };
344        let tail = repeat(ids, seq(ids, vec![token(ids, ","), tail_alt(ids)]), 0, None);
345        let full = seq(ids, vec![arg_choice, tail]);
346        items.push(repeat(ids, full, 0, Some(1)));
347    } else {
348        for (i, arg) in args.into_iter().enumerate() {
349            if i > 0 {
350                items.push(token(ids, ","));
351            }
352            items.push(arg);
353        }
354    }
355    items.push(token(ids, ")"));
356
357    rule(
358        ids,
359        v.name.clone(),
360        node(ids, v.name.clone(), seq(ids, items)),
361    )
362}
363
364/// Value production for a payload field: the most specific
365/// [`SyntaxOverrides`] entry if registered, else the built-in mapping.
366fn resolved_field_value_peg(
367    variant: &str,
368    f: &FieldSchema,
369    ids: &IdGen,
370    overrides: &SyntaxOverrides,
371) -> Option<Peg> {
372    match overrides.resolve(variant, f) {
373        Some(factory) => Some(factory(ids)),
374        None => field_value_peg(f, ids),
375    }
376}
377
378/// Built-in value production for a payload field, by Rust type source
379/// text. `None` when the type has no canonical-syntax mapping.
380///
381/// Recognised (whitespace-insensitive on the type-source spelling):
382///
383/// - `String` → `%str`
384/// - the integer types → `%int`
385/// - `bool` → `true` / `false`
386/// - `Option<String>` → `none` | `%str`
387/// - `Vec<String>` → `[ %str ("," %str)* ]`, empty list allowed
388///
389/// The last two entries realise Layer 2 of the "built-in optional
390/// payload fields" contract — downstream DSLs no longer need to
391/// register a [`SyntaxOverrides`] entry (nor a paired
392/// `#[dsl_build(with = ...)]` converter) for these shapes.
393fn field_value_peg(f: &FieldSchema, ids: &IdGen) -> Option<Peg> {
394    const INT_TYPES: &[&str] = &[
395        "i8", "i16", "i32", "i64", "i128", "u8", "u16", "u32", "u64", "u128", "usize", "isize",
396    ];
397    let ty = strip_ws(&f.ty);
398    if ty == "String" {
399        Some(token(ids, "%str"))
400    } else if INT_TYPES.contains(&ty.as_str()) {
401        Some(token(ids, "%int"))
402    } else if ty == "bool" {
403        Some(choice(
404            ids,
405            vec![token(ids, "%kw:true"), token(ids, "%kw:false")],
406        ))
407    } else if ty == "Option<String>" {
408        // Canonical spelling of an absent Option-payload; mirrors the
409        // `Multiplicity::Optional` child idiom.
410        Some(choice(
411            ids,
412            vec![token(ids, "%kw:none"), token(ids, "%str")],
413        ))
414    } else if ty == "Vec<String>" {
415        // `[ %str_raw ("," %str_raw)* ]` with empty list allowed.
416        // `%str_raw` (peg-level primitive) contributes the raw
417        // source slice for each element — quotes and escapes intact —
418        // so the joined field text is a JSON-compatible array literal
419        // that `build_field_vec` can hand straight to
420        // `serde_json::from_str`.
421        let elems = seq(
422            ids,
423            vec![
424                token(ids, "%str_raw"),
425                repeat(
426                    ids,
427                    seq(ids, vec![token(ids, ","), token(ids, "%str_raw")]),
428                    0,
429                    None,
430                ),
431            ],
432        );
433        Some(seq(
434            ids,
435            vec![
436                token(ids, "["),
437                repeat(ids, elems, 0, Some(1)),
438                token(ids, "]"),
439            ],
440        ))
441    } else {
442        None
443    }
444}
445
446/// Argument production for one child slot, by multiplicity.
447fn child_arg_peg(c: &ChildSchema, ids: &IdGen) -> Peg {
448    let name_kw = token(ids, format!("%kw:{}", c.name));
449    let colon = token(ids, ":");
450    match c.multiplicity {
451        Multiplicity::One => seq(
452            ids,
453            vec![
454                name_kw,
455                colon,
456                field(ids, c.name.clone(), rule_ref(ids, START_RULE)),
457            ],
458        ),
459        // `name: <node>` or `name: none`. The Field arm is tried first,
460        // so a variant literally named `none` still wins when followed
461        // by `(`. The bare-`none` arm sits *outside* any Field: its
462        // matched text lands on the enclosing Node sink where it is
463        // dropped as syntactic noise, leaving the slot absent.
464        Multiplicity::Optional => seq(
465            ids,
466            vec![
467                name_kw,
468                colon,
469                choice(
470                    ids,
471                    vec![
472                        field(ids, c.name.clone(), rule_ref(ids, START_RULE)),
473                        token(ids, "%kw:none"),
474                    ],
475                ),
476            ],
477        ),
478        // `name: [ <node> ("," <node>)* ]`, empty list allowed. The
479        // list commas live inside the Field body; the mixed-field
480        // "trees win" fallback drops them as noise.
481        Multiplicity::Many => {
482            let elems = seq(
483                ids,
484                vec![
485                    rule_ref(ids, START_RULE),
486                    repeat(
487                        ids,
488                        seq(ids, vec![token(ids, ","), rule_ref(ids, START_RULE)]),
489                        0,
490                        None,
491                    ),
492                ],
493            );
494            seq(
495                ids,
496                vec![
497                    name_kw,
498                    colon,
499                    token(ids, "["),
500                    field(ids, c.name.clone(), repeat(ids, elems, 0, Some(1))),
501                    token(ids, "]"),
502                ],
503            )
504        }
505        // `name: { <key>: <node> ("," <key>: <node>)* }`, empty map
506        // allowed. Braces rather than the `Many` idiom's brackets so
507        // the two shapes are distinguishable at a glance, and matching
508        // the JSON bridge's object spelling so a DSL reads the same
509        // way in both front-ends.
510        //
511        // The key token is `%str | %ident`: keys are arbitrary strings
512        // at the `ParseTree` level, so a quoted form has to exist, but
513        // requiring quotes around every `PATH`-style key would be
514        // noise. `%str` is tried first — a quoted key is unambiguous,
515        // while `%ident` cannot start with `"` — and its production is
516        // the decoded content, so `"a b"` and `a` both arrive as plain
517        // key text.
518        Multiplicity::Map => {
519            //
520            // The `:` separator rides on the *value* half, not the
521            // key half: every token matched inside the key production
522            // contributes to the key text, so a `:` there would land
523            // in the key itself. On the value side it is dropped as
524            // syntactic noise, the same way the `Many` list's commas
525            // are.
526            let entry = |ids: &IdGen| -> Peg {
527                keyed_entry(
528                    ids,
529                    c.name.clone(),
530                    choice(ids, vec![token(ids, "%str"), token(ids, "%ident")]),
531                    seq(ids, vec![token(ids, ":"), rule_ref(ids, START_RULE)]),
532                )
533            };
534            let entries = seq(
535                ids,
536                vec![
537                    entry(ids),
538                    repeat(ids, seq(ids, vec![token(ids, ","), entry(ids)]), 0, None),
539                ],
540            );
541            seq(
542                ids,
543                vec![
544                    name_kw,
545                    colon,
546                    token(ids, "{"),
547                    repeat(ids, entries, 0, Some(1)),
548                    token(ids, "}"),
549                ],
550            )
551        }
552        // `#[non_exhaustive]` catch-all: a future Multiplicity variant
553        // added to dsl-kit-schema before this crate is updated would
554        // land here. The pre-flight check in
555        // `grammar_from_schema_with` should be extended in lockstep to
556        // reject unknown variants; if that extension is missed the
557        // panic here surfaces the omission loudly instead of emitting
558        // a silently-wrong grammar rule.
559        _ => unreachable!(
560            "child_arg_peg encountered an unrecognised Multiplicity variant on slot \
561             `{}` — extend the pre-flight check in grammar_from_schema_with to reject it",
562            c.name
563        ),
564    }
565}
566
567/// Convenience: generate and immediately assert the grammar is clean
568/// under `GrammarCheck` (left recursion, nullable repeats, schema
569/// consistency). Intended for tests and one-shot setup paths; returns
570/// the same grammar as [`grammar_from_schema`].
571pub fn checked_grammar_from_schema(
572    schema: &NodeSchema,
573    ids: &IdGen,
574) -> Result<Grammar, BuildError> {
575    checked_grammar_from_schema_with(schema, ids, &SyntaxOverrides::default())
576}
577
578/// [`checked_grammar_from_schema`] with [`SyntaxOverrides`] consulted
579/// before the built-in field mapping.
580pub fn checked_grammar_from_schema_with(
581    schema: &NodeSchema,
582    ids: &IdGen,
583    overrides: &SyntaxOverrides,
584) -> Result<Grammar, BuildError> {
585    let grammar = grammar_from_schema_with(schema, ids, overrides)?;
586    let mut diags = grammar_check::check_left_recursion(&grammar);
587    diags.extend(grammar_check::check_nullable_repeat(&grammar));
588    diags.extend(
589        grammar_check::check_schema_consistency(&grammar, schema)
590            .into_iter()
591            .filter(|d| d.severity == crate::Severity::Error),
592    );
593    if diags.is_empty() {
594        Ok(grammar)
595    } else {
596        Err(BuildError::new(diags))
597    }
598}
599
600#[cfg(test)]
601mod tests {
602    use super::*;
603    use crate::{RawValue, check_conformance};
604
605    /// Expr-flavoured schema exercising every supported shape: int /
606    /// string / bool fields, One / Optional / Many children, and a
607    /// zero-argument variant.
608    fn demo_schema() -> NodeSchema {
609        NodeSchema {
610            name: "Expr".into(),
611            variants: vec![
612                VariantSchema {
613                    name: "Lit".into(),
614                    fields: vec![FieldSchema {
615                        name: "value".into(),
616                        ty: "i64".into(),
617                        optional: false,
618                    }],
619                    children: vec![],
620                },
621                VariantSchema {
622                    name: "Name".into(),
623                    fields: vec![
624                        FieldSchema {
625                            name: "text".into(),
626                            ty: "String".into(),
627                            optional: false,
628                        },
629                        FieldSchema {
630                            name: "quoted".into(),
631                            ty: "bool".into(),
632                            optional: false,
633                        },
634                    ],
635                    children: vec![],
636                },
637                VariantSchema {
638                    name: "Add".into(),
639                    fields: vec![],
640                    children: vec![
641                        ChildSchema {
642                            name: "lhs".into(),
643                            multiplicity: Multiplicity::One,
644                        },
645                        ChildSchema {
646                            name: "rhs".into(),
647                            multiplicity: Multiplicity::One,
648                        },
649                    ],
650                },
651                VariantSchema {
652                    name: "Neg".into(),
653                    fields: vec![],
654                    children: vec![ChildSchema {
655                        name: "body".into(),
656                        multiplicity: Multiplicity::Optional,
657                    }],
658                },
659                VariantSchema {
660                    name: "List".into(),
661                    fields: vec![],
662                    children: vec![ChildSchema {
663                        name: "items".into(),
664                        multiplicity: Multiplicity::Many,
665                    }],
666                },
667                VariantSchema {
668                    name: "Env".into(),
669                    fields: vec![],
670                    children: vec![ChildSchema {
671                        name: "entries".into(),
672                        multiplicity: Multiplicity::Map,
673                    }],
674                },
675                VariantSchema {
676                    name: "Unit".into(),
677                    fields: vec![],
678                    children: vec![],
679                },
680            ],
681        }
682    }
683
684    fn demo_grammar() -> Grammar {
685        checked_grammar_from_schema(&demo_schema(), &IdGen::new())
686            .expect("demo schema generates a clean grammar")
687    }
688
689    /// Parse + conformance-check against the demo schema in one go.
690    fn parse_ok(input: &str) -> crate::ParseTree {
691        let g = demo_grammar();
692        let tree = g
693            .parse(input)
694            .unwrap_or_else(|e| panic!("parse failed for {input:?}: {:?}", e.diagnostics));
695        let diags = check_conformance(&tree, &demo_schema());
696        assert!(
697            diags.is_empty(),
698            "conformance clean for {input:?}: {diags:?}"
699        );
700        tree
701    }
702
703    #[test]
704    fn generated_grammar_passes_all_static_checks() {
705        // checked_grammar_from_schema already runs the three checks;
706        // this test pins that it succeeds for the full shape matrix.
707        demo_grammar();
708    }
709
710    #[test]
711    fn parses_int_field_variant() {
712        let tree = parse_ok("Lit(value: -42)");
713        assert_eq!(tree.variant, "Lit");
714        assert_eq!(tree.field("value"), Some(&RawValue::Text("-42".into())));
715    }
716
717    #[test]
718    fn parses_string_and_bool_fields_with_escapes() {
719        let tree = parse_ok(r#"Name(text: "hello \"world\"\n", quoted: true)"#);
720        assert_eq!(
721            tree.field("text"),
722            Some(&RawValue::Text("hello \"world\"\n".into()))
723        );
724        assert_eq!(tree.field("quoted"), Some(&RawValue::Text("true".into())));
725    }
726
727    #[test]
728    fn parses_nested_one_children() {
729        let tree = parse_ok("Add(lhs: Lit(value: 1), rhs: Neg(body: none))");
730        let lhs = tree.child_slot("lhs").unwrap();
731        assert_eq!(lhs.len(), 1);
732        assert_eq!(lhs[0].variant, "Lit");
733        let rhs = tree.child_slot("rhs").unwrap();
734        assert_eq!(rhs[0].variant, "Neg");
735    }
736
737    #[test]
738    fn optional_child_none_leaves_slot_absent() {
739        let tree = parse_ok("Neg(body: none)");
740        assert!(
741            tree.child_slot("body").is_none(),
742            "bare `none` = absent slot"
743        );
744    }
745
746    #[test]
747    fn optional_child_present_binds_one_tree() {
748        let tree = parse_ok("Neg(body: Lit(value: 3))");
749        assert_eq!(tree.child_slot("body").unwrap().len(), 1);
750    }
751
752    #[test]
753    fn many_child_list_binds_in_order_and_drops_commas() {
754        let tree = parse_ok("List(items: [Lit(value: 1), Lit(value: 2), Unit()])");
755        let items = tree.child_slot("items").unwrap();
756        let variants: Vec<&str> = items.iter().map(|t| t.variant.as_str()).collect();
757        assert_eq!(variants, ["Lit", "Lit", "Unit"]);
758    }
759
760    #[test]
761    fn many_child_empty_list_is_conformant() {
762        let tree = parse_ok("List(items: [])");
763        assert!(
764            tree.child_slot("items").is_none_or(<[_]>::is_empty),
765            "empty list = zero children"
766        );
767    }
768
769    #[test]
770    fn keyed_map_binds_entries_sorted_by_key() {
771        // Written deliberately out of order, with one quoted key that
772        // could not be spelled as a bare identifier: the parser is
773        // responsible for landing both in canonical order.
774        let tree = parse_ok(r#"Env(entries: { zeta: Unit(), "a b": Lit(value: 1) })"#);
775        let entries = tree.keyed_child_slot("entries").expect("keyed slot bound");
776        let keys: Vec<&str> = entries.iter().map(|(k, _)| k.as_str()).collect();
777        assert_eq!(keys, ["a b", "zeta"]);
778        let variants: Vec<&str> = entries.iter().map(|(_, t)| t.variant.as_str()).collect();
779        assert_eq!(variants, ["Lit", "Unit"]);
780        assert!(
781            tree.children.is_empty(),
782            "keyed entries must not leak into the positional half: {:?}",
783            tree.children
784        );
785    }
786
787    #[test]
788    fn keyed_map_source_order_does_not_change_the_tree() {
789        let forward = parse_ok("Env(entries: { a: Unit(), b: Lit(value: 1) })");
790        let reversed = parse_ok("Env(entries: { b: Lit(value: 1), a: Unit() })");
791        // Spans differ (the two spellings put the subtrees at
792        // different offsets), so compare the keyed payload rather than
793        // the whole tree.
794        let keys = |t: &crate::ParseTree| -> Vec<String> {
795            t.keyed_child_slot("entries")
796                .unwrap()
797                .iter()
798                .map(|(k, v)| format!("{k}={}", v.variant))
799                .collect()
800        };
801        assert_eq!(keys(&forward), keys(&reversed));
802    }
803
804    #[test]
805    fn keyed_map_empty_is_conformant() {
806        let tree = parse_ok("Env(entries: {})");
807        assert!(
808            tree.keyed_child_slot("entries").is_none_or(<[_]>::is_empty),
809            "empty map = zero entries"
810        );
811    }
812
813    #[test]
814    fn keyed_map_duplicate_key_parses_but_fails_conformance() {
815        // The grammar has no reason to reject it — duplicate detection
816        // is the schema's job, and `parse_ok` would hide the split, so
817        // this test drives the two stages apart deliberately.
818        let g = demo_grammar();
819        let tree = g
820            .parse("Env(entries: { k: Unit(), k: Lit(value: 1) })")
821            .expect("grammar accepts a repeated key");
822        let diags = check_conformance(&tree, &demo_schema());
823        assert!(
824            diags.iter().any(|d| d.code == crate::codes::DUPLICATE_KEY),
825            "expected DUPLICATE_KEY; got {:?}",
826            diags.iter().map(|d| d.code.as_str()).collect::<Vec<_>>()
827        );
828    }
829
830    #[test]
831    fn zero_argument_variant_parses() {
832        let tree = parse_ok("Unit()");
833        assert_eq!(tree.variant, "Unit");
834        assert!(tree.fields.is_empty() && tree.children.is_empty());
835    }
836
837    #[test]
838    fn whitespace_and_newlines_are_tolerated() {
839        let tree = parse_ok("Add(\n  lhs: Lit( value : 7 ),\n  rhs: Unit()\n)");
840        assert_eq!(tree.child_slot("lhs").unwrap()[0].variant, "Lit");
841    }
842
843    #[test]
844    fn unsupported_field_type_fails_generation_with_full_list() {
845        let schema = NodeSchema {
846            name: "Bad".into(),
847            variants: vec![VariantSchema {
848                name: "Par".into(),
849                fields: vec![
850                    FieldSchema {
851                        name: "policy".into(),
852                        ty: "Option<JoinPolicy>".into(),
853                        optional: false,
854                    },
855                    FieldSchema {
856                        name: "reducer".into(),
857                        ty: "ReducerId".into(),
858                        optional: false,
859                    },
860                ],
861                children: vec![],
862            }],
863        };
864        let err = grammar_from_schema(&schema, &IdGen::new()).unwrap_err();
865        assert_eq!(err.diagnostics.len(), 2, "one diagnostic per bad field");
866        assert!(
867            err.diagnostics
868                .iter()
869                .all(|d| d.code == codes::UNSUPPORTED_FIELD)
870        );
871    }
872
873    /// Flow-shaped schema whose `Par` payload fields the built-in
874    /// mapping rejects — the override motivating case.
875    fn par_schema() -> NodeSchema {
876        NodeSchema {
877            name: "Flow".into(),
878            variants: vec![
879                VariantSchema {
880                    name: "Par".into(),
881                    fields: vec![
882                        FieldSchema {
883                            name: "policy".into(),
884                            // Token-stream spelling, as the derive extracts it.
885                            ty: "Option < JoinPolicy >".into(),
886                            optional: false,
887                        },
888                        FieldSchema {
889                            name: "reducer_id".into(),
890                            ty: "Option < String >".into(),
891                            optional: false,
892                        },
893                    ],
894                    children: vec![ChildSchema {
895                        name: "children".into(),
896                        multiplicity: Multiplicity::Many,
897                    }],
898                },
899                VariantSchema {
900                    name: "Call".into(),
901                    fields: vec![FieldSchema {
902                        name: "label".into(),
903                        ty: "String".into(),
904                        optional: false,
905                    }],
906                    children: vec![],
907                },
908            ],
909        }
910    }
911
912    fn par_overrides() -> SyntaxOverrides {
913        SyntaxOverrides::new()
914            .for_type("Option<JoinPolicy>", |ids| {
915                choice(
916                    ids,
917                    vec![
918                        token(ids, "%kw:none"),
919                        token(ids, "%kw:all_failfast"),
920                        token(ids, "%kw:any_failfast"),
921                    ],
922                )
923            })
924            .for_type("Option<String>", |ids| {
925                choice(ids, vec![token(ids, "%kw:none"), token(ids, "%str")])
926            })
927    }
928
929    #[test]
930    fn type_overrides_unlock_exotic_payload_fields() {
931        // Without overrides the Flow-shaped schema fails generation
932        // (pinned by unsupported_field_type_fails_generation_with_full_list);
933        // with them it generates check-clean and parses. Note the
934        // override keys are written without whitespace while the schema
935        // carries the token-stream spelling.
936        let g = checked_grammar_from_schema_with(&par_schema(), &IdGen::new(), &par_overrides())
937            .expect("overridden Flow schema generates a clean grammar");
938        let tree = g
939            .parse(
940                r#"Par(policy: all_failfast, reducer_id: "reduce_all_ordered",
941                     children: [Call(label: "a"), Call(label: "b")])"#,
942            )
943            .expect("canonical Par text parses");
944        let diags = check_conformance(&tree, &par_schema());
945        assert!(diags.is_empty(), "conformance clean: {diags:?}");
946        assert_eq!(
947            tree.field("policy"),
948            Some(&RawValue::Text("all_failfast".into()))
949        );
950        assert_eq!(
951            tree.field("reducer_id"),
952            Some(&RawValue::Text("reduce_all_ordered".into()))
953        );
954        assert_eq!(tree.child_slot("children").unwrap().len(), 2);
955    }
956
957    #[test]
958    fn field_override_wins_over_type_override() {
959        // Same type in both entries; the (variant, field)-pinned one
960        // must decide the syntax.
961        let overrides = par_overrides().for_field("Par", "policy", |ids| token(ids, "%kw:pinned"));
962        let g = checked_grammar_from_schema_with(&par_schema(), &IdGen::new(), &overrides)
963            .expect("clean grammar with field-level override");
964        let tree = g
965            .parse(r#"Par(policy: pinned, reducer_id: none, children: [])"#)
966            .expect("field-level syntax parses");
967        assert_eq!(tree.field("policy"), Some(&RawValue::Text("pinned".into())));
968        // The type-level spelling is no longer accepted at that site.
969        assert!(
970            g.parse(r#"Par(policy: all_failfast, reducer_id: none, children: [])"#)
971                .is_err(),
972            "type-level syntax rejected once the field is pinned"
973        );
974    }
975
976    #[test]
977    fn unrelated_override_leaves_builtin_mapping_and_failure_intact() {
978        // An override for some other type neither rescues the
979        // unsupported fields nor perturbs built-in ones. Note that
980        // `Option<String>` on `reducer_id` is now a built-in mapping
981        // (Layer 2 of the "built-in optional payload fields"
982        // contract), so only the `Option<JoinPolicy>` field on
983        // `policy` remains unmapped without a `SyntaxOverrides` entry.
984        let overrides = SyntaxOverrides::new().for_type("Uuid", |ids| token(ids, "%str"));
985        let err = grammar_from_schema_with(&par_schema(), &IdGen::new(), &overrides).unwrap_err();
986        assert_eq!(
987            err.diagnostics.len(),
988            1,
989            "policy is the only Par field still unmapped without overrides",
990        );
991        assert!(
992            err.diagnostics
993                .iter()
994                .all(|d| d.code == codes::UNSUPPORTED_FIELD)
995        );
996        assert!(
997            err.diagnostics[0].message.contains("policy"),
998            "unmapped-field diagnostic points at `policy`",
999        );
1000        // Built-in demo schema is unaffected by the stray entry.
1001        let g = checked_grammar_from_schema_with(&demo_schema(), &IdGen::new(), &overrides)
1002            .expect("demo schema still generates");
1003        assert_eq!(g.parse("Lit(value: 7)").unwrap().variant, "Lit");
1004    }
1005
1006    /// Layer 2: `Option<String>` payload maps to `none | %str` via the
1007    /// built-in mapping (no `SyntaxOverrides` entry needed). Canonical
1008    /// text parses both spellings and both build through the derive's
1009    /// `build_field_optional` route.
1010    #[test]
1011    fn builtin_option_string_mapping_accepts_none_and_str() {
1012        let schema = NodeSchema {
1013            name: "Meta".into(),
1014            variants: vec![VariantSchema {
1015                name: "Row".into(),
1016                fields: vec![FieldSchema {
1017                    name: "description".into(),
1018                    ty: "Option<String>".into(),
1019                    optional: true,
1020                }],
1021                children: vec![],
1022            }],
1023        };
1024        let g = checked_grammar_from_schema(&schema, &IdGen::new())
1025            .expect("Option<String> is a built-in mapping");
1026        // `none` spelling.
1027        let t1 = g.parse(r#"Row(description: none)"#).expect("none parses");
1028        assert_eq!(
1029            t1.field("description"),
1030            Some(&RawValue::Text("none".into())),
1031        );
1032        // `%str` spelling.
1033        let t2 = g.parse(r#"Row(description: "hi")"#).expect("string parses");
1034        assert_eq!(t2.field("description"), Some(&RawValue::Text("hi".into())));
1035        // Omitted entirely (Layer 1 optional PEG wrap).
1036        let t3 = g.parse(r#"Row()"#).expect("omitted parses");
1037        assert!(t3.field("description").is_none());
1038        // check_conformance is clean for all three.
1039        for t in [&t1, &t2, &t3] {
1040            assert!(
1041                check_conformance(t, &schema).is_empty(),
1042                "conformance clean for {t:?}",
1043            );
1044        }
1045    }
1046
1047    /// Layer 2: `Vec<String>` payload maps to `[ %str ("," %str)* ]`
1048    /// via the built-in mapping. Empty list, single item, and multi
1049    /// item all parse; captured text is JSON-parsable so
1050    /// `build_field_vec` reads it directly.
1051    #[test]
1052    fn builtin_vec_string_mapping_accepts_bracketed_list() {
1053        let schema = NodeSchema {
1054            name: "Meta".into(),
1055            variants: vec![VariantSchema {
1056                name: "Row".into(),
1057                fields: vec![FieldSchema {
1058                    name: "tags".into(),
1059                    ty: "Vec<String>".into(),
1060                    optional: true,
1061                }],
1062                children: vec![],
1063            }],
1064        };
1065        let g = checked_grammar_from_schema(&schema, &IdGen::new())
1066            .expect("Vec<String> is a built-in mapping");
1067        // Empty list.
1068        let t1 = g.parse(r#"Row(tags: [])"#).expect("empty list parses");
1069        assert_eq!(t1.field("tags"), Some(&RawValue::Text("[]".into())));
1070        // Multi item. The PEG runtime's implicit whitespace-skip
1071        // strips inter-token spaces from the captured text, so the
1072        // field carries the compact form `["a","b"]` (still valid
1073        // JSON — `serde_json::from_str` accepts it).
1074        let t2 = g
1075            .parse(r#"Row(tags: ["a", "b"])"#)
1076            .expect("two items parses");
1077        assert_eq!(
1078            t2.field("tags"),
1079            Some(&RawValue::Text(r#"["a","b"]"#.into())),
1080        );
1081        // Omitted.
1082        let t3 = g.parse(r#"Row()"#).expect("omitted parses");
1083        assert!(t3.field("tags").is_none());
1084        for t in [&t1, &t2, &t3] {
1085            assert!(
1086                check_conformance(t, &schema).is_empty(),
1087                "conformance clean for {t:?}",
1088            );
1089        }
1090    }
1091
1092    #[test]
1093    fn empty_schema_fails_generation() {
1094        let schema = NodeSchema {
1095            name: "Void".into(),
1096            variants: vec![],
1097        };
1098        let err = grammar_from_schema(&schema, &IdGen::new()).unwrap_err();
1099        assert_eq!(err.diagnostics[0].code, codes::EMPTY_SCHEMA);
1100    }
1101
1102    #[test]
1103    fn parse_error_reports_expected_set() {
1104        let g = demo_grammar();
1105        let err = g.parse("Lit(value: banana)").unwrap_err();
1106        assert!(!err.diagnostics.is_empty());
1107    }
1108}