code-constraints 0.1.0__py3-none-any.whl

code_constraints/core/rulesdoc.py

@@ -0,0 +1,208 @@
+"""`.cdec/rules.yaml` — the one file a project commits.
+
+Everything the tool needs to gate a codebase lives here: the project settings,
+the rules that are enforced, the exceptions that were granted, and the digests
+of frozen implementations. One file, one diff to review, one thing to put behind
+CODEOWNERS.
+
+That creates a problem this module exists to solve. The `rules:` section is
+hand-written and carries the explanations that make a failed build teach
+something; the `exceptions:` and `locks:` sections are written by the tool. A
+naive ``yaml.safe_dump`` of the whole document would silently delete every
+comment and reflow every ``message: |`` block the first time anyone ran
+``cdec check --automatic-exceptions``.
+
+So writes are *surgical*. The tool-written sections live at the end of the file
+under a marker line; a write keeps every byte above the marker verbatim and
+regenerates only what is below it. Reads are ordinary ``yaml.safe_load`` over
+the whole document, so the split is invisible to everything else.
+
+Shape::
+
+    language: python
+    source: src
+
+    rules:
+      - id: catalog-is-a-leaf
+        type: forbidden-package-references
+        ...
+
+    # >>> cdec: managed section ...
+    exceptions:
+      - key: V-1A2B3C4D
+        ...
+    locks:
+      - target: orders.Receipt.formatted
+        ...
+
+Deliberately engine-agnostic: this module deals in plain mappings and imports
+nothing from `lint`, `enforce`, `lock` or `waivers`, so the engines that write
+into the file stay decoupled from each other.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+RULES_FILENAME = "rules.yaml"
+
+#: Top-level keys owned by the tool. Everything else in the file is the user's.
+MANAGED_KEYS: tuple[str, ...] = ("exceptions", "locks")
+
+MANAGED_MARKER = (
+    "# >>> cdec: managed section — rewritten by `cdec check --automatic-exceptions`\n"
+    "# >>> and by `cdec exceptions ...`. Edit the rules above this line, not below it.\n"
+)
+
+# A top-level YAML key: no leading whitespace, an identifier, a colon.
+_TOP_KEY_RE = re.compile(r"^([A-Za-z_][A-Za-z0-9_-]*)\s*:")
+
+
+class RulesFileError(ValueError):
+    """Raised when `rules.yaml` exists but can't be interpreted."""
+
+
+def load_document(path: Path) -> dict[str, Any]:
+    """Read the whole file as a mapping. A missing file is an empty document."""
+    if not path.is_file():
+        return {}
+    with path.open("r", encoding="utf-8") as fh:
+        try:
+            raw = yaml.safe_load(fh) or {}
+        except yaml.YAMLError as exc:
+            raise RulesFileError(f"{path}: not valid YAML ({exc})") from exc
+    if not isinstance(raw, dict):
+        raise RulesFileError(f"{path}: top-level must be a mapping")
+    return raw
+
+
+def read_section(path: Path, key: str) -> Any:
+    """One top-level section, or None when absent."""
+    return load_document(path).get(key)
+
+
+def write_sections(path: Path, sections: dict[str, Any]) -> None:
+    """Replace the named tool-owned sections, preserving everything else byte
+    for byte.
+
+    Only the keys in `sections` are touched — writing `exceptions` leaves a
+    `locks` section exactly as it was, so the two engines can write the same
+    file without stepping on each other.
+    """
+    unknown = set(sections) - set(MANAGED_KEYS)
+    if unknown:
+        raise RulesFileError(
+            f"refusing to write non-managed section(s) {sorted(unknown)} into {path}"
+        )
+
+    text = path.read_text(encoding="utf-8") if path.is_file() else ""
+    prefix, existing = _split(text)
+
+    merged = dict(existing)
+    for key, value in sections.items():
+        if value:
+            merged[key] = value
+        else:
+            merged.pop(key, None)
+
+    body = ""
+    for key in MANAGED_KEYS:
+        if key in merged:
+            body += yaml.safe_dump(
+                {key: merged[key]}, sort_keys=False, default_flow_style=False,
+                allow_unicode=True, width=100000,
+            )
+
+    if prefix and not prefix.endswith("\n"):
+        prefix += "\n"
+    out = prefix
+    if body:
+        if out and not out.endswith("\n\n"):
+            out += "\n"
+        out += MANAGED_MARKER + body
+    elif not out:
+        out = ""
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(out, encoding="utf-8")
+
+
+# ---------- internals ----------
+
+def _split(text: str) -> tuple[str, dict[str, Any]]:
+    """Split the document into (verbatim prefix, parsed managed sections).
+
+    The prefix is everything the user owns. Managed sections are removed from it
+    wherever they appear — normally below the marker, but a hand-placed
+    `exceptions:` higher up is lifted too, so a write can never produce a
+    duplicate top-level key.
+    """
+    lines = text.splitlines(keepends=True)
+    spans = _top_level_spans(lines)
+
+    managed_text = "".join(
+        "".join(lines[start:end])
+        for key, start, end in spans
+        if key in MANAGED_KEYS
+    )
+    drop: set[int] = set()
+    for key, start, end in spans:
+        if key in MANAGED_KEYS:
+            drop.update(range(start, end))
+
+    prefix_lines = [line for i, line in enumerate(lines) if i not in drop]
+    prefix = "".join(prefix_lines)
+    # The marker only describes the block below it; without one it is noise.
+    prefix = prefix.replace(MANAGED_MARKER, "")
+    for marker_line in MANAGED_MARKER.splitlines(keepends=True):
+        prefix = prefix.replace(marker_line, "")
+    prefix = prefix.rstrip("\n")
+    if prefix:
+        prefix += "\n"
+
+    if not managed_text.strip():
+        return prefix, {}
+    try:
+        parsed = yaml.safe_load(managed_text) or {}
+    except yaml.YAMLError:
+        # Unparseable managed text is regenerated from scratch rather than
+        # merged; the caller is handing us the authoritative content anyway.
+        return prefix, {}
+    return prefix, parsed if isinstance(parsed, dict) else {}
+
+
+def _top_level_spans(lines: list[str]) -> list[tuple[str, int, int]]:
+    """(key, start_index, end_index) for every top-level mapping key.
+
+    A span runs from the key line to just before the next top-level key (or
+    EOF), so it carries the key's whole nested block. Comment lines immediately
+    above a key belong to that key, so they travel with it.
+    """
+    starts: list[tuple[str, int]] = []
+    for i, line in enumerate(lines):
+        match = _TOP_KEY_RE.match(line)
+        if match is None:
+            continue
+        starts.append((match.group(1), _comment_block_start(lines, i)))
+
+    spans: list[tuple[str, int, int]] = []
+    for pos, (key, start) in enumerate(starts):
+        end = starts[pos + 1][1] if pos + 1 < len(starts) else len(lines)
+        spans.append((key, start, end))
+    return spans
+
+
+def _comment_block_start(lines: list[str], key_index: int) -> int:
+    """Index of the first line of the comment block attached to `key_index`."""
+    i = key_index
+    while i > 0:
+        previous = lines[i - 1].strip()
+        if previous.startswith("#"):
+            i -= 1
+            continue
+        break
+    return i

