codmap 0.0.15__tar.gz → 0.0.17__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.15
+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
@@ -177,7 +177,8 @@ codemap query analyze_zones --graph graph.json
 codemap report architecture   --graph graph.json   # layers, coupling, god-objects, cycles
 codemap report dependencies   --graph graph.json
 codemap report dead-code      --graph graph.json
-codemap report impact --symbol MyClass --graph graph.json
+codemap report impact --symbol MyClass --graph graph.json   # who references it, and which
+                                                            # flows it lands on — at which step
 codemap report api-surface --graph graph.json --format json   # every kind has a json form
 
 # change-set review straight from a diff → risk-sorted dossier

{codmap-0.0.15 → codmap-0.0.17}/README.md

@@ -141,7 +141,8 @@ codemap query analyze_zones --graph graph.json
 codemap report architecture   --graph graph.json   # layers, coupling, god-objects, cycles
 codemap report dependencies   --graph graph.json
 codemap report dead-code      --graph graph.json
-codemap report impact --symbol MyClass --graph graph.json
+codemap report impact --symbol MyClass --graph graph.json   # who references it, and which
+                                                            # flows it lands on — at which step
 codemap report api-surface --graph graph.json --format json   # every kind has a json form
 
 # change-set review straight from a diff → risk-sorted dossier

{codmap-0.0.15 → 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.15 → codmap-0.0.17}/codemap/cli.py

@@ -507,7 +507,8 @@ def _cmd_report(args) -> int:
     if args.kind == "impact":
         if not args.symbol:
             raise SystemExit("error: report impact needs --symbol <name>")
-        print(render_impact(Query(graph), args.symbol, depth=args.depth), end="")
+        print(render_impact(Query(graph), args.symbol, depth=args.depth,
+                            flow_depth=args.flow_depth), end="")
         return 0
     if args.kind in ("communities", "flows"):
         from codemap.serve.subsystems import render_communities, render_flows
@@ -542,7 +543,11 @@ def _report_json(graph, args) -> dict:
         ids = q.impact_targets(args.symbol)
         return {"kind": "impact", "target": graph.target, "symbol": args.symbol,
                 "matched": ids,
-                "reports": [{"id": sid, **q.impact(sid, depth=args.depth)} for sid in ids]}
+                # R1-C40: the flows the change lands on ride next to the blast radius,
+                # not inside it — two answers with two different partialities.
+                "reports": [{"id": sid, **q.impact(sid, depth=args.depth),
+                             "flows": q.flows_to(sid, max_depth=args.flow_depth)}
+                            for sid in ids]}
     if args.kind == "communities":
         return {"kind": "communities", "target": graph.target,
                 "communities": Query(graph).communities()}
@@ -962,6 +967,9 @@ def build_parser() -> argparse.ArgumentParser:
     r.add_argument("--symbol", help="Symbol for `report impact` (short or full name).")
     r.add_argument("--depth", type=int, default=2,
                    help="report impact: transitive BFS depth (default 2).")
+    r.add_argument("--flow-depth", type=int, default=5,
+                   help="report impact: how many call steps a flow may take to reach "
+                        "the symbol (default 5, same as `report flows`).")
     r.add_argument("--min-confidence", choices=["low", "medium", "high"], default=None,
                    help="report dead-code: only show candidates at/above this confidence.")
     r.add_argument("--format", choices=["markdown", "json"], default="markdown")

{codmap-0.0.15 → codmap-0.0.17}/codemap/model.py

@@ -97,6 +97,107 @@ EDGE_TYPES = frozenset({
     "accesses",       # function → attribute node it reads/writes (extras.access, R1-C20)
 })
 
