codmap 0.0.18__tar.gz → 0.0.19__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.18
+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, **938 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.18 → 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, **938 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.18 → 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.18 → codmap-0.0.19}/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:
@@ -1110,13 +1160,19 @@ class Query:
                                  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 _canonical_cycles(c for c in nx.simple_cycles(self._imports)
@@ -1132,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.18 → 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.18 → 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.18 → 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.18 → 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.18 → 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.18 → 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.18 → codmap-0.0.19}/codemap/serve/session.py

@@ -191,6 +191,11 @@ def _match(q: Query, n) -> dict:
     (posargs / kwargs / splat per call site), which no node field can know.
     """
     e = {"id": n.id, "kind": n.kind, "file": n.file, "lines": [n.lineno, n.endlineno]}
+    if n.extras.get("stub"):
+        # R1-C56/D4: a `.pyi` declaration, not code. Whoever is about to read the body
+        # must learn there is none from the answer, not from the file extension — the
+        # same rule as the epistemic label and the kind of an empty answer.
+        e["stub"] = True
     if n.signature:
         e["signature"] = n.signature
     elif n.kind == "class":

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.18
+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, **938 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.18 → codmap-0.0.19}/codmap.egg-info/SOURCES.txt

@@ -124,6 +124,9 @@ 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_r1c55_override_grade.py
+tests/test_r1c56_stub_files.py
+tests/test_r1c57_facade_package.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py
 tests/test_r1c7_edge_vocab.py

{codmap-0.0.18 → codmap-0.0.19}/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.18"
+version = "0.0.19"
 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

{codmap-0.0.18 → codmap-0.0.19}/tests/test_m1_query.py

@@ -79,7 +79,8 @@ def test_cycle_detection(q, graph):
     type_only = {frozenset(c) for c in q.type_only_import_cycles()}
     assert not (eager & lazy) and not (eager & type_only) and not (lazy & type_only), \
         "a cycle has exactly one kind — the weakest scope that closes it (R1-C49)"
-    assert set(q.import_map()) == {"module_level", "function_local", "type_checking"}
+    assert set(q.import_map()) == {"module_level", "function_local", "type_checking",
+                                   "stub"}
     assert q.import_map()["module_level"] > 0
 
     scopes: dict[tuple[str, str], set[str]] = {}
@@ -94,13 +95,24 @@ def test_cycle_detection(q, graph):
     for c in lazy:
         assert closing(c, "function"), f"a lazy cycle needs a function-local edge: {c}"
     for c in type_only:
-        assert closing(c, "type_checking"), f"a type-only cycle needs one: {c}"
+        # R1-C56: two mechanisms never execute — `if TYPE_CHECKING:` and a `.pyi`. The
+        # class is defined by the consequence, so either scope may be what closes it.
+        assert closing(c, "type_checking") or closing(c, "stub"), \
+            f"a type-only cycle needs an import that never runs: {c}"
 
 
 def test_orphan_modules(q):
+    """An invariant, not a name: `bquant.cli` was the example until the target grew a
+    `__main__.py` that imports it, and the assertion started measuring the target
+    rather than the query (R1-C25 — the second time in this suite, after
+    `test_cycle_detection`). What must hold on any tree: an orphan is a module the
+    import graph has no inbound edge for."""
     orphans = q.orphan_modules()
-    assert isinstance(orphans, list)
-    assert "bquant.cli" in orphans  # entry point, imported by nothing internally
+    assert isinstance(orphans, list) and orphans, "the dogfood tree has orphans"
+    for mod in orphans:
+        assert q.graph.nodes[mod].kind == "module"
+        assert not [e for e in q.graph.edges
+                    if e.type == "imports" and e.target == mod], f"{mod} is imported"
 
 
 def test_determinism_with_edges():

{codmap-0.0.18 → codmap-0.0.19}/tests/test_r1c29_lazy_imports.py

@@ -153,7 +153,7 @@ def test_import_map_is_emitted_even_when_nothing_is_lazy(tmp_path):
     to tell "no lazy imports here" from "this build did not look for them"."""
     pkg = _pkg(tmp_path, {"a.py": "x = 1\n", "b.py": "from pkg.a import x\n"})
     im = Query(extract(str(pkg))).import_map()
-    assert im == {"module_level": 1, "function_local": 0, "type_checking": 0}
+    assert im == {"module_level": 1, "function_local": 0, "type_checking": 0, "stub": 0}
 
 
 # -- and no consumer states acyclicity as a property -------------------------
