codmap 0.0.12__tar.gz → 0.0.14__tar.gz

{codmap-0.0.12/codmap.egg-info → codmap-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.12
+Version: 0.0.14
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT

{codmap-0.0.12 → codmap-0.0.14}/codemap/arch.py

@@ -21,6 +21,7 @@ integration gate reads). All rules operate on the **core** module import graph
     # also gate the coupling a lazy import hides: cycles closed only by an import
     # written inside a function. Off by default — see below.
     no_lazy_cycles = false
+    no_type_only_cycles = false
     # every core module's layer must appear in `layers` (catches a new,
     # undeclared top-level package slipping in).
     exhaustive = false
@@ -54,6 +55,7 @@ class ArchitectureContract:
     forbidden: tuple[tuple[str, str], ...] = ()
     no_cycles: bool = False
     no_lazy_cycles: bool = False
+    no_type_only_cycles: bool = False
     exhaustive: bool = False
     error: str | None = None
     # R1-C35: the file this contract was looked for in. "No contract found" is only
@@ -63,7 +65,8 @@ class ArchitectureContract:
 
     def is_empty(self) -> bool:
         return not (self.layers or self.independent or self.forbidden
-                    or self.no_cycles or self.no_lazy_cycles or self.exhaustive)
+                    or self.no_cycles or self.no_lazy_cycles
+                    or self.no_type_only_cycles or self.exhaustive)
 
 
 @dataclass(frozen=True)
@@ -71,7 +74,7 @@ class Violation:
     """One broken rule, with the concrete import edges (or cycle) that break it."""
 
     rule: str            # layered | independent | forbidden | no_cycles | no_lazy_cycles
-    #                      | exhaustive
+    #                      | no_type_only_cycles | exhaustive
     summary: str         # human one-liner
     edges: tuple[tuple[str, str], ...] = field(default=())   # offending (importer, imported)
     modules: tuple[str, ...] = field(default=())             # for exhaustive / cycles
@@ -112,6 +115,7 @@ def parse_contract(section: dict) -> ArchitectureContract:
         forbidden=tuple(forbidden),
         no_cycles=bool(section.get("no_cycles", False)),
         no_lazy_cycles=bool(section.get("no_lazy_cycles", False)),
+        no_type_only_cycles=bool(section.get("no_type_only_cycles", False)),
         exhaustive=bool(section.get("exhaustive", False)),
     )
 
@@ -211,6 +215,24 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
                 modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
             ))
 
+    # -- no_type_only_cycles: the third kind, and the one with no runtime dependency ----
+    # R1-C49 (issue #18): a cycle that needs an import under `if TYPE_CHECKING:` cannot
+    # break at import time and does not couple the modules at run time either — the two
+    # only name each other's types. Gating it is a style choice about the type layer, so
+    # it is opt-in and separate: the consumer who asked for this had `no_lazy_cycles` on
+    # 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()
+        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),
+            ))
+
     # -- exhaustive: every core module's layer must be declared -----------------
     if contract.exhaustive and contract.layers:
         declared = set(contract.layers)

{codmap-0.0.12 → codmap-0.0.14}/codemap/extract/griffe_extractor.py

@@ -265,8 +265,9 @@ def _input_report(graph, pkg_dir: Path, root: Path, walk) -> dict:
     return report
 
 
-def _source_import_targets(module) -> list[tuple[str, str]]:
-    """``(target, scope)`` for the imports griffe's module-level map does not carry.
+def _source_import_targets(module) -> tuple[list[tuple[str, str]], set[str]]:
+    """``([(target, scope)], eager targets)`` — the imports griffe's module-level map does
+    not carry, and the targets it carries correctly.
 
     Two families, one traversal, one parse — griffe records neither, and both used to be
     invisible to the import graph:
@@ -282,6 +283,11 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
     - **imports written in a class body** → scope ``"module"``. They run at
       class-definition time, i.e. at import time, so they are ordinary eager dependencies
       and *can* close a real import cycle. griffe does not record them either (measured).
