mecha10-cli 0.7.0

//! Export JSON Schema + Markdown reference docs for this repo's config kinds
//! (project config, the node config base, model catalog, and three more
//! promoted schemas -- see below) as raw JSON Schema files plus a generated
//! Markdown field reference, under `schemas/`.
//!
//! `packages/nodes/*` were extracted into mecha-industries/mecha10-nodes (history preserved via
//! git filter-repo). This example used to also write each built-in node type's own composed
//! schema straight into that node's crate directory under this repo
//! (`packages/nodes/<type>/<type>.schema.json`, via the now-removed `export_builtin_node_schema_files`),
//! then (after the node-crate split) only link out to where that file now lives and is
//! maintained in `mecha10-nodes` instead (via a now-removed `render_node_schema_links`). Node
//! schemas are API-driven now -- fetched live from `mecha10-api`'s catalog at runtime (see
//! `packages/robot-config/src/node_catalog.rs`), not derived at this repo's compile time from
//! node-crate Rust types -- so this repo has no node-crate dependency left to export or link out
//! to at all; this example only covers the config kinds below.
//!
//! This used to be the `mecha10 schema export` subcommand, but it's internal
//! tooling -- only `scripts/ci/schema-docs-check.sh` (CI drift check) and
//! whoever regenerates `schemas/` by hand ever runs it, never a robot
//! developer -- so it doesn't belong on the user-facing `mecha10` CLI
//! surface. Moved out to this example binary instead, following the same
//! `cargo run --example <name>` convention used elsewhere in this repo for
//! internal/dev-only tooling.
//!
//! Usage:
//! ```bash
//! cargo run -p mecha10-cli --example export_schemas -- --out schemas
//! ```
//!
//! Or build first, then run the binary directly (what
//! `scripts/ci/schema-docs-check.sh` does):
//! ```bash
//! cargo build -p mecha10-cli --example export_schemas
//! ./target/debug/examples/export_schemas --out schemas
//! ```
//!
//! Renders `schemars`-derived project-config schema
//! (`mecha10_cli_core::types::project::ProjectConfig::schema_value`, with a small
//! hand-written remainder spliced back in for the handful of properties that struct
//! doesn't model -- see [`full_project_schema`]) and the `schemars`-derived
//! base/model-catalog schemas (`mecha10_schema_registry`). See
//! `docs/adr/0001-node-config-base-schema.md` for how a node's own config schema is
//! composed and validated -- this is purely about rendering 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`).
//!
//! LAB-4245 promoted three more already-correct, already-validated-in-Rust
//! schemas into this same export, so they're CI-diff-checked the same way as
//! everything above instead of only living in a crate this never touched:
//! - `environment.schema.json` -- the hand-written `environment.json` schema
//!   bundled under `mecha10-templates` (see [`environment_config_schema`]).
//! - `behavior.schema.json` -- `schemars`-derived from
//!   `mecha10_behavior_runtime::BehaviorConfig`, the same schema
//!   `packages/behavior-runtime/src/config/validator.rs` validates every
//!   behavior-tree `config.json` against. This used to be separately rendered, via its
//!   own `cargo run --example generate_schema` invocation, to the non-standard-named
//!   `packages/behavior-runtime/schemas/behavior_composition_v1.json` -- that separate
//!   example and its stale committed output are gone now that this export covers it.
//!
//! `rl-job.schema.json` is the same kind of promotion, added separately: `schemars`-derived
//! from `mecha10_cli::services::train_jobs::JobDefinition`, the real struct `mecha10 train`
//! already deserializes every `configs/rl/jobs/*.yml` job definition into (LAB-2970 folded
//! the old separate `configs/rl/local.yml` training config into this same struct, so there
//! is no other training-config shape left to schema-export).
//!
//! `base.schema.json` (LAB-4384) is `schemars`-derived from
//! `mecha10_core::node_config_base::NodeConfigBase`, the shared base config contract every
//! node's resolved config is meant to flatten in (currently just `relay_topics` -- see that
//! module's doc comment for the full design). [`collect_schemas`] does not write a per-node-type
//! schema file at all -- a built-in node's own composed base+`custom` schema is published by
//! `mecha-industries/mecha10-nodes` (pushed to `mecha10-api`'s node catalog by that repo's own
//! `release.yml`) and fetched live by a project at runtime, not derived or exported from this
//! repo.
//!
//! 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 `schemas/` can never
//! silently drift from the schemas it documents.

