codmap 0.0.19__tar.gz → 0.0.20__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.19
+Version: 0.0.20
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **961 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **972 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.19 → codmap-0.0.20}/README.md

@@ -8,7 +8,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **961 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **972 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.19 → codmap-0.0.20}/codemap/arch.py

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

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

@@ -1129,16 +1129,103 @@ class Query:
 
     # -- graph-wide ----------------------------------------------------------
 
+    def _tangle_sets(self, g) -> set[frozenset]:
+        """Strongly connected components of ``g`` that are cycles (R1-C58).
+
+        A tangle — not a cycle — is the unit a reader acts on: *these N modules cannot be
+        separated*. The number of **simple cycles** through them is combinatorial and says
+        nothing more; on pytest's `_pytest` it was 1080 / 95 001 / 464 109 for one tangle
+        of 78 modules, and enumerating them cost 10 s of a report that printed twenty.
+        """
+        out = {frozenset(c) for c in nx.strongly_connected_components(g) if len(c) > 1}
+        out |= {frozenset({n}) for n in g.nodes if g.has_edge(n, n)}
+        return out
+
+    def _example_cycle(self, g, modules: frozenset,
+                       via: set | None = None) -> tuple[list[str], tuple | None]:
+        """One cycle through ``modules``, chosen deterministically (R1-C58).
+
+        Deliberately **not** promised to be the shortest — promising it would buy a
+        narrowing we would then have to declare. It is an example, and it is chosen to
+        pass through an edge of the class that *defines* the tangle (``via``): a lazy
+        tangle must show a function-local edge, or the example reads like an eager cycle
+        in the section about lazy ones. Returns the cycle and that edge, so the answer can
+        name *which* import is the one holding the tangle together.
+        """
+        sub = g.subgraph(modules)
+        chosen = sorted(e for e in sub.edges if via is None or e in via)
+        edges = chosen or sorted(sub.edges)
+        if not edges:
+            return sorted(modules), None    # a self-loop: the module is the whole cycle
+        src, dst = edges[0]
+        edge = (src, dst) if chosen else None
+        if src == dst:
+            return [src], edge
+        try:
+            path = nx.shortest_path(sub, dst, src)
+        except nx.NetworkXNoPath:           # cannot happen inside an SCC; not asserted
+            return sorted(modules), edge
+        return _canonical_cycles([path])[0], edge
+
+    def _tangles(self, g, weaker: set[frozenset], via: set | None = None) -> list[dict]:
+        """Tangles of ``g`` that are not already reported in a stronger class."""
+        out = []
+        for tangle in self._tangle_sets(g) - weaker:
+            example, edge = self._example_cycle(g, tangle, via)
+            sub = g.subgraph(tangle)
+            row = {"modules": sorted(tangle), "size": len(tangle),
+                   # R1-C58: the cycle rank (first Betti number) of the tangle — how many
+                   # **independent** loops it holds. This is the part of the old count that
+                   # was worth keeping: two loops sharing one module are two problems, and
+                   # collapsing them to "one tangle" would hide that. Unlike the number of
+                   # simple cycles it is linear to compute and does not explode: the 19-module
+                   # tangle in pytest has 1080 simple cycles and 31 independent loops.
+                   "loops": sub.number_of_edges() - len(tangle) + 1,
+                   "example": example}
+            if edge:
+                row["closed_by"] = list(edge)
+            out.append(row)
+        return sorted(out, key=lambda r: (r["size"], r["modules"]))
+
+    def import_tangles(self) -> list[dict]:
+        """Mutually-dependent module groups in the **eager** import graph (R1-C58).
+
+        Each entry is ``{modules, size, example}``: the group that cannot be separated,
+        and one cycle through it. The count of simple cycles is not reported — see
+        :meth:`_tangle_sets`.
+        """
+        return self._tangles(self._imports_eager, set())
+
+    def lazy_import_tangles(self) -> list[dict]:
+        """Tangles that exist only once function-local imports are counted."""
+        return self._tangles(self._imports_runtime,
+                             self._tangle_sets(self._imports_eager),
+                             via={(e.source, e.target) for e in self.graph.edges
+                                  if e.type == "imports"
+                                  and e.extras.get("scope") == "function"})
+
+    def type_only_import_tangles(self) -> list[dict]:
+        """Tangles that exist only once imports that never execute are counted."""
+        return self._tangles(self._imports, self._tangle_sets(self._imports_runtime),
+                             via={(e.source, e.target) for e in self.graph.edges
+                                  if e.type == "imports"
+                                  and e.extras.get("scope") in ("type_checking", "stub")})
+
     def import_cycles(self) -> list[list[str]]:
