code-constraints 0.1.0__py3-none-any.whl

code_constraints/lock/engine.py

@@ -0,0 +1,395 @@
+"""The implementation-freeze engine (Engine C).
+
+Reached through the `implementation-locks` rule type in `.cdec/rules.yaml`, so
+freezing a body is configured, reported and gated by the same `cdec check` as
+every other law. The engine itself stays an independent package with its own
+result types; the rule is a thin adapter.
+
+Two operations, both driven off the same collected fingerprints:
+
+  * `check_locks`  — verify every ledger entry still matches the source.
+  * `update_locks` — (re-)record digests; the lead-gated re-baseline path.
+
+Locks are declared two ways, and both are honoured:
+
+  * a `@locked` / `[Locked]` tag on the element — the primary, in-code route;
+  * `targets:` globs on the `implementation-locks` rule in `.cdec/rules.yaml` —
+    for freezing code that isn't practical to decorate, e.g. a whole test
+    package.
+
+The engine never consults the diff, the reference XMI, or the baseline: a lock
+is an absolute statement about the current source, not a drift signal.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Sequence
+
+from code_constraints.lock.model import (
+    LOCK_RULE,
+    LockEntry,
+    LockReport,
+    LockTarget,
+    LockViolation,
+    match_any_glob,
+)
+from code_constraints.lock.store import now_stamp
+
+BYPASS_ENV = "CDEC_LOCK_BYPASS"
+BYPASS_REASON_ENV = "CDEC_LOCK_BYPASS_REASON"
+
+
+class UnsupportedLockLanguage(ValueError):
+    """Raised for a language with no fingerprinter."""
+
+
+@dataclass
+class LockOptions:
+    include_docstrings: bool = False
+    patterns: list[str] = field(default_factory=list)
+
+
+@dataclass
+class UpdateResult:
+    added: list[LockEntry] = field(default_factory=list)
+    updated: list[LockEntry] = field(default_factory=list)
+    removed: list[LockEntry] = field(default_factory=list)
+    unchanged: int = 0
+    # Entries whose digest drifted but that `--force` was not given for.
+    blocked: list[LockViolation] = field(default_factory=list)
+    # Entries still in the ledger whose element is gone or has lost its tag, and
+    # which were left in place because `--force` was not given. Reporting these
+    # matters: without them an unforced run over a tampered-with tree would
+    # cheerfully print "nothing to do" while the lock is being violated.
+    stale: list[LockEntry] = field(default_factory=list)
+
+    @property
+    def changed(self) -> bool:
+        return bool(self.added or self.updated or self.removed)
+
+    @property
+    def clean(self) -> bool:
+        return not self.blocked and not self.stale
+
+
+def collect_targets(
+    root: str | Path, lang: str, options: LockOptions | None = None
+) -> list[LockTarget]:
+    """Fingerprint every lockable element under `root`."""
+    opts = options or LockOptions()
+    if lang == "python":
+        from code_constraints.python.fingerprint import collect_lockables
+    elif lang == "csharp":
+        from code_constraints.csharp.fingerprint import collect_lockables
+    elif lang == "odin":
+        from code_constraints.odin.fingerprint import collect_lockables
+    elif lang == "lua":
+        from code_constraints.lua.fingerprint import collect_lockables
+    elif lang == "julia":
+        from code_constraints.julia.fingerprint import collect_lockables
+    else:
+        raise UnsupportedLockLanguage(
+            f"implementation locks support python, csharp, odin, lua and julia; "
+            f"got {lang!r}. "
+            f"Implementation freezing needs an AST fingerprinter for the language."
+        )
+    return collect_lockables(root, include_docstrings=opts.include_docstrings)
+
+
+def is_locked_target(target: LockTarget, patterns: Sequence[str]) -> bool:
+    """A target is under lock when it carries the tag or matches a config glob."""
+    return target.declared or match_any_glob(target.target, patterns)
+
+
+def check_locks(
+    root: str | Path,
+    lang: str,
+    entries: dict[str, LockEntry],
+    options: LockOptions | None = None,
+    *,
+    bypass: bool = False,
+    bypass_reason: str = "",
+) -> LockReport:
+    """Verify the ledger against the current source.
+
+    Five failure modes, all of them real ways a frozen implementation stops
+    being frozen:
+
+      * `changed`       — the digest moved: the body was edited.
+      * `missing`       — tagged `@locked` but never baselined, so nothing is
+                          actually being verified.
+      * `removed`       — the element is gone (deleting it is a mutation too).
+      * `unlocked`      — the element survives but the tag was deleted; without
+                          this check, escaping a lock is a one-line edit.
+      * `algo-mismatch` — the digest was produced by a different algorithm
+                          version, so the comparison is meaningless. Reported
+                          separately so an upgrade never looks like tampering.
+    """
+    opts = options or LockOptions()
+    env_bypass, env_reason = _env_bypass()
+    bypass = bypass or env_bypass
+    bypass_reason = bypass_reason or env_reason
+
+    targets = collect_targets(root, lang, opts)
+    by_name = {t.target: t for t in targets}
+    violations: list[LockViolation] = []
+
+    for name, entry in sorted(entries.items()):
+        target = by_name.get(name)
+        if target is None:
+            violations.append(
+                LockViolation(
+                    kind="removed",
+                    target=name,
+                    file=entry.file,
+                    message=(
+                        f"'{name}' is locked in the ledger but no longer exists in the "
+                        f"source. Deleting or renaming a frozen element is a change: "
+                        f"restore it, or have a lead drop the lock with "
+                        f"`cdec check --automatic-exceptions locks --force`."
+                        + (f"\nLock reason: {entry.reason}" if entry.reason else "")
+                    ),
+                    reason=entry.reason,
+                    owner=entry.locked_by,
+                )
+            )
+            continue
+
+        if entry.algo and target.algo != entry.algo:
+            violations.append(
+                LockViolation(
+                    kind="algo-mismatch",
+                    target=name,
+                    file=target.file,
+                    line=target.line,
+                    expected=entry.algo,
+                    actual=target.algo,
+                    message=(
+                        f"'{name}' was baselined with digest algorithm "
+                        f"'{entry.algo}' but this code-constraints computes "
+                        f"'{target.algo}'. The digests are not comparable — "
+                        f"re-baseline with "
+                        f"`cdec check --automatic-exceptions locks --force` after "
+                        f"confirming the implementation is unchanged."
+                    ),
+                )
+            )
+            continue
+
+        if target.digest != entry.digest:
+            violations.append(
+                LockViolation(
+                    kind="changed",
+                    target=name,
+                    file=target.file,
+                    line=target.line,
+                    expected=entry.digest,
+                    actual=target.digest,
+                    message=_changed_message(name, entry, target),
+                    reason=entry.reason or target.reason,
+                    owner=entry.locked_by or target.owner,
+                )
+            )
+            continue
+
+        if not entry.via_pattern and not is_locked_target(target, opts.patterns):
+            violations.append(
+                LockViolation(
+                    kind="unlocked",
+                    target=name,
+                    file=target.file,
+                    line=target.line,
+                    message=(
+                        f"'{name}' is recorded in the lock ledger but its @{LOCK_RULE} "
+                        f"tag is gone. Removing the tag does not remove the lock — "
+                        f"restore it, or have a lead run "
+                        f"`cdec check --automatic-exceptions locks --force`."
+                    ),
+                    reason=entry.reason,
+                    owner=entry.locked_by,
+                )
+            )
+
+    declared = 0
+    for target in targets:
+        if not is_locked_target(target, opts.patterns):
+            continue
+        declared += 1
+        if target.target in entries:
+            continue
+        violations.append(
+            LockViolation(
+                kind="missing",
+                target=target.target,
+                file=target.file,
+                line=target.line,
+                actual=target.digest,
+                message=(
+                    f"'{target.target}' is tagged @{LOCK_RULE} but has no baseline "
+                    f"digest, so nothing is being verified. Record it with "
+                    f"`cdec check --automatic-exceptions locks`."
+                ),
+                reason=target.reason,
+                owner=target.owner,
+            )
+        )
+
+    return LockReport(
+        violations=violations,
+        checked=len(entries),
+        declared=declared,
+        bypassed=bypass,
+        bypass_reason=bypass_reason,
+    )
+
+
+def update_locks(
+    root: str | Path,
+    lang: str,
+    entries: dict[str, LockEntry],
+    options: LockOptions | None = None,
+    *,
+    only: Sequence[str] = (),
+    force: bool = False,
+    prune: bool = True,
+    reason: str = "",
+    owner: str = "",
+) -> tuple[dict[str, LockEntry], UpdateResult]:
+    """Recompute digests and return the new ledger plus a summary of changes.
+
+    Adding a lock is cheap; *re-baselining a drifted one is the privileged
+    operation*, so an existing entry whose digest moved is only rewritten with
+    `force=True`. That keeps `cdec check --automatic-exceptions locks` safe to
+    run by anyone — without `--force` it can never erase evidence of a change —
+    while the `--force` run shows up as a reviewable diff on the `locks:`
+    section of `.cdec/rules.yaml`.
+
+    `only` restricts the operation to matching targets (globs). `prune` drops
+    ledger entries whose element no longer exists or is no longer locked.
+    """
+    opts = options or LockOptions()
+    targets = collect_targets(root, lang, opts)
+    by_name = {t.target: t for t in targets}
+    result = UpdateResult()
+    out = dict(entries)
+    stamp = now_stamp()
+    who = owner or _default_owner()
+
+    for target in targets:
+        if not is_locked_target(target, opts.patterns):
+            continue
+        if only and not match_any_glob(target.target, only):
+            continue
+        existing = out.get(target.target)
+        via_pattern = not target.declared
+        if existing is None:
+            entry = _entry_for(target, stamp, who, reason, via_pattern)
+            out[target.target] = entry
+            result.added.append(entry)
+        elif existing.digest == target.digest and existing.algo == target.algo:
+            result.unchanged += 1
+        elif force:
+            entry = _entry_for(
+                target, stamp, who, reason or existing.reason, via_pattern
+            )
+            out[target.target] = entry
+            result.updated.append(entry)
+        else:
+            result.blocked.append(
+                LockViolation(
+                    kind="changed",
+                    target=target.target,
+                    file=target.file,
+                    line=target.line,
+                    expected=existing.digest,
+                    actual=target.digest,
+                    message=(
+                        f"'{target.target}' has drifted from its baseline. Re-baselining "
+                        f"a frozen implementation requires --force (and a lead's "
+                        f"approval on the `locks:` diff in .cdec/rules.yaml)."
+                    ),
+                    reason=existing.reason,
+                    owner=existing.locked_by,
+                )
+            )
+
+    for name, entry in list(out.items()):
+        if only and not match_any_glob(name, only):
+            continue
+        target = by_name.get(name)
+        if target is not None and is_locked_target(target, opts.patterns):
+            continue
+        # The element is gone or its tag was deleted. Dropping the ledger entry
+        # is privileged: an unforced run leaves it in place so `cdec check` keeps
+        # reporting it, rather than letting anyone unlock by deleting a decorator
+        # and re-running the baselining command.
+        if prune and force:
+            del out[name]
+            result.removed.append(entry)
+        else:
+            result.stale.append(entry)
+
+    return out, result
+
+
+def resolve_entries_for_removal(
+    entries: dict[str, LockEntry], patterns: Sequence[str]
+) -> list[LockEntry]:
+    return [e for name, e in sorted(entries.items()) if match_any_glob(name, patterns)]
+
+
+# ---------- internals ----------
+
+def _entry_for(
+    target: LockTarget, stamp: str, who: str, reason: str, via_pattern: bool
+) -> LockEntry:
+    return LockEntry(
+        target=target.target,
+        kind=target.kind,
+        digest=target.digest,
+        algo=target.algo,
+        file=target.file,
+        locked_at=stamp,
+        locked_by=who,
+        reason=reason or target.reason,
+        via_pattern=via_pattern,
+    )
+
+
+def _changed_message(name: str, entry: LockEntry, target: LockTarget) -> str:
+    lines = [
+        f"'{name}' is a frozen {entry.kind or target.kind} and its implementation "
+        f"changed.",
+    ]
+    if entry.reason:
+        lines.append(f"Lock reason: {entry.reason}")
+    if entry.locked_by:
+        lines.append(f"Locked by: {entry.locked_by}" + (f" on {entry.locked_at}" if entry.locked_at else ""))
+    lines.append(
+        "Revert the change, or ask a lead to approve a re-baseline with "
+        "`cdec check --automatic-exceptions locks --force`."
+    )
+    return "\n".join(lines)
+
+
+def _env_bypass() -> tuple[bool, str]:
+    raw = os.environ.get(BYPASS_ENV, "").strip().lower()
+    enabled = raw in ("1", "true", "yes", "on")
+    return enabled, os.environ.get(BYPASS_REASON_ENV, "").strip() if enabled else ""
+
+
+def _default_owner() -> str:
+    for var in ("CDEC_LOCK_OWNER", "GIT_AUTHOR_NAME", "USERNAME", "USER"):
+        value = os.environ.get(var, "").strip()
+        if value:
+            return value
+    return ""
+
+
+def iter_locked(targets: Iterable[LockTarget], patterns: Sequence[str]):
+    for target in targets:
+        if is_locked_target(target, patterns):
+            yield target

code_constraints/lock/model.py

@@ -0,0 +1,235 @@
+"""Result types for the implementation-freeze engine (Engine C).
+
+Deliberately separate from `code_constraints.lint.Violation` and
+`code_constraints.enforce.Finding`: the
+three engines are decoupled by design and share only the rule *catalog*.
+
+  * Engine A (configured rules)  — did the architectural *intent* drift?
+  * Engine B (tag conformance)   — does the code *obey* the tags right now?
+  * Engine C (locks)             — did a frozen implementation *change at all*?
+
+All three run inside `cdec check`, as rule types in `.cdec/rules.yaml`; they
+share only the rule catalog. Engine C is the only one that cares about the exact
+contents of a body. It compares an AST-derived digest against the digest
+recorded in the `locks:` section of `rules.yaml`, so reformatting, comment edits
+and moving the element around a file never trip a lock, while any semantic edit
+does.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Literal
+
+from code_constraints.core.keys import make_key
+
+# Catalog id of the tag that declares a lock. Never hard-code this elsewhere —
+# import it (or look it up via `code_constraints.core.rules.by_id`).
+LOCK_RULE = "locked"
+
+TargetKind = Literal["class", "method", "function"]
+ViolationKind = Literal["changed", "missing", "removed", "unlocked", "algo-mismatch"]
+
+
+@dataclass
+class LockTarget:
+    """A lockable element discovered in the current source tree.
+
+    Produced by the per-language fingerprinters (`code_constraints/{python,csharp}
+    .fingerprint`). `digest` is over the *normalised* AST: position-independent,
+    comment-free, and (by default) docstring-free.
+
+    Overloads / same-named siblings in one scope collapse into a single target
+    whose digest covers the whole group, so adding an overload to a locked
+    method is itself a lock violation and no ordinal disambiguator is needed.
+    """
+
+    target: str  # dotted identity, e.g. "orders.Receipt.formatted"
+    kind: TargetKind
+    digest: str  # hex sha256 of the canonical AST serialisation
+    algo: str  # digest algorithm id, e.g. "py-ast/1"
+    file: str = ""
+    line: int = 0
+    declared: bool = False  # carries an explicit @locked / [Locked] tag
+    params: dict[str, str] = field(default_factory=dict)  # tag kwargs (reason/owner)
+
+    @property
+    def reason(self) -> str:
+        return self._param("reason")
+
+    @property
+    def owner(self) -> str:
+        return self._param("owner")
+
+    def _param(self, name: str) -> str:
+        """Tag params are case-insensitive: Python writes `reason=`, C# writes
+        `Reason =`, and both land in the same catalog param."""
+        for key, value in self.params.items():
+            if key.lower() == name:
+                return _unquote(value)
+        return ""
+
+
+@dataclass
+class LockEntry:
+    """One recorded lock in the `locks:` section of `.cdec/rules.yaml`."""
+
+    target: str
+    kind: str
+    digest: str
+    algo: str
+    file: str = ""
+    locked_at: str = ""
+    locked_by: str = ""
+    reason: str = ""
+    # True when the lock came from a rule `targets:` glob rather than a tag.
+    # Glob-locked entries are exempt from the "tag was removed" check.
+    via_pattern: bool = False
+
+
+@dataclass
+class LockViolation:
+    kind: ViolationKind
+    target: str
+    message: str
+    file: str = ""
+    line: int = 0
+    expected: str = ""
+    actual: str = ""
+    reason: str = ""
+    owner: str = ""
+
+    def fingerprint(self) -> tuple[str, str]:
+        return (self.kind, self.target)
+
+    def key(self) -> str:
+        """Stable review key (`L-…`) — see `code_constraints.core.keys`.
+
+        Locks are the one thing `cdec exceptions` will not accept: a changed
+        implementation is approved with
+        `cdec check --automatic-exceptions locks --force`, a privileged,
+        reviewable act. The key exists anyway so reports are uniform and an
+        agent can name the lock it means.
+        """
+        return make_key("lock", self.kind, self.target, "")
+
+
+@dataclass
+class LockReport:
+    violations: list[LockViolation] = field(default_factory=list)
+    checked: int = 0  # number of lockfile entries verified
+    declared: int = 0  # number of @locked elements found in source
+    bypassed: bool = False
+    bypass_reason: str = ""
+
+    @property
+    def ok(self) -> bool:
+        """True when nothing blocks the build. A bypassed run is never a
+        failure — but `bypassed` stays in the report so CI can reject it."""
+        return self.bypassed or not self.violations
+
+
+# ---------- rendering ----------
+
+_KIND_HEADLINE: dict[str, str] = {
+    "changed": "frozen implementation changed",
+    "missing": "declared @locked but not baselined",
+    "removed": "frozen element no longer exists",
+    "unlocked": "@locked tag was removed",
+    "algo-mismatch": "digest algorithm changed",
+}
+
+
+def format_report(report: LockReport) -> str:
+    """Standalone rendering of a lock report.
+
+    `cdec check` renders lock violations through the unified report instead;
+    this stays for library callers and for the MCP tools that surface the lock
+    ledger on its own.
+    """
+    if report.bypassed:
+        head = [
+            "!" * 72,
+            "LOCKS BYPASSED — frozen implementations were NOT verified.",
+        ]
+        if report.bypass_reason:
+            head.append(f"          reason: {report.bypass_reason}")
+        head.append(
+            f"          {len(report.violations)} lock violation(s) suppressed."
+        )
+        head.append("!" * 72)
+        return "\n".join(head) + "\n"
+    if not report.violations:
+        return (
+            f"{report.checked} locked element(s) verified, no changes.\n"
+        )
+
+    by_kind: dict[str, list[LockViolation]] = {}
+    for v in report.violations:
+        by_kind.setdefault(v.kind, []).append(v)
+
+    lines = [f"{len(report.violations)} lock violation(s):"]
+    for kind in sorted(by_kind):
+        lines.append(f"[{kind}] {_KIND_HEADLINE.get(kind, '')}")
+        for v in sorted(by_kind[kind], key=lambda x: x.target):
+            loc = f" — {v.file}:{v.line}" if v.file else ""
+            lines.append(f"  - [{v.key()}] {v.target}{loc}")
+            for cont in (v.message or "").splitlines():
+                lines.append(f"      {cont}" if cont else "")
+        lines.append("")
+    lines.append(
+        "A locked implementation may only change with a lead's approval:\n"
+        "  cdec check --automatic-exceptions locks --force\n"
+        "To ship without re-baselining (audited, discouraged):\n"
+        "  cdec check --bypass-locks --bypass-reason \"<why>\""
+    )
+    return "\n".join(lines) + "\n"
+
+
+def report_to_json(report: LockReport) -> dict[str, Any]:
+    return {
+        "violations": [
+            {
+                "key": v.key(),
+                "kind": v.kind,
+                "target": v.target,
+                "message": v.message,
+                "file": v.file,
+                "line": v.line,
+                "expected": v.expected,
+                "actual": v.actual,
+                "reason": v.reason,
+                "owner": v.owner,
+            }
+            for v in report.violations
+        ],
+        "summary": {
+            "checked": report.checked,
+            "declared": report.declared,
+            "violations": len(report.violations),
+            "bypassed": report.bypassed,
+            "bypass_reason": report.bypass_reason,
+        },
+    }
+
+
+# ---------- helpers ----------
+
+def match_any_glob(name: str, patterns: Iterable[str]) -> bool:
+    """Glob match with `.` treated as a normal character, so `tests.**` matches
+    every descendant of `tests`. Mirrors `code_constraints.lint.rules.base.match_any_glob`;
+    duplicated rather than imported to keep the engines decoupled."""
+    for p in patterns:
+        if fnmatch.fnmatchcase(name, p.replace("**", "*")):
+            return True
+    return False
+
+
+def _unquote(raw: str) -> str:
+    """Tag kwargs hold raw source text, so a Python `reason="x"` arrives as
+    `'"x"'` and a C# one as `"\"x\""`. Strip one layer of matching quotes."""
+    text = raw.strip()
+    if len(text) >= 2 and text[0] == text[-1] and text[0] in "\"'":
+        return text[1:-1]
+    return text