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