code_constraints/core/tags.py

@@ -0,0 +1,114 @@
+"""Parse XML-style comment tags from source code.
+
+Recognised forms (after the comment prefix is stripped):
+
+    <uml-class />
+    <uml-activity name="checkout" granularity="control-flow">
+    </uml-activity>
+    <uml-sequence name="login" root="Handle">
+    </uml-sequence>
+
+The caller provides the comment prefix (e.g. `//` for C#, `#` for Python).
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Literal
+
+TagKind = Literal["uml-class", "uml-activity", "uml-sequence"]
+_VALID_KINDS: set[str] = {"uml-class", "uml-activity", "uml-sequence"}
+
+
+@dataclass
+class TagInstance:
+    """A matched tag span. `start_line` and `end_line` are 1-indexed; the
+    closed range covers the lines between the opening and closing tags
+    (inclusive of the lines containing the tags themselves)."""
+    kind: TagKind
+    name: str
+    attributes: dict[str, str] = field(default_factory=dict)
+    start_line: int = 0
+    end_line: int = 0
+    self_closed: bool = False
+
+
+_TAG_LINE_RE = re.compile(r"<\s*/?\s*uml-[a-zA-Z-]+\b[^>]*?/?\s*>")
+
+
+def find_tags(source: str, comment_prefix: str) -> list[TagInstance]:
+    """Scan `source` (full file text) and return tag spans.
+
+    Unbalanced tags (open without close, or vice versa) are skipped silently;
+    the parser is intentionally forgiving so a malformed comment never breaks
+    the rest of the diagram generation.
+    """
+    prefix = comment_prefix.strip()
+    open_stack: list[tuple[str, dict[str, str], int]] = []
+    result: list[TagInstance] = []
+
+    for lineno, line in enumerate(source.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped.startswith(prefix):
+            continue
+        rest = stripped[len(prefix) :].strip()
+        match = _TAG_LINE_RE.search(rest)
+        if not match:
+            continue
+        tag_text = match.group(0)
+
+        if tag_text.startswith("</"):
+            kind = _extract_kind(tag_text)
+            if kind not in _VALID_KINDS:
+                continue
+            if open_stack and open_stack[-1][0] == kind:
+                opened_kind, attrs, opened_line = open_stack.pop()
+                result.append(
+                    TagInstance(
+                        kind=opened_kind,  # type: ignore[arg-type]
+                        name=attrs.get("name", ""),
+                        attributes=attrs,
+                        start_line=opened_line,
+                        end_line=lineno,
+                        self_closed=False,
+                    )
+                )
+            continue
+
+        is_self_closing = tag_text.rstrip().endswith("/>")
+        # ET requires balanced XML — rewrite an open tag as self-closing so
+        # we can reuse it to parse attributes.
+        parse_text = tag_text if is_self_closing else tag_text.rstrip()[:-1] + "/>"
+        try:
+            element = ET.fromstring(parse_text)
+        except ET.ParseError:
+            continue
+        kind = element.tag
+        if kind not in _VALID_KINDS:
+            continue
+        attrs = dict(element.attrib)
+        if is_self_closing:
+            result.append(
+                TagInstance(
+                    kind=kind,  # type: ignore[arg-type]
+                    name=attrs.get("name", ""),
+                    attributes=attrs,
+                    start_line=lineno,
+                    end_line=lineno,
+                    self_closed=True,
+                )
+            )
+        else:
+            open_stack.append((kind, attrs, lineno))
+
+    return result
+
+
+def _extract_kind(tag_text: str) -> str:
+    """Pull the bare tag name out of `</uml-activity>` etc."""
+    cleaned = tag_text.strip().lstrip("<").rstrip(">").lstrip("/").rstrip("/").strip()
+    if " " in cleaned:
+        cleaned = cleaned.split(" ", 1)[0]
+    return cleaned

code_constraints/core/ts_fingerprint.py

@@ -0,0 +1,88 @@
+"""Canonical AST serialisation for tree-sitter-backed lock fingerprints.
+
+The shared half of Engine C (`cdec lock`) for every tree-sitter language. It
+answers only "what string represents this subtree"; each language's
+`fingerprint.py` owns discovery, target naming, and which nodes to drop.
+
+The invariants a fingerprinter must preserve — the same ones documented on
+`code_constraints.csharp.fingerprint`, which predates this module and keeps its
+own copy:
+
+* **Anonymous children are walked.** Operators and punctuation are anonymous
+  tokens, so skipping them would hash `a + b` and `a - b` identically.
+* **Whitespace never appears.** tree-sitter emits no nodes for indentation or
+  newlines, so a locked body survives reformatting and relocation for free.
+* **Comments are dropped** unless the caller keeps them, and the rule *tag*
+  itself is always dropped — applying or removing a lock must not change the
+  digest of the body it guards.
+* **Changing this serialiser must bump the caller's algo id.** A mismatch then
+  surfaces as an `algo-mismatch` violation ("re-baseline") rather than as a
+  false "implementation changed".
+"""
+
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Callable, Sequence
+
+from tree_sitter import Node
+
+# Returns True for a node that must not contribute to the digest. Takes the
+# source alongside the node because a group's members can come from different
+# files (Odin and Julia declare a type's operations at package scope, so two
+# same-named members need not share a file).
+DropFn = Callable[[Node, bytes], bool]
+
+# Extra text folded into a member's digest beyond its serialised subtree. Lets a
+# language account for something outside the node it digests — Julia uses it to
+# keep non-rule macro wrappers significant while digesting the unwrapped
+# definition. Return "" to add nothing.
+ExtraFn = Callable[[Node, bytes], str]
+
+
+def canonical(node: Node, source: bytes, drop: DropFn) -> str:
+    """Serialise `node` to a canonical, position-independent string."""
+    if drop(node, source):
+        return ""
+    if node.child_count == 0:
+        text = _text(node, source).strip()
+        return f"({node.type} {text!r})" if node.is_named else f"({text!r})"
+    parts = [p for p in (canonical(c, source, drop) for c in node.children) if p]
+    if not parts:
+        # Every child was dropped; keep the node's own identity so an emptied
+        # wrapper still differs from the wrapper being absent.
+        return f"({node.type})"
+    return f"({node.type} {' '.join(parts)})"
+
+
+def digest_members(
+    members: Sequence[tuple[Node, bytes]], drop: DropFn, extra: ExtraFn | None = None
+) -> str:
+    """Digest a group of same-named members as one target.
+
+    Overloads, `@property`/setter pairs, and multiple-dispatch methods collapse
+    into a single digest over their sorted member digests, so adding an overload
+    to a locked name is a violation in its own right and no ordinal
+    disambiguator is needed. Sorting also makes the digest independent of the
+    order the files happened to be walked in.
+    """
+    digests = sorted(
+        sha256(
+            (canonical(node, source, drop) + _suffix(extra, node, source)).encode("utf-8")
+        ).hexdigest()
+        for node, source in members
+    )
+    if len(digests) == 1:
+        return digests[0]
+    return sha256(("group:" + "|".join(digests)).encode("utf-8")).hexdigest()
+
+
+def _suffix(extra: ExtraFn | None, node: Node, source: bytes) -> str:
+    if extra is None:
+        return ""
+    text = extra(node, source)
+    return f"|extra:{text}" if text else ""
+
+
+def _text(node: Node, source: bytes) -> str:
+    return source[node.start_byte : node.end_byte].decode("utf-8", errors="replace")