codmap 0.0.18__tar.gz → 0.0.20__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.18
+Version: 0.0.20
 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, **938 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **972 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.18 → codmap-0.0.20}/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, **938 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **972 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.18 → codmap-0.0.20}/codemap/arch.py

@@ -133,6 +133,20 @@ def _core_layer_edges(query) -> list[tuple[str, str, str, str]]:
     return out
 
 
+
+def _tangle_line(tangle: dict) -> str:
+    """One gate line per tangle: the example cycle, then the members (R1-C58).
+
+    The example comes first because it is what a reader acts on; the membership follows
+    because the tangle, not the cycle, is what has to be broken.
+    """
+    ex = tangle["example"]
+    head = " → ".join(ex) + " → " + ex[0]
+    if tangle["size"] <= len(ex):
+        return head
+    return f"{head} (tangle of {tangle['size']}: {', '.join(tangle['modules'])})"
+
+
 def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
     """Evaluate every rule against the graph; return the violations (empty = clean)."""
     if contract.is_empty():
@@ -192,13 +206,16 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
     # migrated into the gate. So: the gate stays eager, the *disclosure* is mandatory (see
     # `build_check`), and a contract that wants the coupling gated says so.
     if contract.no_cycles:
-        cycles = query.import_cycles()
-        if cycles:
-            worst = sorted(cycles, key=lambda c: (len(c), c))
+        tangles = query.import_tangles()
+        if tangles:
+            # R1-C58: one violation per **tangle**, not per simple cycle. A tangle of 19
+            # modules used to produce 1080 violations that were all the same problem, and
+            # the gate's own output then took a thousand lines to say it once.
             violations.append(Violation(
                 "no_cycles",
-                f"{len(cycles)} import cycle(s)",
-                modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
+                f"{len(tangles)} import tangle(s), "
+                f"{sum(t['size'] for t in tangles)} module(s)",
+                modules=tuple(_tangle_line(t) for t in tangles),
             ))
 
     # -- no_lazy_cycles: opt in to gating the coupling a lazy import hides -------
@@ -206,13 +223,13 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
     # not a gate, and a lazy import is the accepted way to break an import cycle — so this
     # is the contract owner's call to state, not a default to pick on their behalf.
     if contract.no_lazy_cycles:
-        lazy = query.lazy_import_cycles()
+        lazy = query.lazy_import_tangles()
         if lazy:
-            worst = sorted(lazy, key=lambda c: (len(c), c))
             violations.append(Violation(
                 "no_lazy_cycles",
-                f"{len(lazy)} dependency cycle(s) closed only by a function-local import",
-                modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
+                f"{len(lazy)} tangle(s) closed only by a function-local import, "
+                f"{sum(t['size'] for t in lazy)} module(s)",
+                modules=tuple(_tangle_line(t) for t in lazy),
             ))
 
     # -- no_type_only_cycles: the third kind, and the one with no runtime dependency ----
@@ -223,14 +240,14 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
     # against lazy imports used as a way around `no_cycles`, and the standard typing
     # idiom is not that.
     if contract.no_type_only_cycles:
-        type_only = query.type_only_import_cycles()
+        type_only = query.type_only_import_tangles()
         if type_only:
-            worst = sorted(type_only, key=lambda c: (len(c), c))
             violations.append(Violation(
                 "no_type_only_cycles",
-                f"{len(type_only)} dependency cycle(s) closed only by an import under "
-                f"`if TYPE_CHECKING:`",
-                modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
+                f"{len(type_only)} tangle(s) closed only by an import that never runs "
+                f"(`if TYPE_CHECKING:` or a `.pyi`), "
+                f"{sum(t['size'] for t in type_only)} module(s)",
+                modules=tuple(_tangle_line(t) for t in type_only),
             ))
 
     # -- exhaustive: every core module's layer must be declared -----------------

{codmap-0.0.18 → codmap-0.0.20}/codemap/extract/griffe_extractor.py

@@ -80,6 +80,63 @@ def _assert_is_the_target(loaded, pkg_dir: Path, module_name: str) -> None:
         )
 
 
