mecha10-core 0.1.25

# Schema Validation Implementation Summary

## Overview

Implemented comprehensive JSON Schema validation for Mecha10 configuration files to catch errors early with helpful, detailed error messages.

## What Was Implemented

### 1. Core Schema Validation Module (`src/schema_validation.rs`)

**Location**: `/packages/core/src/schema_validation.rs` (850+ lines)

**Key Components**:

- **`get_project_schema()`**: Built-in JSON Schema v7 definition for mecha10.json
- **`get_node_config_schema()`**: JSON Schema for NodeConfig (runtime node configuration)
- **`validate_project_json()`**: Validate serde_json::Value against project schema
- **`validate_project_config()`**: Validate file-based project configuration
- **`validate_node_config_json()`**: Validate NodeConfig JSON
- **`load_and_validate_project()`**: Load and validate in one step
- **`export_project_schema()`**: Export schema to file for IDE integration

**Custom Validation Rules**:
1. **Circular dependency detection**: Prevents infinite loops in node dependencies
2. **Run target reference validation**: Ensures all run_target references exist
3. **Unique node names**: Validates node names are unique across all categories
4. **Resource specification validation**: Validates memory/CPU format correctness

### 2. Schema Definitions

**Project Schema** covers:
- Project metadata (name, version, description, author, license)
- Robot configuration (id, type, platform)
- Node definitions (drivers, standard, custom)
- Run targets (robot, remote, dev, etc.)
- Behaviors (behavior tree configs)
- Simulation settings
- Script shortcuts

**Node Config Schema** covers:
- Node identification (id, name)
- Execution (executable, args, env)
- Lifecycle (mode, auto_restart, health_check_interval_s)
- Topics (publishes, subscribes)
- Dependencies (depends_on)

### 3. Validation Rules

**Pattern Validations**:
- Project names: `^[a-z0-9][a-z0-9-]*$` (lowercase, alphanumeric, hyphens)
- Versions: `^\d+\.\d+\.\d+(-.+)?$` (semver: X.Y.Z or X.Y.Z-suffix)
- Node names: `^[a-z][a-z0-9_]*$` (snake_case)
- Topic names: `^/[a-z0-9/_-]+$` (leading slash, lowercase)
- Env vars: `^[A-Z_][A-Z0-9_]*$` (uppercase, underscores)
- Memory specs: `^\d+(K|M|G|T)?$` (e.g., "512M", "16G")
- CPU limits: `^\d+(\.\d+)?$` (e.g., "2.0", "4")

**Enum Validations**:
- Robot types: `service`, `delivery`, `industrial`, `mobile`, `manipulator`, `custom`
- Node modes: `local`, `remote`, `simulation`
- GPU vendors: `nvidia`, `amd`, `intel`
- Storage types: `local`, `ssd`, `hdd`, `any`

### 4. Integration

**Module Exports**:
- Added to `src/lib.rs` at line 127
- Exported in `src/prelude.rs` (lines 60-65)

**Prelude Exports**:
```rust
pub use crate::schema_validation::{
    validate_project_config, validate_project_json, validate_node_config_json,
    load_and_validate_project, export_project_schema,
    get_project_schema, get_node_config_schema,
};
```

### 5. Examples

**Location**: `/packages/core/examples/schema_validation_usage.rs` (600+ lines)

**11 Examples Covering**:
1. Basic project configuration validation
2. Detecting invalid project names
3. Detecting version format errors
4. Detecting circular dependencies
5. Detecting undefined run_target references
6. Detecting duplicate node names
7. Validating file-based configuration
8. Load and validate in one step
9. Validating node configuration
10. Exporting schema for IDE integration
11. Complex configuration with all features

### 6. Documentation

**Location**: `/packages/core/SCHEMA_VALIDATION_GUIDE.md` (700+ lines)

**Comprehensive Guide Covering**:
- Why schema validation matters
- Features and benefits
- Usage examples
- Configuration structure reference
- Validation rules documentation
- Custom validation rules
- Integration examples (startup, CLI, CI/CD, pre-commit hooks)
- Error message format
- Best practices
- Advanced usage
- Troubleshooting

## Files Created/Modified

### Created:
1. `/packages/core/src/schema_validation.rs` (850+ lines)
2. `/packages/core/examples/schema_validation_usage.rs` (600+ lines)
3. `/packages/core/SCHEMA_VALIDATION_GUIDE.md` (700+ lines)
4. `/packages/core/SCHEMA_VALIDATION_IMPLEMENTATION.md` (this file)

