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}