delimit-cli 2.3.2 → 3.0.0

package/gateway/core/gateway.py

@@ -0,0 +1,128 @@
+import time
+import logging
+from typing import Any, Dict, List, Optional
+from schemas.base import TaskRequest, TaskResponse, ErrorResponse, TaskStatus, ErrorDetails
+from .registry import task_registry
+
+logger = logging.getLogger(__name__)
+
+class Gateway:
+    """Main gateway implementing V10 architecture with advisor recommendations"""
+    
+    def __init__(self, max_file_size: int = 10 * 1024 * 1024, timeout: int = 30):
+        self.registry = task_registry
+        self.max_file_size = max_file_size
+        self.timeout = timeout
+        self._load_tasks()
+    
+    def _load_tasks(self):
+        """Load all task modules to register handlers"""
+        try:
+            import tasks.validate_api
+            import tasks.check_policy
+            import tasks.explain_diff
+        except ImportError as e:
+            logger.warning(f"Could not load all tasks: {e}")
+    
+    def run(self, task: str, files: List[str], **kwargs) -> Dict[str, Any]:
+        """Main entry point - the single gateway function"""
+        start_time = time.time()
+        
+        # Build request with Codex's recommendation for strict typing
+        try:
+            request = TaskRequest(
+                task=task,
+                files=files,
+                config=kwargs,
+                correlation_id=kwargs.get("correlation_id"),
+                version=kwargs.get("version", "v1")
+            )
+        except Exception as e:
+            return self._error_response("invalid_request", str(e))
+        
+        # Check if task exists
+        if not self.registry.has_task(task):
+            return self._error_response(
+                "unknown_task",
+                f"Task '{task}' not recognized",
+                available_tasks=self.registry.list_tasks()
+            )
+        
+        # Get handler - use None for default version if v1 requested
+        version_to_use = None if request.version == "v1" else request.version
+        handler = self.registry.get_handler(task, version_to_use)
+        if not handler:
+            return self._error_response(
+                "version_not_found",
+                f"Version {request.version} not found for task '{task}'"
+            )
+        
+        # Execute with timeout and error handling per Codex's guardrails
+        try:
+            # Validate file constraints
+            for file_path in files:
+                if not self._validate_file(file_path):
+                    return self._error_response(
+                        "file_validation_failed",
+                        f"File validation failed for: {file_path}"
+                    )
+            
+            # Execute task
+            result = handler(request)
+            
+            # Build response with observability (Codex requirement #5)
+            duration_ms = int((time.time() - start_time) * 1000)
+            
+            response = TaskResponse(
+                status=TaskStatus.SUCCESS,
+                task=task,
+                result=result,
+                duration_ms=duration_ms,
+                correlation_id=request.correlation_id
+            )
+            
+            logger.info(f"Task {task} completed in {duration_ms}ms")
+            return response.model_dump(mode='json')
+            
+        except Exception as e:
+            duration_ms = int((time.time() - start_time) * 1000)
+            logger.error(f"Task {task} failed after {duration_ms}ms: {e}")
+            
+            return TaskResponse(
+                status=TaskStatus.ERROR,
+                task=task,
+                errors=[ErrorDetails(
+                    code="execution_failed",
+                    message=str(e),
+                    retryable=True
+                )],
+                duration_ms=duration_ms,
+                correlation_id=request.correlation_id
+            ).model_dump(mode='json')
+    
+    def _validate_file(self, file_path: str) -> bool:
+        """Validate file constraints"""
+        try:
+            import os
+            if not os.path.exists(file_path):
+                return False
+            file_size = os.path.getsize(file_path)
+            return file_size <= self.max_file_size
+        except:
+            return False
+    
+    def _error_response(self, code: str, message: str, **kwargs) -> Dict[str, Any]:
+        """Build standardized error response (Codex requirement #2)"""
+        return ErrorResponse(
+            code=code,
+            message=message,
+            details=kwargs.get("details"),
+            available_tasks=kwargs.get("available_tasks")
+        ).model_dump(mode='json')
+
+# Global gateway instance
+gateway = Gateway()
+
+def delimit_run(task: str, files: List[str], **kwargs) -> Dict[str, Any]:
+    """The main gateway function - V10 architecture entry point"""
+    return gateway.run(task, files, **kwargs)

package/gateway/core/gateway_v2.py

