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