mecha10_cli/services/

schema_export.rs

//! Generates `docs/schemas/` (LAB-1829) from this repo's real schemas: the
//! hand-written project-config schema (`mecha10_core::schema_validation::get_project_schema`,
//! with its `behaviors` property overridden by the real `schemars`-derived
//! `BehaviorsConfig` schema -- see [`project_schema_with_introspected_behaviors`])
//! and the `schemars`-derived per-node-type/model-catalog schemas
//! (`mecha10_schema_registry`). See `docs/validate-configs.md` for how these schemas
//! are used to validate configs; this module is purely about rendering them as
//! reference docs — it adds no new schema content and hand-writes no field
//! descriptions (those come from the schemas themselves, which pull node-config
//! field docs from `packages/nodes/*/src/config.rs`'s doc comments via `schemars`).
//!
//! Every file this writes is generated output: the raw schema JSON (one file per
//! schema) plus a single Markdown field reference. `scripts/ci/schema-docs-check.sh`
//! re-runs this and diffs against what's committed, so `docs/schemas/` can never
//! silently drift from the schemas it documents.

use anyhow::{Context, Result};
use serde_json::Value;
use std::collections::BTreeSet;
use std::fmt::Write as _;
use std::fs;
use std::path::{Path, PathBuf};

/// One schema this service exports: a relative path (under the export root) for
/// its raw JSON, a title used in the generated Markdown, and the schema itself.
struct ExportedSchema {
    /// Path relative to the export root, e.g. `"mecha10.schema.json"` or
    /// `"nodes/camera.schema.json"`.
    relative_json_path: PathBuf,
    /// Heading used for this schema's section in the generated Markdown.
    title: String,
    schema: Value,
}

/// Generates `docs/schemas/`-style reference docs (raw JSON Schema files plus a
/// Markdown field reference) from every schema this CLI knows about. See the
/// module-level docs for what "knows about" means and why nothing here
/// hand-writes schema content.
pub struct SchemaExportService;

impl SchemaExportService {
    /// Generate every schema this CLI knows about and write it under `out_dir`:
    /// raw JSON Schema files plus a single `README.md` field reference. Returns
    /// the list of files written (relative to `out_dir`), for callers that want
    /// to report what changed.
    ///
    /// # Errors
    ///
    /// Returns an error if `out_dir` can't be created, or a file can't be written.
    pub fn export(out_dir: &Path) -> Result<Vec<PathBuf>> {
        export_schemas(out_dir)
    }
}

/// Generate every schema this CLI knows about and write it under `out_dir`:
/// raw JSON Schema files plus a single `README.md` field reference. Returns the
/// list of files written (relative to `out_dir`), for callers that want to report
/// what changed.
///
/// # Errors
///
/// Returns an error if `out_dir` can't be created, or a file can't be written.
fn export_schemas(out_dir: &Path) -> Result<Vec<PathBuf>> {
    let schemas = collect_schemas();
    let mut written = Vec::new();

    for exported in &schemas {
        let path = out_dir.join(&exported.relative_json_path);
        if let Some(parent) = path.parent() {
            fs::create_dir_all(parent).with_context(|| format!("Failed to create directory {}", parent.display()))?;
        }
        let pretty = serde_json::to_string_pretty(&exported.schema)
            .with_context(|| format!("Failed to serialize schema for {}", exported.title))?;
        fs::write(&path, format!("{pretty}\n")).with_context(|| format!("Failed to write {}", path.display()))?;
        written.push(exported.relative_json_path.clone());
    }

    let readme_path = out_dir.join("README.md");
    fs::create_dir_all(out_dir).with_context(|| format!("Failed to create directory {}", out_dir.display()))?;
    fs::write(&readme_path, render_readme(&schemas)).context("Failed to write docs/schemas/README.md")?;
    written.push(PathBuf::from("README.md"));

    Ok(written)
}