#![allow(
    clippy::print_stdout,
    reason = "example prints its report to the terminal, by design -- same as the handler this replaced"
)]

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

const DEFAULT_SCHEMA_EXPORT_DIR: &str = "schemas";

fn main() -> Result<()> {
    let out_dir = parse_out_dir(std::env::args().skip(1).collect())?;

    println!();
    println!("📄 Schema Export");
    println!("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
    println!();

    let written = export_schemas(&out_dir)?;

    println!("Wrote {} file(s) to {}:", written.len(), out_dir.display());
    for path in &written {
        println!("  - {}", path.display());
    }
    println!();

    Ok(())
}

/// Parse `--out <dir>` from the given args, defaulting to
/// [`DEFAULT_SCHEMA_EXPORT_DIR`] when omitted.
///
/// # Errors
///
/// Returns an error if `--out` is given without a following value, or an
/// unrecognized argument is passed.
fn parse_out_dir(args: Vec<String>) -> Result<PathBuf> {
    let mut iter = args.into_iter();
    let mut out_dir = PathBuf::from(DEFAULT_SCHEMA_EXPORT_DIR);

    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--out" => {
                let value = iter.next().ok_or_else(|| anyhow::anyhow!("--out requires a value"))?;
                out_dir = PathBuf::from(value);
            }
            other => bail!("unrecognized argument: {other}"),
        }
    }

    Ok(out_dir)
}

struct ExportedSchema {
    relative_json_path: PathBuf,
    title: String,
    schema: Value,
}

/// Generate every schema this 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 schemas/README.md")?;
    written.push(PathBuf::from("README.md"));

    Ok(written)
}

/// Every schema this 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: full_project_schema(),
        },
        ExportedSchema {
            relative_json_path: PathBuf::from("base.schema.json"),
            title: "Node config base (common/reserved fields)".to_string(),
            schema: mecha10_schema_registry::schema_for::<mecha10_core::node_config_base::NodeConfigBase>(),
        },
    ];

    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.push(ExportedSchema {
        relative_json_path: PathBuf::from("environment.schema.json"),
        title: "Simulation environment (environment.json)".to_string(),
        schema: environment_config_schema(),
    });

    schemas.push(ExportedSchema {
        relative_json_path: PathBuf::from("behavior.schema.json"),
        title: "Behavior composition (behavior tree config.json)".to_string(),
        schema: mecha10_behavior_runtime::BehaviorConfig::schema_value(),
    });

    schemas.push(ExportedSchema {
        relative_json_path: PathBuf::from("rl-job.schema.json"),
        title: "RL training job (configs/rl/jobs/*.yml)".to_string(),
        schema: mecha10_schema_registry::schema_for::<mecha10_cli::services::train_jobs::JobDefinition>(),
    });

    schemas
}

/// The hand-written draft-07 schema for `environment.json`
/// (`packages/mecha10-templates/templates/configs/simulation/schemas/environment-config.schema.json`,
/// bundled at compile time via `mecha10_templates::templates::ENVIRONMENT_CONFIG_SCHEMA_JSON`),
/// parsed and re-emitted here so it's covered by this export (and so
/// `scripts/ci/schema-docs-check.sh`'s drift check extends to it the same way it
/// already covers every other file this writes) instead of only living
/// under `mecha10-templates` where nothing diffs it against what's committed
/// under `schemas/` (LAB-4245). This is read-and-copy, not move-and-re-export:
/// `mecha10 init` scaffolds new projects from the `mecha10-templates` copy
/// directly (relative `$id`/companion-doc references included), so that copy
/// stays the canonical on-disk location; this is simply a second, CI-tracked
/// rendering of the same content.
///
/// Delegates to `mecha10_schema_registry::environment_config_schema` (LAB-4246) so this
/// export and `mecha10 config push`'s build-time validation gate
/// (`packages/cli/src/config_validation.rs`) parse the bundled constant exactly once
/// between them, instead of each keeping its own copy of this function.
fn environment_config_schema() -> Value {
    mecha10_schema_registry::environment_config_schema()
}

