bnto-core 0.18.0

// Definition JSON Schema — Validates `.bnto.json` files.
//
// Generates a JSON Schema (Draft 2020-12) describing the Definition format.
// Built by hand with `serde_json::json!()` — simpler than a codegen library
// since the Definition shape is stable. Makes the engine the single source
// of truth for both execution and validation.

use serde_json::Value;

/// Build the JSON Schema for a `Port` object (connection point on a node).
fn port_schema() -> Value {
    serde_json::json!({
        "type": "object",
        "description": "A connection point on a node (input or output).",
        "required": ["id", "name"],
        "properties": {
            "id": {
                "type": "string",
                "description": "Unique identifier for this port within its node."
            },
            "name": {
                "type": "string",
                "description": "Human-readable display name for the port."
            },
            "handle": {
                "type": "string",
                "description": "Optional handle identifier used by the visual editor for positioning."
            }
        },
        "additionalProperties": false
    })
}

/// Build the JSON Schema for an `Edge` (connection between two nodes).
fn edge_schema() -> Value {
    serde_json::json!({
        "type": "object",
        "description": "A connection between two nodes in the pipeline graph.",
        "required": ["id", "source", "target"],
        "properties": {
            "id": {
                "type": "string",
                "description": "Unique identifier for this edge."
            },
            "source": {
                "type": "string",
                "description": "The id of the source node (where data flows FROM)."
            },
            "target": {
                "type": "string",
                "description": "The id of the target node (where data flows TO)."
            },
            "sourceHandle": {
                "type": "string",
                "description": "Optional: which output port on the source node."
            },
            "targetHandle": {
                "type": "string",
                "description": "Optional: which input port on the target node."
            }
        },
        "additionalProperties": false
    })
}

/// Build the JSON Schema for the `metadata` object (description, timestamps, tags).
fn metadata_schema() -> Value {
    serde_json::json!({
        "type": "object",
        "description": "Descriptive metadata about the node (description, timestamps, tags).",
        "properties": {
            "description": {
                "type": "string",
                "description": "Human-readable description of what this node does."
            },
            "createdAt": {
                "type": "string",
                "description": "ISO 8601 timestamp of when this node was created."
            },
            "updatedAt": {
                "type": "string",
                "description": "ISO 8601 timestamp of the last modification."
            },
            "tags": {
                "type": "array",
                "description": "Tags for categorization and search.",
                "items": { "type": "string" }
            },
            "customData": {
                "type": "object",
                "description": "Open-ended key-value pairs for consumer-specific data.",
                "additionalProperties": { "type": "string" }
            }
        },
        "additionalProperties": false
    })
}

/// Build the JSON Schema for `PipelineSettings` (recipe-level configuration).
fn pipeline_settings_schema() -> Value {
    serde_json::json!({
        "type": "object",
        "description": "Recipe-level settings that control execution behavior.",
        "properties": {
            "iteration": {
                "type": "string",
                "description": "How the executor handles iteration over multiple input files. 'auto' wraps primitive sequences in implicit per-file loops; 'explicit' (default) executes exactly what's defined.",
                "enum": ["auto", "explicit"],
                "default": "explicit"
            },
            "timeout": {
                "type": "integer",
                "minimum": 1,
                "description": "The whole run's time limit in seconds. Once it passes, every step the run started is stopped and the run fails. No limit when unset; `bnto run --timeout` overrides it."
            }
        },
        "additionalProperties": false
    })
}

// --- Definition Schema ---

/// Build the JSON Schema for a canvas position (`{ x, y }`).
fn position_schema() -> Value {
    serde_json::json!({
        "type": "object",
        "description": "The node's position on the visual editor canvas.",
        "required": ["x", "y"],
        "properties": {
            "x": { "type": "number" },
            "y": { "type": "number" }
        },
        "additionalProperties": false
    })
}

/// Build the properties map for the Definition schema.
fn definition_properties() -> Value {
    serde_json::json!({
        "id":         { "type": "string", "description": "Unique identifier for this node within the recipe." },
        "type":       { "type": "string", "description": "The node type (e.g., 'image-compress', 'spreadsheet-clean', 'file-rename')." },
        "version":    { "type": "string", "description": "Format version (semver, e.g., '1.0.0')." },
        "parentId":   { "type": "string", "description": "Optional parent node id (for nested nodes)." },
        "name":       { "type": "string", "description": "Human-readable name for this node." },
        "position":   position_schema(),
        "metadata":   { "$ref": "#/$defs/Metadata" },
        "parameters": { "type": "object", "description": "Configuration parameters (key-value pairs).", "additionalProperties": true },
        "inputPorts": { "type": "array", "description": "Input connection ports.", "items": { "$ref": "#/$defs/Port" } },
        "outputPorts":{ "type": "array", "description": "Output connection ports.", "items": { "$ref": "#/$defs/Port" } },
        "settings":   { "$ref": "#/$defs/PipelineSettings" },
        "always":     { "type": "boolean", "default": false, "description": "Closing step: run even after an earlier node in the same chain failed, like `finally`. The run still fails with the first error." },
        "when":       { "$ref": "#/$defs/When" },
        "requires":   { "type": "array", "description": "External tools this node needs. At the root, needed on every OS; on a nested node, checked only on the OSes that node runs on (its platform guards).", "items": { "$ref": "#/$defs/Dependency" } },
        "nodes":      { "type": "array", "description": "Child nodes (recursive).", "items": { "$ref": "#/$defs/Definition" } },
        "edges":      { "type": "array", "description": "Connections between child nodes.", "items": { "$ref": "#/$defs/Edge" } }
    })
}

