dsl_kit_parse/lib.rs
1//! Parser trunk for `dsl-kit` DSLs.
2//!
3//! Two front-ends (serde bridge in G-1b, PEG interpreter in G-2) will
4//! both feed a single [`ParseTree`] shape. One consumer,
5//! `#[derive(DslBuild)]` (G-1c), converts a validated tree into a
6//! typed AST value using the caller's [`IdGen`] to mint fresh
7//! [`NodeId`]s.
8//!
9//! This module (G-1a) lands the central data types and the schema
10//! conformance checker that both front-ends run against. All feedback
11//! flows through one [`Diagnostic`] envelope so the consumer AI sees a
12//! single dialect across parsing, conformance, lint, and debugger.
13//!
14//! ## Architecture (layers)
15//!
16//! - [`ParseTree`] — untyped trunk. Variant name + field payloads +
17//! named child slots (positional lists, plus keyed entries for
18//! [`Multiplicity::Map`] slots) + optional source [`Span`].
19//! - [`RawValue`] — per-field payload representation. `Text` keeps the
20//! PEG front-end's matched source text; `Json` keeps the serde
21//! front-end's typed value with no stringify round-trip.
22//! - [`check_conformance`] — validates a tree against a
23//! [`NodeSchema`] and returns diagnostics.
24//! - [`Diagnostic`] / [`Severity`] / [`Location`] — the shared
25//! envelope shape.
26//! - [`DslBuild`] — trait consumed by the derive to build a typed AST.
27//! - [`BuildError`] — non-empty diagnostic bag returned on build
28//! failure.
29
30#![warn(missing_docs)]
31
32use dsl_kit_core::{IdGen, NodeId, Suggester, Suggestion};
33use dsl_kit_schema::{ChildSchema, Multiplicity, NodeSchema, VariantSchema};
34use serde_json::{Value, json};
35use std::cmp::Ordering;
36use std::collections::BTreeMap;
37use std::fmt;
38
39pub mod example_gen;
40pub mod grammar_check;
41pub mod peg;
42pub mod schema_gen;
43pub mod serde_bridge;
44
45// ---------------------------------------------------------------------------
46// Span
47// ---------------------------------------------------------------------------
48
49/// Byte-offset range into the parser input.
50///
51/// The PEG front-end fills this in as it consumes input; the serde
52/// front-end leaves it `None` because JSON payloads have no meaningful
53/// source position after deserialization.
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55pub struct Span {
56 /// Inclusive start byte offset.
57 pub start: usize,
58 /// Exclusive end byte offset.
59 pub end: usize,
60}
61
62impl Span {
63 /// Constructs a new [`Span`].
64 pub const fn new(start: usize, end: usize) -> Self {
65 Self { start, end }
66 }
67}
68
69// ---------------------------------------------------------------------------
70// RawValue
71// ---------------------------------------------------------------------------
72
73/// Per-field payload representation carried by [`ParseTree`].
74///
75/// The two arms correspond to the two front-ends:
76///
77/// - [`RawValue::Text`] is the matched source text a PEG rule produced;
78/// the [`DslBuild`] consumer converts it via `FromStr`.
79/// - [`RawValue::Json`] is a typed value straight from serde; the
80/// consumer converts it via serde deserialization. Nested payloads
81/// like `Option<u32>` never take a stringify → reparse detour.
82#[derive(Debug, Clone, PartialEq)]
83pub enum RawValue {
84 /// Matched source text (PEG front-end).
85 Text(String),
86 /// Typed value (serde front-end).
87 Json(Value),
88}
89
90// ---------------------------------------------------------------------------
91// ParseTree
92// ---------------------------------------------------------------------------
93
94/// Untyped parse trunk, produced by any front-end and consumed by
95/// [`DslBuild`].
96///
97/// The shape deliberately mirrors [`NodeSchema`] / [`VariantSchema`]:
98/// `variant` picks a variant by name; `fields` carries non-recursive
99/// payload; `children` carries named **positional** child slots each
100/// holding an ordered list of subtrees; `keyed_children` carries named
101/// **keyed** child slots ([`Multiplicity::Map`]) holding `(key,
102/// subtree)` pairs.
103///
104/// A given slot name lives in exactly one of the two child vectors —
105/// whichever one its schema [`Multiplicity`] calls for. Putting it in
106/// the wrong one is a [`codes::KEYED_SLOT_SHAPE`] diagnostic at
107/// conformance time rather than a silent drop.
108#[derive(Debug, Clone, PartialEq)]
109pub struct ParseTree {
110 /// Variant name — must match a [`VariantSchema::name`] at
111 /// conformance time.
112 pub variant: String,
113 /// Non-recursive payload fields, keyed by field name.
114 pub fields: Vec<(String, RawValue)>,
115 /// Positional child slots, keyed by slot name. Each slot's inner
116 /// [`Vec`] holds zero-or-more trees per the child's
117 /// [`Multiplicity`] ([`One`](Multiplicity::One) /
118 /// [`Optional`](Multiplicity::Optional) /
119 /// [`Many`](Multiplicity::Many)).
120 pub children: Vec<(String, Vec<ParseTree>)>,
121 /// Keyed child slots ([`Multiplicity::Map`]), by slot name. Each
122 /// slot holds `(key, subtree)` pairs.
123 ///
124 /// Front-ends must emit the pairs **sorted by key**, so that two
125 /// front-ends handed the same document produce equal entries. The
126 /// JSON bridge sorts on ingest; hand-built trees that do not are
127 /// rejected at conformance time with
128 /// [`codes::KEYED_SLOT_UNSORTED`] rather than quietly compared
129 /// unequal later.
130 ///
131 /// One shape is *not* pinned across front-ends: an **empty** map
132 /// may arrive either as a present-but-empty slot or as no slot at
133 /// all, depending on how the front-end spells emptiness (the JSON
134 /// bridge records the key it saw; the PEG interpreter has nothing
135 /// to record). Both mean the same thing everywhere it matters —
136 /// [`check_conformance`] accepts both and
137 /// [`build_child_map`] yields an empty map from both — so
138 /// consumers should read a slot through
139 /// [`ParseTree::keyed_child_slot`] rather than testing for its
140 /// presence. The positional [`ParseTree::children`] half has
141 /// carried the same asymmetry since it existed.
142 ///
143 /// Duplicate keys within one slot are representable (the storage
144 /// is a [`Vec`], not a map) precisely so they can be *diagnosed* —
145 /// [`codes::DUPLICATE_KEY`] — instead of one entry silently
146 /// winning.
147 pub keyed_children: Vec<(String, Vec<(String, ParseTree)>)>,
148 /// Source-range span, if the front-end tracks it.
149 pub span: Option<Span>,
150}
151
152impl ParseTree {
153 /// Constructs a new [`ParseTree`] with no fields, children, or span.
154 pub fn new(variant: impl Into<String>) -> Self {
155 Self {
156 variant: variant.into(),
157 fields: Vec::new(),
158 children: Vec::new(),
159 keyed_children: Vec::new(),
160 span: None,
161 }
162 }
163
164 /// Looks up a payload field by name.
165 pub fn field(&self, name: &str) -> Option<&RawValue> {
166 self.fields.iter().find(|(n, _)| n == name).map(|(_, v)| v)
167 }
168
169 /// Looks up a positional child slot by name.
170 pub fn child_slot(&self, name: &str) -> Option<&[ParseTree]> {
171 self.children
172 .iter()
173 .find(|(n, _)| n == name)
174 .map(|(_, v)| v.as_slice())
175 }
176
177 /// Looks up a keyed child slot ([`Multiplicity::Map`]) by name.
178 ///
179 /// Returns the slot's `(key, subtree)` pairs in the order the
180 /// front-end emitted them. For a tree that passed
181 /// [`check_conformance`] that order is ascending by key; on an
182 /// unchecked tree it is whatever the producer wrote.
183 pub fn keyed_child_slot(&self, name: &str) -> Option<&[(String, ParseTree)]> {
184 self.keyed_children
185 .iter()
186 .find(|(n, _)| n == name)
187 .map(|(_, v)| v.as_slice())
188 }
189}
190
191// ---------------------------------------------------------------------------
192// Diagnostic envelope
193// ---------------------------------------------------------------------------
194
195/// Severity level of a [`Diagnostic`].
196///
197/// Matches the shape used by `dsl-kit-lint` so consumers speak one
198/// dialect across parse / conformance / lint / debugger.
199#[derive(Debug, Clone, Copy, PartialEq, Eq)]
200pub enum Severity {
201 /// Blocks build. Multiple errors may be collected before returning.
202 Error,
203 /// Non-blocking warning.
204 Warning,
205 /// Advisory note.
206 Info,
207}
208
209impl Severity {
210 /// Returns the wire-format string used by [`Diagnostic::to_json`].
211 pub const fn as_str(self) -> &'static str {
212 match self {
213 Severity::Error => "error",
214 Severity::Warning => "warning",
215 Severity::Info => "info",
216 }
217 }
218}
219
220/// Where a [`Diagnostic`] points into the consumer's material.
221///
222/// [`Location::Span`] is the parse-time answer (byte range into the
223/// input text); [`Location::Node`] is the post-build answer
224/// ([`NodeId`] into the typed AST); [`Location::None`] is for
225/// diagnostics without a natural anchor point (e.g. "missing top-level
226/// variant").
227#[derive(Debug, Clone, Copy, PartialEq, Eq)]
228pub enum Location {
229 /// Source-text range.
230 Span(Span),
231 /// AST node identity.
232 Node(NodeId),
233 /// No anchor point.
234 None,
235}
236
237impl Location {
238 /// Renders the location as the JSON value used by
239 /// [`Diagnostic::to_json`].
240 ///
241 /// - `Location::Span { start, end }` → `{ "kind": "span", "start": N, "end": M }`
242 /// - `Location::Node(id)` → `{ "kind": "node", "id": N }`
243 /// - `Location::None` → JSON `null`
244 pub fn to_json(&self) -> Value {
245 match self {
246 Location::Span(Span { start, end }) => {
247 json!({ "kind": "span", "start": start, "end": end })
248 }
249 Location::Node(id) => json!({ "kind": "node", "id": id.0 }),
250 Location::None => Value::Null,
251 }
252 }
253}
254
255/// One diagnostic in the unified envelope shared across parse,
256/// conformance, lint, and debugger feedback.
257///
258/// The consumer AI is expected to read a single JSON dialect regardless
259/// of which subsystem produced the diagnostic: `{ severity, code,
260/// message, location }`. `code` is a stable machine-friendly slug
261/// (e.g. `"dsl_kit::parse::unknown_variant"`); `message` is the human
262/// (or AI) readable one-liner.
263#[derive(Debug, Clone, PartialEq, Eq)]
264pub struct Diagnostic {
265 /// Severity level.
266 pub severity: Severity,
267 /// Stable machine slug.
268 pub code: String,
269 /// One-line human / AI readable description.
270 pub message: String,
271 /// Anchor point (or [`Location::None`]).
272 pub location: Location,
273}
274
275impl Diagnostic {
276 /// Constructs an [`Severity::Error`] diagnostic.
277 pub fn error(code: impl Into<String>, message: impl Into<String>) -> Self {
278 Self {
279 severity: Severity::Error,
280 code: code.into(),
281 message: message.into(),
282 location: Location::None,
283 }
284 }
285
286 /// Attaches a source [`Span`] as the location.
287 pub fn with_span(mut self, span: Option<Span>) -> Self {
288 if let Some(span) = span {
289 self.location = Location::Span(span);
290 }
291 self
292 }
293
294 /// Attaches an AST [`NodeId`] as the location.
295 pub fn with_node(mut self, id: NodeId) -> Self {
296 self.location = Location::Node(id);
297 self
298 }
299
300 /// Renders the diagnostic as a JSON value.
301 ///
302 /// Layout:
303 /// ```json
304 /// {
305 /// "severity": "error",
306 /// "code": "dsl_kit::parse::unknown_variant",
307 /// "message": "unknown variant `Foo` (candidates: Add, Mul, Lit)",
308 /// "location": { "kind": "span", "start": 0, "end": 3 }
309 /// }
310 /// ```
311 pub fn to_json(&self) -> Value {
312 json!({
313 "severity": self.severity.as_str(),
314 "code": self.code,
315 "message": self.message,
316 "location": self.location.to_json(),
317 })
318 }
319}
320
321// ---------------------------------------------------------------------------
322// BuildError
323// ---------------------------------------------------------------------------
324
325/// Non-empty diagnostic bag returned by [`DslBuild::from_parse_tree`]
326/// and [`check_conformance`] callers.
327///
328/// Multiple diagnostics are collected before failing so the consumer
329/// AI sees every problem in one round-trip.
330#[derive(Debug, Clone, PartialEq, Eq)]
331pub struct BuildError {
332 /// The diagnostics (at least one is guaranteed by
333 /// [`BuildError::new`]).
334 pub diagnostics: Vec<Diagnostic>,
335}
336
337impl BuildError {
338 /// Wraps a non-empty vector of diagnostics.
339 ///
340 /// # Panics
341 ///
342 /// Panics if `diagnostics` is empty — a [`BuildError`] with no
343 /// diagnostics is meaningless.
344 pub fn new(diagnostics: Vec<Diagnostic>) -> Self {
345 assert!(
346 !diagnostics.is_empty(),
347 "BuildError requires at least one diagnostic"
348 );
349 Self { diagnostics }
350 }
351
352 /// Convenience constructor for a single-diagnostic error.
353 pub fn single(diag: Diagnostic) -> Self {
354 Self {
355 diagnostics: vec![diag],
356 }
357 }
358
359 /// Renders the whole bag as a JSON array of
360 /// [`Diagnostic::to_json`] entries.
361 pub fn to_json(&self) -> Value {
362 Value::Array(self.diagnostics.iter().map(Diagnostic::to_json).collect())
363 }
364}
365
366impl fmt::Display for BuildError {
367 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
368 write!(
369 f,
370 "build failed with {} diagnostic(s):",
371 self.diagnostics.len()
372 )?;
373 for d in &self.diagnostics {
374 write!(f, "\n [{}] {}: {}", d.severity.as_str(), d.code, d.message)?;
375 }
376 Ok(())
377 }
378}
379
380impl std::error::Error for BuildError {}
381
382// ---------------------------------------------------------------------------
383// DslBuild
384// ---------------------------------------------------------------------------
385
386/// Contract for building a typed AST value from a validated
387/// [`ParseTree`].
388///
389/// Implemented via `#[derive(DslBuild)]` in `dsl-kit-macros` (G-1c);
390/// hand-written impls are fine for shapes the derive cannot express
391/// (mixed tuple variants, generics, cross-type recursion, etc.).
392pub trait DslBuild: Sized {
393 /// Builds a typed value from `tree`, minting fresh [`NodeId`]s from
394 /// `ids`.
395 ///
396 /// Implementations should call [`check_conformance`] against
397 /// `Self::schema()` before dispatching per-variant so that shape
398 /// mismatches surface as diagnostics rather than panics or ad-hoc
399 /// errors. `RawValue::Text` payloads convert through `FromStr`;
400 /// `RawValue::Json` payloads convert through
401 /// `serde_json::from_value`.
402 fn from_parse_tree(tree: &ParseTree, ids: &IdGen) -> Result<Self, BuildError>;
403}
404
405// ---------------------------------------------------------------------------
406// Schema conformance
407// ---------------------------------------------------------------------------
408
409/// Diagnostic codes emitted by [`check_conformance`].
410///
411/// Exposed as a module of `pub const &str` slugs so downstream tools
412/// (lint UIs, doc generators) can reference them without matching on
413/// string literals.
414pub mod codes {
415 /// Tree's `variant` did not match any
416 /// [`VariantSchema`](dsl_kit_schema::VariantSchema) in the
417 /// [`NodeSchema`](dsl_kit_schema::NodeSchema).
418 pub const UNKNOWN_VARIANT: &str = "dsl_kit::parse::unknown_variant";
419 /// A field required by the schema is absent from the tree.
420 pub const MISSING_FIELD: &str = "dsl_kit::parse::missing_field";
421 /// The tree carries a field the schema does not declare.
422 pub const UNKNOWN_FIELD: &str = "dsl_kit::parse::unknown_field";
423 /// The tree references a child slot the schema does not declare.
424 pub const UNKNOWN_CHILD: &str = "dsl_kit::parse::unknown_child";
425 /// A [`crate::Multiplicity::One`] slot did not carry exactly one
426 /// child.
427 pub const ARITY_ONE: &str = "dsl_kit::parse::arity_one";
428 /// A [`crate::Multiplicity::Optional`] slot carried more than one
429 /// child.
430 pub const ARITY_OPTIONAL: &str = "dsl_kit::parse::arity_optional";
431 /// A payload field appeared under `children` (structural mismatch).
432 pub const FIELD_AS_CHILD: &str = "dsl_kit::parse::field_as_child";
433 /// A child slot appeared under `fields` (structural mismatch).
434 pub const CHILD_AS_FIELD: &str = "dsl_kit::parse::child_as_field";
435 /// A field name appeared more than once.
436 pub const DUPLICATE_FIELD: &str = "dsl_kit::parse::duplicate_field";
437 /// A child slot name appeared more than once.
438 pub const DUPLICATE_CHILD: &str = "dsl_kit::parse::duplicate_child";
439 /// A payload field's value could not be converted to the target
440 /// Rust type (serde deserialization failure or `FromStr` failure).
441 pub const FIELD_TYPE: &str = "dsl_kit::parse::field_type";
442 /// A keyed child slot ([`crate::Multiplicity::Map`]) carried the
443 /// same key more than once. The map the consumer asked for cannot
444 /// hold both, and picking a winner silently would make the parse
445 /// lossy — so the duplicate is an error at conformance time and at
446 /// [`crate::build_child_map`] time.
447 pub const DUPLICATE_KEY: &str = "dsl_kit::parse::duplicate_key";
448 /// A child slot was placed in the wrong half of the tree: a slot
449 /// declared [`crate::Multiplicity::Map`] appeared under
450 /// [`ParseTree::children`] (positional), or a slot declared
451 /// `One` / `Optional` / `Many` appeared under
452 /// [`ParseTree::keyed_children`].
453 pub const KEYED_SLOT_SHAPE: &str = "dsl_kit::parse::keyed_slot_shape";
454 /// A keyed child slot's entries were not in ascending key order.
455 /// [`ParseTree::keyed_children`] documents sorted-by-key as the
456 /// canonical form so that two front-ends producing the same
457 /// document produce equal trees; this is that contract enforced
458 /// rather than assumed. The JSON bridge sorts on ingest, so this
459 /// fires only for hand-built or hand-rolled front-end trees.
460 pub const KEYED_SLOT_UNSORTED: &str = "dsl_kit::parse::keyed_slot_unsorted";
461 /// A child slot's multiplicity is a variant this build of
462 /// `dsl-kit-parse` does not recognise. Emitted from the catch-all
463 /// arm required by [`crate::Multiplicity`]'s `#[non_exhaustive]`
464 /// contract when a future variant is added to the schema crate
465 /// ahead of parse-side support. Not reachable in practice within
466 /// the workspace (both crates are versioned in lockstep) but held
467 /// as a first-class diagnostic so out-of-workspace consumers see a
468 /// stable slug rather than a panic.
469 pub const UNKNOWN_MULTIPLICITY: &str = "dsl_kit::parse::unknown_multiplicity";
470}
471
472/// Validates `tree` against `schema` shallowly (this level only).
473///
474/// The check is intentionally single-level — the recursion is the
475/// caller's job (typically `DslBuild::from_parse_tree` for each child
476/// slot). Every mismatch produces a [`Diagnostic`]; the returned
477/// vector is empty when the tree matches.
478///
479/// Checks performed:
480///
481/// - variant name matches one of `schema.variants` (else
482/// [`codes::UNKNOWN_VARIANT`] with nearest candidates in the
483/// message);
484/// - every declared field is present exactly once
485/// ([`codes::MISSING_FIELD`], [`codes::DUPLICATE_FIELD`]);
486/// - no undeclared field is present ([`codes::UNKNOWN_FIELD`],
487/// or [`codes::CHILD_AS_FIELD`] when the extra name is actually a
488/// declared child slot);
489/// - every declared child slot is present exactly once
490/// ([`codes::DUPLICATE_CHILD`]) and honours its [`Multiplicity`]
491/// ([`codes::ARITY_ONE`], [`codes::ARITY_OPTIONAL`]);
492/// - every child slot sits in the half its [`Multiplicity`] calls for
493/// — keyed slots under [`ParseTree::keyed_children`], positional
494/// ones under [`ParseTree::children`] ([`codes::KEYED_SLOT_SHAPE`]);
495/// - a keyed slot carries each key at most once
496/// ([`codes::DUPLICATE_KEY`]) and in ascending key order
497/// ([`codes::KEYED_SLOT_UNSORTED`]);
498/// - no undeclared child slot is present ([`codes::UNKNOWN_CHILD`],
499/// or [`codes::FIELD_AS_CHILD`] when the extra name is actually a
500/// declared payload field).
501///
502/// [`Multiplicity::Many`] and [`Multiplicity::Map`] both accept
503/// zero-or-more children — emptiness is a domain-level judgment, not a
504/// shape error, so the `no-empty-child-slots` lint rule is where it
505/// belongs. That rule covers both collection shapes and reports at
506/// `Warn`, since neither multiplicity promises a non-empty
507/// collection.
508pub fn check_conformance(tree: &ParseTree, schema: &NodeSchema) -> Vec<Diagnostic> {
509 check_conformance_with(tree, schema, &BuiltinLevenshteinSuggester)
510}
511
512/// Variant of [`check_conformance`] that routes `did you mean X?`
513/// hints through a caller-supplied [`Suggester`].
514///
515/// The free function [`check_conformance`] delegates here with a
516/// crate-private [`Suggester`] backed by the same Levenshtein
517/// algorithm the crate has always shipped, so existing callers see no
518/// behavioural change. Reach for this variant when you want to plug
519/// in a different similarity algorithm (e.g. `dsl-kit-fuzzy`'s
520/// `FuzzySuggester` with Jaro-Winkler) at a specific call site.
521pub fn check_conformance_with(
522 tree: &ParseTree,
523 schema: &NodeSchema,
524 suggester: &dyn Suggester,
525) -> Vec<Diagnostic> {
526 let mut out = Vec::new();
527
528 let Some(variant) = schema.variant(&tree.variant) else {
529 let msg = format_unknown_variant(&tree.variant, schema, suggester);
530 out.push(Diagnostic::error(codes::UNKNOWN_VARIANT, msg).with_span(tree.span));
531 return out;
532 };
533
534 check_fields(tree, variant, &mut out, suggester);
535 check_children(tree, variant, &mut out, suggester);
536 out
537}
538
539/// Shared formatter for the `UNKNOWN_VARIANT` diagnostic message,
540/// used by both [`check_conformance_with`] and the serde bridge so the
541/// wording stays consistent across front-ends.
542pub(crate) fn format_unknown_variant(
543 query: &str,
544 schema: &NodeSchema,
545 suggester: &dyn Suggester,
546) -> String {
547 let names: Vec<&str> = schema.variants.iter().map(|v| v.name.as_str()).collect();
548 let base = format!("unknown variant `{}` for `{}`", query, schema.name);
549 match suggester.enrich_unknown(query, &names) {
550 Some(hint) => format!("{base} ({hint})"),
551 None => base,
552 }
553}
554
555/// Shared formatter for `UNKNOWN_FIELD` and `UNKNOWN_CHILD` messages.
556///
557/// `kind` is `"field"` or `"child slot"`. `all_candidates` should
558/// include both declared field names and declared child slot names so
559/// a `did you mean` hint can point at either. `missing_candidates`
560/// carries the slot names that are declared but currently absent from
561/// the tree; suggestions that appear in this set are marked
562/// `(missing)` — the "pair hint" that makes payloads like
563/// `taget` → `target` (missing) diagnose themselves at a glance.
564pub(crate) fn format_unknown_slot(
565 kind: &str,
566 query: &str,
567 variant_name: &str,
568 all_candidates: &[&str],
569 missing_candidates: &[&str],
570 suggester: &dyn Suggester,
571) -> String {
572 let base = format!("unknown {kind} `{query}` on variant `{variant_name}`");
573 let sugs = suggester.suggest(query, all_candidates);
574 if sugs.is_empty() {
575 return base;
576 }
577 let joined = sugs
578 .iter()
579 .take(3)
580 .map(|s| {
581 if missing_candidates.contains(&s.candidate) {
582 format!("`{}` (missing)", s.candidate)
583 } else {
584 format!("`{}`", s.candidate)
585 }
586 })
587 .collect::<Vec<_>>()
588 .join(", ");
589 format!("{base} (did you mean: {joined})")
590}
591
592fn check_fields(
593 tree: &ParseTree,
594 variant: &VariantSchema,
595 out: &mut Vec<Diagnostic>,
596 suggester: &dyn Suggester,
597) {
598 // Duplicate field names.
599 for i in 0..tree.fields.len() {
600 let (name, _) = &tree.fields[i];
601 if tree.fields[..i].iter().any(|(n, _)| n == name) {
602 out.push(
603 Diagnostic::error(
604 codes::DUPLICATE_FIELD,
605 format!(
606 "field `{}` appears more than once on variant `{}`",
607 name, variant.name
608 ),
609 )
610 .with_span(tree.span),
611 );
612 }
613 }
614
615 // Missing declared fields. Optional fields (typically `Option<T>`
616 // / `Vec<T>` payloads recognised by `#[derive(DslSchema)]`) are
617 // skipped — their absence is a valid shape and the build layer's
618 // `build_field_optional` / `build_field_vec` helpers supply the
619 // default (`None` / empty vec).
620 for f in &variant.fields {
621 if f.optional {
622 continue;
623 }
624 if tree.field(&f.name).is_none() {
625 out.push(
626 Diagnostic::error(
627 codes::MISSING_FIELD,
628 format!(
629 "variant `{}` is missing required field `{}` (type `{}`)",
630 variant.name, f.name, f.ty
631 ),
632 )
633 .with_span(tree.span),
634 );
635 }
636 }
637
638 // Precompute the "missing-so-far" set once: slot names that are
639 // declared but currently absent from `tree`. Used as the pair-hint
640 // marker on UNKNOWN_FIELD suggestions.
641 let missing = missing_slot_names(tree, variant);
642 let all_slots = all_slot_names(variant);
643
644 // Unknown fields.
645 for (name, _) in &tree.fields {
646 if variant.fields.iter().any(|f| &f.name == name) {
647 continue;
648 }
649 // If it names a declared child slot, that's a structural mix-up.
650 if variant.children.iter().any(|c| &c.name == name) {
651 out.push(
652 Diagnostic::error(
653 codes::CHILD_AS_FIELD,
654 format!(
655 "`{}` on variant `{}` is a child slot, not a payload field \
656 (move it under `children`)",
657 name, variant.name
658 ),
659 )
660 .with_span(tree.span),
661 );
662 } else {
663 let msg = format_unknown_slot(
664 "field",
665 name,
666 &variant.name,
667 &all_slots,
668 &missing,
669 suggester,
670 );
671 out.push(Diagnostic::error(codes::UNKNOWN_FIELD, msg).with_span(tree.span));
672 }
673 }
674}
675
676fn check_children(
677 tree: &ParseTree,
678 variant: &VariantSchema,
679 out: &mut Vec<Diagnostic>,
680 suggester: &dyn Suggester,
681) {
682 // Duplicate child slot names. The two child vectors share one
683 // namespace — a slot appearing once positionally and once keyed is
684 // a duplicate, not two independent slots — so the scan walks them
685 // as a single sequence.
686 let mut seen: Vec<&str> = Vec::new();
687 for name in slot_names_in_tree(tree) {
688 if seen.contains(&name) {
689 out.push(
690 Diagnostic::error(
691 codes::DUPLICATE_CHILD,
692 format!(
693 "child slot `{}` appears more than once on variant `{}`",
694 name, variant.name
695 ),
696 )
697 .with_span(tree.span),
698 );
699 } else {
700 seen.push(name);
701 }
702 }
703
704 // Declared children: keying + arity check.
705 for c in &variant.children {
706 let positional = tree.child_slot(&c.name);
707 let keyed = tree.keyed_child_slot(&c.name);
708 let count = positional.map(<[ParseTree]>::len).unwrap_or(0);
709
710 // Keying mismatch: the slot exists, but in the half the schema
711 // did not ask for.
712 let is_map = c.multiplicity == Multiplicity::Map;
713 let wrong_half = if is_map {
714 positional.is_some()
715 } else {
716 keyed.is_some()
717 };
718 if wrong_half {
719 out.push(diag_keying(variant, c, is_map, tree.span));
720 }
721
722 // When the slot's *only* occurrence sits in the wrong half,
723 // skip the shape check below: it reads the right half, finds
724 // it empty, and would report "expects exactly one child but
725 // got 0" about a tree that supplied exactly one child. The
726 // keying diagnostic already says what went wrong; a second,
727 // untrue one only misdirects. A slot present in *both* halves
728 // still gets checked — `DUPLICATE_CHILD` covers the collision
729 // and the shape verdict on the right half stays meaningful.
730 let only_in_wrong_half = wrong_half
731 && if is_map {
732 keyed.is_none()
733 } else {
734 positional.is_none()
735 };
736 if only_in_wrong_half {
737 continue;
738 }
739
740 match c.multiplicity {
741 Multiplicity::One => {
742 if count != 1 {
743 out.push(diag_arity(codes::ARITY_ONE, variant, c, count, tree.span));
744 }
745 }
746 Multiplicity::Optional => {
747 if count > 1 {
748 out.push(diag_arity(
749 codes::ARITY_OPTIONAL,
750 variant,
751 c,
752 count,
753 tree.span,
754 ));
755 }
756 }
757 Multiplicity::Many => {
758 // Zero is fine at the shape level.
759 }
760 Multiplicity::Map => {
761 // Zero-or-more keyed entries is fine at the shape
762 // level (same as `Many`); what a map *cannot* carry is
763 // the same key twice.
764 //
765 // Walking adjacent pairs checks that in one linear
766 // pass — and the same pass verifies the sorted-by-key
767 // order [`ParseTree::keyed_children`] documents, so
768 // that contract is enforced rather than trusted. A
769 // front-end that emits out of order finds out here
770 // instead of shipping trees that compare unequal to
771 // every other front-end's for the same document.
772 let entries = keyed.unwrap_or(&[]);
773 for pair in entries.windows(2) {
774 let (lhs, rhs) = (&pair[0].0, &pair[1].0);
775 match lhs.cmp(rhs) {
776 Ordering::Equal => out.push(
777 Diagnostic::error(
778 codes::DUPLICATE_KEY,
779 format!(
780 "keyed child slot `{}` on variant `{}` carries key \
781 `{}` more than once",
782 c.name, variant.name, rhs
783 ),
784 )
785 .with_span(tree.span),
786 ),
787 Ordering::Greater => out.push(
788 Diagnostic::error(
789 codes::KEYED_SLOT_UNSORTED,
790 format!(
791 "keyed child slot `{}` on variant `{}` is not sorted by \
792 key (`{}` precedes `{}`); front-ends must emit keyed \
793 entries in key order",
794 c.name, variant.name, lhs, rhs
795 ),
796 )
797 .with_span(tree.span),
798 ),
799 Ordering::Less => {}
800 }
801 }
802 }
803 // `#[non_exhaustive]` catch-all: emitted when a future
804 // Multiplicity variant lands in dsl-kit-schema before this
805 // arm has been extended to handle it. Not reachable inside
806 // the workspace (both crates are versioned together) but
807 // required by the type contract and useful for
808 // out-of-workspace consumers pinned to an older parse.
809 _ => {
810 out.push(
811 Diagnostic::error(
812 codes::UNKNOWN_MULTIPLICITY,
813 format!(
814 "child slot `{}` on variant `{}` uses an unrecognised \
815 Multiplicity variant (upgrade dsl-kit-parse to a version \
816 that knows about it)",
817 c.name, variant.name
818 ),
819 )
820 .with_span(tree.span),
821 );
822 }
823 }
824 }
825
826 // Same pair-hint precomputation as check_fields, sharing the
827 // "declared but currently absent" set across both diagnostics.
828 let missing = missing_slot_names(tree, variant);
829 let all_slots = all_slot_names(variant);
830
831 // Unknown child slots — both halves, since an undeclared name is
832 // equally unknown whether it arrived keyed or positional.
833 for name in slot_names_in_tree(tree) {
834 if variant.children.iter().any(|c| c.name == name) {
835 continue;
836 }
837 if variant.fields.iter().any(|f| f.name == name) {
838 out.push(
839 Diagnostic::error(
840 codes::FIELD_AS_CHILD,
841 format!(
842 "`{}` on variant `{}` is a payload field, not a child slot \
843 (move it under `fields`)",
844 name, variant.name
845 ),
846 )
847 .with_span(tree.span),
848 );
849 } else {
850 let msg = format_unknown_slot(
851 "child slot",
852 name,
853 &variant.name,
854 &all_slots,
855 &missing,
856 suggester,
857 );
858 out.push(Diagnostic::error(codes::UNKNOWN_CHILD, msg).with_span(tree.span));
859 }
860 }
861}
862
863/// Every child slot name present on `tree`, positional slots first
864/// then keyed ones. The two vectors share a single namespace, so both
865/// the duplicate scan and the unknown-slot scan walk this sequence
866/// rather than either vector alone.
867fn slot_names_in_tree(tree: &ParseTree) -> impl Iterator<Item = &str> {
868 tree.children
869 .iter()
870 .map(|(n, _)| n.as_str())
871 .chain(tree.keyed_children.iter().map(|(n, _)| n.as_str()))
872}
873
874/// Builds the [`codes::KEYED_SLOT_SHAPE`] diagnostic. `positional_seen`
875/// distinguishes the two directions: `true` = a `Map`-declared slot
876/// arrived under [`ParseTree::children`], `false` = a positional slot
877/// arrived under [`ParseTree::keyed_children`].
878fn diag_keying(
879 variant: &VariantSchema,
880 child: &ChildSchema,
881 positional_seen: bool,
882 span: Option<Span>,
883) -> Diagnostic {
884 let msg = if positional_seen {
885 format!(
886 "child slot `{}` on variant `{}` declares Multiplicity::Map — its children \
887 must be supplied as keyed entries, not as a positional list",
888 child.name, variant.name
889 )
890 } else {
891 format!(
892 "child slot `{}` on variant `{}` is positional ({}) — its children must be \
893 supplied as a plain list, not as keyed entries",
894 child.name,
895 variant.name,
896 child.multiplicity.as_str()
897 )
898 };
899 Diagnostic::error(codes::KEYED_SLOT_SHAPE, msg).with_span(span)
900}
901
902/// Names of every declared payload field and child slot on
903/// `variant`, in that order. Used as the `all_candidates` slice for
904/// [`format_unknown_slot`].
905pub(crate) fn all_slot_names(variant: &VariantSchema) -> Vec<&str> {
906 variant
907 .fields
908 .iter()
909 .map(|f| f.name.as_str())
910 .chain(variant.children.iter().map(|c| c.name.as_str()))
911 .collect()
912}
913
914/// Names of declared slots that are **not** currently present on
915/// `tree`. Includes fields with no matching entry in `tree.fields`
916/// and children whose slot has zero occurrences on the tree. Feeds
917/// [`format_unknown_slot`]'s `(missing)` pair-hint marker.
918pub(crate) fn missing_slot_names<'a>(tree: &ParseTree, variant: &'a VariantSchema) -> Vec<&'a str> {
919 let mut out = Vec::new();
920 for f in &variant.fields {
921 // Optional fields are never "missing" for pair-hint purposes:
922 // their absence is a valid shape, so pointing at them from an
923 // unknown-slot suggestion would misdirect the reader.
924 if f.optional {
925 continue;
926 }
927 if tree.field(&f.name).is_none() {
928 out.push(f.name.as_str());
929 }
930 }
931 for c in &variant.children {
932 // A slot counts as present when it carries entries in either
933 // half — a keyed slot supplied positionally (or vice versa)
934 // already earns its own `KEYED_SLOT_SHAPE` diagnostic, and
935 // listing it as "missing" on top of that would misdirect.
936 let positional = tree
937 .child_slot(&c.name)
938 .map(<[ParseTree]>::len)
939 .unwrap_or(0);
940 let keyed = tree
941 .keyed_child_slot(&c.name)
942 .map(<[(String, ParseTree)]>::len)
943 .unwrap_or(0);
944 if positional + keyed == 0 {
945 out.push(c.name.as_str());
946 }
947 }
948 out
949}
950
951fn diag_arity(
952 code: &'static str,
953 variant: &VariantSchema,
954 child: &ChildSchema,
955 count: usize,
956 span: Option<Span>,
957) -> Diagnostic {
958 let expected = match child.multiplicity {
959 Multiplicity::One => "exactly one child",
960 Multiplicity::Optional => "at most one child",
961 Multiplicity::Many => "zero or more children",
962 // `Map` never enters `diag_arity` in practice — keyed slots
963 // accept zero-or-more entries, so `check_children` has no
964 // arity complaint to raise for them (only `DUPLICATE_KEY`).
965 // Kept explicit (rather than folded into the `_` arm) so a
966 // future change that routes Map through here gets a Map-shaped
967 // label instead of the generic "unknown multiplicity" fallback.
968 Multiplicity::Map => "any number of keyed children",
969 // `#[non_exhaustive]` catch-all — see the sibling arm in
970 // `check_children` for the versioning rationale.
971 _ => "a shape this build of dsl-kit-parse does not recognise",
972 };
973 Diagnostic::error(
974 code,
975 format!(
976 "child slot `{}` on variant `{}` expects {} but got {}",
977 child.name, variant.name, expected, count
978 ),
979 )
980 .with_span(span)
981}
982
983// ---------------------------------------------------------------------------
984// Built-in Suggester (case-insensitive Levenshtein, cutoff = max(query.len, 1))
985// ---------------------------------------------------------------------------
986
987/// Default [`Suggester`] used by [`check_conformance`] and the serde
988/// bridge when no explicit suggester is supplied.
989///
990/// Backed by an ASCII-case-insensitive Levenshtein edit distance with
991/// cutoff `max(query.len(), 1)` — the same behaviour the crate has
992/// shipped since Round 1, kept internal so the parser does not need
993/// to depend on the plugin crate.
994pub(crate) struct BuiltinLevenshteinSuggester;
995
996impl Suggester for BuiltinLevenshteinSuggester {
997 fn suggest<'a>(&self, query: &str, candidates: &'a [&str]) -> Vec<Suggestion<'a>> {
998 let cutoff = query.chars().count().max(1);
999 let mut scored: Vec<(usize, &'a str)> = candidates
1000 .iter()
1001 .map(|c| (levenshtein(query, c), *c))
1002 .filter(|(d, _)| *d <= cutoff)
1003 .collect();
1004 scored.sort_by(|(da, na), (db, nb)| da.cmp(db).then_with(|| na.cmp(nb)));
1005 scored.truncate(3);
1006 scored
1007 .into_iter()
1008 .map(|(d, name)| Suggestion {
1009 candidate: name,
1010 score: normalise_edit(d, query, name),
1011 })
1012 .collect()
1013 }
1014}
1015
1016fn normalise_edit(distance: usize, a: &str, b: &str) -> f64 {
1017 let max_len = a.chars().count().max(b.chars().count());
1018 if max_len == 0 {
1019 return 1.0;
1020 }
1021 1.0 - (distance as f64 / max_len as f64)
1022}
1023
1024fn levenshtein(a: &str, b: &str) -> usize {
1025 let a: Vec<char> = a.chars().collect();
1026 let b: Vec<char> = b.chars().collect();
1027 let (m, n) = (a.len(), b.len());
1028 if m == 0 {
1029 return n;
1030 }
1031 if n == 0 {
1032 return m;
1033 }
1034 let mut prev: Vec<usize> = (0..=n).collect();
1035 let mut curr: Vec<usize> = vec![0; n + 1];
1036 for i in 1..=m {
1037 curr[0] = i;
1038 for j in 1..=n {
1039 let cost = if a[i - 1].eq_ignore_ascii_case(&b[j - 1]) {
1040 0
1041 } else {
1042 1
1043 };
1044 curr[j] = (curr[j - 1] + 1).min(prev[j] + 1).min(prev[j - 1] + cost);
1045 }
1046 std::mem::swap(&mut prev, &mut curr);
1047 }
1048 prev[n]
1049}
1050
1051// ---------------------------------------------------------------------------
1052// Build helpers (used by #[derive(DslBuild)] code emission)
1053// ---------------------------------------------------------------------------
1054
1055/// Extracts a payload field into `T`.
1056///
1057/// Dispatches on the field's [`RawValue`] arm:
1058///
1059/// - [`RawValue::Json`] → `serde_json::from_value::<T>`.
1060/// - [`RawValue::Text`] → `T::from_str` (G-2: PEG front-end path).
1061///
1062/// This means the derive works with either front-end unchanged — the
1063/// front-end picks the payload representation, the derive is agnostic.
1064/// `T` must therefore satisfy both bounds; every primitive the kit
1065/// currently uses (`String`, `i64`, `u32`, `bool`, `f64`) does.
1066///
1067/// This helper is intended for use by `#[derive(DslBuild)]`-generated
1068/// code but is usable directly by hand-written [`DslBuild`] impls.
1069pub fn build_field<T>(tree: &ParseTree, name: &str) -> Result<T, BuildError>
1070where
1071 T: serde::de::DeserializeOwned + std::str::FromStr,
1072 <T as std::str::FromStr>::Err: std::fmt::Display,
1073{
1074 match tree.field(name) {
1075 Some(RawValue::Json(v)) => serde_json::from_value(v.clone()).map_err(|e| {
1076 BuildError::single(
1077 Diagnostic::error(codes::FIELD_TYPE, format!("field `{name}`: {e}"))
1078 .with_span(tree.span),
1079 )
1080 }),
1081 Some(RawValue::Text(s)) => s.parse::<T>().map_err(|e| {
1082 BuildError::single(
1083 Diagnostic::error(codes::FIELD_TYPE, format!("field `{name}`: {e}"))
1084 .with_span(tree.span),
1085 )
1086 }),
1087 None => Err(BuildError::single(
1088 Diagnostic::error(
1089 codes::MISSING_FIELD,
1090 format!("missing required field `{name}`"),
1091 )
1092 .with_span(tree.span),
1093 )),
1094 }
1095}
1096
1097/// Extracts an optional payload field into `Option<T>`.
1098///
1099/// Companion to [`build_field`] for fields whose Rust type is
1100/// `Option<T>` — the `#[derive(DslBuild)]` default path routes here
1101/// automatically for payload `Option<T>` types (see the derive docs).
1102///
1103/// Resolution rules:
1104///
1105/// - Absent field → `Ok(None)` (this is the "AI-emit omits noise"
1106/// contract — schema-level `optional: true` skips the
1107/// `MISSING_FIELD` diagnostic so absence reaches here).
1108/// - [`RawValue::Json`] with a `null` value → `Ok(None)`.
1109/// - [`RawValue::Text`] whose text is the literal `"none"` (the
1110/// canonical-syntax keyword produced by `schema_gen`) → `Ok(None)`.
1111/// - Any other value → delegate to [`build_field`], wrap in `Some`.
1112///
1113/// `T` must satisfy the same `DeserializeOwned + FromStr` bounds as
1114/// [`build_field`] because the delegate path uses it.
1115pub fn build_field_optional<T>(tree: &ParseTree, name: &str) -> Result<Option<T>, BuildError>
1116where
1117 T: serde::de::DeserializeOwned + std::str::FromStr,
1118 <T as std::str::FromStr>::Err: std::fmt::Display,
1119{
1120 match tree.field(name) {
1121 None => Ok(None),
1122 Some(RawValue::Json(Value::Null)) => Ok(None),
1123 Some(RawValue::Text(s)) if s == "none" => Ok(None),
1124 Some(_) => build_field::<T>(tree, name).map(Some),
1125 }
1126}
1127
1128/// Extracts a payload field into `Vec<T>`.
1129///
1130/// Companion to [`build_field`] for fields whose Rust type is
1131/// `Vec<T>` — the `#[derive(DslBuild)]` default path routes here
1132/// automatically for payload `Vec<T>` types (see the derive docs).
1133///
1134/// Resolution rules:
1135///
1136/// - Absent field → `Ok(vec![])` (schema-level `optional: true` skips
1137/// the `MISSING_FIELD` diagnostic; missing = empty list).
1138/// - [`RawValue::Json`] with a `null` value → `Ok(vec![])`.
1139/// - [`RawValue::Json`] with an array → `serde_json::from_value`
1140/// over the whole array.
1141/// - [`RawValue::Text`] whose trimmed body is empty → `Ok(vec![])`.
1142/// - [`RawValue::Text`] otherwise → parse the text as a JSON array
1143/// (`serde_json::from_str::<Vec<T>>`). The canonical-syntax
1144/// production for `Vec<String>` (`[ "a", "b" ]`) is JSON-parsable
1145/// as-is; hand-authored value productions that follow the same
1146/// bracketed shape work unchanged.
1147///
1148/// `T` must implement `serde::de::DeserializeOwned` — no `FromStr`
1149/// bound is needed because the text path routes through
1150/// `serde_json::from_str` rather than element-wise parsing.
1151pub fn build_field_vec<T>(tree: &ParseTree, name: &str) -> Result<Vec<T>, BuildError>
1152where
1153 T: serde::de::DeserializeOwned,
1154{
1155 match tree.field(name) {
1156 None => Ok(Vec::new()),
1157 Some(RawValue::Json(Value::Null)) => Ok(Vec::new()),
1158 Some(RawValue::Json(v)) => serde_json::from_value(v.clone()).map_err(|e| {
1159 BuildError::single(
1160 Diagnostic::error(codes::FIELD_TYPE, format!("field `{name}`: {e}"))
1161 .with_span(tree.span),
1162 )
1163 }),
1164 Some(RawValue::Text(s)) => {
1165 let trimmed = s.trim();
1166 if trimmed.is_empty() {
1167 return Ok(Vec::new());
1168 }
1169 serde_json::from_str(trimmed).map_err(|e| {
1170 BuildError::single(
1171 Diagnostic::error(codes::FIELD_TYPE, format!("field `{name}`: {e}"))
1172 .with_span(tree.span),
1173 )
1174 })
1175 }
1176 }
1177}
1178
1179/// Extracts a payload field's raw text production.
1180///
1181/// Convenience for `#[dsl_build(with = ...)]` converter functions,
1182/// which typically match on the spelling the grammar (often a
1183/// `schema_gen::SyntaxOverrides` value production) captured. Errors
1184/// mirror [`build_field`]: [`codes::MISSING_FIELD`] when absent,
1185/// [`codes::FIELD_TYPE`] when the field carries a
1186/// [`RawValue::Json`] payload instead of text.
1187pub fn field_text<'t>(tree: &'t ParseTree, name: &str) -> Result<&'t str, BuildError> {
1188 match tree.field(name) {
1189 Some(RawValue::Text(s)) => Ok(s),
1190 Some(RawValue::Json(_)) => Err(BuildError::single(
1191 Diagnostic::error(
1192 codes::FIELD_TYPE,
1193 format!("field `{name}`: expected a text production, found JSON"),
1194 )
1195 .with_span(tree.span),
1196 )),
1197 None => Err(BuildError::single(
1198 Diagnostic::error(
1199 codes::MISSING_FIELD,
1200 format!("missing required field `{name}`"),
1201 )
1202 .with_span(tree.span),
1203 )),
1204 }
1205}
1206
1207/// Builds the single child of a [`Multiplicity::One`] slot.
1208///
1209/// Returns [`codes::ARITY_ONE`] if the slot is absent or holds more
1210/// than one subtree. Errors from the recursive
1211/// [`DslBuild::from_parse_tree`] call bubble up as-is.
1212pub fn build_child_one<T: DslBuild>(
1213 tree: &ParseTree,
1214 name: &str,
1215 ids: &IdGen,
1216) -> Result<T, BuildError> {
1217 let slot = tree.child_slot(name).unwrap_or(&[]);
1218 if slot.len() != 1 {
1219 return Err(BuildError::single(
1220 Diagnostic::error(
1221 codes::ARITY_ONE,
1222 format!(
1223 "child slot `{name}` expects exactly one child but got {}",
1224 slot.len()
1225 ),
1226 )
1227 .with_span(tree.span),
1228 ));
1229 }
1230 T::from_parse_tree(&slot[0], ids)
1231}
1232
1233/// Builds the (optional) child of a [`Multiplicity::Optional`] slot.
1234///
1235/// Returns [`codes::ARITY_OPTIONAL`] if the slot holds more than one
1236/// subtree. Missing / empty slots yield `Ok(None)`.
1237pub fn build_child_optional<T: DslBuild>(
1238 tree: &ParseTree,
1239 name: &str,
1240 ids: &IdGen,
1241) -> Result<Option<T>, BuildError> {
1242 let slot = tree.child_slot(name).unwrap_or(&[]);
1243 match slot.len() {
1244 0 => Ok(None),
1245 1 => Ok(Some(T::from_parse_tree(&slot[0], ids)?)),
1246 n => Err(BuildError::single(
1247 Diagnostic::error(
1248 codes::ARITY_OPTIONAL,
1249 format!("child slot `{name}` expects at most one child but got {n}"),
1250 )
1251 .with_span(tree.span),
1252 )),
1253 }
1254}
1255
1256/// Builds every child of a [`Multiplicity::Many`] slot.
1257///
1258/// Diagnostics from individual children are collected across the whole
1259/// slot before returning, so a partially-broken batch surfaces every
1260/// bad subtree at once rather than the first-encountered one.
1261pub fn build_child_many<T: DslBuild>(
1262 tree: &ParseTree,
1263 name: &str,
1264 ids: &IdGen,
1265) -> Result<Vec<T>, BuildError> {
1266 let slot = tree.child_slot(name).unwrap_or(&[]);
1267 let mut out = Vec::with_capacity(slot.len());
1268 let mut diags = Vec::new();
1269 for child in slot {
1270 match T::from_parse_tree(child, ids) {
1271 Ok(v) => out.push(v),
1272 Err(mut e) => diags.append(&mut e.diagnostics),
1273 }
1274 }
1275 if diags.is_empty() {
1276 Ok(out)
1277 } else {
1278 Err(BuildError::new(diags))
1279 }
1280}
1281
1282/// Builds every entry of a scalar-valued [`Multiplicity::Map`] slot
1283/// (Shape 1 of the tracking issue) into a [`BTreeMap`] keyed by the
1284/// front-end's keys.
1285///
1286/// Each entry in the tree's [`ParseTree::keyed_children`] slot is
1287/// expected to be a leaf [`ParseTree`] whose single payload field is
1288/// named `"value"` — the front-end wraps every scalar value in that
1289/// canonical shape. The convention gives `build_scalar_map` a stable
1290/// spot to fetch the payload from without the derive having to know
1291/// about the wrapping.
1292///
1293/// Like [`build_child_map`], duplicate keys emit a
1294/// [`codes::DUPLICATE_KEY`] diagnostic rather than a silent
1295/// last-one-wins overwrite. Missing `"value"` fields inside an entry
1296/// surface as [`codes::MISSING_FIELD`] and payload type errors as
1297/// [`codes::FIELD_TYPE`] — the same envelope as [`build_field`].
1298///
1299/// `V` must satisfy `serde::de::DeserializeOwned + FromStr` so both
1300/// front-ends (JSON payload / PEG text) can convert values without
1301/// element-wise divergence.
1302pub fn build_scalar_map<V>(tree: &ParseTree, name: &str) -> Result<BTreeMap<String, V>, BuildError>
1303where
1304 V: serde::de::DeserializeOwned + std::str::FromStr,
1305 <V as std::str::FromStr>::Err: std::fmt::Display,
1306{
1307 let slot = tree.keyed_child_slot(name).unwrap_or(&[]);
1308 let mut out = BTreeMap::new();
1309 let mut diags = Vec::new();
1310 for (key, entry) in slot {
1311 match build_field::<V>(entry, "value") {
1312 Ok(v) => {
1313 if out.insert(key.clone(), v).is_some() {
1314 diags.push(
1315 Diagnostic::error(
1316 codes::DUPLICATE_KEY,
1317 format!("keyed child slot `{name}` carries key `{key}` more than once"),
1318 )
1319 .with_span(tree.span),
1320 );
1321 }
1322 }
1323 Err(mut e) => diags.append(&mut e.diagnostics),
1324 }
1325 }
1326 if diags.is_empty() {
1327 Ok(out)
1328 } else {
1329 Err(BuildError::new(diags))
1330 }
1331}
1332
1333/// Builds every entry of a [`Multiplicity::Map`] slot into a
1334/// [`BTreeMap`] keyed by the front-end's keys.
1335///
1336/// [`BTreeMap`] rather than `HashMap` on purpose: the consumer's
1337/// iteration order is part of the observable AST (walks, re-emission,
1338/// canonical text), so it has to be deterministic. The derive
1339/// recognises `BTreeMap<String, T>` for the same reason.
1340///
1341/// Like [`build_child_many`], diagnostics from individual entries are
1342/// collected across the whole slot before returning. A key appearing
1343/// twice is a [`codes::DUPLICATE_KEY`] error rather than a silent
1344/// last-one-wins overwrite — the parse would otherwise drop a subtree
1345/// the author wrote.
1346pub fn build_child_map<T: DslBuild>(
1347 tree: &ParseTree,
1348 name: &str,
1349 ids: &IdGen,
1350) -> Result<BTreeMap<String, T>, BuildError> {
1351 let slot = tree.keyed_child_slot(name).unwrap_or(&[]);
1352 let mut out = BTreeMap::new();
1353 let mut diags = Vec::new();
1354 for (key, child) in slot {
1355 match T::from_parse_tree(child, ids) {
1356 Ok(v) => {
1357 if out.insert(key.clone(), v).is_some() {
1358 diags.push(
1359 Diagnostic::error(
1360 codes::DUPLICATE_KEY,
1361 format!("keyed child slot `{name}` carries key `{key}` more than once"),
1362 )
1363 .with_span(tree.span),
1364 );
1365 }
1366 }
1367 Err(mut e) => diags.append(&mut e.diagnostics),
1368 }
1369 }
1370 if diags.is_empty() {
1371 Ok(out)
1372 } else {
1373 Err(BuildError::new(diags))
1374 }
1375}
1376
1377// ---------------------------------------------------------------------------
1378// Tests
1379// ---------------------------------------------------------------------------
1380
1381#[cfg(test)]
1382mod tests {
1383 use super::*;
1384 use dsl_kit_schema::{
1385 ChildSchema, ChildValueShape, FieldSchema, Multiplicity, NodeSchema, VariantSchema,
1386 };
1387
1388 fn schema_add_lit() -> NodeSchema {
1389 NodeSchema {
1390 name: "Expr".into(),
1391 variants: vec![
1392 VariantSchema {
1393 name: "Lit".into(),
1394 fields: vec![FieldSchema {
1395 name: "value".into(),
1396 ty: "i64".into(),
1397 optional: false,
1398 }],
1399 children: vec![],
1400 },
1401 VariantSchema {
1402 name: "Add".into(),
1403 fields: vec![],
1404 children: vec![
1405 ChildSchema {
1406 name: "lhs".into(),
1407 multiplicity: Multiplicity::One,
1408 value_shape: ChildValueShape::Recursive,
1409 },
1410 ChildSchema {
1411 name: "rhs".into(),
1412 multiplicity: Multiplicity::One,
1413 value_shape: ChildValueShape::Recursive,
1414 },
1415 ],
1416 },
1417 VariantSchema {
1418 name: "Let".into(),
1419 fields: vec![FieldSchema {
1420 name: "name".into(),
1421 ty: "String".into(),
1422 optional: false,
1423 }],
1424 children: vec![
1425 ChildSchema {
1426 name: "value".into(),
1427 multiplicity: Multiplicity::One,
1428 value_shape: ChildValueShape::Recursive,
1429 },
1430 ChildSchema {
1431 name: "body".into(),
1432 multiplicity: Multiplicity::One,
1433 value_shape: ChildValueShape::Recursive,
1434 },
1435 ],
1436 },
1437 ],
1438 }
1439 }
1440
1441 fn lit(v: i64) -> ParseTree {
1442 let mut t = ParseTree::new("Lit");
1443 t.fields.push(("value".into(), RawValue::Json(json!(v))));
1444 t
1445 }
1446
1447 #[test]
1448 fn ok_lit() {
1449 let schema = schema_add_lit();
1450 assert!(check_conformance(&lit(1), &schema).is_empty());
1451 }
1452
1453 #[test]
1454 fn ok_add_with_two_children() {
1455 let schema = schema_add_lit();
1456 let mut add = ParseTree::new("Add");
1457 add.children.push(("lhs".into(), vec![lit(1)]));
1458 add.children.push(("rhs".into(), vec![lit(2)]));
1459 assert!(check_conformance(&add, &schema).is_empty());
1460 }
1461
1462 #[test]
1463 fn unknown_variant_lists_candidates() {
1464 let schema = schema_add_lit();
1465 let tree = ParseTree::new("Aad"); // typo of Add
1466 let diags = check_conformance(&tree, &schema);
1467 assert_eq!(diags.len(), 1);
1468 assert_eq!(diags[0].code, codes::UNKNOWN_VARIANT);
1469 assert!(
1470 diags[0].message.contains("Add"),
1471 "expected Add to appear as a candidate; got: {}",
1472 diags[0].message
1473 );
1474 }
1475
1476 #[test]
1477 fn unknown_variant_uses_injected_suggester() {
1478 use dsl_kit_fuzzy::FuzzySuggester;
1479
1480 let schema = schema_add_lit();
1481 let tree = ParseTree::new("Adx"); // Jaro-Winkler prefix bias picks "Add"
1482 let suggester = FuzzySuggester::default();
1483 let diags = check_conformance_with(&tree, &schema, &suggester);
1484 assert_eq!(diags.len(), 1);
1485 assert_eq!(diags[0].code, codes::UNKNOWN_VARIANT);
1486 assert!(
1487 diags[0].message.contains("did you mean") && diags[0].message.contains("Add"),
1488 "expected FuzzySuggester to surface `Add`; got: {}",
1489 diags[0].message
1490 );
1491 }
1492
1493 #[test]
1494 fn unknown_field_suggests_declared_field() {
1495 // The design's canonical example: `taget` should surface `target`
1496 // as a `did you mean` hint on the UNKNOWN_FIELD diagnostic.
1497 let schema = NodeSchema {
1498 name: "Cfg".into(),
1499 variants: vec![VariantSchema {
1500 name: "Load".into(),
1501 fields: vec![
1502 FieldSchema {
1503 name: "target".into(),
1504 ty: "String".into(),
1505 optional: false,
1506 },
1507 FieldSchema {
1508 name: "count".into(),
1509 ty: "u32".into(),
1510 optional: false,
1511 },
1512 ],
1513 children: vec![],
1514 }],
1515 };
1516 let mut tree = ParseTree::new("Load");
1517 tree.fields
1518 .push(("taget".into(), RawValue::Json(json!("a"))));
1519 tree.fields.push(("count".into(), RawValue::Json(json!(1))));
1520 let diags = check_conformance(&tree, &schema);
1521
1522 let unknown = diags
1523 .iter()
1524 .find(|d| d.code == codes::UNKNOWN_FIELD)
1525 .expect("expected an UNKNOWN_FIELD diagnostic for `taget`");
1526 assert!(
1527 unknown.message.contains("did you mean") && unknown.message.contains("target"),
1528 "expected `target` in the hint, got: {}",
1529 unknown.message
1530 );
1531 assert!(
1532 unknown.message.contains("(missing)"),
1533 "expected `(missing)` pair-hint since `target` is a required field \
1534 not present on the tree; got: {}",
1535 unknown.message
1536 );
1537 }
1538
1539 #[test]
1540 fn unknown_child_suggests_declared_child() {
1541 let schema = schema_add_lit();
1542 let mut add = ParseTree::new("Add");
1543 // `lsh` is a typo of `lhs`; `rhs` is present so only `lhs`
1544 // remains in the missing set.
1545 add.children.push(("lsh".into(), vec![lit(1)]));
1546 add.children.push(("rhs".into(), vec![lit(2)]));
1547 let diags = check_conformance(&add, &schema);
1548
1549 let unknown = diags
1550 .iter()
1551 .find(|d| d.code == codes::UNKNOWN_CHILD)
1552 .expect("expected an UNKNOWN_CHILD diagnostic for `lsh`");
1553 assert!(
1554 unknown.message.contains("did you mean") && unknown.message.contains("lhs"),
1555 "expected `lhs` in the hint, got: {}",
1556 unknown.message
1557 );
1558 assert!(
1559 unknown.message.contains("(missing)"),
1560 "expected `(missing)` pair-hint on the `lhs` suggestion since \
1561 the `lhs` slot is required but absent; got: {}",
1562 unknown.message
1563 );
1564 }
1565
1566 #[test]
1567 fn missing_field_is_reported() {
1568 let schema = schema_add_lit();
1569 let tree = ParseTree::new("Lit"); // no "value"
1570 let diags = check_conformance(&tree, &schema);
1571 assert_eq!(diags.len(), 1);
1572 assert_eq!(diags[0].code, codes::MISSING_FIELD);
1573 assert!(diags[0].message.contains("value"));
1574 }
1575
1576 /// Layer 1: absent optional field does NOT trigger `MISSING_FIELD`.
1577 #[test]
1578 fn optional_field_absent_is_conformant() {
1579 let schema = NodeSchema {
1580 name: "Meta".into(),
1581 variants: vec![VariantSchema {
1582 name: "Row".into(),
1583 fields: vec![
1584 FieldSchema::required("id", "u32"),
1585 FieldSchema::optional("description", "Option<String>"),
1586 FieldSchema::optional("tags", "Vec<String>"),
1587 ],
1588 children: vec![],
1589 }],
1590 };
1591 let mut tree = ParseTree::new("Row");
1592 tree.fields.push(("id".into(), RawValue::Json(json!(1))));
1593 // description + tags are absent — must not report MISSING_FIELD.
1594 let diags = check_conformance(&tree, &schema);
1595 assert!(
1596 diags.is_empty(),
1597 "optional fields absent should be clean: {diags:?}",
1598 );
1599 }
1600
1601 /// Layer 1 negative: absent REQUIRED field alongside absent
1602 /// optional fields still reports only the required one.
1603 #[test]
1604 fn optional_field_absence_does_not_shadow_required_missing() {
1605 let schema = NodeSchema {
1606 name: "Meta".into(),
1607 variants: vec![VariantSchema {
1608 name: "Row".into(),
1609 fields: vec![
1610 FieldSchema::required("id", "u32"),
1611 FieldSchema::optional("description", "Option<String>"),
1612 ],
1613 children: vec![],
1614 }],
1615 };
1616 let tree = ParseTree::new("Row"); // absent id + absent description
1617 let diags = check_conformance(&tree, &schema);
1618 assert_eq!(diags.len(), 1);
1619 assert_eq!(diags[0].code, codes::MISSING_FIELD);
1620 assert!(
1621 diags[0].message.contains("id"),
1622 "only `id` is reported missing; got: {}",
1623 diags[0].message,
1624 );
1625 }
1626
1627 /// Layer 1 wire contract: `to_json` emits `optional: true` only
1628 /// when the field is optional, preserving the pre-0.3 layout for
1629 /// required fields.
1630 #[test]
1631 fn field_schema_to_json_omits_optional_when_false() {
1632 let required = FieldSchema::required("id", "u32").to_json();
1633 assert_eq!(required, json!({ "name": "id", "type": "u32" }));
1634 assert!(
1635 required.get("optional").is_none(),
1636 "required field omits the optional key entirely (pre-0.3 layout)",
1637 );
1638 let opt = FieldSchema::optional("description", "Option<String>").to_json();
1639 assert_eq!(
1640 opt,
1641 json!({ "name": "description", "type": "Option<String>", "optional": true }),
1642 );
1643 }
1644
1645 /// Layer 2: `build_field_optional` returns `None` for every
1646 /// canonical form of absence: missing field, JSON null, canonical
1647 /// `none` keyword. Present values flow through `build_field`.
1648 #[test]
1649 fn build_field_optional_covers_every_absence_shape() {
1650 let mut t = ParseTree::new("Row");
1651 // Absent field.
1652 assert_eq!(
1653 build_field_optional::<String>(&t, "description").unwrap(),
1654 None,
1655 );
1656 // JSON null.
1657 t.fields
1658 .push(("description".into(), RawValue::Json(Value::Null)));
1659 assert_eq!(
1660 build_field_optional::<String>(&t, "description").unwrap(),
1661 None,
1662 );
1663 // Canonical "none" keyword (Text path).
1664 let mut t2 = ParseTree::new("Row");
1665 t2.fields
1666 .push(("description".into(), RawValue::Text("none".into())));
1667 assert_eq!(
1668 build_field_optional::<String>(&t2, "description").unwrap(),
1669 None,
1670 );
1671 // Present JSON string.
1672 let mut t3 = ParseTree::new("Row");
1673 t3.fields
1674 .push(("description".into(), RawValue::Json(json!("hi"))));
1675 assert_eq!(
1676 build_field_optional::<String>(&t3, "description").unwrap(),
1677 Some("hi".to_string()),
1678 );
1679 }
1680
1681 /// Layer 2: `build_field_vec` defaults to empty on absence, parses
1682 /// JSON arrays natively, and parses canonical bracketed text
1683 /// productions via `serde_json::from_str`.
1684 #[test]
1685 fn build_field_vec_covers_every_shape() {
1686 // Absent → empty.
1687 let t = ParseTree::new("Row");
1688 assert_eq!(
1689 build_field_vec::<String>(&t, "tags").unwrap(),
1690 Vec::<String>::new()
1691 );
1692 // JSON null → empty.
1693 let mut t2 = ParseTree::new("Row");
1694 t2.fields.push(("tags".into(), RawValue::Json(Value::Null)));
1695 assert_eq!(
1696 build_field_vec::<String>(&t2, "tags").unwrap(),
1697 Vec::<String>::new(),
1698 );
1699 // JSON array.
1700 let mut t3 = ParseTree::new("Row");
1701 t3.fields
1702 .push(("tags".into(), RawValue::Json(json!(["a", "b"]))));
1703 assert_eq!(
1704 build_field_vec::<String>(&t3, "tags").unwrap(),
1705 vec!["a".to_string(), "b".to_string()],
1706 );
1707 // Canonical bracketed text (JSON-parsable as-is).
1708 let mut t4 = ParseTree::new("Row");
1709 t4.fields
1710 .push(("tags".into(), RawValue::Text(r#"["a", "b"]"#.into())));
1711 assert_eq!(
1712 build_field_vec::<String>(&t4, "tags").unwrap(),
1713 vec!["a".to_string(), "b".to_string()],
1714 );
1715 // Empty bracketed text.
1716 let mut t5 = ParseTree::new("Row");
1717 t5.fields.push(("tags".into(), RawValue::Text("[]".into())));
1718 assert_eq!(
1719 build_field_vec::<String>(&t5, "tags").unwrap(),
1720 Vec::<String>::new(),
1721 );
1722 }
1723
1724 #[test]
1725 fn unknown_field_is_reported() {
1726 let schema = schema_add_lit();
1727 let mut tree = lit(3);
1728 tree.fields.push(("extra".into(), RawValue::Json(json!(0))));
1729 let diags = check_conformance(&tree, &schema);
1730 assert_eq!(diags.len(), 1);
1731 assert_eq!(diags[0].code, codes::UNKNOWN_FIELD);
1732 }
1733
1734 #[test]
1735 fn field_and_child_slot_swapped_reports_structural_codes() {
1736 let schema = schema_add_lit();
1737
1738 // A child slot placed under fields.
1739 let mut swap1 = ParseTree::new("Add");
1740 swap1.fields.push(("lhs".into(), RawValue::Json(json!(0))));
1741 swap1.children.push(("rhs".into(), vec![lit(1)]));
1742 // Missing lhs child (arity_one) + child-as-field structural swap
1743 // → two diagnostics.
1744 let diags = check_conformance(&swap1, &schema);
1745 assert!(diags.iter().any(|d| d.code == codes::CHILD_AS_FIELD));
1746 assert!(diags.iter().any(|d| d.code == codes::ARITY_ONE));
1747
1748 // A payload field placed under children.
1749 let mut swap2 = ParseTree::new("Let");
1750 swap2
1751 .children
1752 .push(("name".into(), vec![ParseTree::new("Lit")]));
1753 swap2.children.push(("value".into(), vec![lit(1)]));
1754 swap2.children.push(("body".into(), vec![lit(2)]));
1755 let diags = check_conformance(&swap2, &schema);
1756 assert!(diags.iter().any(|d| d.code == codes::FIELD_AS_CHILD));
1757 assert!(diags.iter().any(|d| d.code == codes::MISSING_FIELD));
1758 }
1759
1760 #[test]
1761 fn arity_one_reports_wrong_count() {
1762 let schema = schema_add_lit();
1763 let mut add = ParseTree::new("Add");
1764 add.children.push(("lhs".into(), vec![lit(1), lit(2)])); // two, not one
1765 add.children.push(("rhs".into(), vec![lit(3)]));
1766 let diags = check_conformance(&add, &schema);
1767 assert_eq!(diags.len(), 1);
1768 assert_eq!(diags[0].code, codes::ARITY_ONE);
1769 assert!(diags[0].message.contains("lhs"));
1770 }
1771
1772 #[test]
1773 fn duplicate_field_and_child_reported() {
1774 let schema = schema_add_lit();
1775 let mut t = ParseTree::new("Lit");
1776 t.fields.push(("value".into(), RawValue::Json(json!(1))));
1777 t.fields.push(("value".into(), RawValue::Json(json!(2))));
1778 let diags = check_conformance(&t, &schema);
1779 assert!(diags.iter().any(|d| d.code == codes::DUPLICATE_FIELD));
1780
1781 let mut a = ParseTree::new("Add");
1782 a.children.push(("lhs".into(), vec![lit(1)]));
1783 a.children.push(("lhs".into(), vec![lit(2)]));
1784 a.children.push(("rhs".into(), vec![lit(3)]));
1785 let diags = check_conformance(&a, &schema);
1786 assert!(diags.iter().any(|d| d.code == codes::DUPLICATE_CHILD));
1787 }
1788
1789 #[test]
1790 fn diagnostic_json_shape() {
1791 let diag = Diagnostic::error("x::y", "boom").with_span(Some(Span::new(3, 7)));
1792 let v = diag.to_json();
1793 assert_eq!(v["severity"], "error");
1794 assert_eq!(v["code"], "x::y");
1795 assert_eq!(v["message"], "boom");
1796 assert_eq!(v["location"]["kind"], "span");
1797 assert_eq!(v["location"]["start"], 3);
1798 assert_eq!(v["location"]["end"], 7);
1799 }
1800
1801 #[test]
1802 fn build_error_display_lists_all() {
1803 let err = BuildError::new(vec![
1804 Diagnostic::error("a::b", "one"),
1805 Diagnostic::error("c::d", "two"),
1806 ]);
1807 let s = format!("{err}");
1808 assert!(s.contains("a::b: one"));
1809 assert!(s.contains("c::d: two"));
1810 }
1811}