/// The real `mecha10.json` schema: `ProjectConfig::schema_value()` (the real, `schemars`-derived
/// struct schema) plus a small hand-written remainder for the handful of properties that struct
/// doesn't model, spliced back in by [`apply_legacy_project_schema_fragments`] and
/// [`inject_build_target_triple_enum`] below (LAB-4282 follow-up).
///
/// Before this, `mecha10_core::schema_validation::get_project_schema()` was a hand-written JSON
/// Schema covering the whole struct, not derived from `mecha10_cli_core::types::project::ProjectConfig`
/// -- `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 wasn't reachable from where that
/// schema was built, unlike node configs (see `mecha10-schema-registry`, which lives downstream of
/// every node crate for the same reason). That hand-written schema silently drifted from the real
/// struct more than once (its `behaviors` property said `default` where the struct has always had
/// `active`, and survived two prior `schemas/` regenerations (LAB-1829) before an unrelated PR
/// happened to fix its text) -- exactly the drift this function exists to make structurally
/// impossible for everything the struct actually models. `mecha10-cli` *can* depend on
/// `mecha10-cli-core` (it already does, for other CLI functionality), so this calls its
/// `schema_value()` directly instead of re-deriving or hand-copying anything.
///
/// `mecha10_core::schema_validation::get_project_schema()` (the runtime validator, which can't
/// take the same path -- see that function's own doc comment) embeds a build-time copy of this
/// exact function's output, kept in sync by `scripts/ci/schema-docs-check.sh`.
fn full_project_schema() -> Value {
    let mut schema = mecha10_cli_core::types::project::ProjectConfig::schema_value();
    apply_legacy_project_schema_fragments(&mut schema);
    inject_build_target_triple_enum(&mut schema);
    schema
}

