code-constraints 0.1.0__py3-none-any.whl

code_constraints/lint/engine.py

@@ -0,0 +1,179 @@
+"""Orchestrate: build RuleContext, dispatch to rules, collect violations.
+
+This is the whole of `cdec check`. Every gate the tool offers — configured
+architectural rules, source-tag conformance, implementation locks, the
+reference gate — arrives here as a `Rule`, so there is one run, one report, one
+exit code, and one place to grant an exception.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+from code_constraints.core.associations import resolve_association
+from code_constraints.core.model import DiffStatus, Package, Project
+
+from code_constraints.lint.baseline import Baseline
+from code_constraints.lint.report import Report
+from code_constraints.lint.rules.base import Rule, RuleContext, RuleSkipped, Violation
+
+
+@dataclass
+class SourceContext:
+    """Where the code and the config live.
+
+    Needed only by the rules that adapt an engine which re-reads the source
+    (tag conformance, locks) or loads a second model (the reference gate).
+    Rules that read the model alone never touch it, which is why it is optional.
+    """
+
+    source: Path | None = None
+    language: str = ""
+    config_dir: Path | None = None
+    reference_path: Path | None = None
+
+
+def run_checks(
+    project: Project,
+    rules: Iterable[Rule],
+    *,
+    has_diff: bool,
+    baseline: Baseline | None = None,
+    baseline_project: Project | None = None,
+    source_context: SourceContext | None = None,
+    bypass_locks: bool = False,
+    bypass_reason: str = "",
+) -> Report:
+    """Run every rule and return a `Report`.
+
+    `project` is the annotated `Project` when `has_diff` is True (i.e. the
+    output of `diff_projects`); when `has_diff` is False it's a raw parse and
+    every element has `DiffStatus.UNCHANGED`.
+
+    `baseline_project` is the OLD side of the diff (unannotated). Diff-scope
+    rules that need the previous element state (e.g. frozen-rules) read it via
+    `ctx.baseline_class_by_qn`.
+
+    `bypass_locks` moves lock violations out of the failing set into
+    `Report.bypassed`. They are still collected and still printed under an audit
+    banner, and the JSON report says so, so a pipeline can reject a bypassed run
+    on a protected branch rather than silently accepting it.
+    """
+    ctx = _build_context(project, has_diff, baseline_project, source_context)
+    raw: list[Violation] = []
+    skipped: list[tuple[str, str]] = []
+    for rule in rules:
+        if rule.scope == "diff" and not has_diff:
+            skipped.append((rule.rule_id, "no baseline available; diff-scope rule skipped"))
+            continue
+        try:
+            # Materialised inside the guard: `check` is a generator in most
+            # rules, so a RuleSkipped raised in its body only surfaces on
+            # iteration.
+            raw.extend(rule.check(ctx) or ())
+        except RuleSkipped as exc:
+            skipped.append((rule.rule_id, str(exc)))
+    if baseline is not None:
+        kept, suppressed = baseline.filter(raw)
+    else:
+        kept, suppressed = raw, []
+    bypassed: list[Violation] = []
+    if bypass_locks:
+        held = [v for v in kept if v.key_engine == "lock"]
+        if held:
+            kept = [v for v in kept if v.key_engine != "lock"]
+            bypassed = held
+    return Report(
+        violations=kept,
+        suppressed=suppressed,
+        skipped=skipped,
+        bypassed=bypassed,
+        bypass_reason=bypass_reason if bypassed else "",
+    )
+
+
+def _build_context(
+    project: Project,
+    has_diff: bool,
+    baseline_project: Project | None = None,
+    source_context: SourceContext | None = None,
+) -> RuleContext:
+    src = source_context or SourceContext()
+    ctx = RuleContext(
+        project=project,
+        has_diff=has_diff,
+        source=src.source,
+        language=src.language,
+        config_dir=src.config_dir,
+        reference_path=src.reference_path,
+    )
+    # Class index by qualified name.
+    for cls in project.iter_classes():
+        ctx.class_by_qn[cls.qualified_name] = cls
+    if baseline_project is not None:
+        for cls in baseline_project.iter_classes():
+            ctx.baseline_class_by_qn[cls.qualified_name] = cls
+    # Map class -> containing package.
+    for pkg in _walk_packages(project.packages):
+        for cls in pkg.classes:
+            ctx.class_to_package[cls.qualified_name] = pkg.qualified_name
+
+    # Outgoing references (attribute types + bases that resolve to project classes).
+    for cls in project.iter_classes():
+        if cls.status == DiffStatus.REMOVED:
+            continue
+        outgoing: set[str] = set()
+        for attr in cls.attributes:
+            if attr.status == DiffStatus.REMOVED:
+                continue
+            target_qn, _ = resolve_association(attr.type, project)
+            if target_qn:
+                outgoing.add(target_qn)
+        # Usage references: method parameter / return types and types used
+        # inside method bodies. Mirrors graph_model so the dangling rule and the
+        # diagram agree on what "references" a class.
+        for op in cls.operations:
+            if op.status == DiffStatus.REMOVED:
+                continue
+            for raw_type in (op.return_type, *(p.type for p in op.parameters)):
+                target_qn, _ = resolve_association(raw_type, project)
+                if target_qn:
+                    outgoing.add(target_qn)
+        for dep in cls.dependencies:
+            target_qn, _ = resolve_association(dep, project)
+            if target_qn:
+                outgoing.add(target_qn)
+        for base in cls.bases:
+            if base in ctx.class_by_qn:
+                outgoing.add(base)
+                continue
+            # Fall back to short-name match (mirrors graph_model logic).
+            short = base.split(".")[-1]
+            for qn in ctx.class_by_qn:
+                if qn.split(".")[-1] == short:
+                    outgoing.add(qn)
+                    break
+        ctx.outgoing_refs[cls.qualified_name] = outgoing
+        for tgt in outgoing:
+            ctx.incoming_refs.setdefault(tgt, set()).add(cls.qualified_name)
+
+    # Aggregate to package level.
+    for src_qn, tgt_qns in ctx.outgoing_refs.items():
+        src_pkg = ctx.class_to_package.get(src_qn)
+        if src_pkg is None:
+            continue
+        bucket = ctx.outgoing_pkg_refs.setdefault(src_pkg, set())
+        for tgt_qn in tgt_qns:
+            tgt_pkg = ctx.class_to_package.get(tgt_qn)
+            if tgt_pkg is None or tgt_pkg == src_pkg:
+                continue
+            bucket.add(tgt_pkg)
+    return ctx
+
+
+def _walk_packages(packages: list[Package]):
+    for pkg in packages:
+        yield pkg
+        yield from _walk_packages(pkg.sub_packages)

code_constraints/lint/pipeline.py

@@ -0,0 +1,108 @@
+"""Parse the source and resolve the baseline — the front half of `cdec check`.
+
+Extracted so that anything needing the *same* issues `cdec check` would report
+computes them the same way. That matters for the review workflow: a key is only
+useful if the command that grants a waiver sees exactly the issues the command
+that printed the report saw, which means resolving the baseline identically
+(same reference file, same `--base-ref`, same diff).
+
+Pure functions raising `PipelineError`; the CLI adapts to typer, other callers
+adapt as they like.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from code_constraints.core.diff import diff_projects
+from code_constraints.core.model import SUPPORTED_LANGUAGES, Project
+from code_constraints.lint.config import REFERENCE_FILENAME
+
+SUPPORTED_LANGS = SUPPORTED_LANGUAGES
+
+
+class PipelineError(RuntimeError):
+    """Raised when the source or the baseline can't be prepared."""
+
+
+def parse_source(path: Path, lang: str) -> Project:
+    if lang == "python":
+        from code_constraints.python import parse_project
+    elif lang == "csharp":
+        from code_constraints.csharp import parse_project
+    elif lang == "typescript":
+        from code_constraints.typescript import parse_project
+    elif lang == "svelte":
+        from code_constraints.svelte import parse_project
+    elif lang == "odin":
+        from code_constraints.odin import parse_project
+    elif lang == "lua":
+        from code_constraints.lua import parse_project
+    elif lang == "julia":
+        from code_constraints.julia import parse_project
+    else:
+        raise PipelineError(f"unsupported language: {lang}")
+    return parse_project(path)
+
+
+def checkout_revision(repo: Any, ref: str, dest: Path) -> Path:
+    """Copy the tree at `ref` into `dest` (avoids touching the working tree)."""
+    dest.mkdir(parents=True, exist_ok=True)
+    commit = repo.commit(ref)
+    archive = dest.with_suffix(".tar")
+    with archive.open("wb") as fh:
+        repo.archive(fh, treeish=commit.hexsha, format="tar")
+    shutil.unpack_archive(str(archive), str(dest), format="tar")
+    archive.unlink()
+    return dest
+
+
+def resolve_baseline(
+    *,
+    head_proj: Project,
+    lang: str,
+    config_dir: Path,
+    explicit_reference: Path | None = None,
+    explicit_base_ref: str | None = None,
+    repo_path: Path = Path("."),
+    default_reference: Path | None = None,
+) -> tuple[Project, bool, Project | None]:
+    """Returns (project_for_rules, has_diff, baseline_project).
+
+    When no baseline is available, returns the head project unchanged with
+    has_diff=False and a None baseline, so diff-scope rules get skipped rather
+    than silently passing.
+    """
+    if explicit_base_ref:
+        from git import Repo
+
+        git_repo = Repo(str(Path(repo_path).resolve()))
+        with tempfile.TemporaryDirectory(prefix="cdec-check-") as tmp:
+            base_dir = checkout_revision(git_repo, explicit_base_ref, Path(tmp) / "base")
+            base_proj = parse_source(base_dir, lang)
+            try:
+                annotated = diff_projects(base_proj, head_proj)
+            except ValueError as exc:
+                raise PipelineError(str(exc)) from exc
+        return annotated, True, base_proj
+
+    ref_path: Path | None = explicit_reference or default_reference
+    if ref_path is None:
+        candidate = config_dir / REFERENCE_FILENAME
+        if candidate.is_file():
+            ref_path = candidate
+
+    if ref_path and ref_path.is_file():
+        from code_constraints.core.model_io import load_model
+
+        base_proj = load_model(ref_path)
+        try:
+            annotated = diff_projects(base_proj, head_proj)
+        except ValueError as exc:
+            raise PipelineError(str(exc)) from exc
+        return annotated, True, base_proj
+
+    return head_proj, False, None

