delimit-cli 2.4.0 → 3.0.0

package/gateway/tasks/validate_api.py

@@ -0,0 +1,131 @@
+import yaml
+import json
+from typing import Dict, List, Any
+from core.registry import task_registry
+from schemas.base import TaskRequest
+
+register_task = task_registry.register
+
+@register_task("validate-api", version="v1", description="Validate API for breaking changes")
+def validate_api_handler(request: TaskRequest) -> Dict[str, Any]:
+    """Check API specifications for breaking changes"""
+    
+    files = request.files
+    if len(files) != 2:
+        raise ValueError("validate-api requires exactly 2 files: old and new API spec")
+    
+    old_spec = load_spec(files[0])
+    new_spec = load_spec(files[1])
+    
+    breaking_changes = []
+    warnings = []
+    
+    # Check removed endpoints
+    old_paths = set(old_spec.get("paths", {}).keys())
+    new_paths = set(new_spec.get("paths", {}).keys())
+    
+    removed = old_paths - new_paths
+    if removed:
+        for path in removed:
+            breaking_changes.append({
+                "type": "endpoint_removed",
+                "path": path,
+                "severity": "high"
+            })
+    
+    # Check modified endpoints
+    for path in old_paths & new_paths:
+        old_methods = set(old_spec["paths"][path].keys())
+        new_methods = set(new_spec["paths"][path].keys())
+        
+        removed_methods = old_methods - new_methods
+        if removed_methods:
+            for method in removed_methods:
+                breaking_changes.append({
+                    "type": "method_removed",
+                    "path": path,
+                    "method": method.upper(),
+                    "severity": "high"
+                })
+        
+        # Check parameter changes
+        for method in old_methods & new_methods:
+            old_params = old_spec["paths"][path][method].get("parameters", [])
+            new_params = new_spec["paths"][path][method].get("parameters", [])
+            
+            old_required = {p["name"] for p in old_params if p.get("required", False)}
+            new_required = {p["name"] for p in new_params if p.get("required", False)}
+            
+            new_required_params = new_required - old_required
+            if new_required_params:
+                for param in new_required_params:
+                    breaking_changes.append({
+                        "type": "required_parameter_added",
+                        "path": path,
+                        "method": method.upper(),
+                        "parameter": param,
+                        "severity": "high"
+                    })
+    
+    # Check for new optional endpoints (non-breaking)
+    added = new_paths - old_paths
+    if added:
+        for path in added:
+            warnings.append(f"New endpoint added: {path}")
+    
+    risk_score = calculate_risk_score(breaking_changes)
+    
+    return {
+        "breaking_changes": breaking_changes,
+        "warnings": warnings,
+        "risk_score": risk_score,
+        "risk_level": get_risk_level(risk_score),
+        "summary": {
+            "total_breaking_changes": len(breaking_changes),
+            "endpoints_removed": len([c for c in breaking_changes if c["type"] == "endpoint_removed"]),
+            "methods_removed": len([c for c in breaking_changes if c["type"] == "method_removed"]),
+            "required_params_added": len([c for c in breaking_changes if c["type"] == "required_parameter_added"])
+        }
+    }
+
+def load_spec(file_path: str) -> Dict:
+    """Load API specification from YAML or JSON"""
+    with open(file_path, 'r') as f:
+        if file_path.endswith('.yaml') or file_path.endswith('.yml'):
+            return yaml.safe_load(f)
+        elif file_path.endswith('.json'):
+            return json.load(f)
+        else:
+            # Try YAML first, then JSON
+            content = f.read()
+            try:
+                return yaml.safe_load(content)
+            except:
+                return json.loads(content)
+
+def calculate_risk_score(breaking_changes: List[Dict]) -> int:
+    """Calculate risk score based on breaking changes"""
+    if not breaking_changes:
+        return 0
+    
+    score = 0
+    for change in breaking_changes:
+        if change["severity"] == "high":
+            score += 10
+        elif change["severity"] == "medium":
+            score += 5
+        else:
+            score += 1
+    
+    return min(score, 100)
+
+def get_risk_level(score: int) -> str:
+    """Convert risk score to level"""
+    if score == 0:
+        return "none"
+    elif score < 20:
+        return "low"
+    elif score < 50:
+        return "medium"
+    else:
+        return "high"

package/gateway/tasks/validate_api_v2.py

