codmap 0.0.25__tar.gz → 0.0.27__tar.gz

{codmap-0.0.25/codmap.egg-info → codmap-0.0.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.25
+Version: 0.0.27
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1130 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1180 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.25 → codmap-0.0.27}/README.md

@@ -8,7 +8,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1130 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1180 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.25 → codmap-0.0.27}/codemap/arch.py

@@ -16,6 +16,8 @@ integration gate reads). All rules operate on the **core** module import graph
     independent = [["indicators", "data"]]
     # hard bans regardless of layering: `from` must not import `to`.
     forbidden = [{ from = "core", to = "analysis" }]
+    # ...or no chain of imports at all, through any module (R1-C78):
+    #   forbidden = [{ from = "data", to = "analysis", indirect = true }]
     # the import graph must be acyclic *at import time* (the eager graph).
     no_cycles = true
     # also gate the coupling a lazy import hides: cycles closed only by an import
@@ -53,6 +55,9 @@ class ArchitectureContract:
     layers: tuple[str, ...] = ()
     independent: tuple[tuple[str, ...], ...] = ()
     forbidden: tuple[tuple[str, str], ...] = ()
+    # R1-C78: parallel to `forbidden` — True where the item bans every chain, not one edge.
+    # Kept beside the pairs, not inside them, so every reader of `(from, to)` stays as it was.
+    forbidden_indirect: tuple[bool, ...] = ()
     no_cycles: bool = False
     no_lazy_cycles: bool = False
     no_type_only_cycles: bool = False
@@ -101,9 +106,31 @@ def load_contract(root: str | Path = ".") -> ArchitectureContract:
     data, error = read_toml(path)
     if error:
         return ArchitectureContract(error=error, path=str(path))
+    near = _near_miss_tables(data)
+    if near:
+        return ArchitectureContract(error=near, path=str(path))
     return replace(parse_contract(data.get("architecture", {})), path=str(path))
 
 
+def _near_miss_tables(data: dict) -> str | None:
+    """R1-C76 (design ``contract_table_typo.md``): a table named like ``[architecture]`` but not it.
+
+    ``[architectur]`` used to read as "no contract", exit 0: R1-C69 closed the schema inside the
+    table, and the table name stayed the one typo that turned a gate green. Refused even beside a
+    real ``[architecture]`` (D2): its rules would never run. Other tables are not checked (D3).
+    """
+    import difflib
+
+    names = [k for k, v in data.items()
+             if k != "architecture" and isinstance(v, dict)
+             and difflib.SequenceMatcher(None, k.lower(), "architecture").ratio() >= 0.8]
+    if not names:
+        return None
+    listed = ", ".join(f"`[{k}]`" for k in names)
+    return (f"{listed} looks like a misspelling of `[architecture]`; codemap reads only "
+            "`[architecture]`, so its rules would never run")
+
+
 #: R1-C69: the closed schema of ``[architecture]``. A key outside it is an error, not a skip.
 _FLAGS = ("no_cycles", "no_lazy_cycles", "no_type_only_cycles", "exhaustive", "no_phantom_rules")
 _KNOWN_KEYS = ("layers", "independent", "forbidden") + _FLAGS
@@ -113,6 +140,17 @@ def _is_str_list(v) -> bool:
     return isinstance(v, list) and all(isinstance(x, str) for x in v)
 
 
