Skip to main content

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 [`Multiplicity::Map`] slot into a
1283/// [`BTreeMap`] keyed by the front-end's keys.
1284///
1285/// [`BTreeMap`] rather than `HashMap` on purpose: the consumer's
1286/// iteration order is part of the observable AST (walks, re-emission,
1287/// canonical text), so it has to be deterministic. The derive
1288/// recognises `BTreeMap<String, T>` for the same reason.
1289///
1290/// Like [`build_child_many`], diagnostics from individual entries are
1291/// collected across the whole slot before returning. A key appearing
1292/// twice is a [`codes::DUPLICATE_KEY`] error rather than a silent
1293/// last-one-wins overwrite — the parse would otherwise drop a subtree
1294/// the author wrote.
1295pub fn build_child_map<T: DslBuild>(
1296    tree: &ParseTree,
1297    name: &str,
1298    ids: &IdGen,
1299) -> Result<BTreeMap<String, T>, BuildError> {
1300    let slot = tree.keyed_child_slot(name).unwrap_or(&[]);
1301    let mut out = BTreeMap::new();
1302    let mut diags = Vec::new();
1303    for (key, child) in slot {
1304        match T::from_parse_tree(child, ids) {
1305            Ok(v) => {
1306                if out.insert(key.clone(), v).is_some() {
1307                    diags.push(
1308                        Diagnostic::error(
1309                            codes::DUPLICATE_KEY,
1310                            format!("keyed child slot `{name}` carries key `{key}` more than once"),
1311                        )
1312                        .with_span(tree.span),
1313                    );
1314                }
1315            }
1316            Err(mut e) => diags.append(&mut e.diagnostics),
1317        }
1318    }
1319    if diags.is_empty() {
1320        Ok(out)
1321    } else {
1322        Err(BuildError::new(diags))
1323    }
1324}
1325
1326// ---------------------------------------------------------------------------
1327// Tests
1328// ---------------------------------------------------------------------------
1329
1330#[cfg(test)]
1331mod tests {
1332    use super::*;
1333    use dsl_kit_schema::{ChildSchema, FieldSchema, Multiplicity, NodeSchema, VariantSchema};
1334
1335    fn schema_add_lit() -> NodeSchema {
1336        NodeSchema {
1337            name: "Expr".into(),
1338            variants: vec![
1339                VariantSchema {
1340                    name: "Lit".into(),
1341                    fields: vec![FieldSchema {
1342                        name: "value".into(),
1343                        ty: "i64".into(),
1344                        optional: false,
1345                    }],
1346                    children: vec![],
1347                },
1348                VariantSchema {
1349                    name: "Add".into(),
1350                    fields: vec![],
1351                    children: vec![
1352                        ChildSchema {
1353                            name: "lhs".into(),
1354                            multiplicity: Multiplicity::One,
1355                        },
1356                        ChildSchema {
1357                            name: "rhs".into(),
1358                            multiplicity: Multiplicity::One,
1359                        },
1360                    ],
1361                },
1362                VariantSchema {
1363                    name: "Let".into(),
1364                    fields: vec![FieldSchema {
1365                        name: "name".into(),
1366                        ty: "String".into(),
1367                        optional: false,
1368                    }],
1369                    children: vec![
1370                        ChildSchema {
1371                            name: "value".into(),
1372                            multiplicity: Multiplicity::One,
1373                        },
1374                        ChildSchema {
1375                            name: "body".into(),
1376                            multiplicity: Multiplicity::One,
1377                        },
1378                    ],
1379                },
1380            ],
1381        }
1382    }
1383
1384    fn lit(v: i64) -> ParseTree {
1385        let mut t = ParseTree::new("Lit");
1386        t.fields.push(("value".into(), RawValue::Json(json!(v))));
1387        t
1388    }
1389
1390    #[test]
1391    fn ok_lit() {
1392        let schema = schema_add_lit();
1393        assert!(check_conformance(&lit(1), &schema).is_empty());
1394    }
1395
1396    #[test]
1397    fn ok_add_with_two_children() {
1398        let schema = schema_add_lit();
1399        let mut add = ParseTree::new("Add");
1400        add.children.push(("lhs".into(), vec![lit(1)]));
1401        add.children.push(("rhs".into(), vec![lit(2)]));
1402        assert!(check_conformance(&add, &schema).is_empty());
1403    }
1404
1405    #[test]
1406    fn unknown_variant_lists_candidates() {
1407        let schema = schema_add_lit();
1408        let tree = ParseTree::new("Aad"); // typo of Add
1409        let diags = check_conformance(&tree, &schema);
1410        assert_eq!(diags.len(), 1);
1411        assert_eq!(diags[0].code, codes::UNKNOWN_VARIANT);
1412        assert!(
1413            diags[0].message.contains("Add"),
1414            "expected Add to appear as a candidate; got: {}",
1415            diags[0].message
1416        );
1417    }
1418
1419    #[test]
1420    fn unknown_variant_uses_injected_suggester() {
1421        use dsl_kit_fuzzy::FuzzySuggester;
1422
1423        let schema = schema_add_lit();
1424        let tree = ParseTree::new("Adx"); // Jaro-Winkler prefix bias picks "Add"
1425        let suggester = FuzzySuggester::default();
1426        let diags = check_conformance_with(&tree, &schema, &suggester);
1427        assert_eq!(diags.len(), 1);
1428        assert_eq!(diags[0].code, codes::UNKNOWN_VARIANT);
1429        assert!(
1430            diags[0].message.contains("did you mean") && diags[0].message.contains("Add"),
1431            "expected FuzzySuggester to surface `Add`; got: {}",
1432            diags[0].message
1433        );
1434    }
1435
1436    #[test]
1437    fn unknown_field_suggests_declared_field() {
1438        // The design's canonical example: `taget` should surface `target`
1439        // as a `did you mean` hint on the UNKNOWN_FIELD diagnostic.
1440        let schema = NodeSchema {
1441            name: "Cfg".into(),
1442            variants: vec![VariantSchema {
1443                name: "Load".into(),
1444                fields: vec![
1445                    FieldSchema {
1446                        name: "target".into(),
1447                        ty: "String".into(),
1448                        optional: false,
1449                    },
1450                    FieldSchema {
1451                        name: "count".into(),
1452                        ty: "u32".into(),
1453                        optional: false,
1454                    },
1455                ],
1456                children: vec![],
1457            }],
1458        };
1459        let mut tree = ParseTree::new("Load");
1460        tree.fields
1461            .push(("taget".into(), RawValue::Json(json!("a"))));
1462        tree.fields.push(("count".into(), RawValue::Json(json!(1))));
1463        let diags = check_conformance(&tree, &schema);
1464
1465        let unknown = diags
1466            .iter()
1467            .find(|d| d.code == codes::UNKNOWN_FIELD)
1468            .expect("expected an UNKNOWN_FIELD diagnostic for `taget`");
1469        assert!(
1470            unknown.message.contains("did you mean") && unknown.message.contains("target"),
1471            "expected `target` in the hint, got: {}",
1472            unknown.message
1473        );
1474        assert!(
1475            unknown.message.contains("(missing)"),
1476            "expected `(missing)` pair-hint since `target` is a required field \
1477             not present on the tree; got: {}",
1478            unknown.message
1479        );
1480    }
1481
1482    #[test]
1483    fn unknown_child_suggests_declared_child() {
1484        let schema = schema_add_lit();
1485        let mut add = ParseTree::new("Add");
1486        // `lsh` is a typo of `lhs`; `rhs` is present so only `lhs`
1487        // remains in the missing set.
1488        add.children.push(("lsh".into(), vec![lit(1)]));
1489        add.children.push(("rhs".into(), vec![lit(2)]));
1490        let diags = check_conformance(&add, &schema);
1491
1492        let unknown = diags
1493            .iter()
1494            .find(|d| d.code == codes::UNKNOWN_CHILD)
1495            .expect("expected an UNKNOWN_CHILD diagnostic for `lsh`");
1496        assert!(
1497            unknown.message.contains("did you mean") && unknown.message.contains("lhs"),
1498            "expected `lhs` in the hint, got: {}",
1499            unknown.message
1500        );
1501        assert!(
1502            unknown.message.contains("(missing)"),
1503            "expected `(missing)` pair-hint on the `lhs` suggestion since \
1504             the `lhs` slot is required but absent; got: {}",
1505            unknown.message
1506        );
1507    }
1508
1509    #[test]
1510    fn missing_field_is_reported() {
1511        let schema = schema_add_lit();
1512        let tree = ParseTree::new("Lit"); // no "value"
1513        let diags = check_conformance(&tree, &schema);
1514        assert_eq!(diags.len(), 1);
1515        assert_eq!(diags[0].code, codes::MISSING_FIELD);
1516        assert!(diags[0].message.contains("value"));
1517    }
1518
1519    /// Layer 1: absent optional field does NOT trigger `MISSING_FIELD`.
1520    #[test]
1521    fn optional_field_absent_is_conformant() {
1522        let schema = NodeSchema {
1523            name: "Meta".into(),
1524            variants: vec![VariantSchema {
1525                name: "Row".into(),
1526                fields: vec![
1527                    FieldSchema::required("id", "u32"),
1528                    FieldSchema::optional("description", "Option<String>"),
1529                    FieldSchema::optional("tags", "Vec<String>"),
1530                ],
1531                children: vec![],
1532            }],
1533        };
1534        let mut tree = ParseTree::new("Row");
1535        tree.fields.push(("id".into(), RawValue::Json(json!(1))));
1536        // description + tags are absent — must not report MISSING_FIELD.
1537        let diags = check_conformance(&tree, &schema);
1538        assert!(
1539            diags.is_empty(),
1540            "optional fields absent should be clean: {diags:?}",
1541        );
1542    }
1543
1544    /// Layer 1 negative: absent REQUIRED field alongside absent
1545    /// optional fields still reports only the required one.
1546    #[test]
1547    fn optional_field_absence_does_not_shadow_required_missing() {
1548        let schema = NodeSchema {
1549            name: "Meta".into(),
1550            variants: vec![VariantSchema {
1551                name: "Row".into(),
1552                fields: vec![
1553                    FieldSchema::required("id", "u32"),
1554                    FieldSchema::optional("description", "Option<String>"),
1555                ],
1556                children: vec![],
1557            }],
1558        };
1559        let tree = ParseTree::new("Row"); // absent id + absent description
1560        let diags = check_conformance(&tree, &schema);
1561        assert_eq!(diags.len(), 1);
1562        assert_eq!(diags[0].code, codes::MISSING_FIELD);
1563        assert!(
1564            diags[0].message.contains("id"),
1565            "only `id` is reported missing; got: {}",
1566            diags[0].message,
1567        );
1568    }
1569
1570    /// Layer 1 wire contract: `to_json` emits `optional: true` only
1571    /// when the field is optional, preserving the pre-0.3 layout for
1572    /// required fields.
1573    #[test]
1574    fn field_schema_to_json_omits_optional_when_false() {
1575        let required = FieldSchema::required("id", "u32").to_json();
1576        assert_eq!(required, json!({ "name": "id", "type": "u32" }));
1577        assert!(
1578            required.get("optional").is_none(),
1579            "required field omits the optional key entirely (pre-0.3 layout)",
1580        );
1581        let opt = FieldSchema::optional("description", "Option<String>").to_json();
1582        assert_eq!(
1583            opt,
1584            json!({ "name": "description", "type": "Option<String>", "optional": true }),
1585        );
1586    }
1587
1588    /// Layer 2: `build_field_optional` returns `None` for every
1589    /// canonical form of absence: missing field, JSON null, canonical
1590    /// `none` keyword. Present values flow through `build_field`.
1591    #[test]
1592    fn build_field_optional_covers_every_absence_shape() {
1593        let mut t = ParseTree::new("Row");
1594        // Absent field.
1595        assert_eq!(
1596            build_field_optional::<String>(&t, "description").unwrap(),
1597            None,
1598        );
1599        // JSON null.
1600        t.fields
1601            .push(("description".into(), RawValue::Json(Value::Null)));
1602        assert_eq!(
1603            build_field_optional::<String>(&t, "description").unwrap(),
1604            None,
1605        );
1606        // Canonical "none" keyword (Text path).
1607        let mut t2 = ParseTree::new("Row");
1608        t2.fields
1609            .push(("description".into(), RawValue::Text("none".into())));
1610        assert_eq!(
1611            build_field_optional::<String>(&t2, "description").unwrap(),
1612            None,
1613        );
1614        // Present JSON string.
1615        let mut t3 = ParseTree::new("Row");
1616        t3.fields
1617            .push(("description".into(), RawValue::Json(json!("hi"))));
1618        assert_eq!(
1619            build_field_optional::<String>(&t3, "description").unwrap(),
1620            Some("hi".to_string()),
1621        );
1622    }
1623
1624    /// Layer 2: `build_field_vec` defaults to empty on absence, parses
1625    /// JSON arrays natively, and parses canonical bracketed text
1626    /// productions via `serde_json::from_str`.
1627    #[test]
1628    fn build_field_vec_covers_every_shape() {
1629        // Absent → empty.
1630        let t = ParseTree::new("Row");
1631        assert_eq!(
1632            build_field_vec::<String>(&t, "tags").unwrap(),
1633            Vec::<String>::new()
1634        );
1635        // JSON null → empty.
1636        let mut t2 = ParseTree::new("Row");
1637        t2.fields.push(("tags".into(), RawValue::Json(Value::Null)));
1638        assert_eq!(
1639            build_field_vec::<String>(&t2, "tags").unwrap(),
1640            Vec::<String>::new(),
1641        );
1642        // JSON array.
1643        let mut t3 = ParseTree::new("Row");
1644        t3.fields
1645            .push(("tags".into(), RawValue::Json(json!(["a", "b"]))));
1646        assert_eq!(
1647            build_field_vec::<String>(&t3, "tags").unwrap(),
1648            vec!["a".to_string(), "b".to_string()],
1649        );
1650        // Canonical bracketed text (JSON-parsable as-is).
1651        let mut t4 = ParseTree::new("Row");
1652        t4.fields
1653            .push(("tags".into(), RawValue::Text(r#"["a", "b"]"#.into())));
1654        assert_eq!(
1655            build_field_vec::<String>(&t4, "tags").unwrap(),
1656            vec!["a".to_string(), "b".to_string()],
1657        );
1658        // Empty bracketed text.
1659        let mut t5 = ParseTree::new("Row");
1660        t5.fields.push(("tags".into(), RawValue::Text("[]".into())));
1661        assert_eq!(
1662            build_field_vec::<String>(&t5, "tags").unwrap(),
1663            Vec::<String>::new(),
1664        );
1665    }
1666
1667    #[test]
1668    fn unknown_field_is_reported() {
1669        let schema = schema_add_lit();
1670        let mut tree = lit(3);
1671        tree.fields.push(("extra".into(), RawValue::Json(json!(0))));
1672        let diags = check_conformance(&tree, &schema);
1673        assert_eq!(diags.len(), 1);
1674        assert_eq!(diags[0].code, codes::UNKNOWN_FIELD);
1675    }
1676
1677    #[test]
1678    fn field_and_child_slot_swapped_reports_structural_codes() {
1679        let schema = schema_add_lit();
1680
1681        // A child slot placed under fields.
1682        let mut swap1 = ParseTree::new("Add");
1683        swap1.fields.push(("lhs".into(), RawValue::Json(json!(0))));
1684        swap1.children.push(("rhs".into(), vec![lit(1)]));
1685        // Missing lhs child (arity_one) + child-as-field structural swap
1686        // → two diagnostics.
1687        let diags = check_conformance(&swap1, &schema);
1688        assert!(diags.iter().any(|d| d.code == codes::CHILD_AS_FIELD));
1689        assert!(diags.iter().any(|d| d.code == codes::ARITY_ONE));
1690
1691        // A payload field placed under children.
1692        let mut swap2 = ParseTree::new("Let");
1693        swap2
1694            .children
1695            .push(("name".into(), vec![ParseTree::new("Lit")]));
1696        swap2.children.push(("value".into(), vec![lit(1)]));
1697        swap2.children.push(("body".into(), vec![lit(2)]));
1698        let diags = check_conformance(&swap2, &schema);
1699        assert!(diags.iter().any(|d| d.code == codes::FIELD_AS_CHILD));
1700        assert!(diags.iter().any(|d| d.code == codes::MISSING_FIELD));
1701    }
1702
1703    #[test]
1704    fn arity_one_reports_wrong_count() {
1705        let schema = schema_add_lit();
1706        let mut add = ParseTree::new("Add");
1707        add.children.push(("lhs".into(), vec![lit(1), lit(2)])); // two, not one
1708        add.children.push(("rhs".into(), vec![lit(3)]));
1709        let diags = check_conformance(&add, &schema);
1710        assert_eq!(diags.len(), 1);
1711        assert_eq!(diags[0].code, codes::ARITY_ONE);
1712        assert!(diags[0].message.contains("lhs"));
1713    }
1714
1715    #[test]
1716    fn duplicate_field_and_child_reported() {
1717        let schema = schema_add_lit();
1718        let mut t = ParseTree::new("Lit");
1719        t.fields.push(("value".into(), RawValue::Json(json!(1))));
1720        t.fields.push(("value".into(), RawValue::Json(json!(2))));
1721        let diags = check_conformance(&t, &schema);
1722        assert!(diags.iter().any(|d| d.code == codes::DUPLICATE_FIELD));
1723
1724        let mut a = ParseTree::new("Add");
1725        a.children.push(("lhs".into(), vec![lit(1)]));
1726        a.children.push(("lhs".into(), vec![lit(2)]));
1727        a.children.push(("rhs".into(), vec![lit(3)]));
1728        let diags = check_conformance(&a, &schema);
1729        assert!(diags.iter().any(|d| d.code == codes::DUPLICATE_CHILD));
1730    }
1731
1732    #[test]
1733    fn diagnostic_json_shape() {
1734        let diag = Diagnostic::error("x::y", "boom").with_span(Some(Span::new(3, 7)));
1735        let v = diag.to_json();
1736        assert_eq!(v["severity"], "error");
1737        assert_eq!(v["code"], "x::y");
1738        assert_eq!(v["message"], "boom");
1739        assert_eq!(v["location"]["kind"], "span");
1740        assert_eq!(v["location"]["start"], 3);
1741        assert_eq!(v["location"]["end"], 7);
1742    }
1743
1744    #[test]
1745    fn build_error_display_lists_all() {
1746        let err = BuildError::new(vec![
1747            Diagnostic::error("a::b", "one"),
1748            Diagnostic::error("c::d", "two"),
1749        ]);
1750        let s = format!("{err}");
1751        assert!(s.contains("a::b: one"));
1752        assert!(s.contains("c::d: two"));
1753    }
1754}