codmap 0.0.26__tar.gz → 0.0.28__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.26
+Version: 0.0.28
 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, **1189 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.28}/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, **1189 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.28}/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.28}/codemap/cli.py

@@ -495,8 +495,10 @@ def _cmd_tests(args) -> int:
     session = Session(_graph_from(args))
     op = "covers" if args.covers else "tests"
     key = "test" if args.covers else "symbol"
-    env = session.handle({"op": op, "args": {key: args.name,
-                                             "depth": args.depth, "cap": args.cap}})
+    payload = {key: args.name, "depth": args.depth, "cap": args.cap}
+    if not args.covers:
+        payload["all_bands"] = args.all_bands
+    env = session.handle({"op": op, "args": payload})
     if not env.get("ok"):
         print(env.get("error", "not found"), file=sys.stderr)
         return 1
@@ -512,7 +514,12 @@ def _cmd_tests(args) -> int:
         print(f"# tests for {r['symbol']} — confidence: {r['confidence']}"
               + (f", {r['distance']} hop(s) away" if r["distance"] else ""))
         for row in r["tests"]:
-            print(f"  {row['node_id']}")
+            far = f"   (distance {row['distance']})" if args.all_bands else ""
+            print(f"  {row['node_id']}{far}")
+        nb = r.get("next_band")
+        if nb and not args.all_bands:   # R1-C80 D2
+            print(f"  … {nb['count']} more test(s) at distance {nb['distance']} — "
+                  "`--all-bands` lists them")
     for c in r["caveats"]:
         print(f"  · {c}", file=sys.stderr)
     ids = [row["node_id"] for row in r.get("tests", []) if row.get("node_id")]
@@ -1081,6 +1088,8 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Hops to search back. Beyond 3 the answer is low-confidence "
                         "(measured: precision 1.00 at 3 hops, 0.33 at 5).")
     t.add_argument("--cap", type=int, default=25, help="Max tests listed (default 25).")
+    t.add_argument("--all-bands", action="store_true",
+                   help="List every band within --depth, not only the nearest (R1-C80).")
     t.add_argument("--format", choices=["text", "json"], default="text")
     t.set_defaults(func=_cmd_tests)
 

{codmap-0.0.26 → codmap-0.0.28}/codemap/extract/roots.py

@@ -269,6 +269,14 @@ def _scan_consumer_module(graph, py, base, label, tree, index, mode, origin=None
     # R1-C46: a use inside a body that a later definition replaced is not a use — it
     # would attribute a reference (or a call) to code that never runs, in either mode.
     dead = _shadow_map(tree)[2]
+    # R1-C80 D0: in full mode, a use of the module's own top-level function or class is an
+    # edge too — a test calling `_vector` in its own module. Without it the walk from a core
+    # symbol stopped at the helper. Names that an import also binds are left to the import.
+    local_defs = set()
+    if mode == "full":
+        local_defs = {n.name for n in tree.body
+                      if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))}
+        local_defs -= set(symbol_map) | set(module_aliases)
 
     for node in ast.walk(tree):
         line = getattr(node, "lineno", None)