+# Closed vocabulary of ``extras.resolution`` (R1-C39), keyed by (edge type, value).
+#
+# The route was already on the edge before this table existed — `calls` alone carries six
+# distinguishable values — but five modules emitted them and nothing enumerated them, so a
+# new or mistyped value shipped in silence. The guard is the R1-C7 shape: a pair absent
+# here fails, and a row that stops appearing in any build fails too.
+#
+# ``means`` is the honest part. On `calls`/`accesses` the value says **how the target was
+# found** (route); on `references` three of four values say **what kind of site** it was
+# (an annotation, a name used as a value, a doc mention) and only `imported` is a route.
+# One field, two questions — stated rather than papered over (design D4).
+#
+# ``confidence`` is a *grade*, never a probability: `exact` (the target came from a binding
+# read in the source), `inferred` (a type-inference engine produced it — precise but a
+# sample: one deep build misses a live edge ~1 time in 4, R1-C42), `heuristic` (a name
+# match, not a binding — an honest over-approximation). A computed float would read as a
+# precision that is not there. It is derived, never stored: writing it on the edge would be
+# a second source of truth for a pure function of the first (design D2/D3).
+RESOLUTIONS: dict[tuple[str, str], dict[str, str]] = {
+    ("calls", "self"): {"means": "route", "confidence": "exact",
+                        "how": "receiver is `self`; target is a member of the enclosing class"},
+    ("calls", "module"): {"means": "route", "confidence": "exact",
+                          "how": "the name is defined at this module's level"},
+    ("calls", "imported"): {"means": "route", "confidence": "exact",
+                            "how": "the name is bound by an import statement in this file"},
+    ("calls", "deep"): {"means": "route", "confidence": "inferred",
+                        "how": "receiver type inferred by jedi (deep tier only)"},
+    ("calls", "registry"): {"means": "route", "confidence": "exact",
+                            "how": "a literal registry key resolved to the registered impl (M7)"},
+    ("calls", "registry-candidate"): {
+        "means": "route", "confidence": "heuristic",
+        "how": "a factory/getter call fanned out to every member of the family — an "
+               "honest over-approximation, not a resolved target"},
+    ("accesses", "self"): {"means": "route", "confidence": "exact",
+                           "how": "`self.attr` inside the class that declares the attribute"},
+    ("accesses", "class"): {"means": "route", "confidence": "exact",
+                            "how": "`Class.attr` through an import or module member"},
+    ("accesses", "construct"): {"means": "route", "confidence": "exact",
+                                "how": "`Class(...).attr` — the constructor names the owner"},
+    ("accesses", "deep"): {"means": "route", "confidence": "inferred",
+                           "how": "owner type inferred by jedi (deep tier only)"},
+    ("references", "annotation"): {"means": "site", "confidence": "exact",
+                                   "how": "the symbol appears in a type annotation"},
+    ("references", "name"): {"means": "site", "confidence": "exact",
+                             "how": "the symbol is named as a value (dict entry, default=…)"},
+    ("references", "doc"): {"means": "site", "confidence": "exact",
+                            "how": "a documentation file names the symbol"},
+    ("references", "imported"): {"means": "route", "confidence": "exact",
+                                 "how": "a consumer root names an imported core symbol"},
+    ("reads", "string-key"): {"means": "route", "confidence": "exact",
+                              "how": "a literal subscript key — the column set is an "
+                                     "over-set, dict access lands here too"},
+    ("writes", "string-key"): {"means": "route", "confidence": "exact",
+                               "how": "a literal subscript key (see `reads`)"},
+    ("imports", "flat"): {"means": "route", "confidence": "exact",
+                          "how": "sibling import under a flat layout (R1-C21)"},
+    ("export", "flat"): {"means": "route", "confidence": "exact",
+                         "how": "re-export inferred under a flat layout (R1-C21)"},
+}
+
+#: Edge types that carry no ``resolution``: pure syntax, with no route to record.
+UNRESOLVED_EDGE_TYPES = frozenset({"contains", "inherits", "decorated_by", "implements"})
+
+#: Grades, strongest first — the order `min_confidence` filters by.
+CONFIDENCE_ORDER = ("exact", "inferred", "heuristic")
+
+#: A value this build's table does not know. Reachable only from an artifact built by
+#: another version of the tool — never from a graph this build produced (the guard test
+#: is what keeps that true), so it is reported, not raised, when a graph is merely read.
+UNKNOWN_CONFIDENCE = "unknown"
+
+
+def resolution_of(edge, *, strict: bool = True) -> dict[str, str] | None:
+    """The table row for ``edge``, or ``None`` when it carries no ``resolution``.
+
+    ``None`` is a legitimate answer (``contains`` has no route), and it is distinct from
+    a value the table does not know. Under ``strict`` that one raises — a silent unknown
+    is how an open vocabulary pretends to be closed — and this is the form the guard test
+    and the extractor use. Reading a *foreign* graph passes ``strict=False`` and gets an
+    ``unknown`` grade instead: refusing to open an artifact from another version is a
+    worse answer than saying which part of it this build cannot grade.
+    """
+    value = edge.extras.get("resolution")
+    if value is None:
+        return None
+    row = RESOLUTIONS.get((edge.type, value))
+    if row is None:
+        if not strict:
+            return {"means": "route", "confidence": UNKNOWN_CONFIDENCE,
+                    "how": f"{value!r} is not in this build's table"}
+        raise KeyError(f"unknown resolution {value!r} on a {edge.type!r} edge — add it to "
+                       f"RESOLUTIONS (codemap/model.py) with its meaning and grade")
+    return row
+
+
+def confidence_of(edge, *, strict: bool = True) -> str | None:
+    """Grade of ``edge``: exact | inferred | heuristic, or ``None`` when it has no route."""
+    row = resolution_of(edge, strict=strict)
+    return row["confidence"] if row else None
+
+
 # The subset of EDGE_TYPES an incremental build splices from the old graph for modules
 # it did not recompute (``incremental.py``) — and therefore the classes a deep+incremental
 # graph answers from an *earlier* build's jedi sample (R1-C43). Lives with the vocabulary

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

