codedna-analyzer 1.4.0__py3-none-any.whl

codedna/ci/gatekeeper.py

@@ -0,0 +1,421 @@
+"""CodeDNA Gatekeeper — validates architectural policies & enforces quality gates."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+
+from codedna import __version__
+
+
+@dataclass
+class PolicyEvaluation:
+    """Evaluation result for a single architectural or quality policy."""
+
+    rule_id: str
+    name: str
+    passed: bool
+    severity: str  # "error" | "warning"
+    message: str
+
+
+@dataclass
+class GatekeeperResult:
+    """Complete evaluation outcome for CI pipeline execution."""
+
+    passed: bool
+    overall_health: str
+    policies_evaluated: int
+    policies_passed: int
+    policies_failed: int
+    evaluations: list[PolicyEvaluation] = field(default_factory=list)
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    def to_dict(self) -> dict:
+        """Convert result to dictionary representation."""
+        return asdict(self)
+
+
+class Gatekeeper:
+    """Enforces architecture, security, and code quality gates for continuous delivery."""
+
+    HEALTH_HIERARCHY = {
+        "Healthy": 4,
+        "Fair": 3,
+        "Needs Attention": 2,
+        "Critical": 1,
+        "Unknown": 0,
+    }
+
+    def __init__(
+        self,
+        min_health: str = "Fair",
+        max_smells: int | None = None,
+        max_critical_smells: int = 0,
+        fail_on_secrets: bool = True,
+        fail_on_circular: bool = False,
+        max_density: float | None = None,
+        max_cyclomatic_complexity: int | None = None,
+        min_maintainability_index: float | None = None,
+    ):
+        """Initialize the Gatekeeper with policy thresholds."""
+        self.min_health = min_health
+        self.max_smells = max_smells
+        self.max_critical_smells = max_critical_smells
+        self.fail_on_secrets = fail_on_secrets
+        self.fail_on_circular = fail_on_circular
+        self.max_density = max_density
+        self.max_cyclomatic_complexity = max_cyclomatic_complexity
+        self.min_maintainability_index = min_maintainability_index
+
+    def evaluate(self, profile: dict) -> GatekeeperResult:
+        """Evaluate a DNA profile against the configured policies.
+
+        Args:
+            profile: Complete DNA profile generated by DNAGenerator.
+
+        Returns:
+            GatekeeperResult with detailed policy evaluations and pass/fail status.
+        """
+        evaluations: list[PolicyEvaluation] = []
+
+        health_data = profile.get("health", {})
+        current_health = health_data.get("overall", "Unknown")
+        severity_counts = health_data.get("severity_counts", {})
+        crit_smells = severity_counts.get("critical", 0)
+        warn_smells = severity_counts.get("warning", 0)
+        total_smells = crit_smells + warn_smells + severity_counts.get("info", 0)
+
+        deps_data = profile.get("dependencies", {})
+        has_circular = deps_data.get("has_circular_deps", False)
+        density = deps_data.get("density", 0.0)
+
+        security_data = profile.get("security", {})
+        has_secrets = security_data.get("has_secrets", False)
+        total_critical_vulns = security_data.get("total_critical", 0)
+
+        # 1. Minimum Health Policy
+        target_rank = self.HEALTH_HIERARCHY.get(self.min_health, 3)
+        actual_rank = self.HEALTH_HIERARCHY.get(current_health, 0)
+        health_pass = actual_rank >= target_rank
+        evaluations.append(
+            PolicyEvaluation(
+                rule_id="DNA-HLT-001",
+                name="Minimum Codebase Health",
+                passed=health_pass,
+                severity="error",
+                message=(
+                    f"Overall health '{current_health}' meets or exceeds requirement '{self.min_health}'"
+                    if health_pass
+                    else f"Overall health '{current_health}' falls below required '{self.min_health}'"
+                ),
+            )
+        )
+
+        # 2. Hardcoded Secrets Policy
+        if self.fail_on_secrets:
+            secrets_pass = not has_secrets and total_critical_vulns == 0
+            vuln_count = len(security_data.get("vulnerabilities", []))
+            evaluations.append(
+                PolicyEvaluation(
+                    rule_id="DNA-SEC-001",
+                    name="Zero Hardcoded Secrets & Critical CVEs",
+                    passed=secrets_pass,
+                    severity="error",
+                    message=(
+                        "No credentials or critical security vulnerabilities detected"
+                        if secrets_pass
+                        else f"Security scan found {vuln_count} vulnerability findings"
+                    ),
+                )
+            )
+
+        # 3. Critical Code Smells Policy
+        crit_pass = crit_smells <= self.max_critical_smells
+        evaluations.append(
+            PolicyEvaluation(
+                rule_id="DNA-SML-001",
+                name="Critical Smells Ceiling",
+                passed=crit_pass,
+                severity="error",
+                message=(
+                    f"Critical smells ({crit_smells}) within allowable limit ({self.max_critical_smells})"
+                    if crit_pass
+                    else f"Critical smells ({crit_smells}) exceeded allowable limit ({self.max_critical_smells})"
+                ),
+            )
+        )
+
+        # 4. Total Code Smells Ceiling (Optional)
+        if self.max_smells is not None:
+            smells_pass = total_smells <= self.max_smells
+            evaluations.append(
+                PolicyEvaluation(
+                    rule_id="DNA-SML-002",
+                    name="Total Smells Threshold",
+                    passed=smells_pass,
+                    severity="warning" if self.max_smells > 20 else "error",
+                    message=(
+                        f"Total smells ({total_smells}) within limit ({self.max_smells})"
+                        if smells_pass
+                        else f"Total smells ({total_smells}) exceeded threshold ({self.max_smells})"
+                    ),
+                )
+            )
+
+        # 5. Circular Dependency Policy
+        if self.fail_on_circular:
+            circ_pass = not has_circular
+            evaluations.append(
+                PolicyEvaluation(
+                    rule_id="DNA-DEP-001",
+                    name="No Circular Dependencies",
+                    passed=circ_pass,
+                    severity="error",
+                    message=(
+                        "Architecture dependency graph is acyclic"
+                        if circ_pass
+                        else f"Detected {deps_data.get('circular_count', 0)} circular dependency cycles"
+                    ),
+                )
+            )
+
+        # 6. Graph Density Policy
+        if self.max_density is not None:
+            density_pass = density <= self.max_density
+            evaluations.append(
+                PolicyEvaluation(
+                    rule_id="DNA-DEP-002",
+                    name="Coupling Density Limit",
+                    passed=density_pass,
+                    severity="warning",
+                    message=(
+                        f"Dependency density {density:.4f} within limit {self.max_density:.4f}"
+                        if density_pass
+                        else f"Dependency density {density:.4f} exceeds limit {self.max_density:.4f}"
+                    ),
+                )
+            )
+
+        # 7. Complexity Ceiling Policy
+        complexity_info = profile.get("smells", {}).get("complexity", {}) or profile.get("complexity", {})
+        if self.max_cyclomatic_complexity is not None and complexity_info:
+            max_cc = complexity_info.get("max_cyclomatic_complexity", 1)
+            cc_pass = max_cc <= self.max_cyclomatic_complexity
+            evaluations.append(
+                PolicyEvaluation(
+                    rule_id="DNA-CMP-001",
+                    name="Cyclomatic Complexity Ceiling",
+                    passed=cc_pass,
+                    severity="error" if self.max_cyclomatic_complexity < 20 else "warning",
+                    message=(
+                        f"Peak cyclomatic complexity ({max_cc}) within limit ({self.max_cyclomatic_complexity})"
+                        if cc_pass
+                        else f"Peak cyclomatic complexity ({max_cc}) exceeds limit ({self.max_cyclomatic_complexity})"
+                    ),
+                )
+            )
+
+        # 8. Maintainability Index Floor Policy
+        if self.min_maintainability_index is not None and complexity_info:
+            current_mi = complexity_info.get("maintainability_index", 100.0)
+            mi_pass = current_mi >= self.min_maintainability_index
+            evaluations.append(
+                PolicyEvaluation(
+                    rule_id="DNA-CMP-002",
+                    name="Maintainability Index Floor",
+                    passed=mi_pass,
+                    severity="error" if self.min_maintainability_index > 65 else "warning",
+                    message=(
+                        f"Maintainability Index ({current_mi}) meets required floor ({self.min_maintainability_index})"
+                        if mi_pass
+                        else f"Maintainability Index ({current_mi}) below required floor ({self.min_maintainability_index})"
+                    ),
+                )
+            )
+
+        # Final Verdict
+        passed_count = sum(1 for e in evaluations if e.passed)
+        failed_count = sum(1 for e in evaluations if not e.passed)
+        overall_pass = all(e.passed for e in evaluations if e.severity == "error")
+
+        return GatekeeperResult(
+            passed=overall_pass,
+            overall_health=current_health,
+            policies_evaluated=len(evaluations),
+            policies_passed=passed_count,
+            policies_failed=failed_count,
+            evaluations=evaluations,
+        )
+
+    def to_sarif(self, result: GatekeeperResult, profile: dict) -> dict:
+        """Generate standard SARIF v2.1.0 output for GitHub Code Scanning integration."""
+        rules = []
+        rule_indices = {}
+
+        # Define standard rules in SARIF schema
+        standard_rules = [
+            {
+                "id": "DNA-HLT-001",
+                "name": "MinimumCodebaseHealth",
+                "shortDescription": {"text": "CodeDNA Minimum Codebase Health Gate"},
+                "fullDescription": {"text": "Enforces that the codebase overall health does not degrade below policy."},
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "DNA-SEC-001",
+                "name": "HardcodedSecretsOrVulnerabilities",
+                "shortDescription": {"text": "Hardcoded Secret or Security Vulnerability"},
+                "fullDescription": {"text": "Identifies hardcoded API tokens, private keys, or critical security vulnerabilities."},
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "DNA-SML-001",
+                "name": "CriticalCodeSmellCeiling",
+                "shortDescription": {"text": "Critical Code Smell Limit Exceeded"},
+                "fullDescription": {"text": "Enforces that severe structural issues such as God Classes do not exceed thresholds."},
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "DNA-SML-002",
+                "name": "TotalCodeSmellsThreshold",
+                "shortDescription": {"text": "Total Code Smells Limit Exceeded"},
+                "fullDescription": {"text": "Enforces that cumulative code smell findings remain within acceptable boundaries."},
+                "defaultConfiguration": {"level": "warning"},
+            },
+            {
+                "id": "DNA-DEP-001",
+                "name": "CircularDependencyDetected",
+                "shortDescription": {"text": "Circular Dependency Cycle"},
+                "fullDescription": {"text": "Architectural coupling cycle detected between modules."},
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "DNA-DEP-002",
+                "name": "CouplingDensityLimit",
+                "shortDescription": {"text": "Coupling Density Limit Exceeded"},
+                "fullDescription": {"text": "Enforces that dependency density between modules stays below complexity limits."},
+                "defaultConfiguration": {"level": "warning"},
+            },
+            {
+                "id": "DNA-CMP-001",
+                "name": "CyclomaticComplexityCeiling",
+                "shortDescription": {"text": "Peak Cyclomatic Complexity Limit Exceeded"},
+                "fullDescription": {"text": "Enforces that peak function cyclomatic complexity does not exceed thresholds."},
+                "defaultConfiguration": {"level": "error"},
+            },
+            {
+                "id": "DNA-CMP-002",
+                "name": "MaintainabilityIndexFloor",
+                "shortDescription": {"text": "Maintainability Index Below Floor"},
+                "fullDescription": {"text": "Enforces that system maintainability index meets required rating."},
+                "defaultConfiguration": {"level": "error"},
+            },
+        ]
+
+        for idx, r in enumerate(standard_rules):
+            rules.append(r)
+            rule_indices[r["id"]] = idx
+
+        sarif_results = []
+
+        # 1. Add Gatekeeper policy breaches
+        for evaluation in result.evaluations:
+            if not evaluation.passed:
+                rule_idx = rule_indices.get(evaluation.rule_id, 0)
+                level = "error" if evaluation.severity == "error" else "warning"
+                sarif_results.append({
+                    "ruleId": evaluation.rule_id,
+                    "ruleIndex": rule_idx,
+                    "level": level,
+                    "message": {"text": f"{evaluation.name}: {evaluation.message}"},
+                    "locations": [
+                        {
+                            "physicalLocation": {
+                                "artifactLocation": {"uri": "pyproject.toml"},
+                                "region": {"startLine": 1},
+                            }
+                        }
+                    ],
+                })
+
+        # 2. Add individual secrets if present
+        security = profile.get("security", {})
+        for vuln in security.get("vulnerabilities", []):
+            raw_file = vuln.get("file", "unknown")
+            line = 1
+            if ":" in raw_file:
+                parts = raw_file.split(":")
+                raw_file = parts[0]
+                try:
+                    line = int(parts[1])
+                except (ValueError, IndexError):
+                    line = 1
+
+            sarif_results.append({
+                "ruleId": "DNA-SEC-001",
+                "ruleIndex": rule_indices.get("DNA-SEC-001", 1),
+                "level": "error",
+                "message": {"text": f"{vuln.get('type')}: {vuln.get('detail')}"},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": raw_file.replace("\\", "/")},
+                            "region": {"startLine": line},
+                        }
+                    }
+                ],
+            })
+
+        return {
+            "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+            "version": "2.1.0",
+            "runs": [
+                {
+                    "tool": {
+                        "driver": {
+                            "name": "CodeDNA Gatekeeper",
+                            "semanticVersion": __version__,
+                            "informationUri": "https://github.com/shenald-dev/codedna",
+                            "rules": rules,
+                        }
+                    },
+                    "results": sarif_results,
+                }
+            ],
+        }
+
+    def to_markdown(self, result: GatekeeperResult, profile: dict) -> str:
+        """Format Gatekeeper evaluation as a GitHub Flavored Markdown PR comment report."""
+        badge = "🟢 PASSED" if result.passed else "🔴 FAILED"
+        lines = [
+            f"## 🛡️ CodeDNA Quality Gatekeeper — {badge}\n",
+            f"> **Overall Health:** `{result.overall_health}`  ",
+            f"> **Policies Evaluated:** **{result.policies_evaluated}** (Passed: {result.policies_passed}, Failed: {result.policies_failed})  ",
+            f"> **Evaluated At:** {result.timestamp[:19]}\n",
+            "---\n",
+            "### 📋 Architectural & Quality Policy Checklist\n",
+            "| Rule ID | Policy | Severity | Status | Message |",
+            "| :--- | :--- | :---: | :---: | :--- |",
+        ]
+
+        for e in result.evaluations:
+            status_icon = "✅ Pass" if e.passed else "❌ Breach"
+            lines.append(f"| `{e.rule_id}` | {e.name} | `{e.severity.upper()}` | {status_icon} | {e.message} |")
+
+        security = profile.get("security", {})
+        vulns = security.get("vulnerabilities", [])
+        if vulns:
+            lines.append("\n### 🔒 Security Alerts")
+            lines.append("| Type | Location | Detail |")
+            lines.append("| :--- | :--- | :--- |")
+            for v in vulns:
+                lines.append(f"| `{v.get('type')}` | `{v.get('file')}` | {v.get('detail')} |")
+
+        lines.append("\n---\n*Generated by [CodeDNA Gatekeeper](https://github.com/shenald-dev/codedna)*")
+        return "\n".join(lines)
+
+    def to_json(self, result: GatekeeperResult) -> str:
+        """Serialize result to formatted JSON string."""
+        return json.dumps(result.to_dict(), indent=2)