/// Splice the handful of `mecha10.json` properties `ProjectConfig` doesn't model at all into
/// `schema` (its `properties` and `$defs` maps, in place):
///
/// - `nodes`: overridden (not merely added) -- `ProjectConfig`'s `NodesConfig` field only models
///   the current flat identifier -> version map; it can't also accept the legacy
///   `drivers`/`standard`/`custom` array shape some older projects still have on disk (see
///   `mecha10_cli_core::types::project::NodesConfig`'s own doc comment). This fragment accepts
///   both, exactly as the pre-LAB-4282-follow-up hand-written schema did.
/// - `run_targets`: added -- `ProjectConfig` has no field for this at all; it's read as raw JSON
///   by `mecha10_core::schema_validation::rules::validate_run_target_references`.
/// - `scripts`: added -- `ProjectConfig` has no field for this at all, and nothing left in this
///   repo reads it; kept purely so a `mecha10.json` still using it doesn't fail validation.
///
/// Every fragment here is copied verbatim from the schema this function's caller replaced, so
/// none of this is new hand-maintained surface -- it's the same already-committed text, just
/// layered onto the derived schema instead of being the whole schema.
fn apply_legacy_project_schema_fragments(schema: &mut Value) {
    let legacy_properties = json!({
        "nodes": {
            "type": "object",
            "properties": {
                "drivers": {
                    "type": "array",
                    "items": { "$ref": "#/definitions/node" },
                    "description": "Hardware driver nodes (legacy array form - see this property's own description)"
                },
                "standard": {
                    "type": "array",
                    "items": { "$ref": "#/definitions/standardNode" },
                    "description": "Standard/pre-built nodes from packages (legacy array form - see this property's own description)"
                },
                "custom": {
                    "type": "array",
                    "items": { "$ref": "#/definitions/node" },
                    "description": "Custom application nodes (legacy array form - see this property's own description)"
                }
            },
            "description": "Node definitions (NodesConfig in mecha10-cli-core) - typically a flat identifier -> version map, though the legacy `drivers`/`standard`/`custom` arrays below also validate (no `additionalProperties` restriction). Keys: a framework node's full package id (\"@mecha10/speaker\"), a future registry node (\"@<org>/<name>\"), or a project node's own unprefixed name (\"my-custom\"); the legacy \"@local/*\" prefix is no longer supported.",
            "examples": [
                { "@mecha10/speaker": "latest", "@mecha10/motor": "latest", "my-custom": "0.1.0" }
            ]
        },
        "run_targets": {
            "type": "object",
            "patternProperties": {
                "^[a-z][a-z0-9_-]*$": {
                    "$ref": "#/definitions/runTarget"
                }
            },
            "description": "Execution targets (robot, remote, dev, etc.)"
        },
        "scripts": {
            "type": "object",
            "patternProperties": {
                "^[a-z][a-z0-9:_-]*$": {
                    "type": "string"
                }
            },
            "description": "Script shortcuts (npm scripts-like)"
        }
    });

    let legacy_definitions = json!({
        "node": {
            "type": "object",
            "required": ["name", "path"],
            "properties": {
                "name": {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9_]*$",
                    "description": "Node name (snake_case)"
                },
                "path": {
                    "type": "string",
                    "description": "Path to node source code"
                },
                "config": {
                    "type": "string",
                    "description": "Path to node configuration file"
                },
                "description": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Node description"
                },
                "run_target": {
                    "type": "string",
                    "description": "Where to run this node - a key of this project's `run_targets` map"
                },
                "enabled": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether node is enabled"
                },
                "auto_restart": {
                    "type": "boolean",
                    "default": true,
                    "description": "Auto-restart on crash"
                },
                "depends_on": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Node dependencies (other nodes that must start first)"
                }
            }
        },
        "standardNode": {
            "type": "object",
            "required": ["package", "binary"],
            "properties": {
                "package": {
                    "type": "string",
                    "pattern": "^@[a-z0-9-]+/[a-z0-9/-]+$",
                    "description": "Package identifier (e.g., @mecha10/speaker)",
                    "examples": ["@mecha10/speaker"]
                },
                "binary": {
                    "type": "string",
                    "description": "Binary name within package"
                },
                "config": {
                    "type": "string",
                    "description": "Path to configuration file"
                }
            }
        },
        "runTarget": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Target description"
                },
                "includes": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Node groups to include"
                },
                "resources": {
                    "type": "object",
                    "properties": {
                        "cpu_limit": {
                            "type": "string",
                            "pattern": "^\\d+(\\.\\d+)?$",
                            "description": "CPU limit (e.g., '2.0')"
                        },
                        "memory_limit": {
                            "type": "string",
                            "pattern": "^\\d+(K|M|G|T)?$",
                            "description": "Memory limit (e.g., '512M', '16G')"
                        },
                        "gpu": {
                            "oneOf": [
                                { "type": "boolean" },
                                {
                                    "type": "object",
                                    "properties": {
                                        "enabled": { "type": "boolean" },
                                        "vendor": {
                                            "type": "string",
                                            "enum": ["nvidia", "amd", "intel"]
                                        },
                                        "count": {
                                            "type": "integer",
                                            "minimum": 1
                                        },
                                        "optional": { "type": "boolean" }
                                    }
                                }
                            ],
                            "description": "GPU requirements"
                        },
                        "storage_type": {
                            "type": "string",
                            "enum": ["local", "ssd", "hdd", "any"],
                            "description": "Storage type requirement"
                        },
                        "storage_size_gb": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Storage size in GB"
                        },
                        "model_cache": {
                            "type": "string",
                            "description": "Path to model cache directory"
                        },
                        "devices": {
                            "type": "array",
                            "items": {
                                "type": "string",
                                "pattern": "^/dev/.+$"
                            },
                            "description": "Required device files (e.g., /dev/video0)"
                        }
                    },
                    "description": "Resource requirements"
                }
            }
        }
    });

    if let Some(properties) = schema.get_mut("properties").and_then(Value::as_object_mut) {
        if let Some(legacy_properties) = legacy_properties.as_object() {
            for (name, value) in legacy_properties {
                properties.insert(name.clone(), value.clone());
            }
        }
    }

    if let Some(root) = schema.as_object_mut() {
        root.insert("definitions".to_string(), legacy_definitions);
    }
}