@@ -0,0 +1,154 @@
+"""
+Hardened Gateway with Evidence Contract
+V12 Core Hardening
+"""
+
+import time
+import logging
+from typing import Optional, Dict, Any
+from pathlib import Path
+
+from schemas.evidence import TaskEvidence, Decision
+from schemas.requests import ValidateAPIRequest, CheckPolicyRequest, ExplainDiffRequest
+from .registry_v2 import task_registry
+
+logger = logging.getLogger(__name__)
+
+
+class HardenedGateway:
+    """
+    V12 Hardened Gateway with strict evidence contract
+    """
+    
+    def __init__(self):
+        self.registry = task_registry
+        self._load_tasks()
+    
+    def _load_tasks(self):
+        """Load all task modules to register handlers"""
+        try:
+            # Import refactored tasks with evidence contract
+            import tasks.validate_api_v2
+            import tasks.check_policy_v2
+            import tasks.explain_diff_v2
+        except ImportError as e:
+            logger.warning(f"Could not load all tasks: {e}")
+    
+    def run_validate_api(self, request: ValidateAPIRequest) -> TaskEvidence:
+        """Execute validate-api task with typed request/response"""
+        handler = self.registry.get_handler("validate-api", request.version)
+        if not handler:
+            raise ValueError(f"Task handler not found: validate-api:{request.version or 'latest'}")
+        
+        return handler(request)
+    
+    def run_check_policy(self, request: CheckPolicyRequest) -> TaskEvidence:
+        """Execute check-policy task with typed request/response"""
+        handler = self.registry.get_handler("check-policy", request.version)
+        if not handler:
+            raise ValueError(f"Task handler not found: check-policy:{request.version or 'latest'}")
+        
+        return handler(request)
+    
+    def run_explain_diff(self, request: ExplainDiffRequest) -> TaskEvidence:
+        """Execute explain-diff task with typed request/response"""
+        handler = self.registry.get_handler("explain-diff", request.version)
+        if not handler:
+            raise ValueError(f"Task handler not found: explain-diff:{request.version or 'latest'}")
+        
+        return handler(request)
+    
+    def run(self, task: str, **kwargs) -> Dict[str, Any]:
+        """
+        Main gateway entry point - maintains backward compatibility
+        Returns Evidence Contract as dict
+        """
+        start_time = time.time()
+        
+        try:
+            # Route to typed handlers based on task
+            if task == "validate-api":
+                request = ValidateAPIRequest(
+                    task=task,
+                    old_spec=kwargs.get("old_spec") or kwargs.get("files", [])[0],
+                    new_spec=kwargs.get("new_spec") or kwargs.get("files", [])[1],
+                    version=kwargs.get("version"),
+                    correlation_id=kwargs.get("correlation_id")
+                )
+                evidence = self.run_validate_api(request)
+                
+            elif task == "check-policy":
+                request = CheckPolicyRequest(
+                    task=task,
+                    spec_files=kwargs.get("spec_files") or kwargs.get("files", []),
+                    policy_file=kwargs.get("policy_file"),
+                    policy_inline=kwargs.get("policy_inline"),
+                    version=kwargs.get("version"),
+                    correlation_id=kwargs.get("correlation_id")
+                )
+                evidence = self.run_check_policy(request)
+                
+            elif task == "explain-diff":
+                request = ExplainDiffRequest(
+                    task=task,
+                    old_spec=kwargs.get("old_spec") or kwargs.get("files", [])[0],
+                    new_spec=kwargs.get("new_spec") or kwargs.get("files", [])[1],
+                    detail_level=kwargs.get("detail_level", "medium"),
+                    version=kwargs.get("version"),
+                    correlation_id=kwargs.get("correlation_id")
+                )
+                evidence = self.run_explain_diff(request)
+                
+            else:
+                # Unknown task - return error evidence
+                return {
+                    "task": task,
+                    "task_version": "unknown",
+                    "decision": "fail",
+                    "exit_code": 1,
+                    "summary": f"Unknown task: {task}",
+                    "violations": [{
+                        "rule": "task_exists",
+                        "severity": "high",
+                        "message": f"Task '{task}' not found"
+                    }]
+                }
+            
+            # Add timing
+            duration_ms = int((time.time() - start_time) * 1000)
+            evidence_dict = evidence.model_dump(mode='json')
+            evidence_dict["duration_ms"] = duration_ms
+            
+            return evidence_dict
+            
+        except Exception as e:
+            logger.error(f"Task execution failed: {e}")
+            
+            # Return error evidence
+            return {
+                "task": task,
+                "task_version": "error",
+                "decision": "fail",
+                "exit_code": 1,
+                "summary": f"Execution failed: {str(e)}",
+                "violations": [{
+                    "rule": "execution",
+                    "severity": "high",
+                    "message": str(e)
+                }],
+                "duration_ms": int((time.time() - start_time) * 1000)
+            }
+
+
+# Global instance
+gateway = HardenedGateway()
+
+
+def delimit_run(task: str, files: list = None, **kwargs) -> Dict[str, Any]:
+    """
+    Main entry point maintaining backward compatibility
+    Returns Evidence Contract as dictionary
+    """
+    if files:
+        kwargs["files"] = files
+    return gateway.run(task, **kwargs)

