codd-dev 2.12.0__tar.gz → 2.13.0__tar.gz

{codd_dev-2.12.0 → codd_dev-2.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.12.0
+Version: 2.13.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev
@@ -153,10 +153,11 @@ This is what lets CoDD ship one core that works for Next.js, Django, FastAPI, Ra
 
 ## 🧭 Roadmap
 
-- **v2.12.0 (current)** — Test-completeness gates: C7 `actors_without_journeys` amber promotion + new C8 `ci_health` static check (workflow presence, trigger coverage, verification-in-workflow). Defaults to opt-in for legacy projects; new `codd init` projects get `ci:` defaults from the template. See [post-mortem](docs/post-mortems/test_completeness_gap.md).
+- **v2.13.0 (current)** — Opt-out protection: `OptOutPolicy` requires a `justification` + `expires_at` for every config-level opt-out (`ci.provider=none`, etc.). Silent SKIP abolished; severity preserved. `codd validate` reports policy violations. See [post-mortem](docs/post-mortems/optout_loophole.md).
+- **v2.12.0** — Test-completeness gates: C7 `actors_without_journeys` amber promotion + new C8 `ci_health` static check (workflow presence, trigger coverage, verification-in-workflow). See [post-mortem](docs/post-mortems/test_completeness_gap.md).
 - **v2.11.0** — Sprint-less `codd implement` (`--design <path> --output <dir>` directly; `implementation_plan.md` parser removed). See [migration guide](docs/migrations/v2.11.0-sprintless.md).
 - **v2.10.0** — Lexicon-driven completeness, 38 plug-ins, LLM-enhanced init, scope/phase filter, auto-repair across the full DAG.
-- **v2.13.0 (next)** — C8 `ci_health` runtime mode (opt-in `ci.runtime_check: true`) polling the CI provider for latest-run-on-default-branch success.
+- **v2.14.0 (next)** — C8 `ci_health` runtime mode (opt-in `ci.runtime_check: true`) polling the CI provider for latest-run-on-default-branch success.
 
 ---
 

{codd_dev-2.12.0 → codd_dev-2.13.0}/README.md

@@ -113,10 +113,11 @@ This is what lets CoDD ship one core that works for Next.js, Django, FastAPI, Ra
 
 ## 🧭 Roadmap
 
-- **v2.12.0 (current)** — Test-completeness gates: C7 `actors_without_journeys` amber promotion + new C8 `ci_health` static check (workflow presence, trigger coverage, verification-in-workflow). Defaults to opt-in for legacy projects; new `codd init` projects get `ci:` defaults from the template. See [post-mortem](docs/post-mortems/test_completeness_gap.md).
+- **v2.13.0 (current)** — Opt-out protection: `OptOutPolicy` requires a `justification` + `expires_at` for every config-level opt-out (`ci.provider=none`, etc.). Silent SKIP abolished; severity preserved. `codd validate` reports policy violations. See [post-mortem](docs/post-mortems/optout_loophole.md).
+- **v2.12.0** — Test-completeness gates: C7 `actors_without_journeys` amber promotion + new C8 `ci_health` static check (workflow presence, trigger coverage, verification-in-workflow). See [post-mortem](docs/post-mortems/test_completeness_gap.md).
 - **v2.11.0** — Sprint-less `codd implement` (`--design <path> --output <dir>` directly; `implementation_plan.md` parser removed). See [migration guide](docs/migrations/v2.11.0-sprintless.md).
 - **v2.10.0** — Lexicon-driven completeness, 38 plug-ins, LLM-enhanced init, scope/phase filter, auto-repair across the full DAG.
-- **v2.13.0 (next)** — C8 `ci_health` runtime mode (opt-in `ci.runtime_check: true`) polling the CI provider for latest-run-on-default-branch success.
+- **v2.14.0 (next)** — C8 `ci_health` runtime mode (opt-in `ci.runtime_check: true`) polling the CI provider for latest-run-on-default-branch success.
 
 ---
 

{codd_dev-2.12.0 → codd_dev-2.13.0}/codd/cli.py

@@ -4901,10 +4901,13 @@ def dag_verify(project_path: str, check_names: tuple[str, ...], output_format: s
         click.echo(f"Error: {exc}")
         raise SystemExit(1)
 
+    opt_out_results = [result for result in results if _dag_result_status(result) == "opt_out"]
     failed_red = [
         result
         for result in results
-        if not _dag_result_passed(result) and _dag_result_severity(result) == "red"
+        if not _dag_result_passed(result)
+        and _dag_result_severity(result) == "red"
+        and _dag_result_status(result) != "opt_out"
     ]
     amber_findings = [
         result
@@ -4917,7 +4920,10 @@ def dag_verify(project_path: str, check_names: tuple[str, ...], output_format: s
     else:
         for result in results:
             severity = _dag_result_severity(result)
-            if _dag_result_passed(result):
+            status_value = _dag_result_status(result)
+            if status_value == "opt_out":
+                status = "OPT_OUT"
+            elif _dag_result_passed(result):
                 status = "PASS"
             else:
                 status = "WARN" if severity == "amber" else "FAIL"
@@ -4929,6 +4935,10 @@ def dag_verify(project_path: str, check_names: tuple[str, ...], output_format: s
             click.echo(f"\n{len(failed_red)} check(s) FAILED (severity=red)")
         elif amber_findings:
             click.echo(f"\n{len(amber_findings)} check(s) WARN (severity=amber, deploy allowed)")
+        if opt_out_results:
+            click.echo(f"\n{len(opt_out_results)} active opt-out(s) (deploy allowed):")
+            for result in opt_out_results:
+                click.echo(f"  - {_dag_result_name(result)}: {_dag_result_message(result)}")
 
     raise SystemExit(1 if failed_red else 0)
 
@@ -5185,6 +5195,14 @@ def _dag_result_passed(result: Any) -> bool:
     return _dag_result_value(result, "passed") is not False
 
 
+def _dag_result_status(result: Any) -> str:
+    return str(_dag_result_value(result, "status") or "")
+
+
+def _dag_result_message(result: Any) -> str:
+    return str(_dag_result_value(result, "message") or "")
+
+
 def _dag_result_has_findings(result: Any) -> bool:
     for key in (
         "violations",

{codd_dev-2.12.0 → codd_dev-2.13.0}/codd/coverage_metrics.py

@@ -183,12 +183,17 @@ def compute_dag_completeness(
         return _exception_result("dag_completeness", threshold, exc)
 
     red_results = [result for result in results if _dag_result_severity(result) == "red"]
-    failed_red = [result for result in red_results if _dag_result_passed(result) is False]
+    failed_red = [
+        result
+        for result in red_results
+        if _dag_result_passed(result) is False and _dag_result_status(result) != "opt_out"
+    ]
     amber_findings = [
         result
         for result in results
         if _dag_result_severity(result) == "amber" and _dag_result_has_findings(result)
     ]
+    opt_outs = [result for result in results if _dag_result_status(result) == "opt_out"]
 
     total = len(red_results)
     uncovered = len(failed_red)
@@ -197,6 +202,7 @@ def compute_dag_completeness(
     details = [f"checks: {len(results)}", f"red_failures: {uncovered}"]
     details.extend(_format_dag_result(result) for result in failed_red[:5])
     details.extend(f"warning: {_format_dag_result(result)}" for result in amber_findings[:5])
+    details.extend(f"opt_out: {_format_dag_result(result)}" for result in opt_outs[:5])
 
     return CoverageResult(
         metric="dag_completeness",
@@ -361,6 +367,10 @@ def _dag_result_passed(result: Any) -> bool:
     return _dag_result_value(result, "passed") is not False
 
 
+def _dag_result_status(result: Any) -> str:
+    return str(_dag_result_value(result, "status") or "")
+
+
 def _dag_result_name(result: Any) -> str:
     return str(_dag_result_value(result, "check_name") or result.__class__.__name__)
 

{codd_dev-2.12.0 → codd_dev-2.13.0}/codd/dag/checks/__init__.py

@@ -3,8 +3,12 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from datetime import date
 from pathlib import Path
-from typing import Any
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codd.dag.checks.opt_out import OptOutDeclaration, OptOutPolicy, OptOutSignal
 
 
 _REGISTRY: dict[str, type[Any]] = {}
@@ -34,14 +38,50 @@ class DagCheck:
         dag: Any | None = None,
         project_root: str | Path | None = None,
         settings: dict[str, Any] | None = None,
+        opt_out_policy: "OptOutPolicy | None" = None,
+        today: date | None = None,
     ) -> None:
         self.dag = dag
         self.project_root = Path(project_root) if project_root is not None else None
         self.settings = settings or {}
+        self.opt_out_policy = opt_out_policy
+        self.today = today or date.today()
 
     def run(self, dag: Any | None = None) -> CheckResult:
         raise NotImplementedError
 
+    def detect_opt_out(self, codd_config: dict[str, Any]) -> "OptOutSignal | None":
+        """Return an OptOutSignal when this check's config requests an opt-out.
+
+        Default: no opt-out detection. Subclasses that own a config-level
+        opt-out flag (e.g. ``ci.provider: none``) override this and route the
+        request through :class:`OptOutPolicy` rather than handling it inline.
+        """
+
+        del codd_config
+        return None
+
+    def resolve_opt_out(
+        self,
+        codd_config: dict[str, Any] | None = None,
+    ) -> "tuple[OptOutSignal, OptOutDeclaration | None] | None":
+        """Convenience helper: run detect_opt_out and look up a declaration.
+
+        Returns ``None`` when no opt-out signal is detected. Returns
+        ``(signal, declaration_or_None)`` otherwise so the caller can decide
+        whether the missing-or-expired declaration should fail red or pass
+        through.
+        """
+
+        config = codd_config if codd_config is not None else self.settings
+        signal = self.detect_opt_out(config)
+        if signal is None:
+            return None
+        declaration = (
+            self.opt_out_policy.lookup(signal.check_name) if self.opt_out_policy else None
+        )
+        return signal, declaration
+
 
 def register_dag_check(name: str):
     """Register a DAG check class under ``name``."""

{codd_dev-2.12.0 → codd_dev-2.13.0}/codd/dag/checks/ci_health.py

@@ -12,9 +12,15 @@ from typing import Any, Mapping
 import yaml
 
 from codd.dag.checks import DagCheck, register_dag_check
+from codd.dag.checks.opt_out import (
+    OPT_OUT_STATUS,
+    OptOutDeclaration,
+    OptOutSignal,
+)
 
 
 _DEFAULT_PROVIDER = "github" + "_actions"
+_OPT_OUT_PROVIDER = "none"
 
 
 @dataclass
@@ -30,7 +36,11 @@ class CiConfig:
     @classmethod
     def from_mapping(cls, value: Mapping[str, Any] | None) -> "CiConfig":
         if not isinstance(value, Mapping):
-            return cls(provider="none")
+            # Missing ``ci:`` section is no longer treated as a silent opt-out.
+            # The default provider applies; if no workflow files exist this
+            # surfaces as a normal red ``ci_workflow_missing`` finding rather
+            # than a free PASS.
+            return cls()
 
         config = cls()
         return cls(
@@ -87,17 +97,67 @@ class CiHealthCheck(DagCheck):
         del dag
         root = Path(project_root or self.project_root or ".").resolve()
         active_settings = codd_config or settings or self.settings
-        return self.check(root, CiConfig.from_mapping(_mapping_value(active_settings, "ci")))
+        config = CiConfig.from_mapping(_mapping_value(active_settings, "ci"))
+        return self.check(root, config)
+
+    def detect_opt_out(self, codd_config: dict[str, Any]) -> OptOutSignal | None:
+        config = CiConfig.from_mapping(_mapping_value(codd_config, "ci"))
+        if self._is_opt_out_provider(config):
+            return OptOutSignal(
+                check_name=self.check_name,
+                source="ci.provider=none",
+            )
+        return None
 
-    def check(self, project_root: Path, config: CiConfig) -> CiHealthResult:
-        project_root = Path(project_root).resolve()
-        if config.provider.strip().lower() == "none":
+    @staticmethod
+    def _is_opt_out_provider(config: CiConfig) -> bool:
+        return config.provider.strip().lower() == _OPT_OUT_PROVIDER
+
+    def _make_opt_out_result(self, declaration: OptOutDeclaration | None) -> CiHealthResult:
+        today = self.today
+        if declaration is None:
+            return CiHealthResult(
+                status="fail",
+                severity="red",
+                block_deploy=True,
+                message=(
+                    "C8 ci_health: ci.provider=none requires an opt_outs declaration "
+                    "in codd.yaml (check: ci_health, reason: ..., expires_at: "
+                    "YYYY-MM-DD)."
+                ),
+                passed=False,
+            )
+        if declaration.is_expired(today):
             return CiHealthResult(
-                status="skip",
-                message="ci.provider=none, C8 SKIP",
-                passed=True,
+                status="fail",
+                severity="red",
+                block_deploy=True,
+                message=(
+                    f"C8 ci_health: opt-out expired on "
+                    f"{declaration.expires_at.isoformat()} "
+                    f"(reason: {declaration.reason}); renew the entry or remove it."
+                ),
+                passed=False,
             )
+        return CiHealthResult(
+            status=OPT_OUT_STATUS,
+            severity=self.severity,
+            block_deploy=False,
+            message=(
+                f"C8 ci_health opt-out active "
+                f"(reason: {declaration.reason}, "
+                f"expires: {declaration.expires_at.isoformat()})"
+            ),
+            passed=False,
+        )
 
+    def check(self, project_root: Path, config: CiConfig) -> CiHealthResult:
+        project_root = Path(project_root).resolve()
+        if self._is_opt_out_provider(config):
+            declaration = (
+                self.opt_out_policy.lookup(self.check_name) if self.opt_out_policy else None
+            )
+            return self._make_opt_out_result(declaration)
         workflow_files = self._locate_workflows(project_root, config.workflow_glob)
         if not workflow_files:
             finding = CiHealthFinding(

codd_dev-2.13.0/codd/dag/checks/opt_out.py

@@ -0,0 +1,265 @@
+"""Generic opt-out policy for DAG checks.
+
+This module introduces a single, check-agnostic representation of "the user
+has explicitly asked this gate to stand down". It is the only sanctioned way
+to disable a registered DAG check; per-check ad-hoc flags (e.g. legacy
+``ci.provider: none`` style) must be re-routed through this policy via the
+:meth:`DagCheck.detect_opt_out` hook.
+
+A valid opt-out requires:
+
+* an explicit ``opt_outs`` entry in ``codd.yaml`` whose ``check`` matches a
+  registered DAG check name;
+* a non-empty ``reason``;
+* an ISO ``expires_at`` date strictly in the future at evaluation time.
+
+Anything else is rejected. ``codd validate`` surfaces the policy errors as
+configuration problems; ``codd dag verify`` aggregates active and expired
+opt-outs separately from the normal pass/fail counts so the cost of a
+standing opt-out is always visible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any, Iterable, Mapping
+
+
+OPT_OUT_STATUS = "opt_out"
+
+
+@dataclass(frozen=True)
+class OptOutDeclaration:
+    """One opt-out entry parsed from ``codd.yaml``."""
+
+    check: str
+    reason: str
+    expires_at: date
+    approved_by: str | None = None
+    context: str | None = None
+
+    def is_expired(self, today: date) -> bool:
+        return self.expires_at <= today
+
+
+@dataclass(frozen=True)
+class OptOutSignal:
+    """Emitted by a check when its config indicates an explicit opt-out request."""
+
+    check_name: str
+    source: str
+
+
+@dataclass(frozen=True)
+class OptOutPolicyError:
+    """A configuration-level violation of the opt-out policy."""
+
+    code: str
+    message: str
+    check: str | None = None
+
+
+@dataclass
+class OptOutPolicy:
+    """Resolved opt-out declarations for a project."""
+
+    declarations: list[OptOutDeclaration] = field(default_factory=list)
+    parse_errors: list[OptOutPolicyError] = field(default_factory=list)
+
+    @classmethod
+    def from_config(cls, codd_config: Mapping[str, Any] | None) -> "OptOutPolicy":
+        """Build a policy from the parsed ``codd.yaml`` mapping.
+
+        Unknown / unparseable shapes are recorded as ``parse_errors`` rather
+        than raised — this lets ``codd validate`` report them alongside other
+        validation issues.
+        """
+
+        if not isinstance(codd_config, Mapping):
+            return cls()
+
+        raw = codd_config.get("opt_outs")
+        if raw is None:
+            return cls()
+        if not isinstance(raw, list):
+            return cls(
+                parse_errors=[
+                    OptOutPolicyError(
+                        code="invalid_opt_outs_section",
+                        message="opt_outs must be a list of mappings",
+                    )
+                ]
+            )
+
+        declarations: list[OptOutDeclaration] = []
+        errors: list[OptOutPolicyError] = []
+        for index, entry in enumerate(raw):
+            if not isinstance(entry, Mapping):
+                errors.append(
+                    OptOutPolicyError(
+                        code="invalid_opt_out_entry",
+                        message=f"opt_outs[{index}] must be a mapping",
+                    )
+                )
+                continue
+            decl, entry_errors = _build_declaration(entry, index)
+            errors.extend(entry_errors)
+            if decl is not None:
+                declarations.append(decl)
+
+        return cls(declarations=declarations, parse_errors=errors)
+
+    def lookup(self, check_name: str) -> OptOutDeclaration | None:
+        """Return the raw declaration for ``check_name`` (regardless of expiry).
+
+        Expiry handling is the caller's responsibility: a declaration may be
+        present but expired, and the caller decides whether that is treated as
+        a hard failure or a warning. This keeps the policy itself stateless
+        with respect to "today".
+        """
+
+        for declaration in self.declarations:
+            if declaration.check == check_name:
+                return declaration
+        return None
+
+    def validate(
+        self,
+        today: date,
+        registered_check_names: Iterable[str],
+    ) -> list[OptOutPolicyError]:
+        """Return all opt-out policy errors at the given evaluation date.
+
+        Errors include parse errors discovered at ``from_config`` time,
+        unknown check names, duplicates, and expired declarations.
+        """
+
+        errors: list[OptOutPolicyError] = list(self.parse_errors)
+        registered = set(registered_check_names)
+        seen_checks: set[str] = set()
+
+        for declaration in self.declarations:
+            if declaration.check in seen_checks:
+                errors.append(
+                    OptOutPolicyError(
+                        code="duplicate",
+                        check=declaration.check,
+                        message=(
+                            f"opt_outs has more than one entry for check "
+                            f"{declaration.check!r}"
+                        ),
+                    )
+                )
+                continue
+            seen_checks.add(declaration.check)
+
+            if declaration.check not in registered:
+                errors.append(
+                    OptOutPolicyError(
+                        code="unknown_check",
+                        check=declaration.check,
+                        message=(
+                            f"opt_outs entry references unknown check "
+                            f"{declaration.check!r}"
+                        ),
+                    )
+                )
+            if declaration.is_expired(today):
+                errors.append(
+                    OptOutPolicyError(
+                        code="expired",
+                        check=declaration.check,
+                        message=(
+                            f"opt_outs entry for {declaration.check!r} expired on "
+                            f"{declaration.expires_at.isoformat()}; renew or remove"
+                        ),
+                    )
+                )
+
+        return errors
+
+    def active(self, today: date) -> list[OptOutDeclaration]:
+        return [decl for decl in self.declarations if not decl.is_expired(today)]
+
+    def expired(self, today: date) -> list[OptOutDeclaration]:
+        return [decl for decl in self.declarations if decl.is_expired(today)]
+
+
+def _build_declaration(
+    entry: Mapping[str, Any],
+    index: int,
+) -> tuple[OptOutDeclaration | None, list[OptOutPolicyError]]:
+    errors: list[OptOutPolicyError] = []
+    check_value = entry.get("check")
+    check_name: str | None = None
+    if isinstance(check_value, str) and check_value.strip():
+        check_name = check_value.strip()
+    else:
+        errors.append(
+            OptOutPolicyError(
+                code="missing_check",
+                message=f"opt_outs[{index}] is missing a non-empty 'check' name",
+            )
+        )
+
+    reason_value = entry.get("reason")
+    reason = reason_value.strip() if isinstance(reason_value, str) else ""
+    if not reason:
+        errors.append(
+            OptOutPolicyError(
+                code="missing_reason",
+                check=check_name,
+                message=(
+                    f"opt_outs[{index}] requires a non-empty 'reason' "
+                    "(briefly explain why this gate is disabled)"
+                ),
+            )
+        )
+
+    expires_at = _coerce_expires_at(entry.get("expires_at"))
+    if expires_at is None:
+        errors.append(
+            OptOutPolicyError(
+                code="missing_expires_at",
+                check=check_name,
+                message=(
+                    f"opt_outs[{index}] requires 'expires_at' as an ISO date "
+                    "(YYYY-MM-DD) so the opt-out cannot be permanent"
+                ),
+            )
+        )
+
+    if check_name is None or expires_at is None or not reason:
+        return None, errors
+
+    approved_by = entry.get("approved_by")
+    approved_by = approved_by.strip() if isinstance(approved_by, str) and approved_by.strip() else None
+
+    context = entry.get("context")
+    context = context.strip() if isinstance(context, str) and context.strip() else None
+
+    declaration = OptOutDeclaration(
+        check=check_name,
+        reason=reason,
+        expires_at=expires_at,
+        approved_by=approved_by,
+        context=context,
+    )
+    return declaration, errors
+
+
+def _coerce_expires_at(value: Any) -> date | None:
+    if isinstance(value, date) and not isinstance(value, datetime):
+        return value
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        try:
+            return date.fromisoformat(text)
+        except ValueError:
+            return None
+    return None