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