delvewright_dsl/

envelope.rs

//! The stage envelope, the assembled [`Campaign`], and parsing from raw JSON.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::design::DesignContent;
use crate::detailplan::DetailPlanContent;
use crate::diagnostic::{Diagnostic, DwCode, ExitTier, codes};
use crate::ids::CampaignId;
use crate::layout::{GeometryBriefContent, LayoutGraphContent};
use crate::siteplan::SitePlanContent;
use crate::{
    ClassesContent, DialogueContent, NpcsContent, QuestPlanContent, QuestsContent, WorldContent,
    WorldEditsContent,
};

/// **The one `dsl_version` this engine accepts** (ADR-0024).
///
/// Every envelope this engine reads — the stage documents, the map-pipeline
/// documents, an l10n sidecar — declares exactly this number; any other is
/// refused at the envelope with `DW0102`, which names this constant. The number
/// says which surface a document was written against, so a refusal can say
/// why, and it promises nothing about any other engine: a released campaign is
/// built by the engine it pins (`versions.toml`), and a surface change bumps
/// this number and moves every document in this repository with it.
///
/// **This crate's package version IS the format's number** (ADR-0024), so the
/// number is read from the manifest rather than restated here: there is one
/// place to move it, and a literal in this file could not disagree with
/// `Cargo.toml` even in principle.
pub const DSL_VERSION: &str = env!("CARGO_PKG_VERSION");

/// Which stage a document belongs to.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum Stage {
    /// Stage 1.
    World,
    /// Stage 2.
    Npcs,
    /// Stage 3.
    Classes,
    /// Stage 4.
    QuestPlan,
    /// Stage 5.
    Quests,
    /// Stage 6.
    Dialogue,
    /// Stage 7 (optional; DSL v0.6, spec-0017): the map-editor edit script.
    WorldEdits,
    /// The whole map's written brief, reduced to numbers (optional; DSL v0.13,
    /// spec-0049 §4.2). Named, never renumbered into the 1..7 sequence: it is a
    /// different pipeline's document and the two orderings are unrelated.
    GeometryBrief,
    /// The campaign's space as a graph, before any coordinate exists (optional;
    /// DSL v0.13, spec-0049 §3).
    LayoutGraph,
    /// The geometric embedding of that graph — the whole map's design of record
    /// (optional; DSL v0.14, spec-0049 §4).
    SitePlan,
    /// Which piece stands in which of the plan's places (optional; DSL v0.15,
    /// spec-0050). Named, never renumbered, for the reason `GeometryBrief`
    /// gives.
    DetailPlan,
    /// **The approved design's record** (optional; DSL v0.22, spec-0061): one
    /// row per approved reference image, each naming the sky the picture was
    /// drawn under. Named, never renumbered — it is the design step's document,
    /// and the design step is not a position in the 1..7 sequence.
    Design,
}

impl Stage {
    /// The wire/filename name (`world`, `npcs`, `classes`, `quest-plan`,
    /// `quests`, `dialogue`).
    pub fn name(self) -> &'static str {
        match self {
            Stage::World => "world",
            Stage::Npcs => "npcs",
            Stage::Classes => "classes",
            Stage::QuestPlan => "quest-plan",
            Stage::Quests => "quests",
            Stage::Dialogue => "dialogue",
            Stage::WorldEdits => "world-edits",
            Stage::GeometryBrief => "geometry-brief",
            Stage::LayoutGraph => "layout-graph",
            Stage::SitePlan => "site-plan",
            Stage::DetailPlan => "detail-plan",
            Stage::Design => "design",
        }
    }

    /// **Every stage, in document order.** The one enumeration.
    ///
    /// Hand-written stage lists are how a new document escapes a gate that was
    /// written before it existed: `crates/dsl/tests/gate_consumers.rs` walked
    /// seven stages by name, so a schema object declaring part of the gate in an
    /// eighth would have been invisible to the check whose whole subject is that
    /// no such object exists. Anything that means "over the stages" reads this.
    pub const ALL: [Stage; 12] = [
        Stage::World,
        Stage::Npcs,
        Stage::Classes,
        Stage::QuestPlan,
        Stage::Quests,
        Stage::Dialogue,
        Stage::WorldEdits,
        Stage::GeometryBrief,
        Stage::LayoutGraph,
        Stage::SitePlan,
        Stage::DetailPlan,
        Stage::Design,
    ];
}