+#: How many sibling packages one load may pull in before we stop trying (R1-C57).
+_MAX_SIBLING_LOADS = 8
+
+
+def _load_with_siblings(module_name: str, search_path: Path):
+    """``griffe.load`` the target, pulling in siblings its re-exports point at (R1-C57).
+
+    The facade shape — a public package whose whole job is to re-export a private one,
+    as ``pytest``/``_pytest`` and ``attrs``/``attr`` do — used to **crash the build**:
+    griffe merges a ``.pyi`` beside ``__init__.py``, that merge resolves aliases, and an
+    alias into a package nobody loaded raises ``AliasResolutionError``. Exit code 1, no
+    graph, for a six-file package that is valid and published.
+
+    An unresolvable re-export is partiality, not a crash. So: load the sibling the alias
+    names into the *same* collection and retry. The sibling has to be there — it sits on
+    the same search path, which is how Python finds it too — and loading it does not put
+    it in the graph: the walk starts from the target's own root, and targets outside it
+    stay external, exactly as they were before.
+
+    Returns ``(root, siblings)``; ``siblings`` is what had to be pulled in, and it is
+    recorded in the input report so a reader can see the load was not self-contained.
+    """
+    collection = griffe.ModulesCollection()
+    siblings: list[str] = []
+    for _ in range(_MAX_SIBLING_LOADS + 1):
+        try:
+            return griffe.load(module_name, search_paths=[str(search_path)],
+                               try_relative_path=False,
+                               modules_collection=collection), siblings
+        except griffe.AliasResolutionError as exc:
+            top = exc.alias.target_path.split(".")[0]
+            if top == module_name or top in siblings:
+                raise                      # retrying would loop on the same alias
+            if not _package_on_path(top, search_path):
+                raise ValueError(
+                    f"`{module_name}` re-exports `{exc.alias.target_path}`, and "
+                    f"`{top}` is not beside it in {search_path}. This is the facade "
+                    f"layout (a public package re-exporting a private one): build from "
+                    f"a tree that holds both, or point codemap at the implementation "
+                    f"package instead."
+                ) from exc
+            griffe.load(top, search_paths=[str(search_path)], try_relative_path=False,
+                        modules_collection=collection)
+            siblings.append(top)
+    raise ValueError(
+        f"`{module_name}` still had unresolved re-exports after loading "
+        f"{len(siblings)} sibling package(s): {', '.join(siblings)}."
+    )
+
+
+def _package_on_path(name: str, search_path: Path) -> bool:
+    """True when ``name`` is importable as a package/module from ``search_path``."""
+    d = search_path / name
+    return (d / "__init__.py").is_file() or (d / "__init__.pyi").is_file() \
+        or (search_path / f"{name}.py").is_file() or (search_path / f"{name}.pyi").is_file()
+
+
 def build_structural(package_path: str | Path):
     """The cheap, deterministic base: griffe load + definition nodes + structural
     edges (contains / imports / inherits / decorated_by / export). No behavioral
@@ -99,7 +156,7 @@ def build_structural(package_path: str | Path):
     # a repo whose root holds `pkg/`, `build /elsewhere/pkg` then silently analysed the
     # local `pkg` — same shape of answer, different code. We always know the directory we
     # were handed, so the name must resolve through `search_paths` and nowhere else.
-    root = griffe.load(module_name, search_paths=[str(search_path)], try_relative_path=False)
+    root, siblings = _load_with_siblings(module_name, search_path)
     # Defence in depth: whatever the finder does next (a .pth file, a namespace package,
     # a future default), a graph must describe the directory that was asked for. A wrong
     # answer here is invisible downstream — it is well-formed, complete and about the
@@ -402,13 +459,18 @@ def _collect(graph, obj, root, target_pkg, walk) -> None:
         # carry, or carries under the wrong scope, in one parse.
         nested, eager = _source_import_targets(obj)
         type_checking = {tgt for tgt, scope in nested if scope == "type_checking"}
+        # R1-C56/D1: a `.pyi` is a declaration — Python never executes it, so *none* of
+        # its imports run, whatever they look like. Recorded as a fourth scope rather
+        # than borrowed from `type_checking`: the mechanism is a different one, and the
+        # cycle classes are named by mechanism.
+        stub = _is_stub(obj)
         for name, tgt in (obj.imports or {}).items():
             # griffe files an import under `if TYPE_CHECKING:` as module-level; it never
             # runs. Demote it unless the same target is also imported eagerly (D2).
             scope = "type_checking" if tgt in type_checking and tgt not in eager else "module"
-            walk.imports.append((obj.canonical_path, tgt, scope))
+            walk.imports.append((obj.canonical_path, tgt, "stub" if stub else scope))
         for tgt, scope in nested:
-            walk.imports.append((obj.canonical_path, tgt, scope))
+            walk.imports.append((obj.canonical_path, tgt, "stub" if stub else scope))
     for name, member in obj.members.items():
         if member.is_alias:
             # capture ALL re-exports (public flag kept) — a symbol can be importable
@@ -487,7 +549,7 @@ def _emit_decorated_by(graph, obj) -> None:
 #: import is a **function-local** dependency: it can execute, and labelling it by the
 #: import that cannot would let a tree launder runtime coupling into the type layer
 #: (R1-C49, and the test that says so).
-_SCOPE_RANK = {"module": 0, "function": 1, "type_checking": 2}
+_SCOPE_RANK = {"module": 0, "function": 1, "type_checking": 2, "stub": 3}
 
 
 def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
@@ -506,7 +568,18 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
             # no edge at all. Same narrow gate as pass B: only when the head names a
             # module sitting beside the re-exporter, and labelled as the inference it is.
             if _flat_sibling(parent_module, target_path, known_modules) is None:
-                continue  # external re-export (e.g. `import numpy as np`) — out of scope
+                # R1-C57: `import numpy as np` is not this package's API and stays out.
+                # A **public** alias to an outside definition is the opposite case: it is
+                # exactly what the package exposes, and dropping it made the facade layout
+                # (`pytest` re-exporting 90 names from `_pytest`) report a public surface
+                # of one symbol. Kept, with the target left as written and marked external
+                # — the definition is outside this graph, and the edge says so rather than
+                # pretending to resolve it.
+                if not is_public:
+                    continue
+                extras["external"] = True
+                graph.add_edge(Edge("export", parent_module, target_path, extras=extras))
+                continue
             target_path = f"{parent_module.rsplit('.', 1)[0]}.{target_path}"
             extras["resolution"] = "flat"
         graph.add_edge(Edge("export", parent_module, target_path, extras=extras))
@@ -599,6 +672,12 @@ def _add_node(graph, obj, root) -> None:
     )
 
 
+def _is_stub(obj) -> bool:
+    """True when ``obj`` lives in a ``.pyi`` — a declaration Python never executes."""
+    f = module_file(obj)
+    return f is not None and f.suffix == ".pyi"
+
+
 def _stub_marked(extras: dict, obj) -> dict:
     """Label a symbol that exists only in a ``.pyi`` stub (R1-C23 / design D5).
 
