delimit-cli 2.3.2 → 3.0.0

package/gateway/core/__init__.py

@@ -0,0 +1,3 @@
+from .registry import TaskRegistry, task_registry
+
+__all__ = ["TaskRegistry", "task_registry"]

package/gateway/core/auto_baseline.py

@@ -0,0 +1,304 @@
+"""
+Auto-Baseline Mode for Gradual Adoption
+Enables teams to start governance without failing on existing issues
+"""
+
+import json
+import hashlib
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, Any, Optional, List
+
+from schemas.evidence import TaskEvidence, Decision, Violation
+
+
+class AutoBaseline:
+    """
+    Manages automatic baseline generation and comparison.
+    Allows gradual adoption by only flagging NEW violations.
+    """
+    
+    def __init__(self, baseline_dir: Optional[Path] = None):
+        """
+        Initialize auto-baseline manager.
+        
+        Args:
+            baseline_dir: Directory to store baselines (default: ~/.delimit/baselines)
+        """
+        self.baseline_dir = baseline_dir or (Path.home() / ".delimit" / "baselines")
+        self.baseline_dir.mkdir(parents=True, exist_ok=True)
+    
+    def get_baseline_path(self, file_path: str, task: str) -> Path:
+        """
+        Get the baseline file path for a given source file.
+        
+        Args:
+            file_path: Path to the source file
+            task: Task name (validate-api, check-policy, etc)
+            
+        Returns:
+            Path to baseline file
+        """
+        file_hash = hashlib.md5(file_path.encode()).hexdigest()[:8]
+        file_name = Path(file_path).stem
+        baseline_name = f"{file_name}_{task}_{file_hash}.baseline.json"
+        return self.baseline_dir / baseline_name
+    
+    def load_baseline(self, file_path: str, task: str) -> Optional[Dict[str, Any]]:
+        """
+        Load existing baseline if it exists.
+        
+        Args:
+            file_path: Path to the source file
+            task: Task name
+            
+        Returns:
+            Baseline data or None if not found
+        """
+        baseline_path = self.get_baseline_path(file_path, task)
+        
+        if baseline_path.exists():
+            with baseline_path.open('r') as f:
+                return json.load(f)
+        
+        return None
+    
+    def save_baseline(self, file_path: str, task: str, evidence: TaskEvidence) -> Path:
+        """
+        Save current results as baseline.
+        
+        Args:
+            file_path: Path to the source file
+            task: Task name
+            evidence: Task evidence to baseline
+            
+        Returns:
+            Path to saved baseline
+        """
+        baseline_path = self.get_baseline_path(file_path, task)
+        
+        baseline_data = {
+            "timestamp": datetime.now().isoformat(),
+            "file": file_path,
+            "task": task,
+            "violations": [v.model_dump(mode='json') for v in evidence.violations],
+            "metrics": evidence.metrics,
+            "checksum": self._calculate_file_checksum(file_path)
+        }
+        
+        with baseline_path.open('w') as f:
+            json.dump(baseline_data, f, indent=2)
+        
+        return baseline_path
+    
+    def filter_new_violations(self, 
+                            current_evidence: TaskEvidence,
+                            baseline_data: Dict[str, Any]) -> TaskEvidence:
+        """
+        Filter violations to only show NEW issues not in baseline.
+        
+        Args:
+            current_evidence: Current task evidence
+            baseline_data: Baseline data to compare against
+            
+        Returns:
+            Modified evidence with only new violations
+        """
+        baseline_violations = baseline_data.get("violations", [])
+        
+        # Create set of baseline violation signatures
+        baseline_sigs = set()
+        for v in baseline_violations:
+            sig = f"{v.get('rule')}:{v.get('path', '')}:{v.get('message', '')}"
+            baseline_sigs.add(sig)
+        
+        # Filter to only new violations
+        new_violations = []
+        baselined_count = 0
+        
+        for violation in current_evidence.violations:
+            sig = f"{violation.rule}:{violation.path or ''}:{violation.message}"
+            if sig not in baseline_sigs:
+                new_violations.append(violation)
+            else:
+                baselined_count += 1
+        
+        # Update evidence
+        current_evidence.violations = new_violations
+        
+        # Adjust decision based on new violations only
+        if len(new_violations) == 0:
+            current_evidence.decision = Decision.PASS
+            current_evidence.exit_code = 0
+            current_evidence.summary = f"No new violations found ({baselined_count} baselined)"
+        else:
+            # Keep original decision for new violations
+            current_evidence.summary = f"{current_evidence.summary} ({baselined_count} baselined)"
+        
+        # Add baseline info to metrics
+        current_evidence.metrics["baselined_violations"] = baselined_count
+        current_evidence.metrics["new_violations"] = len(new_violations)
+        current_evidence.metrics["baseline_applied"] = True
+        
+        return current_evidence
+    
+    def apply_auto_baseline(self,
+                           file_path: str,
+                           task: str,
+                           evidence: TaskEvidence,
+                           create_if_missing: bool = True) -> TaskEvidence:
+        """
+        Apply auto-baseline logic to task evidence.
+        
+        Args:
+            file_path: Path to the source file
+            task: Task name
+            evidence: Task evidence to process
+            create_if_missing: Create baseline if it doesn't exist
+            
+        Returns:
+            Modified evidence with baseline applied
+        """
+        baseline = self.load_baseline(file_path, task)
+        
+        if baseline is None:
+            if create_if_missing and evidence.violations:
+                # First run - create baseline
+                baseline_path = self.save_baseline(file_path, task, evidence)
+                
+                # On first baseline, pass with warning
+                evidence.decision = Decision.WARN
+                evidence.exit_code = 0
+                evidence.summary = f"Baseline created with {len(evidence.violations)} violations"
+                evidence.metrics["baseline_created"] = True
+                evidence.metrics["baseline_path"] = str(baseline_path)
+            else:
+                # No baseline and no violations - pass normally
+                evidence.metrics["baseline_applied"] = False
+        else:
+            # Apply baseline filtering
+            evidence = self.filter_new_violations(evidence, baseline)
+        
+        return evidence
+    
+    def _calculate_file_checksum(self, file_path: str) -> str:
+        """Calculate checksum of file for change detection."""
+        try:
+            with open(file_path, 'rb') as f:
+                return hashlib.sha256(f.read()).hexdigest()
+        except:
+            return ""
+    
+    def update_baseline(self,
+                       file_path: str,
+                       task: str,
+                       evidence: TaskEvidence,
+                       threshold: float = 0.8) -> bool:
+        """
+        Update baseline if improvement threshold is met.
+        
+        Args:
+            file_path: Path to the source file
+            task: Task name
+            evidence: Current task evidence
+            threshold: Improvement threshold (0.8 = 20% reduction required)
+            
+        Returns:
+            True if baseline was updated
+        """
+        baseline = self.load_baseline(file_path, task)
+        
+        if baseline is None:
+            # No existing baseline
+            self.save_baseline(file_path, task, evidence)
+            return True
+        
+        # Check if violations have improved enough
+        baseline_count = len(baseline.get("violations", []))
+        current_count = len(evidence.violations)
+        
+        if current_count <= baseline_count * threshold:
+            # Significant improvement - update baseline
+            self.save_baseline(file_path, task, evidence)
+            return True
+        
+        return False
+    
+    def get_baseline_status(self) -> Dict[str, Any]:
+        """
+        Get status of all baselines.
+        
+        Returns:
+            Status information about baselines
+        """
+        baselines = list(self.baseline_dir.glob("*.baseline.json"))
+        
+        status = {
+            "baseline_dir": str(self.baseline_dir),
+            "total_baselines": len(baselines),
+            "baselines": []
+        }
+        
+        for baseline_file in baselines:
+            with baseline_file.open('r') as f:
+                data = json.load(f)
+                status["baselines"].append({
+                    "file": data.get("file"),
+                    "task": data.get("task"),
+                    "timestamp": data.get("timestamp"),
+                    "violations_count": len(data.get("violations", [])),
+                    "path": str(baseline_file)
+                })
+        
+        return status
+    
+    def clear_baseline(self, file_path: Optional[str] = None, task: Optional[str] = None) -> int:
+        """
+        Clear baselines.
+        
+        Args:
+            file_path: Specific file to clear baseline for (optional)
+            task: Specific task to clear baseline for (optional)
+            
+        Returns:
+            Number of baselines cleared
+        """
+        count = 0
+        
+        if file_path and task:
+            # Clear specific baseline
+            baseline_path = self.get_baseline_path(file_path, task)
+            if baseline_path.exists():
+                baseline_path.unlink()
+                count = 1
+        else:
+            # Clear all baselines
+            for baseline_file in self.baseline_dir.glob("*.baseline.json"):
+                baseline_file.unlink()
+                count += 1
+        
+        return count
+
+
+# Convenience functions
+def apply_auto_baseline(evidence: TaskEvidence,
+                       file_path: str,
+                       task: str,
+                       enabled: bool = False) -> TaskEvidence:
+    """
+    Apply auto-baseline to evidence if enabled.
+    
+    Args:
+        evidence: Task evidence
+        file_path: Source file path
+        task: Task name
+        enabled: Whether auto-baseline is enabled
+        
+    Returns:
+        Potentially modified evidence
+    """
+    if not enabled:
+        return evidence
+    
+    baseline_manager = AutoBaseline()
+    return baseline_manager.apply_auto_baseline(file_path, task, evidence)