/// Recover the `buildTargetTriple` enum constraint (the 4 Rust target triples `mecha10 build`
/// cross-compiles for) on `targets.{robot,remote}.platforms` -- `TargetsConfig`'s real field,
/// `TargetEntry::platforms: Option<Vec<String>>`, has no way to express an enum-of-strings
/// constraint on a `Vec` item at the Rust type level, so `schemars` can only derive `{"type":
/// "array", "items": {"type": "string"}}` for it. This patches the one `$defs.TargetEntry`
/// `schemars` already generates (shared by every `targets.*` entry, platform-bearing or not) so
/// `mecha10.schema.json` keeps rejecting an unknown triple the same way the hand-written schema
/// it replaced did (see `validate_project_config_rejects_unknown_build_target_triple`).
fn inject_build_target_triple_enum(schema: &mut Value) {
    let triples = json!([
        "x86_64-apple-darwin",
        "aarch64-apple-darwin",
        "x86_64-unknown-linux-gnu",
        "aarch64-unknown-linux-gnu"
    ]);

    if let Some(items) = schema
        .get_mut("$defs")
        .and_then(|defs| defs.get_mut("TargetEntry"))
        .and_then(|target_entry| target_entry.get_mut("properties"))
        .and_then(|properties| properties.get_mut("platforms"))
        .and_then(|platforms| platforms.get_mut("items"))
    {
        if let Some(items) = items.as_object_mut() {
            items.insert("enum".to_string(), triples);
        }
    }
}