/// A stage document: `{ dsl_version, campaign_id, stage, content }`.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Envelope<T> {
    /// DSL version string.
    pub dsl_version: String,
    /// Owning campaign id.
    pub campaign_id: CampaignId,
    /// The stage this document is for.
    pub stage: Stage,
    /// The stage payload.
    pub content: T,
}

/// The parsed stage documents that make up one campaign: the six required
/// stages plus the optional stage-7 edit script (spec-0017).
#[derive(Clone, Debug, PartialEq)]
pub struct Campaign {
    /// Stage 1.
    pub world: Envelope<WorldContent>,
    /// Stage 2.
    pub npcs: Envelope<NpcsContent>,
    /// Stage 3.
    pub classes: Envelope<ClassesContent>,
    /// Stage 4.
    pub quest_plan: Envelope<QuestPlanContent>,
    /// Stage 5.
    pub quests: Envelope<QuestsContent>,
    /// Stage 6.
    pub dialogue: Envelope<DialogueContent>,
    /// Stage 7 (optional; DSL v0.6, spec-0017): the map-editor edit script.
    /// `None` = no `world-edits.json` in the campaign directory — byte-identical
    /// to a campaign from before the stage existed.
    pub world_edits: Option<Envelope<WorldEditsContent>>,
    /// The whole map's brief as numbers (optional; DSL v0.13, spec-0049 §4.2).
    pub geometry_brief: Option<Envelope<GeometryBriefContent>>,
    /// The campaign's space as a graph (optional; DSL v0.13, spec-0049 §3).
    pub layout_graph: Option<Envelope<LayoutGraphContent>>,
    /// The geometric embedding of that graph (optional; DSL v0.14, spec-0049 §4).
    pub site_plan: Option<Envelope<SitePlanContent>>,
    /// Which piece fills which of the plan's places (optional; DSL v0.15,
    /// spec-0050 §1).
    pub detail_plan: Option<Envelope<DetailPlanContent>>,
    /// The approved design's record (optional; DSL v0.22, spec-0061): the rows
    /// `DW0890` holds the world's reachable skies to. `None` = the campaign
    /// ships no `design.json`, which is a measured zero of an optional surface
    /// at validation and a refusal at staging.
    pub design: Option<Envelope<DesignContent>>,
    /// The site plan's heightmap as the loader read it (spec-0098 §2c), or
    /// `None` when nothing has read one — every campaign whose terrain is not a
    /// heightmap, and a campaign parsed from documents alone. A plan whose
    /// terrain IS a heightmap and whose image was never read is refused at
    /// validation (`DW0826`) rather than built over a guessed ground.
    pub heightmap: Option<crate::siteplan::HeightmapRead>,
}

/// The stage documents as raw JSON strings (compiler input): six required, the
/// stage-7 edit script optional.
#[derive(Clone, Debug, PartialEq)]
pub struct RawCampaign {
    /// `world.json`.
    pub world: String,
    /// `npcs.json`.
    pub npcs: String,
    /// `classes.json`.
    pub classes: String,
    /// `quest-plan.json`.
    pub quest_plan: String,
    /// `quests.json`.
    pub quests: String,
    /// `dialogue.json`.
    pub dialogue: String,
    /// `world-edits.json` (optional stage 7, spec-0017); `None` when the
    /// campaign directory ships none.
    pub world_edits: Option<String>,
    /// `geometry-brief.json` (optional; spec-0049 §4.2).
    pub geometry_brief: Option<String>,
    /// `layout-graph.json` (optional; spec-0049 §3).
    pub layout_graph: Option<String>,
    /// `site-plan.json` (optional; spec-0049 §4).
    pub site_plan: Option<String>,
    /// `detail-plan.json` (optional; spec-0050 §1).
    pub detail_plan: Option<String>,
    /// `design.json` (optional; spec-0061 §2).
    pub design: Option<String>,
}