@@ -13,7 +13,19 @@ import re
 
 import networkx as nx
 
-from codemap.model import Graph, Node
+from codemap.model import CONFIDENCE_ORDER, Graph, Node, confidence_of
+
+
+def _grade_rank(grade: str | None) -> int:
+    """Route grades ordered strongest-first (R1-C39); an unknown one sorts last."""
+    return CONFIDENCE_ORDER.index(grade) if grade in CONFIDENCE_ORDER else len(CONFIDENCE_ORDER)
+
+
+def _check_grade(min_confidence: str | None) -> None:
+    if min_confidence is not None and min_confidence not in CONFIDENCE_ORDER:
+        raise ValueError(f"min_confidence must be one of {CONFIDENCE_ORDER}, "
+                         f"got {min_confidence!r}")
+
 
 # Dead-code confidence, most-certain first (R1-C8). "high" = no inbound edge of any
 # kind and no decorator/registry hook; "medium" = an implicit-use hook (decorator /
@@ -162,7 +174,16 @@ class Query:
         self._call_in: dict[str, list[tuple[str, dict]]] = {}
         for e in graph.edges:
             if e.type == "calls":
-                self._calls.add_edge(e.source, e.target)
+                # R1-C39: the grade of the route rides on the graph edge, so `callers` /
+                # `callees` can answer "only what a binding found". Two edges may collapse
+                # onto one pair (a call resolved exactly at one site, fanned out from a
+                # registry at another) — the *strongest* wins: the pair is genuinely
+                # connected by a binding, whatever else also points that way.
+                grade = confidence_of(e, strict=False)
+                prev = self._calls.edges.get((e.source, e.target), {}).get("confidence")
+                if prev is not None and _grade_rank(prev) < _grade_rank(grade):
+                    grade = prev
+                self._calls.add_edge(e.source, e.target, confidence=grade)
                 self._call_in.setdefault(e.target, []).append((e.source, e.extras))
         # implements edges (M9/F4): concrete impl -> Protocol (structural typing,
         # synthesised via the registry family since it's never inherited).
