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