mecha10_core/

schema_validation.rs

//! JSON Schema Validation for Mecha10 Configuration
//!
//! Provides validation for mecha10.json project configuration files using JSON Schema.
//! This catches configuration errors early with helpful error messages.
//!
//! # Features
//!
//! - JSON Schema v7 validation
//! - Detailed error reporting with line numbers and field paths
//! - Built-in schema for mecha10.json
//! - Custom validation rules for Mecha10-specific constraints
//! - Support for $schema references
//!
//! # Example
//!
//! ```rust
//! use mecha10::prelude::*;
//! use mecha10::schema_validation::{validate_project_config, load_and_validate_project};
//!
//! # async fn example() -> Result<()> {
//! // Validate a config file
//! validate_project_config("mecha10.json")?;
//!
//! // Load and validate in one step
//! let config = load_and_validate_project("mecha10.json")?;
//! # Ok(())
//! # }
//! ```

use crate::error::{Mecha10Error, Result};
use anyhow::Context as _;
use jsonschema::{Draft, JSONSchema, ValidationError};
use serde_json::Value;
use std::collections::HashMap;
use std::fs;
use std::path::Path;
use tracing::{debug, info};

// ============================================================================
// Schema Definitions
// ============================================================================

/// Get the built-in JSON Schema for mecha10.json project configuration
pub fn get_project_schema() -> Value {
    serde_json::json!({
        "$schema": "http://json-schema.org/draft-07/schema#",
        "$id": "https://mecha10.dev/schemas/project.schema.json",
        "title": "Mecha10 Project Configuration",
        "description": "Configuration file for Mecha10 robotics projects",
        "type": "object",
        "required": ["name", "version"],
        "properties": {
            "$schema": {
                "type": "string",
                "description": "JSON Schema reference"
            },
            "name": {
                "type": "string",
                "pattern": "^[a-z0-9][a-z0-9-]*$",
                "minLength": 1,
                "maxLength": 64,
                "description": "Project name (lowercase, alphanumeric, hyphens)"
            },
            "version": {
                "type": "string",
                "pattern": "^\\d+\\.\\d+\\.\\d+(-.+)?$",
                "description": "Semantic version (e.g., '1.0.0' or '1.0.0-beta')"
            },
            "description": {
                "type": "string",
                "maxLength": 500,
                "description": "Project description"
            },
            "author": {
                "type": "string",
                "maxLength": 100,
                "description": "Project author"
            },
            "license": {
                "type": "string",
                "maxLength": 50,
                "description": "License identifier (e.g., MIT, Apache-2.0)"
            },
            "robot": {
                "type": "object",
                "required": ["id", "type"],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^[a-zA-Z0-9_\\-${}]+$",
                        "description": "Robot identifier (can use ${ROBOT_ID} env var)"
                    },
                    "type": {
                        "type": "string",
                        "enum": ["service", "delivery", "industrial", "mobile", "manipulator", "custom"],
                        "description": "Robot type classification"
                    },
                    "platform": {
                        "type": "string",
                        "description": "Hardware platform (e.g., differential-drive, mecanum, ackermann)"
                    }
                },
                "description": "Robot hardware configuration"
            },
            "nodes": {
                "type": "object",
                "properties": {
                    "drivers": {
                        "type": "array",
                        "items": { "$ref": "#/definitions/node" },
                        "description": "Hardware driver nodes"
                    },
                    "standard": {
                        "type": "array",
                        "items": { "$ref": "#/definitions/standardNode" },
                        "description": "Standard/pre-built nodes from packages"
                    },
                    "custom": {
                        "type": "array",
                        "items": { "$ref": "#/definitions/node" },
                        "description": "Custom application nodes"
                    }
                },
                "description": "Node definitions"
            },
            "run_targets": {
                "type": "object",
                "patternProperties": {
                    "^[a-z][a-z0-9_-]*$": {
                        "$ref": "#/definitions/runTarget"
                    }
                },
                "description": "Execution targets (robot, remote, dev, etc.)"
            },
            "behaviors": {
                "type": "object",
                "properties": {
                    "default": {
                        "type": "string",
                        "description": "Default behavior tree file"
                    }
                },
                "additionalProperties": {
                    "type": "string"
                },
                "description": "Behavior tree configurations"
            },
            "simulation": {
                "type": "object",
                "properties": {
                    "enabled": {
                        "type": "boolean",
                        "description": "Enable simulation mode"
                    },
                    "environment": {
                        "type": "string",
                        "description": "Path to simulation environment file"
                    }
                },
                "description": "Simulation settings"
            },
            "scripts": {
                "type": "object",
                "patternProperties": {
                    "^[a-z][a-z0-9:_-]*$": {
                        "type": "string"
                    }
                },
                "description": "Script shortcuts (npm scripts-like)"
            }
        },
        "definitions": {
            "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 (robot, remote, etc.)"
                    },
                    "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/drivers/camera-fake)"
                    },
                    "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"
                    }
                }
            }
        }
    })
}