@@ -607,8 +686,7 @@ def _stub_marked(extras: dict, obj) -> dict:
     a stubs distribution, and leaving them unmarked presents a function that does not
     exist as if it did. Consumers that reason about execution (dead-code) exclude them.
     """
-    f = module_file(obj)
-    if f is not None and f.suffix == ".pyi":
+    if _is_stub(obj):
         extras = {**extras, "stub": True}
     return extras
 

{codmap-0.0.18 → codmap-0.0.20}/codemap/query.py

@@ -153,7 +153,10 @@ class Query:
         # R1-C49: between the two — everything that can execute. A `TYPE_CHECKING` import
         # never does, so a cycle that needs one is not runtime coupling at all.
         self._imports_runtime = nx.DiGraph()
-        self._import_scopes = {"module": 0, "function": 0, "type_checking": 0}
+        # R1-C56: `stub` is the fourth scope — a `.pyi` is never executed, so none of its
+        # imports run. Counted apart from `type_checking` (different mechanism, same
+        # consequence) and, like it, kept out of both the eager and the runtime graph.
+        self._import_scopes = {"module": 0, "function": 0, "type_checking": 0, "stub": 0}
         for n in graph.nodes.values():
             if n.kind == "module":
                 self._imports.add_node(n.id)
@@ -163,9 +166,9 @@ class Query:
             if e.type == "imports":
                 self._imports.add_edge(e.source, e.target)
                 scope = e.extras.get("scope")
-                if scope in ("function", "type_checking"):
-                    # R1-C29: runs when the function runs; R1-C48: never runs. Neither
-                    # is an import-time edge — but only the first is a runtime one.
+                if scope in ("function", "type_checking", "stub"):
+                    # R1-C29: runs when the function runs; R1-C48 and R1-C56: never runs.
+                    # Neither is an import-time edge — but only the first is a runtime one.
                     self._import_scopes[scope] += 1
                     if scope == "function":
                         self._imports_runtime.add_edge(e.source, e.target)
@@ -665,10 +668,57 @@ class Query:
             out = [c for c in out if _CONFIDENCE_RANK[c["confidence"]] >= floor]
         return out
 
+    def _overridden_base(self, n: Node) -> tuple[str, int] | None:
+        """The ancestor method ``n`` overrides, and that ancestor's inbound calls (R1-C55).
+
+        An override is not reached by its own name: the base is called and dynamic
+        dispatch lands here, so "no inbound calls" is a statement about the *name*, not
+        about the body. Measured on Pillow, where 40 of 63 ``high`` candidates were
+        ``_open`` implementations of a template method the graph itself records as
+        called from ``ImageFile.__init__`` — the strongest grade, on the most ordinary
+        shape in object-oriented Python.
+
+        Walks ``inherits`` transitively and weighs **every** ancestor that declares the
+        name, not just the nearest: in a three-deep chain the middle link is an override
+        too, so it has no inbound call of its own, and stopping there would report "the
+        base is itself uncalled" while the call sits one level further up. An ancestor
+        with inbound calls therefore wins; failing that, the nearest one is named.
+        """
+        cls, _, meth = n.id.rpartition(".")
+        if not cls or cls not in self._inherits:
+            return None
+        nearest: tuple[str, int] | None = None
+        seen, queue = {cls}, [cls]
+        while queue:  # breadth-first, so `nearest` is the closest declaration
+            for base in self.bases(queue.pop(0)):
+                if base in seen:
+                    continue
+                seen.add(base)
+                queue.append(base)
+                cand = f"{base}.{meth}"
+                if cand not in self.graph.nodes:
+                    continue
+                in_calls = self._calls.in_degree(cand) if cand in self._calls else 0
+                if in_calls:
+                    return cand, in_calls
+                nearest = nearest or (cand, 0)
+        return nearest
+
     def _grade_dead(self, n: Node) -> dict:
         """Score one uncalled-private candidate → {id, confidence, root, reasons}."""
         refs = self.references_to(n.id)  # inbound of every kind, across roots
         registry = n.extras.get("registry")
+        override = self._overridden_base(n)
+        if override and not refs:
+            # R1-C55: the name is uncalled; the body is reachable through the base.
+            base, in_calls = override
+            if in_calls:
+                return {"id": n.id, "confidence": "low", "root": self.root_of(n.id),
+                        "reasons": [f"overrides {base}, which has {in_calls} inbound "
+                                    f"call(s) — reached by dispatch, not by name"]}
+            return {"id": n.id, "confidence": "medium", "root": self.root_of(n.id),
+                    "reasons": [f"overrides {base}, which is itself uncalled here — "
+                                f"dead only if the base is"]}
         if refs:
             by: dict[tuple[str, str], int] = {}
             for r in refs:
@@ -1079,16 +1129,103 @@ class Query:
 
     # -- graph-wide ----------------------------------------------------------
 
+    def _tangle_sets(self, g) -> set[frozenset]:
+        """Strongly connected components of ``g`` that are cycles (R1-C58).
+
+        A tangle — not a cycle — is the unit a reader acts on: *these N modules cannot be
+        separated*. The number of **simple cycles** through them is combinatorial and says
+        nothing more; on pytest's `_pytest` it was 1080 / 95 001 / 464 109 for one tangle
+        of 78 modules, and enumerating them cost 10 s of a report that printed twenty.
+        """
+        out = {frozenset(c) for c in nx.strongly_connected_components(g) if len(c) > 1}
+        out |= {frozenset({n}) for n in g.nodes if g.has_edge(n, n)}
+        return out
+
+    def _example_cycle(self, g, modules: frozenset,
+                       via: set | None = None) -> tuple[list[str], tuple | None]:
+        """One cycle through ``modules``, chosen deterministically (R1-C58).
+
+        Deliberately **not** promised to be the shortest — promising it would buy a
+        narrowing we would then have to declare. It is an example, and it is chosen to
+        pass through an edge of the class that *defines* the tangle (``via``): a lazy
+        tangle must show a function-local edge, or the example reads like an eager cycle
+        in the section about lazy ones. Returns the cycle and that edge, so the answer can
+        name *which* import is the one holding the tangle together.
+        """
+        sub = g.subgraph(modules)
+        chosen = sorted(e for e in sub.edges if via is None or e in via)
+        edges = chosen or sorted(sub.edges)
+        if not edges:
+            return sorted(modules), None    # a self-loop: the module is the whole cycle
+        src, dst = edges[0]
+        edge = (src, dst) if chosen else None
+        if src == dst:
+            return [src], edge
+        try:
+            path = nx.shortest_path(sub, dst, src)
+        except nx.NetworkXNoPath:           # cannot happen inside an SCC; not asserted
+            return sorted(modules), edge
+        return _canonical_cycles([path])[0], edge
+
+    def _tangles(self, g, weaker: set[frozenset], via: set | None = None) -> list[dict]:
+        """Tangles of ``g`` that are not already reported in a stronger class."""
+        out = []
+        for tangle in self._tangle_sets(g) - weaker:
+            example, edge = self._example_cycle(g, tangle, via)
+            sub = g.subgraph(tangle)
+            row = {"modules": sorted(tangle), "size": len(tangle),
+                   # R1-C58: the cycle rank (first Betti number) of the tangle — how many
+                   # **independent** loops it holds. This is the part of the old count that
+                   # was worth keeping: two loops sharing one module are two problems, and
+                   # collapsing them to "one tangle" would hide that. Unlike the number of
+                   # simple cycles it is linear to compute and does not explode: the 19-module
+                   # tangle in pytest has 1080 simple cycles and 31 independent loops.
+                   "loops": sub.number_of_edges() - len(tangle) + 1,
+                   "example": example}
+            if edge:
+                row["closed_by"] = list(edge)
+            out.append(row)
+        return sorted(out, key=lambda r: (r["size"], r["modules"]))
+
+    def import_tangles(self) -> list[dict]:
+        """Mutually-dependent module groups in the **eager** import graph (R1-C58).
+
+        Each entry is ``{modules, size, example}``: the group that cannot be separated,
+        and one cycle through it. The count of simple cycles is not reported — see
+        :meth:`_tangle_sets`.
+        """
+        return self._tangles(self._imports_eager, set())
+
+    def lazy_import_tangles(self) -> list[dict]:
+        """Tangles that exist only once function-local imports are counted."""
+        return self._tangles(self._imports_runtime,
+                             self._tangle_sets(self._imports_eager),
+                             via={(e.source, e.target) for e in self.graph.edges
+                                  if e.type == "imports"
+                                  and e.extras.get("scope") == "function"})
+
+    def type_only_import_tangles(self) -> list[dict]:
+        """Tangles that exist only once imports that never execute are counted."""
+        return self._tangles(self._imports, self._tangle_sets(self._imports_runtime),
+                             via={(e.source, e.target) for e in self.graph.edges
+                                  if e.type == "imports"
+                                  and e.extras.get("scope") in ("type_checking", "stub")})
+
     def import_cycles(self) -> list[list[str]]:
-        """Cycles that exist in the **eager** import graph — the import-order landmines.
+        """One example cycle per **eager** tangle — the import-order landmines.
 
         R1-C29: deliberately *not* computed over every import edge. A function-local
         import does not run at import time, so a cycle closed only by one does not break
         on import — it is what a developer writes to stop it breaking. Counting it here
         would report someone's fix as their bug. Those cycles are still real coupling
         and are returned by :meth:`lazy_import_cycles`.
+
+        R1-C58 changed what one entry **means**: it used to be every simple cycle, which
+        is a combinatorial quantity (1080 entries for one tangle of 78 modules), and is
+        now one representative per tangle. :meth:`import_tangles` carries the group each
+        example stands for.
         """
