codmap 0.0.27__tar.gz → 0.0.28__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.27
+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, **1180 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.27 → 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, **1180 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.27 → 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.27 → 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.27 → 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.27 → 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.27 → 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.27 → 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.27 → codmap-0.0.28/codmap.egg-info}/PKG-INFO

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

@@ -151,6 +151,7 @@ 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.27 → 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.27"
+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.27 → codmap-0.0.28}/tests/test_r1c63_answer_format.py

@@ -160,3 +160,48 @@ def test_the_pin_is_over_a_fixture_this_test_owns(pkg):
     """Positive control for the pin: it must not be hashing the live dogfood tree."""
     assert pkg.graph.target == "pkg"
     assert len(pkg.graph.nodes) < 40, "a fixture, not a real package"
+
+
+# -- format 5 (R1-C80): the `tests` answer joins the pinned surfaces ---------------------------
+# Consumers act on it ("what to run before a change"), and until format 5 its shape could move
+# without any pin noticing: none of the six surfaces above is `tests`. Its own fixture, so the
+# repo-scoped build does not move the pin above.
+TESTS_SHA = "8035e17477e5da2f2d6260056b8c030c7846bec2e2c8a6778d5e79746f1a92b3"
+
+REPO_FILES = {
+    "pkg/__init__.py": "",
+    "pkg/core.py": "def act():\n    return 1\n\n\ndef wrap():\n    return act()\n",
+    "tests/test_a.py": ("from pkg.core import act, wrap\n\n\n"
+                        "def _helper():\n    return act()\n\n\n"
+                        "def test_direct():\n    assert act() == 1\n\n\n"
+                        "def test_through_helper():\n    assert _helper() == 1\n\n\n"
+                        "def test_far():\n    assert wrap() == 1\n"),
+}
+
+
+@pytest.fixture(scope="module")
+def repo(tmp_path_factory):
+    from codemap.extract import extract_repo
+    root = tmp_path_factory.mktemp("r1c63_tests")
+    for rel, body in REPO_FILES.items():
+        path = root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(body)
+    return Query(extract_repo(str(root / "pkg"), consumers=(str(root / "tests"),), mode="full"))
+
+
+def _tests_answers(query) -> str:
+    session = Session(query.graph)
+    out = []
+    for args in ({"symbol": "pkg.core.act"}, {"symbol": "pkg.core.act", "all_bands": True},
+                 {"symbol": "pkg.core.wrap"}):
+        env = session.handle({"op": "tests", "args": args})
+        out.append(json.dumps(env["result"], sort_keys=True))
+    return "\n@@\n".join(out)
+
+
+def test_the_tests_answer_matches_its_pin(repo):
+    got = hashlib.sha256(_tests_answers(repo).encode()).hexdigest()
+    assert got == TESTS_SHA, (
+        "the `tests` answer changed shape or content — bump ANSWER_FORMAT if structural, "
+        f"and re-pin.\n  expected {TESTS_SHA}\n  got      {got}\n{_tests_answers(repo)}")

codmap-0.0.28/tests/test_r1c80_tests_through_helpers.py