/// Get the JSON Schema for NodeConfig (runtime node configuration)
pub fn get_node_config_schema() -> Value {
    serde_json::json!({
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "Mecha10 Node Configuration",
        "description": "Runtime configuration for individual nodes",
        "type": "object",
        "required": ["id", "executable"],
        "properties": {
            "id": {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_-]*$",
                "description": "Unique node identifier"
            },
            "name": {
                "type": "string",
                "maxLength": 100,
                "description": "Human-readable name"
            },
            "executable": {
                "type": "string",
                "minLength": 1,
                "description": "Path to executable"
            },
            "args": {
                "type": "array",
                "items": { "type": "string" },
                "description": "Command-line arguments"
            },
            "env": {
                "type": "object",
                "patternProperties": {
                    "^[A-Z_][A-Z0-9_]*$": {
                        "type": "string"
                    }
                },
                "description": "Environment variables"
            },
            "mode": {
                "type": "string",
                "enum": ["local", "remote", "simulation"],
                "default": "local",
                "description": "Execution mode"
            },
            "auto_restart": {
                "type": "boolean",
                "default": true,
                "description": "Auto-restart on crash"
            },
            "health_check_interval_s": {
                "type": "integer",
                "minimum": 1,
                "maximum": 300,
                "default": 5,
                "description": "Health check interval in seconds"
            },
            "publishes": {
                "type": "array",
                "items": {
                    "type": "string",
                    "pattern": "^/[a-z0-9/_-]+$"
                },
                "description": "Topics this node publishes to"
            },
            "subscribes": {
                "type": "array",
                "items": {
                    "type": "string",
                    "pattern": "^/[a-z0-9/_-]+$"
                },
                "description": "Topics this node subscribes to"
            },
            "depends_on": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "description": "Node dependencies"
            }
        }
    })
}

// ============================================================================
// Validation Functions
// ============================================================================

/// Validate a JSON value against the project schema
///
/// # Arguments
///
/// * `config` - The configuration to validate (as serde_json::Value)
///
/// # Returns
///
/// Ok(()) if valid, Err with detailed validation errors if invalid
///
/// # Example
///
/// ```rust
/// use mecha10::schema_validation::validate_project_json;
///
/// let config = serde_json::json!({
///     "name": "my-robot",
///     "version": "1.0.0"
/// });
///
/// validate_project_json(&config)?;
/// ```
pub fn validate_project_json(config: &Value) -> Result<()> {
    let schema = get_project_schema();

    let compiled_schema = JSONSchema::options()
        .with_draft(Draft::Draft7)
        .compile(&schema)
        .map_err(|e| Mecha10Error::Configuration(format!("Invalid schema: {}", e)))?;

    if compiled_schema.is_valid(config) {
        debug!("Project configuration validation passed");
        Ok(())
    } else {
        // Collect errors before compiled_schema is dropped
        let error_messages: Vec<String> = compiled_schema
            .validate(config)
            .unwrap_err()
            .map(|e| format_validation_error(&e))
            .collect();

        Err(Mecha10Error::Configuration(format!(
            "Configuration validation failed:\n{}",
            error_messages.join("\n")
        )))
    }
}

