code-constraints 0.1.0__py3-none-any.whl

code_constraints/waivers/collect.py

@@ -0,0 +1,167 @@
+"""Run the checks and project the result into one keyed issue list.
+
+`cdec exceptions allow V-1A2B3C4D` has to answer "which issue is that?", and the
+only honest answer comes from re-running the checks: a key is a hash of an
+identity, not a record you can look up. Re-deriving it also means an exception
+can never be granted for an issue that isn't actually there — the key must match
+something reported *now*, or the command refuses.
+
+Since every gate is a rule, this is one run of the same engine `cdec check`
+uses, resolved through `lint.pipeline` with the same options. The keys only line
+up if both commands look at the same source and the same baseline, and this is
+what guarantees they do.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from code_constraints.lint.config import (
+    LoadedRules,
+    ProjectConfig,
+    load_project_config,
+    load_rules,
+)
+from code_constraints.lint.pipeline import PipelineError, parse_source, resolve_baseline
+from code_constraints.waivers.model import Issue
+from code_constraints.waivers.store import WaiverStore, ledger_paths, load_waivers
+
+
+@dataclass
+class CollectOptions:
+    """Everything that changes *which* issues exist. Mirrors `cdec check`'s
+    options one for one, because the keys have to line up with the report the
+    reviewer is holding."""
+
+    source: Path | None = None
+    reference: Path | None = None
+    base_ref: str | None = None
+    repo: Path = Path(".")
+
+
+@dataclass
+class Collected:
+    issues: list[Issue] = field(default_factory=list)
+    store: WaiverStore = field(default_factory=WaiverStore)
+    ledger_path: Path = Path()
+    config: ProjectConfig | None = None
+    # Rule ids whose results in `issues` are complete. `prune` needs this: an
+    # exception isn't stale just because the rule that reports it didn't run.
+    rules_ran: set[str] = field(default_factory=set)
+    # Engines whose results are complete, derived from `rules_ran`. An exception
+    # is keyed by engine, so this is the granularity pruning works at.
+    engines_ran: set[str] = field(default_factory=set)
+    # Rules that couldn't run, with the reason (e.g. a language with no
+    # fingerprinter). Reported rather than swallowed: a silently skipped rule
+    # looks exactly like a clean one.
+    skipped: list[tuple[str, str]] = field(default_factory=list)
+
+    def by_key(self) -> dict[str, Issue]:
+        return {issue.key: issue for issue in self.issues}
+
+    def open_issues(self) -> list[Issue]:
+        return [i for i in self.issues if not i.waived]
+
+
+def collect_issues(config_dir: Path, options: CollectOptions | None = None) -> Collected:
+    """Every issue `cdec check` currently reports, accepted ones included.
+
+    Accepted issues stay in the list (flagged `waived=True`) so `remove` and
+    `prune` can reason about them.
+    """
+    opts = options or CollectOptions()
+    cfg = load_project_config(config_dir)
+    source_path = opts.source.resolve() if opts.source else cfg.source
+    rules_file, _ = ledger_paths(config_dir)
+    store = load_waivers(config_dir)
+
+    out = Collected(store=store, ledger_path=rules_file, config=cfg)
+
+    head_proj = parse_source(source_path, cfg.language)
+    annotated, has_diff, base_proj = resolve_baseline(
+        head_proj=head_proj,
+        lang=cfg.language,
+        config_dir=config_dir,
+        explicit_reference=opts.reference,
+        explicit_base_ref=opts.base_ref,
+        repo_path=opts.repo,
+        default_reference=cfg.reference,
+    )
+
+    # Imported here, not at module scope: `lint.engine` pulls in `lint.baseline`,
+    # which adapts this package's store — a module-level import would close the
+    # cycle while `waivers` is still initialising.
+    from code_constraints.lint.engine import SourceContext, run_checks
+
+    loaded: LoadedRules = load_rules(config_dir)
+    # Run unfiltered (`baseline=None`) so accepted issues are still visible to
+    # the review workflow rather than silently dropped.
+    report = run_checks(
+        annotated,
+        loaded.rules,
+        has_diff=has_diff,
+        baseline=None,
+        baseline_project=base_proj,
+        source_context=SourceContext(
+            source=source_path,
+            language=cfg.language,
+            config_dir=config_dir,
+            reference_path=opts.reference or cfg.reference_path,
+        ),
+    )
+
+    skipped_ids = {rule_id for rule_id, _ in report.skipped}
+    out.skipped = list(report.skipped)
+    for rule in loaded.rules:
+        if rule.rule_id not in skipped_ids:
+            out.rules_ran.add(rule.rule_id)
+
+    for v in report.violations:
+        issue = Issue(
+            engine=v.key_engine,
+            rule=v.key_rule or v.rule_id,
+            rule_id=v.rule_id,
+            qualified_name=v.qualified_name,
+            detail=v.signature or "",
+            message=v.message,
+            severity=v.severity.value,
+            file=v.location.file if v.location else "",
+            line=v.location.start_line if v.location else 0,
+            waivable=v.waivable,
+        )
+        out.issues.append(issue)
+        out.engines_ran.add(issue.engine)
+
+    # A rule that ran and found nothing still counts as "this engine ran", which
+    # is exactly the case where a stale exception should be pruned.
+    for rule in loaded.rules:
+        if rule.rule_id in skipped_ids:
+            continue
+        out.engines_ran.update(_engines_of(rule))
+
+    for issue in out.issues:
+        if issue.waivable and store.has(issue.key):
+            issue.waived = True
+            waiver = store.get(issue.key)
+            issue.waiver_reason = waiver.reason if waiver else ""
+
+    return out
+
+
+def _engines_of(rule) -> set[str]:
+    """Which key-engine(s) a rule type can produce issues under.
+
+    Needed because pruning happens per engine but a clean run reports no
+    violations to read the engine off, and dropping every `F-` exception just
+    because the tag-conformance rule happened to pass would be wrong only if
+    that rule never ran at all.
+    """
+    return {
+        "tag-conformance": {"enforce"},
+        "implementation-locks": {"lock"},
+        "reference-architecture": {"reference"},
+    }.get(rule.type_name, {"check"})
+
+
+__all__ = ["CollectOptions", "Collected", "collect_issues", "PipelineError"]

code_constraints/waivers/model.py

@@ -0,0 +1,90 @@
+"""One engine-neutral view of a reported issue.
+
+The engines have deliberately separate result types (`Violation`, `Finding`,
+`LockViolation`, `Deviation`). The review workflow needs to talk about all of
+them in one list, so this is the narrow projection they share — just enough to
+print a line, identify it by key, and turn it into an exception.
+
+Adapting happens at the boundary (`collect.py`); the engines never learn about
+this type, so they stay decoupled.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from code_constraints.core.keys import make_key
+from code_constraints.waivers.store import WAIVABLE_ENGINES, Waiver, now_stamp
+
+
+class NotWaivable(ValueError):
+    """Raised when something tries to waive an issue that must not be waived."""
+
+
+@dataclass
+class Issue:
+    """A single reported issue, from any engine."""
+
+    engine: str  # "check" | "enforce" | "lock" | "reference"
+    rule: str  # the engine's own rule identity — what the key is derived from
+    qualified_name: str  # class qname, or lock target
+    detail: str = ""  # discriminator; see code_constraints.core.keys
+    message: str = ""
+    severity: str = "error"
+    file: str = ""
+    line: int = 0
+    # The `rules.yaml` entry that surfaced this issue. Shown to the reader so a
+    # report points at the line of config to edit; never part of the key, so
+    # renaming an entry doesn't invalidate an exception granted against it.
+    rule_id: str = ""
+    # False for issues that must not be accepted as exceptions — locks.
+    waivable: bool = True
+    # True when an exception already covers this issue (it was silenced).
+    waived: bool = False
+    waiver_reason: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.rule_id:
+            self.rule_id = self.rule
+        # The engine is the authority on waivability; a caller can only narrow.
+        if self.engine not in WAIVABLE_ENGINES:
+            self.waivable = False
+
+    @property
+    def key(self) -> str:
+        return make_key(self.engine, self.rule, self.qualified_name, self.detail)
+
+    @property
+    def location(self) -> str:
+        if not self.file:
+            return ""
+        return f"{self.file}:{self.line}" if self.line else self.file
+
+    def to_waiver(self, reason: str = "", actor: str = "") -> Waiver:
+        if not self.waivable:
+            raise NotWaivable(_not_waivable_message(self))
+        return Waiver(
+            engine=self.engine,
+            rule=self.rule,
+            qualified_name=self.qualified_name,
+            detail=self.detail,
+            reason=reason,
+            added=now_stamp(),
+            added_by=actor,
+        )
+
+
+def _not_waivable_message(issue: Issue) -> str:
+    """Locks are the only non-exceptable engine, and the message has to say what
+    to do instead — a dead end here is a dead end for the whole workflow."""
+    if issue.engine == "lock":
+        return (
+            f"{issue.key} is a lock violation on '{issue.qualified_name}', and locks "
+            f"cannot be accepted as exceptions. A frozen implementation may only "
+            f"change with a lead's approval, which leaves a reviewable diff on the "
+            f"`locks:` section of .cdec/rules.yaml:\n"
+            f"    cdec check --automatic-exceptions locks --force\n"
+            f"To drop the lock entirely, delete its @locked tag from the source and "
+            f"re-run that command."
+        )
+    return f"{issue.key}: issues from engine {issue.engine!r} cannot be accepted."

