code-constraints 0.1.0__py3-none-any.whl

code_constraints/python/sequence.py

@@ -0,0 +1,257 @@
+"""Build a UML `Sequence` from a tagged Python region.
+
+Three semantics worth pinning down:
+
+1. **Call evaluation order is preserved.** Calls within a single statement
+   are emitted innermost-first (post-order), matching Python's evaluation
+   order. For `cart.checkout(cart.total())` we emit `total()` before
+   `checkout()` — the argument is computed before the outer dispatch.
+
+2. **Each call has a paired return arrow.** Right after the forward
+   `root → receiver` message we emit a dashed `receiver → root` return
+   message. The return is anonymous (empty label) by default; when the
+   call is the *outermost* call in an `Assign` statement we use the
+   assignment target as the return label (e.g. `result = cart.checkout(...)`
+   produces a return labelled `result`).
+
+3. **Branches become combined fragments + guard prefixes.** For
+   `if cond: ...` we attach `cond` to every message inside the body as a
+   guard string AND emit a `Fragment(kind="alt", label=cond, …)` covering
+   the body's message rows; the `else` branch gets a sibling fragment with
+   the negation. `return X` at the top level emits a self-return on the
+   root with label `return X`, giving the diagram an explicit endpoint.
+"""
+
+from __future__ import annotations
+
+import ast
+
+from code_constraints.core.model import Fragment, Lifeline, Message, Sequence, SourceLocation
+from code_constraints.core.tags import TagInstance
+
+
+def build_sequence_from_tag(
+    tag: TagInstance, tree: ast.Module, source: str, *, file: str
+) -> Sequence | None:
+    if not tag.name:
+        return None
+    root = tag.attributes.get("root", "self")
+
+    stmts = _statements_in_range(tree, tag.start_line, tag.end_line)
+    if not stmts:
+        return None
+
+    state = _State(root=root)
+    _emit_messages(stmts, [], state)
+
+    return Sequence(
+        name=tag.name,
+        lifelines=list(state.lifelines.values()),
+        messages=state.messages,
+        fragments=state.fragments,
+        location=SourceLocation(file=file, start_line=tag.start_line, end_line=tag.end_line),
+    )
+
+
+class _State:
+    """Mutable accumulator threaded through the recursive emitter."""
+
+    def __init__(self, root: str) -> None:
+        self.root = root
+        self.lifelines: dict[str, Lifeline] = {root: Lifeline(name=root, represents=root)}
+        self.messages: list[Message] = []
+        self.fragments: list[Fragment] = []
+
+    def ensure_lifeline(self, name: str) -> None:
+        if name not in self.lifelines:
+            self.lifelines[name] = Lifeline(name=name, represents=name)
+
+
+def _emit_messages(
+    stmts: list[ast.stmt],
+    active_guards: list[str],
+    state: _State,
+) -> None:
+    """Walk top-level `stmts`, dispatching ifs/returns into special handlers
+    and letting any other statement contribute its calls in post-order."""
+    guard_str = " and ".join(active_guards)
+    for stmt in stmts:
+        if isinstance(stmt, ast.If):
+            _emit_if(stmt, active_guards, state)
+        elif isinstance(stmt, ast.Return):
+            _emit_calls_in(stmt.value, guard_str, state, return_label="")
+            value_text = _safe_unparse(stmt.value) if stmt.value is not None else ""
+            label = f"return {value_text}" if value_text else "return"
+            state.messages.append(
+                Message(
+                    sender=state.root,
+                    receiver=state.root,
+                    label=label,
+                    is_return=True,
+                    guard=guard_str,
+                )
+            )
+        elif isinstance(stmt, ast.Assign):
+            target = ""
+            if len(stmt.targets) == 1 and isinstance(stmt.targets[0], ast.Name):
+                target = stmt.targets[0].id
+            _emit_calls_in(stmt.value, guard_str, state, return_label=target)
+        elif isinstance(stmt, ast.AnnAssign):
+            target = ""
+            if isinstance(stmt.target, ast.Name):
+                target = stmt.target.id
+            if stmt.value is not None:
+                _emit_calls_in(stmt.value, guard_str, state, return_label=target)
+        else:
+            _emit_calls_in(stmt, guard_str, state, return_label="")
+
+
+def _emit_if(stmt: ast.If, active_guards: list[str], state: _State) -> None:
+    cond_text = _safe_unparse(stmt.test)
+    # Calls in the condition execute unconditionally — keep the current guards.
+    _emit_calls_in(stmt.test, " and ".join(active_guards), state, return_label="")
+
+    # Body: capture row range so we can emit a fragment covering it.
+    body_start = len(state.messages)
+    _emit_messages(stmt.body, active_guards + [cond_text], state)
+    body_end = len(state.messages) - 1
+    if body_end >= body_start:
+        state.fragments.append(
+            Fragment(
+                kind="alt" if stmt.orelse else "opt",
+                label=cond_text,
+                start_row=body_start,
+                end_row=body_end,
+            )
+        )
+
+    if stmt.orelse:
+        else_start = len(state.messages)
+        _emit_messages(stmt.orelse, active_guards + [f"not ({cond_text})"], state)
+        else_end = len(state.messages) - 1
+        if else_end >= else_start:
+            state.fragments.append(
+                Fragment(
+                    kind="alt",
+                    label=f"else ({cond_text} is false)",
+                    start_row=else_start,
+                    end_row=else_end,
+                )
+            )
+
+
+def _emit_calls_in(
+    node: ast.AST | None,
+    guard: str,
+    state: _State,
+    *,
+    return_label: str,
+) -> None:
+    """Emit forward + return messages for every Call inside `node`.
+
+    `return_label` decorates the return of the OUTERMOST call only (the one
+    yielded last by post-order). Inner calls always get an anonymous return.
+    """
+    if node is None:
+        return
+    calls = list(_calls_post_order(node))
+    if not calls:
+        return
+    last_idx = len(calls) - 1
+    for i, call in enumerate(calls):
+        rl = return_label if i == last_idx else ""
+        _emit_call(call, state.root, guard, state, return_label=rl)
+
+
+def _emit_call(
+    call: ast.Call,
+    root: str,
+    guard: str,
+    state: _State,
+    *,
+    return_label: str,
+) -> None:
+    sender, receiver, label = _resolve_call(call, root)
+    state.ensure_lifeline(receiver)
+    state.ensure_lifeline(sender)
+    state.messages.append(
+        Message(sender=sender, receiver=receiver, label=label, guard=guard)
+    )
+    state.messages.append(
+        Message(
+            sender=receiver,
+            receiver=sender,
+            label=return_label,
+            is_return=True,
+            guard=guard,
+        )
+    )
+
+
+def _calls_post_order(node: ast.AST):
+    """Yield Call nodes inside `node` in inner-first (post-order) order."""
+    for child in ast.iter_child_nodes(node):
+        yield from _calls_post_order(child)
+    if isinstance(node, ast.Call):
+        yield node
+
+
+def _safe_unparse(node: ast.AST) -> str:
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def _statements_in_range(tree: ast.Module, start: int, end: int) -> list[ast.stmt]:
+    out: list[ast.stmt] = []
+    candidates: list[tuple[int, list[ast.stmt]]] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            f_start = getattr(node, "lineno", 0)
+            if not node.body:
+                continue
+            body_end = max(
+                (getattr(s, "end_lineno", getattr(s, "lineno", 0)) or 0)
+                for s in node.body
+            )
+            if f_start < start and body_end >= start:
+                stmts = [s for s in node.body if start < getattr(s, "lineno", 0) < end]
+                if stmts:
+                    candidates.append((f_start, stmts))
+    if candidates:
+        candidates.sort(key=lambda c: c[0])
+        return candidates[-1][1]
+    for stmt in tree.body:
+        s_start = getattr(stmt, "lineno", 0)
+        if start < s_start < end:
+            out.append(stmt)
+    return out
+
+
+def _resolve_call(call: ast.Call, root: str) -> tuple[str, str, str]:
+    func = call.func
+    if isinstance(func, ast.Attribute):
+        receiver_name = _receiver_name(func.value, root)
+        label = func.attr + "()"
+        return root, receiver_name, label
+    if isinstance(func, ast.Name):
+        return root, "module", f"{func.id}()"
+    try:
+        return root, "module", f"{ast.unparse(func)}()"
+    except Exception:
+        return root, "module", "call()"
+
+
+def _receiver_name(node: ast.AST, root: str) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        try:
+            return ast.unparse(node)
+        except Exception:
+            return node.attr
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return "obj"