fn parse_stage<T: for<'de> Deserialize<'de>>(
    src: &str,
    stage: Stage,
    out: &mut Result<Envelope<T>, ()>,
    diags: &mut Vec<Diagnostic>,
) {
    match serde_json::from_str::<Envelope<T>>(src) {
        Ok(env) => *out = Ok(env),
        Err(e) => {
            *out = Err(());
            diags.push(Diagnostic::error(
                codes::SCHEMA,
                stage.name(),
                "",
                format!(
                    "`{name}` stage document does not conform to its schema: {e}. Fix the \
                     offending field (unknown field, wrong type, or missing required one) in the \
                     campaign JSON to match the schema — run `delvec schema --stage {name}` to \
                     see the exact shape of THIS document. The schema is the authority on the \
                     form; a spec that disagrees with it is the stale one.",
                    name = stage.name()
                ),
            ));
        }
    }
}

/// Parse all six stage documents.
///
/// On any schema/parse failure returns every `DW0100` diagnostic collected
/// (validation cannot run on unparseable input).
pub fn parse_campaign(raw: &RawCampaign) -> Result<Campaign, Vec<Diagnostic>> {
    let mut diags = Vec::new();
    let mut world = Err(());
    let mut npcs = Err(());
    let mut classes = Err(());
    let mut quest_plan = Err(());
    let mut quests = Err(());
    let mut dialogue = Err(());

    parse_stage(&raw.world, Stage::World, &mut world, &mut diags);
    parse_stage(&raw.npcs, Stage::Npcs, &mut npcs, &mut diags);
    parse_stage(&raw.classes, Stage::Classes, &mut classes, &mut diags);
    parse_stage(
        &raw.quest_plan,
        Stage::QuestPlan,
        &mut quest_plan,
        &mut diags,
    );
    parse_stage(&raw.quests, Stage::Quests, &mut quests, &mut diags);
    parse_stage(&raw.dialogue, Stage::Dialogue, &mut dialogue, &mut diags);
    // The optional stage-7 edit script (spec-0017): absent = `None`; present but
    // unparseable = a `DW0100` like any other stage.
    let mut world_edits: Result<Option<Envelope<WorldEditsContent>>, ()> = Ok(None);
    if let Some(src) = &raw.world_edits {
        let mut parsed = Err(());
        parse_stage(src, Stage::WorldEdits, &mut parsed, &mut diags);
        world_edits = parsed.map(Some);
    }
    // The spec-0049 map-pipeline documents, on the same terms: absent = `None`
    // and a campaign that ships neither is byte-identical to one from before
    // they existed; present = parsed, validated and hashed like any other stage.
    let mut geometry_brief: Result<Option<Envelope<GeometryBriefContent>>, ()> = Ok(None);
    if let Some(src) = &raw.geometry_brief {
        let mut parsed = Err(());
        parse_stage(src, Stage::GeometryBrief, &mut parsed, &mut diags);
        geometry_brief = parsed.map(Some);
    }
    let mut layout_graph: Result<Option<Envelope<LayoutGraphContent>>, ()> = Ok(None);
    if let Some(src) = &raw.layout_graph {
        let mut parsed = Err(());
        parse_stage(src, Stage::LayoutGraph, &mut parsed, &mut diags);
        layout_graph = parsed.map(Some);
    }
    let mut site_plan: Result<Option<Envelope<SitePlanContent>>, ()> = Ok(None);
    if let Some(src) = &raw.site_plan {
        let mut parsed = Err(());
        parse_stage(src, Stage::SitePlan, &mut parsed, &mut diags);
        site_plan = parsed.map(Some);
    }
    let mut detail_plan: Result<Option<Envelope<DetailPlanContent>>, ()> = Ok(None);
    if let Some(src) = &raw.detail_plan {
        let mut parsed = Err(());
        parse_stage(src, Stage::DetailPlan, &mut parsed, &mut diags);
        detail_plan = parsed.map(Some);
    }
    // The design record (spec-0061 §2), on the same terms: absent = a campaign
    // that has approved no design yet, which validation measures and staging
    // refuses; present = parsed, validated and hashed like any other stage.
    let mut design: Result<Option<Envelope<DesignContent>>, ()> = Ok(None);
    if let Some(src) = &raw.design {
        let mut parsed = Err(());
        parse_stage(src, Stage::Design, &mut parsed, &mut diags);
        design = parsed.map(Some);
    }

    match (
        world,
        npcs,
        classes,
        quest_plan,
        quests,
        dialogue,
        world_edits,
        geometry_brief,
        layout_graph,
        site_plan,
        detail_plan,
        design,
    ) {
        (
            Ok(world),
            Ok(npcs),
            Ok(classes),
            Ok(quest_plan),
            Ok(quests),
            Ok(dialogue),
            Ok(world_edits),
            Ok(geometry_brief),
            Ok(layout_graph),
            Ok(site_plan),
            Ok(detail_plan),
            Ok(design),
        ) => {
            let mut campaign = Campaign {
                world,
                npcs,
                classes,
                quest_plan,
                quests,
                dialogue,
                world_edits,
                geometry_brief,
                layout_graph,
                site_plan,
                detail_plan,
                design,
                heightmap: None,
            };
            // spec-0016 §3: expand the `ambush` sugar into real environment
            // triggers, ONCE, at the DSL boundary. Every downstream consumer —
            // validation, l10n, the flow producer scans, nav, emission — then
            // sees the same `triggers` list it always has, so the sugar has no
            // second code path to drift down and an ambush is exactly as
            // debuggable as the trigger an author would otherwise hand-write.
            campaign.quests.content.expand_ambushes();
            Ok(campaign)
        }
        _ => Err(diags),
    }
}