/// Every schema `mecha10 schema export` knows about, in the order they should
/// appear in the generated Markdown.
fn collect_schemas() -> Vec<ExportedSchema> {
    let mut schemas = vec![ExportedSchema {
        relative_json_path: PathBuf::from("mecha10.schema.json"),
        title: "Project config (mecha10.json)".to_string(),
        schema: project_schema_with_introspected_behaviors(),
    }];

    for node_type in mecha10_schema_registry::BUILTIN_NODE_TYPES.iter() {
        let schema = mecha10_schema_registry::node_type_schema(node_type).unwrap_or_else(|| {
            panic!("mecha10-schema-registry declares '{node_type}' as built-in but has no schema for it")
        });
        schemas.push(ExportedSchema {
            relative_json_path: PathBuf::from("nodes").join(format!("{node_type}.schema.json")),
            title: format!("Node config: {node_type}"),
            schema,
        });
    }

    schemas.push(ExportedSchema {
        relative_json_path: PathBuf::from("model-catalog.schema.json"),
        title: "Model catalog (model_catalog.toml)".to_string(),
        schema: mecha10_schema_registry::model_catalog_schema(),
    });

    schemas
}

/// `mecha10_core::schema_validation::get_project_schema()`'s `behaviors` property
/// is a hand-written JSON Schema fragment, not derived from
/// `mecha10_cli_core::types::project::BehaviorsConfig` -- `mecha10-core` can't
/// depend on `mecha10-cli-core` (the reverse dependency already exists, see
/// `mecha10-cli-core`'s own doc comments), so the real struct isn't reachable
/// from where that schema is built, unlike node configs (see
/// `mecha10-schema-registry`, which lives downstream of every node crate for the
/// same reason).
///
/// That hand-written fragment silently drifted from the real struct for its
/// entire existence (it said `default` where the struct has always had
/// `active`) and survived two prior `docs/schemas/` regenerations (LAB-1829)
/// before an unrelated PR happened to fix its text. This crate *can* depend on
/// `mecha10-cli-core` (it already does, for other CLI functionality), so this
/// splices the real `schemars`-derived schema for `BehaviorsConfig` into the
/// `behaviors` property here -- after this point, `docs/schemas/` reflects the
/// real struct and can't silently drift from it again, even though the
/// hand-written fragment in `mecha10-core` (used for runtime validation, where
/// the dependency direction can't be worked around the same way) remains as a
/// separately-maintained copy.
fn project_schema_with_introspected_behaviors() -> Value {
    let mut schema = mecha10_core::schema_validation::get_project_schema();
    let behaviors_schema = mecha10_schema_registry::schema_for::<mecha10_cli_core::types::project::BehaviorsConfig>();
    if let Some(properties) = schema.get_mut("properties").and_then(Value::as_object_mut) {
        properties.insert("behaviors".to_string(), behaviors_schema);
    }
    schema
}

/// Render the full `README.md`: one section per schema, each with a field table
/// plus a subsection per nested `definitions` entry it references.
fn render_readme(schemas: &[ExportedSchema]) -> String {
    let mut out = String::new();
    out.push_str("# Schema reference\n\n");
    out.push_str(
        "Generated from this repo's JSON Schemas by `mecha10 schema export` (LAB-1829) — \
         do not hand-edit. Regenerate with:\n\n```\ncargo run -p mecha10-cli --bin mecha10 -- schema export\n```\n\n\
         Descriptions come from the schemas themselves (Rust doc comments on node config \
         structs, via `schemars`, or `get_project_schema()`'s own `description` fields for \
         the project config). See [`docs/validate-configs.md`](../validate-configs.md) for how \
         these schemas are used to validate configs, and the raw `.schema.json` files \
         alongside this doc for the exact JSON Schema.\n\n",
    );

    out.push_str("## Contents\n\n");
    for exported in schemas {
        let anchor = slugify(&exported.title);
        let _ = writeln!(out, "- [{}](#{anchor})", exported.title);
    }
    out.push('\n');

    for exported in schemas {
        let _ = writeln!(out, "## {}\n", exported.title);
        if let Some(description) = exported.schema.get("description").and_then(Value::as_str) {
            let _ = writeln!(out, "{description}\n");
        }
        let _ = writeln!(
            out,
            "Raw schema: [`{}`]({}).\n",
            exported.relative_json_path.display(),
            exported.relative_json_path.display()
        );

        render_schema_body(&exported.schema, &exported.schema, &mut out, &mut BTreeSet::new());
    }

    out
}

