codmap 0.0.16__tar.gz → 0.0.17__tar.gz

{codmap-0.0.16 → codmap-0.0.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.16
+Version: 0.0.17
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT

{codmap-0.0.16 → codmap-0.0.17}/codemap/apidiff.py

@@ -45,6 +45,8 @@ class ApiDiff:
     added: list[str] = field(default_factory=list)     # new public symbols
     removed: list[str] = field(default_factory=list)   # deleted public symbols (each breaking)
     changes: list[Change] = field(default_factory=list)  # per-symbol classified changes
+    root: str | None = "core"                          # the provenance root compared (R1-C52)
+    excluded: dict[str, int] = field(default_factory=dict)  # public symbols left unjudged, by root
 
     @property
     def breaking(self) -> list[Change]:
@@ -52,6 +54,8 @@ class ApiDiff:
 
     def to_dict(self) -> dict:
         return {
+            "root": self.root,
+            "excluded": dict(self.excluded),
             "added": sorted(self.added),
             "removed": sorted(self.removed),
             "changes": [
@@ -184,11 +188,43 @@ def _is_public(node: Node) -> bool:
     return node.visibility == "public"
 
 
-def diff_api(old: Graph, new: Graph) -> ApiDiff:
-    """Diff the public API surface of two graphs (old → new)."""
+def _root_of(node: Node) -> str:
+    """Provenance root of a node; an untagged graph is all ``core`` by construction."""
+    return node.extras.get("root", "core")
+
+
+def diff_api(old: Graph, new: Graph, *, root: str | None = "core") -> ApiDiff:
+    """Diff the public API surface of two graphs (old → new).
+
+    ``root`` restricts the comparison to one provenance root, default ``core`` — the
+    package. R1-C52: this used to filter on visibility alone, so on a repo-scoped graph
+    (built with ``--consumer``) every public *test* function counted as added API. The
+    dogfood target measured it on their own release gate: **40 of 47** "added public
+    symbols" were test functions, which means `--exit-code` fired on test churn rather
+    than on the package. A public function in `tests/` is not this package's API.
+
+    Pass ``root=None`` to compare every root, and read ``excluded`` for what a root
+    filter left out — a gate must name what it did not judge (R1-C30-f2).
+    """
     diff = ApiDiff()
-    old_nodes = {i: n for i, n in old.nodes.items() if n.kind in ("function", "class", "attribute")}
-    new_nodes = {i: n for i, n in new.nodes.items() if n.kind in ("function", "class", "attribute")}
+
+    def _pick(graph: Graph) -> tuple[dict, dict[str, int]]:
+        keep, skipped = {}, {}
+        for i, n in graph.nodes.items():
+            if n.kind not in ("function", "class", "attribute"):
+                continue
+            r = _root_of(n)
+            if root is not None and r != root:
+                if _is_public(n):
+                    skipped[r] = skipped.get(r, 0) + 1
+                continue
+            keep[i] = n
+        return keep, skipped
+
+    old_nodes, _ = _pick(old)
+    new_nodes, skipped = _pick(new)
+    diff.root = root
+    diff.excluded = dict(sorted(skipped.items()))
 
     for sid, n in new_nodes.items():
         if sid not in old_nodes and _is_public(n):

{codmap-0.0.16 → codmap-0.0.17}/codemap/query.py

@@ -834,18 +834,75 @@ class Query:
         return out
 
     def entry_points(self, root: str = "core") -> list[str]:
-        """Call-forest roots: functions that call out but are never called (resolved).
-
-        Where behaviour starts — public API / mains / not-yet-triggered. Restricted
-        to one provenance ``root`` (default core). Best-effort: call resolution is
-        partial, so an unresolved caller can leave a real internal as an entry point.
+        """Call-forest roots: functions that call out and are called by nothing *in
+        their own root* (resolved calls only).
+
+        Where behaviour starts — public API / mains / not-yet-triggered. Restricted to
+        one provenance ``root`` (default core).
+
+        R1-C50: "called by nothing" used to mean in-degree zero **across the whole
+        graph**, which on a library means the public API is never an entry point — the
+        one function a user enters the package through is called from `tests`,
+        `examples` and `scripts`, and those 43 calls were what disqualified it. A call
+        from a consumer root is a *use*, not an internal caller; being used is not
+        evidence of being reachable-from-elsewhere. Reported by the dogfood target as
+        [issue #19](https://github.com/kogriv/codemap/issues/19). On a single-package
+        graph every node is `core`, so this is the same set as before by construction.
+
+        Best-effort in **both** directions: an unresolved caller leaves a real internal
+        looking like an entry point (the set is an over-estimate), and resolving one
+        *removes* an entry point (it is an under-estimate of heads whose chain the
+        resolver cannot close). The second direction is what #19 measured.
         """
         return sorted(
             n for n in self._calls.nodes
             if self.root_of(n) == root
-            and self._calls.out_degree(n) > 0 and self._calls.in_degree(n) == 0
+            and self._calls.out_degree(n) > 0
+            and not any(self.root_of(p) == root
+                        for p in self._calls.predecessors(n))
         )
 
+    def external_callers(self, symbol_id: str, root: str = "core") -> dict[str, int]:
+        """Resolved callers of ``symbol_id`` living **outside** ``root``, by root.
+
+        R1-C50/D8: on an entry point this is the evidence that the head is public —
+        `{"tests": 43}` says the package is entered here, which is exactly what the
+        in-degree rule used to read as a disqualification.
+        """
+        out: dict[str, int] = {}
+        if symbol_id in self._calls:
+            for p in self._calls.predecessors(symbol_id):
+                r = self.root_of(p)
+                if r != root:
+                    out[r] = out.get(r, 0) + 1
+        return dict(sorted(out.items()))
+
+    def caller_grades(self, symbol_id: str) -> dict[str, int]:
+        """Histogram of the route grades of the resolved calls *into* ``symbol_id``.
+
+        R1-C51: what `callers(min_confidence=…)` would drop, so a filtered answer can
+        say so instead of coming back as a bare empty list. Reported by the dogfood
+        target with the measurement that makes it matter: of the 25 symbols their
+        registry fan-out reaches, **13 have no `exact` caller at all** — every strategy
+        method — so `min_confidence="exact"` answers `[]` about symbols that are called
+        on every run, through an object a factory returned for a string key.
+        """
+        out: dict[str, int] = {}
+        if symbol_id in self._calls:
+            for p in self._calls.predecessors(symbol_id):
+                g = self._calls.edges[p, symbol_id].get("confidence") or "unknown"
+                out[g] = out.get(g, 0) + 1
+        return dict(sorted(out.items(), key=lambda kv: _grade_rank(kv[0])))
+
+    def callee_grades(self, symbol_id: str) -> dict[str, int]:
+        """Histogram of the route grades of the resolved calls *out of* ``symbol_id``."""
+        out: dict[str, int] = {}
+        if symbol_id in self._calls:
+            for t in self._calls.successors(symbol_id):
+                g = self._calls.edges[symbol_id, t].get("confidence") or "unknown"
+                out[g] = out.get(g, 0) + 1
+        return dict(sorted(out.items(), key=lambda kv: _grade_rank(kv[0])))
+
     def flow(self, entry: str, *, max_depth: int = 5) -> dict:
         """Forward call-flow from ``entry`` along ``calls`` edges, bounded by depth.
 
@@ -906,7 +963,8 @@ class Query:
         out = {
             "symbol": symbol_id, "root": root, "max_depth": max_depth,
             "in_call_graph": bool(targets), "entry_points": len(entries),
-            "flows": [], "beyond_depth": 0,
+            "flows": [], "beyond_depth": 0, "nearest_beyond": None,
+            "inbound_calls": sum(len(self._calls.pred[t]) for t in targets),
             "non_call_refs": sum(1 for r in refs if r["type"] != "calls"),
         }
         if not targets:
@@ -922,9 +980,16 @@ class Query:
                         nxt.add(pred)
             frontier, step = nxt, step + 1
         reaching = sorted((dist[e], e) for e in entries if e in dist)
-        out["flows"] = [{"entry": e, "first_step": d}
+        out["flows"] = [{"entry": e, "first_step": d,
+                         "external_callers": self.external_callers(e, root)}
                         for d, e in reaching if d <= max_depth]
-        out["beyond_depth"] = sum(1 for d, _ in reaching if d > max_depth)
+        beyond = [d for d, _ in reaching if d > max_depth]
+        # R1-C50/D9: "0 flows" and "0 flows, and the nearest head is one step past the
+        # bound" are different answers, and the second one is actionable. Naming only
+        # the count made the headline read as unreachable — measured on a deep graph
+        # where four real heads sat at step 6 under a bound of 5.
+        out["beyond_depth"] = len(beyond)
+        out["nearest_beyond"] = min(beyond) if beyond else None
         return out
 
     # -- relevance ranking (R1-C6) -------------------------------------------

{codmap-0.0.16 → codmap-0.0.17}/codemap/serve/apidiff.py

@@ -44,6 +44,19 @@ def render_apidiff(old: Graph, new: Graph) -> str:
     out.append(f"{verdict} {s['added']} added, {s['removed']} removed, "
                f"{s['changed_symbols']} changed.")
     out.append("")
+    # R1-C52: a gate must name what it did not judge. The verdict covers one root — the
+    # package — and on a repo-scoped graph that leaves the public symbols of `tests`,
+    # `examples` and friends outside it. Silence here is what let 40 test functions read
+    # as 40 additions to the API.
+    if d.get("root") is not None:
+        excluded = d.get("excluded") or {}
+        out.append(f"_Compared: public symbols of root `{d['root']}` — the package._"
+                   if not excluded else
+                   f"_Compared: public symbols of root `{d['root']}` — the package. "
+                   "**Not judged:** "
+                   + ", ".join(f"{n} public symbol(s) in `{r}`" for r, n in excluded.items())
+                   + " — a consumer root is not this package's API._")
+        out.append("")
     # R1-C25/D4: a verdict about the code is only a verdict about the code when both
     # graphs came from the same tool. Say so above the verdict, not in a footnote.
     prov = d.get("provenance") or {}

{codmap-0.0.16 → codmap-0.0.17}/codemap/serve/impact.py

@@ -36,25 +36,46 @@ def _flow_section(rep: dict) -> list[str]:
                      "the change._")
         lines.append("")
         for f in rep["flows"][:_FLOW_ROWS]:
-            lines.append(f"- `{f['entry']}` — step {f['first_step']}")
+            ext = f.get("external_callers") or {}
+            tail = ("  _(entered from " + ", ".join(f"{r} ×{n}" for r, n in ext.items())
+                    + ")_" if ext else "")
+            lines.append(f"- `{f['entry']}` — step {f['first_step']}{tail}")
         if len(rep["flows"]) > _FLOW_ROWS:
             lines.append(f"- _… {len(rep['flows']) - _FLOW_ROWS} more_")
+    elif rep["nearest_beyond"] is not None:
+        # R1-C50/D9: an empty list with a head one step past the bound is not the same
+        # answer as an empty list, and it is the one a reader can act on.
+        lines.append(f"_No entry point within {rep['max_depth']} step(s) — but "
+                     f"{rep['beyond_depth']} reach it further out, the nearest at step "
+                     f"**{rep['nearest_beyond']}**. Re-run with `--flow-depth "
+                     f"{rep['nearest_beyond']}` to see them._")
+    elif rep["inbound_calls"]:
+        lines.append(f"_No entry point reaches it, at any depth — yet {rep['inbound_calls']} "
+                     "resolved call(s) do reach it. Every chain above it is either closed "
+                     "in a call cycle (no head to start from) or starts outside root "
+                     f"`{rep['root']}`. Not 'nothing calls it'._")
     else:
-        lines.append(f"_No entry point reaches it within {rep['max_depth']} step(s)._")
+        lines.append(f"_No entry point reaches it within {rep['max_depth']} step(s), and "
+                     "no resolved call reaches it either._")
     lines.append("")
     notes = []
-    if rep["beyond_depth"]:
+    if rep["beyond_depth"] and rep["flows"]:
         notes.append(f"{rep['beyond_depth']} further entry point(s) reach it **beyond** "
-                     f"{rep['max_depth']} steps — counted, not listed.")
+                     f"{rep['max_depth']} steps (nearest at step "
+                     f"{rep['nearest_beyond']}) — counted, not listed.")
     if rep["non_call_refs"]:
         notes.append(f"{rep['non_call_refs']} direct reference(s) arrive by an edge that "
                      "is not a call (import / inheritance / decoration / attribute) and "
                      "cannot appear in a flow at all.")
-    notes.append("Flows follow resolved `calls` edges only — a lower bound both ways: an "
-                 "unresolved caller also leaves a real internal looking like an entry "
-                 "point, so the denominator is an upper bound. *Reached*, not *broken*: "
-                 "the graph knows the symbol is on the path, not whether the change "
-                 "breaks it.")
+    notes.append("Flows follow resolved `calls` edges only, and the entry-point set is "
+                 "best-effort in **both** directions: an unresolved caller leaves a real "
+                 "internal looking like an entry point (the denominator is an upper "
+                 "bound), while resolving one *removes* an entry point and can lengthen "
+                 "a chain past `--flow-depth` — so a **more** complete graph can answer "
+                 "with **fewer** flows. A call from another root (`tests`, `examples`) is "
+                 "a use, not an internal caller, and does not disqualify a head. "
+                 "*Reached*, not *broken*: the graph knows the symbol is on the path, not "
+                 "whether the change breaks it.")
     lines.append("_" + " ".join(notes) + "_")
     lines.append("")
     return lines

{codmap-0.0.16 → codmap-0.0.17}/codemap/serve/session.py

@@ -118,6 +118,20 @@ _UNLIMITED_BY_DESIGN = {
 }
 
 
+def _grade_filter(min_confidence, every: list, kept: list, grades: dict) -> dict:
+    """The `filter` block: what the route-grade filter kept, dropped, and out of what.
+
+    R1-C51, the filter half of R1-C28. ``by_grade`` is the composition of the
+    *unfiltered* answer, so an empty ``kept`` is readable on its own — `{"heuristic": 2}`
+    with `returned: 0` says "called, but only through routes you excluded", which a bare
+    `[]` cannot. Emitted even with no filter in force (`min_confidence: null`), because
+    that is when a reader most needs to know what a filter *would* remove.
+    """
+    return {"min_confidence": min_confidence, "returned": len(kept),
+            "total": len(every), "dropped": len(every) - len(kept),
+            "by_grade": grades}
+
+
 def _match(q: Query, n) -> dict:
     """One entry of the ``matches`` list: where the symbol is, and how it is declared.
 
@@ -319,6 +333,7 @@ class Session:
                     "ops": sorted(_OPS)}
         self._resolution = None
         self._limit = None
+        self._filter = None
         try:
             env = {"ok": True, "result": fn(self, args)}
         except Exception as exc:  # a bad arg must not kill the resident process
@@ -335,6 +350,15 @@ class Session:
             env["epistemic"] = self._epistemic(op)
         if self._limit is not None:  # R1-C28: how much of the answer survived the cut
             env["limit"] = self._limit
+        # R1-C51: a *filter* is the same partiality as a limit, and it was not declared.
+        # `callers(min_confidence="exact")` came back as a bare `[]` on symbols that are
+        # called on every run through a factory — reported by the dogfood target with the
+        # measurement that makes it matter (13 of 25 registry targets have no exact
+        # caller at all). Emitted whenever the op accepts the filter, including when it
+        # dropped nothing: a caller must not have to tell "nothing was filtered" from
+        # "this build does not report filtering".
+        if self._filter is not None:
+            env["filter"] = self._filter
         return env
 
     def _epistemic(self, op: str) -> dict:
@@ -518,12 +542,20 @@ class Session:
         return res
 
     def _op_callers(self, args) -> list:
-        return self.query.callers(self._canon(args["symbol"]),
-                                  min_confidence=args.get("min_confidence"))
+        sid = self._canon(args["symbol"])
+        kept = self.query.callers(sid, min_confidence=args.get("min_confidence"))
+        self._filter = _grade_filter(args.get("min_confidence"),
+                                     self.query.callers(sid), kept,
+                                     self.query.caller_grades(sid))
+        return kept
 
     def _op_callees(self, args) -> list:
-        return self.query.callees(self._canon(args["symbol"]),
-                                  min_confidence=args.get("min_confidence"))
+        sid = self._canon(args["symbol"])
+        kept = self.query.callees(sid, min_confidence=args.get("min_confidence"))
+        self._filter = _grade_filter(args.get("min_confidence"),
+                                     self.query.callees(sid), kept,
+                                     self.query.callee_grades(sid))
+        return kept
 
     def _op_implementers(self, args) -> list:
         return self.query.implementers(self._canon(args["protocol"]))

{codmap-0.0.16 → codmap-0.0.17}/codmap.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.16
+Version: 0.0.17
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT

{codmap-0.0.16 → codmap-0.0.17}/codmap.egg-info/SOURCES.txt

@@ -121,6 +121,7 @@ tests/test_r1c47_incremental_resample.py
 tests/test_r1c48_type_checking_imports.py
 tests/test_r1c49_type_only_cycles.py
 tests/test_r1c4_complexity.py
+tests/test_r1c50_flow_entry_points.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py
 tests/test_r1c7_edge_vocab.py

{codmap-0.0.16 → codmap-0.0.17}/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.16"
+version = "0.0.17"
 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.16 → codmap-0.0.17}/tests/test_r1c40_flow_reach.py

@@ -208,9 +208,14 @@ def test_a_reference_that_cannot_appear_in_a_flow_is_counted(q):
 
 
 def test_the_depth_bound_is_stated_when_nothing_reaches(q):
+    """R1-C50/D9 replaced the bare "No entry point reaches it within N step(s)" here:
+    a head one step past the bound is a different answer from no head at all, and the
+    only one a reader can act on. The bare sentence survives for the case that really
+    is empty — see `test_never_modelled_by_the_call_layer_is_not_an_empty_flow_list`."""
     md = render_impact(q, "flowpkg.leaf.hit", flow_depth=1)
-    assert "No entry point reaches it within 1 step(s)" in md
-    assert "reach it **beyond** 1 steps" in md
+    assert "No entry point within 1 step(s)" in md
+    assert "1 reach it further out, the nearest at step **2**" in md
+    assert "--flow-depth 2" in md
 
 
 # -- D5: three kinds of emptiness -------------------------------------------------------

codmap-0.0.17/tests/test_r1c50_flow_entry_points.py

@@ -0,0 +1,285 @@
+"""R1-C50/C51/C52 — three findings that arrived in one message from the dogfood target.
+
+[Issue #19](https://github.com/kogriv/codemap/issues/19), filed the day after 0.0.16 while
+they were *verifying our own measurement* from bquant#120 on their tree. Gap:
+`gaps/flow_entry_points_2026-09-10.md`.
+
+**R1-C50 — an entry point defined so that a library never has one.** `entry_points` asked
+for in-degree zero across the whole graph, so the one function a user enters the package
+through was disqualified by being used: 43 calls, all from `tests`/`examples`/`scripts`/
+`research`. Worse, the better tier answered *emptier* — deep resolution closes the chain
+above a node, removing it as a head, so `report impact` said "step 3" on fast and "no
+entry point reaches it" on deep, same tree, same version. Fixed three ways: in-degree is
+counted **within the root** (D7), an entry says which outside roots enter it (D8), and the
+empty answer names its kind — including the nearest head past the depth bound (D9).
+
+**R1-C51 — a filter is partiality too.** `callers(min_confidence="exact")` returned a bare
+`[]` for symbols called on every run through a factory. Their measurement is what makes it
+matter: of the 25 symbols their registry fan-out reaches, **13 have no `exact` caller at
+all** — every strategy method. The envelope now carries a `filter` block in the shape
+R1-C28 uses for limits, always, including when nothing was dropped.
+
+**R1-C52 — `diff` judged the consumers' API.** 40 of 47 "added public symbols" in their
+release-gate run were test functions, because `diff_api` filtered on visibility alone. It
+compares one provenance root now, and says what it did not judge.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from codemap import apidiff
+from codemap.extract import extract, extract_repo
+from codemap.query import Query
+from codemap.serve.apidiff import build_apidiff, render_apidiff
+from codemap.serve.impact import render_impact
+from codemap.serve.session import Session
+
+# public → mid → leaf, and the public head is called only from the consumer root.
+CORE_API = '''from core.mid import step
+
+
+def public_entry(x):
+    return step(x)
+'''
+CORE_MID = '''from core.leaf import work
+
+
+def step(x):
+    return work(x)
+'''
+CORE_LEAF = '''def work(x):
+    return x
+'''
+# a pair that calls each other: a chain with no head at all
+CORE_RING = '''def ping(n):
+    return pong(n) if n else 0
+
+
+def pong(n):
+    return ping(n - 1)
+
+
+def rung():
+    return ping(2)
+'''
+USAGE = '''from core.api import public_entry
+
+
+def scenario():
+    return public_entry(1)
+
+
+def scenario_two():
+    return public_entry(2)
+'''
+
+
+def _repo(tmp_path):
+    core = tmp_path / "core"
+    core.mkdir()
+    (core / "__init__.py").write_text("")
+    (core / "api.py").write_text(CORE_API)
+    (core / "mid.py").write_text(CORE_MID)
+    (core / "leaf.py").write_text(CORE_LEAF)
+    (core / "ring.py").write_text(CORE_RING)
+    usage = tmp_path / "usage"
+    usage.mkdir()
+    (usage / "script.py").write_text(USAGE)
+    return core, usage
+
+
+@pytest.fixture(scope="module")
+def repo(tmp_path_factory):
+    core, usage = _repo(tmp_path_factory.mktemp("r1c50"))
+    return Query(extract_repo(core, consumers=(usage,), mode="full"))
+
+
+@pytest.fixture(scope="module")
+def package_only(tmp_path_factory):
+    core, _ = _repo(tmp_path_factory.mktemp("r1c50-solo"))
+    return Query(extract(core))
+
+
+def _entries(rep):
+    return {f["entry"]: f["first_step"] for f in rep["flows"]}
+
+
+# -- D7: the head of a library's flow is public, not internal ---------------------------
+
+def test_a_head_called_only_from_a_consumer_root_is_an_entry_point(repo):
+    head = "core.api.public_entry"
+    assert head in repo.entry_points("core")
+    assert repo._calls.in_degree(head) == 2, "and it is called — twice, from the consumer"
+
+
+def test_the_flow_reaches_the_leaf_from_the_public_head(repo):
+    rep = repo.flows_to("core.leaf.work")
+    assert _entries(rep)["core.api.public_entry"] == 2
+
+
+def test_the_old_rule_loses_the_flow_entirely(repo, monkeypatch):
+    """R1-C37, and the exact shape of #19: with in-degree counted across the whole graph,
+    the public head is disqualified by being used, and nothing reaches the leaf at any
+    depth — so raising `--flow-depth` cannot help, which is what they measured."""
+    def global_indegree(self, root="core"):
+        return sorted(n for n in self._calls.nodes
+                      if self.root_of(n) == root
+                      and self._calls.out_degree(n) > 0
+                      and self._calls.in_degree(n) == 0)
+
+    monkeypatch.setattr(Query, "entry_points", global_indegree)
+    assert "core.api.public_entry" not in repo.entry_points("core")
+    for depth in (2, 5, 50):
+        assert repo.flows_to("core.leaf.work", max_depth=depth)["flows"] == []
+
+
+def test_a_single_package_graph_is_unaffected(package_only):
+    """The rule may not silently change the answer where no consumer root exists: with one
+    root, in-root in-degree *is* in-degree."""
+    q = package_only
+    old = sorted(n for n in q._calls.nodes if q.root_of(n) == "core"
+                 and q._calls.out_degree(n) > 0 and q._calls.in_degree(n) == 0)
+    assert q.entry_points("core") == old
+
+
+# -- D8: an entry says what enters it ---------------------------------------------------
+
+def test_an_entry_carries_the_roots_that_enter_it(repo):
+    rep = repo.flows_to("core.leaf.work")
+    flow = next(f for f in rep["flows"] if f["entry"] == "core.api.public_entry")
+    assert flow["external_callers"] == {"usage": 2}
+    assert repo.external_callers("core.api.public_entry") == {"usage": 2}
+    md = render_impact(repo, "core.leaf.work")
+    assert "entered from usage ×2" in md
+
+
+def test_an_internal_head_has_no_external_callers(package_only):
+    assert package_only.external_callers("core.api.public_entry") == {}
+
+
+# -- D9: the empty answer names its kind ------------------------------------------------
+
+def test_the_nearest_head_past_the_bound_is_named_and_actionable(repo):
+    rep = repo.flows_to("core.leaf.work", max_depth=1)
+    assert rep["flows"] == [] and rep["beyond_depth"] == 1 and rep["nearest_beyond"] == 2
+    md = render_impact(repo, "core.leaf.work", flow_depth=1)
+    assert "the nearest at step **2**" in md and "--flow-depth 2" in md
+
+
+def test_called_but_headless_is_not_nothing_calls_it(repo):
+    """`ping`/`pong` call each other and `rung` calls `ping`; nothing reaches `pong` from
+    a head, because the chain closes in a cycle. That is not 'no call reaches it'."""
+    rep = repo.flows_to("core.ring.pong")
+    assert rep["in_call_graph"] is True and rep["inbound_calls"] >= 1
+    md = render_impact(repo, "core.ring.pong")
+    if not rep["flows"]:
+        assert "closed in a call cycle" in md and "Not 'nothing calls it'" in md
+
+
+def test_the_note_warns_in_both_directions(repo):
+    md = render_impact(repo, "core.leaf.work")
+    assert "looking like an entry point" in md, "the over-estimate, as before"
+    assert "*removes* an entry point" in md, "and the reverse (#19)"
+    assert "**more** complete graph can answer with **fewer** flows" in md
+    assert "a use, not an internal caller" in md
+
+
+# -- R1-C51: a filter declares itself ---------------------------------------------------
+
+def _handle(q, op, args):
+    return Session(q.graph).handle({"op": op, "args": args})
+
+
+@pytest.fixture(scope="module")
+def registry():
+    from pathlib import Path
+    return Query(extract(Path(__file__).resolve().parent / "fixtures" / "dispatchpkg"))
+
+
+def test_the_filter_block_is_present_even_with_no_filter(registry):
+    target = next(e.target for e in registry.graph.edges
+                  if e.extras.get("resolution") == "registry-candidate")
+    env = _handle(registry, "callers", {"symbol": target})
+    f = env["filter"]
+    assert f["min_confidence"] is None and f["dropped"] == 0
+    assert f["returned"] == f["total"] == len(env["result"])
+    assert f["by_grade"], "the composition is stated before anyone filters"
+
+
+def test_an_empty_filtered_answer_says_what_it_dropped(registry):
+    """The reported shape — theirs was a strategy method whose *every* caller is a
+    registry fan-out, so `exact` answers `[]`. The block turns that into 'called, but
+    only through routes you excluded', which a bare list cannot say."""
+    target = next(t for t in sorted({e.target for e in registry.graph.edges
+                                     if e.extras.get("resolution") == "registry-candidate"})
+                  if set(registry.caller_grades(t)) == {"heuristic"})
+    env = _handle(registry, "callers", {"symbol": target, "min_confidence": "exact"})
+    f = env["filter"]
+    assert env["result"] == [] and f["returned"] == 0
+    assert f["total"] > 0 and f["dropped"] == f["total"]
+    assert f["by_grade"].get("heuristic") == f["total"]
+    assert f["min_confidence"] == "exact"
+
+
+def test_callees_declares_it_too(registry):
+    src = next(e.source for e in registry.graph.edges
+               if e.extras.get("resolution") == "registry-candidate")
+    env = _handle(registry, "callees", {"symbol": src, "min_confidence": "exact"})
+    assert env["filter"]["dropped"] >= 1 and env["filter"]["by_grade"]
+
+
+def test_the_grade_histogram_matches_the_edges(registry):
+    for target in {e.target for e in registry.graph.edges if e.type == "calls"}:
+        counted: dict[str, int] = {}
+        for e in registry.graph.edges:
+            if e.type == "calls" and e.target == target:
+                from codemap.model import confidence_of
+                g = confidence_of(e) or "unknown"
+                counted[g] = counted.get(g, 0) + 1
+        got = registry.caller_grades(target)
+        # the graph edge collapses parallel resolutions onto one pair, keeping the
+        # strongest, so the histogram counts pairs — never more than the raw edges.
+        assert sum(got.values()) <= sum(counted.values())
+        assert set(got) <= set(counted)
+
+
+# -- R1-C52: the diff judges the package, and says so -----------------------------------
+
+def test_a_consumers_public_function_is_not_this_packages_api(repo, tmp_path):
+    core, usage = _repo(tmp_path)
+    (usage / "script.py").write_text(USAGE + "\n\ndef brand_new_helper():\n    return 1\n")
+    new = extract_repo(core, consumers=(usage,), mode="full")
+    d = apidiff.diff_api(repo.graph, new)
+    assert d.added == [], "a new public test/consumer function is not an API addition"
+    assert d.excluded.get("usage", 0) >= 3, "and the count of what was not judged is stated"
+    assert d.root == "core"
+    everything = apidiff.diff_api(repo.graph, new, root=None)
+    assert "usage.script.brand_new_helper" in everything.added, "asked for, and there"
+    assert everything.excluded == {}
+
+
+def test_the_package_api_still_diffs(repo, tmp_path):
+    core, usage = _repo(tmp_path)
+    (core / "api.py").write_text(CORE_API + "\n\ndef second_entry(y):\n    return y\n")
+    new = extract_repo(core, consumers=(usage,), mode="full")
+    d = apidiff.diff_api(repo.graph, new)
+    assert d.added == ["core.api.second_entry"]
+
+
+def test_the_report_names_what_it_did_not_judge(repo, tmp_path):
+    core, usage = _repo(tmp_path)
+    (usage / "script.py").write_text(USAGE + "\n\ndef brand_new_helper():\n    return 1\n")
+    new = extract_repo(core, consumers=(usage,), mode="full")
+    md = render_apidiff(repo.graph, new)
+    assert "Compared: public symbols of root `core`" in md
+    assert "Not judged:" in md and "`usage`" in md
+    assert build_apidiff(repo.graph, new)["excluded"]
+
+
+def test_a_single_root_diff_says_the_scope_without_an_exclusion_list(package_only, tmp_path):
+    core, _ = _repo(tmp_path)
+    (core / "api.py").write_text(CORE_API + "\n\ndef second_entry(y):\n    return y\n")
+    md = render_apidiff(package_only.graph, extract(core))
+    assert "Compared: public symbols of root `core` — the package._" in md
+    assert "Not judged:" not in md