codmap 0.0.19__tar.gz → 0.0.21__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.19
+Version: 0.0.21
 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, **990 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.21}/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, **990 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.21}/codemap/arch.py

@@ -57,6 +57,11 @@ class ArchitectureContract:
     no_lazy_cycles: bool = False
     no_type_only_cycles: bool = False
     exhaustive: bool = False
+    # R1-C62: the mirror of `exhaustive`. That one asks "is every layer of the code
+    # declared?"; this asks "does every declared name exist?". Opt-in, because a contract
+    # written ahead of the code is a documented, legitimate use (see the module docstring)
+    # and failing on it by default would turn that practice red on somebody else's tree.
+    no_phantom_rules: bool = False
     error: str | None = None
     # R1-C35: the file this contract was looked for in. "No contract found" is only
     # actionable next to *where* we looked — a reader in the wrong directory cannot tell
@@ -66,7 +71,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.no_type_only_cycles or self.exhaustive)
+                    or self.no_type_only_cycles or self.exhaustive
+                    or self.no_phantom_rules)
 
 
 @dataclass(frozen=True)
@@ -117,9 +123,46 @@ def parse_contract(section: dict) -> ArchitectureContract:
         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)),
+        no_phantom_rules=bool(section.get("no_phantom_rules", False)),
     )
 
 
+def _graph_layers(query) -> set[str]:
+    """Layer names that exist in the core import graph."""
+    return {query._layer_of(m) for m in query.import_graph.nodes
+            if query.root_of(m) == "core"}
+
+
+def applicability(query, contract: ArchitectureContract) -> dict:
+    """Per-rule *declared* vs *applicable* counts, plus the names that do not exist (R1-C62).
+
+    A rule naming a layer the graph does not contain is **inert by design** — no module, no
+    edge, nothing to break — which is what lets a contract be written ahead of the code. The
+    defect that made this function necessary is not the inertness: it is that the gate
+    counted such a rule as *enforced*, so a renamed layer left a green tick over a rule that
+    could no longer fire.
+
+    Applicability is presence of the **name**, nothing cleverer: `layers` needs the layer,
+    `independent` needs at least two members of the group (one cannot import itself), and
+    `forbidden` needs both ends. Whether a violation is even possible between two existing
+    layers is not asked, and should not be.
+    """
+    present = _graph_layers(query)
+    named = set(contract.layers) | {m for grp in contract.independent for m in grp}
+    named |= {n for pair in contract.forbidden for n in pair}
+    return {
+        "layers": {"declared": len(contract.layers),
+                   "applicable": sum(1 for x in contract.layers if x in present)},
+        "independent": {"declared": len(contract.independent),
+                        "applicable": sum(1 for g in contract.independent
+                                          if len([x for x in g if x in present]) >= 2)},
+        "forbidden": {"declared": len(contract.forbidden),
+                      "applicable": sum(1 for (a, b) in contract.forbidden
+                                        if a in present and b in present)},
+        "absent_names": tuple(sorted(n for n in named if n not in present)),
+    }
+
+
 def _core_layer_edges(query) -> list[tuple[str, str, str, str]]:
     """Cross-layer core→core import edges as (importer, imported, layer_i, layer_j)."""
     ig = query.import_graph
@@ -133,6 +176,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 +249,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 +266,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 +283,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 -----------------
@@ -249,4 +309,18 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
                 modules=tuple(undeclared),
             ))
 
+    # -- no_phantom_rules: every name the contract mentions must exist -----------
+    # R1-C62, the mirror of `exhaustive`. Off by default on purpose: inert rules are how a
+    # contract gets written ahead of the code. On, it catches the drift the count alone
+    # only *discloses* — a layer renamed while the contract kept guarding the old name.
+    if contract.no_phantom_rules:
+        absent = applicability(query, contract)["absent_names"]
+        if absent:
+            violations.append(Violation(
+                "no_phantom_rules",
+                f"{len(absent)} name(s) in the contract are absent from the graph, "
+                "so the rules naming them cannot apply",
+                modules=absent,
+            ))
+
     return violations

{codmap-0.0.19 → codmap-0.0.21}/codemap/cli.py

