codmap 0.0.15__tar.gz → 0.0.16__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.15
+Version: 0.0.16
 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.16}/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.16}/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.16}/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.16}/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.
@@ -815,6 +872,61 @@ 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,
+            "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}
+                        for d, e in reaching if d <= max_depth]
+        out["beyond_depth"] = sum(1 for d, _ in reaching if d > max_depth)
+        return out
+
     # -- relevance ranking (R1-C6) -------------------------------------------
 
     def _expand_seeds(self, seeds) -> set[str]:

{codmap-0.0.15 → codmap-0.0.16}/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("")

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

@@ -11,7 +11,57 @@ from __future__ import annotations
 from codemap.query import Query
 
 
-def render_impact(query: Query, symbol: str, *, depth: int = 2) -> str:
+_FLOW_ROWS = 40
+
+
+def _flow_section(rep: dict) -> list[str]:
+    """R1-C40: which scenarios the change lands on, and at which step.
+
+    The three partialities of `Query.flows_to` are rendered as words, not left for the
+    reader to infer from a short list: an empty flow list next to twenty references is
+    the exact shape that reads as "nothing will break" when it means "the flow layer
+    cannot see this kind of edge".
+    """
+    lines = [f"### Flows reached ({len(rep['flows'])} of {rep['entry_points']} "
+             f"entry point(s) in root `{rep['root']}`)", ""]
+    if not rep["in_call_graph"]:
+        lines += ["_The call layer never modelled this symbol — no resolved call reaches "
+                  "it or leaves it — so there is nothing to say about flows here. This is "
+                  "not 'no flow reaches it'._", ""]
+        return lines
+    if rep["flows"]:
+        lines.append("_`step` — where in the flow the change first lands: 1 means the "
+                     "entry point calls it directly, 0 that the entry point is the "
+                     "symbol itself (or one of its members), so the flow starts inside "
+                     "the change._")
+        lines.append("")
+        for f in rep["flows"][:_FLOW_ROWS]:
+            lines.append(f"- `{f['entry']}` — step {f['first_step']}")
+        if len(rep["flows"]) > _FLOW_ROWS:
+            lines.append(f"- _… {len(rep['flows']) - _FLOW_ROWS} more_")
+    else:
+        lines.append(f"_No entry point reaches it within {rep['max_depth']} step(s)._")
+    lines.append("")
+    notes = []
+    if rep["beyond_depth"]:
+        notes.append(f"{rep['beyond_depth']} further entry point(s) reach it **beyond** "
+                     f"{rep['max_depth']} steps — 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.")
+    lines.append("_" + " ".join(notes) + "_")
+    lines.append("")
+    return lines
+
+
+def render_impact(query: Query, symbol: str, *, depth: int = 2,
+                  flow_depth: int = 5) -> str:
     """Markdown blast-radius for the symbol matching ``symbol`` (short or full)."""
     ids = query.impact_targets(symbol)  # F23: short name / full id / re-export
     lines = [f"# Impact — `{symbol}`", ""]
@@ -64,6 +114,9 @@ def render_impact(query: Query, symbol: str, *, depth: int = 2) -> str:
                 lines.append(f"- _+{len(indirect)} transitive (distance >1)_")
             lines.append("")
 
+        # R1-C40: from "who references" to "what stops working, and where".
+        lines += _flow_section(query.flows_to(sid, max_depth=flow_depth))
+
         # F7: argument contract of the call-sites — what a signature change touches.
         contract = query.call_contract(sid)
         if contract:

{codmap-0.0.15 → codmap-0.0.16}/codemap/serve/mcp_server.py

@@ -55,15 +55,27 @@ def _compact_impact(env: dict, limit: int) -> dict:
     for e in result.get("impact", []):
         refs = e.get("refs", [])
         shown = min(limit, len(refs))