/// One more schema to render as its own subsection: either a named
/// `definitions` entry (referenced via `$ref`), or an anonymous inline object
/// schema (no `$ref` of its own — e.g. an array's `items`, embedded directly
/// rather than hoisted to `definitions`, as `model_catalog_schema()` does for
/// `ModelCatalogEntry` — see its doc comment for why). Anonymous sections are
/// titled after the field that introduced them.
struct PendingSection {
    title: String,
    schema: Value,
}

/// Render one schema's body: its own field table (if it's an object schema, or a
/// "Variants" breakdown if it's a `oneOf`/`anyOf`), followed by a subsection per
/// `definitions` entry and anonymous nested object it (transitively) references.
/// `visited` dedupes sections reached from more than one place so each is only
/// rendered once.
fn render_schema_body(root: &Value, schema: &Value, out: &mut String, visited: &mut BTreeSet<String>) {
    let mut pending: Vec<PendingSection> = Vec::new();
    render_value_body(schema, out, &mut pending);

    if let Some(definitions) = root.get("definitions").and_then(Value::as_object) {
        let mut names: Vec<&String> = definitions.keys().collect();
        names.sort();
        for name in names {
            pending.push(PendingSection {
                title: name.clone(),
                schema: definitions[name].clone(),
            });
        }
    }

    let mut index = 0;
    while index < pending.len() {
        if visited.insert(pending[index].title.clone()) {
            let _ = writeln!(out, "### {}\n", pending[index].title);
            if let Some(description) = pending[index].schema.get("description").and_then(Value::as_str) {
                let _ = writeln!(out, "{description}\n");
            }
            let schema_to_render = pending[index].schema.clone();
            render_value_body(&schema_to_render, out, &mut pending);
        }
        index += 1;
    }
}

/// Render a single schema value's field table or variant breakdown — no heading,
/// callers add their own. Queues any anonymous inline nested object schema it
/// finds (a property, or an array property's `items`, with its own `properties`
/// but no `$ref`) onto `pending` for [`render_schema_body`] to render as its own
/// subsection.
fn render_value_body(schema: &Value, out: &mut String, pending: &mut Vec<PendingSection>) {
    if let Some(properties) = schema.get("properties").and_then(Value::as_object) {
        let required: BTreeSet<&str> = schema
            .get("required")
            .and_then(Value::as_array)
            .map(|values| values.iter().filter_map(Value::as_str).collect())
            .unwrap_or_default();

        let mut names: Vec<&String> = properties.keys().collect();
        names.sort();

        out.push_str("| Field | Type | Required | Description |\n");
        out.push_str("| --- | --- | --- | --- |\n");
        for name in names {
            let field_schema = &properties[name];
            let type_label = type_label(field_schema);
            let is_required = if required.contains(name.as_str()) { "yes" } else { "no" };
            let description = field_description(field_schema).unwrap_or_default();
            let _ = writeln!(out, "| `{name}` | {type_label} | {is_required} | {description} |");
            if let Some(nested) = anonymous_nested_object(name, field_schema) {
                pending.push(nested);
            }
        }
        out.push('\n');
        return;
    }

    if let Some(variants) = schema
        .get("oneOf")
        .or_else(|| schema.get("anyOf"))
        .and_then(Value::as_array)
    {
        out.push_str("One of the following variants:\n\n");
        for (index, variant) in variants.iter().enumerate() {
            let label = variant_label(variant, index);
            let _ = writeln!(out, "- **{label}**");
        }
        out.push('\n');
        for (index, variant) in variants.iter().enumerate() {
            let is_bare_reference_or_null = (variant.get("$ref").is_some()
                || variant.get("type").and_then(Value::as_str) == Some("null"))
                && variant.get("properties").is_none();
            if is_bare_reference_or_null || (variant.get("enum").is_some() && variant.get("properties").is_none()) {
                continue;
            }
            let label = variant_label(variant, index);
            let _ = writeln!(out, "**{label}**\n");
            render_value_body(variant, out, pending);
        }
        return;
    }

    if let Some(items) = schema.get("enum").and_then(Value::as_array) {
        let values: Vec<String> = items.iter().map(display_scalar).collect();
        let _ = writeln!(out, "Allowed values: {}\n", values.join(", "));
    }
}