+    - **imports under `if TYPE_CHECKING:`** (R1-C48 / issue #18) → scope
+      ``"type_checking"``. griffe *does* record these, as module-level — it has no notion
+      of a condition that is always false at run time — so the second value returned is
+      the set of targets imported at plain module level: the caller demotes griffe's entry
+      for a target that appears only under ``TYPE_CHECKING``.
 
     Cost discipline, and it is not theoretical: the first version of this walked every
     function's subtree separately, which is quadratic in nesting and cost the dogfood
@@ -293,13 +299,13 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
     try:
         src = module.source
     except Exception:                       # no source (namespace dir, synthetic)
-        return []
+        return [], set()
     if not NESTED_IMPORT_HINT.search(src):
-        return []
+        return [], set()
     try:
         tree = ast.parse(src)
     except (SyntaxError, ValueError):
-        return []                            # unreadable: D2's report owns this file
+        return [], set()                     # unreadable: D2's report owns this file
     modpath = module.canonical_path
     f = module_file(module)
     is_pkg = f is not None and f.name == "__init__.py"
@@ -312,9 +318,11 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
         return node.module or ""
 
     out: list[tuple[str, str]] = []
+    eager: set[str] = set()   # targets imported at plain module level (griffe has them)
 
     def visit(node, scope: str | None) -> None:
-        """``scope`` is None at module level (griffe has those), else module|function."""
+        """``scope`` is None at module level (griffe has those), else
+        module|function|type_checking."""
         for child in ast.iter_child_nodes(node):
             if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
                 visit(child, "function")
@@ -322,9 +330,21 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
                 # A class body runs at import time — unless we are already inside a
                 # function, in which case the whole thing does not.
                 visit(child, "function" if scope == "function" else "module")
+            elif isinstance(child, ast.If) and scope in (None, "type_checking") \
+                    and (tc := _type_checking_branches(child)) is not None:
+                # R1-C48 (issue #18): `if TYPE_CHECKING:` never runs. Its body is a third
+                # scope; its `else` is ordinary module level. Inside a function the whole
+                # `if` is function-local already and is not looked at.
+                body_scope, else_scope = tc
+                for stmt in child.body:
+                    visit_stmt(stmt, body_scope if body_scope else scope)
+                for stmt in child.orelse:
+                    visit_stmt(stmt, else_scope if else_scope else scope)
             elif isinstance(child, ast.Import):
                 if scope is not None:
                     out.extend((a.name, scope) for a in child.names)
+                else:
+                    eager.update(a.name for a in child.names)
             elif isinstance(child, ast.ImportFrom):
                 target = resolve(child)
                 if not target:
@@ -333,6 +353,8 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
                 if scope is None:
                     if star:                 # the D3 case: griffe records nothing
                         out.append((target, "module"))
+                    eager.add(target)
+                    eager.update(f"{target}.{a.name}" for a in child.names if a.name != "*")
                     continue
                 # `from pkg.mod import name` → keep the member paths so the resolver walks
                 # down to the containing module exactly as it does for the module-level
@@ -343,19 +365,49 @@ def _source_import_targets(module) -> list[tuple[str, str]]:
             else:
                 visit(child, scope)
 
+    def visit_stmt(stmt, scope: str | None) -> None:
+        """Route one statement through ``visit`` as if it were the only child."""
+        holder = ast.Module(body=[stmt], type_ignores=[])
+        visit(holder, scope)
+
     visit(tree, None)
-    return out
+    return out, eager
+
+
+def _type_checking_branches(node: ast.If) -> tuple[str | None, str | None] | None:
+    """``(scope of body, scope of else)`` for a recognised ``TYPE_CHECKING`` test, else None.
+
+    Recognised, narrowly (design D3): the bare name ``TYPE_CHECKING``, any attribute named
+    ``TYPE_CHECKING`` (``typing.TYPE_CHECKING``, ``t.TYPE_CHECKING``), and ``not`` of either,
+    which swaps the branches. A compound test (``TYPE_CHECKING or X``) is *not* recognised
+    and stays eager: a condition the tool cannot read is judged strictly, never leniently.
+    ``None`` in a slot means "the enclosing scope" (module level).
+    """
+    test, negated = node.test, False
+    if isinstance(test, ast.UnaryOp) and isinstance(test.op, ast.Not):
+        test, negated = test.operand, True
+    is_tc = ((isinstance(test, ast.Name) and test.id == "TYPE_CHECKING")
+             or (isinstance(test, ast.Attribute) and test.attr == "TYPE_CHECKING"))
+    if not is_tc:
+        return None
+    return (None, "type_checking") if negated else ("type_checking", None)
 
 
 def _collect(graph, obj, root, target_pkg, walk) -> None:
     if obj.kind.value == "module":
         _claim(obj, walk)  # the root claims its own path before any member is walked
         _add_node(graph, obj, root)
+        # R1-C23/D3 (star imports) + R1-C29 (function-local and class-body imports) +
+        # R1-C48 (`if TYPE_CHECKING:`): everything griffe's module-level map does not
+        # 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"}
         for name, tgt in (obj.imports or {}).items():
-            walk.imports.append((obj.canonical_path, tgt, "module"))
-        # R1-C23/D3 (star imports) + R1-C29 (function-local and class-body imports):
-        # everything griffe's module-level map does not carry, in one parse.
-        for tgt, scope in _source_import_targets(obj):
+            # 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))
+        for tgt, scope in nested:
             walk.imports.append((obj.canonical_path, tgt, scope))
     for name, member in obj.members.items():
         if member.is_alias:
@@ -429,6 +481,15 @@ def _emit_decorated_by(graph, obj) -> None:
 
 # -- pass 2: resolve export + import edges against known nodes ----------------
 
+#: How strongly an import scope reaches its target: an edge carries the strongest (R1-C29
+#: D2, R1-C48 D2). ``module`` runs at import time, ``function`` when the function runs,
+#: ``type_checking`` never. A pair reached by both a function-local and a ``TYPE_CHECKING``
+#: 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}
+
+
 def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     module_ids = sorted(
         (n.id for n in graph.nodes.values() if n.kind == "module"), key=len, reverse=True
@@ -457,7 +518,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
     # the eager import it is. `scope` only ever *weakens* to "function" for a pair that
     # has no module-level import at all — the edge says how the dependency is reached at
     # its earliest, never how it happens to appear last in the walk.
-    ordered = sorted(imports, key=lambda t: t[2] == "function")
+    ordered = sorted(imports, key=lambda t: _SCOPE_RANK.get(t[2], 0))
 
     # pass A — package-qualified targets. Exact, and run first so that a pair reachable
     # both ways is recorded as exact rather than inferred.
@@ -472,7 +533,7 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
         if key in seen:
             continue
         seen.add(key)
-        extras = {"scope": "function"} if scope == "function" else {}
+        extras = {"scope": scope} if scope != "module" else {}
         graph.add_edge(Edge("imports", src_module, tgt_module, extras=extras))
 
     # pass B — flat layout (R1-C21): sibling modules importing each other by bare name
@@ -489,8 +550,8 @@ def _resolve_edges(graph, target_pkg, aliases, imports) -> None:
             continue
         seen.add(key)
         extras = {"resolution": "flat"}
-        if scope == "function":
-            extras["scope"] = "function"
+        if scope != "module":
+            extras["scope"] = scope
         graph.add_edge(Edge("imports", src_module, tgt_module, extras=extras))
 
 

{codmap-0.0.12 → codmap-0.0.14}/codemap/extract/union.py

@@ -36,7 +36,10 @@ An edge seen in fewer than N runs carries ``extras.seen: k``; nothing is written
 ``k == N``, so a single-sample build's edges are byte-identical to what they were. Node
 counters (``calls`` / ``attr_access``) count *sites*, which dedupe into edges — the
 measured node had three counter variants behind one flapping edge — so per node the
-variant with the fewest ``unresolved`` is kept (tie: most ``resolved``, tie: first run).
+variant with the fewest ``unresolved`` is kept (tie: most ``resolved``, tie: the serialized
+counter). Every choice between variants of one key is a **total order** over the candidates
+(:func:`_rank`, :func:`_counter_rank`): the merged graph is a function of the set of
+samples, and the same samples in any order produce the same bytes.
 
 **Every sample is a fresh process.** The share above was measured across processes —
 the consumer's 175 builds and the eight here. Repeating the behavioural layer *inside*
@@ -74,20 +77,30 @@ def _identity(e: Edge) -> tuple:
             json.dumps(e.extras, sort_keys=True, ensure_ascii=False))
 
 
-def _deeper(new: Edge, current: Edge) -> bool:
-    return (new.extras.get("resolution") == "deep"
-            and current.extras.get("resolution") != "deep")
+def _rank(e: Edge) -> tuple:
+    """Total order among the variants of one identity key: ``deep`` beats any other
+    resolution, more call sites beat fewer, and the serialized ``extras`` break what is
+    left — so the winner is a function of the *set* of samples, never of the order they
+    arrived in. The consumer's hint on codemap#17: where two candidates are equally
+    legitimate, 'first one wins' is a dependence on arrival order, and one that a probe
+    permuting the *output* can never see."""
+    ex = e.extras
+    return (ex.get("resolution") == "deep", ex.get("callsites", 0),
+            json.dumps(ex, sort_keys=True, ensure_ascii=False))
+
+
+def _counter_rank(c: dict) -> tuple:
+    return (-c.get("unresolved", 0), c.get("resolved", 0), json.dumps(c, sort_keys=True))
 
 
 def _better_counter(a: dict | None, b: dict | None) -> dict | None:
-    """The counter variant that resolved more sites (``None`` never beats a value)."""
+    """The counter variant that resolved more sites (``None`` never beats a value);
+    a tie is broken by the serialized counter, not by which sample came first."""
     if a is None:
         return b
     if b is None:
         return a
-    ka = (-a.get("unresolved", 0), a.get("resolved", 0))
-    kb = (-b.get("unresolved", 0), b.get("resolved", 0))
-    return b if kb > ka else a
+    return b if _counter_rank(b) > _counter_rank(a) else a
 
 
 def merge_samples(samples: list[Graph]) -> tuple[Graph, dict]:
@@ -116,7 +129,7 @@ def merge_samples(samples: list[Graph]) -> tuple[Graph, dict]:
             else:
                 if key not in seen_this_run:
                     entry[0] += 1
-                if _deeper(e, entry[1]):
+                if _rank(e) > _rank(entry[1]):
                     entry[1] = e
             seen_this_run.add(key)
 

{codmap-0.0.12 → codmap-0.0.14}/codemap/query.py

@@ -119,17 +119,27 @@ class Query:
         # made an incomplete map read as a safety property.
         self._imports = nx.DiGraph()
         self._imports_eager = nx.DiGraph()
-        self._import_scopes = {"module": 0, "function": 0}
+        # 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}
         for n in graph.nodes.values():
             if n.kind == "module":
                 self._imports.add_node(n.id)
                 self._imports_eager.add_node(n.id)
+                self._imports_runtime.add_node(n.id)
         for e in graph.edges:
             if e.type == "imports":
                 self._imports.add_edge(e.source, e.target)
-                if e.extras.get("scope") == "function":
-                    self._import_scopes["function"] += 1
+                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.
+                    self._import_scopes[scope] += 1
+                    if scope == "function":
+                        self._imports_runtime.add_edge(e.source, e.target)
                 else:
+                    self._imports_runtime.add_edge(e.source, e.target)
                     self._imports_eager.add_edge(e.source, e.target)
                     self._import_scopes["module"] += 1
         # export edges: name -> [target definition paths]
@@ -888,12 +898,32 @@ class Query:
         """Dependency cycles that close **only** through a function-local import.
 
         Not an import-time failure, and not nothing: the modules still cannot be
-        separated, and the lazy import is the evidence someone already hit this. Before
-        R1-C29 these were invisible — on the target this project benchmarks on, eight of
-        the nine cycles present were of this kind and the report said "1".
+        separated at run time, and the lazy import is the evidence someone already hit
+        this. Before R1-C29 these were invisible — on the target this project benchmarks
+        on, eight of the nine cycles present were of this kind and the report said "1".
+
+        R1-C49 narrowed this back after R1-C48 briefly widened it: a cycle that needs an
+        import under ``if TYPE_CHECKING:`` is not runtime coupling at all and is returned
+        by :meth:`type_only_import_cycles`. The partition is by the **weakest scope that
+        closes the cycle**, not by which scopes appear in it — a pair coupled through a
+        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 [c for c in nx.simple_cycles(self._imports) if frozenset(c) not in eager]
+        return [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:``.
+
+        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.
+        """
+        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]
 
     def import_map(self) -> dict:
         """How much of the import graph each scope contributed (R1-C29).
@@ -904,7 +934,8 @@ class Query:
         did not look for them".
         """
         return {"module_level": self._import_scopes["module"],
-                "function_local": self._import_scopes["function"]}
+                "function_local": self._import_scopes["function"],
+                "type_checking": self._import_scopes["type_checking"]}
 
     def orphan_modules(self, root: str | None = None) -> list[str]:
         """Modules with no incoming imports (dead-code candidates — heuristic).

{codmap-0.0.12 → codmap-0.0.14}/codemap/serve/architecture.py

@@ -18,8 +18,10 @@ from codemap.query import Query
 def build_architecture(query: Query) -> dict:
     """Structured whole-system overview (cycles + layers + coupling + hotspots).
 