-        entries.append({**e, "refs": refs[:limit],
-                        "refs_shown": shown, "refs_total": len(refs)})
+        entry = {**e, "refs": refs[:limit],
+                 "refs_shown": shown, "refs_total": len(refs)}
+        # R1-C40: the flows section is a second computed list, cut here as well — in its
+        # own vocabulary, so a reader never has to guess which list the envelope's summed
+        # block describes (it is the refs one).
+        flows = e.get("flows")
+        if isinstance(flows, dict):
+            listed = flows.get("flows", [])
+            entry["flows"] = {**flows, "flows": listed[:limit],
+                              "flows_shown": min(limit, len(listed)),
+                              "flows_total": len(listed)}
+        entries.append(entry)
         shown_total += shown
         refs_total += len(refs)
     result["impact"] = entries
     env["result"] = result
     env["limit"] = limit_block(limit, shown_total, refs_total,
-                               note="applied per impact entry, not across the answer; "
-                                    "the by_root counts are complete regardless")
+                               note="counts the refs list, applied per impact entry, not "
+                                    "across the answer; the by_root counts are complete "
+                                    "regardless, and the flows list carries its own "
+                                    "flows_shown / flows_total")
     return env
 
 
@@ -139,14 +151,20 @@ def build_mcp_server(session: "Session", name: str = "codemap") -> Any:
         return op("resolve", {"name": name})
 
     @server.tool()
-    def callers(symbol: str) -> dict:
-        """Functions that statically call `symbol` (resolved calls only)."""
-        return op("callers", {"symbol": symbol})
+    def callers(symbol: str, min_confidence: str | None = None) -> dict:
+        """Functions that statically call `symbol` (resolved calls only).
+        `min_confidence` keeps only edges whose route grades at least that strong:
+        `exact` (a binding in the source found the target), `inferred` (a type-inference
+        engine did — precise, but one deep build samples ~3 of 4 live edges), `heuristic`
+        (a name match, e.g. a factory fanned out across a registry family). Omit for
+        every resolved edge. `stats` reports the whole graph's grade mix."""
+        return op("callers", {"symbol": symbol, "min_confidence": min_confidence})
 
     @server.tool()
-    def callees(symbol: str) -> dict:
-        """Internal symbols that `symbol` statically calls."""
-        return op("callees", {"symbol": symbol})
+    def callees(symbol: str, min_confidence: str | None = None) -> dict:
+        """Internal symbols that `symbol` statically calls. `min_confidence` as in
+        `callers`: exact | inferred | heuristic."""
+        return op("callees", {"symbol": symbol, "min_confidence": min_confidence})
 
     @server.tool()
     def tests(symbol: str, depth: int = 3, cap: int = 25) -> dict:
@@ -164,13 +182,18 @@ def build_mcp_server(session: "Session", name: str = "codemap") -> Any:
         return op("covers", {"test": test, "depth": depth, "cap": cap})
 
     @server.tool()
