codmap 0.0.16__tar.gz → 0.0.18__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.16
+Version: 0.0.18
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **938 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.16 → codmap-0.0.18}/README.md

@@ -8,7 +8,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **938 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.16 → codmap-0.0.18}/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.18}/codemap/query.py

@@ -21,6 +21,25 @@ def _grade_rank(grade: str | None) -> int:
     return CONFIDENCE_ORDER.index(grade) if grade in CONFIDENCE_ORDER else len(CONFIDENCE_ORDER)
 
 
+def _canonical_cycles(cycles) -> list[list[str]]:
+    """Cycles in a stable form: each rotated to start at its smallest node, then sorted.
+
+    R1-C54, reported by the lab as [issue #20](https://github.com/kogriv/codemap/issues/20).
+    ``nx.simple_cycles`` yields a cycle starting wherever its traversal happened to enter
+    it, and that traversal follows set-iteration order, i.e. string hashes. The chain is
+    the *same cycle* either way — but three consumers print it, and they printed three
+    different texts for one graph across eight hash seeds.
+
+    The sort afterwards is the point of the rotation: ``arch.py`` already sorted cycles by
+    ``(len, c)`` and that looked like canonicalisation, except the key itself moved with
+    the rotation — ``["a","b"]`` and ``["b","a"]`` are one cycle and two keys. Rotating
+    first makes the existing sort mean what it appeared to mean.
+    """
+    out = [c[i:] + c[:i] for c in (list(x) for x in cycles)
+           if (i := c.index(min(c))) >= 0]
+    return sorted(out, key=lambda c: (len(c), c))
+
+
 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}, "
@@ -834,18 +853,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 +982,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 +999,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) -------------------------------------------
@@ -1004,7 +1088,7 @@ class Query:
         would report someone's fix as their bug. Those cycles are still real coupling
         and are returned by :meth:`lazy_import_cycles`.
         """
-        return [c for c in nx.simple_cycles(self._imports_eager)]
+        return _canonical_cycles(nx.simple_cycles(self._imports_eager))
 
     def lazy_import_cycles(self) -> list[list[str]]:
         """Dependency cycles that close **only** through a function-local import.
@@ -1022,8 +1106,8 @@ class Query:
         them, or a tree could hide real coupling by adding one.
         """
         eager = {frozenset(c) for c in nx.simple_cycles(self._imports_eager)}
-        return [c for c in nx.simple_cycles(self._imports_runtime)
-                if frozenset(c) not in eager]
+        return _canonical_cycles(c for c in nx.simple_cycles(self._imports_runtime)
+                                 if frozenset(c) not in eager)
 
     def type_only_import_cycles(self) -> list[list[str]]:
         """Dependency cycles that close **only** with an import under ``if TYPE_CHECKING:``.
@@ -1035,7 +1119,8 @@ class Query:
         opt-in rule instead.
         """
         runtime = {frozenset(c) for c in nx.simple_cycles(self._imports_runtime)}
-        return [c for c in nx.simple_cycles(self._imports) if frozenset(c) not in runtime]
+        return _canonical_cycles(c for c in nx.simple_cycles(self._imports)
+                                 if frozenset(c) not in runtime)
 
     def import_map(self) -> dict:
         """How much of the import graph each scope contributed (R1-C29).

{codmap-0.0.16 → codmap-0.0.18}/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.18}/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.18}/codemap/serve/mermaid.py