@@ -0,0 +1,208 @@
+"""
+Validate API task with Evidence Contract
+V12 Core Hardening
+"""
+
+import yaml
+import json
+from typing import Dict, List, Set
+from pathlib import Path
+
+from core.registry_v2 import task_registry
+from schemas.requests import ValidateAPIRequest
+from schemas.evidence import (
+    APIChangeEvidence, Decision, Violation, ViolationSeverity,
+    Evidence, Remediation
+)
+
+
+@task_registry.register("validate-api", version="1.0", description="Check API for breaking changes")
+def validate_api_handler(request: ValidateAPIRequest) -> APIChangeEvidence:
+    """Check API specifications for breaking changes with evidence contract"""
+    
+    # Load specifications
+    old_spec = load_spec(request.old_spec)
+    new_spec = load_spec(request.new_spec)
+    
+    # Analyze changes
+    violations = []
+    evidence_list = []
+    breaking_changes = []
+    non_breaking_changes = []
+    
+    # Check removed endpoints
+    old_paths = set(old_spec.get("paths", {}).keys())
+    new_paths = set(new_spec.get("paths", {}).keys())
+    
+    removed_paths = old_paths - new_paths
+    for path in removed_paths:
+        violations.append(Violation(
+            rule="no_removed_endpoint",
+            severity=ViolationSeverity.HIGH,
+            path=path,
+            message=f"Endpoint removed: {path}",
+            details={"type": "endpoint_removed"}
+        ))
+        breaking_changes.append({
+            "type": "endpoint_removed",
+            "path": path
+        })
+        evidence_list.append(Evidence(
+            rule="no_removed_endpoint",
+            passed=False,
+            details={"path": path, "status": "removed"}
+        ))
+    
+    # Check for removed methods
+    for path in old_paths & new_paths:
+        old_methods = set(old_spec["paths"][path].keys())
+        new_methods = set(new_spec["paths"][path].keys())
+        
+        removed_methods = old_methods - new_methods
+        for method in removed_methods:
+            violations.append(Violation(
+                rule="no_removed_method",
+                severity=ViolationSeverity.HIGH,
+                path=f"{path}:{method.upper()}",
+                message=f"Method removed: {method.upper()} {path}",
+                details={"type": "method_removed", "method": method}
+            ))
+            breaking_changes.append({
+                "type": "method_removed",
+                "path": path,
+                "method": method.upper()
+            })
+            evidence_list.append(Evidence(
+                rule="no_removed_method",
+                passed=False,
+                details={"path": path, "method": method, "status": "removed"}
+            ))
+        
+        # Check for new required parameters (breaking)
+        for method in old_methods & new_methods:
+            old_params = extract_parameters(old_spec["paths"][path][method])
+            new_params = extract_parameters(new_spec["paths"][path][method])
+            
+            old_required = {p["name"] for p in old_params if p.get("required", False)}
+            new_required = {p["name"] for p in new_params if p.get("required", False)}
+            
+            newly_required = new_required - old_required
+            for param in newly_required:
+                violations.append(Violation(
+                    rule="no_new_required_param",
+                    severity=ViolationSeverity.HIGH,
+                    path=f"{path}:{method.upper()}",
+                    message=f"New required parameter: {param}",
+                    details={"type": "required_param_added", "parameter": param}
+                ))
+                breaking_changes.append({
+                    "type": "required_param_added",
+                    "path": path,
+                    "method": method.upper(),
+                    "parameter": param
+                })
+                evidence_list.append(Evidence(
+                    rule="no_new_required_param",
+                    passed=False,
+                    details={"path": path, "method": method, "parameter": param}
+                ))
+    
+    # Check for added endpoints (non-breaking)
+    added_paths = new_paths - old_paths
+    for path in added_paths:
+        non_breaking_changes.append({
+            "type": "endpoint_added",
+            "path": path
+        })
+        evidence_list.append(Evidence(
+            rule="backward_compatible_additions",
+            passed=True,
+            details={"path": path, "status": "added"}
+        ))
+    
+    # Determine decision and exit code
+    if violations:
+        decision = Decision.FAIL
+        exit_code = 1
+        summary = f"API validation failed: {len(violations)} breaking changes detected"
+    else:
+        decision = Decision.PASS
+        exit_code = 0
+        summary = "API validation passed: No breaking changes detected"
+    
+    # Calculate risk score
+    risk_score = min(len(violations) * 10, 100)
+    
+    # Build remediation if needed
+    remediation = None
+    if violations:
+        remediation = Remediation(
+            summary="Breaking changes detected in API specification",
+            steps=[
+                "Option 1: Restore removed endpoints/methods to maintain compatibility",
+                "Option 2: Create a new API version (e.g., v2) for breaking changes",
+                "Option 3: Implement deprecation warnings before removal",
+                "Option 4: Document migration path for API consumers"
+            ],
+            examples=[
+                "Keep old endpoint with deprecation notice",
+                "Add version prefix: /v2/api/..."
+            ],
+            documentation="https://docs.delimit.ai/api-versioning"
+        )
+    
+    # Return evidence contract
+    return APIChangeEvidence(
+        task="validate-api",
+        task_version="1.0",
+        decision=decision,
+        exit_code=exit_code,
+        violations=violations,
+        evidence=evidence_list,
+        remediation=remediation,
+        summary=summary,
+        correlation_id=request.correlation_id,
+        metrics={
+            "endpoints_checked": len(old_paths | new_paths),
+            "breaking_changes": len(breaking_changes),
+            "non_breaking_changes": len(non_breaking_changes)
+        },
+        breaking_changes=breaking_changes,
+        non_breaking_changes=non_breaking_changes,
+        risk_score=risk_score
+    )
+
+
+def load_spec(file_path: str) -> Dict:
+    """Load API specification from file"""
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Spec file not found: {file_path}\n"
+            f"If the spec was deleted, ensure both old and new spec paths exist before running validation."
+        )
+    with path.open('r') as f:
+        if path.suffix in ['.yaml', '.yml']:
+            return yaml.safe_load(f)
+        elif path.suffix == '.json':
+            return json.load(f)
+        else:
+            # Try YAML first, then JSON
+            content = f.read()
+            try:
+                return yaml.safe_load(content)
+            except:
+                return json.loads(content)
+
+
+def extract_parameters(operation: Dict) -> List[Dict]:
+    """Extract parameters from an operation"""
+    params = operation.get("parameters", [])
+    # Also check requestBody for required fields
+    if "requestBody" in operation and operation["requestBody"].get("required", False):
+        params.append({
+            "name": "requestBody",
+            "required": True,
+            "in": "body"
+        })
+    return params