@@ -412,17 +433,53 @@ class Query:
 
     # -- call graph (M4, best-effort — see gaps/ CM-09) ----------------------
 
-    def callers(self, symbol_id: str) -> list[str]:
-        """Functions that statically call ``symbol_id`` (resolved calls only)."""
-        if symbol_id not in self._calls:
-            return []
-        return sorted(self._calls.predecessors(symbol_id))
+    def callers(self, symbol_id: str, *, min_confidence: str | None = None) -> list[str]:
+        """Functions that statically call ``symbol_id`` (resolved calls only).
 
-    def callees(self, symbol_id: str) -> list[str]:
-        """Internal symbols ``symbol_id`` statically calls."""
+        ``min_confidence`` (R1-C39) keeps only edges whose route grades at least that
+        strong — ``"exact"`` asks for calls a *binding* found and drops the honest
+        over-approximations (a factory fanned out across a registry family). Default:
+        every resolved edge, whatever found it.
+        """
+        _check_grade(min_confidence)  # before the membership test: a bad argument must
+        if symbol_id not in self._calls:  # not pass silently just because the symbol is
+            return []                     # absent from the call graph
+        return sorted(src for src in self._calls.predecessors(symbol_id)
+                      if self._passes(src, symbol_id, min_confidence))
+
+    def callees(self, symbol_id: str, *, min_confidence: str | None = None) -> list[str]:
+        """Internal symbols ``symbol_id`` statically calls (see :meth:`callers`)."""
+        _check_grade(min_confidence)
         if symbol_id not in self._calls:
             return []