code_constraints/reference/__init__.py

@@ -0,0 +1,15 @@
+"""The architecture-reference gate.
+
+A dedicated structural comparator (decoupled from `code_constraints.core.diff`
+and from the `code_constraints.lint` / `code_constraints.enforce` engines) that
+reports every structural deviation of the current code from a stored reference
+model. Driven by the `reference-architecture` rule type in `.cdec/rules.yaml`,
+which is what `cdec check` runs.
+"""
+
+from __future__ import annotations
+
+from code_constraints.reference.compare import Deviation, compare_to_reference
+from code_constraints.reference.report import format_human, to_json
+
+__all__ = ["Deviation", "compare_to_reference", "format_human", "to_json"]

code_constraints/reference/compare.py

@@ -0,0 +1,356 @@
+"""Structural comparator for the `reference-architecture` rule.
+
+Decoupled from `code_constraints.core.diff` on purpose. `diff_projects` matches members by
+`signature()` and only marks a matched member CHANGED when its *rule tags* differ,
+so it is blind to visibility / static / abstract / readonly changes and to class
+`kind` changes. The reference gate must reject all of those, so it walks both
+`Project`s itself and reports every structural deviation as a `Deviation`.
+
+Matching strategy (chosen so the human messages read as "changed", not
+"removed + added"):
+- classes      -> by qualified name
+- attributes   -> by name within the class
+- operations   -> by name within the class, with full-signature fallback for
+                  overload groups (C# can declare several operations per name)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from code_constraints.core.model import Attribute, Class, Operation, Project
+
+
+@dataclass
+class Deviation:
+    """A single structural difference between the reference and current code.
+
+    `category` is a stable machine id (e.g. "attribute-changed"); `member` is the
+    attribute/operation signature when the deviation is member-level, else None.
+    `old` / `new` carry the differing values for machine consumers (None for pure
+    add/remove deviations).
+    """
+
+    category: str
+    qualified_name: str
+    message: str
+    member: str | None = None
+    old: str | None = None
+    new: str | None = None
+
+    def sort_key(self) -> tuple[str, str, str]:
+        return (self.qualified_name, self.member or "", self.category)
+
+
+def compare_to_reference(reference: Project, current: Project) -> list[Deviation]:
+    """Return every structural deviation of `current` from `reference`.
+
+    Raises ValueError when the two projects are in different source languages
+    (matching `diff_projects`' guard), since a cross-language comparison is
+    meaningless.
+    """
+    if reference.source_language != current.source_language:
+        raise ValueError(
+            f"cannot compare across languages: "
+            f"{reference.source_language} -> {current.source_language}"
+        )
+
+    out: list[Deviation] = []
+    ref_by_qn = {c.qualified_name: c for c in reference.iter_classes()}
+    cur_by_qn = {c.qualified_name: c for c in current.iter_classes()}
+
+    for qn, cur_cls in cur_by_qn.items():
+        if qn not in ref_by_qn:
+            out.append(
+                Deviation(
+                    category="class-added",
+                    qualified_name=qn,
+                    message=f"Class '{qn}' was added.",
+                )
+            )
+        else:
+            out.extend(_compare_class(ref_by_qn[qn], cur_cls))
+
+    for qn in ref_by_qn:
+        if qn not in cur_by_qn:
+            out.append(
+                Deviation(
+                    category="class-removed",
+                    qualified_name=qn,
+                    message=f"Class '{qn}' was removed.",
+                )
+            )
+
+    out.sort(key=Deviation.sort_key)
+    return out
+
+
+def _compare_class(ref: Class, cur: Class) -> list[Deviation]:
+    out: list[Deviation] = []
+    qn = cur.qualified_name
+
+    if ref.kind != cur.kind:
+        out.append(
+            Deviation(
+                category="class-kind-changed",
+                qualified_name=qn,
+                message=f"Class '{qn}' kind changed from {ref.kind} to {cur.kind}.",
+                old=ref.kind,
+                new=cur.kind,
+            )
+        )
+
+    ref_bases, cur_bases = sorted(ref.bases), sorted(cur.bases)
+    if ref_bases != cur_bases:
+        out.append(
+            Deviation(
+                category="class-bases-changed",
+                qualified_name=qn,
+                message=(
+                    f"Class '{qn}' base classes changed from "
+                    f"[{', '.join(ref_bases)}] to [{', '.join(cur_bases)}]."
+                ),
+                old=", ".join(ref_bases),
+                new=", ".join(cur_bases),
+            )
+        )
+
+    out.extend(_compare_attributes(qn, ref.attributes, cur.attributes))
+    out.extend(_compare_operations(qn, ref.operations, cur.operations))
+    return out
+
+
+# ---------- attributes ----------
+
+def _compare_attributes(
+    qn: str, ref: list[Attribute], cur: list[Attribute]
+) -> list[Deviation]:
+    out: list[Deviation] = []
+    ref_by_name = {a.name: a for a in ref}
+    cur_by_name = {a.name: a for a in cur}
+
+    for name, a in cur_by_name.items():
+        if name not in ref_by_name:
+            out.append(
+                Deviation(
+                    category="attribute-added",
+                    qualified_name=qn,
+                    member=a.signature(),
+                    message=f"Property '{a.signature()}' was added to '{qn}'.",
+                )
+            )
+        else:
+            out.extend(_compare_attribute_pair(qn, ref_by_name[name], a))
+
+    for name, a in ref_by_name.items():
+        if name not in cur_by_name:
+            out.append(
+                Deviation(
+                    category="attribute-removed",
+                    qualified_name=qn,
+                    member=a.signature(),
+                    message=f"Property '{a.signature()}' was removed from '{qn}'.",
+                )
+            )
+    return out
+
+
+def _compare_attribute_pair(qn: str, ref: Attribute, cur: Attribute) -> list[Deviation]:
+    changes = _diff_fields(
+        ref,
+        cur,
+        [
+            ("type", "type"),
+            ("visibility", "access level"),
+            ("is_static", "static"),
+            ("is_readonly", "readonly"),
+            ("default", "default value"),
+        ],
+    )
+    if not changes:
+        return []
+    summary = "; ".join(desc for desc, _, _ in changes)
+    return [
+        Deviation(
+            category="attribute-changed",
+            qualified_name=qn,
+            member=cur.signature(),
+            message=f"Property '{cur.name}' on '{qn}' changed: {summary}.",
+            old="; ".join(f"{label}={old}" for label, old, _ in changes),
+            new="; ".join(f"{label}={new}" for label, _, new in changes),
+        )
+    ]
+
+
+# ---------- operations ----------
+
+def _compare_operations(
+    qn: str, ref: list[Operation], cur: list[Operation]
+) -> list[Deviation]:
+    out: list[Deviation] = []
+    ref_by_name = _group_by_name(ref)
+    cur_by_name = _group_by_name(cur)
+
+    for name, cur_ops in cur_by_name.items():
+        ref_ops = ref_by_name.get(name)
+        if not ref_ops:
+            for op in cur_ops:
+                out.append(
+                    Deviation(
+                        category="operation-added",
+                        qualified_name=qn,
+                        member=op.signature(),
+                        message=f"Method '{op.signature()}' was added to '{qn}'.",
+                    )
+                )
+            continue
+        if len(ref_ops) == 1 and len(cur_ops) == 1:
+            out.extend(_compare_operation_pair(qn, ref_ops[0], cur_ops[0]))
+        else:
+            out.extend(_compare_operation_overloads(qn, ref_ops, cur_ops))
+
+    for name, ref_ops in ref_by_name.items():
+        if name not in cur_by_name:
+            for op in ref_ops:
+                out.append(
+                    Deviation(
+                        category="operation-removed",
+                        qualified_name=qn,
+                        member=op.signature(),
+                        message=f"Method '{op.signature()}' was removed from '{qn}'.",
+                    )
+                )
+    return out
+
+
+def _compare_operation_overloads(
+    qn: str, ref_ops: list[Operation], cur_ops: list[Operation]
+) -> list[Deviation]:
+    """Overload group (>1 op sharing a name): match on full signature so we can
+    only report clean add/remove — a modifier-only change on one overload still
+    surfaces because the signature is unchanged yet the pair compares equal here,
+    so fall through to a per-signature modifier check."""
+    out: list[Deviation] = []
+    ref_by_sig = {o.signature(): o for o in ref_ops}
+    cur_by_sig = {o.signature(): o for o in cur_ops}
+    for sig, op in cur_by_sig.items():
+        if sig not in ref_by_sig:
+            out.append(
+                Deviation(
+                    category="operation-added",
+                    qualified_name=qn,
+                    member=sig,
+                    message=f"Method '{sig}' was added to '{qn}'.",
+                )
+            )
+        else:
+            out.extend(_compare_operation_modifiers(qn, ref_by_sig[sig], op))
+    for sig, op in ref_by_sig.items():
+        if sig not in cur_by_sig:
+            out.append(
+                Deviation(
+                    category="operation-removed",
+                    qualified_name=qn,
+                    member=sig,
+                    message=f"Method '{sig}' was removed from '{qn}'.",
+                )
+            )
+    return out
+
+
+def _compare_operation_pair(qn: str, ref: Operation, cur: Operation) -> list[Deviation]:
+    out: list[Deviation] = []
+    ref_params = _params_repr(ref)
+    cur_params = _params_repr(cur)
+    if ref_params != cur_params:
+        out.append(
+            Deviation(
+                category="operation-signature-changed",
+                qualified_name=qn,
+                member=cur.signature(),
+                message=(
+                    f"Method '{cur.name}' on '{qn}' signature changed from "
+                    f"({ref_params}) to ({cur_params})."
+                ),
+                old=ref_params,
+                new=cur_params,
+            )
+        )
+    if ref.return_type != cur.return_type:
+        out.append(
+            Deviation(
+                category="operation-return-type-changed",
+                qualified_name=qn,
+                member=cur.signature(),
+                message=(
+                    f"Method '{cur.name}' on '{qn}' return type changed from "
+                    f"'{ref.return_type}' to '{cur.return_type}'."
+                ),
+                old=ref.return_type,
+                new=cur.return_type,
+            )
+        )
+    out.extend(_compare_operation_modifiers(qn, ref, cur))
+    return out
+
+
+def _compare_operation_modifiers(qn: str, ref: Operation, cur: Operation) -> list[Deviation]:
+    changes = _diff_fields(
+        ref,
+        cur,
+        [
+            ("visibility", "access level"),
+            ("is_static", "static"),
+            ("is_abstract", "abstract"),
+        ],
+    )
+    if not changes:
+        return []
+    summary = "; ".join(desc for desc, _, _ in changes)
+    return [
+        Deviation(
+            category="operation-modifier-changed",
+            qualified_name=qn,
+            member=cur.signature(),
+            message=f"Method '{cur.name}' on '{qn}' modifiers changed: {summary}.",
+            old="; ".join(f"{label}={old}" for label, old, _ in changes),
+            new="; ".join(f"{label}={new}" for label, _, new in changes),
+        )
+    ]
+
+
+# ---------- shared helpers ----------
+
+def _diff_fields(ref, cur, fields: list[tuple[str, str]]):
+    """Return [(human_desc, old_str, new_str)] for each field that differs.
+
+    `fields` is a list of (attr_name, label). Enum/None values are stringified.
+    """
+    changes = []
+    for attr_name, label in fields:
+        old_val = _scalar(getattr(ref, attr_name))
+        new_val = _scalar(getattr(cur, attr_name))
+        if old_val != new_val:
+            changes.append((f"{label} {old_val} -> {new_val}", old_val, new_val))
+    return changes
+
+
+def _scalar(value) -> str:
+    if value is None:
+        return "none"
+    # Visibility / other str-enums carry a readable .value.
+    return str(getattr(value, "value", value))
+
+
+def _params_repr(op: Operation) -> str:
+    return ", ".join(
+        f"{p.name}:{p.type}" + (f"={p.default}" if p.default is not None else "")
+        for p in op.parameters
+    )
+
+
+def _group_by_name(ops: list[Operation]) -> dict[str, list[Operation]]:
+    grouped: dict[str, list[Operation]] = {}
+    for op in ops:
+        grouped.setdefault(op.name, []).append(op)
+    return grouped

code_constraints/reference/report.py

@@ -0,0 +1,38 @@
+"""Human + JSON formatting for reference-gate deviations."""
+
+from __future__ import annotations
+
+from code_constraints.reference.compare import Deviation
+
+
+def format_human(deviations: list[Deviation]) -> str:
+    """Render deviations as a readable, CI-friendly report, grouped by class."""
+    if not deviations:
+        return "no deviations -- the codebase matches the reference.\n"
+
+    lines = [f"{len(deviations)} deviation(s) from the reference:"]
+    current_qn: str | None = None
+    for d in sorted(deviations, key=Deviation.sort_key):
+        if d.qualified_name != current_qn:
+            current_qn = d.qualified_name
+            lines.append(f"\n  {current_qn}")
+        lines.append(f"    - [{d.category}] {d.message}")
+    return "\n".join(lines) + "\n"
+
+
+def to_json(deviations: list[Deviation]) -> dict:
+    """Machine-readable report for pipelines."""
+    return {
+        "deviation_count": len(deviations),
+        "deviations": [
+            {
+                "category": d.category,
+                "qualifiedName": d.qualified_name,
+                "member": d.member,
+                "message": d.message,
+                "old": d.old,
+                "new": d.new,
+            }
+            for d in sorted(deviations, key=Deviation.sort_key)
+        ],
+    }

code_constraints/svelte/__init__.py

@@ -0,0 +1,3 @@
+from code_constraints.svelte.parser import parse_project
+
+__all__ = ["parse_project"]