package/gateway/core/gateway_v3.py

@@ -0,0 +1,224 @@
+"""
+Hardened Gateway with Evidence Contract - Final Version
+V12 Complete Implementation
+"""
+
+import time
+import logging
+from typing import Optional, Dict
+from pathlib import Path
+
+from schemas.evidence import TaskEvidence, Decision, Violation, ViolationSeverity, Remediation
+from schemas.requests_v2 import ValidateAPIRequest, CheckPolicyRequest, ExplainDiffRequest
+from .registry_v3 import task_registry
+
+logger = logging.getLogger(__name__)
+
+
+class HardenedGateway:
+    """
+    V12 Hardened Gateway with strict evidence contract
+    All paths return TaskEvidence
+    """
+    
+    def __init__(self):
+        self.registry = task_registry
+        self._load_tasks()
+    
+    def _load_tasks(self):
+        """Load all task modules to register handlers"""
+        try:
+            # Import refactored tasks with evidence contract
+            import tasks.validate_api_v3
+            import tasks.check_policy_v3
+            import tasks.explain_diff_v2
+        except ImportError as e:
+            logger.warning(f"Could not load all tasks: {e}")
+    
+    def run_validate_api(self, request: ValidateAPIRequest) -> TaskEvidence:
+        """Execute validate-api task with typed request/response"""
+        handler = self.registry.get_handler("validate-api", request.version)
+        if not handler:
+            # Return error evidence instead of raising
+            return self._create_error_evidence(
+                "validate-api",
+                f"Task handler not found: validate-api:{request.version or 'latest'}",
+                request.correlation_id
+            )
+        
+        try:
+            return handler(request)
+        except Exception as e:
+            return self._create_error_evidence("validate-api", str(e), request.correlation_id)
+    
+    def run_check_policy(self, request: CheckPolicyRequest) -> TaskEvidence:
+        """Execute check-policy task with typed request/response"""
+        handler = self.registry.get_handler("check-policy", request.version)
+        if not handler:
+            return self._create_error_evidence(
+                "check-policy",
+                f"Task handler not found: check-policy:{request.version or 'latest'}",
+                request.correlation_id
+            )
+        
+        try:
+            return handler(request)
+        except Exception as e:
+            return self._create_error_evidence("check-policy", str(e), request.correlation_id)
+    
+    def run_explain_diff(self, request: ExplainDiffRequest) -> TaskEvidence:
+        """Execute explain-diff task with typed request/response"""
+        handler = self.registry.get_handler("explain-diff", request.version)
+        if not handler:
+            return self._create_error_evidence(
+                "explain-diff",
+                f"Task handler not found: explain-diff:{request.version or 'latest'}",
+                request.correlation_id
+            )
+        
+        try:
+            return handler(request)
+        except Exception as e:
+            return self._create_error_evidence("explain-diff", str(e), request.correlation_id)
+    
+    def _create_error_evidence(self, task: str, error_message: str, correlation_id: Optional[str] = None) -> TaskEvidence:
+        """Create proper TaskEvidence for errors - never return raw dicts"""
+        return TaskEvidence(
+            task=task,
+            task_version="error",
+            decision=Decision.FAIL,
+            exit_code=1,
+            violations=[
+                Violation(
+                    rule="execution_error",
+                    severity=ViolationSeverity.HIGH,
+                    message=error_message,
+                    details={"error_type": "execution_failure"}
+                )
+            ],
+            evidence=[],
+            remediation=Remediation(
+                summary="Task execution failed",
+                steps=["Check input parameters", "Verify file paths exist", "Review error message"],
+                documentation="https://docs.delimit.ai/troubleshooting"
+            ),
+            summary=f"Task execution failed: {error_message}",
+            correlation_id=correlation_id,
+            metrics={}
+        )
+    
+    def run(self, task: str, **kwargs) -> Dict[str, str]:
+        """
+        Main gateway entry point - maintains backward compatibility
+        Returns Evidence Contract as dict
+        ALL PATHS RETURN TaskEvidence
+        """
+        start_time = time.time()
+        correlation_id = kwargs.get("correlation_id")
+        
+        try:
+            # Route to typed handlers based on task
+            if task == "validate-api":
+                # Handle both old and new parameter styles
+                files = kwargs.get("files", [])
+                old_spec = kwargs.get("old_spec") or (files[0] if len(files) > 0 else None)
+                new_spec = kwargs.get("new_spec") or (files[1] if len(files) > 1 else None)
+                
+                if not old_spec or not new_spec:
+                    evidence = self._create_error_evidence(
+                        task,
+                        "validate-api requires two files: old_spec and new_spec",
+                        correlation_id
+                    )
+                else:
+                    request = ValidateAPIRequest(
+                        task=task,
+                        old_spec=old_spec,
+                        new_spec=new_spec,
+                        version=kwargs.get("version"),
+                        correlation_id=correlation_id
+                    )
+                    evidence = self.run_validate_api(request)
+                
+            elif task == "check-policy":
+                files = kwargs.get("spec_files") or kwargs.get("files", [])
+                
+                if not files:
+                    evidence = self._create_error_evidence(
+                        task,
+                        "check-policy requires at least one spec file",
+                        correlation_id
+                    )
+                else:
+                    request = CheckPolicyRequest(
+                        task=task,
+                        spec_files=files,
+                        policy_file=kwargs.get("policy_file"),
+                        policy_inline=kwargs.get("policy_inline"),
+                        version=kwargs.get("version"),
+                        correlation_id=correlation_id
+                    )
+                    evidence = self.run_check_policy(request)
+                
+            elif task == "explain-diff":
+                files = kwargs.get("files", [])
+                old_spec = kwargs.get("old_spec") or (files[0] if len(files) > 0 else None)
+                new_spec = kwargs.get("new_spec") or (files[1] if len(files) > 1 else None)
+                
+                if not old_spec or not new_spec:
+                    evidence = self._create_error_evidence(
+                        task,
+                        "explain-diff requires two files: old_spec and new_spec",
+                        correlation_id
+                    )
+                else:
+                    request = ExplainDiffRequest(
+                        task=task,
+                        old_spec=old_spec,
+                        new_spec=new_spec,
+                        detail_level=kwargs.get("detail_level", "medium"),
+                        version=kwargs.get("version"),
+                        correlation_id=correlation_id
+                    )
+                    evidence = self.run_explain_diff(request)
+                
+            else:
+                # Unknown task - return error evidence
+                evidence = self._create_error_evidence(
+                    task,
+                    f"Unknown task: {task}. Available tasks: validate-api, check-policy, explain-diff",
+                    correlation_id
+                )
+            
+            # Add timing
+            duration_ms = int((time.time() - start_time) * 1000)
+            evidence_dict = evidence.model_dump(mode='json')
+            evidence_dict["duration_ms"] = duration_ms
+            
+            return evidence_dict
+            
+        except Exception as e:
+            logger.error(f"Task execution failed: {e}")
+            
+            # Always return TaskEvidence, never raw dict
+            error_evidence = self._create_error_evidence(task, str(e), correlation_id)
+            duration_ms = int((time.time() - start_time) * 1000)
+            evidence_dict = error_evidence.model_dump(mode='json')
+            evidence_dict["duration_ms"] = duration_ms
+            
+            return evidence_dict
+
+
+# Global instance
+gateway = HardenedGateway()
+
+
+def delimit_run(task: str, files: list = None, **kwargs) -> Dict[str, str]:
+    """
+    Main entry point maintaining backward compatibility
+    Returns Evidence Contract as dictionary
+    ALL PATHS RETURN VALID TaskEvidence
+    """
+    if files:
+        kwargs["files"] = files
+    return gateway.run(task, **kwargs)