-    R1-C29: ``cycles`` are the **import-time** ones and ``lazy_cycles`` the dependency
-    cycles closed only by a function-local import. Splitting them is the point — a lazy
+    Three kinds, by the weakest scope that closes the cycle (R1-C49): ``cycles`` break at
+    import time, ``lazy_cycles`` need a function-local import (runtime coupling), and
+    ``type_only_cycles`` need one under ``if TYPE_CHECKING:`` (no runtime dependency at
+    all). Splitting them is the point — a lazy
     import is how a developer *fixes* an import cycle, so folding the two together would
     report someone's fix as their bug, while dropping the second (what this tool did
     until issue #11) hides that the modules are still inseparable. ``import_map`` is
@@ -30,6 +32,7 @@ def build_architecture(query: Query) -> dict:
         "target": query.graph.target,
         "cycles": query.import_cycles(),
         "lazy_cycles": query.lazy_import_cycles(),
+        "type_only_cycles": query.type_only_import_cycles(),
         "import_map": query.import_map(),
         "layers": query.layers(),
         "coupling": query.coupling(),
@@ -78,9 +81,10 @@ def render_architecture(query: Query) -> str:
                 sorted(a["cycles"], key=lambda c: (len(c), c))]
                or ["_none found in the eager import graph._"])
     out.append("")
