code-constraints 0.1.0__py3-none-any.whl

code_constraints/lock/store.py

@@ -0,0 +1,144 @@
+"""The approved-digest ledger — the `locks:` section of `.cdec/rules.yaml`.
+
+The audit trail for frozen implementations. It is meant to be committed and to
+sit behind a CODEOWNERS entry so only leads can approve a re-baseline;
+`cdec check --automatic-exceptions locks` refuses to overwrite a drifted digest
+without `--force` precisely so the diff on this file is the review artefact.
+
+Shape (in the tool-managed tail of `rules.yaml`, see
+`code_constraints.core.rulesdoc`):
+
+    locks:
+      - target: orders.Receipt.formatted
+        kind: method
+        algo: py-ast/1
+        digest: 3f9a…
+        file: orders/billing.py
+        locked_at: "2026-08-02T10:15:00Z"
+        locked_by: alice
+        reason: agreed receipt formatting
+
+A standalone `.cdec/locks.yaml` was the old home. It is still read when present
+(so an existing project keeps working on upgrade) and folded into `rules.yaml`
+by `cdec init --migrate`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable
+
+from code_constraints.core.rulesdoc import RULES_FILENAME, RulesFileError, load_document, write_sections
+from code_constraints.lock.model import LockEntry
+
+LOCKS_FILENAME = "locks.yaml"  # legacy standalone ledger
+LOCKFILE_VERSION = 1
+
+
+class LockfileError(ValueError):
+    """Raised when the lockfile exists but can't be interpreted."""
+
+
+def load_locks(config_dir: Path) -> dict[str, LockEntry]:
+    """Read the ledger into a target -> entry map.
+
+    Accepts either a `.cdec/` directory (the normal call) or a direct path to a
+    YAML file holding a `locks:` list. An absent ledger is an empty one —
+    nothing is locked yet — which is not an error.
+    """
+    rules_file, legacy_file = _ledger_paths(config_dir)
+    items: list = []
+    path = rules_file
+    for candidate in (rules_file, legacy_file):
+        if candidate is None or not candidate.is_file():
+            continue
+        try:
+            raw = load_document(candidate)
+        except RulesFileError as exc:
+            raise LockfileError(str(exc)) from exc
+        version = raw.get("version", LOCKFILE_VERSION)
+        if not isinstance(version, int) or version > LOCKFILE_VERSION:
+            raise LockfileError(
+                f"{candidate}: lockfile version {version!r} is newer than this "
+                f"code-constraints supports (max {LOCKFILE_VERSION}); upgrade with "
+                f"`cdec update`."
+            )
+        found = raw.get("locks") or []
+        if not isinstance(found, list):
+            raise LockfileError(f"{candidate}: 'locks' must be a list")
+        if found:
+            # `rules.yaml` wins outright: once migrated, a leftover locks.yaml
+            # must not resurrect entries a lead deliberately released.
+            items, path = found, candidate
+            break
+
+    out: dict[str, LockEntry] = {}
+    for i, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise LockfileError(f"{path}: locks[{i}] must be a mapping")
+        target = str(item.get("target") or "")
+        digest = str(item.get("digest") or "")
+        if not target or not digest:
+            raise LockfileError(f"{path}: locks[{i}] needs both 'target' and 'digest'")
+        out[target] = LockEntry(
+            target=target,
+            kind=str(item.get("kind") or "class"),
+            digest=digest,
+            algo=str(item.get("algo") or ""),
+            file=str(item.get("file") or ""),
+            locked_at=str(item.get("locked_at") or ""),
+            locked_by=str(item.get("locked_by") or ""),
+            reason=str(item.get("reason") or ""),
+            via_pattern=bool(item.get("via_pattern") or False),
+        )
+    return out
+
+
+def write_locks(config_dir: Path, entries: Iterable[LockEntry]) -> Path:
+    """Write the ledger into `rules.yaml`, sorted so the file diffs cleanly.
+
+    Only the `locks:` section is rewritten — every hand-written rule and comment
+    above it is preserved byte for byte. Returns the file written.
+    """
+    rules_file, _ = _ledger_paths(config_dir)
+    write_sections(
+        rules_file,
+        {"locks": [_entry_to_dict(e) for e in sorted(entries, key=lambda e: e.target)]},
+    )
+    return rules_file
+
+
+def _ledger_paths(config_dir: Path) -> tuple[Path, Path | None]:
+    """(rules.yaml, legacy locks.yaml) for a `.cdec/` dir.
+
+    Passing a YAML file directly is also honoured — tests and `--lockfile`-style
+    overrides point straight at one — in which case there is no legacy fallback.
+    """
+    if config_dir.suffix in (".yaml", ".yml"):
+        return config_dir, None
+    return config_dir / RULES_FILENAME, config_dir / LOCKS_FILENAME
+
+
+def now_stamp() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def _entry_to_dict(e: LockEntry) -> dict[str, object]:
+    out: dict[str, object] = {
+        "target": e.target,
+        "kind": e.kind,
+        "algo": e.algo,
+        "digest": e.digest,
+    }
+    if e.file:
+        out["file"] = e.file
+    if e.locked_at:
+        out["locked_at"] = e.locked_at
+    if e.locked_by:
+        out["locked_by"] = e.locked_by
+    if e.reason:
+        out["reason"] = e.reason
+    if e.via_pattern:
+        out["via_pattern"] = True
+    return out