code_constraints/waivers/ops.py

@@ -0,0 +1,150 @@
+"""Apply review decisions to the exceptions ledger.
+
+Kept apart from the CLI so the rules about what may be waived — and what must
+be refused — are testable on their own and identical whether the decision
+arrives from a marked-up file, a key on the command line, or (later) an MCP
+call.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from code_constraints.core.keys import normalize_key
+from code_constraints.waivers.collect import Collected
+from code_constraints.waivers.model import Issue, NotWaivable
+from code_constraints.waivers.review import Decision, ReviewDecisions
+from code_constraints.waivers.store import Waiver, WaiverStore, default_actor
+
+
+@dataclass
+class ApplyResult:
+    allowed: list[Issue] = field(default_factory=list)
+    already_waived: list[Issue] = field(default_factory=list)
+    removed: list[Waiver] = field(default_factory=list)
+    # Keys that match no current issue and no existing waiver. Nearly always a
+    # stale report or a mistyped key, so it's an error rather than a no-op.
+    unknown: list[str] = field(default_factory=list)
+    # (key, explanation) for issues that exist but must not be waived — locks.
+    refused: list[tuple[str, str]] = field(default_factory=list)
+    # [REMOVE] on a key that wasn't waived in the first place.
+    not_waived: list[str] = field(default_factory=list)
+    malformed: list[str] = field(default_factory=list)
+    problems: list[str] = field(default_factory=list)
+
+    @property
+    def changed(self) -> bool:
+        return bool(self.allowed or self.removed)
+
+    @property
+    def failed(self) -> bool:
+        return bool(self.unknown or self.refused or self.malformed or self.problems)
+
+
+def apply_decisions(
+    store: WaiverStore,
+    collected: Collected,
+    decisions: ReviewDecisions,
+    *,
+    default_reason: str = "",
+    actor: str | None = None,
+) -> ApplyResult:
+    """Apply `[ALLOW]` / `[REMOVE]` decisions to `store` in memory."""
+    result = ApplyResult(problems=list(decisions.problems))
+    who = default_actor() if actor is None else actor
+    index = collected.by_key()
+
+    for decision in decisions.allow:
+        _allow_one(store, index, decision, default_reason, who, result)
+    for decision in decisions.remove:
+        _remove_one(store, decision, result)
+    return result
+
+
+def allow_keys(
+    store: WaiverStore,
+    collected: Collected,
+    keys: Iterable[str],
+    *,
+    reason: str = "",
+    actor: str | None = None,
+) -> ApplyResult:
+    """Waive issues named directly by key — the agent-friendly path."""
+    decisions = ReviewDecisions(allow=[Decision(key=k) for k in keys])
+    return apply_decisions(
+        store, collected, decisions, default_reason=reason, actor=actor
+    )
+
+
+def remove_keys(store: WaiverStore, keys: Iterable[str]) -> ApplyResult:
+    """Withdraw waivers by key. Needs no source parse — the store is enough."""
+    result = ApplyResult()
+    for raw in keys:
+        _remove_one(store, Decision(key=raw), result)
+    return result
+
+
+def prune(store: WaiverStore, collected: Collected) -> list[Waiver]:
+    """Drop exceptions whose issue no longer occurs, and return them.
+
+    Only prunes engines that actually ran this time round: an exception is not
+    stale just because the rule that would have reported it was skipped.
+    """
+    engines_ran = collected.engines_ran
+    live = {issue.key for issue in collected.issues}
+    stale = [
+        w for w in store.waivers if w.engine in engines_ran and w.key not in live
+    ]
+    for waiver in stale:
+        store.remove(waiver.key)
+    return stale
+
+
+# ---------- internals ----------
+
+def _allow_one(
+    store: WaiverStore,
+    index: dict[str, Issue],
+    decision: Decision,
+    default_reason: str,
+    actor: str,
+    result: ApplyResult,
+) -> None:
+    key = normalize_key(decision.key)
+    if not key:
+        result.malformed.append(decision.key)
+        return
+    issue = index.get(key)
+    if issue is None:
+        result.unknown.append(key)
+        return
+    reason = decision.reason or default_reason
+    try:
+        waiver = issue.to_waiver(reason=reason, actor=actor)
+    except NotWaivable as exc:
+        result.refused.append((key, str(exc)))
+        return
+    if store.add(waiver):
+        result.allowed.append(issue)
+    else:
+        result.already_waived.append(issue)
+
+
+def _remove_one(store: WaiverStore, decision: Decision, result: ApplyResult) -> None:
+    key = normalize_key(decision.key)
+    if not key:
+        result.malformed.append(decision.key)
+        return
+    if not store.has(key):
+        result.not_waived.append(key)
+        return
+    waiver = store.remove(key)
+    if waiver is not None:
+        result.removed.append(waiver)
+    else:
+        # A hand-written key with no matching tuple: it was honoured for
+        # matching, and dropping it is still a real change.
+        result.removed.append(
+            Waiver(engine="check", rule="(hand-written key)", qualified_name=key)
+        )

code_constraints/waivers/review.py

@@ -0,0 +1,156 @@
+"""The review file: render issues for a human, read their decisions back.
+
+This is the round trip the whole feature exists for. `cdec exceptions review`
+writes a plain-text report where every issue occupies one line and leads with
+its key. A reviewer (or an agent) marks the lines they accept with `[ALLOW]`
+and hands the file to `cdec exceptions patch`, which applies exactly those.
+
+The parser is deliberately forgiving, because the file is meant to be edited by
+hand and pasted between tools: any line carrying a marker and a key counts, no
+matter what else is on it. That means the output of `cdec check --log-out` works
+as a patch file too — the review file is a convenience, not a required format.
+A `#` at the start of a line comments it out, which is how you cancel a decision
+without deleting the evidence.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from code_constraints.core.keys import find_keys
+from code_constraints.waivers.model import Issue
+
+ALLOW_RE = re.compile(r"\[\s*ALLOW\s*(?::\s*([^\]]*?))?\s*\]", re.IGNORECASE)
+REMOVE_RE = re.compile(r"\[\s*(?:REMOVE|UNALLOW|DENY)\s*(?::\s*([^\]]*?))?\s*\]", re.IGNORECASE)
+
+# Order matters: the review file groups by engine in this order, so a reviewer
+# reads the cheap decisions before the ones that need a lead.
+_ENGINE_HEADINGS: dict[str, str] = {
+    "check": "configured architectural rules",
+    "enforce": "source-tag conformance — does the implementation obey its tags",
+    "reference": "reference-architecture gate — structural deviation",
+    "lock": "frozen implementations",
+}
+
+
+@dataclass
+class Decision:
+    """One marked line in a reviewed file."""
+
+    key: str
+    reason: str = ""
+    line_no: int = 0
+    source_line: str = ""
+
+
+@dataclass
+class ReviewDecisions:
+    allow: list[Decision] = field(default_factory=list)
+    remove: list[Decision] = field(default_factory=list)
+    # Lines that carried a marker but no key — almost always a typo in a key,
+    # and silently ignoring them is how a reviewer thinks they allowed
+    # something they didn't.
+    problems: list[str] = field(default_factory=list)
+
+    @property
+    def empty(self) -> bool:
+        return not self.allow and not self.remove
+
+
+def parse_review(text: str) -> ReviewDecisions:
+    """Extract the marked decisions from a reviewed report."""
+    out = ReviewDecisions()
+    for i, raw_line in enumerate(text.splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        allow = ALLOW_RE.search(line)
+        remove = REMOVE_RE.search(line)
+        if allow is None and remove is None:
+            continue
+        keys = find_keys(line)
+        if not keys:
+            marker = "ALLOW" if allow is not None else "REMOVE"
+            out.problems.append(
+                f"line {i}: [{marker}] with no issue key — nothing to apply: {line}"
+            )
+            continue
+        # A line marked both ways is a mistake worth surfacing rather than
+        # resolving by precedence.
+        if allow is not None and remove is not None:
+            out.problems.append(
+                f"line {i}: marked both [ALLOW] and [REMOVE] — skipped: {line}"
+            )
+            continue
+        if allow is not None:
+            reason = (allow.group(1) or "").strip()
+            bucket = out.allow
+        else:
+            assert remove is not None  # one of the two matched, checked above
+            reason = (remove.group(1) or "").strip()
+            bucket = out.remove
+        for key in keys:
+            bucket.append(Decision(key=key, reason=reason, line_no=i, source_line=line))
+    return out
+
+
+def render_review(issues: Iterable[Issue], *, include_waived: bool = False) -> str:
+    """Write the editable report."""
+    items = [i for i in issues if include_waived or not i.waived]
+    lines = list(_HEADER)
+    if not items:
+        lines.append("# No issues to review — the project is clean.")
+        lines.append("")
+        return "\n".join(lines) + "\n"
+
+    for engine in _ENGINE_HEADINGS:
+        group = [i for i in items if i.engine == engine]
+        if not group:
+            continue
+        lines.append("")
+        heading = _ENGINE_HEADINGS.get(engine, engine)
+        lines.append(f"## {heading} — {len(group)} issue(s)")
+        if any(not i.waivable for i in group):
+            lines.append(
+                "## NOT EXCEPTABLE: a frozen implementation changes only via "
+                "`cdec check --automatic-exceptions locks --force`."
+            )
+        lines.append("")
+        for issue in sorted(group, key=lambda i: (i.rule, i.qualified_name, i.detail)):
+            lines.append(render_issue_line(issue))
+    lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def render_issue_line(issue: Issue) -> str:
+    """One issue, one line — the unit the patch parser operates on.
+
+    Everything discriminating goes on this single line (never a continuation),
+    because a reviewer marks lines, and a decision must be readable from the
+    line it is written on.
+    """
+    prefix = "- [ACCEPTED] " if issue.waived else "- "
+    loc = f" [{issue.location}]" if issue.location else ""
+    message = " ".join((issue.message or "").split())
+    return (
+        f"{prefix}[{issue.key}] [{issue.severity}] [{issue.rule}]{loc} "
+        f"{issue.qualified_name}: {message}"
+    )
+
+
+_HEADER = [
+    "# cdec review file",
+    "#",
+    "# One line per issue. To accept an issue as known-and-allowed, add [ALLOW]",
+    "# anywhere on its line; add a reason with [ALLOW: why this is acceptable].",
+    "# To withdraw an exception already granted, mark the line [REMOVE].",
+    "# Lines starting with # are ignored, so commenting one out cancels it.",
+    "#",
+    "# Then apply the file:",
+    "#     cdec exceptions patch --file <this file>",
+    "#",
+    "# Example:",
+    "#     - [ALLOW: legacy, tracked in ARCH-42] [V-1A2B3C4D] [error] [no-new-classes] ...",
+]