-        """Cycles that exist in the **eager** import graph — the import-order landmines.
+        """One example cycle per **eager** tangle — the import-order landmines.
 
         R1-C29: deliberately *not* computed over every import edge. A function-local
         import does not run at import time, so a cycle closed only by one does not break
         on import — it is what a developer writes to stop it breaking. Counting it here
         would report someone's fix as their bug. Those cycles are still real coupling
         and are returned by :meth:`lazy_import_cycles`.
+
+        R1-C58 changed what one entry **means**: it used to be every simple cycle, which
+        is a combinatorial quantity (1080 entries for one tangle of 78 modules), and is
+        now one representative per tangle. :meth:`import_tangles` carries the group each
+        example stands for.
         """
-        return _canonical_cycles(nx.simple_cycles(self._imports_eager))
+        return _canonical_cycles(t["example"] for t in self.import_tangles())
 
     def lazy_import_cycles(self) -> list[list[str]]:
         """Dependency cycles that close **only** through a function-local import.
@@ -1155,9 +1242,7 @@ class Query:
         function-local import stays *lazy* however many type imports also run between
         them, or a tree could hide real coupling by adding one.
         """
-        eager = {frozenset(c) for c in nx.simple_cycles(self._imports_eager)}
-        return _canonical_cycles(c for c in nx.simple_cycles(self._imports_runtime)
-                                 if frozenset(c) not in eager)
+        return _canonical_cycles(t["example"] for t in self.lazy_import_tangles())
 
     def type_only_import_cycles(self) -> list[list[str]]:
         """Dependency cycles that close **only** with an import that never executes.
@@ -1174,9 +1259,7 @@ class Query:
         break — while the edge keeps the mechanism in ``extras.scope``. Measured on
         Pillow, whose *only* "hard" cycle was a stub declaring the module that imports it.
         """
-        runtime = {frozenset(c) for c in nx.simple_cycles(self._imports_runtime)}
-        return _canonical_cycles(c for c in nx.simple_cycles(self._imports)
-                                 if frozenset(c) not in runtime)
+        return _canonical_cycles(t["example"] for t in self.type_only_import_tangles())
 
     def import_map(self) -> dict:
         """How much of the import graph each scope contributed (R1-C29).

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

@@ -15,6 +15,36 @@ from codemap.diagnostics import render_lines
 from codemap.query import Query
 
 
