codmap 0.0.13__tar.gz → 0.0.15__tar.gz

{codmap-0.0.13/codmap.egg-info → codmap-0.0.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.13
+Version: 0.0.15
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -85,7 +85,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
+lazy cycles    40 more, closed only by a function-local import — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5

{codmap-0.0.13 → codmap-0.0.15}/README.md

@@ -49,7 +49,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
+lazy cycles    40 more, closed only by a function-local import — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5

{codmap-0.0.13 → codmap-0.0.15}/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)),
     )
 
@@ -207,8 +211,25 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
             worst = sorted(lazy, key=lambda c: (len(c), c))
             violations.append(Violation(
                 "no_lazy_cycles",
-                f"{len(lazy)} dependency cycle(s) closed only by a non-eager import "
-                f"(function-local, or under `if TYPE_CHECKING:`)",
+                f"{len(lazy)} dependency cycle(s) closed only by a function-local import",
+                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),
             ))
 

{codmap-0.0.13 → codmap-0.0.15}/codemap/extract/griffe_extractor.py

@@ -481,11 +481,13 @@ def _emit_decorated_by(graph, obj) -> None:
 
 # -- pass 2: resolve export + import edges against known nodes ----------------
 
-#: How early an import scope reaches its target: an edge carries the earliest (R1-C29 D2,
-#: R1-C48 D2). ``module`` runs at import time, ``type_checking`` never, ``function`` when
-#: the function runs — the middle one is ordered before ``function`` only so the label
-#: names the construct actually written at module level.
-_SCOPE_RANK = {"module": 0, "type_checking": 1, "function": 2}
+#: 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:

{codmap-0.0.13 → codmap-0.0.15}/codemap/query.py

@@ -119,20 +119,27 @@ class Query:
         # made an incomplete map read as a safety property.
         self._imports = nx.DiGraph()
         self._imports_eager = nx.DiGraph()
+        # 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)
                 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.
+                    # 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,16 +895,35 @@ class Query:
         return [c for c in nx.simple_cycles(self._imports_eager)]
 
     def lazy_import_cycles(self) -> list[list[str]]:
-        """Dependency cycles that close **only** through a non-eager import — one
-        written inside a function (R1-C29) or under ``if TYPE_CHECKING:`` (R1-C48).
+        """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).

{codmap-0.0.13 → codmap-0.0.15}/codemap/serve/architecture.py

@@ -18,9 +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 non-eager import — function-local (R1-C29) or under
-    ``if TYPE_CHECKING:`` (R1-C48). 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
@@ -31,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(),
@@ -85,19 +87,35 @@ def render_architecture(query: Query) -> str:
                f"an import under `if TYPE_CHECKING:` never runs._")
     out.append("")
     if a["lazy_cycles"]:
-        out.append(f"### Dependency cycles closed only by a non-eager import "
-                   f"(function-local, or under `if TYPE_CHECKING:`): {len(a['lazy_cycles'])}")
+        out.append(f"### Dependency cycles closed only by a function-local import: "
+                   f"{len(a['lazy_cycles'])}")
         out.append("")
-        out.append("_These do **not** break at import time — the non-eager import is what "
+        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.13 → codmap-0.0.15}/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("")
@@ -31,11 +32,10 @@ def render_dependencies(query: Query) -> str:
     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. "
-                 + (f"{len(lazy)} further cycle(s) close through a non-eager import "
-                    f"(function-local, or under `if TYPE_CHECKING:`) — real coupling, not "
-                    f"an import-time failure._" if lazy
-                    else "No cycle closes through a non-eager import._"))
+                 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)")
@@ -63,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.13 → codmap-0.0.15}/codemap/serve/check.py

@@ -27,18 +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 non-eager import (function-local, or under `if TYPE_CHECKING:`)",
+        "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),
-        "note": ("a non-eager 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."),
+        "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."),
     }]
 
 
