codmap 0.0.17__tar.gz → 0.0.19__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.17
+Version: 0.0.19
 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, **961 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.17 → codmap-0.0.19}/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, **961 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.17 → codmap-0.0.19}/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.17 → codmap-0.0.19}/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}, "
@@ -134,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)
@@ -144,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)
@@ -646,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:
@@ -1069,7 +1138,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.
@@ -1087,20 +1156,27 @@ 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:``.
+        """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 [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).
@@ -1112,7 +1188,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.17 → codmap-0.0.19}/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.17 → codmap-0.0.19}/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"
 
 

{codmap-0.0.17 → codmap-0.0.19}/codemap/serve/architecture.py

@@ -82,9 +82,10 @@ def render_architecture(query: Query) -> str:
                or ["_none found in the eager import graph._"])
     out.append("")
     out.append(f"_Read {im['module_level']} module-level, {im['function_local']} "
-               f"function-local and {im['type_checking']} `TYPE_CHECKING` import(s). Only "
-               f"module-level imports run at import time, so only they can break on import; "
-               f"an import under `if TYPE_CHECKING:` never runs._")
+               f"function-local, {im['type_checking']} `TYPE_CHECKING` and {im['stub']} "
+               f"`.pyi` import(s). Only module-level imports run at import time, so only "
+               f"they can break on import; an import under `if TYPE_CHECKING:` never runs, "
+               f"and a `.pyi` is not executed at all._")
     out.append("")
     if a["lazy_cycles"]:
         out.append(f"### Dependency cycles closed only by a function-local import: "
@@ -103,8 +104,8 @@ def render_architecture(query: Query) -> str:
     if a["type_only_cycles"]:
         # R1-C49: the third kind, kept apart from the second because the difference is the
         # whole point — these modules have no runtime dependency on each other at all.
-        out.append(f"### Dependency cycles closed only by an import under "
-                   f"`if TYPE_CHECKING:`: {len(a['type_only_cycles'])}")
+        out.append(f"### Dependency cycles closed only by an import that never runs "
+                   f"(`if TYPE_CHECKING:` or a `.pyi`): {len(a['type_only_cycles'])}")
         out.append("")
         out.append("_Neither module pulls the other at any moment of execution — they name "
                    "each other's types. Not an import-time failure and not runtime coupling; "

{codmap-0.0.17 → codmap-0.0.19}/codemap/serve/audit.py

@@ -32,11 +32,11 @@ def render_dependencies(query: Query) -> str:
         lines.append("_none found in the eager import graph._")
     lines.append("")
     lines.append(f"_Read {im['module_level']} module-level, {im['function_local']} "
-                 f"function-local and {im['type_checking']} `TYPE_CHECKING` import(s); only "
-                 f"the first run at import time. {len(lazy)} further cycle(s) close through "
-                 f"a function-local import (runtime coupling, not an import-time failure) "
-                 f"and {len(type_only)} through an import under `if TYPE_CHECKING:` (no "
-                 f"runtime dependency at all)._")
+                 f"function-local, {im['type_checking']} `TYPE_CHECKING` and {im['stub']} "
+                 f"`.pyi` import(s); only the first run at import time. {len(lazy)} further "
+                 f"cycle(s) close through a function-local import (runtime coupling, not an "
+                 f"import-time failure) and {len(type_only)} through an import that never "
+                 f"runs — `if TYPE_CHECKING:` or a `.pyi` (no runtime dependency at all)._")
     lines.append("")
 
     lines.append("## Most-depended-on modules (top 15)")

{codmap-0.0.17 → codmap-0.0.19}/codemap/serve/check.py

@@ -47,9 +47,10 @@ def _not_judged(query, contract: ArchitectureContract) -> list[dict]:
         "type_checking_imports": query.import_map()["type_checking"],
         "count": len(lazy) + len(type_only),
         "note": ("`lazy` needs a function-local import — runtime coupling, gated by "
-                 "`no_lazy_cycles = true`. `type_only` needs an import under "
-                 "`if TYPE_CHECKING:` — no runtime dependency at all, gated by "
-                 "`no_type_only_cycles = true`. `report architecture` lists both."),
+                 "`no_lazy_cycles = true`. `type_only` needs an import that never runs "
+                 "(`if TYPE_CHECKING:`, or a `.pyi`, which Python does not execute) — no "
+                 "runtime dependency at all, gated by `no_type_only_cycles = true`. "
+                 "`report architecture` lists both."),
     }]
 
 

{codmap-0.0.17 → codmap-0.0.19}/codemap/serve/livingdocs.py

@@ -160,9 +160,9 @@ def render_docs(query: Query) -> str:
         out.append(f"- **{len(lazy)} dependency cycle(s) closed only by a function-local "
                    f"import** — deliberate, and still runtime coupling.")
     if type_only:
-        out.append(f"- **{len(type_only)} dependency cycle(s) closed only by an import under "
-                   f"`if TYPE_CHECKING:`** — the modules name each other's types and have no "
-                   f"runtime dependency.")
+        out.append(f"- **{len(type_only)} dependency cycle(s) closed only by an import that "
+                   f"never runs** (`if TYPE_CHECKING:` or a `.pyi`) — the modules name each "
+                   f"other's types and have no runtime dependency.")
     if lay["violations"]:
         out.append("- **Layer violations (mutual dependency):** "
                    + ", ".join(f"{a} ↔ {b}" for a, b in lay["violations"]))

{codmap-0.0.17 → codmap-0.0.19}/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