+def _tangle_head(tangles: list[dict]) -> str:
+    """`N tangle(s) (M modules)` — the count that is stable under adding an edge.
+
+    R1-C58: the previous head counted **simple cycles**, which is combinatorial. A tangle
+    of three mutually-dependent modules has one head here and produced five entries there;
+    pytest's `_pytest` produced 1080, 95 001 and 464 109 for one tangle each.
+    """
+    if not tangles:
+        return "0"
+    return (f"{len(tangles)} tangle(s), {sum(t['size'] for t in tangles)} module(s), "
+            f"{sum(t['loops'] for t in tangles)} independent loop(s)")
+
+
+def _tangle_lines(tangles: list[dict]) -> list[str]:
+    """One block per tangle: its members, and one cycle through it as an example."""
+    out: list[str] = []
+    for tg in tangles:
+        if tg["size"] == 1:
+            out.append(f"- `{tg['modules'][0]}` — imports itself")
+            continue
+        out.append(f"- **{tg['size']} modules, {tg['loops']} independent loop(s):** "
+                   + ", ".join(f"`{m}`" for m in tg["modules"]))
+        ex = tg["example"]
+        line = f"  - e.g. {' → '.join(ex)} → {ex[0]}"
+        if tg.get("closed_by"):
+            line += f" — held together by `{tg['closed_by'][0]}` → `{tg['closed_by'][1]}`"
+        out.append(line)
+    return out
+
+
 def build_architecture(query: Query) -> dict:
     """Structured whole-system overview (cycles + layers + coupling + hotspots).
 
@@ -30,9 +60,16 @@ def build_architecture(query: Query) -> dict:
     """
     return {
         "target": query.graph.target,
+        # R1-C58: the unit is the tangle (a strongly connected group of modules). The
+        # `*_cycles` keys stay, carrying **one example per tangle** — they used to carry
+        # every simple cycle, a combinatorial quantity that reached 464 109 entries for a
+        # single tangle of 78 modules and said nothing the tangle does not.
         "cycles": query.import_cycles(),
         "lazy_cycles": query.lazy_import_cycles(),
         "type_only_cycles": query.type_only_import_cycles(),
+        "tangles": query.import_tangles(),
+        "lazy_tangles": query.lazy_import_tangles(),
+        "type_only_tangles": query.type_only_import_tangles(),
         "import_map": query.import_map(),
         "layers": query.layers(),
         "coupling": query.coupling(),
@@ -54,15 +91,27 @@ def render_architecture(query: Query) -> str:
 
     # -- layers -------------------------------------------------------------
     lay = a["layers"]
+    # R1-C58/D4: a layer is the first path segment under the root. A package with no
+    # subpackages therefore has one layer per module, and the section reads as an
+    # architectural overview while saying only "this package is flat". Measured on
+    # Pillow: "Layers (105)" over 105 modules. Say it instead of implying structure.
+    degenerate = bool(lay["layers"]) and all(len(m) == 1 for m in lay["layers"].values())
     out.append(f"## Layers ({len(lay['layers'])})")
     out.append("")
+    if degenerate:
+        out.append("_This package has no subpackages, so **layer = module** here: the "
+                   "grouping below is the module list, and the inter-layer view would "
+                   "repeat the import graph edge for edge. Not a statement about "
+                   "structure — a statement that there is none to report._")
+        out.append("")
     for name, mods in lay["layers"].items():
         out.append(f"- **{name}** — {len(mods)} module(s)")
     out.append("")
-    out.append("### Inter-layer dependencies")
-    out.append("")
-    out.extend([f"- {edge} ({n})" for edge, n in lay["edges"].items()] or ["_none._"])
-    out.append("")
+    if not degenerate:
+        out.append("### Inter-layer dependencies")
+        out.append("")
+        out.extend([f"- {edge} ({n})" for edge, n in lay["edges"].items()] or ["_none._"])
+        out.append("")
     if lay["violations"]:
         out.append("### ⚠ Layer violations (mutual dependency)")
         out.append("")
@@ -75,10 +124,15 @@ def render_architecture(query: Query) -> str:
     # R1-C29: never state acyclicity as a property. The map is only as complete as the
     # imports it read, and the reader cannot see which those were unless we say so.
     im = a["import_map"]
-    out.append(f"## Import cycles: {len(a['cycles'])}")
+    out.append(f"## Import cycles: {_tangle_head(a['tangles'])}")
+    out.append("")
+    out.append("_A **tangle** is a group of modules that cannot be separated — the unit you "
+               "would act on — and its **independent loops** are how many distinct ways it "
+               "closes (the cycle rank). The number of *simple* cycles is combinatorial (one "
+               "19-module tangle of a real package has 1080, and its 78-module tangle has "
+               "464 109) and is deliberately not reported; one example cycle per tangle is._")
     out.append("")
-    out.extend([f"- {' → '.join(c)} → {c[0]}" for c in
-                sorted(a["cycles"], key=lambda c: (len(c), c))]
+    out.extend(_tangle_lines(a["tangles"])
                or ["_none found in the eager import graph._"])
     out.append("")
     out.append(f"_Read {im['module_level']} module-level, {im['function_local']} "
@@ -89,33 +143,27 @@ def render_architecture(query: Query) -> str:
     out.append("")
     if a["lazy_cycles"]:
         out.append(f"### Dependency cycles closed only by a function-local import: "
-                   f"{len(a['lazy_cycles'])}")
+                   f"{_tangle_head(a['lazy_tangles'])}")
         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 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.extend(_tangle_lines(a["lazy_tangles"]))
         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 that never runs "
-                   f"(`if TYPE_CHECKING:` or a `.pyi`): {len(a['type_only_cycles'])}")
+                   f"(`if TYPE_CHECKING:` or a `.pyi`): {_tangle_head(a['type_only_tangles'])}")
         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.extend(_tangle_lines(a["type_only_tangles"]))
         out.append("")
 
     # -- coupling -----------------------------------------------------------

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