code_constraints/lint/report.py

@@ -0,0 +1,151 @@
+"""Format the `cdec check` output as human-readable text or JSON."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from code_constraints.lint.rules.base import Severity, Violation
+
+
+@dataclass
+class Report:
+    violations: list[Violation] = field(default_factory=list)
+    suppressed: list[Violation] = field(default_factory=list)
+    # Rules that couldn't run (e.g. a diff-scope rule with no baseline, or a
+    # language with no AST fingerprinter). Reported, never swallowed.
+    skipped: list[tuple[str, str]] = field(default_factory=list)
+    # Lock violations held back by `--bypass-locks`: reported under an audit
+    # banner and flagged in JSON, but not counted as failures.
+    bypassed: list[Violation] = field(default_factory=list)
+    bypass_reason: str = ""
+
+    def has_failures(self, fail_on: Severity) -> bool:
+        if fail_on == Severity.OFF:
+            return False
+        if fail_on == Severity.WARNING:
+            return any(v.severity in (Severity.ERROR, Severity.WARNING) for v in self.violations)
+        # default: error
+        return any(v.severity == Severity.ERROR for v in self.violations)
+
+    def to_human(self) -> str:
+        lines: list[str] = []
+        if self.bypassed:
+            lines.extend(self._bypass_banner())
+        if not self.violations:
+            lines.append("cdec check: no violations.")
+        else:
+            lines.extend(self._violation_lines())
+        if self.suppressed:
+            lines.append(
+                f"({len(self.suppressed)} violation(s) silenced by an exception / ignore.)"
+            )
+        for rule_id, reason in self.skipped:
+            lines.append(f"[skipped] {rule_id}: {reason}")
+        total_errors = sum(1 for v in self.violations if v.severity == Severity.ERROR)
+        total_warnings = sum(1 for v in self.violations if v.severity == Severity.WARNING)
+        lines.append(f"Summary: {total_errors} error(s), {total_warnings} warning(s).")
+        lines.extend(self._guidance())
+        return "\n".join(lines) + "\n"
+
+    def _violation_lines(self) -> list[str]:
+        lines: list[str] = []
+        by_rule: dict[str, list[Violation]] = {}
+        for v in self.violations:
+            by_rule.setdefault(v.rule_id, []).append(v)
+        for rule_id in sorted(by_rule):
+            group = by_rule[rule_id]
+            lines.append(f"[{rule_id}] ({group[0].severity.value})")
+            if not group[0].waivable:
+                lines.append(
+                    "  NOT EXCEPTABLE: a frozen implementation changes only via "
+                    "`cdec check --automatic-exceptions locks --force`."
+                )
+            for v in group:
+                loc = ""
+                if v.location is not None:
+                    loc = f" — {v.location.file}:{v.location.start_line}"
+                msg_lines = (v.message or "").splitlines() or [""]
+                lines.append(f"  - [{v.key()}] {v.qualified_name}{loc}: {msg_lines[0]}")
+                for cont in msg_lines[1:]:
+                    lines.append(f"      {cont}" if cont else "")
+            lines.append("")
+        return lines
+
+    def _bypass_banner(self) -> list[str]:
+        lines = [
+            "!" * 72,
+            "cdec check: LOCKS BYPASSED — frozen implementations were NOT enforced.",
+        ]
+        if self.bypass_reason:
+            lines.append(f"          reason: {self.bypass_reason}")
+        lines.append(f"          {len(self.bypassed)} lock violation(s) suppressed:")
+        for v in sorted(self.bypassed, key=lambda x: x.qualified_name):
+            lines.append(f"            - [{v.key()}] {v.qualified_name}")
+        lines.append("!" * 72)
+        lines.append("")
+        return lines
+
+    def _guidance(self) -> list[str]:
+        """Commented on purpose: this text lands inside `--log-out` files that
+        are handed straight back to `cdec exceptions patch`, and an uncommented
+        `[ALLOW]` in the guidance would read as a decision."""
+        example = next((v.key() for v in self.violations if v.waivable), "")
+        if not example:
+            return []
+        # Quote a key that is actually in this report, so the line can be copied
+        # rather than adapted.
+        return [
+            "# To accept any of these as known-and-allowed, quote its key:\n"
+            f"#   cdec exceptions allow {example} --reason \"why\"\n"
+            "# Or mark them in bulk: add [ALLOW] to a line of this report and\n"
+            "# apply it with `cdec exceptions patch --file <report>`."
+        ]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "violations": [_v_to_json(v) for v in self.violations],
+            "suppressed": [_v_to_json(v) for v in self.suppressed],
+            "bypassed": [_v_to_json(v) for v in self.bypassed],
+            "skipped": [{"rule_id": r, "reason": reason} for r, reason in self.skipped],
+            "summary": {
+                "errors": sum(1 for v in self.violations if v.severity == Severity.ERROR),
+                "warnings": sum(1 for v in self.violations if v.severity == Severity.WARNING),
+                "suppressed": len(self.suppressed),
+                "skipped": len(self.skipped),
+                # Kept as a top-level flag so a pipeline can reject a bypassed
+                # run on a protected branch with one JSON lookup.
+                "bypassed": bool(self.bypassed),
+                "bypass_reason": self.bypass_reason,
+            },
+        }
+
+    def write_json(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("w", encoding="utf-8") as fh:
+            json.dump(self.to_json(), fh, indent=2, sort_keys=True)
+
+
+def _v_to_json(v: Violation) -> dict[str, Any]:
+    out: dict[str, Any] = {
+        "key": v.key(),
+        "rule_id": v.rule_id,
+        "engine": v.key_engine,
+        "severity": v.severity.value,
+        "qualified_name": v.qualified_name,
+        "message": v.message,
+        "waivable": v.waivable,
+    }
+    if v.key_rule:
+        out["rule"] = v.key_rule
+    if v.signature:
+        out["signature"] = v.signature
+    if v.location is not None:
+        out["location"] = {
+            "file": v.location.file,
+            "start_line": v.location.start_line,
+            "end_line": v.location.end_line,
+        }
+    return out

code_constraints/lint/rules/__init__.py

@@ -0,0 +1,50 @@
+"""Rule registry. Importing this package side-effect-registers every rule."""
+
+from __future__ import annotations
+
+from typing import Type
+
+from code_constraints.lint.rules.base import Rule
+
+_REGISTRY: dict[str, Type[Rule]] = {}
+
+
+def register(type_name: str):
+    def decorator(cls: Type[Rule]) -> Type[Rule]:
+        cls.type_name = type_name
+        _REGISTRY[type_name] = cls
+        return cls
+
+    return decorator
+
+
+def get_rule_class(type_name: str) -> Type[Rule] | None:
+    return _REGISTRY.get(type_name)
+
+
+def known_rule_types() -> list[str]:
+    return sorted(_REGISTRY.keys())
+
+
+# Side-effect imports — every rule module must be imported here so its
+# @register decorator runs.
+from code_constraints.lint.rules import (  # noqa: E402, F401
+    no_new_classes,
+    no_removed_classes,
+    dangling_classes,
+    frozen_members,
+    frozen_rules,
+    forbidden_references,
+    forbidden_package_references,
+    layer_dependencies,
+    subclass_naming,
+    cyclic_package_dependencies,
+    max_class_fanout,
+    # Adapters for the three decoupled engines that used to be separate
+    # commands. They import their engine lazily and translate its results into
+    # `Violation`s, so the engines stay independent packages while the user sees
+    # one file of rules and one `cdec check`.
+    tag_conformance,
+    implementation_locks,
+    reference_architecture,
+)

code_constraints/lint/rules/base.py

@@ -0,0 +1,200 @@
+"""Rule base class, Violation dataclass, RuleContext."""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Iterable
+
+from code_constraints.core.keys import make_key
+from code_constraints.core.model import Class, DiffStatus, Project, SourceLocation
+
+
+class RuleSkipped(RuntimeError):
+    """Raised by a rule that cannot run at all in this project.
+
+    Recorded in `Report.skipped` rather than swallowed: a rule that quietly
+    checks nothing looks exactly like a rule that passed, and that is how a
+    guardrail stops guarding without anybody noticing.
+    """
+
+
+class Severity(str, Enum):
+    ERROR = "error"
+    WARNING = "warning"
+    OFF = "off"
+
+
+@dataclass
+class Violation:
+    rule_id: str
+    severity: Severity
+    qualified_name: str
+    message: str
+    location: SourceLocation | None = None
+    # `signature` is used by the exception fingerprint so that frozen-members
+    # violations on the same class can be distinguished by member.
+    signature: str | None = None
+    # --- key identity -------------------------------------------------------
+    # A key names the *issue*, not the config entry that surfaced it. Rules that
+    # adapt one of the decoupled engines (tag conformance, locks, the reference
+    # gate) therefore key their violations under that engine's own identity, so
+    # renaming a `rules.yaml` entry never invalidates a granted exception and a
+    # key recorded before the CLI was unified still resolves. Native rules leave
+    # these unset and key as `check`/`rule_id`, exactly as they always have.
+    key_engine: str = "check"
+    key_rule: str | None = None
+    # False for issues that must not be accepted as exceptions — locks, whose
+    # escape hatch is a privileged re-baseline instead.
+    waivable: bool = True
+
+    def fingerprint(self) -> tuple[str, str, str]:
+        return (self.rule_id, self.qualified_name, self.signature or "")
+
+    def key(self) -> str:
+        """Stable review key. Derived from the issue identity, so it never moves
+        when the file does — see `code_constraints.core.keys`."""
+        return make_key(
+            self.key_engine,
+            self.key_rule or self.rule_id,
+            self.qualified_name,
+            self.signature or "",
+        )
+
+
+@dataclass
+class RuleContext:
+    """Per-run context, built once and passed to every rule.
+
+    The annotated project carries DiffStatus values when a baseline was used;
+    `has_diff` is False when running in snapshot-only mode (no baseline).
+    """
+    project: Project
+    has_diff: bool
+    # --- source-level context ----------------------------------------------
+    # Most rules read only the model. The rules that adapt an engine which
+    # re-parses bodies (tag conformance, locks) or loads another model (the
+    # reference gate) need to know where the code and the config live. The
+    # engines themselves stay independent packages: these rules are adapters
+    # that import them lazily and translate their results into `Violation`s.
+    source: Path | None = None
+    language: str = ""
+    config_dir: Path | None = None
+    reference_path: Path | None = None
+    # Cached: qualified_name -> set of qualified names that reference it
+    # (attribute type or base class).
+    incoming_refs: dict[str, set[str]] = field(default_factory=dict)
+    # qualified_name -> set of qualified names this class references.
+    outgoing_refs: dict[str, set[str]] = field(default_factory=dict)
+    # package qualified_name -> set of package qualified names it references.
+    outgoing_pkg_refs: dict[str, set[str]] = field(default_factory=dict)
+    # class qualified_name -> Class
+    class_by_qn: dict[str, Class] = field(default_factory=dict)
+    # class qualified_name -> containing package qualified_name
+    class_to_package: dict[str, str] = field(default_factory=dict)
+    # Baseline (OLD side) classes by qualified name; populated only when a
+    # baseline project was supplied. Used by diff-scope rules that need the
+    # *previous* element state (e.g. frozen-rules), since the annotated
+    # `project` carries the NEW rule lists, not the old ones.
+    baseline_class_by_qn: dict[str, Class] = field(default_factory=dict)
+
+
+def match_any_glob(name: str, patterns: Iterable[str]) -> bool:
+    """Match `name` against any of the patterns. Patterns use shell glob
+    semantics with `.` treated as a normal character (so `foo.bar.*` matches
+    `foo.bar.baz` and `foo.**` matches every descendant)."""
+    for p in patterns:
+        # Treat `**` as matching across dot-separated segments. `fnmatch` already
+        # treats `*` as any char including `.`, so `foo.**` collapses to
+        # `foo.*` for matching purposes — which is what we want.
+        pat = p.replace("**", "*")
+        if fnmatch.fnmatchcase(name, pat):
+            return True
+    return False
+
+
+class Rule:
+    """Subclasses are instantiated once per `rules.yaml` entry."""
+
+    type_name: str = ""  # set by @register
+    #: Scope used when the entry doesn't say. Rules that compare against a
+    #: baseline override this to "diff".
+    default_scope: str = "snapshot"
+    #: True when the rule can record the current state as the new approved
+    #: baseline via `accept_current_state` (locks, the reference gate).
+    supports_auto_accept: bool = False
+
+    def __init__(
+        self,
+        rule_id: str,
+        severity: Severity,
+        scope: str,
+        message: str,
+        ignore: list[str],
+        options: dict[str, Any],
+    ) -> None:
+        self.rule_id = rule_id
+        self.severity = severity
+        self.scope = scope  # "diff" | "snapshot"
+        self.message_template = message
+        self.ignore = list(ignore or [])
+        self.options = options
+
+    # ---- helpers shared by subclasses ----
+    def is_ignored(self, qualified_name: str) -> bool:
+        return match_any_glob(qualified_name, self.ignore)
+
+    def message_for(self, **fmt: Any) -> str:
+        if not self.message_template:
+            return ""
+        try:
+            return self.message_template.format(**fmt)
+        except (KeyError, IndexError):
+            return self.message_template
+
+    def emit(
+        self,
+        qualified_name: str,
+        message: str,
+        location: SourceLocation | None = None,
+        signature: str | None = None,
+    ) -> Violation:
+        return Violation(
+            rule_id=self.rule_id,
+            severity=self.severity,
+            qualified_name=qualified_name,
+            message=message or self.message_template,
+            location=location,
+            signature=signature,
+        )
+
+    # ---- override hooks ----
+    def check(self, ctx: RuleContext) -> Iterable[Violation]:
+        raise NotImplementedError
+
+    def accept_current_state(self, ctx: RuleContext, *, force: bool = False) -> list[str]:
+        """Record the code as it stands now as this rule's approved baseline.
+
+        Called by `cdec check --automatic-exceptions`. Rules whose issues are
+        grandfathered through the `exceptions:` list don't implement this — it
+        exists for the two rules that carry a baseline of their own: the lock
+        ledger and the reference snapshot. Returns lines describing what
+        changed, for the command to print.
+        """
+        return []
+
+
+def changed_classes(ctx: RuleContext, only_status: DiffStatus | None = None) -> Iterable[Class]:
+    """Yield classes whose status matches `only_status`; or all non-unchanged
+    classes when `only_status` is None. Skips the iteration entirely when
+    the context isn't from a diff."""
+    if not ctx.has_diff:
+        return
+    for cls in ctx.project.iter_classes():
+        if only_status is None:
+            if cls.status != DiffStatus.UNCHANGED:
+                yield cls
+        elif cls.status == only_status:
+            yield cls