package/gateway/core/impact_analyzer.py

@@ -0,0 +1,163 @@
+"""
+Delimit Impact Analyzer
+Determines downstream consumers affected by an API change
+and produces informational impact summaries for CI output.
+
+Per Jamsons Doctrine:
+- Impact analysis is INFORMATIONAL ONLY
+- NEVER affects CI pass/fail outcome
+- Deterministic outputs
+- Graceful degradation when no dependency data exists
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .dependency_graph import DependencyGraph
+
+logger = logging.getLogger("delimit.impact_analyzer")
+
+
+class ImpactAnalyzer:
+    """Analyze the downstream impact of API changes."""
+
+    def __init__(self, graph: DependencyGraph):
+        """Initialize with a dependency graph.
+
+        Args:
+            graph: Populated DependencyGraph instance.
+        """
+        self._graph = graph
+
+    def analyze(self, api_name: str) -> Dict[str, Any]:
+        """Analyze the impact of a change to an API.
+
+        Args:
+            api_name: The API that changed.
+
+        Returns:
+            Deterministic impact summary dictionary.
+        """
+        downstream = self._graph.get_consumers(api_name)
+
+        return {
+            "api": api_name,
+            "downstream_services": downstream,
+            "impact_count": len(downstream),
+            "graph_available": not self._graph.is_empty(),
+        }
+
+    def analyze_multiple(self, api_names: List[str]) -> List[Dict[str, Any]]:
+        """Analyze impact for multiple APIs.
+
+        Args:
+            api_names: List of API names that changed.
+
+        Returns:
+            Sorted list of impact summaries.
+        """
+        results = [self.analyze(api) for api in api_names]
+        results.sort(key=lambda r: r["api"])
+        return results
+
+    def get_blast_radius(self, api_name: str) -> int:
+        """Get the number of downstream services affected.
+
+        Args:
+            api_name: The API that changed.
+
+        Returns:
+            Number of affected downstream services.
+        """
+        return len(self._graph.get_consumers(api_name))
+
+    def format_ci_output(self, api_name: str) -> str:
+        """Format impact analysis for CI log output.
+
+        This output is informational only and NEVER affects CI outcome.
+
+        Args:
+            api_name: The API that changed.
+
+        Returns:
+            Formatted string for CI logs.
+        """
+        impact = self.analyze(api_name)
+        lines = []
+
+        lines.append("")
+        lines.append("--------------------------------------")
+        lines.append("DELIMIT IMPACT ANALYSIS")
+        lines.append("--------------------------------------")
+        lines.append("")
+        lines.append(f"API changed: {api_name}")
+        lines.append("")
+
+        if not impact["graph_available"]:
+            lines.append("No dependency manifests found.")
+            lines.append("Add .delimit/dependencies.yaml to enable impact analysis.")
+        elif impact["impact_count"] == 0:
+            lines.append("No known downstream consumers.")
+        else:
+            lines.append("Potential downstream consumers:")
+            lines.append("")
+            for service in impact["downstream_services"]:
+                lines.append(f"  * {service}")
+            lines.append("")
+            lines.append(f"Blast radius: {impact['impact_count']} service(s)")
+
+        lines.append("")
+        lines.append("--------------------------------------")
+        lines.append("")
+
+        return "\n".join(lines)
+
+
+def analyze_impact(
+    graph: DependencyGraph,
+    api_name: str,
+) -> Dict[str, Any]:
+    """Convenience function for CI pipeline integration.
+
+    Called after event_backbone in the pipeline:
+        diff_engine → policy_engine → complexity_analyzer
+        → event_backbone → dependency_graph → impact_analyzer
+
+    CRITICAL: This function NEVER raises exceptions.
+    Impact analysis is informational only.
+
+    Args:
+        graph: Dependency graph (may be empty).
+        api_name: The API that changed.
+
+    Returns:
+        Impact summary dictionary.
+    """
+    try:
+        analyzer = ImpactAnalyzer(graph)
+        return analyzer.analyze(api_name)
+    except Exception as e:
+        logger.warning("Impact analysis failed: %s — continuing", e)
+        return {
+            "api": api_name,
+            "downstream_services": [],
+            "impact_count": 0,
+            "graph_available": False,
+            "error": str(e),
+        }
+
+
+def format_impact_for_ci(
+    graph: DependencyGraph,
+    api_name: str,
+) -> str:
+    """Convenience function to format impact analysis for CI output.
+
+    NEVER raises. Returns empty string on failure.
+    """
+    try:
+        analyzer = ImpactAnalyzer(graph)
+        return analyzer.format_ci_output(api_name)
+    except Exception as e:
+        logger.warning("Impact formatting failed: %s", e)
+        return ""

package/gateway/core/policies/default.yml

@@ -0,0 +1,13 @@
+# Delimit Policy Preset: default
+# Balanced rules for most teams. Blocks destructive changes, warns on risky ones.
+# Good starting point — tighten as your API matures.
+
+override_defaults: false
+
+# Uses built-in defaults:
+#   ERROR: endpoint_removed, method_removed, required_param_added, field_removed (2xx)
+#   WARN:  type_changed
+#   ALLOW: enum_value_added
+#
+# No custom rules needed — the built-in defaults are the "default" preset.
+rules: []