-        return _canonical_cycles(nx.simple_cycles(self._imports_eager))
+        return _canonical_cycles(t["example"] for t in self.import_tangles())
 
     def lazy_import_cycles(self) -> list[list[str]]:
         """Dependency cycles that close **only** through a function-local import.
@@ -1105,22 +1242,24 @@ class Query:
         function-local import stays *lazy* however many type imports also run between
         them, or a tree could hide real coupling by adding one.
         """
-        eager = {frozenset(c) for c in nx.simple_cycles(self._imports_eager)}
-        return _canonical_cycles(c for c in nx.simple_cycles(self._imports_runtime)
-                                 if frozenset(c) not in eager)
+        return _canonical_cycles(t["example"] for t in self.lazy_import_tangles())
 
     def type_only_import_cycles(self) -> list[list[str]]:
-        """Dependency cycles that close **only** with an import under ``if TYPE_CHECKING:``.
+        """Dependency cycles that close **only** with an import that never executes.
 
         The third kind (R1-C49, issue #18). These modules name each other's types and have
         **no runtime dependency whatever**: neither import pulls the other at any moment of
         execution. That is why they are not gated by ``no_lazy_cycles`` — which exists
         against a lazy import used to walk *around* ``no_cycles`` — and get their own
         opt-in rule instead.
+
+        Two mechanisms, one consequence (R1-C56/D2): an import under ``if TYPE_CHECKING:``
+        and an import written in a ``.pyi``, which Python does not execute at all. The
+        class partitions by consequence — what a reader needs is whether the import can
+        break — while the edge keeps the mechanism in ``extras.scope``. Measured on
+        Pillow, whose *only* "hard" cycle was a stub declaring the module that imports it.
         """
-        runtime = {frozenset(c) for c in nx.simple_cycles(self._imports_runtime)}
-        return _canonical_cycles(c for c in nx.simple_cycles(self._imports)
-                                 if frozenset(c) not in runtime)
+        return _canonical_cycles(t["example"] for t in self.type_only_import_tangles())
 
     def import_map(self) -> dict:
         """How much of the import graph each scope contributed (R1-C29).
@@ -1132,7 +1271,8 @@ class Query:
         """
         return {"module_level": self._import_scopes["module"],
                 "function_local": self._import_scopes["function"],
-                "type_checking": self._import_scopes["type_checking"]}
+                "type_checking": self._import_scopes["type_checking"],
+                "stub": self._import_scopes["stub"]}
 
     def orphan_modules(self, root: str | None = None) -> list[str]:
         """Modules with no incoming imports (dead-code candidates — heuristic).

{codmap-0.0.18 → codmap-0.0.20}/codemap/scope.py

@@ -19,7 +19,10 @@ import subprocess
 from pathlib import Path
 
 # What codemap actually consumes as input (source + docs it indexes as references).
-DEFAULT_INCLUDE = ("*.py", "*.md")
+# R1-C56/D3: `.pyi` is here because griffe reads it. Leaving it out made the manifest
+# describe a different input than the graph was built from, so `scope_id` — and with it
+# `--incremental` and `watch` — read as unknown on every tree that ships stubs.
+DEFAULT_INCLUDE = ("*.py", "*.pyi", "*.md")
 # fs-mode default excludes (git mode gets these for free via .gitignore).
 DEFAULT_EXCLUDE_DIRS = frozenset({
     "__pycache__", ".git", ".venv", "venv", "node_modules", "build", "dist",

{codmap-0.0.18 → codmap-0.0.20}/codemap/serve/api_surface.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 from collections import defaultdict
 
+from codemap.diagnostics import diagnostics, render_lines
 from codemap.model import Graph
 
 _SYMBOL_KINDS = {"class", "function", "attribute"}
@@ -41,16 +42,39 @@ def build_api_surface(graph: Graph) -> dict:
              "doc": _first_line(n.docstring), "file": n.file, "lineno": n.lineno}
             for n in symbols
         ]})
