codmap 0.0.26__tar.gz → 0.0.27__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.26
+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, **1136 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.26 → 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, **1136 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.26 → 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
@@ -135,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).
 
@@ -153,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):
@@ -163,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):
@@ -172,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__} "
@@ -203,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 [])
@@ -216,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)),
@@ -287,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():
@@ -324,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.26 → 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.26 → codmap-0.0.27/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.26
+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, **1136 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.26 → codmap-0.0.27}/codmap.egg-info/SOURCES.txt

@@ -148,6 +148,8 @@ 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.26 → 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.26"
+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.26 → 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_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

codmap-0.0.27/tests/test_r1c78_forbidden_chains.py

@@ -0,0 +1,138 @@
+"""R1-C78 — `forbidden` with `indirect = true`: no chain of imports from one layer to another.
+
+Design `docs/design/forbidden_chains.md` (acceptance pre-registered in 312c104, oracle in e466ee1).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from codemap import arch
+from codemap.cli import main
+from codemap.extract import extract, extract_repo
+from codemap.query import Query
+from codemap.serve.check import build_check
+
+CHAIN = '[architecture]\nforbidden = [{from = "data", to = "analysis", indirect = true}]\n'
+DIRECT = '[architecture]\nforbidden = [{from = "data", to = "analysis"}]\n'
+
+
+def _pkg(root: Path, files: dict[str, str]) -> Path:
+    pkg = root / "pkg"
+    for rel, src in {"__init__.py": "", **files}.items():
+        p = pkg / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        for parent in p.relative_to(pkg).parents:
+            init = pkg / parent / "__init__.py"
+            if not init.exists():
+                init.write_text("")
+        p.write_text(src)
+    return pkg
+
+
+def _check(tmp_path: Path, files: dict[str, str], toml: str, capsys) -> tuple[int, str]:
+    pkg = _pkg(tmp_path, files)
+    (tmp_path / "codemap.toml").write_text(toml)
+    rc = main(["check", "--build", str(pkg), "--root", str(tmp_path)])
+    return rc, capsys.readouterr().out
+
+
+BASE = {
+    "data/d.py": "from pkg.core import c\n",
+    "core/c.py": "from pkg.analysis import a\n",
+    "analysis/a.py": "X = 1\n",
+}
+
+
+def test_A1_a_two_hop_chain_breaks_an_indirect_item_and_not_a_direct_one(tmp_path, capsys):
+    rc, out = _check(tmp_path, BASE, CHAIN, capsys)
+    assert rc == 2, out
+    assert "`data` must not reach `analysis`, directly or through other modules: 1 module(s)" in out
+    assert "- `pkg.core.c` → `pkg.analysis.a`" in out                       # the entry edge
+    assert "- `pkg.data.d` → `pkg.core.c` → `pkg.analysis.a`" in out        # its witness
+    rc, out = _check(tmp_path, BASE, DIRECT, capsys)
+    assert rc == 0 and "forbidden (1)" in out, out                           # direct: unchanged
+
+
+@pytest.mark.parametrize("middle", [
+    "def f():\n    from pkg.analysis import a\n    return a\n",
+    "from typing import TYPE_CHECKING\nif TYPE_CHECKING:\n    from pkg.analysis import a\n",
+], ids=["function-local", "type-checking"])
+def test_A2_every_import_scope_carries_a_chain(tmp_path, capsys, middle):
+    rc, out = _check(tmp_path, {**BASE, "core/c.py": middle}, CHAIN, capsys)
+    assert rc == 2 and "`pkg.data.d` → `pkg.core.c` → `pkg.analysis.a`" in out, out
+
+
+def test_A3_a_chain_through_an_undeclared_layer(tmp_path, capsys):
+    files = {"data/d.py": "from pkg.utils import u\n", "utils/u.py": "from pkg.analysis import a\n",
+             "analysis/a.py": "X = 1\n"}
+    toml = '[architecture]\nlayers = ["analysis", "data"]\n' + CHAIN.split("\n", 1)[1]
+    rc, out = _check(tmp_path, files, toml, capsys)
+    assert rc == 2, out
+    assert "`layered`" not in out                                     # the stack alone sees nothing
+    assert "`pkg.data.d` → `pkg.utils.u` → `pkg.analysis.a`" in out, out
+
+
+def test_A4_a_consumer_root_does_not_create_a_chain(tmp_path):
+    # Vacuous by construction, and asserted as such: codemap's graph has no edge from core into a
+    # consumer root (even `import helper` with `tests/helper.py` present is not resolved), so no
+    # chain can pass through one and the `root_of == "core"` filter in `_forbidden_chain` is
+    # defensive. What is pinned here is the property the filter relies on.
+    pkg = _pkg(tmp_path, {"data/d.py": "import helper\n", "analysis/a.py": "Y = 1\n"})
+    tests = tmp_path / "tests"
+    tests.mkdir()
+    (tests / "helper.py").write_text("from pkg.analysis import a\n")
+    (tests / "test_x.py").write_text("from pkg.data import d\nfrom pkg.analysis import a\n")
+    (tmp_path / "codemap.toml").write_text(CHAIN)
+    q = Query(extract_repo(str(pkg), consumers=(str(tests),), mode="full"))
+    ig = q.import_graph
+    assert any(q.root_of(u) != "core" for u, _ in ig.edges())               # consumers are in the graph
+    assert not any(q.root_of(u) == "core" and q.root_of(v) != "core" for u, v in ig.edges())
+    assert arch.check_contract(q, arch.load_contract(tmp_path)) == []
+
+
+def test_A5_the_shortest_then_smallest_witness_and_a_stable_answer(tmp_path, capsys):
+    files = {
+        "data/a.py": "from pkg.core import z\n",              # data.a → core.z → core.m → analysis.t (3)
+        "data/b.py": "from pkg.core import y\n",              # data.b → core.y → core.m → analysis.t (3)
+        "data/c.py": "from pkg.core import m\n",              # data.c → core.m → analysis.t (2) ← shortest
+        "core/z.py": "from pkg.core import m\n",
+        "core/y.py": "from pkg.core import m\n",
+        "core/m.py": "from pkg.analysis import t\n",
+        "analysis/t.py": "T = 1\n",
+    }
+    rc, out = _check(tmp_path, files, CHAIN, capsys)
+    assert rc == 2 and "3 module(s) of `data` reach it" in out, out
+    assert "- `pkg.data.c` → `pkg.core.m` → `pkg.analysis.t`" in out, out
+    files2 = {**files, "data/c.py": "X = 1\n"}                 # two chains of 3: a < b
+    rc, out1 = _check(tmp_path, files2, CHAIN, capsys)
+    assert "- `pkg.data.a` → `pkg.core.z` → `pkg.core.m` → `pkg.analysis.t`" in out1, out1
+    rc, out2 = _check(tmp_path, files2, CHAIN, capsys)
+    assert out1 == out2
+
+
+@pytest.mark.parametrize("value, rc_want", [('"yes"', 2), ("false", 0)])
+def test_A6_indirect_is_a_boolean(tmp_path, capsys, value, rc_want):
+    toml = f'[architecture]\nforbidden = [{{from = "data", to = "analysis", indirect = {value}}}]\n'
+    rc, out = _check(tmp_path, BASE, toml, capsys)
+    assert rc == rc_want, out
+    if rc_want == 2:
+        assert "`forbidden[0]`: `indirect` must be true or false" in out
+    else:
+        assert "forbidden (1)" in out                       # false is the same as absent
+
+
+def test_the_structured_answer_carries_entry_edges_and_witnesses(tmp_path):
+    pkg = _pkg(tmp_path, BASE)
+    (tmp_path / "codemap.toml").write_text(CHAIN)
+    c = arch.load_contract(tmp_path)
+    q = Query(extract(str(pkg)))
+    payload = build_check(q, c, arch.check_contract(q, c))
+    (v,) = payload["violations"]
+    assert payload["ok"] is False and v["rule"] == "forbidden"
+    assert v["edges"] == [["pkg.core.c", "pkg.analysis.a"]]
+    assert v["modules"] == ["`pkg.data.d` → `pkg.core.c` → `pkg.analysis.a`"]
+    json.dumps(payload)