/// If `field_schema` (or, for an array field, its `items`) is an anonymous
/// inline object schema — has its own `properties` but isn't a `$ref`/`allOf`-
/// wrapped reference to a named `definitions` entry — return a [`PendingSection`]
/// for it, titled after `field_name` (or the schema's own `title`, if it has
/// one). This is what documents e.g. `model_catalog_schema()`'s `models[]` items
/// (`ModelCatalogEntry`, embedded inline rather than hoisted to `definitions` —
/// see that function's doc comment for why), which a `$ref`-only walk would
/// otherwise silently skip.
fn anonymous_nested_object(field_name: &str, field_schema: &Value) -> Option<PendingSection> {
    let candidate = if field_schema.get("type").and_then(Value::as_str) == Some("array") {
        field_schema.get("items")?
    } else {
        field_schema
    };

    if candidate.get("$ref").is_some() {
        return None;
    }
    if let Some(all_of) = candidate.get("allOf").and_then(Value::as_array) {
        if all_of.iter().any(|s| s.get("$ref").is_some()) {
            return None;
        }
    }
    if candidate.get("oneOf").is_some() || candidate.get("anyOf").is_some() {
        return None;
    }

    let has_properties = candidate
        .get("properties")
        .and_then(Value::as_object)
        .is_some_and(|props| !props.is_empty());
    if !has_properties {
        return None;
    }

    let title = candidate
        .get("title")
        .and_then(Value::as_str)
        .map(str::to_string)
        .unwrap_or_else(|| field_name.to_string());
    Some(PendingSection {
        title,
        schema: candidate.clone(),
    })
}

/// A human label for one `oneOf`/`anyOf` variant: its serde-tag discriminant value
/// if present (`properties.type.enum[0]`, the common internally-tagged-enum shape),
/// its own `enum` value if it's a plain string-enum member, else its `title`, else
/// a positional fallback.
fn variant_label(variant: &Value, index: usize) -> String {
    if let Some(tag) = variant
        .get("properties")
        .and_then(|p| p.get("type"))
        .and_then(|t| t.get("enum"))
        .and_then(Value::as_array)
        .and_then(|values| values.first())
        .and_then(Value::as_str)
    {
        return format!("`{tag}`");
    }
    if let Some(tag) = variant
        .get("enum")
        .and_then(Value::as_array)
        .and_then(|values| values.first())
        .and_then(Value::as_str)
    {
        return format!("`{tag}`");
    }
    if let Some(title) = variant.get("title").and_then(Value::as_str) {
        return title.to_string();
    }
    if variant.get("type").and_then(Value::as_str) == Some("null") {
        return "`null`".to_string();
    }
    if let Some(reference) = variant.get("$ref").and_then(Value::as_str) {
        return ref_type_label(reference);
    }
    format!("variant {index}")
}

/// The description for a property schema, accounting for the `{"description":
/// ..., "allOf": [{"$ref": ...}]}` wrapping `schemars` uses when a field has its
/// own doc comment on top of a `$ref` (draft-07 doesn't allow sibling keywords
/// next to `$ref` directly).
fn field_description(schema: &Value) -> Option<String> {
    schema
        .get("description")
        .and_then(Value::as_str)
        .map(|s| s.replace('\n', " ").trim().to_string())
        .filter(|s| !s.is_empty())
}