-        return sorted(self._calls.successors(symbol_id))
+        return sorted(tgt for tgt in self._calls.successors(symbol_id)
+                      if self._passes(symbol_id, tgt, min_confidence))
+
+    def _passes(self, source: str, target: str, min_confidence: str | None) -> bool:
+        if min_confidence is None:
+            return True
+        grade = self._calls.edges[source, target].get("confidence")
+        return _grade_rank(grade) <= _grade_rank(min_confidence)
+
+    def confidence_map(self) -> dict[str, dict[str, int]]:
+        """Edge counts by route grade, and by (edge type, resolution) pair — R1-C39.
+
+        The answer to "how much of this graph was found by a binding, and how much by a
+        name match", which no field of the artifact stated before: the route was on every
+        edge, but nothing said what a route is worth. Edges with no route at all
+        (``contains``, ``inherits``, …) are counted under ``none`` rather than dropped —
+        absence is a number here too (R1-C28).
+        """
+        by_grade: dict[str, int] = {}
+        by_pair: dict[str, int] = {}
+        for e in self.graph.edges:
+            grade = confidence_of(e, strict=False) or "none"
+            by_grade[grade] = by_grade.get(grade, 0) + 1
+            if e.extras.get("resolution") is not None:
+                key = f"{e.type}:{e.extras['resolution']}"
+                by_pair[key] = by_pair.get(key, 0) + 1
+        return {"by_grade": dict(sorted(by_grade.items())),
+                "by_pair": dict(sorted(by_pair.items()))}
 
     def call_contract(self, symbol_id: str) -> list[dict]:
         """Per-caller argument contract of calls into ``symbol_id`` (+ members) — F7.
@@ -777,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.
 
@@ -815,6 +929,69 @@ class Query:
         return {"entry": entry, "edges": edges, "reached": len(seen) - 1,
                 "max_depth": max((e["distance"] for e in edges), default=0)}
 
+    def flows_to(self, symbol_id: str, *, max_depth: int = 5,
+                 root: str = "core") -> dict:
+        """Which flows a change to ``symbol_id`` lands on, and at which step (R1-C40).
+
+        The join of the two ends codemap already had: :meth:`impact` walks inbound
+        ("who references"), :meth:`flow` walks outbound ("what a call sets in
+        motion"), and neither answers the question asked *before* a change — "what
+        stops working, and where in the scenario". A flow here is what ``flows``
+        already calls one: an entry point of ``root`` (:meth:`entry_points`).
+        ``first_step`` is the shortest distance in ``calls`` edges from that entry
+        to the symbol **or one of its members** — shortest because "first" is what
+        was asked, and a BFS gives the minimum by construction.
+
+        Computed as one reverse BFS from the targets rather than a forward walk per
+        entry: the distance is the same measured from either end, and the cost drops
+        from O(entries × graph) to O(graph). The equivalence is what the acceptance
+        test checks against :meth:`flow`.
+
+        Says "reached", never "broken" (design D3): the graph knows the symbol lies
+        on the path, not whether the edit breaks it. Three separate partialities are
+        named rather than folded into the list — ``non_call_refs`` (a reference that
+        arrives by import / inheritance / decoration / attribute access cannot appear
+        in a flow at all), ``beyond_depth`` (entries that do reach, further than
+        ``max_depth`` — counted, not silently dropped), and the standing note that
+        call resolution is a lower bound. ``in_call_graph: False`` is the honest
+        "nothing to say about flows" for a symbol the call layer never modelled — not
+        the same answer as an empty list (R1-C44).
+        """
+        targets = {i for i in self._member_ids(symbol_id) if i in self._calls}
+        entries = self.entry_points(root)
+        refs = self.references_to(symbol_id)
+        out = {
+            "symbol": symbol_id, "root": root, "max_depth": max_depth,
+            "in_call_graph": bool(targets), "entry_points": len(entries),
+            "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:
+            return out
+        dist = {t: 0 for t in targets}
+        frontier, step = set(targets), 0
+        while frontier:
+            nxt: set[str] = set()
+            for node in sorted(frontier):
+                for pred in self._calls.predecessors(node):
+                    if pred not in dist:
+                        dist[pred] = step + 1
+                        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,
+                         "external_callers": self.external_callers(e, root)}
+                        for d, e 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) -------------------------------------------
 
     def _expand_seeds(self, seeds) -> set[str]:

{codmap-0.0.15 → 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.15 → codmap-0.0.17}/codemap/serve/audit.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from codemap.diagnostics import diagnostics, render_lines
+from codemap.model import CONFIDENCE_ORDER, RESOLUTIONS, UNKNOWN_CONFIDENCE
 from codemap.query import Query
 from codemap.tomlio import read_toml
 
@@ -250,6 +251,22 @@ def render_behavior(query: Query) -> str:
             by_res[e.extras.get("resolution", "?")] = by_res.get(e.extras.get("resolution", "?"), 0) + 1
     calls_edges = sum(by_res.values())
     lines.append(f"_Emitted {calls_edges} `calls` edges (deduped caller→callee)._")
+    # R1-C39: the route was already on every edge; what a route is worth was not.
+    grades: dict[str, int] = {}
+    for value, count in by_res.items():
+        row = RESOLUTIONS.get(("calls", value))
+        grade = row["confidence"] if row else UNKNOWN_CONFIDENCE
+        grades[grade] = grades.get(grade, 0) + count
+    if grades:
+        lines.append("")
+        lines.append("- by route grade: " + ", ".join(
+            f"**{g}** {grades[g]}" for g in CONFIDENCE_ORDER if g in grades)
+            + (f", unknown {grades[UNKNOWN_CONFIDENCE]}"
+               if UNKNOWN_CONFIDENCE in grades else ""))
+        lines.append("")
+        lines.append("_`exact` — a binding read from the source found the target; "
+                     "`inferred` — a type-inference engine did (precise, but one deep "
+                     "build is a sample); `heuristic` — a name match, not a binding._")
     bridged = by_res.get("registry", 0) + by_res.get("registry-candidate", 0)
     if bridged:
         lines.append("")