-    def impact(symbol: str, depth: int = 2, limit: int = 40, full: bool = False) -> dict:
+    def impact(symbol: str, depth: int = 2, limit: int = 40, full: bool = False,
+               flow_depth: int = 5) -> dict:
         """Blast radius of changing `symbol`: inbound references up to `depth`, counted
-        by provenance root (core/tests/docs/…). Compact by default (F22): omits the
-        duplicate markdown and caps the flat ref list at `limit` (by_root counts stay
-        complete, and every entry carries refs_shown/refs_total). Pass full=true for
-        the entire payload including markdown."""
-        env = op("impact", {"symbol": symbol, "depth": depth})
+        by provenance root (core/tests/docs/…), plus `flows` — which entry points reach
+        it and at which step (`first_step`), within `flow_depth`. Compact by default
+        (F22): omits the duplicate markdown and caps each list at `limit` (by_root counts
+        stay complete; entries carry refs_shown/refs_total and flows_shown/flows_total).
+        Flows follow resolved `calls` edges only: `non_call_refs` says how many
+        references cannot appear there, `beyond_depth` how many entries reach further,
+        and `in_call_graph: false` means the call layer never modelled the symbol — not
+        that no flow reaches it. Pass full=true for the entire payload with markdown."""
+        env = op("impact", {"symbol": symbol, "depth": depth, "flow_depth": flow_depth})
         return env if full else _compact_impact(env, limit)
 
     @server.tool()

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

@@ -110,7 +110,10 @@ _UNLIMITED_BY_DESIGN = {
     "pack": "budget is a token budget the caller sets on purpose, and the result is "
             "explicitly a *pack* — self-describing by construction",
     "impact": "depth bounds the walk, it does not slice a computed list; the reach is "
-              "already echoed back as by_distance / max_distance",
+              "already echoed back as by_distance / max_distance, and flow_depth "
+              "likewise bounds the flow walk while counting what lies past it "
+              "(beyond_depth). Both lists come back whole here; the transport cut "
+              "lives in _compact_impact and declares itself there (R1-C40)",
     "flows": "depth likewise bounds the walk, and the answer carries its own depth",
 }
 
@@ -367,6 +370,9 @@ class Session:
             "edges": len(self.graph.edges),
             "node_kinds": dict(Counter(n.kind for n in self.graph.nodes.values())),
             "edge_types": dict(Counter(e.type for e in self.graph.edges)),
+            # R1-C39: how much of this graph a binding found, and how much a name match.
+            # The route was always on the edge; what it is worth was never stated.
+            "confidence": self.query.confidence_map(),
         }
         # M18 + #3: age of the graph WE SERVE (not the on-disk file), with an explicit
         # stale flag when the artifact was rebuilt after we loaded it.
@@ -442,13 +448,20 @@ class Session:
     def _op_impact(self, args) -> dict:
         sym = args["symbol"]
         depth = int(args.get("depth", 2))
+        flow_depth = int(args.get("flow_depth", 5))
         ids = self.query.impact_targets(sym)  # F23: accept full id / re-export too
         if not ids:  # R1-C44: this op resolves on its own, so it records on its own
             self._resolution = _not_found(sym)
         return {
             "symbol": sym,
-            "impact": [self.query.impact(sid, depth=depth) for sid in ids],
-            "markdown": render_impact(self.query, sym, depth=depth),
+            # R1-C40: blast radius and the flows it lands on are two answers kept side by
+            # side, not merged — "who references" and "where in a scenario the change
+            # first bites" have different partialities, and each states its own.
+            "impact": [{**self.query.impact(sid, depth=depth),
+                        "flows": self.query.flows_to(sid, max_depth=flow_depth)}
+                       for sid in ids],
+            "markdown": render_impact(self.query, sym, depth=depth,
+                                      flow_depth=flow_depth),
         }
 
     def _op_resolve(self, args) -> dict | None:
@@ -505,10 +518,12 @@ class Session:
         return res
 
     def _op_callers(self, args) -> list:
-        return self.query.callers(self._canon(args["symbol"]))
+        return self.query.callers(self._canon(args["symbol"]),
+                                  min_confidence=args.get("min_confidence"))
 
     def _op_callees(self, args) -> list:
-        return self.query.callees(self._canon(args["symbol"]))
+        return self.query.callees(self._canon(args["symbol"]),
+                                  min_confidence=args.get("min_confidence"))
 
     def _op_implementers(self, args) -> list:
         return self.query.implementers(self._canon(args["protocol"]))

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.15
+Version: 0.0.16
 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.16}/codmap.egg-info/SOURCES.txt

@@ -107,8 +107,10 @@ tests/test_r1c35_contract_location.py
 tests/test_r1c36_target_resolution.py
 tests/test_r1c37_rule_mutation.py
 tests/test_r1c38_tool_drift.py
+tests/test_r1c39_edge_resolution.py
 tests/test_r1c3_arch_contract.py
 tests/test_r1c3_dogfood.py
+tests/test_r1c40_flow_reach.py
 tests/test_r1c41_scope_membership.py
 tests/test_r1c42_deep_tier_stability.py
 tests/test_r1c43_incremental_splice.py

{codmap-0.0.15 → codmap-0.0.16}/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.15"
+version = "0.0.16"
 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