codegraph-ir 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

cgir/__init__.py

@@ -3,4 +3,4 @@
 See ``Code-IR.md`` at the repo root for the product specification.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

cgir/analyses/cfg.py

@@ -79,7 +79,13 @@ def build(graph: RepoGraph, repo_path: Path, adapter: LanguageAdapter | None = N
         body = file_adapter.function_body(func_ts)
         if body is None:
             continue
-        builder = _CFGBuilder(graph=graph, owner=func, source=source, adapter=file_adapter)
+        builder = _CFGBuilder(
+            graph=graph,
+            owner=func,
+            source=source,
+            adapter=file_adapter,
+            global_names=file_adapter.global_declared_names(func_ts, source),
+        )
         builder.build_block(body, predecessors=[func.id], controller=None)
 
 
@@ -89,6 +95,9 @@ class _CFGBuilder:
     owner: Node
     source: bytes
     adapter: LanguageAdapter
+    # names declared global/nonlocal in this function: writes to them mutate
+    # outer state and are recorded as `mutates`, not local `writes`.
+    global_names: set[str] = field(default_factory=set)
     _counter: int = field(default=0, init=False)
 
     def build_block(
@@ -102,6 +111,11 @@ class _CFGBuilder:
 
     def build_stmt(self, ts_node: TSNode, preds: list[str], controller: str | None) -> list[str]:
         desc = self.adapter.describe_statement(ts_node, self.source)
+        if isinstance(desc, AssignDesc) and self.global_names:
+            outer = [w for w in desc.writes if w in self.global_names]
+            if outer:
+                desc.writes = [w for w in desc.writes if w not in self.global_names]
+                desc.mutates = list(desc.mutates) + outer
         if isinstance(desc, BranchDesc):
             return self._build_branch(ts_node, desc, preds, controller)
         if isinstance(desc, LoopDesc):

cgir/analyses/coverage_link.py

@@ -0,0 +1,152 @@
+"""Coverage-grounded test linkage — measured ``covered_by``, not inferred.
+
+Static call-edge linkage says a test *statically references* a component;
+coverage contexts say a test *actually executed its lines*. When per-test
+contexts exist (pytest-cov ``--cov-context=test`` or coverage.py's
+``dynamic_context = test_function``), the pipeline maps covered lines onto
+component spans and unions the result with static linkage: coverage adds
+tests reached through indirection (fixtures, integration paths); static
+keeps tests the coverage run skipped.
+
+Sources, in preference order:
+* ``.coverage`` — coverage.py's SQLite store, read via stdlib sqlite3. The
+  line data is a "numbits" blob (bit N set = line N covered); the format is
+  internal to coverage.py but has been stable for years — decode failures
+  degrade gracefully to no coverage linkage.
+* ``coverage.json`` — ``coverage json --show-contexts`` output.
+
+No new dependency; no coverage data → identical behavior to before.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+# rel_path -> normalized test id -> covered line numbers
+CoverageData = dict[str, dict[str, set[int]]]
+
+
+def numbits_to_lines(blob: bytes) -> set[int]:
+    """Decode coverage.py's numbits: bit N set means line N covered."""
+    lines: set[int] = set()
+    for byte_index, byte in enumerate(blob):
+        for bit in range(8):
+            if byte & (1 << bit):
+                lines.add(byte_index * 8 + bit)
+    return lines
+
+
+def normalize_context(context: str) -> str | None:
+    """A coverage context name as a CGIR component id, or None to skip.
+
+    pytest-cov: ``tests/test_m.py::TestX::test_f|run`` → ``tests.test_m.TestX.test_f``
+    dynamic_context=test_function: already dotted. The empty string is the
+    global (non-test) context.
+    """
+    if not context:
+        return None
+    context = context.split("|", 1)[0].split(" (", 1)[0].strip()
+    if "::" in context:
+        path, _, rest = context.partition("::")
+        module = path.removesuffix(".py").replace("/", ".").replace("\\", ".")
+        return f"{module}.{rest.replace('::', '.')}"
+    return context
+
+
+def read_coverage_contexts(repo: Path) -> CoverageData | None:
+    """Per-test line coverage from ``.coverage`` or ``coverage.json``."""
+    dot = repo / ".coverage"
+    if dot.exists():
+        data = _read_sqlite(dot, repo)
+        if data:
+            return data
+    js = repo / "coverage.json"
+    if js.exists():
+        return _read_json(js)
+    return None
+
+
+def _read_sqlite(path: Path, repo: Path) -> CoverageData | None:
+    try:
+        db = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+        try:
+            files = dict(db.execute("SELECT id, path FROM file"))
+            contexts = dict(db.execute("SELECT id, context FROM context"))
+            rows = list(db.execute("SELECT file_id, context_id, numbits FROM line_bits"))
+        finally:
+            db.close()
+    except sqlite3.Error:
+        return None
+
+    out: CoverageData = {}
+    for file_id, context_id, numbits in rows:
+        test_id = normalize_context(str(contexts.get(context_id, "")))
+        if test_id is None:
+            continue
+        rel = _relativize(str(files.get(file_id, "")), repo)
+        if rel is None:
+            continue
+        lines = numbits_to_lines(numbits)
+        if lines:
+            out.setdefault(rel, {}).setdefault(test_id, set()).update(lines)
+    return out or None
+
+
+def _read_json(path: Path) -> CoverageData | None:
+    try:
+        payload = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    out: CoverageData = {}
+    for file_path, file_data in (payload.get("files") or {}).items():
+        contexts = file_data.get("contexts") or {}
+        for line_str, ctx_names in contexts.items():
+            try:
+                line = int(line_str)
+            except ValueError:
+                continue
+            for name in ctx_names:
+                test_id = normalize_context(str(name))
+                if test_id is not None:
+                    out.setdefault(file_path, {}).setdefault(test_id, set()).add(line)
+    return out or None
+
+
+def _relativize(file_path: str, repo: Path) -> str | None:
+    try:
+        return str(Path(file_path).resolve().relative_to(repo.resolve()))
+    except ValueError:
+        return file_path if file_path and not Path(file_path).is_absolute() else None
+
+
+def coverage_covered_by(
+    cov: CoverageData, spans: list[tuple[str, str, int, int]]
+) -> dict[str, set[str]]:
+    """Map coverage data onto component spans.
+
+    ``spans`` is ``(component_id, rel_path, start_line, end_line)``. A test
+    covers a component when any of its covered lines falls inside the span.
+    A test never covers itself (its own body's lines are its execution).
+    """
+    out: dict[str, set[str]] = {}
+    for component_id, rel_path, start, end in spans:
+        per_test = cov.get(rel_path)
+        if not per_test:
+            continue
+        for test_id, lines in per_test.items():
+            if test_id == component_id:
+                continue
+            if any(start <= line <= end for line in lines):
+                out.setdefault(component_id, set()).add(test_id)
+    return out
+
+
+__all__ = [
+    "CoverageData",
+    "coverage_covered_by",
+    "normalize_context",
+    "numbits_to_lines",
+    "read_coverage_contexts",
+]

cgir/analyses/effects.py

@@ -41,31 +41,63 @@ def classify(
     graph: RepoGraph, repo_path: Path, adapter: LanguageAdapter | None = None
 ) -> dict[str, list[str]]:
     """Return ``{function_id: sorted([effect_tag, ...])}`` for every function/method."""
+    return classify_with_confidence(graph, repo_path, adapter)[0]
+
+
+def classify_with_confidence(
+    graph: RepoGraph, repo_path: Path, adapter: LanguageAdapter | None = None
+) -> tuple[dict[str, list[str]], dict[str, list[str]]]:
+    """``(effects, lexical_effects)`` — the second maps each function to the
+    subset of its tags backed only by *lexical* evidence (suffix / receiver-
+    name heuristics), the measured false-positive class. Gate rules treat
+    those as low-confidence by default.
+
+    ``calls_effectful`` confidence follows the callees: it is high when any
+    reachable callee carries a high-confidence impure tag, lexical when the
+    entire reachable impurity is lexical.
+    """
     cache = SourceCache(repo_path, adapter)
     func_nodes = [n for n in graph.nodes() if n.kind in {NodeKind.Function, NodeKind.Method}]
     alias_maps = _module_alias_maps(graph)
 
-    effects: dict[str, set[str]] = {}
+    conf: dict[str, dict[str, str]] = {}
     for func in func_nodes:
         module_id = module_of(graph, func)
         aliases = alias_maps.get(module_id, {}) if module_id else {}
-        effects[func.id] = _direct_effects(cache, func, aliases)
+        conf[func.id] = _direct_effects_confidence(cache, func, aliases)
 
-    # Propagate transitively over CALLS edges until fixed point. Only
-    # *impure* effects taint callers — raise-only callees don't.
+    # Two fixpoints over CALLS: does any reachable callee carry impurity at
+    # all, and is any of it high-confidence? Only *impure* effects taint
+    # callers — raise-only callees don't.
+    reaches_any: set[str] = set()
+    reaches_high: set[str] = set()
     changed = True
     while changed:
         changed = False
         for func in func_nodes:
             for edge in graph.out_edges(func.id, EdgeKind.CALLS):
-                callee = effects.get(edge.dst, set())
-                if (
-                    callee & IMPURE_EFFECT_TAGS or TRANSITIVE_TAG in callee
-                ) and TRANSITIVE_TAG not in effects[func.id]:
-                    effects[func.id].add(TRANSITIVE_TAG)
+                callee = conf.get(edge.dst, {})
+                impure = {t for t in callee if t in IMPURE_EFFECT_TAGS}
+                callee_any = bool(impure) or edge.dst in reaches_any
+                callee_high = any(callee[t] == "high" for t in impure) or edge.dst in reaches_high
+                if callee_any and func.id not in reaches_any:
+                    reaches_any.add(func.id)
+                    changed = True
+                if callee_high and func.id not in reaches_high:
+                    reaches_high.add(func.id)
                     changed = True
 
-    return {nid: sorted(tags) for nid, tags in effects.items()}
+    effects: dict[str, list[str]] = {}
+    lexical: dict[str, list[str]] = {}
+    for func in func_nodes:
+        tags = dict(conf[func.id])
+        if func.id in reaches_any:
+            tags[TRANSITIVE_TAG] = "high" if func.id in reaches_high else "lexical"
+        effects[func.id] = sorted(tags)
+        low = sorted(t for t, c in tags.items() if c == "lexical")
+        if low:
+            lexical[func.id] = low
+    return effects, lexical
 
 
 def _module_alias_maps(graph: RepoGraph) -> dict[str, dict[str, str]]:
@@ -82,14 +114,16 @@ def _module_alias_maps(graph: RepoGraph) -> dict[str, dict[str, str]]:
     return maps
 
 
-def _direct_effects(cache: SourceCache, func: Node, aliases: dict[str, str]) -> set[str]:
+def _direct_effects_confidence(
+    cache: SourceCache, func: Node, aliases: dict[str, str]
+) -> dict[str, str]:
     if func.path is None or func.start_line is None:
-        return set()
+        return {}
     parsed = cache.get(func.path)
     if parsed is None:
-        return set()
+        return {}
     source, root, adapter = parsed
     func_ts = adapter.locate_function(root, func.name, func.start_line - 1)
     if func_ts is None:
-        return set()
-    return adapter.direct_effects(func_ts, source, aliases)
+        return {}
+    return adapter.direct_effects_confidence(func_ts, source, aliases)

cgir/analyses/symbols.py

@@ -42,18 +42,63 @@ def build_symbol_tables(graph: RepoGraph) -> dict[str, SymbolTable]:
         tables[module.id] = table
 
     _merge_go_packages(graph, tables)
+    go_dirs = _go_package_dirs(graph)
+    go_module_prefix = _go_module_prefix(graph)
 
     for module in graph.nodes(NodeKind.Module):
         table = tables[module.id]
+        is_go = module.attrs.get("language") == "go"
         for child in graph.children(module.id, NodeKind.Import):
             target = str(child.attrs.get("target") or child.name)
             alias = child.attrs.get("alias")
             local = alias if isinstance(alias, str) else target.rsplit(".", 1)[-1]
-            table.bindings[local] = _resolve_target(qualname_index, target)
+            resolved = _resolve_go_package(target, go_dirs, go_module_prefix) if is_go else None
+            table.bindings[local] = resolved or _resolve_target(qualname_index, target)
 
     return tables
 
 
+def _go_module_prefix(graph: RepoGraph) -> str | None:
+    """The go.mod ``module`` directive (dotted), stashed on the Repository node."""
+    for repo in graph.nodes(NodeKind.Repository):
+        gomod = repo.attrs.get("go_module")
+        if isinstance(gomod, str) and gomod:
+            return gomod.replace("/", ".")
+    return None
+
+
+def _go_package_dirs(graph: RepoGraph) -> dict[str, list[str]]:
+    """Dotted package directory -> module node ids of the go files in it."""
+    dirs: dict[str, list[str]] = {}
+    for module in graph.nodes(NodeKind.Module):
+        if module.attrs.get("language") != "go" or not module.path:
+            continue
+        directory = module.path.rsplit("/", 1)[0] if "/" in module.path else ""
+        dirs.setdefault(directory.replace("/", "."), []).append(module.id)
+    return {d: sorted(ids) for d, ids in dirs.items()}
+
+
+def _resolve_go_package(
+    target: str, go_dirs: dict[str, list[str]], module_prefix: str | None
+) -> str | None:
+    """Resolve a Go import path to a package directory's module.
+
+    ``import "example.com/myapp/internal/store"`` → strip the go.mod module
+    prefix → ``internal.store`` → bind to a module in that directory (the
+    directory merge exposes every package member through it). Without a
+    go.mod, fall back to a *unique* directory-suffix match — ambiguity stays
+    unresolved rather than guessed.
+    """
+    if module_prefix and target.startswith(module_prefix + "."):
+        rel = target[len(module_prefix) + 1 :]
+        modules = go_dirs.get(rel)
+        return modules[0] if modules else None
+    matches = [d for d in go_dirs if d and (target == d or target.endswith("." + d))]
+    if len(matches) == 1:
+        return go_dirs[matches[0]][0]
+    return None
+
+
 def _merge_go_packages(graph: RepoGraph, tables: dict[str, SymbolTable]) -> None:
     """Go's package scope: files in one directory share top-level names.
 

cgir/api/lsp_server.py

@@ -0,0 +1,168 @@
+"""LSP diagnostics — live contract drift as editor squiggles.
+
+Diagnostics-only language server (no completion, no hover): on every save
+it rescans the repo, and publishes
+
+* **errors** for pin violations (`# cgir: pure` that isn't) — absolute
+  invariants, visible from the first refresh;
+* **warnings** for gate drift vs the previous scan (the default low-noise
+  rule set: effect gain/loss on net/fs/db, always-on change pins).
+
+The pure core (:func:`compute_diagnostics`, :class:`DiagnosticsEngine`) is
+fully testable offline; pygls wiring hides behind the ``cgir[lsp]`` extra
+(lazy import — same pattern as mcp/llm). A useful side effect: the engine
+writes the ``.cgir`` index on every refresh, so MCP/pack/impact stay fresh
+while you edit.
+
+Run: ``cgir lsp`` (stdio). Editor config in ``docs/lsp.md``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from cgir.hooks import DEFAULT_FAIL_ON
+from cgir.ir.component_spec import ComponentSpec
+from cgir.pipeline import scan_repo
+from cgir.report.diff import compute_diff, violations
+from cgir.report.pins import change_violations, state_violations
+
+
+@dataclass(slots=True)
+class Diagnostic:
+    path: str  # repo-relative
+    line: int  # 1-based
+    severity: str  # "error" | "warning"
+    message: str
+
+
+def _locate(specs: list[ComponentSpec]) -> dict[str, tuple[str, int]]:
+    out: dict[str, tuple[str, int]] = {}
+    for spec in specs:
+        if spec.trace:
+            path, _, line = spec.trace[0].rpartition(":")
+            try:
+                out[spec.id] = (path, int(line))
+            except ValueError:
+                continue
+    return out
+
+
+def _place(
+    lines: list[str], located: dict[str, tuple[str, int]], severity: str
+) -> list[Diagnostic]:
+    diags: list[Diagnostic] = []
+    for entry in lines:
+        spec_id, _, message = entry.partition(": ")
+        hit = located.get(spec_id)
+        if hit is None or not message:
+            continue  # can't be placed in a file — skip rather than guess
+        path, line = hit
+        diags.append(Diagnostic(path=path, line=line, severity=severity, message=message))
+    return diags
+
+
+def compute_diagnostics(
+    old_specs: list[ComponentSpec],
+    new_specs: list[ComponentSpec],
+    rules: tuple[str, ...] = DEFAULT_FAIL_ON,
+) -> list[Diagnostic]:
+    """Pin violations (errors) + gate drift vs the previous scan (warnings)."""
+    located = _locate(new_specs)
+    diags = _place(state_violations(new_specs), located, "error")
+    diags += _place(change_violations(old_specs, new_specs), located, "error")
+    if old_specs:
+        diff = compute_diff(old_specs, new_specs)
+        diags += _place(violations(diff, list(rules)), located, "warning")
+    return diags
+
+
+class DiagnosticsEngine:
+    """Rescan-on-save loop: keeps the previous scan for drift comparison."""
+
+    def __init__(self, repo: Path, index_dir: Path | None = None) -> None:
+        self._repo = repo
+        self._index_dir = index_dir or (repo / ".cgir")
+        self._prev: list[ComponentSpec] = []
+        self._primed = False
+
+    def refresh(self) -> list[Diagnostic]:
+        result = scan_repo(self._repo, out=self._index_dir)
+        old = self._prev if self._primed else []
+        diags = compute_diagnostics(old, result.specs)
+        self._prev = result.specs
+        self._primed = True
+        return diags
+
+
+def create_server() -> Any:
+    """Build the pygls server (requires the ``cgir[lsp]`` extra)."""
+    try:
+        from lsprotocol import types as lsp
+
+        try:  # pygls 2.x
+            from pygls.lsp.server import LanguageServer
+        except ImportError:  # pygls 1.x
+            from pygls.server import LanguageServer  # type: ignore[attr-defined,no-redef]
+    except ImportError as exc:
+        raise RuntimeError(
+            "Install cgir[lsp] to run the language server (adds the pygls package)"
+        ) from exc
+
+    server = LanguageServer("cgir", "0")
+    state: dict[str, Any] = {"engine": None, "published": set()}
+
+    _SEVERITY = {
+        "error": lsp.DiagnosticSeverity.Error,
+        "warning": lsp.DiagnosticSeverity.Warning,
+    }
+
+    def _publish(diags: list[Diagnostic]) -> None:
+        engine: DiagnosticsEngine = state["engine"]
+        by_path: dict[str, list[Diagnostic]] = {}
+        for d in diags:
+            by_path.setdefault(d.path, []).append(d)
+        current = set(by_path)
+        for rel in current | state["published"]:
+            uri = (engine._repo / rel).resolve().as_uri()
+            items = [
+                lsp.Diagnostic(
+                    range=lsp.Range(
+                        start=lsp.Position(line=max(d.line - 1, 0), character=0),
+                        end=lsp.Position(line=max(d.line - 1, 0), character=200),
+                    ),
+                    message=d.message,
+                    severity=_SEVERITY[d.severity],
+                    source="cgir",
+                )
+                for d in by_path.get(rel, [])
+            ]
+            _send(uri, items)
+        state["published"] = current
+
+    def _send(uri: str, items: list[Any]) -> None:
+        if hasattr(server, "publish_diagnostics"):  # pygls 1.x
+            server.publish_diagnostics(uri, items)
+        else:  # pygls 2.x
+            server.text_document_publish_diagnostics(
+                lsp.PublishDiagnosticsParams(uri=uri, diagnostics=items)
+            )
+
+    @server.feature(lsp.INITIALIZED)
+    def _initialized(_params: Any) -> None:
+        root = server.workspace.root_path
+        if root:
+            state["engine"] = DiagnosticsEngine(Path(root))
+            _publish(state["engine"].refresh())
+
+    @server.feature(lsp.TEXT_DOCUMENT_DID_SAVE)
+    def _did_save(_params: Any) -> None:
+        if state["engine"] is not None:
+            _publish(state["engine"].refresh())
+
+    return server
+
+
+__all__ = ["Diagnostic", "DiagnosticsEngine", "compute_diagnostics", "create_server"]

cgir/api/mcp_server.py

@@ -73,19 +73,12 @@ def tool_pack(index_dir: Path, component_id: str, budget: int = 4000) -> str:
 
 
 def tool_search(index_dir: Path, query: str) -> str:
-    """Components whose id, entrypoint, or effects match a substring."""
-    needle = query.lower()
-    hits: list[str] = []
-    for spec in read_specs(index_dir):
-        haystack = " ".join([spec.id, spec.entrypoint or "", " ".join(spec.effects)]).lower()
-        if needle in haystack:
-            line = f"{spec.id}  [{spec.kind.value}]"
-            if spec.entrypoint:
-                line += f"  ({spec.entrypoint})"
-            hits.append(line)
-    if not hits:
-        return f"no components match {query!r}"
-    return "\n".join(hits) + "\n"
+    """Ranked search: free terms + contract predicates (kind:pure,
+    effects:net, lexical:false, callers:>3, pins:pure, entrypoint:HTTP,
+    lang:go, covered:false)."""
+    from cgir.report.search import render_search
+
+    return render_search(read_specs(index_dir), query)
 
 
 def tool_entrypoints(index_dir: Path) -> str:
@@ -156,7 +149,10 @@ def create_server(index_dir: Path) -> Any:
 
     @server.tool()
     def search(query: str) -> str:
-        """Find components by id / entrypoint / effect substring."""
+        """Ranked component search. Free terms + contract predicates:
+        kind:pure | effects:net | effects:none | lexical:true/false |
+        callers:>3 | calls:>5 | pins:pure | pinned:true |
+        entrypoint:true/HTTP | lang:python/typescript/go | covered:false."""
         return tool_search(index_dir, query)
 
     @server.tool()

cgir/cli.py

@@ -197,6 +197,14 @@ _STARTER_CONFIG = """\
 # name = "core stays pure"
 # in = "app.core.*"
 # forbid-effect = ["net", "db"]
+#
+# [[rule]]
+# name = "no call cycles"
+# forbid-cycle = true
+#
+# [[rule]]
+# name = "layered"
+# layers = ["app.api.*", "app.core.*", "app.db.*"]
 """
 
 _NEXT_STEPS = """\
@@ -275,6 +283,19 @@ def watch(
         typer.echo("\nstopped.")
 
 
+@app.command()
+def search(
+    query: Annotated[
+        str, typer.Argument(help="Free terms + predicates (kind:pure effects:net callers:>3 ...)")
+    ],
+    index_dir: Annotated[Path, typer.Option("--index")] = Path(".cgir"),
+) -> None:
+    """Ranked component search over the index (contract predicates included)."""
+    from cgir.report.search import render_search
+
+    typer.echo(render_search(_load_specs(index_dir), query), nl=False)
+
+
 @app.command()
 def flow(
     component_id: Annotated[str, typer.Argument(metavar="ID")],
@@ -402,7 +423,10 @@ def pack(
     graph = _load_graph(index_dir) if (index_dir / "repo_graph.json").exists() else None
     source = _component_source(graph, component_id, repo) if repo else None
     types = _type_sources(graph, referenced_type_names(target), repo) if repo else {}
-    tests = _test_sources(graph, target.covered_by, repo) if repo else {}
+    # Coverage-grounded linkage can attach dozens of tests to hot-path
+    # components; embed at most a handful of sources (impact --run still
+    # uses the full set — accuracy there, budget here).
+    tests = _test_sources(graph, target.covered_by[:_PACK_TEST_CAP], repo) if repo else {}
     context = _module_context(graph, component_id, repo) if repo else {}
     receivers = _call_receivers(graph, target)
     bundle = build_pack(
@@ -419,6 +443,7 @@ def pack(
 
 
 _HELPER_MAX_LINES = 25
+_PACK_TEST_CAP = 5
 
 
 def _module_context(
@@ -661,6 +686,18 @@ def mcp(
     server.run()
 
 
+@app.command()
+def lsp() -> None:
+    """Serve live contract diagnostics over LSP (stdio; requires cgir[lsp])."""
+    from cgir.api.lsp_server import create_server
+
+    try:
+        server = create_server()
+    except RuntimeError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    server.start_io()
+
+
 @app.command()
 def diff(
     old_index: Annotated[Path, typer.Argument(exists=True, file_okay=False)],

cgir/hooks.py

@@ -146,7 +146,10 @@ def render_hook(result: HookResult) -> str:
         lines.append("")
         lines.append(f"  ❌ blocked — {len(result.violations)} drift violation(s):")
         lines.extend(f"    ! {v}" for v in result.violations)
-        lines.append("  (bypass once with `git commit --no-verify`)")
+        lines.append("  (fix and re-stage — note the blocked change is still staged; discard it")
+        lines.append(
+            "   with `git restore -S -W <file>` — or bypass once with `git commit --no-verify`)"
+        )
     else:
         lines.append("  ✅ no blocking contract drift")
     return "\n".join(lines) + "\n"

cgir/ir/component_spec.py

@@ -42,6 +42,7 @@ COMPONENT_SPEC_SCHEMA: dict[str, Any] = {
         "writes": {"type": "array", "items": {"type": "string"}},
         "purity": {"type": "number", "minimum": 0, "maximum": 1},
         "pins": {"type": "array", "items": {"type": "string"}},
+        "lexical_effects": {"type": "array", "items": {"type": "string"}},
         "algorithm": {"type": "array", "items": {"type": "string"}},
         "trace": {"type": "array", "items": {"type": "string"}},
     },
@@ -77,6 +78,8 @@ class ComponentSpec:
     writes: list[str] = field(default_factory=list)
     purity: float | None = None
     pins: list[str] = field(default_factory=list)
+    # effects backed only by lexical (suffix/receiver-name) evidence
+    lexical_effects: list[str] = field(default_factory=list)
     algorithm: list[str] = field(default_factory=list)
 
     def to_dict(self) -> dict[str, Any]: