""" 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") all_changes = result.get("all_changes", []) migration = result.get("migration") bc = summary.get("breaking_changes", 0) total = summary.get("total_changes", 0) additive = total - bc errors = [v for v in violations if v.get("severity") == "error"] warnings = [v for v in violations if v.get("severity") == "warning"] # โ”€โ”€ HEADERS WITH TEST COMPATIBILITY โ”€โ”€ if decision == "fail": lines.append("\U0001f6e1\ufe0f **Breaking API Changes Detected**\n") elif decision == "warn": lines.append("\U0001f6e1\ufe0f **Governance Passed โ€” Potential Issues**\n") else: lines.append("\U0001f6e1\ufe0f **Governance Passed โ€” API Changes Look Good**\n") if bc == 0: # โ”€โ”€ GREEN PATH โ”€โ”€ if semver and semver.get("bump") != "none": bump_label = f"`{semver.get('bump', 'none').upper()}`" next_label = "" if semver.get("next_version"): next_label = f" ยท Next: `{semver['next_version']}`" lines.append( f"> **No breaking API changes detected.** " f"{additive} additive change{'s' if additive != 1 else ''} " f"found \u2014 Semver: **{bump_label}**{next_label}\n" ) else: lines.append("> **No breaking API changes detected.**\n") # Violations table for warnings/policy issues if errors or warnings: lines.append("### Warnings & Issues\n") lines.append("| Severity | Change | Location |") lines.append("|----------|--------|----------|") for v in errors: rule = v.get("name", v.get("rule", "Unknown")) rule_prefix = f"**{rule}**: " if rule else "" desc = f"{rule_prefix}{v.get('message', 'Unknown violation')}" location = v.get("path", "-") lines.append(f"| ๐Ÿ”ด Error | {desc} | `{location}` |") for v in warnings: rule = v.get("name", v.get("rule", "Unknown")) rule_prefix = f"**{rule}**: " if rule else "" desc = f"{rule_prefix}{v.get('message', 'Unknown warning')}" location = v.get("path", "-") lines.append(f"| ๐ŸŸก Warning | {desc} | `{location}` |") lines.append("") # Additive changes (collapsed) safe_changes = [c for c in all_changes if not c.get("is_breaking")] if safe_changes and len(safe_changes) <= 15: lines.append("
") lines.append(f"\u2705 New additions ({len(safe_changes)})\n") for c in safe_changes: lines.append(f"- `{c.get('path', '')}` \u2014 {c.get('message', '')}") lines.append("
\n") else: # โ”€โ”€ RED PATH โ”€โ”€ # Summary card parts = [f"\U0001f534 **{bc} breaking change{'s' if bc != 1 else ''}**"] parts.append("Semver: **`MAJOR`**") if semver and semver.get("next_version"): parts.append(f"Next: `{semver['next_version']}`") separator = " \u00b7 " lines.append(f"> {separator.join(parts)}\n") # Stats table lines.append("| | Count |") lines.append("|---|---|") lines.append(f"| Total changes | {total} |") lines.append(f"| Breaking | {bc} |") lines.append(f"| Additive | {additive} |") if len(warnings) > 0: lines.append(f"| Warnings | {len(warnings)} |") if summary.get("violations", 0) > 0: lines.append(f"| Policy violations | {summary['violations']} |") lines.append("") # Violations table if errors or warnings: lines.append("### Breaking Changes\n") lines.append("| Severity | Change | Location |") lines.append("|----------|--------|----------|") for v in errors: rule = v.get("name", v.get("rule", "Unknown")) rule_prefix = f"**{rule}**: " if rule else "" desc = f"{rule_prefix}{v.get('message', 'Unknown violation')}" location = v.get("path", "-") lines.append(f"| ๐Ÿ”ด Error | {desc} | `{location}` |") for v in warnings: rule = v.get("name", v.get("rule", "Unknown")) rule_prefix = f"**{rule}**: " if rule else "" desc = f"{rule_prefix}{v.get('message', 'Unknown warning')}" location = v.get("path", "-") lines.append(f"| ๐ŸŸก Warning | {desc} | `{location}` |") lines.append("") # Migration guidance if migration and decision == "fail": lines.append("
") lines.append("\U0001f4cb Migration guide\n") lines.append(migration) lines.append("\n
\n") elif errors and decision == "fail": lines.append("
") lines.append("\U0001f4cb Migration guide\n") lines.append("1. **Restore removed endpoints** \u2014 deprecate before removing") lines.append("2. **Make parameters optional** \u2014 don't add required params") lines.append("3. **Use versioning** \u2014 create `/v2/` for breaking changes") lines.append("4. **Gradual migration** \u2014 provide guides and time") lines.append("\n
\n") # Remediation when migration is missing if decision == "fail" and not migration: lines.append("### ๐Ÿ’ก How to Fix\n") lines.append("1. **Restore removed endpoints** \u2014 deprecate before removing") lines.append("2. **Make parameters optional** \u2014 don't add required params") lines.append("3. **Use versioning** \u2014 create `/v2/` for breaking changes") lines.append("4. **Gradual migration** \u2014 provide guides and time\n") # Additive changes safe_changes = [c for c in all_changes if not c.get("is_breaking")] if safe_changes and len(safe_changes) <= 15: lines.append("
") lines.append(f"\u2705 New additions ({len(safe_changes)})\n") for c in safe_changes: lines.append(f"- `{c.get('path', '')}` \u2014 {c.get('message', '')}") lines.append("
\n") lines.append("> **Fix locally:** `npx delimit-cli lint`\n") # Detailed changes (test compat) if all_changes and len(all_changes) <= 10: lines.append("
") lines.append("All changes\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("
\n") lines.append("---") lines.append( "Generated by [Delimit](https://delimit.ai) \u00b7 " "[Docs](https://delimit.ai/docs) \u00b7 " "[Install](https://github.com/marketplace/actions/delimit-api-governance)" ) if bc == 0: lines.append("\nKeep Building.") 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)