### Modified:
1. `/packages/core/src/lib.rs` - Added module declaration (line 127)
2. `/packages/core/src/prelude.rs` - Added exports (lines 60-65)

## Dependencies

The schema validation module uses:
- `jsonschema` crate for JSON Schema v7 validation
- `serde_json` for JSON handling
- `regex` for pattern validation
- Standard library collections for dependency graph analysis

## Testing

Comprehensive unit tests included in `schema_validation.rs`:

```rust
#[cfg(test)]
mod tests {
    // test_valid_minimal_config
    // test_invalid_name_format
    // test_invalid_version_format
    // test_circular_dependency_detection
    // test_undefined_run_target
    // test_duplicate_node_names
    // test_valid_memory_spec
    // test_node_config_validation
    // test_node_config_invalid_mode
}
```

## Usage

### In Application Code

```rust
use mecha10::prelude::*;

// Validate on startup
validate_project_config("mecha10.json")?;

// Or load and validate
let config = load_and_validate_project("mecha10.json")?;
```

### Export Schema for IDE

```rust
// Export schema file
export_project_schema("project.schema.json")?;
```

Then in `mecha10.json`:
```json
{
  "$schema": "./project.schema.json",
  "name": "my-robot",
  ...
}
```

IDEs will provide auto-complete, inline docs, and real-time validation.

### CLI Integration (Future)

```bash
# Validate project config
mecha10 validate mecha10.json

# Validate node config
mecha10 validate-node config/camera.json

# Export schema
mecha10 schema export project.schema.json
```

## Error Messages

**Before (no validation):**
```
Error: Node failed to start
```

**After (with validation):**
```
Configuration validation failed:
  - /nodes/drivers/0/run_target: references undefined run_target 'robott'
    (Available targets: robot, remote, dev)
  - /nodes/custom/1/name: Duplicate node name 'planner'
    (Node names must be unique across all categories)
```

## Benefits

1. **Early Error Detection**: Catch configuration errors before runtime
2. **Better Error Messages**: Know exactly what's wrong and where
3. **IDE Integration**: Auto-complete and inline validation via $schema
4. **Documentation**: Schema serves as specification
5. **Consistency**: Enforce standards across projects
6. **Confidence**: Deploy knowing configs are valid

## Custom Validation Rules

Beyond JSON Schema, implemented custom rules:

### 1. Circular Dependency Detection
Uses depth-first search to detect cycles in node dependency graph.

**Algorithm**:
```
for each node:
    visited = {}
    stack = {}
    if has_cycle(node, deps, visited, stack):
        error "Circular dependency"
```

### 2. Reference Validation
Ensures all `run_target` references point to defined targets.

**Check**:
- Extract all run_target values from nodes
- Verify each exists in run_targets object
- Provide helpful error with available options

### 3. Uniqueness Validation
Ensures node names are unique across all categories (drivers, standard, custom).

**Check**:
- Collect all node names
- Use HashSet to detect duplicates
- Report which name is duplicated

### 4. Resource Format Validation
Validates memory and CPU specifications follow correct format.

**Checks**:
- Memory: `\d+(K|M|G|T)?` (e.g., "512M")
- CPU: `\d+(\.\d+)?` (e.g., "2.0")
- Provides format examples in error messages

## Example Configurations

### Minimal Valid Config

```json
{
  "name": "my-robot",
  "version": "1.0.0"
}
```

### Complex Valid Config

```json
{
  "$schema": "https://mecha10.dev/schemas/project.schema.json",
  "name": "warehouse-robot",
  "version": "2.1.0-beta",
  "description": "Autonomous warehouse robot",
  "robot": {
    "id": "${ROBOT_ID}",
    "type": "industrial"
  },
  "nodes": {
    "drivers": [...],
    "custom": [...]
  },
  "run_targets": {
    "robot": {...},
    "remote": {...}
  }
}
```

## Future Enhancements

Potential additions:
1. **Schema versioning**: Support multiple schema versions
2. **Warning vs Error**: Distinguish between critical and non-critical issues
3. **Auto-fix suggestions**: Suggest corrections for common errors
4. **Schema evolution**: Migration tools for config updates
5. **Runtime validation**: Validate configs that change at runtime
6. **Web UI**: Interactive config builder with validation

## Conclusion

The schema validation implementation provides:
- ✅ Comprehensive validation for mecha10.json and NodeConfig
- ✅ Custom rules for Mecha10-specific constraints
- ✅ Detailed, helpful error messages
- ✅ IDE integration via JSON Schema
- ✅ Extensive documentation and examples
- ✅ Ready for CI/CD and pre-commit integration

This catches configuration errors early, saving significant debugging time and improving the developer experience.