/// An external tool a node needs (`requires`).
fn dependency_schema() -> Value {
    serde_json::json!({
        "type": "object",
        "description": "An external program that must be on the PATH.",
        "required": ["binary"],
        "properties": {
            "binary":       { "type": "string", "description": "The program's name, as looked up on the PATH." },
            "version":      { "type": "string", "description": "A version constraint, e.g. >=6.0." },
            "installHint":  { "type": "string", "description": "How to install it, when no per-OS hint applies." },
            "installHints": {
                "type": "object",
                "description": "How to install it on each OS.",
                "properties": {
                    "macos":   { "type": "string" },
                    "linux":   { "type": "string" },
                    "windows": { "type": "string" }
                },
                "additionalProperties": false
            },
            "homepage":     { "type": "string", "description": "Where to read about it." }
        },
        "additionalProperties": false
    })
}

/// A node's `when` guard: run the step only when the comparison holds.
fn when_schema() -> Value {
    serde_json::json!({
        "type": "object",
        "description": "Run this step only when the comparison holds; otherwise skip it and pass its files through untouched. Templates work in value and expected, e.g. {{ctx.platform}} or {{fields.action}}.",
        "required": ["value", "op", "expected"],
        "properties": {
            "value":    { "type": "string", "description": "What to compare, usually a template such as {{ctx.platform}}." },
            "op":       { "type": "string", "enum": ["equals", "not-equals", "after", "before"], "description": "How value is compared to expected. after and before compare RFC 3339 times." },
            "expected": { "type": "string", "description": "What value is compared to." }
        },
        "additionalProperties": false
    })
}