@@ -73,6 +73,23 @@ _REPORTS = {
 _REPORT_KINDS = sorted(_REPORTS) + ["impact", "communities", "flows"]  # extra args
 
 
+def _emit_answer(text: str) -> None:
+    """Print a markdown answer with the answer-format trailer (R1-C63).
+
+    One seam rather than a line in every renderer: the renderers stay pure functions of the
+    graph, and there is one place to forget rather than nine. The trailer is what a consumer
+    diffing our output sees when the *shape* of an answer changes deliberately — 0.0.20
+    changed the gate's lines while the graph stayed byte-identical, and on a text diff that
+    looked exactly like the #20 defect, where the text moved between runs of one version. The
+    only thing that told them apart was a message written by hand.
+    """
+    from codemap.model import ANSWER_FORMAT, SCHEMA_VERSION
+    print(text, end="")
+    if not text.endswith("\n"):
+        print()
+    print(f"_answer format {ANSWER_FORMAT} · schema {SCHEMA_VERSION}_")
+
+
 def _graph_from(args):
     if getattr(args, "build", None):
         return extract(args.build, deep=getattr(args, "deep", False))
@@ -507,28 +524,28 @@ def _cmd_report(args) -> int:
     if args.kind == "impact":
         if not args.symbol:
             raise SystemExit("error: report impact needs --symbol <name>")
-        print(render_impact(Query(graph), args.symbol, depth=args.depth,
-                            flow_depth=args.flow_depth), end="")
+        _emit_answer(render_impact(Query(graph), args.symbol, depth=args.depth,
+                        flow_depth=args.flow_depth))
         return 0
     if args.kind in ("communities", "flows"):
         from codemap.serve.subsystems import render_communities, render_flows
         q = Query(graph)
         out = (render_communities(q) if args.kind == "communities"
                else render_flows(q, args.symbol, depth=args.depth))
-        print(out, end="")
+        _emit_answer(out)
         return 0
     if args.kind == "dead-code":
         from codemap.serve.audit import load_dead_code_whitelist
         root = getattr(args, "source_root", None) or os.getcwd()
         whitelist, wl_error = load_dead_code_whitelist(root)
-        print(render_dead_code(Query(graph),
+        _emit_answer(render_dead_code(Query(graph),
                                whitelist=whitelist,
                                min_confidence=args.min_confidence,
-                               whitelist_error=wl_error), end="")
+                               whitelist_error=wl_error))
         return 0
     renderer = _REPORTS[args.kind]
     payload = renderer(graph) if args.kind == "api-surface" else renderer(Query(graph))
-    print(payload, end="")
+    _emit_answer(payload)
     return 0
 
 
@@ -755,13 +772,13 @@ def _cmd_check(args) -> int:
     # would sort an unreadable contract into the success branch of every `if rc == 2` that
     # already exists in someone's pipeline.
     if contract.error:
-        print(render_check(q, contract, []), end="")
+        _emit_answer(render_check(q, contract, []))
         return 2
     if contract.is_empty() and args.require_contract:
-        print(render_check(q, contract, []), end="")
+        _emit_answer(render_check(q, contract, []))
         raise SystemExit("error: no [architecture] contract found (--require-contract)")
     violations = check_contract(q, contract)
-    print(render_check(q, contract, violations), end="")
+    _emit_answer(render_check(q, contract, violations))
     return 2 if violations else 0
 
 

{codmap-0.0.19 → codmap-0.0.21}/codemap/model.py

@@ -77,6 +77,24 @@ from typing import Any
 #       (they had ``lineno`` alone, so `search` answered a line number with no file).
 SCHEMA_VERSION = "0.13"
 
+# R1-C63: the *answer* has a shape too, and consumers diff it. `SCHEMA_VERSION` versions the
+# artifact; 0.0.20 left the graph byte-identical and changed the architecture report and the
+# gate's lines completely (a cycle answer became a tangle), which on a text diff is
+# indistinguishable from the #20 defect — where the text moved between runs of one version,
+# without anyone deciding it. The only thing that told the consumer apart was a message I
+# wrote by hand.
+#
+# Bump on a change to the **structure a consumer sees**: a block appears or vanishes, a
+# counted unit changes meaning, a verdict or heading changes shape, a field in a structured
+# answer changes type or semantics. Do **not** bump for wording, typos or added prose inside
+# an existing note — a version that ticks on whitespace stops being read, which is worse than
+# not having one. Independent of SCHEMA_VERSION by design: the graph can be identical while
+# this moves, and that is the case it exists for.
+#
+# Starts at 1 with 0.0.21 and makes no claim about earlier releases: the answer format changed
+# many times before it, and numbering that retroactively would be inventing a history.
+ANSWER_FORMAT = 1
+
 # Closed vocabulary of edge types (R1-C7). Node ``kind`` is deliberately an OPEN set
 # (DESIGN §2 — new entity kinds may appear), but edges are TYPED: every relationship
 # codemap emits is one of these, each with a fixed meaning. This is the machine-

{codmap-0.0.19 → codmap-0.0.21}/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.21}/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.21}/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("")