+    reexported = _reexported_from_outside(graph)
     return {
         "kind": "api-surface",
         "target": graph.target,
         "totals": {"symbols": sum(len(m["symbols"]) for m in modules),
                    "modules_with_symbols": len(modules),
-                   "public_modules": len(public_modules)},
+                   "public_modules": len(public_modules),
+                   # R1-C57: always present, zero included — a reader must not have to
+                   # tell "this package re-exports nothing" from "we did not look".
+                   "reexported_from_outside": len(reexported)},
         "modules": modules,
+        "reexported_from_outside": reexported,
+        "diagnostics": diagnostics(graph),
     }
 
 
+def _reexported_from_outside(graph: Graph) -> list[dict]:
+    """Public names this package exposes whose definition lives outside it (R1-C57).
+
+    The facade layout — `pytest` re-exporting 90 names from `_pytest`, `attrs` from
+    `attr` — has almost no symbols of its own, so counting nodes reported a public
+    surface of **one** for a package whose whole purpose is its API. These names are
+    the surface; the definitions are simply not in this graph, and the answer says so
+    instead of omitting them.
+    """
+    out = []
+    for e in graph.edges:
+        if e.type == "export" and e.extras.get("external") and e.extras.get("public"):
+            out.append({"name": e.extras.get("as", ""), "module": e.source,
+                        "defined_at": e.target})
+    return sorted(out, key=lambda r: (r["module"], r["name"]))
+
+
 def render_api_surface(graph: Graph) -> str:
     """Render the public API surface of ``graph`` as Markdown."""
     by_module: dict[str, list] = defaultdict(list)