/// Parse then validate.
///
/// Convenience over [`parse_campaign`] and [`crate::validate::validate_campaign`]:
/// a document that does not parse yields its `DW0100` list; one that parses
/// yields every finding validation raises against it.
pub fn check_campaign(raw: &RawCampaign) -> Vec<Diagnostic> {
    match parse_campaign(raw) {
        Ok(campaign) => crate::validate::validate_campaign(&campaign),
        Err(diags) => diags,
    }
}

// ---------------------------------------------------------------------------
// Validation
// ---------------------------------------------------------------------------

crate::dw_code! {
    /// Envelope `stage` does not match the document's slot.
    pub const STAGE_MISMATCH: DwCode = DwCode::new("DW0101", ExitTier::Build);
}

crate::dw_code! {
    /// Inconsistent `campaign_id` across stages.
    pub const CAMPAIGN_ID_MISMATCH: DwCode = DwCode::new("DW0103", ExitTier::Build);
}

/// The envelope of every stage document: its `stage` (`DW0101`), its
/// `dsl_version` (`DW0102`), and its `campaign_id`'s syntax (`DW0110`) and
/// agreement with the world stage's (`DW0103`).
pub(crate) fn envelope_checks(c: &Campaign, d: &mut Vec<Diagnostic>) {
    let stages = [
        (Stage::World, c.world.stage, c.world.dsl_version.as_str()),
        (Stage::Npcs, c.npcs.stage, c.npcs.dsl_version.as_str()),
        (
            Stage::Classes,
            c.classes.stage,
            c.classes.dsl_version.as_str(),
        ),
        (
            Stage::QuestPlan,
            c.quest_plan.stage,
            c.quest_plan.dsl_version.as_str(),
        ),
        (Stage::Quests, c.quests.stage, c.quests.dsl_version.as_str()),
        (
            Stage::Dialogue,
            c.dialogue.stage,
            c.dialogue.dsl_version.as_str(),
        ),
    ];
    let stages: Vec<(Stage, Stage, &str)> = stages
        .into_iter()
        .chain(
            c.world_edits
                .iter()
                .map(|e| (Stage::WorldEdits, e.stage, e.dsl_version.as_str())),
        )
        .chain(
            c.geometry_brief
                .iter()
                .map(|e| (Stage::GeometryBrief, e.stage, e.dsl_version.as_str())),
        )
        .chain(
            c.layout_graph
                .iter()
                .map(|e| (Stage::LayoutGraph, e.stage, e.dsl_version.as_str())),
        )
        .chain(
            c.site_plan
                .iter()
                .map(|e| (Stage::SitePlan, e.stage, e.dsl_version.as_str())),
        )
        .chain(
            c.detail_plan
                .iter()
                .map(|e| (Stage::DetailPlan, e.stage, e.dsl_version.as_str())),
        )
        .chain(
            c.design
                .iter()
                .map(|e| (Stage::Design, e.stage, e.dsl_version.as_str())),
        )
        .collect();
    for (expected, actual, version) in stages {
        if actual != expected {
            d.push(Diagnostic::error(
                STAGE_MISMATCH,
                expected.name(),
                "/stage",
                format!(
                    "`stage` is `{}` but this is the `{}` stage document — set `stage` to `{}` (or \
                     move this content into the `{}` document it belongs to)",
                    actual.name(),
                    expected.name(),
                    expected.name(),
                    actual.name(),
                ),
            ));
        }
        if version != DSL_VERSION {
            d.push(Diagnostic::error(
                codes::DSL_VERSION,
                expected.name(),
                "/dsl_version",
                format!(
                    "dsl_version `{version}` is not the one this engine accepts — set it to \
                     `{DSL_VERSION}` and revise the document against that surface. An engine \
                     accepts exactly the number it implements (ADR-0024); a document written \
                     for another number is built by the engine that implements that number."
                ),
            ));
        }
    }

    let ids: Vec<(Stage, &crate::ids::CampaignId)> = [
        (Stage::World, &c.world.campaign_id),
        (Stage::Npcs, &c.npcs.campaign_id),
        (Stage::Classes, &c.classes.campaign_id),
        (Stage::QuestPlan, &c.quest_plan.campaign_id),
        (Stage::Quests, &c.quests.campaign_id),
        (Stage::Dialogue, &c.dialogue.campaign_id),
    ]
    .into_iter()
    .chain(
        c.world_edits
            .iter()
            .map(|e| (Stage::WorldEdits, &e.campaign_id)),
    )
    .chain(
        c.geometry_brief
            .iter()
            .map(|e| (Stage::GeometryBrief, &e.campaign_id)),
    )
    .chain(
        c.layout_graph
            .iter()
            .map(|e| (Stage::LayoutGraph, &e.campaign_id)),
    )
    .chain(
        c.site_plan
            .iter()
            .map(|e| (Stage::SitePlan, &e.campaign_id)),
    )
    .chain(
        c.detail_plan
            .iter()
            .map(|e| (Stage::DetailPlan, &e.campaign_id)),
    )
    .chain(c.design.iter().map(|e| (Stage::Design, &e.campaign_id)))
    .collect();
    let canonical = c.world.campaign_id.as_str();
    for (stage, id) in ids {
        if !id.is_valid_syntax() {
            d.push(Diagnostic::error(
                codes::ID_SYNTAX,
                stage.name(),
                "/campaign_id",
                format!("malformed campaign_id `{id}` (expected kebab-case)"),
            ));
        }
        if id.as_str() != canonical {
            d.push(Diagnostic::error(
                CAMPAIGN_ID_MISMATCH,
                stage.name(),
                "/campaign_id",
                format!(
                    "campaign_id `{id}` differs from `{canonical}` (the world stage's id) — set \
                     every stage's `campaign_id` to `{canonical}` so all six documents name one \
                     campaign"
                ),
            ));
        }
    }
}

#[cfg(test)]
mod version_tests {
    use super::*;

    /// The number is the crate's own (ADR-0024) by construction, so nothing here
    /// can hold the two apart. What is still worth asserting is its SHAPE: every
    /// gate that reads it — `delvec fmt`, `DW0102`, the release plumbing — treats
    /// it as an exact `major.minor.patch`, and a manifest version carrying a
    /// pre-release or build suffix would reach them as one.
    #[test]
    fn the_accepted_dsl_version_is_an_exact_three_part_number() {
        let parts: Vec<&str> = DSL_VERSION.split('.').collect();
        assert_eq!(parts.len(), 3, "DSL_VERSION is `{DSL_VERSION}`");
        assert!(
            parts
                .iter()
                .all(|p| !p.is_empty() && p.bytes().all(|b| b.is_ascii_digit())),
            "DSL_VERSION is `{DSL_VERSION}`"
        );
    }
}