@@ -17,15 +17,19 @@ def render_dependencies(query: Query) -> str:
     # it; each check supplies its own consequence, or none (issue #8).
     lines.extend(render_lines(query.graph))
 
-    cycles = query.import_cycles()
-    lazy = query.lazy_import_cycles()
-    type_only = query.type_only_import_cycles()
+    tangles = query.import_tangles()
+    lazy = query.lazy_import_tangles()
+    type_only = query.type_only_import_tangles()
     im = query.import_map()
-    lines.append(f"## Import cycles: {len(cycles)}")
+    # R1-C58: tangles, not simple cycles — the count of the latter is combinatorial.
+    lines.append(f"## Import cycles: {len(tangles)} tangle(s)"
+                 + (f", {sum(t['size'] for t in tangles)} module(s)" if tangles else ""))
     lines.append("")
-    if cycles:
-        for cyc in sorted(cycles, key=lambda c: (len(c), c)):
-            lines.append(f"- {' → '.join(cyc)} → {cyc[0]}")
+    if tangles:
+        for tg in tangles:
+            ex = tg["example"]
+            lines.append(f"- **{tg['size']} modules** — e.g. "
+                         f"{' → '.join(ex)} → {ex[0]}")
     else:
         # R1-C29: "none found" is what was measured; "acyclic" is a property, and the
         # map that would have to be complete to support it demonstrably is not.