@@ -117,4 +117,16 @@ def render_mermaid(query: Query, kind: str, scope: str | None = None,
         return render_call_graph(query, root, depth)
     if kind not in _KINDS:
         raise ValueError(f"unknown mermaid kind: {kind}")
-    return _KINDS[kind](query, scope)
+    out = _KINDS[kind](query, scope)
+    if scope:
+        # R1-C53: `--scope` cut this diagram from 144 lines to 47 on the dogfood tree with
+        # no marker of any kind, so the picture read as "the class diagram of this package".
+        # A diagram is an answer too. Mermaid ignores `%%` lines, so the note costs nothing
+        # rendered and is visible in the source a reader diffs or pastes.
+        hidden = len(_KINDS[kind](query, None).splitlines()) - len(out.splitlines())
+        note = (f"%% scope: {scope} — {hidden} further line(s) exist in the unscoped "
+                "diagram of this graph")
+        lines = out.splitlines()
+        at = 1 if lines and lines[0].startswith("```") else 0
+        out = "\n".join(lines[:at] + [note] + lines[at:]) + "\n"
+    return out

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

@@ -50,6 +50,15 @@ _REPORTS = {
 #                     jedi sample (R1-C43).
 # `accessors` used to be in neither — it reads `accesses`, modelled best-effort, and
 # carried no `epistemic` at all (found by the R1-C44 measurement).
+# R1-C53 added the three column ops: they read `reads`/`writes`, which are an **over-set**
+# rather than a lower bound — a different partiality, so it gets its own reason below.
+#
+# `query` was considered here and deliberately left out. Its dossier *does* carry
+# call-derived fields, but most of it — where the symbol is defined, its signature, its
+# file — is exact, and one envelope-wide "this is a lower bound" would say the definition
+# is uncertain too. The rule this file already states is "absence of the label means
+# exact", so a **mixed** answer declares per field (see `_op_query`), not per envelope.
+# Over-claiming partiality is the same defect as hiding it, pointed the other way.
 _OP_EDGE_CLASSES = {
     "callers": frozenset({"calls"}),
     "callees": frozenset({"calls"}),
@@ -59,10 +68,19 @@ _OP_EDGE_CLASSES = {
     "accessors": frozenset({"accesses"}),
     "tests": frozenset({"calls", "references"}),
     "covers": frozenset({"calls", "references"}),
+    "column": frozenset({"reads", "writes"}),
+    "columns": frozenset({"reads", "writes"}),
+    "columns_of": frozenset({"reads", "writes"}),
 }
 _BEST_EFFORT_CLASSES = frozenset({"calls", "accesses"})
+#: Classes that are an over-set, not a lower bound: a literal subscript key cannot be told
+#: from a dict key, so the column set contains more than the DataFrame columns (F15/M12).
+#: The opposite error from `_BEST_EFFORT_CLASSES`, and it must not borrow its wording.
+_OVER_SET_CLASSES = frozenset({"reads", "writes"})
 _PARTIAL_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
-                         if cls & _BEST_EFFORT_CLASSES)
+                         if cls & (_BEST_EFFORT_CLASSES | _OVER_SET_CLASSES))
+_OVER_SET_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
+                          if cls & _OVER_SET_CLASSES)
 _SPLICE_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
                         if cls & _SPLICED_EDGE_TYPES)
 _EPISTEMIC_PARTIAL = {
@@ -70,6 +88,15 @@ _EPISTEMIC_PARTIAL = {
     "reason": "leans on static resolution of calls and attribute accesses (partial "
               "for Python) — a lower bound; pair with grep/tests before acting.",
 }
+# R1-C53: the over-set is partial in the *other* direction, and saying "a lower bound"
+# about it would be worse than saying nothing. A caller that trims by this set would trim
+# too little, not too much.
+_EPISTEMIC_OVER_SET = {
+    "epistemic": "partial",
+    "reason": "string-keyed dataflow is an **over-set**, not a lower bound: a literal "
+              "subscript key cannot be told from a dict key, so this set contains more "
+              "than the DataFrame columns. Confirm a key before acting on it.",
+}
 # D4 — the second reason, named separately: "a lower bound by static resolution" and
 # "part of this graph was carried over, not recomputed" are different facts.
 _EPISTEMIC_SPLICE = (
@@ -118,6 +145,38 @@ _UNLIMITED_BY_DESIGN = {
 }
 
 
+def _root_scope(query: Query, root: str, judged: list) -> dict:
+    """The `scope` block: which provenance root the answer covers, and what it leaves out.
+
+    R1-C53. `communities` judges the package and is silent about it; on a repo-scoped graph
+    a caller reads "9 subsystems" without learning that `tests` was never considered. Same
+    shape as `check`'s "not judged" line and `diff`'s root filter, now stated in one place.
+    """
+    others: dict[str, int] = {}
+    for n in query.graph.nodes.values():
+        if n.kind != "module":
+            continue
+        r = query.root_of(n.id)
+        if r != root:
+            others[r] = others.get(r, 0) + 1
+    return {"root": root, "judged": len(judged),
+            "not_judged": dict(sorted(others.items()))}
+
+
+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.
 
@@ -243,6 +302,17 @@ def build_query_result(q: Query, name: str) -> dict:
                     used_by[n.id] = by_root
         if used_by:
             result["used_by"] = used_by
+            # R1-C53: the dossier is *mixed* — `defined_at`, `matches` and the signatures
+            # are exact, while `used_by` comes from the same best-effort call/reference
+            # layer that makes `callers` a lower bound. An envelope-wide `epistemic` would
+            # have said the definition is uncertain too, and over-claiming partiality is
+            # the same defect as hiding it. So it is declared on the field, here — where
+            # the field is built — so the CLI dossier carries it as well as the op.
+            result["used_by_epistemic"] = (
+                "lower bound — `used_by` comes from statically resolved calls and "
+                "references (partial for Python); `defined_at` and the signatures are "
+                "exact. `callers`/`impact` carry the same caveat for a whole answer."
+            )
     col = q.column(name)
     if col and (col["writes"] or col["reads"]):
         result["column"] = col
@@ -319,6 +389,8 @@ class Session:
                     "ops": sorted(_OPS)}
         self._resolution = None
         self._limit = None
+        self._filter = None
+        self._scope = None
         try:
             env = {"ok": True, "result": fn(self, args)}
         except Exception as exc:  # a bad arg must not kill the resident process
@@ -335,6 +407,21 @@ 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
+        # R1-C53: the third class. A `scope` narrowing is not a cut of a computed list and
+        # not a predicate over it — it is the answer covering **one provenance root** while
+        # the graph holds several, which is how `diff` came to count 40 test functions as
+        # API and how `communities` judges only the package while saying nothing.
+        if self._scope is not None:
+            env["scope"] = self._scope
         return env
 
     def _epistemic(self, op: str) -> dict:
@@ -344,7 +431,7 @@ class Session:
         sample, and only an op reading a spliced class reads it. On a full deep graph
         and on the fast tier the block is exactly the R1-C13 one.
         """
-        block = dict(_EPISTEMIC_PARTIAL)
+        block = dict(_EPISTEMIC_OVER_SET if op in _OVER_SET_OPS else _EPISTEMIC_PARTIAL)
         prov = self.graph.provenance or {}
         if op in _SPLICE_OPS and prov.get("tier") == "deep":
             if prov.get("incremental") is True:
@@ -443,7 +530,7 @@ class Session:
         result = build_query_result(self.query, args["name"])
         if not result["matches"]:  # R1-C44: an empty dossier says why it is empty
             self._resolution = _not_found(args["name"])
-        return result
+        return result  # the mixed-answer note rides on the field (see build_query_result)
 
     def _op_impact(self, args) -> dict:
         sym = args["symbol"]
@@ -488,7 +575,18 @@ class Session:
     def _op_columns(self, args) -> list:
         # F15: default to subscript-accessed keys (the real column-like set);
         # pass all=true for the full over-set incl. dict-literal payload keys.
-        return self.query.columns(subscripted_only=not args.get("all", False))
+        narrow = not args.get("all", False)
+        kept = self.query.columns(subscripted_only=narrow)
+        # R1-C53: the default hides the larger half and said nothing — measured on the
+        # dogfood tree, 331 of 1057. A deliberate narrowing still has to be declared, or
+        # the caller reads 331 as the answer to "which columns exist".
+        every = self.query.columns(subscripted_only=False) if narrow else kept
+        self._filter = {"basis": "subscripted_only" if narrow else None,
+                        "returned": len(kept), "total": len(every),
+                        "dropped": len(every) - len(kept),
+                        "note": "a key reached only through a dict literal is not a "
+                                "subscript access; pass all=true for the full over-set"}
+        return kept
 
     def _op_columns_of(self, args) -> dict:
         return self.query.columns_of(self._canon(args["symbol"]))
@@ -518,12 +616,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"]))
@@ -583,14 +689,38 @@ class Session:
         return build_check(self.query, contract, check_contract(self.query, contract))
 
     def _op_communities(self, args) -> list:
-        """R1-C18: data-driven module subsystems (greedy modularity)."""
-        return self.query.communities()
+        """R1-C18: data-driven module subsystems (greedy modularity).
+
+        R1-C53: subsystems are computed over the **package** only — a consumer root is not
+        a subsystem of it — and that was true in the code and absent from the answer.
+        """
+        out = self.query.communities()
+        self._scope = _root_scope(self.query, "core",
+                                  [m for c in out for m in c["modules"]])
+        return out
 
     def _op_flows(self, args) -> dict:
-        """R1-C18: forward call-flow from a symbol, or entry points if none given."""
+        """R1-C18: forward call-flow from a symbol, or entry points if none given.
+
+        R1-C53: the entry-point list is shaped by a *definition* — "calls out, and nothing
+        in its own root calls it" — which R1-C50 had to change after it disqualified a
+        library's public API for being used. A definition that can be wrong for a target
+        belongs in the answer, not only in a docstring.
+        """
         sym = args.get("symbol")
         if not sym:
-            return {"entry_points": self.query.entry_points()}
+            entries = self.query.entry_points()
+            self._scope = _root_scope(self.query, "core", entries)
+            return {
+                "entry_points": entries,
+                "definition": "a function that calls out and is called by nothing in its "
+                              "own provenance root; a call from `tests`/`examples` is a "
+                              "use, not an internal caller (R1-C50)",
+                "best_effort_both_ways": "an unresolved caller leaves a real internal "
+                                         "looking like an entry point, and resolving one "
+                                         "removes an entry point — so a more complete "
+                                         "graph can list fewer",
+            }
         return self.query.flow(self._canon(sym), max_depth=int(args.get("depth", 5)))
 
     def _op_semantic(self, args) -> dict:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.16
+Version: 0.0.18
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **938 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

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

@@ -121,6 +121,9 @@ 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_r1c53_narrowing_declared.py
+tests/test_r1c54_deterministic_rendering.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py
 tests/test_r1c7_edge_vocab.py

{codmap-0.0.16 → codmap-0.0.18}/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.18"
 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