+def _repeated(names: list[str]) -> list[str]:
+    """Names that occur more than once, in order of first repeat (R1-C79)."""
+    seen: set[str] = set()
+    out: list[str] = []
+    for n in names:
+        if n in seen and n not in out:
+            out.append(n)
+        seen.add(n)
+    return out
+
+
 def contract_problems(section) -> list[str]:
     """Every way ``section`` departs from the ``[architecture]`` schema, in reading order (R1-C69).
 
@@ -131,8 +169,14 @@ def contract_problems(section) -> list[str]:
             near = difflib.get_close_matches(key, _KNOWN_KEYS, n=1, cutoff=0.6)
             hint = f" (did you mean `{near[0]}`?)" if near else ""
             problems.append(f"unknown key `{key}`{hint}; known keys: {', '.join(_KNOWN_KEYS)}")
-    if "layers" in section and not _is_str_list(section["layers"]):
-        problems.append("`layers` must be a list of strings")
+    if "layers" in section:
+        if not _is_str_list(section["layers"]):
+            problems.append("`layers` must be a list of strings")
+        else:
+            # R1-C79 (design ``self_contradicting_rules.md``): a repeated layer overwrote its own
+            # rank and inverted the stack — the legal edge was named, the upward one passed.
+            for name in _repeated(section["layers"]):
+                problems.append(f"`layers` repeats `{name}`")
     if "independent" in section:
         groups = section["independent"]
         if not isinstance(groups, list):
@@ -141,6 +185,9 @@ def contract_problems(section) -> list[str]:
             for i, grp in enumerate(groups):
                 if not _is_str_list(grp) or len(grp) < 2:
                     problems.append(f"`independent[{i}]` must be a list of at least 2 strings")
+                    continue
+                for name in _repeated(grp):      # R1-C79: one layer twice can never fire
+                    problems.append(f"`independent[{i}]` repeats `{name}`")
     if "forbidden" in section:
         items = section["forbidden"]
         if not isinstance(items, list):
@@ -150,17 +197,23 @@ def contract_problems(section) -> list[str]:
                 if not isinstance(item, dict):
                     problems.append(f"`forbidden[{i}]` must be a table `{{ from = \"…\", to = \"…\" }}`")
                     continue
-                extra = sorted(set(item) - {"from", "to"})
+                extra = sorted(set(item) - {"from", "to", "indirect"})
                 missing = [k for k in ("from", "to") if k not in item]
                 wrong = [k for k in ("from", "to") if k in item and not isinstance(item[k], str)]
                 if extra:
                     problems.append(f"`forbidden[{i}]` has unknown key(s) "
                                     + ", ".join(f"`{k}`" for k in extra))
+                if "indirect" in item and not isinstance(item["indirect"], bool):
+                    problems.append(f"`forbidden[{i}]`: `indirect` must be true or false, got "
+                                    f"{type(item['indirect']).__name__} `{item['indirect']!r}`")
                 if missing:
                     problems.append(f"`forbidden[{i}]` is missing " + ", ".join(f"`{k}`" for k in missing))
                 if wrong:
                     problems.append(f"`forbidden[{i}]`: " + ", ".join(f"`{k}`" for k in wrong)
                                     + " must be a string")
+                elif not missing and item["from"] == item["to"]:
+                    # R1-C79: rules read cross-layer edges, so this can never fire.
+                    problems.append(f"`forbidden[{i}]`: `from` and `to` are both `{item['from']}`")
     for flag in _FLAGS:
         if flag in section and not isinstance(section[flag], bool):
             problems.append(f"`{flag}` must be true or false, got {type(section[flag]).__name__} "
@@ -181,10 +234,11 @@ def parse_contract(section: dict) -> ArchitectureContract:
     if problems:
         return ArchitectureContract(
             error="`[architecture]` is not a valid contract: " + "; ".join(problems))
-    forbidden = []
+    forbidden, indirect = [], []
     for item in section.get("forbidden", []) or []:
         if isinstance(item, dict) and "from" in item and "to" in item:
             forbidden.append((str(item["from"]), str(item["to"])))
+            indirect.append(bool(item.get("indirect", False)))
     independent = tuple(
         tuple(str(x) for x in grp)
         for grp in (section.get("independent", []) or [])
@@ -194,6 +248,7 @@ def parse_contract(section: dict) -> ArchitectureContract:
         layers=tuple(str(x) for x in (section.get("layers", []) or [])),
         independent=independent,
         forbidden=tuple(forbidden),
+        forbidden_indirect=tuple(indirect),
         no_cycles=bool(section.get("no_cycles", False)),
         no_lazy_cycles=bool(section.get("no_lazy_cycles", False)),
         no_type_only_cycles=bool(section.get("no_type_only_cycles", False)),
@@ -265,6 +320,71 @@ def _tangle_line(tangle: dict) -> str:
     return f"{head} (tangle of {tangle['size']}: {', '.join(tangle['modules'])})"
 
 
+_CHAIN_CAP = 25   # witness chains listed per indirect item before "… N more"
+
+
+def _forbidden_chain(query, frm: str, to: str) -> Violation | None:
+    """R1-C78 (design ``forbidden_chains.md``): does any module of ``frm`` reach ``to`` by imports?
+
+    The graph is the one the direct rule reads — core modules, every import scope (D2). A chain may
+    pass through any core module, its own layer and undeclared layers included, and stops at the first
+    module of ``to``. Reported (D3): the **entry edges** ``u → v`` (``v`` in ``to``, ``u`` outside it and
+    reachable from ``frm``) and, for each, a shortest witness chain, ties to the lexicographically
+    smallest, so the answer is deterministic.
+    """
+    ig = query.import_graph
+    layer = {m: query._layer_of(m) for m in ig.nodes if query.root_of(m) == "core"}
+    succ = {m: sorted(w for w in ig.successors(m) if w in layer and w != m) for m in layer}
+    sources = sorted(m for m, ly in layer.items() if ly == frm)
+    if not sources:
+        return None
+    # Level-by-level BFS; each node keeps the smallest chain among those of the shortest length.
+    best: dict[str, tuple[str, ...]] = {s: (s,) for s in sources}
+    frontier = sources
+    while frontier:
+        nxt: dict[str, tuple[str, ...]] = {}
+        for u in frontier:
+            for w in succ[u]:
+                if w in best or layer[w] == to:
+                    continue
+                cand = best[u] + (w,)
+                if w not in nxt or cand < nxt[w]:
+                    nxt[w] = cand
+        best.update(nxt)
+        frontier = sorted(nxt)
+    entries = sorted((u, w) for u in best for w in succ[u] if layer[w] == to)
+    if not entries:
+        return None
+    witnesses = [best[u] + (w,) for (u, w) in entries]
+    # Which modules of `frm` reach `to` at all: walk back from the entry edges, outside `to`.
+    pred: dict[str, list[str]] = {}
+    for u in layer:
+        if layer[u] == to:
+            continue
+        for w in succ[u]:
+            pred.setdefault(w, []).append(u)
+    seen, stack = set(), [u for (u, _) in entries]
+    while stack:
+        u = stack.pop()
+        if u in seen:
+            continue
+        seen.add(u)
+        stack.extend(pred.get(u, ()))
+    reaching = sum(1 for s in sources if s in seen)
+    # A one-hop witness is the entry edge itself, already listed; only longer chains add proof.
+    witnesses = [c for c in witnesses if len(c) > 2]
+    lines = [" → ".join(f"`{m}`" for m in c) for c in witnesses[:_CHAIN_CAP]]
+    if len(witnesses) > _CHAIN_CAP:
+        lines.append(f"_… {len(witnesses) - _CHAIN_CAP} more_")
+    return Violation(
+        "forbidden",
+        f"`{frm}` must not reach `{to}`, directly or through other modules: "
+        f"{reaching} module(s) of `{frm}` reach it",
+        edges=tuple(entries),
+        modules=tuple(lines),
+    )
+
+
 def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
     """Evaluate every rule against the graph; return the violations (empty = clean)."""
     if contract.is_empty():
@@ -302,7 +422,13 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
             ))
 
     # -- forbidden: explicit from→to bans ---------------------------------------
-    for frm, to in contract.forbidden:
+    indirect = contract.forbidden_indirect or (False,) * len(contract.forbidden)
+    for (frm, to), chained in zip(contract.forbidden, indirect):
+        if chained:                       # R1-C78: no chain at all, through any module
+            v = _forbidden_chain(query, frm, to)
+            if v:
+                violations.append(v)
+            continue
         bad = tuple((u, v) for (u, v, lu, lv) in edges if lu == frm and lv == to)
         if bad:
             violations.append(Violation(

{codmap-0.0.25 → codmap-0.0.27}/codemap/serve/check.py

@@ -198,7 +198,11 @@ def _render_verdict(query, contract: ArchitectureContract, violations: list[Viol
         if contract.independent:
             rules.append(_rule_count("independent", appl))
         if contract.forbidden:
-            rules.append(_rule_count("forbidden", appl))
+            count = _rule_count("forbidden", appl)
+            k = sum(contract.forbidden_indirect)
+            if k:   # R1-C78 D7: a green run says which kind of rule held
+                count = count[:-1] + f", {k} indirect)"
+            rules.append(count)
         if contract.no_cycles:
             rules.append("no_cycles")
         if contract.no_lazy_cycles:

{codmap-0.0.25 → codmap-0.0.27/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.25
+Version: 0.0.27
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1130 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **1180 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.25 → codmap-0.0.27}/codmap.egg-info/SOURCES.txt

@@ -147,6 +147,9 @@ tests/test_r1c72_flat_inference_in_packages.py
 tests/test_r1c73_cli_version.py
 tests/test_r1c74_call_site_conservation.py
 tests/test_r1c75_reexported_class_calls.py
+tests/test_r1c76_contract_table_typo.py
+tests/test_r1c77_gate_probe_battery.py
+tests/test_r1c78_forbidden_chains.py
 tests/test_r1c7_edge_vocab.py
 tests/test_r1c8_deadcode.py
 tests/test_r1c9_incremental.py

{codmap-0.0.25 → codmap-0.0.27}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 # version. README says this plainly, since `pip install codmap` / `import codemap` is a
 # seam a reader will otherwise hit by surprise.
 name = "codmap"
-version = "0.0.25"
+version = "0.0.27"
 description = "Static analyzer that turns a package's source into a queryable code graph."
 readme = "README.md"
 # M20/D1: measured, not assumed. Each release of the declared range runs the full suite in

{codmap-0.0.25 → codmap-0.0.27}/tests/test_r1c49_type_only_cycles.py

@@ -216,8 +216,13 @@ def test_every_enforced_rule_names_itself_in_the_passing_line(tmp_path):
     over the contract's own fields, so a rule added later without a line here fails."""
     import dataclasses
     quiet = Query(extract(str(_pkg(tmp_path, {"a": "from .b import x\n", "b": "x = 1\n"}))))