@@ -34,7 +38,7 @@ def render_dependencies(query: Query) -> str:
     lines.append(f"_Read {im['module_level']} module-level, {im['function_local']} "
                  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"tangle(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("")

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

@@ -34,8 +34,8 @@ def _not_judged(query, contract: ArchitectureContract) -> list[dict]:
     # 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()
+    lazy = [] if contract.no_lazy_cycles else query.lazy_import_tangles()
+    type_only = [] if contract.no_type_only_cycles else query.type_only_import_tangles()
     return [{
         "rule": "no_cycles",
         "judged": "the eager import graph — imports that run at import time",

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

@@ -142,25 +142,26 @@ def render_docs(query: Query) -> str:
         out.append("")
 
     # -- architecture caveats (the honest health section) -------------------
-    cycles = query.import_cycles()
-    lazy = query.lazy_import_cycles()
-    type_only = query.type_only_import_cycles()
+    cycles = query.import_tangles()
+    lazy = query.lazy_import_tangles()
+    type_only = query.type_only_import_tangles()
     lay = query.layers()
     gods = query.hotspots()["god_classes"]
     out.append("## Architecture notes")
     out.append("")
     if cycles:
-        out.append(f"- **{len(cycles)} import cycle(s)** — e.g. "
-                   + "; ".join(" → ".join(c) for c in sorted(cycles, key=len)[:3]))
+        out.append(f"- **{len(cycles)} import tangle(s)**, {sum(c['size'] for c in cycles)} "
+                   f"module(s) that cannot be separated — e.g. "
+                   + "; ".join(" → ".join(c["example"]) for c in cycles[:3]))
     else:
         # R1-C29: no cycle *found*, over the imports that run at import time — not a
         # 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 function-local "
+        out.append(f"- **{len(lazy)} tangle(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 that "
+        out.append(f"- **{len(type_only)} tangle(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"]:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.19
+Version: 0.0.20
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **961 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **972 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.19 → codmap-0.0.20}/codmap.egg-info/SOURCES.txt

@@ -127,6 +127,7 @@ 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_r1c58_cycle_tangles.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py
 tests/test_r1c7_edge_vocab.py

{codmap-0.0.19 → codmap-0.0.20}/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.19"
+version = "0.0.20"
 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.19 → codmap-0.0.20}/tests/test_m16_architecture.py

@@ -80,7 +80,10 @@ def test_build_architecture_has_all_sections(q):
     # 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", "type_only_cycles", "import_map",
+    assert set(a) == {"target", "cycles", "lazy_cycles", "type_only_cycles",
+                      # R1-C58: the tangle is the unit; the `*_cycles` keys stay and carry
+                      # one example per tangle, because consumers parse them.
+                      "tangles", "lazy_tangles", "type_only_tangles", "import_map",
                       "layers", "coupling", "hotspots"}
     assert a["target"] == "dispatchpkg"
 

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

@@ -116,16 +116,23 @@ def test_an_eager_cycle_is_still_an_import_cycle(tmp_path):
     assert q.lazy_import_cycles() == [], "an eager cycle is not also a lazy one"
 
 
-def test_a_longer_cycle_whose_lazy_edge_closes_it_is_enumerated(tmp_path):
+def test_two_loops_sharing_a_module_are_two_loops(tmp_path):
     """Three modules, the lazy import at the far end — the shape both audit scripts lost.
 
     The reporter of #11 verified the fix on their tree and found codemap reporting **three**
     cycles where their issue had claimed two. Their scan collected DFS back-edges instead
     of enumerating simple cycles, so a 3-node cycle was swallowed once its nodes were
     coloured; ours mis-anchored relative imports. Two independent scripts written to audit
-    a tool, both less careful than the tool, on the same day. This test pins the property
-    that made codemap right here: every elementary cycle, not one representative per
-    strongly-connected blob.
+    a tool, both less careful than the tool, on the same day.
+
+    **R1-C58 reversed the decision this test used to pin** — "every elementary cycle, not
+    one representative per strongly-connected blob" — because enumerating them is
+    combinatorial: one 78-module group of a real package has 464 109 of them, and printing
+    twenty took ten seconds. What must survive the reversal is the property #11 was about:
+    *nothing is swallowed*. Two loops that share a module are still two, and every module
+    in a cycle is still named. That is now carried by the tangle's **cycle rank** (its
+    independent loops) and its membership, instead of by a list whose length is a
+    combinatorial artefact.
     """
     pkg = _pkg(tmp_path, {
         "a.py": "from pkg.b import beta\n\n\ndef alpha():\n    return 1\n",
@@ -141,11 +148,15 @@ def test_a_longer_cycle_whose_lazy_edge_closes_it_is_enumerated(tmp_path):
         "    from pkg.e import eps\n    return eps()\n")
     q = Query(extract(str(pkg)))
     assert q.import_cycles() == [], "every cycle here is closed by a lazy import"
-    found = {frozenset(c) for c in q.lazy_import_cycles()}
-    assert frozenset({"pkg.a", "pkg.b", "pkg.c"}) in found
-    assert frozenset({"pkg.a", "pkg.d", "pkg.e"}) in found, (
-        "a second cycle sharing a node was swallowed — this is back-edge collection, "
-        "not simple-cycle enumeration")
+    tangles = q.lazy_import_tangles()
+    assert len(tangles) == 1, "the two loops share pkg.a, so they are one inseparable group"
+    tangle = tangles[0]
+    assert tangle["modules"] == ["pkg.a", "pkg.b", "pkg.c", "pkg.d", "pkg.e"], (
+        "a module of a cycle was swallowed — the failure #11 was about")
+    assert tangle["loops"] == 2, (
+        "two loops sharing a module are two problems: breaking a → b does not free "
+        "a → d → e → a, and a single count of 'one tangle' would hide that")
+    assert len(q.lazy_import_cycles()) == 1, "one example cycle per tangle"
 
 
 def test_import_map_is_emitted_even_when_nothing_is_lazy(tmp_path):

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

@@ -176,7 +176,7 @@ def test_the_type_only_rule_gates_the_coupling(tree):
     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
+    assert "an import that never runs (`if TYPE_CHECKING:` or a `.pyi`)" in v[0].summary
 
 
 # -- the mutation ---------------------------------------------------------------------------

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

@@ -195,7 +195,7 @@ def test_the_reports_carry_both_kinds_and_say_zero(both, tmp_path):
     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 further tangle(s) close through a function-local import" 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)