-    out.append(f"_Read {im['module_level']} module-level and {im['function_local']} "
-               f"function-local import(s). Only module-level imports run at import time, "
-               f"so only they can break on import._")
+    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._")
     out.append("")
     if a["lazy_cycles"]:
         out.append(f"### Dependency cycles closed only by a function-local import: "
@@ -88,14 +92,30 @@ def render_architecture(query: Query) -> str:
         out.append("")
         out.append("_These do **not** break at import time — the lazy import is what "
                    "prevents that, and is usually deliberate. They are listed because "
-                   "the modules are still mutually dependent: neither can be extracted "
-                   "without the other._")
+                   "the modules are still mutually dependent at run time: neither can be "
+                   "extracted without the other._")
         out.append("")
         out.extend(f"- {' → '.join(c)} → {c[0]}" for c in
                    sorted(a["lazy_cycles"], key=lambda c: (len(c), c))[:20])
         if len(a["lazy_cycles"]) > 20:
             out.append(f"- _… {len(a['lazy_cycles']) - 20} more_")
         out.append("")
+    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("")
+        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; "
+                   "`no_type_only_cycles = true` gates them if the type layer must not close "
+                   "a cycle either._")
+        out.append("")
+        out.extend(f"- {' → '.join(c)} → {c[0]}" for c in
+                   sorted(a["type_only_cycles"], key=lambda c: (len(c), c))[:20])
+        if len(a["type_only_cycles"]) > 20:
+            out.append(f"- _… {len(a['type_only_cycles']) - 20} more_")
+        out.append("")
 
     # -- coupling -----------------------------------------------------------
     out.append("## Coupling (top by afferent Ca)")

