codegraph-ir 0.1.0__py3-none-any.whl

cgir/report/impact.py

@@ -0,0 +1,234 @@
+"""Change-impact / blast-radius analysis — the forward-looking companion
+to :mod:`cgir.report.diff`.
+
+``diff`` is retrospective ("what changed?"). ``impact`` is predictive:
+*before* you (or an agent) touch a component, what does changing it put at
+risk? The answer is the transitive **upstream** (caller) closure — every
+component whose behaviour depends on this one — plus the surface that
+closure reaches: which **entrypoints** sit above it, and which **tests** to
+run (union of ``covered_by`` over the target and everything affected).
+
+``compute_impact`` is the worst case: it assumes the change could affect
+anything upstream. ``compute_typed_impact`` narrows that by *what actually
+changed about the contract*, because not every change propagates the same
+way:
+
+* **body-only** (no contract field changed) — callers are contract-safe;
+  reach ``none``, only the target's own tests matter.
+* **signature / outputs** — an interface break the *direct* call sites must
+  adapt to, but which does not inherently ripple past them; reach
+  ``direct``.
+* **effects / purity / kind** — semantic taint that flows *up* the call
+  graph (a caller of something newly effectful is itself newly effectful);
+  reach ``transitive`` — the full closure.
+
+The reach model is a deliberate, documented heuristic, not a proof: it
+mirrors how the effect/purity analyses actually propagate. Pure over
+ComponentSpecs, so it drives both the CLI (``cgir impact``) and the MCP
+tool an agent calls before — and after — an edit.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from cgir.ir.component_spec import ComponentSpec
+
+# Contract fields whose change taints callers transitively vs. only directly.
+_TRANSITIVE_FIELDS = frozenset({"effects", "purity", "kind"})
+_DIRECT_FIELDS = frozenset({"signature", "outputs", "inputs"})
+
+
+def _callers_map(
+    specs: list[ComponentSpec], by_id: dict[str, ComponentSpec]
+) -> dict[str, set[str]]:
+    """Reverse the CALLS relation: callee id -> ids that call it."""
+    callers: dict[str, set[str]] = {}
+    for spec in specs:
+        for callee in spec.calls:
+            if callee in by_id:
+                callers.setdefault(callee, set()).add(spec.id)
+    return callers
+
+
+def _upstream_closure(callers: dict[str, set[str]], target_id: str) -> set[str]:
+    """Transitive caller closure of ``target_id`` (cycle-safe, target excluded)."""
+    affected: set[str] = set()
+    queue = [target_id]
+    while queue:
+        node = queue.pop()
+        for caller in callers.get(node, ()):
+            if caller != target_id and caller not in affected:
+                affected.add(caller)
+                queue.append(caller)
+    return affected
+
+
+def _is_test_spec(spec: ComponentSpec) -> bool:
+    """Mirror of ``slicer._is_test_node`` at the spec level."""
+    if spec.id.rsplit(".", 1)[-1].startswith("test_"):
+        return True
+    if spec.trace:
+        path = spec.trace[0].rsplit(":", 1)[0].replace("\\", "/")
+        parts = path.split("/")
+        stem = parts[-1].rsplit(".", 1)[0]
+        return "tests" in parts[:-1] or stem.startswith("test_") or stem.endswith("_test")
+    return False
+
+
+def _surface(
+    by_id: dict[str, ComponentSpec], target_id: str, affected: set[str]
+) -> tuple[list[str], list[dict[str, Any]], list[str]]:
+    """Partition + derive: (affected code, entrypoints at risk, tests to run).
+
+    Test components in the caller closure are not "affected code" — they are
+    literally tests to run, so they move into the tests list (this also
+    catches transitive test callers never linked via ``covered_by``).
+    """
+    code = {sid for sid in affected if not _is_test_spec(by_id[sid])}
+    scope = sorted(code | {target_id})
+    entrypoints = [
+        {"id": sid, "entrypoint": by_id[sid].entrypoint} for sid in scope if by_id[sid].entrypoint
+    ]
+    tests: set[str] = set(by_id[target_id].covered_by)
+    tests |= affected - code
+    for sid in code:
+        tests |= set(by_id[sid].covered_by)
+    return sorted(code), entrypoints, sorted(tests)
+
+
+def compute_impact(specs: list[ComponentSpec], target_id: str) -> dict[str, Any]:
+    """Worst-case blast radius of changing ``target_id`` — pure, JSON-able."""
+    by_id = {s.id: s for s in specs}
+    if target_id not in by_id:
+        raise KeyError(target_id)
+    callers = _callers_map(specs, by_id)
+    affected = _upstream_closure(callers, target_id)
+    code, entrypoints, tests = _surface(by_id, target_id, affected)
+    return {
+        "target": target_id,
+        "direct_callers": sorted(callers.get(target_id, set())),
+        "affected": code,
+        "entrypoints": entrypoints,
+        "tests": tests,
+    }
+
+
+def _reach(changed_fields: set[str]) -> str:
+    if changed_fields & _TRANSITIVE_FIELDS:
+        return "transitive"
+    if changed_fields & _DIRECT_FIELDS:
+        return "direct"
+    return "none"
+
+
+def compute_typed_impact(
+    specs: list[ComponentSpec], target_id: str, changed_fields: Iterable[str]
+) -> dict[str, Any]:
+    """Blast radius narrowed by *which* contract fields changed.
+
+    ``changed_fields`` is the set of drifted contract fields — e.g. the keys
+    of a :func:`cgir.report.diff.compute_diff` change entry or a
+    ``VerifyResult.drift``. An empty set means a body-only edit.
+    """
+    by_id = {s.id: s for s in specs}
+    if target_id not in by_id:
+        raise KeyError(target_id)
+    delta = set(changed_fields)
+    reach = _reach(delta)
+    callers = _callers_map(specs, by_id)
+    direct = sorted(callers.get(target_id, set()))
+
+    if reach == "transitive":
+        affected = _upstream_closure(callers, target_id)
+    elif reach == "direct":
+        affected = set(direct)
+    else:
+        affected = set()
+
+    code, entrypoints, tests = _surface(by_id, target_id, affected)
+    return {
+        "target": target_id,
+        "changed_fields": sorted(delta),
+        "reach": reach,
+        "direct_callers": direct,
+        "affected": code,
+        "entrypoints": entrypoints,
+        "tests": tests,
+    }
+
+
+_REACH_NOTE = {
+    "none": "body-only change — no contract drift, callers are unaffected",
+    "direct": "interface change — direct call sites must adapt",
+    "transitive": "effect/purity change — taint flows up the call graph",
+}
+
+
+def _render(data: dict[str, Any]) -> str:
+    target = data["target"]
+    affected = data["affected"]
+    entrypoints = data["entrypoints"]
+    tests = data["tests"]
+    reach = data.get("reach")
+
+    lines: list[str] = [f"# impact of changing {target}", ""]
+    if reach is not None:
+        fields = ", ".join(data["changed_fields"]) or "(none)"
+        lines.append(f"contract delta: {fields}  →  reach: {reach}")
+        lines.append(f"  {_REACH_NOTE[reach]}")
+        lines.append("")
+    lines.append(
+        f"{len(affected)} component(s) affected · "
+        f"{len(entrypoints)} entrypoint(s) at risk · "
+        f"{len(tests)} test(s) to run"
+    )
+
+    lines.append("")
+    lines.append(f"affected components ({len(affected)}):")
+    if affected:
+        direct = set(data["direct_callers"])
+        for sid in affected:
+            lines.append(f"  {'← direct' if sid in direct else '  ⋯    '}  {sid}")
+    elif reach == "none" and data["direct_callers"]:
+        lines.append(f"  (none contract-affected; {len(data['direct_callers'])} call it)")
+    else:
+        lines.append("  (none — nothing calls this)")
+
+    lines.append("")
+    lines.append(f"entrypoints at risk ({len(entrypoints)}):")
+    if entrypoints:
+        for e in entrypoints:
+            lines.append(f"  ! {e['entrypoint']}  ({e['id']})")
+    else:
+        lines.append("  (none reachable)")
+
+    lines.append("")
+    lines.append(f"tests to run ({len(tests)}):")
+    if tests:
+        lines.extend(f"  • {t}" for t in tests)
+    else:
+        lines.append("  (no linked tests — this change is unguarded)")
+
+    return "\n".join(lines) + "\n"
+
+
+def render_impact(specs: list[ComponentSpec], target_id: str) -> str:
+    """Human summary of the worst-case blast radius."""
+    return _render(compute_impact(specs, target_id))
+
+
+def render_typed_impact(
+    specs: list[ComponentSpec], target_id: str, changed_fields: Iterable[str]
+) -> str:
+    """Human summary of the blast radius narrowed by the contract delta."""
+    return _render(compute_typed_impact(specs, target_id, changed_fields))
+
+
+__all__ = [
+    "compute_impact",
+    "compute_typed_impact",
+    "render_impact",
+    "render_typed_impact",
+]

cgir/report/lint.py

@@ -0,0 +1,84 @@
+"""cgir lint — semantic architecture rules over the ComponentSpec index.
+
+Import linters (Tach, import-linter) constrain *imports*. CGIR constrains
+*meaning*: which components may carry which effects, what kind they must be,
+and what they may call — checks an import graph can't express because it
+doesn't know a function touches the network or routes to the DB layer.
+
+A rule is scoped by an ``in`` id-glob and carries one predicate:
+
+* ``forbid-effect``: matched components must not carry these effect tags
+* ``require-kind``: matched components must be this component kind
+* ``forbid-call``: matched components must not call components whose id
+  matches this glob (a semantic layer boundary over resolved CALLS)
+
+Rules live in ``cgir.toml`` as a ``[[rule]]`` array; the checker itself is
+pure over specs so it is trivially testable and CI-friendly.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Any
+
+from cgir.ir.component_spec import ComponentSpec
+
+
+@dataclass(slots=True)
+class LintViolation:
+    rule: str
+    component: str
+    detail: str
+
+
+def load_rules(config_path: Path) -> list[dict[str, Any]]:
+    """Read ``[[rule]]`` entries from a ``cgir.toml``-style config."""
+    data = tomllib.loads(config_path.read_text())
+    rules = data.get("rule", [])
+    return list(rules) if isinstance(rules, list) else []
+
+
+def lint(specs: list[ComponentSpec], rules: list[dict[str, Any]]) -> list[LintViolation]:
+    violations: list[LintViolation] = []
+    known = {s.id for s in specs}
+    for rule in rules:
+        name = str(rule.get("name", "rule"))
+        scope = str(rule.get("in", "*"))
+        matched = [s for s in specs if fnmatch(s.id, scope)]
+
+        if "forbid-effect" in rule:
+            forbidden = set(rule["forbid-effect"])
+            for spec in matched:
+                hit = sorted(forbidden & set(spec.effects))
+                if hit:
+                    violations.append(
+                        LintViolation(name, spec.id, f"has forbidden effect(s): {', '.join(hit)}")
+                    )
+        if "require-kind" in rule:
+            want = str(rule["require-kind"])
+            for spec in matched:
+                if spec.kind.value != want:
+                    violations.append(
+                        LintViolation(name, spec.id, f"is {spec.kind.value}, must be {want}")
+                    )
+        if "forbid-call" in rule:
+            target_glob = str(rule["forbid-call"])
+            for spec in matched:
+                for callee in spec.calls:
+                    if callee in known and fnmatch(callee, target_glob):
+                        violations.append(
+                            LintViolation(name, spec.id, f"calls forbidden target: {callee}")
+                        )
+    return violations
+
+
+def render_lint(violations: list[LintViolation]) -> str:
+    if not violations:
+        return "no architecture-rule violations\n"
+    lines = [f"{len(violations)} architecture-rule violation(s):"]
+    for v in violations:
+        lines.append(f"  ! [{v.rule}] {v.component} {v.detail}")
+    return "\n".join(lines) + "\n"