@@ -93,6 +104,10 @@ def render_check(query, contract: ArchitectureContract, violations: list[Violati
                 "and this exits 0. Use `--require-contract` to make a missing contract a "
                 "failure, or `--root DIR` if the file lives elsewhere._\n")
     if not violations:
+        # R1-C49-f1 (consumer, issue #18): every enforced rule must name itself here. A
+        # rule that ran and stayed silent is the R1-C30-f2 defect from the other side —
+        # there the reader concluded more than was checked, here less. `tests/
+        # test_r1c49_type_only_cycles.py` fails if a new rule is added and not listed.
         rules = []
         if contract.layers:
             rules.append(f"layered ({len(contract.layers)})")
@@ -104,6 +119,8 @@ def render_check(query, contract: ArchitectureContract, violations: list[Violati
             rules.append("no_cycles")
         if contract.no_lazy_cycles:
             rules.append("no_lazy_cycles")
+        if contract.no_type_only_cycles:
+            rules.append("no_type_only_cycles")
         if contract.exhaustive:
             rules.append("exhaustive")
         return (f"# Architecture check — `{target}`\n\n"
@@ -132,15 +149,15 @@ def _render_scope(query, contract: ArchitectureContract) -> str:
     if not scope:
         return ""
     s = scope[0]
-    if not s["count"]:
-        return (f"\n_`no_cycles` judged the eager import graph; no dependency cycle is closed "
-                f"only by a non-eager import (function-local, or under `if TYPE_CHECKING:`) "
-                f"either. {s['type_checking_imports']} import(s) under `TYPE_CHECKING` read "
-                f"as never running._\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"non-eager import (function-local, or under `if TYPE_CHECKING:`) were **not** "
-            f"judged: such a cycle cannot break on import, but the coupling is real. "
-            f"`report architecture` lists them; `no_lazy_cycles = true` gates them. "
-            f"{s['type_checking_imports']} import(s) under `TYPE_CHECKING` read as never "
-            f"running._\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.13 → codmap-0.0.15}/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")
@@ -156,9 +157,12 @@ def render_docs(query: Query) -> str:
         # proof of acyclicity, which this map cannot support.
         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 non-eager "
-                   f"import** (function-local, or under `if TYPE_CHECKING:`) — deliberate, "
-                   f"and still mutual coupling.")
+        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.")
     if lay["violations"]:
         out.append("- **Layer violations (mutual dependency):** "
                    + ", ".join(f"{a} ↔ {b}" for a, b in lay["violations"]))

{codmap-0.0.13 → codmap-0.0.15/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.13
+Version: 0.0.15
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -85,7 +85,7 @@ layers         core 9 · data 12 · indicators 16 · analysis 42 · visualizatio
                analysis → core 38 edges · indicators → core 22 · data → core 13
 violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
 cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
-lazy cycles    40 more, closed only by a non-eager import (function-local or `TYPE_CHECKING`) — not import-time failures,
+lazy cycles    40 more, closed only by a function-local import — not import-time failures,
                still mutual coupling: neither module can be extracted without the other
 coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
 concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5

{codmap-0.0.13 → codmap-0.0.15}/codmap.egg-info/SOURCES.txt

@@ -117,6 +117,7 @@ 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.13 → codmap-0.0.15}/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.13"
+version = "0.0.15"
 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.13 → codmap-0.0.15}/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"
 

{codmap-0.0.13 → codmap-0.0.15}/tests/test_m1_query.py

@@ -70,7 +70,9 @@ def test_cycle_detection(q):
     pair = frozenset({PIPELINE, "bquant.analysis.zones.cache"})
     assert pair not in {frozenset(c) for c in q.import_cycles()}, \
         "an import under TYPE_CHECKING must not close an eager cycle"
-    assert pair in {frozenset(c) for c in q.lazy_import_cycles()}
+    assert pair not in {frozenset(c) for c in q.lazy_import_cycles()}, \
+        "nor a runtime one: R1-C49, the pair has no runtime dependency at all"
+    assert pair in {frozenset(c) for c in q.type_only_import_cycles()}
     assert q.import_map()["type_checking"] >= 1
 
 

{codmap-0.0.13 → codmap-0.0.15}/tests/test_r1c29_lazy_imports.py

@@ -163,13 +163,13 @@ def test_architecture_never_claims_acyclic(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 "Dependency cycles closed only by a non-eager import (function-local, or under `if TYPE_CHECKING:`): 1" in md
+    assert "Dependency cycles closed only by a function-local import: 1" in md
 
 
 def test_dependencies_report_never_claims_acyclic(lazy_cycle):
     md = render_dependencies(Query(extract(str(lazy_cycle))))
     assert "acyclic" not in md
-    assert "close through a non-eager import" in md
+    assert "close through a function-local import" in md
 
 
 def test_architecture_payload_carries_both_kinds_and_the_counts(lazy_cycle):

{codmap-0.0.13 → codmap-0.0.15}/tests/test_r1c30f2_check_scope.py

@@ -75,7 +75,7 @@ def test_the_passing_report_names_what_was_not_judged(lazy_cycle):
     out = render_check(lazy_cycle, contract, violations)
     assert "Contract satisfied" in out
     assert "eager import graph only" in out
-    assert "**1** dependency cycle(s)" in out
+    assert "**1** cycle(s) closed only by a function-local import" in out
 
 
 def test_the_structured_payload_carries_it_too(lazy_cycle):
@@ -92,8 +92,9 @@ def test_it_is_declared_even_when_there_is_nothing_to_declare(eager_only):
     contract, violations = _run(eager_only, {"no_cycles": True})
     scope = build_check(eager_only, contract, violations)["scope"]
     assert len(scope) == 1 and scope[0]["count"] == 0
-    assert "no dependency cycle is closed only by a non-eager import" \
-        in render_check(eager_only, contract, violations)
+    md = render_check(eager_only, contract, violations)
+    assert "**0** cycle(s) closed only by a function-local import" in md
+    assert "**0** closed only by an import under `if TYPE_CHECKING:`" in md
 
 
 def test_a_failing_run_carries_the_same_disclosure(lazy_cycle):
@@ -129,7 +130,14 @@ def test_the_opt_in_alone_is_a_contract(lazy_cycle):
 
 
 def test_opting_in_removes_the_disclaimer_because_nothing_is_left_out(lazy_cycle):
+    """R1-C49: there are three kinds now, so "nothing is left out" needs all three rules.
+    With only `no_lazy_cycles` added, the type-only cycles are still unjudged and the
+    disclosure must keep saying so — a gated kind drops out of it, the others do not."""
     contract, violations = _run(lazy_cycle, {"no_cycles": True, "no_lazy_cycles": True})
+    scope = build_check(lazy_cycle, contract, violations)["scope"]
+    assert len(scope) == 1 and scope[0]["lazy_gated"] is True and scope[0]["lazy"] == 0
+    contract, violations = _run(lazy_cycle, {"no_cycles": True, "no_lazy_cycles": True,
+                                             "no_type_only_cycles": True})
     assert build_check(lazy_cycle, contract, violations)["scope"] == []
     assert "not** judged" not in render_check(lazy_cycle, contract, violations)
 

{codmap-0.0.13 → codmap-0.0.15}/tests/test_r1c48_type_checking_imports.py

@@ -127,10 +127,13 @@ def test_a_pair_imported_both_ways_reads_eager(tree):
 
 # -- D4 / D5: the graphs and the map ----------------------------------------------------
 
-def test_the_cycle_is_lazy_not_eager(tree):
+def test_the_cycle_is_not_eager(tree):
+    """R1-C49 moved it one further: not eager (this fix), and not lazy either — the pair
+    has no runtime dependency at all, so it is the third kind."""
     q = tree[2]
     assert q.import_cycles() == [], "the gate's defect: this used to be the one eager cycle"
-    assert [sorted(c) for c in q.lazy_import_cycles()] == [["tcpkg.cache", "tcpkg.pipeline"]]
+    assert q.lazy_import_cycles() == []
+    assert [sorted(c) for c in q.type_only_import_cycles()] == [["tcpkg.cache", "tcpkg.pipeline"]]
 
 
 def test_import_map_names_the_scope_always(tree):
@@ -148,9 +151,9 @@ def test_every_consumer_says_which_imports_it_did_not_judge(tree):
     assert a["import_map"]["type_checking"] == 3
     md = render_architecture(q)
     assert "3 `TYPE_CHECKING` import(s)" in md
-    assert "closed only by a non-eager import (function-local, or under `if TYPE_CHECKING:`): 1" 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 "non-eager import" in render_docs(q)
+    assert "closed only by an import under `if TYPE_CHECKING:`" in render_docs(q)
 
 
 def test_the_gate_is_green_and_names_what_it_read(tree):
@@ -161,15 +164,18 @@ def test_the_gate_is_green_and_names_what_it_read(tree):
     payload = build_check(q, contract, violations)
     assert payload["ok"] is True
     assert payload["scope"][0]["count"] == 1
+    assert payload["scope"][0]["type_only"] == 1 and payload["scope"][0]["lazy"] == 0
     assert payload["scope"][0]["type_checking_imports"] == 3
     md = render_check(q, contract, violations)
     assert "3 import(s) under `TYPE_CHECKING` read as never running" in md
 
 
-def test_no_lazy_cycles_still_gates_the_coupling(tree):
-    contract = arch.ArchitectureContract(no_lazy_cycles=True)
-    v = arch.check_contract(tree[2], contract)
-    assert [x.rule for x in v] == ["no_lazy_cycles"]
+def test_the_type_only_rule_gates_the_coupling(tree):
+    """R1-C49: `no_lazy_cycles` is about a lazy import used to walk around `no_cycles`,
+    which this is not; the opt-in rule for the type layer is the one that fires."""
+    assert arch.check_contract(tree[2], arch.ArchitectureContract(no_lazy_cycles=True)) == []
+    v = arch.check_contract(tree[2], arch.ArchitectureContract(no_type_only_cycles=True))
+    assert [x.rule for x in v] == ["no_type_only_cycles"]
     assert "under `if TYPE_CHECKING:`" in v[0].summary