@@ -61,12 +85,24 @@ def render_api_surface(graph: Graph) -> str:
         by_module[module].append(node)
 
     lines = [f"# API surface — `{graph.target}`", ""]
+    # R1-C57: every other report carried the build's diagnostics and this one did not, so
+    # a facade package printed its surface with no hint that the import graph behind it was
+    # empty. A warning that reaches four reports out of five is a warning the reader can
+    # miss by asking the wrong question.
+    lines.extend(render_lines(graph))
     public_modules = sorted(
         n.id for n in graph.nodes.values() if n.kind == "module" and n.visibility == "public"
     )
     total = sum(len(v) for v in by_module.values())
-    lines.append(f"_{total} public symbols across {len(public_modules)} modules._")
+    reexported = _reexported_from_outside(graph)
+    lines.append(f"_{total} public symbols across {len(public_modules)} modules; "
+                 f"{len(reexported)} more re-exported from outside this root._")
     lines.append("")
+    if reexported:
+        lines.append(f"> ⚠ This package exposes **{len(reexported)}** name(s) it does not "
+                     f"define — the facade layout. Their definitions are in another root "
+                     f"and are **not judged here**; build that package to see them.")
+        lines.append("")
 
     for module in public_modules:
         symbols = sorted(by_module.get(module, []), key=lambda n: n.id)
@@ -84,6 +120,13 @@ def render_api_surface(graph: Graph) -> str:
                 lines.append(f"  - {doc}")
         lines.append("")
 
+    if reexported:
+        lines.append("## Re-exported from outside this root")
+        lines.append("")
+        for r in reexported:
+            lines.append(f"- **`{r['name']}`** → `{r['defined_at']}` (via `{r['module']}`)")
+        lines.append("")
+
     return "\n".join(lines).rstrip() + "\n"