package/gateway/tasks/validate_api_v3.py

@@ -0,0 +1,163 @@
+"""
+Validate API task with Evidence Contract - V12 Final
+Complete implementation with Pydantic v2
+"""
+
+import yaml
+import json
+from typing import Dict, List, Set
+from pathlib import Path
+
+from core.registry_v3 import task_registry
+from core.diff_engine_v2 import OpenAPIDiffEngine, ChangeType
+from schemas.requests_v2 import ValidateAPIRequest
+from schemas.evidence import (
+    APIChangeEvidence, Decision, Violation, ViolationSeverity,
+    Evidence, Remediation
+)
+
+
+@task_registry.register("validate-api", task_version="1.0", description="Check API for breaking changes")
+def validate_api_handler(request: ValidateAPIRequest) -> APIChangeEvidence:
+    """Check API specifications for breaking changes with evidence contract"""
+    
+    # Load specifications
+    old_spec = load_spec(request.old_spec)
+    new_spec = load_spec(request.new_spec)
+    
+    # Use diff engine for comprehensive change detection
+    diff_engine = OpenAPIDiffEngine()
+    all_changes = diff_engine.compare(old_spec, new_spec)
+    
+    # Process changes from diff engine
+    violations = []
+    evidence_list = []
+    breaking_changes = []
+    non_breaking_changes = []
+    
+    for change in all_changes:
+        if change.is_breaking:
+            # Convert to violation
+            violations.append(Violation(
+                rule=f"no_{change.type.value}",
+                severity=ViolationSeverity.HIGH if change.severity == "high" else ViolationSeverity.MEDIUM,
+                path=change.path,
+                message=change.message,
+                details=change.details
+            ))
+            breaking_changes.append({
+                "type": change.type.value,
+                "path": change.path,
+                **change.details
+            })
+            evidence_list.append(Evidence(
+                rule=f"no_{change.type.value}",
+                passed=False,
+                details={"path": change.path, **change.details}
+            ))
+        else:
+            # Non-breaking change
+            non_breaking_changes.append({
+                "type": change.type.value,
+                "path": change.path,
+                **change.details
+            })
+            evidence_list.append(Evidence(
+                rule="backward_compatible_additions",
+                passed=True,
+                details={"path": change.path, **change.details}
+            ))
+    
+    # Also keep legacy endpoint checks for backward compatibility
+    # Legacy checks are now handled by diff engine above
+    
+    # Get path counts for metrics
+    old_paths = set(old_spec.get("paths", {}).keys())
+    new_paths = set(new_spec.get("paths", {}).keys())
+    
+    # Determine decision and exit code
+    if violations:
+        decision = Decision.FAIL
+        exit_code = 1
+        summary = f"API validation failed: {len(violations)} breaking changes detected"
+    else:
+        decision = Decision.PASS
+        exit_code = 0
+        summary = "API validation passed: No breaking changes detected"
+    
+    # Calculate risk score
+    risk_score = min(len(violations) * 10, 100)
+    
+    # Build remediation if needed
+    remediation = None
+    if violations:
+        remediation = Remediation(
+            summary="Breaking changes detected in API specification",
+            steps=[
+                "Option 1: Restore removed endpoints/methods to maintain compatibility",
+                "Option 2: Create a new API version (e.g., v2) for breaking changes",
+                "Option 3: Implement deprecation warnings before removal",
+                "Option 4: Document migration path for API consumers"
+            ],
+            examples=[
+                "Keep old endpoint with deprecation notice",
+                "Add version prefix: /v2/api/..."
+            ],
+            documentation="https://docs.delimit.ai/api-versioning"
+        )
+    
+    # Return evidence contract
+    return APIChangeEvidence(
+        task="validate-api",
+        task_version="1.0",
+        decision=decision,
+        exit_code=exit_code,
+        violations=violations,
+        evidence=evidence_list,
+        remediation=remediation,
+        summary=summary,
+        correlation_id=request.correlation_id,
+        metrics={
+            "endpoints_checked": len(old_paths | new_paths),
+            "breaking_changes": len(breaking_changes),
+            "non_breaking_changes": len(non_breaking_changes)
+        },
+        breaking_changes=breaking_changes,
+        non_breaking_changes=non_breaking_changes,
+        risk_score=risk_score
+    )
+
+
+def load_spec(file_path: str) -> Dict:
+    """Load API specification from file"""
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Spec file not found: {file_path}\n"
+            f"If the spec was deleted, ensure both old and new spec paths exist before running validation."
+        )
+    with path.open('r') as f:
+        if path.suffix in ['.yaml', '.yml']:
+            return yaml.safe_load(f)
+        elif path.suffix == '.json':
+            return json.load(f)
+        else:
+            # Try YAML first, then JSON
+            content = f.read()
+            try:
+                return yaml.safe_load(content)
+            except:
+                return json.loads(content)
+
+
+def extract_parameters(operation: Dict) -> List[Dict]:
+    """Extract parameters from an operation"""
+    params = operation.get("parameters", [])
+    # Also check requestBody for required fields
+    if "requestBody" in operation and operation["requestBody"].get("required", False):
+        params.append({
+            "name": "requestBody",
+            "required": True,
+            "in": "body"
+        })
+    return params

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
-  "version": "2.4.0",
-  "description": "Prevent breaking API changes before they reach production. Deterministic diff engine + policy enforcement + semver classification.",
+  "version": "3.0.0",
+  "description": "AI agent guardrails for developers. Install governance tools into Claude Code with one command.",
   "main": "index.js",
   "bin": {
     "delimit": "./bin/delimit-cli.js"

package/adapters/codex-skill.js

@@ -1,87 +0,0 @@
-#!/usr/bin/env node
-/**
- * Delimit™ Codex Skill Adapter
- * Implements GitHub Codex "Skills" interface
- */
-
-const axios = require('axios');
-const AGENT_URL = `http://127.0.0.1:${process.env.DELIMIT_AGENT_PORT || 7823}`;
-
-class DelimitCodexSkill {
-    constructor() {
-        this.name = 'delimit-governance';
-        this.version = '2.0.0';
-    }
-    
-    /**
-     * Codex Skills use onBeforeSuggestion and onAfterAccept events
-     */
-    async onBeforeSuggestion(context) {
-        console.log('[DELIMIT CODEX] Validating code suggestion...');
-        
-        try {
-            const { code, language, file } = context;
-            
-            // Check governance rules
-            const response = await axios.post(`${AGENT_URL}/evaluate`, {
-                action: 'codex_suggestion',
-                code: code,
-                language: language,
-                file: file,
-                tool: 'codex'
-            });
-            
-            if (response.data.action === 'block') {
-                return {
-                    allow: false,
-                    message: `[DELIMIT] Code blocked: ${response.data.reason}`
-                };
-            }
-            
-            if (response.data.action === 'prompt') {
-                return {
-                    allow: true,
-                    warning: response.data.message
-                };
-            }
-            
-            return { allow: true };
-        } catch (error) {
-            console.warn('[DELIMIT CODEX] Governance check failed:', error.message);
-            return { allow: true }; // Fail open
-        }
-    }
-    
-    async onAfterAccept(context) {
-        console.log('[DELIMIT CODEX] Recording accepted suggestion...');
-        
-        try {
-            // Collect evidence
-            await axios.post(`${AGENT_URL}/audit`, {
-                action: 'codex_accept',
-                context: context,
-                timestamp: new Date().toISOString()
-            });
-        } catch (error) {
-            // Silent fail for audit
-        }
-    }
-    
-    // Codex-specific command handler
-    async handleCommand(command, args) {
-        if (command === 'governance') {
-            const { execSync } = require('child_process');
-            return execSync('delimit status --verbose').toString();
-        }
-    }
-}
-
-// Export for Codex
-if (typeof module !== 'undefined' && module.exports) {
-    module.exports = new DelimitCodexSkill();
-}
-
-// Codex registration
-if (typeof registerSkill === 'function') {
-    registerSkill(new DelimitCodexSkill());
-}