-    skip = {"error", "path"}
+    # `forbidden_indirect` (R1-C78) is not a rule but a flag per `forbidden` item; it has its own
+    # probe below, so skipping it here does not let it go unnamed.
+    skip = {"error", "path", "forbidden_indirect"}
     names = [f.name for f in dataclasses.fields(arch.ArchitectureContract) if f.name not in skip]
+    chained = arch.ArchitectureContract(forbidden=(("core", "data"),), forbidden_indirect=(True,))
+    md = render_check(quiet, chained, arch.check_contract(quiet, chained))
+    assert "forbidden (1 declared, 0 applicable, 1 indirect)" in md, md
     assert "no_type_only_cycles" in names
     for name in names:
         value = {"layers": ("core",), "independent": (("core", "data"),),

codmap-0.0.27/tests/test_r1c76_contract_table_typo.py

@@ -0,0 +1,68 @@
+"""R1-C76 — a misspelled `[architecture]` table is refused, not read as "no contract".
+
+Found by asking codemap the question its import-linter card asked of import-linter (zero contracts pass).
+Design `docs/design/contract_table_typo.md`.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from codemap import arch
+from codemap.cli import main
+from codemap.extract import extract
+from codemap.query import Query
+from codemap.serve.check import build_check
+
+RULE = 'forbidden = [{from="core", to="analysis"}]\n'
+
+
+@pytest.fixture(scope="module")
+def pkg(tmp_path_factory):
+    root = tmp_path_factory.mktemp("r1c76") / "tpkg"
+    for d in (root, root / "core", root / "analysis"):
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "__init__.py").write_text("")
+    (root / "analysis" / "b.py").write_text("X = 1\n")
+    (root / "core" / "a.py").write_text("from tpkg.analysis import b\n")
+    return root
+
+
+def _check(tmp_path, pkg, toml, capsys, *extra) -> tuple[int, str]:
+    if toml is not None:
+        (tmp_path / "codemap.toml").write_text(toml)
+    rc = main(["check", "--build", str(pkg), "--root", str(tmp_path), *extra])
+    return rc, capsys.readouterr().out
+
+
+@pytest.mark.parametrize("toml, name", [
+    (f"[architectur]\n{RULE}", "architectur"),
+    (f"[Architecture]\n{RULE}", "Architecture"),
+    (f"[archtecture]\n{RULE}", "archtecture"),
+    (f"[architecture]\nno_cycles = true\n\n[architectur]\n{RULE}", "architectur"),
+], ids=["A1", "A2-case", "A2-letter", "A3-both"])
+def test_a_near_miss_table_is_refused(tmp_path, pkg, capsys, toml, name):
+    rc, out = _check(tmp_path, pkg, toml, capsys)
+    assert rc == 2, out
+    assert f"`[{name}]`" in out and "`[architecture]`" in out
+
+
+def test_mcp_check_carries_the_refusal(tmp_path, pkg):
+    (tmp_path / "codemap.toml").write_text(f"[architectur]\n{RULE}")
+    c = arch.load_contract(tmp_path)
+    q = Query(extract(str(pkg)))
+    payload = build_check(q, c, arch.check_contract(q, c))
+    assert payload["ok"] is False
+    assert "`[architectur]`" in payload["contract_error"]
+
+
+def test_what_was_valid_or_absent_answers_as_before(tmp_path, pkg, capsys):
+    rc, out = _check(tmp_path, pkg, f"[architecture]\n{RULE}", capsys)
+    assert rc == 2 and "1 rule(s) broken" in out                      # a real violation, as before
+    rc, out = _check(tmp_path, pkg, '[integrations]\nenabled = []\n', capsys)
+    assert rc == 0 and "No `[architecture]` contract found" in out    # unrelated table: still absent
+    with pytest.raises(SystemExit, match="no \\[architecture\\] contract found"):
+        _check(tmp_path, pkg, None, capsys, "--require-contract")     # still opt-in for absence (exit 1)
+    (tmp_path / "codemap.toml").unlink()
+    rc, out = _check(tmp_path, pkg, None, capsys)
+    assert rc == 0 and "No `[architecture]` contract found" in out    # no file at all

codmap-0.0.27/tests/test_r1c77_gate_probe_battery.py

@@ -0,0 +1,223 @@
+"""R1-C77 — the gate probe battery: the questions asked of import-linter, asked of `codemap check`.
+
+Design `docs/design/gate_probe_battery.md` (predictions pre-registered in 312c104). One fixture, `gp` with
+layers `high > mid > low`; every probe is a fresh copy with one change. A probe whose answer is a defect is
+`xfail(strict=True)` against the *right* answer, with the number of its fix, so fixing it turns this red
+until the mark comes off.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+
+from codemap.cli import main
+
+LAYERS = '[architecture]\nlayers = ["high", "mid", "low"]\n'
+UP = "from gp.high import h\n"
+
+
+@pytest.fixture(scope="module")
+def base(tmp_path_factory) -> Path:
+    root = tmp_path_factory.mktemp("r1c77") / "proj"
+    gp = root / "gp"
+    for d in ("", "high", "mid", "low"):
+        (gp / d).mkdir(parents=True, exist_ok=True)
+        (gp / d / "__init__.py").write_text("")
+    (gp / "high" / "h.py").write_text("from gp.mid import m\n\nclass X:\n    pass\n")
+    (gp / "mid" / "m.py").write_text("from gp.low import l\n")
+    (gp / "low" / "l.py").write_text("Y = 1\n")
+    (root / "codemap.toml").write_text(LAYERS)
+    return root
+
+
+def _copy(base: Path, tmp_path: Path) -> Path:
+    dst = tmp_path / "proj"
+    shutil.copytree(base, dst)
+    return dst
+
+
+def _run(root: Path, capsys, *extra) -> tuple[int, str]:
+    rc = main(["check", "--build", str(root / "gp"), "--root", str(root), *extra])
+    return rc, capsys.readouterr().out
+
+
+# -- import shapes: the change is in gp/low/l.py unless the probe says otherwise -------------------
+
+SHAPES = {
+    "P0": ("low/l.py", UP),
+    "P1": ("low/l.py", "def f():\n    from gp.high import h\n    return h\n"),
+    "P2": ("low/l.py", "from typing import TYPE_CHECKING\nif TYPE_CHECKING:\n    from gp.high import h\n"),
+    "P3": ("low/l.py", "import gp.high.h\n"),
+    "P4": ("low/__init__.py", "from ..high import h\n"),
+    "P5": ("low/l.py", "from gp import high\n"),
+    "P6": ("low/l.py", "from .. import high\n"),
+    "P7": ("low/l.py", "import gp.high.h as hh\n"),
+    "P8": ("low/l.py", "from gp.high.h import *\n"),
+    "P9": ("low/l.py", "try:\n    from gp.high import h\nexcept ImportError:\n    h = None\n"),
+    "P10": ("low/l.py", "class K:\n    from gp.high import h\n"),
+    "P11": ("low/l.py", "import sys\nif sys.version_info >= (3, 8):\n    from gp.high import h\n"),
+    "P12": ("low/l.py", "class K:\n    def m(self):\n        def inner():\n"
+                        "            from gp.high import h\n            return h\n        return inner\n"),
+    "P13": ("low/l.py", "import gp.high\n\ndef f():\n    return gp.high.h.X\n"),
+}
+
+
+def test_P0c_control_clean_tree_is_satisfied(base, tmp_path, capsys):
+    rc, out = _run(_copy(base, tmp_path), capsys)
+    assert rc == 0 and "Contract satisfied" in out, out
+
+
+@pytest.mark.parametrize("probe", sorted(SHAPES, key=lambda p: int(p[1:])))
+def test_an_upward_import_is_caught_in_every_shape(base, tmp_path, capsys, probe):
+    root = _copy(base, tmp_path)
+    rel, src = SHAPES[probe]
+    (root / "gp" / rel).write_text(src)
+    rc, out = _run(root, capsys)
+    assert rc == 2, f"{probe}: {out}"
+    # Which edge, not only whether (the C11 lesson): from gp.low, into gp.high.
+    assert "`layered`" in out and "- `gp.low" in out and "` → `gp.high" in out, f"{probe}: {out}"
+
+
+def test_P14_a_dynamic_import_is_a_documented_limit(base, tmp_path, capsys):
+    root = _copy(base, tmp_path)
+    (root / "gp" / "low" / "l.py").write_text('import importlib\nh = importlib.import_module("gp.high.h")\n')
+    rc, out = _run(root, capsys)
+    assert rc == 0, out          # a static tool cannot see it; import-linter is blind to it too
+
+
+# -- contract shapes -------------------------------------------------------------------------------
+
+def _with(base, tmp_path, toml: str, src: str | None = UP, rel: str = "low/l.py") -> Path:
+    root = _copy(base, tmp_path)
+    (root / "codemap.toml").write_text(toml)
+    if src is not None:
+        (root / "gp" / rel).write_text(src)
+    return root
+
+
+REFUSED = {
+    "C1": (LAYERS + "exhaustiv = true\n", ["unknown key `exhaustiv`", "did you mean `exhaustive`"]),
+    "C3": ('[architecture]\nforbidden = [{from = "low", too = "high"}]\n', ["unknown key(s) `too`", "missing `to`"]),
+    "C6": (LAYERS + 'exhaustive = "maybe"\n', ["`exhaustive` must be true or false"]),
+    "C8": ('[architectur]\nlayers = ["high", "mid", "low"]\n', ["`[architectur]`"]),
+    "C9": ('[architecture]\nforbidden = {from = "low", to = "high"}\n', ["`forbidden` must be a list"]),
+    "C10": ('[architecture]\nLayers = ["high", "mid", "low"]\n', ["unknown key `Layers`", "did you mean `layers`"]),
+}
+
+
+@pytest.mark.parametrize("probe", sorted(REFUSED, key=lambda p: int(p[1:])))
+def test_a_malformed_contract_is_refused(base, tmp_path, capsys, probe):
+    toml, heard = REFUSED[probe]
+    rc, out = _run(_with(base, tmp_path, toml), capsys)
+    assert rc == 2 and "nothing was enforced" in out, f"{probe}: {out}"
+    for line in heard:
+        assert line in out, f"{probe}: {line!r} not in {out}"
+
+
+def test_C15_indirect_is_accepted_since_r1c78(base, tmp_path, capsys):
+    # First run (73a757e, before R1-C78): refused as an unknown key, as predicted. Now the key exists.
+    toml = '[architecture]\nforbidden = [{from = "low", to = "high", indirect = true}]\n'
+    rc, out = _run(_with(base, tmp_path, toml), capsys)
+    assert rc == 2 and "`low` must not reach `high`" in out and "- `gp.low.l` → `gp.high.h`" in out, out
+
+
+def test_C2_exhaustive_names_an_undeclared_layer(base, tmp_path, capsys):
+    root = _with(base, tmp_path, LAYERS + "exhaustive = true\n", src=None)
+    (root / "gp" / "extra").mkdir()
+    (root / "gp" / "extra" / "__init__.py").write_text("")
+    rc, out = _run(root, capsys)
+    assert rc == 2 and "`exhaustive`" in out and "- extra" in out, out
+
+
+def test_C4_a_misspelled_forbidden_layer_is_inert_and_disclosed(base, tmp_path, capsys):
+    toml = '[architecture]\nforbidden = [{from = "low", to = "hihg"}]\n'
+    rc, out = _run(_with(base, tmp_path, toml), capsys)
+    assert rc == 0, out                                     # R1-C62: inert by design ...
+    assert "forbidden (1 declared, 0 applicable)" in out and "`hihg`" in out, out   # ... and said
+
+
+def test_C4b_no_phantom_rules_makes_it_a_failure(base, tmp_path, capsys):
+    toml = '[architecture]\nforbidden = [{from = "low", to = "hihg"}]\nno_phantom_rules = true\n'
+    rc, out = _run(_with(base, tmp_path, toml), capsys)
+    assert rc == 2 and "`no_phantom_rules`" in out and "hihg" in out, out
+
+
+def test_C5_a_misspelled_layer_is_inert_and_disclosed(base, tmp_path, capsys):
+    toml = '[architecture]\nlayers = ["hihg", "mid", "low"]\n'
+    rc, out = _run(_with(base, tmp_path, toml), capsys)
+    assert rc == 0, out
+    assert "layered (3 declared, 2 applicable)" in out and "`hihg`" in out, out
+
+
+def test_C7_no_contract_passes_unless_required(base, tmp_path, capsys):
+    root = _copy(base, tmp_path)
+    (root / "codemap.toml").unlink()
+    (root / "gp" / "low" / "l.py").write_text(UP)
+    rc, out = _run(root, capsys)
+    assert rc == 0 and "No `[architecture]` contract found" in out, out
+    with pytest.raises(SystemExit, match="no \\[architecture\\] contract found"):
+        _run(root, capsys, "--require-contract")
+
+
+def test_C11_a_repeated_layer_is_refused(base, tmp_path, capsys):
+    # R1-C79. First run (73a757e): exit 2, but for the wrong edge. The second `high` overwrote the first in
+    # `rank`, the legal `gp.high.h → gp.mid.m` was named as the violation and the real upward
+    # `gp.mid.m → gp.high.h` was not. An exit-code-only assertion passed on it.
+    toml = '[architecture]\nlayers = ["high", "mid", "high", "low"]\n'
+    rc, out = _run(_with(base, tmp_path, toml, src="from gp.high import h\n", rel="mid/m.py"), capsys)
+    assert rc == 2 and "nothing was enforced" in out and "`layers` repeats `high`" in out, out
+
+
+def test_C12_an_empty_layers_list(base, tmp_path, capsys):
+    rc, out = _run(_with(base, tmp_path, "[architecture]\nlayers = []\n"), capsys)
+    assert rc == 0 and "No `[architecture]` contract found" in out, out
+
+
+def test_C13_a_same_layer_forbidden_item_is_refused(base, tmp_path, capsys):
+    rc, out = _run(_with(base, tmp_path, '[architecture]\nforbidden = [{from = "low", to = "low"}]\n',
+                         src=None), capsys)
+    assert rc == 2 and "`from` and `to` are both `low`" in out, out
+
+
+def test_C14_an_independent_group_naming_one_layer_twice_is_refused(base, tmp_path, capsys):
+    rc, out = _run(_with(base, tmp_path, '[architecture]\nindependent = [["low", "low"]]\n', src=None), capsys)
+    assert rc == 2 and "`independent[0]` repeats `low`" in out, out
+
+
+# -- graph and invocation --------------------------------------------------------------------------
+
+def test_G1_a_stale_graph_fails_unless_allowed(base, tmp_path, capsys):
+    root = _copy(base, tmp_path)
+    graph = tmp_path / "g.json"
+    assert main(["build", str(root / "gp"), "--out", str(graph)]) == 0
+    capsys.readouterr()
+    (root / "gp" / "low" / "l.py").write_text(UP)
+    rc = main(["check", "--graph", str(graph), "--root", str(root)])
+    out = capsys.readouterr().out
+    assert rc == 2 and "behind its source tree" in out, out
+    rc = main(["check", "--graph", str(graph), "--root", str(root), "--allow-stale"])
+    out = capsys.readouterr().out
+    assert rc == 0 and "behind its source tree" in out, out          # G1b
+
+
+def test_G2_a_build_path_that_does_not_exist(tmp_path, capsys):
+    missing = tmp_path / "nope"
+    try:
+        rc = main(["check", "--build", str(missing), "--root", str(tmp_path)])
+    except SystemExit as e:
+        rc = e.code
+    captured = capsys.readouterr()
+    assert rc not in (0, None), captured
+    assert "nope" in (captured.out + captured.err + str(rc)), captured
+
+
+def test_G3_a_root_without_a_contract_names_where_it_looked(base, tmp_path, capsys):
+    root = _copy(base, tmp_path)
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    rc = main(["check", "--build", str(root / "gp"), "--root", str(elsewhere)])
+    out = capsys.readouterr().out
+    assert rc == 0 and str(elsewhere.resolve() / "codemap.toml") in out, out