@@ -276,8 +284,12 @@ def _scan_consumer_module(graph, py, base, label, tree, index, mode, origin=None
             continue
         target = None
         use_node = node
+        local = False
         if isinstance(node, ast.Name) and node.id in symbol_map:
             target = index.resolve(symbol_map[node.id])
+        elif (isinstance(node, ast.Name) and node.id in local_defs
+              and isinstance(node.ctx, ast.Load)):
+            target, local = f"{mod_id}.{node.id}", True
         elif isinstance(node, ast.Attribute) and id(node) not in inner_attr_ids:
             dotted = _dotted(node)
             if dotted:
@@ -288,7 +300,9 @@ def _scan_consumer_module(graph, py, base, label, tree, index, mode, origin=None
         if not target:
             continue
         src = _source_for(use_node, mod_id, func_ranges) if mode == "full" else mod_id
-        entry = uses.setdefault((src, target), {"called": False, "shapes": []})
+        if local and (src == target or target not in graph.nodes):
+            continue                      # recursion, or a def the shadow rule dropped
+        entry = uses.setdefault((src, target), {"called": False, "shapes": [], "local": local})
         call_node = call_by_func.get(id(use_node))
         if call_node is not None:
             entry["called"] = True
@@ -296,7 +310,7 @@ def _scan_consumer_module(graph, py, base, label, tree, index, mode, origin=None
 
     for (src, target), entry in sorted(uses.items()):
         etype = "calls" if entry["called"] else "references"
-        extras = {"resolution": "imported"}
+        extras = {"resolution": "local" if entry["local"] else "imported"}
         if etype == "calls" and entry["shapes"]:
             extras.update(_arg_contract(entry["shapes"]))
         graph.add_edge(Edge(etype, src, target, extras=extras))

{codmap-0.0.26 → codmap-0.0.28}/codemap/model.py

@@ -113,7 +113,12 @@ SCHEMA_VERSION = "0.13"
 #       nested functions, module-level code and class bodies, plus sites in shadowed
 #       bodies that are not walked; the structured answer gains `by_scope` and
 #       `shadowed_not_walked` (R1-C74, docs/design/call_site_conservation.md).
-ANSWER_FORMAT = 4
+#   5 — `tests` names the band after the nearest (`next_band`, a "… N more test(s) at distance d"
+#       line) and says the nearest band closed the answer instead of "searched N hop(s) back";
+#       `--all-bands` lists every band, each row carrying its distance and confidence; a helper
+#       function inside a collected test module costs no hop in `tests` and `covers`, so
+#       distances move where one sits on the path (R1-C80, docs/design/tests_through_helpers.md).
+ANSWER_FORMAT = 5
 
 # Closed vocabulary of edge types (R1-C7). Node ``kind`` is deliberately an OPEN set
 # (DESIGN §2 — new entity kinds may appear), but edges are TYPED: every relationship

{codmap-0.0.26 → codmap-0.0.28}/codemap/query.py

@@ -262,6 +262,16 @@ class Query:
                 self._outbound.setdefault(e.source, []).append((e.target, e.type))
         self._module_ids = [n.id for n in graph.nodes.values() if n.kind == "module"]
         self._test_ids = {i for i in self.graph.nodes if self._is_test(i)}
+        # R1-C80 D1: non-test functions in a collected test module — transparent to distance.
+        self._test_helper_ids = {i for i in self.graph.nodes if self._is_test_helper(i)}
+        self._test_function_ids = self._test_ids | self._test_helper_ids
+        # D1: a nested def in a test module → the test or helper that contains it.
+        self._test_parent = {e.target: e.source for e in graph.edges
+                             if e.type == "contains" and e.target in self._test_helper_ids
+                             and e.source in self._test_function_ids}
+        self._test_children: dict[str, list[str]] = {}
+        for child, parent in sorted(self._test_parent.items()):
+            self._test_children.setdefault(parent, []).append(child)
 
     # -- lookups -------------------------------------------------------------
 
@@ -1538,14 +1548,8 @@ class Query:
         the artifact does not carry one framework's naming convention, and so an existing
         graph gains the feature with no rebuild.
         """
-        node = self.graph.nodes.get(node_id)
-        if node is None or node.kind != "function" or self.root_of(node_id) != "tests":
-            return False
-        mod = self._module_of(node_id)
-        if mod is None or not mod.file:
-            return False
-        base = mod.file.rsplit("/", 1)[-1]
-        if not (base.startswith("test_") or base.endswith("_test.py")):
+        mod = self._collected_module(node_id)
+        if mod is None:
             return False
         tail = node_id[len(mod.id) + 1:].split(".")
         if not tail or not tail[-1].startswith("test"):
@@ -1554,6 +1558,30 @@ class Query:
             return True
         return len(tail) == 2 and tail[0].startswith("Test")
 
+    def _collected_module(self, node_id: str) -> "Node | None":
+        """The module of a function under a ``tests`` root whose file pytest collects, else None."""
+        node = self.graph.nodes.get(node_id)
+        if node is None or node.kind != "function" or self.root_of(node_id) != "tests":
+            return None
+        mod = self._module_of(node_id)
+        if mod is None or not mod.file:
+            return None
+        base = mod.file.rsplit("/", 1)[-1]
+        if not (base.startswith("test_") or base.endswith("_test.py")):
+            return None
+        return mod
+
+    def _is_test_helper(self, node_id: str) -> bool:
+        """R1-C80 D1: a function in a collected test module that is not itself a test.
+
+        Such a helper exists to be called by the tests beside it, so the walk passes through it
+        without spending a hop: a test that calls ``_vector``, which calls the symbol, exercises
+        the symbol as a test that calls it directly does. conftest.py, ``tests/fixtures/`` and
+        shared helper modules are not collected test modules, so they still cost a hop — that is
+        the shared infrastructure where R1-C24 measured precision falling.
+        """
+        return self._collected_module(node_id) is not None and not self._is_test(node_id)
+
     def pytest_nodeid(self, node_id: str) -> str | None:
         """Graph id → the id you can paste after ``pytest`` (design D5).
 
@@ -1566,7 +1594,8 @@ class Query:
         tail = node_id[len(mod.id) + 1:]
         return mod.file + ("::" + "::".join(tail.split(".")) if tail else "")
 
-    def _test_caveats(self, *, truncated: int, searched: int, found: bool) -> list[str]:
+    def _test_caveats(self, *, truncated: int, searched: int, found: bool,
+                      nearest: int | None = None) -> list[str]:
         """The two labels every answer carries, plus whatever this graph earns.
 
         Both are required (R1-C13): an over-set because reaching a symbol is not
@@ -1594,12 +1623,15 @@ class Query:
                        "hop(s). 16% of symbols that coverage.py proves are exercised look "
                        "like this — ask for a deeper walk (`depth=6`) for low-confidence "
                        "candidates, but do not read silence as 'untested'")
+        elif nearest is not None:
+            # R1-C80 D2: say that the nearest band closed the answer, not that the walk was short.
+            out.append(f"nearest band at distance {nearest}; looked up to depth {searched} for more")
         else:
-            out.append(f"searched {searched} hop(s) back")
+            out.append(f"searched {searched} hop(s)")
         return out
 
     def tests_for(self, symbol_id: str, *, depth: int = _TEST_MAX_DEPTH,
-                  cap: int = _TEST_CAP) -> dict:
+                  cap: int = _TEST_CAP, all_bands: bool = False) -> dict:
         """Which tests exercise ``symbol_id`` — nearest band first (R1-C24, axis A10).
 
         Distance 1 is not the question: measured on codemap's own repo, only **18%** of
@@ -1619,6 +1651,7 @@ class Query:
         targets = self._member_ids(symbol_id)
         seen = set(targets)
         frontier = set(targets)
+        bands: list[tuple[int, list[str]]] = []
         for dist in range(1, max(1, depth) + 1):
             nxt: set[str] = set()
             for node in sorted(frontier):
@@ -1626,35 +1659,59 @@ class Query:
                     if src not in seen and etype in _TEST_WALK_EDGES:
                         seen.add(src)
                         nxt.add(src)
+            # R1-C80 D1 (as measured): a def nested in a test or helper is part of its body, so
+            # it leads to its container at no cost. A module-level helper costs a hop like any
+            # other function: made free, it pulled 72–80% coverage-false tests into the nearest
+            # band through shared helpers (design §"Measured", E6).
+            todo = sorted(n for n in nxt if n in self._test_parent)
+            while todo:
+                parent = self._test_parent[todo.pop()]
+                if parent not in seen:
+                    seen.add(parent)
+                    nxt.add(parent)
+                    if parent in self._test_parent:
+                        todo.append(parent)
             if not nxt:
-                frontier = nxt
                 break
             frontier = nxt
             hits = sorted(n for n in nxt if n in self._test_ids)
             if hits:
-                return self._tests_envelope(symbol_id, hits, dist, cap, dist)
-        return self._tests_envelope(symbol_id, [], None, cap, depth)
-
-    def _tests_envelope(self, symbol_id, hits, dist, cap, searched) -> dict:
-        shown, truncated = hits[:cap], max(0, len(hits) - cap)
-        return {
+                bands.append((dist, hits))
+                # D2: the nearest band is the answer; one more band is only counted.
+                if len(bands) == 2 and not all_bands:
+                    break
+        return self._tests_envelope(symbol_id, bands, cap, depth, all_bands)
+
+    def _tests_envelope(self, symbol_id, bands, cap, searched, all_bands=False) -> dict:
+        dist, hits = bands[0] if bands else (None, [])
+        rows = ([(t, d) for d, band in bands for t in band] if all_bands
+                else [(t, dist) for t in hits])
+        shown, truncated = rows[:cap], max(0, len(rows) - cap)
+        nxt = bands[1] if len(bands) > 1 else None
+        out = {
             "symbol": symbol_id,
             "tier": (self.graph.provenance or {}).get("tier"),
             "distance": dist,
             # `unknown` — never "none". A confident empty is the failure this project has
             # now shipped five fixes for (#1 risk:"none", #3, #5, #7, R1-C23).
             "confidence": _TEST_CONFIDENCE.get(dist, "low") if dist else "unknown",
-            "tests": [self._test_row(t, dist) for t in shown],
+            "tests": [self._test_row(t, d) for t, d in shown],
             "total_at_distance": len(hits),
+            # R1-C80 D2: the band after the nearest, within `depth` — always present, null if none.
+            "next_band": {"distance": nxt[0], "count": len(nxt[1])} if nxt else None,
             "truncated": truncated,
             "caveats": self._test_caveats(truncated=truncated, searched=searched,
-                                          found=bool(dist)),
+                                          found=bool(dist), nearest=dist),
         }
+        if all_bands:   # D3
+            out["total"] = len(rows)
+        return out
 
     def _test_row(self, node_id: str, dist) -> dict:
         n = self.graph.nodes.get(node_id)
         return {"id": node_id, "node_id": self.pytest_nodeid(node_id),
-                "line": getattr(n, "lineno", None), "distance": dist}
+                "line": getattr(n, "lineno", None), "distance": dist,
+                "confidence": _TEST_CONFIDENCE.get(dist, "low") if dist else "unknown"}
 
     def covers(self, test_id: str, *, depth: int = _TEST_MAX_DEPTH,
                cap: int = _TEST_CAP) -> dict:
@@ -1668,12 +1725,19 @@ class Query:
         frontier = {test_id}
         for dist in range(1, max(1, depth) + 1):
             nxt: set[str] = set()
-            for node in sorted(frontier):
-                for e in self._outbound.get(node, []):
+            todo = sorted(frontier)
+            while todo:
+                node = todo.pop()
+                downs = list(self._outbound.get(node, []))
+                downs += [(c, "calls") for c in self._test_children.get(node, ())]  # D1
+                for e in sorted(downs):
                     tgt, etype = e
                     if tgt in seen or etype not in _TEST_WALK_EDGES:
                         continue
                     seen.add(tgt)
+                    if etype == "calls" and tgt in self._test_parent and node == self._test_parent[tgt]:
+                        todo.append(tgt)                  # R1-C80 D1: a nested def is its container's body
+                        continue
                     nxt.add(tgt)
                     if self.root_of(tgt) == "core":
                         out.setdefault(tgt, dist)

{codmap-0.0.26 → codmap-0.0.28}/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.28}/codemap/serve/mcp_server.py

@@ -167,13 +167,17 @@ def build_mcp_server(session: "Session", name: str = "codemap") -> Any:
         return op("callees", {"symbol": symbol, "min_confidence": min_confidence})
 
     @server.tool()
-    def tests(symbol: str, depth: int = 3, cap: int = 25) -> dict:
+    def tests(symbol: str, depth: int = 3, cap: int = 25, all_bands: bool = False) -> dict:
         """Which tests exercise `symbol` — the NEAREST band of test functions that reach
-        it, as runnable pytest node ids. `confidence` is high/medium by distance and
-        `unknown` when nothing is found within `depth`: unknown means unknown, never
-        "untested". Needs a repo-scoped graph (`--consumer tests --mode full`). Raise
-        `depth` above 3 only for low-confidence candidates."""
-        return op("tests", {"symbol": symbol, "depth": depth, "cap": cap})
+        it, as runnable pytest node ids. A helper function inside a test module costs no
+        hop. `next_band` says how many more tests sit at the next distance within `depth`
+        (null if none); `all_bands=true` lists every band, each row with its distance.
+        `confidence` is high/medium by distance and `unknown` when nothing is found within
+        `depth`: unknown means unknown, never "untested". Needs a repo-scoped graph
+        (`--consumer tests --mode full`). Raise `depth` above 3 only for low-confidence
+        candidates."""
+        return op("tests", {"symbol": symbol, "depth": depth, "cap": cap,
+                            "all_bands": all_bands})
 
     @server.tool()
     def covers(test: str, depth: int = 3, cap: int = 25) -> dict:

{codmap-0.0.26 → codmap-0.0.28}/codemap/serve/session.py

@@ -610,7 +610,8 @@ class Session:
         """R1-C24: which tests exercise a symbol, nearest band first, honestly labelled."""
         cap = int(args.get("cap", 25))
         res = self.query.tests_for(
-            self._canon(args["symbol"]), depth=int(args.get("depth", 3)), cap=cap)
+            self._canon(args["symbol"]), depth=int(args.get("depth", 3)), cap=cap,
+            all_bands=bool(args.get("all_bands", False)))
         # These two already say it in their own body (`total_at_distance` + a caveat
         # line). The envelope block is added anyway: a machine consumer should read one
         # vocabulary across every limited op, not learn a per-op dialect.

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

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

@@ -148,7 +148,10 @@ 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_r1c80_tests_through_helpers.py
 tests/test_r1c8_deadcode.py
 tests/test_r1c9_incremental.py
 tests/test_scip_export.py

{codmap-0.0.26 → codmap-0.0.28}/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.28"
 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.28}/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"),),