/// 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 `cargo run --example export_schemas` (LAB-1829) — \
         do not hand-edit. Regenerate with:\n\n```\ncargo run -p mecha10-cli --example export_schemas\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\
         This directory is also mirrored verbatim to the public \
         [`mecha-industries/mecha10-schema`](https://github.com/mecha-industries/mecha10-schema) \
         repo (LAB-4067), kept in sync by CI (`scripts/ci/schema-mirror-publish.sh`) — that's the \
         fetchable location for consumers (e.g. the public dashboard docs page, LAB-4054) that \
         can't read this private repo directly.\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
}

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);

    for container_key in ["$defs", "definitions"] {
        if let Some(definitions) = root.get(container_key).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 parse_out_dir_defaults_when_no_args() {
        assert_eq!(parse_out_dir(vec![]).unwrap(), PathBuf::from(DEFAULT_SCHEMA_EXPORT_DIR));
    }

    #[test]
    fn parse_out_dir_reads_out_flag() {
        let args = vec!["--out".to_string(), "custom/dir".to_string()];
        assert_eq!(parse_out_dir(args).unwrap(), PathBuf::from("custom/dir"));
    }

    #[test]
    fn parse_out_dir_rejects_unknown_arg() {
        assert!(parse_out_dir(vec!["--bogus".to_string()]).is_err());
    }

    #[test]
    fn parse_out_dir_rejects_missing_value() {
        assert!(parse_out_dir(vec!["--out".to_string()]).is_err());
    }

    #[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_defs_entries_the_same_as_definitions_entries() {
        let root = json!({
            "type": "object",
            "properties": {
                "source": {"anyOf": [{"$ref": "#/$defs/SourceConfig"}, {"type": "null"}]}
            },
            "$defs": {
                "SourceConfig": {
                    "type": "object",
                    "properties": {"path": {"type": "string"}}
                }
            }
        });
        let mut out = String::new();
        render_schema_body(&root, &root, &mut out, &mut BTreeSet::new());
        assert!(out.contains("### SourceConfig"));
        assert!(out.contains("| `path` | string | no |"));
    }

    #[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 = full_project_schema();
        let behaviors_ref = schema["properties"]["behaviors"]["anyOf"][0]["$ref"]
            .as_str()
            .expect("behaviors should be an anyOf with a $ref variant");
        let def_name = behaviors_ref
            .rsplit('/')
            .next()
            .expect("$ref should have a final segment");
        let behaviors = &schema["$defs"][def_name];

        assert_eq!(def_name, "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 full_project_schema_still_requires_only_name_and_version() {
        let schema = full_project_schema();
        let required: Vec<&str> = schema["required"]
            .as_array()
            .expect("ProjectConfig schema should have a `required` array")
            .iter()
            .filter_map(Value::as_str)
            .collect();
        assert_eq!(required, vec!["name", "version"]);
    }

    #[test]
    fn full_project_schema_still_rejects_an_unknown_build_target_triple_enum_value() {
        let schema = full_project_schema();
        let triples = schema["$defs"]["TargetEntry"]["properties"]["platforms"]["items"]["enum"]
            .as_array()
            .expect("platforms.items should carry the buildTargetTriple enum");
        assert!(triples.iter().any(|t| t == "aarch64-unknown-linux-gnu"));
        assert!(!triples.iter().any(|t| t == "not-a-real-triple"));
    }

    #[test]
    fn full_project_schema_still_accepts_legacy_nodes_drivers_standard_custom_arrays() {
        let schema = full_project_schema();
        let nodes = &schema["properties"]["nodes"];
        assert!(nodes["properties"].get("drivers").is_some());
        assert!(nodes["properties"].get("standard").is_some());
        assert!(nodes["properties"].get("custom").is_some());
        assert!(schema["definitions"].get("node").is_some());
        assert!(schema["definitions"].get("standardNode").is_some());
    }

    #[test]
    fn full_project_schema_still_covers_run_targets_and_scripts() {
        let schema = full_project_schema();
        assert!(schema["properties"].get("run_targets").is_some());
        assert!(schema["properties"].get("scripts").is_some());
        assert!(schema["definitions"].get("runTarget").is_some());
    }

    #[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("base.schema.json")));
        assert!(written.contains(&PathBuf::from("model-catalog.schema.json")));
        assert!(written.contains(&PathBuf::from("environment.schema.json")));
        assert!(written.contains(&PathBuf::from("behavior.schema.json")));
        assert!(written.contains(&PathBuf::from("rl-job.schema.json")));
        assert!(written.contains(&PathBuf::from("README.md")));
        // No `nodes/<type>.schema.json` output at all -- node schemas are API-driven (fetched
        // live from `mecha10-api`'s catalog), not derived or exported from this repo.
        assert!(!written.iter().any(|p| p.starts_with("nodes")));

        assert!(dir.path().join("mecha10.schema.json").exists());
        assert!(dir.path().join("base.schema.json").exists());
        assert!(dir.path().join("model-catalog.schema.json").exists());
        assert!(dir.path().join("environment.schema.json").exists());
        assert!(dir.path().join("behavior.schema.json").exists());
        assert!(dir.path().join("rl-job.schema.json").exists());
        assert!(!dir.path().join("nodes").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 base (common/reserved fields)"));
        assert!(!readme.contains("## Node config: camera"));
        assert!(readme.contains("## Model catalog (model_catalog.toml)"));
        assert!(readme.contains("## Simulation environment (environment.json)"));
        assert!(readme.contains("## Behavior composition (behavior tree config.json)"));
        assert!(readme.contains("## RL training job (configs/rl/jobs/*.yml)"));
        assert!(readme.contains("### ModelCatalogEntry"));
        assert!(readme.contains("| `name` |"));
    }

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

        let written: Value =
            serde_json::from_str(&fs::read_to_string(dir.path().join("environment.schema.json")).unwrap()).unwrap();
        let bundled: Value =
            serde_json::from_str(mecha10_templates::templates::ENVIRONMENT_CONFIG_SCHEMA_JSON).unwrap();
        assert_eq!(written, bundled);
    }

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

        let written: Value =
            serde_json::from_str(&fs::read_to_string(dir.path().join("behavior.schema.json")).unwrap()).unwrap();
        assert_eq!(written, mecha10_behavior_runtime::BehaviorConfig::schema_value());
    }

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

        let written: Value =
            serde_json::from_str(&fs::read_to_string(dir.path().join("base.schema.json")).unwrap()).unwrap();
        assert_eq!(
            written,
            mecha10_schema_registry::schema_for::<mecha10_core::node_config_base::NodeConfigBase>()
        );
        assert!(written["properties"].get("relay_topics").is_some());
    }

    /// Regression test for the LAB-4072 follow-up audit: pins a previously-missing `examples`
    /// keyword on a hand-written schema field so a future change can't silently regress
    /// coverage without a test failing.
    #[test]
    fn export_schemas_fills_in_previously_missing_examples_and_bounds() {
        let dir = tempdir().unwrap();
        export_schemas(dir.path()).unwrap();

        let env: Value =
            serde_json::from_str(&fs::read_to_string(dir.path().join("environment.schema.json")).unwrap()).unwrap();
        assert_eq!(
            env["properties"]["dimensions"]["properties"]["width"]["examples"],
            serde_json::json!([20.0])
        );
    }

    #[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);
    }
}