/// A short type label for a field/variant schema: resolves `$ref`/`allOf`-wrapped
/// refs to the referenced definition's name, arrays to `array of <item type>`,
/// and falls back to the JSON Schema `type` keyword otherwise.
fn type_label(schema: &Value) -> String {
    if let Some(reference) = schema.get("$ref").and_then(Value::as_str) {
        return ref_type_label(reference);
    }
    if let Some(all_of) = schema.get("allOf").and_then(Value::as_array) {
        if let Some(reference) = all_of.iter().find_map(|s| s.get("$ref")).and_then(Value::as_str) {
            return ref_type_label(reference);
        }
    }
    if let Some(one_of) = schema
        .get("oneOf")
        .or_else(|| schema.get("anyOf"))
        .and_then(Value::as_array)
    {
        let labels: Vec<String> = one_of.iter().map(type_label).collect();
        return format!("one of: {}", labels.join(", "));
    }
    if schema.get("type").and_then(Value::as_str) == Some("array") {
        let item_label = schema.get("items").map_or_else(|| "any".to_string(), type_label);
        return format!("array of {item_label}");
    }
    if schema.get("properties").is_some() {
        return schema
            .get("title")
            .and_then(Value::as_str)
            .map_or_else(|| "object".to_string(), |title| format!("`{title}`"));
    }
    match schema.get("type") {
        Some(Value::String(t)) => t.clone(),
        Some(Value::Array(types)) => types.iter().filter_map(Value::as_str).collect::<Vec<_>>().join(" or "),
        _ if schema.get("enum").is_some() => "enum".to_string(),
        _ => "any".to_string(),
    }
}

/// The definition name a `#/definitions/<Name>` ref points at, formatted for
/// display (backtick-quoted so it reads as a type name, not prose).
fn ref_type_label(reference: &str) -> String {
    let name = reference.rsplit('/').next().unwrap_or(reference);
    format!("`{name}`")
}

fn display_scalar(value: &Value) -> String {
    match value {
        Value::String(s) => format!("`{s}`"),
        other => format!("`{other}`"),
    }
}