package/gateway/core/ci_formatter.py

@@ -0,0 +1,283 @@
+"""
+CI Output Formatter - Creates clear, actionable output for developers.
+Supports GitHub Actions annotations and PR comments.
+"""
+
+from typing import Dict, List, Any, Optional
+from enum import Enum
+import json
+
+class OutputFormat(Enum):
+    TEXT = "text"
+    MARKDOWN = "markdown"
+    GITHUB_ANNOTATION = "github_annotation"
+    JSON = "json"
+
+class CIFormatter:
+    """Format Delimit output for different CI environments."""
+    
+    def __init__(self, format_type: OutputFormat = OutputFormat.TEXT):
+        self.format_type = format_type
+    
+    def format_result(self, result: Dict[str, Any]) -> str:
+        """Format the complete result based on output type."""
+        if self.format_type == OutputFormat.JSON:
+            return json.dumps(result, indent=2)
+        elif self.format_type == OutputFormat.MARKDOWN:
+            return self._format_markdown(result)
+        elif self.format_type == OutputFormat.GITHUB_ANNOTATION:
+            return self._format_github_annotations(result)
+        else:
+            return self._format_text(result)
+    
+    def _format_text(self, result: Dict[str, Any]) -> str:
+        """Format as plain text for terminal output."""
+        lines = []
+        
+        decision = result.get("decision", "unknown")
+        violations = result.get("violations", [])
+        summary = result.get("summary", {})
+        
+        # Header
+        if decision == "fail":
+            lines.append("❌ API Governance Check Failed")
+        elif decision == "warn":
+            lines.append("⚠️  API Governance Check Passed with Warnings")
+        else:
+            lines.append("✅ API Governance Check Passed")
+        
+        lines.append("=" * 50)
+        
+        # Summary
+        if summary:
+            lines.append(f"Total Changes: {summary.get('total_changes', 0)}")
+            lines.append(f"Breaking Changes: {summary.get('breaking_changes', 0)}")
+            lines.append(f"Policy Violations: {summary.get('violations', 0)}")
+            lines.append("")
+        
+        # Violations
+        if violations:
+            lines.append("Violations Found:")
+            lines.append("-" * 40)
+            
+            # Group by severity
+            errors = [v for v in violations if v.get("severity") == "error"]
+            warnings = [v for v in violations if v.get("severity") == "warning"]
+            
+            if errors:
+                lines.append("\n🔴 ERRORS (Must Fix):")
+                for v in errors:
+                    lines.append(f"  • {v.get('message', 'Unknown violation')}")
+                    if v.get("path"):
+                        lines.append(f"    Location: {v['path']}")
+            
+            if warnings:
+                lines.append("\n🟡 WARNINGS:")
+                for v in warnings:
+                    lines.append(f"  • {v.get('message', 'Unknown warning')}")
+                    if v.get("path"):
+                        lines.append(f"    Location: {v['path']}")
+        
+        # Remediation
+        if violations and decision == "fail":
+            lines.append("\n" + "=" * 50)
+            lines.append("Suggested Fixes:")
+            lines.append("1. Restore removed endpoints/fields")
+            lines.append("2. Make new parameters optional")
+            lines.append("3. Use API versioning (e.g., /v2/)")
+            lines.append("4. Add deprecation notices before removing")
+        
+        return "\n".join(lines)
+    
+    def _format_markdown(self, result: Dict[str, Any]) -> str:
+        """Format as Markdown for PR comments.
+
+        Includes semver classification badge and migration guidance when
+        the result carries semver/explainer data.
+        """
+        lines = []
+
+        decision = result.get("decision", "unknown")
+        violations = result.get("violations", [])
+        summary = result.get("summary", {})
+        semver = result.get("semver")  # optional dict from semver_classifier
+
+        # Header — include semver badge when available
+        bump_badge = ""
+        if semver:
+            bump = semver.get("bump", "unknown")
+            bump_badge = {"major": " `MAJOR`", "minor": " `MINOR`", "patch": " `PATCH`", "none": ""}.get(bump, "")
+
+        if decision == "fail":
+            lines.append(f"## 🚨 Delimit: Breaking Changes{bump_badge}\n")
+        elif decision == "warn":
+            lines.append(f"## ⚠️ Delimit: Potential Issues{bump_badge}\n")
+        else:
+            lines.append(f"## ✅ API Changes Look Good{bump_badge}\n")
+
+        # Semver + summary table
+        lines.append("| Metric | Value |")
+        lines.append("|--------|-------|")
+        if semver:
+            lines.append(f"| Semver bump | `{semver.get('bump', 'unknown')}` |")
+            if semver.get("next_version"):
+                lines.append(f"| Next version | `{semver['next_version']}` |")
+        lines.append(f"| Total changes | {summary.get('total_changes', 0)} |")
+        lines.append(f"| Breaking | {summary.get('breaking_changes', 0)} |")
+        if summary.get("violations", 0) > 0:
+            lines.append(f"| Policy violations | {summary['violations']} |")
+        lines.append("")
+
+        # Violations table
+        if violations:
+            errors = [v for v in violations if v.get("severity") == "error"]
+            warnings = [v for v in violations if v.get("severity") == "warning"]
+
+            if errors or warnings:
+                lines.append("### Violations\n")
+                lines.append("| Severity | Rule | Description | Location |")
+                lines.append("|----------|------|-------------|----------|")
+
+                for v in errors:
+                    rule = v.get("name", v.get("rule", "Unknown"))
+                    desc = v.get("message", "Unknown violation")
+                    location = v.get("path", "-")
+                    lines.append(f"| 🔴 **Error** | {rule} | {desc} | `{location}` |")
+
+                for v in warnings:
+                    rule = v.get("name", v.get("rule", "Unknown"))
+                    desc = v.get("message", "Unknown warning")
+                    location = v.get("path", "-")
+                    lines.append(f"| 🟡 Warning | {rule} | {desc} | `{location}` |")
+
+                lines.append("")
+
+        # Detailed changes
+        all_changes = result.get("all_changes", [])
+        if all_changes and len(all_changes) <= 10:
+            lines.append("<details>")
+            lines.append("<summary>All changes</summary>\n")
+            lines.append("```")
+            for change in all_changes:
+                breaking = "BREAKING" if change.get("is_breaking") else "safe"
+                lines.append(f"[{breaking}] {change.get('message', 'Unknown change')}")
+            lines.append("```")
+            lines.append("</details>\n")
+
+        # Migration guidance (from explainer) when available
+        migration = result.get("migration")
+        if migration and decision == "fail":
+            lines.append("<details>")
+            lines.append("<summary>Migration guide</summary>\n")
+            lines.append(migration)
+            lines.append("\n</details>\n")
+
+        # Remediation
+        if violations and decision == "fail" and not migration:
+            lines.append("### 💡 How to Fix\n")
+            lines.append("1. **Restore removed endpoints** — deprecate before removing")
+            lines.append("2. **Make parameters optional** — don't add required params")
+            lines.append("3. **Use versioning** — create `/v2/` for breaking changes")
+            lines.append("4. **Gradual migration** — provide guides and time")
+            lines.append("")
+
+        lines.append("---")
+        lines.append("*Generated by [Delimit](https://github.com/delimit-ai/delimit) — ESLint for API contracts*")
+
+        return "\n".join(lines)
+    
+    def _format_github_annotations(self, result: Dict[str, Any]) -> str:
+        """Format as GitHub Actions annotations."""
+        annotations = []
+        
+        violations = result.get("violations", [])
+        
+        for v in violations:
+            severity = v.get("severity", "warning")
+            message = v.get("message", "Unknown violation")
+            path = v.get("path", "")
+            
+            # GitHub annotation format
+            if severity == "error":
+                level = "error"
+            elif severity == "warning":
+                level = "warning"
+            else:
+                level = "notice"
+            
+            # Extract file and line if possible
+            file = "openapi.yaml"  # Default, would need to map from path
+            
+            # GitHub annotation syntax
+            annotation = f"::{level} file={file},title=API Governance::{message}"
+            annotations.append(annotation)
+        
+        # Also output summary
+        decision = result.get("decision", "unknown")
+        summary = result.get("summary", {})
+        
+        if decision == "fail":
+            annotations.append(f"::error::Delimit found {summary.get('violations', 0)} policy violations")
+        elif decision == "warn":
+            annotations.append(f"::warning::Delimit found {summary.get('violations', 0)} warnings")
+        
+        return "\n".join(annotations)
+
+
+class PRCommentGenerator:
+    """Generate PR comments for GitHub."""
+    
+    @staticmethod
+    def generate_comment(result: Dict[str, Any], pr_number: Optional[int] = None) -> str:
+        """Generate a complete PR comment."""
+        formatter = CIFormatter(OutputFormat.MARKDOWN)
+        content = formatter.format_result(result)
+        
+        # Add PR-specific header if PR number provided
+        if pr_number:
+            header = f"### Delimit Report for PR #{pr_number}\n\n"
+            content = header + content
+        
+        return content
+    
+    @staticmethod
+    def generate_inline_comment(violation: Dict[str, Any]) -> str:
+        """Generate inline comment for specific line."""
+        severity = violation.get("severity", "warning")
+        message = violation.get("message", "Unknown issue")
+        
+        icon = "🔴" if severity == "error" else "⚠️"
+        
+        return f"{icon} **Delimit**: {message}"
+
+
+def format_for_ci(result: Dict[str, Any], ci_environment: str = "github") -> str:
+    """
+    Main entry point for CI formatting.
+    
+    Args:
+        result: The Delimit check result
+        ci_environment: The CI platform (github, gitlab, jenkins, etc.)
+    
+    Returns:
+        Formatted output string
+    """
+    if ci_environment == "github":
+        # Use GitHub annotations for inline warnings
+        formatter = CIFormatter(OutputFormat.GITHUB_ANNOTATION)
+        annotations = formatter.format_result(result)
+        
+        # Also output readable summary
+        formatter = CIFormatter(OutputFormat.TEXT)
+        summary = formatter.format_result(result)
+        
+        return annotations + "\n\n" + summary
+    
+    elif ci_environment == "pr_comment":
+        # Generate markdown for PR comment
+        return PRCommentGenerator.generate_comment(result)
+    
+    else:
+        # Default text output
+        formatter = CIFormatter(OutputFormat.TEXT)
+        return formatter.format_result(result)