{codmap-0.0.12 → codmap-0.0.14}/codemap/serve/audit.py

@@ -18,6 +18,7 @@ def render_dependencies(query: Query) -> str:
 
     cycles = query.import_cycles()
     lazy = query.lazy_import_cycles()
+    type_only = query.type_only_import_cycles()
     im = query.import_map()
     lines.append(f"## Import cycles: {len(cycles)}")
     lines.append("")
@@ -29,11 +30,12 @@ def render_dependencies(query: Query) -> str:
         # map that would have to be complete to support it demonstrably is not.
         lines.append("_none found in the eager import graph._")
     lines.append("")
-    lines.append(f"_Read {im['module_level']} module-level and {im['function_local']} "
-                 f"function-local import(s); only the former run at import time. "
-                 + (f"{len(lazy)} further cycle(s) close through a lazy import — real "
-                    f"coupling, not an import-time failure._" if lazy
-                    else "No cycle closes through a lazy import._"))
+    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)._")
     lines.append("")
 
     lines.append("## Most-depended-on modules (top 15)")
@@ -61,6 +63,8 @@ def build_dependencies(query: Query) -> dict:
         "import_cycles": [list(c) for c in sorted(query.import_cycles(), key=lambda c: (len(c), c))],
         "lazy_import_cycles": [list(c) for c in
                                sorted(query.lazy_import_cycles(), key=lambda c: (len(c), c))],