/// GitHub-flavored-Markdown heading-anchor slug for the table of contents links
/// (lowercase, spaces to hyphens, parens dropped).
fn slugify(title: &str) -> String {
    title
        .to_lowercase()
        .chars()
        .filter_map(|c| {
            if c.is_alphanumeric() || c == ' ' || c == '-' {
                Some(if c == ' ' { '-' } else { c })
            } else {
                None
            }
        })
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use tempfile::tempdir;

    #[test]
    fn type_label_resolves_plain_primitive() {
        let schema = json!({"type": "string"});
        assert_eq!(type_label(&schema), "string");
    }

    #[test]
    fn type_label_resolves_direct_ref() {
        let schema = json!({"$ref": "#/definitions/SourceConfig"});
        assert_eq!(type_label(&schema), "`SourceConfig`");
    }

    #[test]
    fn type_label_resolves_all_of_wrapped_ref() {
        let schema = json!({
            "description": "Frame source configuration",
            "allOf": [{"$ref": "#/definitions/SourceConfig"}]
        });
        assert_eq!(type_label(&schema), "`SourceConfig`");
    }

    #[test]
    fn type_label_resolves_array_of_ref() {
        let schema = json!({"type": "array", "items": {"$ref": "#/definitions/ModelCatalogEntry"}});
        assert_eq!(type_label(&schema), "array of `ModelCatalogEntry`");
    }

    #[test]
    fn field_description_reads_plain_description() {
        let schema = json!({"type": "string", "description": "Camera ID for identification"});
        assert_eq!(
            field_description(&schema).as_deref(),
            Some("Camera ID for identification")
        );
    }

    #[test]
    fn field_description_reads_all_of_wrapped_description() {
        let schema = json!({
            "description": "Frame source configuration",
            "allOf": [{"$ref": "#/definitions/SourceConfig"}]
        });
        assert_eq!(
            field_description(&schema).as_deref(),
            Some("Frame source configuration")
        );
    }

    #[test]
    fn render_value_body_produces_a_field_table_with_required_column() {
        let root = json!({
            "type": "object",
            "required": ["name"],
            "properties": {
                "name": {"type": "string", "description": "The name"},
                "note": {"type": "string", "description": "Optional note"}
            }
        });
        let mut out = String::new();
        render_value_body(&root, &mut out, &mut Vec::new());
        assert!(out.contains("| `name` | string | yes | The name |"));
        assert!(out.contains("| `note` | string | no | Optional note |"));
    }

    #[test]
    fn render_value_body_queues_anonymous_nested_array_item_object() {
        let root = json!({
            "type": "object",
            "properties": {
                "models": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {"name": {"type": "string", "description": "Model name"}}
                    }
                }
            }
        });
        let mut out = String::new();
        render_schema_body(&root, &root, &mut out, &mut BTreeSet::new());
        assert!(out.contains("### models"));
        assert!(out.contains("| `name` | string | no | Model name |"));
    }

    #[test]
    fn render_schema_body_documents_referenced_definitions_once() {
        let root = json!({
            "type": "object",
            "properties": {
                "source": {"allOf": [{"$ref": "#/definitions/SourceConfig"}]}
            },
            "definitions": {
                "SourceConfig": {
                    "type": "object",
                    "properties": {"path": {"type": "string"}}
                }
            }
        });
        let mut out = String::new();
        render_schema_body(&root, &root, &mut out, &mut BTreeSet::new());
        assert_eq!(out.matches("### SourceConfig").count(), 1);
        assert!(out.contains("| `path` | string | no |"));
    }

    #[test]
    fn project_schema_behaviors_property_reflects_the_real_behaviors_config_struct() {
        let schema = project_schema_with_introspected_behaviors();
        let behaviors = &schema["properties"]["behaviors"];

        assert_eq!(behaviors["title"], "BehaviorsConfig");
        assert!(
            behaviors["properties"].get("active").is_some(),
            "expected `behaviors.properties.active`, got: {behaviors}"
        );
        assert!(
            behaviors["properties"].get("default").is_none(),
            "`behaviors` schema still has a stale `default` field: {behaviors}"
        );
        let required: Vec<&str> = behaviors["required"]
            .as_array()
            .expect("BehaviorsConfig schema should have a `required` array")
            .iter()
            .filter_map(Value::as_str)
            .collect();
        assert_eq!(required, vec!["active"]);
    }

    #[test]
    fn variant_label_prefers_serde_tag_discriminant() {
        let variant = json!({
            "type": "object",
            "properties": {"type": {"enum": ["mock"]}}
        });
        assert_eq!(variant_label(&variant, 0), "`mock`");
    }

    #[test]
    fn export_schemas_writes_json_and_readme() {
        let dir = tempdir().unwrap();
        let written = export_schemas(dir.path()).unwrap();

        assert!(written.contains(&PathBuf::from("mecha10.schema.json")));
        assert!(written.contains(&PathBuf::from("model-catalog.schema.json")));
        assert!(written.contains(&PathBuf::from("nodes/camera.schema.json")));
        assert!(written.contains(&PathBuf::from("README.md")));

        assert!(dir.path().join("mecha10.schema.json").exists());
        assert!(dir.path().join("nodes/camera.schema.json").exists());
        assert!(dir.path().join("model-catalog.schema.json").exists());

        let readme = fs::read_to_string(dir.path().join("README.md")).unwrap();
        assert!(readme.contains("# Schema reference"));
        assert!(readme.contains("## Project config (mecha10.json)"));
        assert!(readme.contains("## Node config: camera"));
        assert!(readme.contains("## Model catalog (model_catalog.toml)"));
        assert!(readme.contains("### ModelCatalogEntry"));
        assert!(readme.contains("| `name` |"));
    }

    #[test]
    fn export_schemas_covers_every_builtin_node_type() {
        let dir = tempdir().unwrap();
        export_schemas(dir.path()).unwrap();
        for node_type in mecha10_schema_registry::BUILTIN_NODE_TYPES.iter() {
            let path = dir.path().join("nodes").join(format!("{node_type}.schema.json"));
            assert!(
                path.exists(),
                "expected schema file for '{node_type}' at {}",
                path.display()
            );
        }
    }

    #[test]
    fn export_schemas_output_is_deterministic() {
        let dir_a = tempdir().unwrap();
        let dir_b = tempdir().unwrap();
        export_schemas(dir_a.path()).unwrap();
        export_schemas(dir_b.path()).unwrap();

        let readme_a = fs::read_to_string(dir_a.path().join("README.md")).unwrap();
        let readme_b = fs::read_to_string(dir_b.path().join("README.md")).unwrap();
        assert_eq!(readme_a, readme_b);

        let schema_a = fs::read_to_string(dir_a.path().join("mecha10.schema.json")).unwrap();
        let schema_b = fs::read_to_string(dir_b.path().join("mecha10.schema.json")).unwrap();
        assert_eq!(schema_a, schema_b);
    }
}