@@ -162,7 +162,7 @@ def test_architecture_never_claims_acyclic(lazy_cycle):
     md = render_architecture(Query(extract(str(lazy_cycle))))
     assert "acyclic" not in md, "a partial map cannot support a property claim"
     assert "none found in the eager import graph" in md
-    assert "function-local and 0 `TYPE_CHECKING` import(s)" in md
+    assert "function-local, 0 `TYPE_CHECKING` and 0 `.pyi` import(s)" in md
     assert "Dependency cycles closed only by a function-local import: 1" in md
 
 
@@ -176,7 +176,7 @@ def test_architecture_payload_carries_both_kinds_and_the_counts(lazy_cycle):
     a = build_architecture(Query(extract(str(lazy_cycle))))
     assert a["cycles"] == []
     assert [sorted(c) for c in a["lazy_cycles"]] == [["pkg.a", "pkg.b"]]
-    assert a["import_map"] == {"module_level": 1, "function_local": 1, "type_checking": 0}
+    assert a["import_map"] == {"module_level": 1, "function_local": 1, "type_checking": 0, "stub": 0}
 
 
 def test_no_renderer_states_acyclicity_anywhere(tmp_path):

{codmap-0.0.18 → codmap-0.0.19}/tests/test_r1c48_type_checking_imports.py

@@ -137,7 +137,7 @@ def test_the_cycle_is_not_eager(tree):
 
 
 def test_import_map_names_the_scope_always(tree):
-    assert tree[2].import_map() == {"module_level": 4, "function_local": 1, "type_checking": 3}
+    assert tree[2].import_map() == {"module_level": 4, "function_local": 1, "type_checking": 3, "stub": 0}
 
 
 def test_import_map_says_zero_when_there_is_none(tmp_path):
@@ -150,10 +150,10 @@ def test_every_consumer_says_which_imports_it_did_not_judge(tree):
     a = build_architecture(q)
     assert a["import_map"]["type_checking"] == 3
     md = render_architecture(q)
-    assert "3 `TYPE_CHECKING` import(s)" in md
-    assert "closed only by an import under `if TYPE_CHECKING:`: 1" in md
-    assert "`TYPE_CHECKING` import(s)" in render_dependencies(q)
-    assert "closed only by an import under `if TYPE_CHECKING:`" in render_docs(q)
+    assert "3 `TYPE_CHECKING` and 0 `.pyi` import(s)" in md
+    assert "closed only by an import that never runs (`if TYPE_CHECKING:` or a `.pyi`): 1" in md
+    assert "`TYPE_CHECKING` and 0 `.pyi` import(s)" in render_dependencies(q)
+    assert "closed only by an import that never runs" in render_docs(q)
 
 
 def test_the_gate_is_green_and_names_what_it_read(tree):

{codmap-0.0.18 → codmap-0.0.19}/tests/test_r1c49_type_only_cycles.py

@@ -192,18 +192,19 @@ def test_the_reports_carry_both_kinds_and_say_zero(both, tmp_path):
     assert _flat(a["type_only_cycles"]) == [["bp.typed_a", "bp.typed_b"]]
     md = render_architecture(both)
     assert "Dependency cycles closed only by a function-local import: 1" in md
-    assert "Dependency cycles closed only by an import under `if TYPE_CHECKING:`: 1" in md
+    assert ("Dependency cycles closed only by an import that never runs "
+            "(`if TYPE_CHECKING:` or a `.pyi`): 1") in md
     dep = render_dependencies(both)
     assert "1 further cycle(s) close through a function-local import" in dep
-    assert "1 through an import under `if TYPE_CHECKING:`" in dep
+    assert "1 through an import that never runs" in dep
     assert _flat(build_dependencies(both)["type_only_import_cycles"]) == [["bp.typed_a", "bp.typed_b"]]
     docs = render_docs(both)
     assert "closed only by a function-local import" in docs
-    assert "closed only by an import under `if TYPE_CHECKING:`" in docs
+    assert "closed only by an import that never runs" in docs
 
     quiet = Query(extract(str(_pkg(tmp_path, {"a": "from .b import x\n", "b": "x = 1\n"}))))
     assert build_architecture(quiet)["type_only_cycles"] == []
-    assert "and 0 through an import under `if TYPE_CHECKING:`" in render_dependencies(quiet)
+    assert "and 0 through an import that never runs" in render_dependencies(quiet)
 
 
 # -- f1: a rule that ran must name itself ---------------------------------------------------