cgir/report/pack.py

@@ -0,0 +1,271 @@
+"""Context packer — the minimal bundle for working on one component.
+
+This is the product's core loop (Code-IR.md: rewrite/audit "without
+holding the whole repo in context"): given a target component, assemble
+what an LLM needs and nothing else, in priority order:
+
+1. the target — spec fields + source text when available
+2. its callees, as *interfaces only* (signature, kind, effects, returns)
+3. its callers — how it's used, with entrypoints ("how the outside
+   world reaches this")
+4. the types it constructs
+
+``budget`` is an approximate token budget (chars / 4). Lower-priority
+sections are dropped whole to fit, and every drop is recorded under
+``omitted`` — the bundle never silently lies about completeness.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from cgir.ir.component_spec import ComponentSpec
+
+DEFAULT_BUDGET = 4000
+
+# Dropped in this order to fit budget: types, tests & the target contract
+# are the last to go (they're what makes a context-free rewrite possible).
+_SECTION_PRIORITY = ("constructs", "callers", "callees", "context", "tests", "types")
+
+_BUILTIN_TYPES = frozenset(
+    {
+        "int",
+        "float",
+        "str",
+        "bool",
+        "bytes",
+        "None",
+        "Any",
+        "list",
+        "dict",
+        "set",
+        "tuple",
+        "frozenset",
+        "object",
+        "Optional",
+        "Union",
+        "Iterable",
+        "Iterator",
+        "Sequence",
+        "Mapping",
+        "Callable",
+        "Type",
+        "Awaitable",
+        "Coroutine",
+        "AsyncIterator",
+    }
+)
+_TYPE_TOKEN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+def referenced_type_names(spec: ComponentSpec) -> set[str]:
+    """Non-builtin type identifiers the component's contract names.
+
+    Pulled from the return type, constructed classes, and parameter
+    annotations — the types an implementer must know the shape of.
+    """
+    names: set[str] = set()
+    for output in spec.outputs:
+        names |= _type_tokens(output)
+    for construct in spec.constructs:
+        names.add(construct.rsplit(".", 1)[-1])
+    for _, annotation in _param_items(spec.signature):
+        if annotation:
+            names |= _type_tokens(annotation)
+    return {n for n in names if n not in _BUILTIN_TYPES}
+
+
+def _type_tokens(annotation: str) -> set[str]:
+    return set(_TYPE_TOKEN.findall(annotation))
+
+
+def _param_items(signature: str | None) -> list[tuple[str, str | None]]:
+    if not signature or "(" not in signature or ")" not in signature:
+        return []
+    inner = signature[signature.index("(") + 1 : signature.rindex(")")]
+    items: list[tuple[str, str | None]] = []
+    depth, current = 0, ""
+    for ch in inner + ",":
+        if ch in "([{":
+            depth += 1
+        elif ch in ")]}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            name, _, annotation = current.partition(":")
+            annotation = annotation.split("=", 1)[0].strip()
+            items.append((name.strip().lstrip("*"), annotation or None))
+            current = ""
+        else:
+            current += ch
+    return items
+
+
+def build_pack(
+    specs: list[ComponentSpec],
+    target_id: str,
+    source: str | None = None,
+    budget: int = DEFAULT_BUDGET,
+    types: dict[str, str] | None = None,
+    tests: dict[str, str] | None = None,
+    context: dict[str, str] | None = None,
+    receivers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    by_id = {s.id: s for s in specs}
+    target = by_id[target_id]  # KeyError for unknown targets, by design
+
+    callees = []
+    for callee in target.calls:
+        if callee not in by_id:
+            continue
+        entry = _interface(by_id[callee])
+        # A DI callee is reached through an injected field; naming it lets a
+        # rewriter reproduce the call (and thus the effect contract) instead
+        # of guessing the field name.
+        if receivers and callee in receivers:
+            entry["receiver"] = receivers[callee]
+        callees.append(entry)
+    callers = [_interface(s) for s in specs if target_id in s.calls]
+    type_defs = [{"name": name, "source": src} for name, src in sorted((types or {}).items())]
+    test_defs = [{"id": tid, "source": src} for tid, src in sorted((tests or {}).items())]
+    context_defs = [{"name": n, "source": src} for n, src in sorted((context or {}).items())]
+    pack: dict[str, Any] = {
+        "target": {
+            "id": target.id,
+            "kind": target.kind.value,
+            "signature": target.signature,
+            "inputs": target.inputs,
+            "outputs": target.outputs,
+            "effects": target.effects,
+            "purity": target.purity,
+            "entrypoint": target.entrypoint,
+            "doc": target.doc,
+            "raises": target.raises,
+            "trace": target.trace,
+            "source": source,
+        },
+        "types": type_defs,
+        "context": context_defs,
+        "tests": test_defs,
+        "callees": callees,
+        "callers": callers,
+        "constructs": list(target.constructs),
+        "omitted": [],
+    }
+
+    for section in _SECTION_PRIORITY:
+        if _estimate_tokens(pack) <= budget:
+            break
+        if pack[section]:
+            pack[section] = []
+            pack["omitted"].append(section)
+    return pack
+
+
+def _interface(spec: ComponentSpec) -> dict[str, Any]:
+    return {
+        "id": spec.id,
+        "kind": spec.kind.value,
+        "signature": spec.signature,
+        "outputs": spec.outputs,
+        "effects": spec.effects,
+        "entrypoint": spec.entrypoint,
+    }
+
+
+def _estimate_tokens(pack: dict[str, Any]) -> int:
+    return len(str(pack)) // 4
+
+
+def render_pack(pack: dict[str, Any]) -> str:
+    target = pack["target"]
+    lines: list[str] = [f"# {target['id']}", ""]
+    lines.append(
+        f"`{target['signature']}` — {target['kind']}"
+        + (f", purity {target['purity']}" if target["purity"] is not None else "")
+    )
+    if target["entrypoint"]:
+        lines.append(f"Entrypoint: **{target['entrypoint']}**")
+    if target["effects"]:
+        lines.append(f"Effects: {', '.join(target['effects'])}")
+    if target["outputs"]:
+        lines.append(f"Returns: {', '.join(target['outputs'])}")
+    if target.get("raises"):
+        lines.append(f"Raises: {', '.join(target['raises'])}")
+    if target["trace"]:
+        lines.append(f"Source location: {target['trace'][0]}")
+    if target.get("doc"):
+        lines.append("")
+        lines.append(f"> {target['doc'].strip().splitlines()[0]}")
+    if target["source"]:
+        lines.append("")
+        lines.append("```python")
+        lines.append(target["source"].rstrip("\n"))
+        lines.append("```")
+
+    if pack.get("types"):
+        lines.append("")
+        lines.append("## Types")
+        lines.append("Shapes the target's contract references — match these exactly.")
+        for tdef in pack["types"]:
+            lines.append("")
+            lines.append("```python")
+            lines.append(tdef["source"].rstrip("\n"))
+            lines.append("```")
+
+    if pack.get("context"):
+        lines.append("")
+        lines.append("## Referenced module definitions")
+        lines.append("Constants and helpers the body uses — use them, don't redefine.")
+        for cdef in pack["context"]:
+            lines.append("")
+            lines.append("```python")
+            lines.append(cdef["source"].rstrip("\n"))
+            lines.append("```")
+
+    if pack.get("tests"):
+        lines.append("")
+        lines.append("## Tests (behavior contract)")
+        lines.append("The implementation must satisfy these.")
+        for tdef in pack["tests"]:
+            lines.append("")
+            lines.append(f"```python  # {tdef['id']}")
+            lines.append(tdef["source"].rstrip("\n"))
+            lines.append("```")
+
+    if pack["callees"]:
+        lines.append("")
+        lines.append("## Callees (interfaces)")
+        lines.append("Do not modify these; call them as specified.")
+        lines.append("")
+        for callee in pack["callees"]:
+            lines.append(_interface_line(callee))
+    if pack["callers"]:
+        lines.append("")
+        lines.append("## Callers")
+        lines.append("These depend on the target's current contract.")
+        lines.append("")
+        for caller in pack["callers"]:
+            lines.append(_interface_line(caller))
+    if pack["constructs"]:
+        lines.append("")
+        lines.append("## Constructs")
+        lines.extend(f"- {type_name}" for type_name in pack["constructs"])
+    if pack["omitted"]:
+        lines.append("")
+        lines.append(f"_Omitted for budget: {', '.join(pack['omitted'])}_")
+    return "\n".join(lines) + "\n"
+
+
+def _interface_line(entry: dict[str, Any]) -> str:
+    receiver = entry.get("receiver")
+    call = f"{receiver}.{entry['signature']}" if receiver else entry["signature"]
+    parts = [f"- `{call}`", f"({entry['id']}, {entry['kind']}"]
+    if entry["effects"]:
+        parts[-1] += f", effects: {','.join(entry['effects'])}"
+    parts[-1] += ")"
+    if entry["outputs"]:
+        parts.append(f"-> {entry['outputs'][0]}")
+    if entry["entrypoint"]:
+        parts.append(f"[{entry['entrypoint']}]")
+    return " ".join(parts)