/// Validate a project configuration file
///
/// # Arguments
///
/// * `path` - Path to mecha10.json file
///
/// # Returns
///
/// Ok(()) if valid, Err with detailed validation errors
///
/// # Example
///
/// ```rust
/// use mecha10::schema_validation::validate_project_config;
///
/// validate_project_config("mecha10.json")?;
/// ```
pub fn validate_project_config<P: AsRef<Path>>(path: P) -> Result<()> {
    let path = path.as_ref();

    info!("Validating project configuration: {}", path.display());

    // Read and parse file
    let content = fs::read_to_string(path)
        .with_context(|| format!("Failed to read config file: {}", path.display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    let config: Value = serde_json::from_str(&content)
        .with_context(|| format!("Failed to parse JSON from: {}", path.display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    // Validate against schema
    validate_project_json(&config)?;

    // Additional custom validations
    validate_custom_rules(&config)?;

    info!("Configuration validation passed");
    Ok(())
}

/// Validate NodeConfig JSON against schema
pub fn validate_node_config_json(config: &Value) -> Result<()> {
    let schema = get_node_config_schema();

    let compiled_schema = JSONSchema::options()
        .with_draft(Draft::Draft7)
        .compile(&schema)
        .map_err(|e| Mecha10Error::Configuration(format!("Invalid schema: {}", e)))?;

    if compiled_schema.is_valid(config) {
        debug!("Node configuration validation passed");
        Ok(())
    } else {
        // Collect errors before compiled_schema is dropped
        let error_messages: Vec<String> = compiled_schema
            .validate(config)
            .unwrap_err()
            .map(|e| format_validation_error(&e))
            .collect();

        Err(Mecha10Error::Configuration(format!(
            "Node configuration validation failed:\n{}",
            error_messages.join("\n")
        )))
    }
}

// ============================================================================
// Custom Validation Rules
// ============================================================================

/// Apply custom validation rules beyond JSON Schema
fn validate_custom_rules(config: &Value) -> Result<()> {
    // Rule 1: Check for circular dependencies in nodes
    if let Some(nodes) = config.get("nodes") {
        validate_no_circular_dependencies(nodes)?;
    }

    // Rule 2: Check run_target references exist
    if let Some(nodes) = config.get("nodes") {
        if let Some(targets) = config.get("run_targets") {
            validate_run_target_references(nodes, targets)?;
        }
    }

    // Rule 3: Check node names are unique across all categories
    if let Some(nodes) = config.get("nodes") {
        validate_unique_node_names(nodes)?;
    }

    // Rule 4: Validate resource specifications
    if let Some(targets) = config.get("run_targets") {
        validate_resource_specs(targets)?;
    }

    Ok(())
}

/// Check for circular dependencies in node definitions
fn validate_no_circular_dependencies(nodes: &Value) -> Result<()> {
    let mut node_deps: HashMap<String, Vec<String>> = HashMap::new();

    // Collect all dependencies
    for category in ["drivers", "standard", "custom"] {
        if let Some(node_list) = nodes.get(category).and_then(|v| v.as_array()) {
            for node in node_list {
                if let Some(name) = node.get("name").and_then(|n| n.as_str()) {
                    let deps = node
                        .get("depends_on")
                        .and_then(|d| d.as_array())
                        .map(|arr| arr.iter().filter_map(|v| v.as_str().map(String::from)).collect())
                        .unwrap_or_default();

                    node_deps.insert(name.to_string(), deps);
                }
            }
        }
    }

    // Check for cycles using DFS
    for node in node_deps.keys() {
        let mut visited = std::collections::HashSet::new();
        let mut stack = std::collections::HashSet::new();

        if has_cycle(node, &node_deps, &mut visited, &mut stack) {
            return Err(Mecha10Error::Configuration(format!(
                "Circular dependency detected involving node '{}'",
                node
            )));
        }
    }

    Ok(())
}

fn has_cycle(
    node: &str,
    deps: &HashMap<String, Vec<String>>,
    visited: &mut std::collections::HashSet<String>,
    stack: &mut std::collections::HashSet<String>,
) -> bool {
    if stack.contains(node) {
        return true; // Cycle detected
    }

    if visited.contains(node) {
        return false; // Already checked
    }

    visited.insert(node.to_string());
    stack.insert(node.to_string());

    if let Some(dependencies) = deps.get(node) {
        for dep in dependencies {
            if has_cycle(dep, deps, visited, stack) {
                return true;
            }
        }
    }

    stack.remove(node);
    false
}

/// Validate that all run_target references exist
fn validate_run_target_references(nodes: &Value, targets: &Value) -> Result<()> {
    let target_names: Vec<String> = targets
        .as_object()
        .map(|obj| obj.keys().cloned().collect())
        .unwrap_or_default();

    for category in ["drivers", "custom"] {
        if let Some(node_list) = nodes.get(category).and_then(|v| v.as_array()) {
            for node in node_list {
                if let Some(run_target) = node.get("run_target").and_then(|t| t.as_str()) {
                    if !target_names.contains(&run_target.to_string()) {
                        let node_name = node.get("name").and_then(|n| n.as_str()).unwrap_or("<unnamed>");

                        return Err(Mecha10Error::Configuration(format!(
                            "Node '{}' references undefined run_target '{}'. Available targets: {}",
                            node_name,
                            run_target,
                            target_names.join(", ")
                        )));
                    }
                }
            }
        }
    }

    Ok(())
}

/// Validate that node names are unique
fn validate_unique_node_names(nodes: &Value) -> Result<()> {
    let mut seen_names = std::collections::HashSet::new();

    for category in ["drivers", "standard", "custom"] {
        if let Some(node_list) = nodes.get(category).and_then(|v| v.as_array()) {
            for node in node_list {
                if let Some(name) = node.get("name").and_then(|n| n.as_str()) {
                    if !seen_names.insert(name.to_string()) {
                        return Err(Mecha10Error::Configuration(format!(
                            "Duplicate node name '{}' found. Node names must be unique across all categories.",
                            name
                        )));
                    }
                }
            }
        }
    }

    Ok(())
}

/// Validate resource specifications
fn validate_resource_specs(targets: &Value) -> Result<()> {
    if let Some(targets_obj) = targets.as_object() {
        for (target_name, target_config) in targets_obj {
            if let Some(resources) = target_config.get("resources") {
                // Validate memory format
                if let Some(mem_limit) = resources.get("memory_limit").and_then(|m| m.as_str()) {
                    if !is_valid_memory_spec(mem_limit) {
                        return Err(Mecha10Error::Configuration(format!(
                            "Invalid memory_limit '{}' in run_target '{}'. Expected format: <number><K|M|G|T>",
                            mem_limit, target_name
                        )));
                    }
                }

                // Validate CPU format
                if let Some(cpu_limit) = resources.get("cpu_limit").and_then(|c| c.as_str()) {
                    if cpu_limit.parse::<f64>().is_err() {
                        return Err(Mecha10Error::Configuration(format!(
                            "Invalid cpu_limit '{}' in run_target '{}'. Expected a number (e.g., '2.0')",
                            cpu_limit, target_name
                        )));
                    }
                }
            }
        }
    }

    Ok(())
}

fn is_valid_memory_spec(spec: &str) -> bool {
    let re = regex::Regex::new(r"^\d+(K|M|G|T)?$").unwrap();
    re.is_match(spec)
}

// ============================================================================
// Helper Functions
// ============================================================================

/// Format a validation error into a human-readable message
fn format_validation_error(error: &ValidationError) -> String {
    let path_str = error.instance_path.to_string();
    let path = if path_str.is_empty() || path_str == "/" {
        "root".to_string()
    } else {
        path_str
    };

    format!("  - {}: {} ({})", path, error, error.instance)
}

// ============================================================================
// High-Level API
// ============================================================================

/// Load and validate a project configuration file
///
/// This combines loading and validation into one convenient function.
///
/// # Example
///
/// ```rust
/// use mecha10::schema_validation::load_and_validate_project;
///
/// let config = load_and_validate_project("mecha10.json")?;
/// println!("Project: {}", config["name"]);
/// ```
pub fn load_and_validate_project<P: AsRef<Path>>(path: P) -> Result<Value> {
    let path = path.as_ref();

    // Read file
    let content = fs::read_to_string(path)
        .with_context(|| format!("Failed to read config file: {}", path.display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    // Parse JSON
    let config: Value = serde_json::from_str(&content)
        .with_context(|| format!("Failed to parse JSON: {}", path.display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    // Validate
    validate_project_json(&config)?;
    validate_custom_rules(&config)?;

    Ok(config)
}

/// Export the JSON Schema to a file
///
/// Useful for IDE integration and documentation.
///
/// # Example
///
/// ```rust
/// use mecha10::schema_validation::export_project_schema;
///
/// export_project_schema("project.schema.json")?;
/// ```
pub fn export_project_schema<P: AsRef<Path>>(path: P) -> Result<()> {
    let schema = get_project_schema();
    let json = serde_json::to_string_pretty(&schema)
        .map_err(|e| Mecha10Error::Configuration(format!("Failed to serialize schema: {}", e)))?;

    fs::write(path.as_ref(), json)
        .with_context(|| format!("Failed to write schema to: {}", path.as_ref().display()))
        .map_err(|e| Mecha10Error::Configuration(format!("{:#}", e)))?;

    info!("Exported schema to: {}", path.as_ref().display());
    Ok(())
}