/// Generate a JSON Schema (Draft 2020-12) for the `.bnto.json` Definition format.
///
/// The Definition is recursive — child `nodes` reference the same schema via `$ref`.
pub fn definition_json_schema() -> Value {
    serde_json::json!({
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "title": "Bnto Definition",
        "description": "A .bnto.json recipe definition. Describes a pipeline of nodes that process data.",
        "$ref": "#/$defs/Definition",
        "$defs": {
            "Port": port_schema(),
            "Edge": edge_schema(),
            "Metadata": metadata_schema(),
            "PipelineSettings": pipeline_settings_schema(),
            "When": when_schema(),
            "Dependency": dependency_schema(),
            "Definition": {
                "type": "object",
                "description": "A single node in a .bnto.json recipe. Can contain child nodes (recursive).",
                "required": ["id", "type", "version", "name", "position", "metadata", "parameters", "inputPorts", "outputPorts"],
                "properties": definition_properties(),
                "additionalProperties": true
            }
        }
    })
}

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

    #[test]
    fn test_definition_schema_is_valid_json_object() {
        // The schema should be a valid JSON object (not null, not an array).
        let schema = definition_json_schema();
        assert!(schema.is_object(), "Schema should be a JSON object");
    }

    #[test]
    fn test_definition_schema_has_correct_meta_fields() {
        // Verify the schema metadata fields are present and correct.
        let schema = definition_json_schema();
        assert_eq!(
            schema["$schema"],
            "https://json-schema.org/draft/2020-12/schema"
        );
        assert_eq!(schema["title"], "Bnto Definition");
        assert!(schema["description"].is_string());
    }

    #[test]
    fn test_definition_schema_uses_ref_to_defs() {
        // The top-level schema should reference $defs/Definition.
        let schema = definition_json_schema();
        assert_eq!(schema["$ref"], "#/$defs/Definition");
    }

    #[test]
    fn test_definition_schema_has_all_defs() {
        // The $defs block should contain all 5 type definitions.
        let schema = definition_json_schema();
        let defs = schema["$defs"]
            .as_object()
            .expect("$defs should be an object");
        assert!(
            defs.contains_key("Definition"),
            "Missing Definition in $defs"
        );
        assert!(defs.contains_key("Port"), "Missing Port in $defs");
        assert!(defs.contains_key("Edge"), "Missing Edge in $defs");
        assert!(defs.contains_key("Metadata"), "Missing Metadata in $defs");
        assert!(
            defs.contains_key("PipelineSettings"),
            "Missing PipelineSettings in $defs"
        );
    }

    #[test]
    fn test_definition_has_required_properties() {
        // The Definition schema should list the correct required fields.
        let schema = definition_json_schema();
        let def = &schema["$defs"]["Definition"];
        let required = def["required"]
            .as_array()
            .expect("required should be an array");

        // Convert to strings for comparison.
        let required_strs: Vec<&str> = required.iter().map(|v| v.as_str().unwrap()).collect();

        assert!(required_strs.contains(&"id"));
        assert!(required_strs.contains(&"type"));
        assert!(required_strs.contains(&"version"));
        assert!(required_strs.contains(&"name"));
        assert!(required_strs.contains(&"position"));
        assert!(required_strs.contains(&"metadata"));
        assert!(required_strs.contains(&"parameters"));
        assert!(required_strs.contains(&"inputPorts"));
        assert!(required_strs.contains(&"outputPorts"));
    }

    #[test]
    fn test_definition_has_recursive_nodes() {
        // The `nodes` field should reference $defs/Definition (recursive).
        let schema = definition_json_schema();
        let nodes_items = &schema["$defs"]["Definition"]["properties"]["nodes"]["items"];
        assert_eq!(
            nodes_items["$ref"], "#/$defs/Definition",
            "nodes items should reference Definition recursively"
        );
    }

    #[test]
    fn test_port_schema_has_required_fields() {
        // Port should require id and name.
        let schema = definition_json_schema();
        let port = &schema["$defs"]["Port"];
        let required = port["required"]
            .as_array()
            .expect("Port required should be an array");
        let required_strs: Vec<&str> = required.iter().map(|v| v.as_str().unwrap()).collect();
        assert!(required_strs.contains(&"id"));
        assert!(required_strs.contains(&"name"));
    }

    #[test]
    fn test_edge_schema_has_required_fields() {
        // Edge should require id, source, and target.
        let schema = definition_json_schema();
        let edge = &schema["$defs"]["Edge"];
        let required = edge["required"]
            .as_array()
            .expect("Edge required should be an array");
        let required_strs: Vec<&str> = required.iter().map(|v| v.as_str().unwrap()).collect();
        assert!(required_strs.contains(&"id"));
        assert!(required_strs.contains(&"source"));
        assert!(required_strs.contains(&"target"));
    }

    #[test]
    fn test_definition_schema_has_settings_property() {
        let schema = definition_json_schema();
        let props = schema["$defs"]["Definition"]["properties"]
            .as_object()
            .expect("Definition properties should be an object");
        assert!(
            props.contains_key("settings"),
            "Definition should have a settings property"
        );
        assert_eq!(
            props["settings"]["$ref"], "#/$defs/PipelineSettings",
            "settings should reference PipelineSettings"
        );
    }

    #[test]
    fn test_any_node_can_carry_requires() {
        let schema = definition_json_schema();
        let requires = &schema["$defs"]["Definition"]["properties"]["requires"];
        assert_eq!(requires["items"]["$ref"], "#/$defs/Dependency");
        let dep = &schema["$defs"]["Dependency"];
        assert_eq!(dep["required"], serde_json::json!(["binary"]));
        let hints = dep["properties"]["installHints"]["properties"]
            .as_object()
            .unwrap();
        assert!(hints.contains_key("macos") && hints.contains_key("windows"));
    }

    #[test]
    fn test_definition_schema_has_a_when_guard() {
        let schema = definition_json_schema();
        let when = &schema["$defs"]["Definition"]["properties"]["when"];
        assert_eq!(when["$ref"], "#/$defs/When");
        let guard = &schema["$defs"]["When"];
        assert_eq!(
            guard["required"],
            serde_json::json!(["value", "op", "expected"])
        );
        let ops = guard["properties"]["op"]["enum"].as_array().unwrap();
        assert!(ops.contains(&"not-equals".into()), "{ops:?}");
    }

    #[test]
    fn test_definition_schema_has_always_boolean() {
        let schema = definition_json_schema();
        let always = &schema["$defs"]["Definition"]["properties"]["always"];
        assert_eq!(always["type"], "boolean");
        assert_eq!(always["default"], false);
    }

    #[test]
    fn test_settings_schema_has_iteration_enum() {
        let schema = definition_json_schema();
        let settings = &schema["$defs"]["PipelineSettings"];
        let iteration = &settings["properties"]["iteration"];
        let enum_values = iteration["enum"]
            .as_array()
            .expect("iteration should have an enum");
        let values: Vec<&str> = enum_values.iter().map(|v| v.as_str().unwrap()).collect();
        assert!(values.contains(&"auto"));
        assert!(values.contains(&"explicit"));
        assert_eq!(iteration["default"], "explicit");
    }

    #[test]
    fn test_settings_schema_has_timeout_in_whole_seconds() {
        let schema = definition_json_schema();
        let timeout = &schema["$defs"]["PipelineSettings"]["properties"]["timeout"];
        assert_eq!(timeout["type"], "integer");
        assert_eq!(timeout["minimum"], 1);
    }

    #[test]
    fn test_definition_schema_has_pipeline_settings_def() {
        let schema = definition_json_schema();
        let defs = schema["$defs"]
            .as_object()
            .expect("$defs should be an object");
        let settings = defs
            .get("PipelineSettings")
            .expect("PipelineSettings should exist in $defs");
        assert_eq!(settings["type"], "object");
        assert!(
            settings["properties"]["iteration"].is_object(),
            "PipelineSettings should have an iteration property"
        );
    }
}