code_constraints/lua/__init__.py

@@ -0,0 +1,5 @@
+"""Lua language support: UML parsing, rule recognition, conformance and locks."""
+
+from code_constraints.lua.parser import parse_project
+
+__all__ = ["parse_project"]

code_constraints/lua/conformance.py

@@ -0,0 +1,239 @@
+"""Body-level conformance analysis for Lua (`cdec enforce`, Engine B).
+
+Re-parses Lua source with tree-sitter and inspects function bodies for violations
+of architectural-rule tags. Reuses `lua.rules_extract` so "what is a rule" stays
+identical to the UML parser.
+
+Lua is the loosest of the supported languages, so detection is explicitly
+heuristic — closer to the Python analyzer than to the C# one:
+
+* **Construction** has no syntax of its own. Two idioms are recognised:
+  `T.new(...)` / `T:new(...)` where `T` names a class in the project, and a
+  direct `setmetatable(tbl, T)`. A bare `T(...)` call is *not* treated as
+  construction, because in Lua that is an ordinary `__call`, not a constructor.
+* **Field reassignment** is `self.x = …` outside the constructor. "The
+  constructor" means a static function on the class named `new`, `create` or
+  `init` — Lua has no `__init__` to privilege, so the convention is named
+  explicitly here rather than guessed per project.
+
+`allow` is the escape hatch when the heuristic is wrong, exactly as in Python.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import tree_sitter_lua
+from tree_sitter import Language, Node, Parser
+
+from code_constraints.core.annotations import literal_set
+from code_constraints.core.model import Project, RuleAnnotation
+from code_constraints.enforce.model import Finding
+from code_constraints.lua.parser import (
+    _dot_parts,
+    _qualified_package_name,
+    _should_skip,
+    _text,
+)
+from code_constraints.lua.rules_extract import extract_rules
+
+_LANG = Language(tree_sitter_lua.language())
+_PARSER = Parser(_LANG)
+
+CTOR_RULE = "no-instantiation"
+FACTORY_RULE = "factory"
+IMMUTABLE_RULE = "immutable"
+
+# Function names treated as constructors: `self.x = …` in these is initialisation,
+# not reassignment.
+_CONSTRUCTOR_NAMES = frozenset({"new", "create", "init", "_init", "_new"})
+
+
+def analyze(root: Path, project: Project) -> list[Finding]:
+    project_classes = {cls.name for cls in project.iter_classes()}
+    factory_index = _factory_index(project)
+    class_rules = {
+        cls.qualified_name: {r.name: r for r in cls.rules}
+        for cls in project.iter_classes()
+    }
+
+    findings: list[Finding] = []
+    for lua_file in sorted(root.rglob("*.lua")):
+        if _should_skip(lua_file):
+            continue
+        try:
+            source = lua_file.read_bytes()
+        except OSError:
+            continue
+        tree = _PARSER.parse(source)
+        rel = lua_file.relative_to(root)
+        package_qn = _qualified_package_name(rel)
+        for stmt in tree.root_node.named_children:
+            if stmt.type != "function_declaration":
+                continue
+            _analyze_function(
+                stmt, source, package_qn, rel, class_rules,
+                project_classes, factory_index, findings,
+            )
+    return findings
+
+
+def _analyze_function(
+    node: Node,
+    source: bytes,
+    package_qn: str,
+    rel: Path,
+    class_rules: dict[str, dict[str, RuleAnnotation]],
+    project_classes: set[str],
+    factory_index: dict[str, set[str]],
+    out: list[Finding],
+) -> None:
+    target = next(
+        (
+            c
+            for c in node.children
+            if c.type in ("identifier", "dot_index_expression", "method_index_expression")
+        ),
+        None,
+    )
+    if target is None:
+        return
+    block = next((c for c in node.children if c.type == "block"), None)
+    if block is None:
+        return
+
+    if target.type == "identifier":
+        owner_name = rel.stem
+        name = _text(target, source)
+    else:
+        owner_name, name = _dot_parts(target, source)
+        if not owner_name or not name:
+            return
+    owner_qn = (
+        f"{package_qn}.{owner_name}" if package_qn != "__root__" else owner_name
+    )
+
+    func_rules = {r.name: r for r in extract_rules(node, source)}
+    owner_rules = class_rules.get(owner_qn, {})
+    file = rel.as_posix()
+
+    noinst = func_rules.get(CTOR_RULE, owner_rules.get(CTOR_RULE))
+    allow = literal_set(noinst.kwargs.get("allow", "")) if noinst is not None else None
+
+    for constructed, line in _constructions(block, source, project_classes):
+        if constructed == owner_name:
+            # A type constructing itself is never a violation: it is how the
+            # `T.new(...)` / inner-constructor idiom is written, and neither
+            # `no_instantiation` nor `factory` is aimed at a type's own
+            # constructor — they guard construction by *other* code.
+            continue
+        if allow is not None and constructed not in allow:
+            out.append(
+                Finding(
+                    rule=CTOR_RULE,
+                    qualified_name=owner_qn,
+                    message=(
+                        f"'{owner_qn}.{name}' is tagged @cdec no_instantiation but "
+                        f"constructs '{constructed}'."
+                    ),
+                    detail=f"{name}->{constructed}",
+                    file=file,
+                    line=line,
+                )
+            )
+        designated = factory_index.get(constructed)
+        if designated is not None and owner_name not in designated:
+            allowed = ", ".join(sorted(designated)) or "(none)"
+            out.append(
+                Finding(
+                    rule=FACTORY_RULE,
+                    qualified_name=owner_qn,
+                    message=(
+                        f"'{owner_qn}.{name}' constructs '{constructed}' outside its "
+                        f"designated factory ({allowed})."
+                    ),
+                    detail=f"{name}->{constructed}",
+                    file=file,
+                    line=line,
+                )
+            )
+
+    if IMMUTABLE_RULE in owner_rules and name not in _CONSTRUCTOR_NAMES:
+        for field, line in _self_assignments(block, source):
+            out.append(
+                Finding(
+                    rule=IMMUTABLE_RULE,
+                    qualified_name=owner_qn,
+                    message=(
+                        f"'{owner_qn}' is tagged @cdec immutable but '{name}' "
+                        f"reassigns field 'self.{field}'."
+                    ),
+                    detail=f"{name}.{field}",
+                    file=file,
+                    line=line,
+                )
+            )
+
+
+def _constructions(
+    block: Node, source: bytes, project_classes: set[str]
+) -> list[tuple[str, int]]:
+    """`T.new(...)` / `T:new(...)` calls and `setmetatable(t, T)` allocations."""
+    out: list[tuple[str, int]] = []
+    stack = [block]
+    while stack:
+        node = stack.pop()
+        stack.extend(node.children)
+        if node.type != "function_call":
+            continue
+        line = node.start_point[0] + 1
+        callee = node.named_children[0] if node.named_children else None
+        if callee is None:
+            continue
+
+        if callee.type in ("dot_index_expression", "method_index_expression"):
+            owner, member = _dot_parts(callee, source)
+            if owner in project_classes and member in _CONSTRUCTOR_NAMES:
+                out.append((owner, line))
+            continue
+
+        if callee.type == "identifier" and _text(callee, source) == "setmetatable":
+            args = next((c for c in node.named_children if c.type == "arguments"), None)
+            named = args.named_children if args else []
+            if len(named) >= 2 and named[1].type == "identifier":
+                metatable = _text(named[1], source)
+                if metatable in project_classes:
+                    out.append((metatable, line))
+    return out
+
+
+def _self_assignments(block: Node, source: bytes) -> list[tuple[str, int]]:
+    out: list[tuple[str, int]] = []
+    stack = [block]
+    while stack:
+        node = stack.pop()
+        stack.extend(node.children)
+        if node.type != "assignment_statement":
+            continue
+        targets = next((c for c in node.named_children if c.type == "variable_list"), None)
+        if targets is None:
+            continue
+        for target in targets.named_children:
+            if target.type != "dot_index_expression":
+                continue
+            owner, field = _dot_parts(target, source)
+            if owner == "self" and field:
+                out.append((field, node.start_point[0] + 1))
+    return out
+
+
+def _factory_index(project: Project) -> dict[str, set[str]]:
+    """Created-type name -> set of class names designated to construct it."""
+    idx: dict[str, set[str]] = {}
+    for cls in project.iter_classes():
+        for rule in list(cls.rules) + [r for op in cls.operations for r in op.rules]:
+            if rule.name != FACTORY_RULE:
+                continue
+            for created in literal_set(rule.kwargs.get("creates", "")):
+                idx.setdefault(created, set()).add(cls.name)
+    return idx

code_constraints/lua/fingerprint.py

@@ -0,0 +1,252 @@
+"""AST fingerprinting for Lua (`cdec lock`, Engine C).
+
+Digests come from the tree-sitter tree via `core.ts_fingerprint`, so a locked
+element survives reformatting and relocation within its file.
+
+Lua-specific concerns:
+
+* **A class is not one node.** The table-plus-metatable idiom spreads a class
+  across several top-level statements (`local T = {}`, `T.__index = T`, each
+  `function T:m()`), so a class target digests the whole group of statements that
+  belong to `T`. That is the right semantics for a freeze: adding a method to a
+  locked class is a change to the class.
+* **Tags are comments**, so `---@cdec locked` lines are dropped from the digest
+  explicitly rather than incidentally — otherwise `include_docstrings` would let
+  applying a lock change the very digest it records.
+* **Target names match the UML model**, so a target read from `cdec lock list` is
+  the target `cdec lock set` accepts. Naming reuses `lua.parser` helpers rather
+  than re-deriving them, so the two can't drift apart.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import tree_sitter_lua
+from tree_sitter import Language, Node, Parser
+
+from code_constraints.core.ts_fingerprint import digest_members
+from code_constraints.lock.model import LOCK_RULE, LockTarget
+from code_constraints.lua.parser import (
+    _dot_parts,
+    _inner_assignment,
+    _qualified_package_name,
+    _should_skip,
+    _text,
+)
+from code_constraints.lua.rules_extract import comment_is_rule_tag, extract_rules
+
+DIGEST_ALGO = "lua-ts/1"
+
+_LANG = Language(tree_sitter_lua.language())
+_PARSER = Parser(_LANG)
+
+
+def collect_lockables(
+    root: str | Path, *, include_docstrings: bool = False
+) -> list[LockTarget]:
+    root_path = Path(root).resolve()
+    out: list[LockTarget] = []
+
+    for lua_file in sorted(root_path.rglob("*.lua")):
+        if _should_skip(lua_file):
+            continue
+        try:
+            source = lua_file.read_bytes()
+        except OSError:
+            continue
+        tree = _PARSER.parse(source)
+        rel = lua_file.relative_to(root_path)
+        out.extend(
+            _collect_file(
+                tree.root_node,
+                source,
+                _qualified_package_name(rel),
+                rel,
+                include_docstrings,
+            )
+        )
+    return out
+
+
+def _collect_file(
+    root: Node,
+    source: bytes,
+    package_qn: str,
+    rel: Path,
+    include_docstrings: bool,
+) -> list[LockTarget]:
+    file = rel.as_posix()
+    # Table name -> the statements that *declare* it (`local T = {}`,
+    # `T.__index = T`, `T.field = …`). Kept apart from its function
+    # declarations, because a class's own tags come only from these: a
+    # `---@cdec locked` above `function T:m()` locks the method, not the class.
+    declarations: dict[str, list[Node]] = {}
+    # (table, member) -> the function declarations for it.
+    methods: dict[tuple[str, str], list[Node]] = {}
+    # Tables carrying a self-index or a metatable base — class evidence even
+    # with no methods, matching how the parser promotes a table.
+    marked: set[str] = set()
+    free: dict[str, list[Node]] = {}
+
+    for stmt in root.named_children:
+        if stmt.type == "function_declaration":
+            target = next(
+                (
+                    c
+                    for c in stmt.children
+                    if c.type
+                    in ("identifier", "dot_index_expression", "method_index_expression")
+                ),
+                None,
+            )
+            if target is None:
+                continue
+            if target.type == "identifier":
+                free.setdefault(_text(target, source), []).append(stmt)
+                continue
+            owner, name = _dot_parts(target, source)
+            if owner and name:
+                declarations.setdefault(owner, [])
+                methods.setdefault((owner, name), []).append(stmt)
+            continue
+
+        assign = _inner_assignment(stmt) if stmt.type == "variable_declaration" else (
+            stmt if stmt.type == "assignment_statement" else None
+        )
+        if assign is None:
+            continue
+        for name, is_marker in _assigned_tables(assign, source):
+            declarations.setdefault(name, []).append(stmt)
+            if is_marker:
+                marked.add(name)
+
+    out: list[LockTarget] = []
+    for table, decls in declarations.items():
+        member_nodes = [
+            node for (owner, _name), nodes in methods.items() if owner == table
+            for node in nodes
+        ]
+        rules = [r for node in decls for r in extract_rules(node, source)]
+        # Mirror the parser's promotion rule: a bare `local cfg = {}` data table
+        # is not a class, so it is not a lockable either.
+        if not (member_nodes or table in marked or rules):
+            continue
+        qn = f"{package_qn}.{table}" if package_qn != "__root__" else table
+        statements = sorted(decls + member_nodes, key=lambda n: n.start_byte)
+        out.append(
+            _target(
+                [(node, source) for node in statements],
+                qn,
+                "class",
+                file,
+                include_docstrings,
+                tag_nodes=decls,
+            )
+        )
+
+    for (table, name), nodes in methods.items():
+        owner = f"{package_qn}.{table}" if package_qn != "__root__" else table
+        out.append(
+            _target(
+                [(node, source) for node in nodes],
+                f"{owner}.{name}",
+                "method",
+                file,
+                include_docstrings,
+            )
+        )
+
+    for name, nodes in free.items():
+        owner = f"{package_qn}.{rel.stem}" if package_qn != "__root__" else rel.stem
+        out.append(
+            _target(
+                [(node, source) for node in nodes],
+                f"{owner}.{name}",
+                "function",
+                file,
+                include_docstrings,
+            )
+        )
+
+    return out
+
+
+def _assigned_tables(assign: Node, source: bytes) -> list[tuple[str, bool]]:
+    """Table names an assignment contributes to, each with a "this is class
+    evidence" flag.
+
+    `T = {}` names `T` but proves nothing on its own; `T.__index = …` and
+    `T = setmetatable(…)` are the metatable markers that make it a prototype.
+    """
+    targets = next((c for c in assign.named_children if c.type == "variable_list"), None)
+    if targets is None:
+        return []
+    values = next((c for c in assign.named_children if c.type == "expression_list"), None)
+    out: list[tuple[str, bool]] = []
+    for i, target in enumerate(targets.named_children):
+        value = values.named_children[i] if values and i < len(values.named_children) else None
+        if target.type == "identifier":
+            marker = value is not None and _is_setmetatable(value, source)
+            out.append((_text(target, source), marker))
+        elif target.type == "dot_index_expression":
+            owner, field = _dot_parts(target, source)
+            if owner:
+                out.append((owner, field == "__index"))
+    return out
+
+
+def _is_setmetatable(value: Node, source: bytes) -> bool:
+    if value.type != "function_call":
+        return False
+    callee = next((c for c in value.named_children if c.type == "identifier"), None)
+    return callee is not None and _text(callee, source) == "setmetatable"
+
+
+def _target(
+    members: list[tuple[Node, bytes]],
+    target: str,
+    kind: str,
+    file: str,
+    include_docstrings: bool,
+    tag_nodes: list[Node] | None = None,
+) -> LockTarget:
+    """`tag_nodes` narrows where the `@locked` tag may be read from.
+
+    A class digests its methods as well as its declaration statements, but a tag
+    above `function T:m()` locks the *method*; only tags above the declaration
+    statements lock the class.
+    """
+
+    def drop(node: Node, source: bytes) -> bool:
+        if node.type != "comment":
+            return False
+        # A rule tag is never part of the implementation, whatever the docstring
+        # setting: applying or removing `---@cdec locked` must leave the digest
+        # of the body it guards untouched.
+        if comment_is_rule_tag(node, source):
+            return True
+        return not include_docstrings
+
+    declared = False
+    params: dict[str, str] = {}
+    source = members[0][1]
+    tagged = (
+        [(node, source) for node in tag_nodes] if tag_nodes is not None else members
+    )
+    for node, source in tagged:
+        for rule in extract_rules(node, source):
+            if rule.name == LOCK_RULE:
+                declared = True
+                params = {**rule.kwargs, **params} if params else dict(rule.kwargs)
+
+    return LockTarget(
+        target=target,
+        kind=kind,  # type: ignore[arg-type]
+        digest=digest_members(members, drop),
+        algo=DIGEST_ALGO,
+        file=file,
+        line=members[0][0].start_point[0] + 1,
+        declared=declared,
+        params=params,
+    )