@@ -0,0 +1,120 @@
+"""R1-C80 — `tests` through a helper in the test module; the answer names the next band.
+
+Design `docs/design/tests_through_helpers.md` (pre-registered e666077, corrected before code in 3247be6).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from codemap.cli import main
+from codemap.extract import extract_repo
+from codemap.query import Query
+
+FILES = {
+    "pkg/__init__.py": "",
+    "pkg/core.py": "def act():\n    return 1\n\n\ndef wrap():\n    return act()\n",
+    "tests/test_a.py": (
+        "from pkg.core import act, wrap\n\n\n"
+        "def _helper():\n    return act()\n\n\n"
+        "def _outer():\n    return _helper()\n\n\n"
+        "def test_direct():\n    assert act() == 1\n\n\n"
+        "def test_through_helper():\n    assert _helper() == 1\n\n\n"
+        "def test_through_two_helpers():\n    assert _outer() == 1\n\n\n"
+        "def test_nested():\n    def one():\n        return _helper()\n    assert one() == 1\n\n\n"
+        "def test_far():\n    assert wrap() == 1\n\n\n"
+        "def test_recursive_helper_is_not_a_self_edge():\n    pass\n"
+    ),
+    "tests/helpers.py": "from pkg.core import act\n\n\ndef shared():\n    return act()\n",
+}
+
+
+def _repo(root: Path, files=FILES, mode="full") -> Query:
+    for rel, body in files.items():
+        p = root / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(body)
+    return Query(extract_repo(str(root / "pkg"), consumers=(str(root / "tests"),), mode=mode))
+
+
+@pytest.fixture(scope="module")
+def q(tmp_path_factory) -> Query:
+    return _repo(tmp_path_factory.mktemp("r1c80"))
+
+
+def _edges(q, etype=None):
+    return {(e.source, e.target, e.extras.get("resolution")) for e in q.graph.edges
+            if e.type != "contains" and (etype is None or e.type == etype)}
+
+
+def test_D0_a_test_calling_its_modules_helper_is_an_edge(q):
+    es = _edges(q, "calls")
+    assert ("tests.test_a.test_through_helper", "tests.test_a._helper", "local") in es
+    assert ("tests.test_a._outer", "tests.test_a._helper", "local") in es
+    assert ("tests.test_a.test_nested.one", "tests.test_a._helper", "local") in es
+    # every local edge stays inside the consumer root
+    for src, tgt, res in _edges(q):
+        if res == "local":
+            assert q.root_of(src) == "tests" and q.root_of(tgt) == "tests"
+
+
+def test_D0_not_in_thin_mode_and_not_for_imported_names(tmp_path):
+    thin = _repo(tmp_path / "thin", mode="thin")
+    assert not any(r == "local" for *_, r in _edges(thin))
+    files = {**FILES, "tests/test_b.py": ("from pkg.core import act\n\n\ndef act_local():\n    return act()\n\n\n"
+                                          "def test_b():\n    assert act() == 1\n")}
+    full = _repo(tmp_path / "full", files)
+    assert ("tests.test_b.test_b", "pkg.core.act", "imported") in _edges(full, "calls")
+
+
+def test_E1_tests_behind_a_helper_are_reachable_one_hop_further(q):
+    # As measured (design §"Measured"): a module-level helper costs a hop. Free, it pulled
+    # mostly coverage-false tests into the nearest band through shared helpers.
+    r = q.tests_for("pkg.core.act", all_bands=True)
+    rows = {t["id"]: t["distance"] for t in r["tests"]}
+    assert rows["tests.test_a.test_direct"] == 1
+    assert rows["tests.test_a.test_through_helper"] == 2          # unreachable before D0
+    assert rows["tests.test_a.test_through_two_helpers"] == 3
+    assert rows["tests.test_a.test_nested"] == 2                  # nested def → its test, free
+    assert "tests.helpers.shared" not in rows                     # not a test
+
+
+def test_E7_next_band_is_named_and_null_when_there_is_none(q):
+    r = q.tests_for("pkg.core.act")
+    assert {t["id"] for t in r["tests"]} == {"tests.test_a.test_direct"}
+    assert r["next_band"] == {"distance": 2, "count": 3}    # through_helper, nested, far
+    assert "nearest band at distance 1; looked up to depth 3 for more" in r["caveats"]
+    assert q.tests_for("pkg.core.wrap")["next_band"] is None
+
+
+def test_E8_all_bands_is_the_union_with_distances_and_is_stable(q):
+    r = q.tests_for("pkg.core.act", all_bands=True)
+    rows = {(t["id"], t["distance"]) for t in r["tests"]}
+    assert ("tests.test_a.test_far", 2) in rows and ("tests.test_a.test_direct", 1) in rows
+    assert r["total"] == 5 and r["total_at_distance"] == 1
+    assert r == q.tests_for("pkg.core.act", all_bands=True)
+
+
+def test_E9_covers_reaches_through_a_helper(q):
+    assert {"id": "pkg.core.act", "distance": 2} in q.covers("tests.test_a.test_through_helper")["symbols"]
+    assert {"id": "pkg.core.act", "distance": 3} in q.covers("tests.test_a.test_through_two_helpers")["symbols"]
+
+
+def test_the_cli_names_the_next_band_and_lists_all_bands(tmp_path, capsys):
+    from codemap import store
+    q = _repo(tmp_path)
+    g = tmp_path / "g.json"
+    store.save(q.graph, str(g))
+    assert main(["tests", "act", "--graph", str(g)]) == 0
+    out = capsys.readouterr().out
+    assert "… 3 more test(s) at distance 2 — `--all-bands` lists them" in out
+    assert main(["tests", "act", "--graph", str(g), "--all-bands"]) == 0
+    out = capsys.readouterr().out
+    assert "test_far   (distance 2)" in out and "more test(s)" not in out
+
+
+def test_E9_covers_enters_a_nested_helper(q):
+    # test_nested → (free) one → _helper → act: the nested def is the test's own body
+    assert {"id": "pkg.core.act", "distance": 2} in q.covers("tests.test_a.test_nested")["symbols"]