+        "type_only_import_cycles": [list(c) for c in
+                                    sorted(query.type_only_import_cycles(), key=lambda c: (len(c), c))],
         "most_depended_on": [{"module": m, "imported_by": g.in_degree(m)}
                              for m in ranked[:15] if g.in_degree(m)],
         "diagnostics": diagnostics(query.graph),

{codmap-0.0.12 → codmap-0.0.14}/codemap/serve/check.py

@@ -27,17 +27,29 @@ def _not_judged(query, contract: ArchitectureContract) -> list[dict]:
     a field that appears only when there is something to say forces a machine consumer to
     tell "nothing was skipped" from "this build does not report skips", and it cannot.
     """
-    if not contract.no_cycles or contract.no_lazy_cycles:
-        return []   # not enforced, or the contract opted into judging them too
-    lazy = query.lazy_import_cycles()
+    if not contract.no_cycles:
+        return []                                   # not enforced
+    if contract.no_lazy_cycles and contract.no_type_only_cycles:
+        return []                                   # the contract judges all three kinds
+    # R1-C49: two kinds may be left out, and they are different things. Whichever of them
+    # this contract does not gate is what the reader must be told about — reporting one
+    # sum over both is the defect the third consumer filed.
+    lazy = [] if contract.no_lazy_cycles else query.lazy_import_cycles()
+    type_only = [] if contract.no_type_only_cycles else query.type_only_import_cycles()
     return [{
         "rule": "no_cycles",
         "judged": "the eager import graph — imports that run at import time",
-        "not_judged": "dependency cycles closed only by a function-local import",
-        "count": len(lazy),
-        "note": ("a lazy import does not run at import time, so such a cycle cannot break "
-                 "on import; it is still mutual coupling. Set `no_lazy_cycles = true` to "
-                 "gate these as well, or see `report architecture` for the list."),
+        "not_judged": "dependency cycles that do not close at import time",
+        "lazy": len(lazy),
+        "type_only": len(type_only),
+        "lazy_gated": contract.no_lazy_cycles,
+        "type_only_gated": contract.no_type_only_cycles,
+        "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."),
     }]
 
 
@@ -131,11 +143,15 @@ def _render_scope(query, contract: ArchitectureContract) -> str:
     if not scope:
         return ""
     s = scope[0]
-    if not s["count"]:
-        return ("\n_`no_cycles` judged the eager import graph; no dependency cycle is closed "
-                "only by a function-local import either._\n")
+    parts = []
+    if not s["lazy_gated"]:
+        parts.append(f"**{s['lazy']}** cycle(s) closed only by a function-local import "
+                     f"(runtime coupling — `no_lazy_cycles = true` gates them)")
+    if not s["type_only_gated"]:
+        parts.append(f"**{s['type_only']}** closed only by an import under "
+                     f"`if TYPE_CHECKING:` (no runtime dependency at all — "
+                     f"`no_type_only_cycles = true` gates them)")
     return (f"\n_`no_cycles` judged **the eager import graph only** — imports that run at "
-            f"import time. **{s['count']}** dependency cycle(s) closed only by a "
-            f"function-local import were **not** judged: such a cycle cannot break on "
-            f"import, but the coupling is real. `report architecture` lists them; "
-            f"`no_lazy_cycles = true` gates them._\n")
+            f"import time. Not judged: {' and '.join(parts)}. `report architecture` lists "
+            f"them. {s['type_checking_imports']} import(s) under `TYPE_CHECKING` read as "
+            f"never running._\n")

{codmap-0.0.12 → codmap-0.0.14}/codemap/serve/livingdocs.py

@@ -144,6 +144,7 @@ def render_docs(query: Query) -> str:
     # -- architecture caveats (the honest health section) -------------------
     cycles = query.import_cycles()
     lazy = query.lazy_import_cycles()
+    type_only = query.type_only_import_cycles()
     lay = query.layers()
     gods = query.hotspots()["god_classes"]
     out.append("## Architecture notes")
@@ -157,7 +158,11 @@ def render_docs(query: Query) -> str:
         out.append("- No import cycle found in the eager import graph.")
     if lazy:
         out.append(f"- **{len(lazy)} dependency cycle(s) closed only by a function-local "
-                   f"import** — deliberate, and still mutual coupling.")
+                   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.")
     if lay["violations"]:
         out.append("- **Layer violations (mutual dependency):** "
                    + ", ".join(f"{a} ↔ {b}" for a, b in lay["violations"]))

{codmap-0.0.12 → codmap-0.0.14/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.12
+Version: 0.0.14
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT

{codmap-0.0.12 → codmap-0.0.14}/codmap.egg-info/SOURCES.txt

@@ -116,6 +116,8 @@ tests/test_r1c44_absent_answers.py
 tests/test_r1c45_repeat_union.py
 tests/test_r1c46_shadowed_definitions.py
 tests/test_r1c47_incremental_resample.py
+tests/test_r1c48_type_checking_imports.py
+tests/test_r1c49_type_only_cycles.py
 tests/test_r1c4_complexity.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py

{codmap-0.0.12 → codmap-0.0.14}/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.12"
+version = "0.0.14"
 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.12 → codmap-0.0.14}/tests/test_m16_architecture.py

@@ -77,8 +77,10 @@ def test_build_architecture_has_all_sections(q):
     a = build_architecture(q)
     # R1-C29 added two: `lazy_cycles` (dependency cycles closed only by a function-local
     # import — real coupling, not an import-time failure) and `import_map` (how many
+    # imports each scope contributed). R1-C49 added `type_only_cycles`, the third kind —
+    # closed only by an import under `if TYPE_CHECKING:`, i.e. no runtime dependency at all —
     # imports of each scope the map was built from, always, zero included).
-    assert set(a) == {"target", "cycles", "lazy_cycles", "import_map",
+    assert set(a) == {"target", "cycles", "lazy_cycles", "type_only_cycles", "import_map",
                       "layers", "coupling", "hotspots"}
     assert a["target"] == "dispatchpkg"