pymodularity 0.2.0__tar.gz

pymodularity-0.2.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: pymodularity
+Version: 0.2.0
+Summary: See and check a repo's real Python imports: a privacy convention on PEP 8 underscores, an import-cycle ban, and a coupling report, all derived from the code.
+Author: Tilo Himmelsbach
+License-Expression: MIT
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/dertilo/pymodularity
+Project-URL: Repository, https://github.com/dertilo/pymodularity
+Project-URL: Issues, https://github.com/dertilo/pymodularity/issues
+Description-Content-Type: text/markdown
+
+# pymodularity
+
+Formerly published as `underscope`.
+
+The underscore's position in a Python import path sets that import's scope — Rust's `pub(super)`/`pub(crate)`, applied to PEP 8 underscores.
+
+`pymodularity` draws a repo's real Python imports as mermaid diagrams, checks them against conventions derived from the code itself (no allow-list to maintain), and reports which files and directories carry the most structural coupling. It needs only the standard library to analyze your code — no runtime dependencies. `check`'s dependency-declaration rule additionally needs `uv` on PATH (see below).
+
+## Install and run
+
+```bash
+uvx pymodularity check .
+uvx pymodularity graph . --out docs/imports
+uvx pymodularity metrics .
+```
+
+Or, inside a project: `uv add --dev pymodularity` and run `pymodularity ...` in that project's venv.
+
+## The rules `check` enforces
+
+Given this tree:
+
+```
+shop/
+  __init__.py
+  billing/
+    __init__.py
+    invoice.py          # from shop.billing._pricing import compute_total
+    _pricing.py          # def compute_total(): ...
+  catalog/
+    __init__.py
+    listing.py           # from shop.billing._pricing import compute_total  <- finding
+```
+
+- **No import cycle**, at any directory level: between files, and between directories at every depth. Imports under `if TYPE_CHECKING:` and inside function bodies count. There is no baseline — an existing cycle fails too.
+- **A private item stays visible only to its owner and the owner's descendants** (Go's `internal/`, applied as Rust's visibility rule to PEP 8 underscores):
+  - a private module — a file, or a path component, named `_x` (single leading underscore, not a dunder) — belongs to the directory holding it; only files under that directory may import it, across package boundaries;
+  - a private name imported via `from m import _x` belongs to `m`; if `m` is a single file, no other file may import `_x`, not even a sibling in the same directory;
+  - if `m` is a package (an `__init__.py` or a namespace package directory), `_x` belongs to that directory, and files under it may import it.
+  - a parent never reaches into a child's private items, and neither do siblings.
+  - `shop/billing/invoice.py` above is allowed (it's under `shop/billing`, `_pricing`'s owner); `shop/catalog/listing.py` is a finding.
+  - the attribute form (`import shop.billing._pricing as p; p.compute_total`) is out of scope here — ruff's `SLF001` already flags it.
+
+`pymodularity check .` exits 1 on any finding and prints, per finding, the importing file, the target, and the directory or file that owns it.
+
+- **Dependency declarations are correct**, on by default, skipped with `check --no-deps`: for each package root (a directory with a `pyproject.toml` `[project]` table), runs [deptry](https://github.com/fpgmaas/deptry) (`uv run --directory <pkg> --with deptry==<pinned version> --frozen deptry . --json-output <tmp>`, a nested package root excluded from its parent's scan via `--extend-exclude`) and reports its findings (unused, missing, and transitive dependencies) the same way as the other rules. A package is skipped, not scanned, if it declares no runtime dependencies, or has no `uv.lock` of its own. This rule needs `uv` on PATH — `check` exits 2 with an error if it is missing, never a silent skip. The first run creates a `.venv` inside each scanned package and downloads its dependencies; later runs reuse it.
+
+- **Structure limits**, fixed constants, no config, no baseline — every one of these is a finding regardless of how long it's been true:
+  - a scanned file has at most 500 physical lines.
+  - a directory has at most 10 entries, where an entry is a scanned `.py` file directly in it or a subdirectory holding scanned `.py` files, transitively; `__init__.py` and `__main__.py` don't count as entries (they're still scanned and still count toward the other limits).
+  - a package root (the same `pyproject.toml` `[project]`-table directory the privacy and dependency rules anchor on) has at most 100 scanned files, each file counted against its nearest (innermost) package root.
+  - a file has at most 15 public top-level names (no leading `_`): `def`/`async def`/`class`, a plain or annotated assignment target (including tuple-unpacking), or a `type X = ...` alias, at top level or nested in a top-level `if`/`try` block (including `elif`/`else`, `except` handlers, `finally`). Imports never count. A top-level function (not a class — `@dataclass` sits on most models) a decorator registers doesn't count either: FastAPI, Typer/Click, Dagster, pytest and the like derive part of their contract (route `operationId`, CLI command name, asset key, fixture name) from the function's name, so counting it toward the width cap would pressure someone into renaming or restructuring around a name the framework, not this tool, owns. Any decorator counts — there's no list of framework names.
+
+## The 3 subcommands
+
+- `pymodularity check <repo> [--no-deps]` — run all four rules above, print findings, exit 1 on any finding (`--no-deps` skips the dependency-declaration rule).
+- `pymodularity graph <repo> --out DIR [--html]` — write one mermaid view per directory under `DIR`: `index.md` everywhere, plus a clickable `index.html` per view with `--html` (needs network access in the browser to load mermaid from a CDN).
+- `pymodularity metrics <repo>` — print a coupling report to stdout: reach (dependents/dependencies, transitive) and a `score` per file and per directory; interface width (names other code imports from a unit); exposure share (how much of what a file defines actually gets used elsewhere); entry files (how much of a directory outside code actually reaches into); misplaced files (files whose closest partners sit mostly in another directory). Always exits 0 — a report, never a gate.
+
+## Blind spots
+
+`pymodularity` shows import coupling only, a lower bound on logical coupling ("if A changes, must B?"). Coupling that bypasses Python imports stays invisible:
+
+- HTTP APIs, shared database schemas and tables, config keys and env vars, message and file formats, string-keyed registries, runtime `sys.path` edits.
+- Two files with no edge here can still force each other's edits. **Never read a missing edge as independence.**
+
+Other limits:
+
+- a `warning: ambiguous import` line (printed to stderr) means several files in the repo match one import; no edge is drawn for it.
+- an import that only resolves through a runtime `sys.path` edit is matched by file path, which can pick the wrong file.
+- a third-party name that happens to equal a package folder elsewhere in the repo draws a false edge.
+- test directories (`tests/`, `test/`) and test files (`test_*.py`, `*_test.py`, `conftest.py`) are always skipped, no flag — a test importing a sibling would otherwise draw a production dependency that production never has.
+- `metrics` is a report on numbers that keep moving even on a repo that passes `check` clean; gating on it rewards gaming the number (for example, replacing an import with a string-keyed registry) instead of actually lowering coupling.

pymodularity-0.2.0/README.md

@@ -0,0 +1,73 @@
+# pymodularity
+
+Formerly published as `underscope`.
+
+The underscore's position in a Python import path sets that import's scope — Rust's `pub(super)`/`pub(crate)`, applied to PEP 8 underscores.
+
+`pymodularity` draws a repo's real Python imports as mermaid diagrams, checks them against conventions derived from the code itself (no allow-list to maintain), and reports which files and directories carry the most structural coupling. It needs only the standard library to analyze your code — no runtime dependencies. `check`'s dependency-declaration rule additionally needs `uv` on PATH (see below).
+
+## Install and run
+
+```bash
+uvx pymodularity check .
+uvx pymodularity graph . --out docs/imports
+uvx pymodularity metrics .
+```
+
+Or, inside a project: `uv add --dev pymodularity` and run `pymodularity ...` in that project's venv.
+
+## The rules `check` enforces
+
+Given this tree:
+
+```
+shop/
+  __init__.py
+  billing/
+    __init__.py
+    invoice.py          # from shop.billing._pricing import compute_total
+    _pricing.py          # def compute_total(): ...
+  catalog/
+    __init__.py
+    listing.py           # from shop.billing._pricing import compute_total  <- finding
+```
+
+- **No import cycle**, at any directory level: between files, and between directories at every depth. Imports under `if TYPE_CHECKING:` and inside function bodies count. There is no baseline — an existing cycle fails too.
+- **A private item stays visible only to its owner and the owner's descendants** (Go's `internal/`, applied as Rust's visibility rule to PEP 8 underscores):
+  - a private module — a file, or a path component, named `_x` (single leading underscore, not a dunder) — belongs to the directory holding it; only files under that directory may import it, across package boundaries;
+  - a private name imported via `from m import _x` belongs to `m`; if `m` is a single file, no other file may import `_x`, not even a sibling in the same directory;
+  - if `m` is a package (an `__init__.py` or a namespace package directory), `_x` belongs to that directory, and files under it may import it.
+  - a parent never reaches into a child's private items, and neither do siblings.
+  - `shop/billing/invoice.py` above is allowed (it's under `shop/billing`, `_pricing`'s owner); `shop/catalog/listing.py` is a finding.
+  - the attribute form (`import shop.billing._pricing as p; p.compute_total`) is out of scope here — ruff's `SLF001` already flags it.
+
+`pymodularity check .` exits 1 on any finding and prints, per finding, the importing file, the target, and the directory or file that owns it.
+
+- **Dependency declarations are correct**, on by default, skipped with `check --no-deps`: for each package root (a directory with a `pyproject.toml` `[project]` table), runs [deptry](https://github.com/fpgmaas/deptry) (`uv run --directory <pkg> --with deptry==<pinned version> --frozen deptry . --json-output <tmp>`, a nested package root excluded from its parent's scan via `--extend-exclude`) and reports its findings (unused, missing, and transitive dependencies) the same way as the other rules. A package is skipped, not scanned, if it declares no runtime dependencies, or has no `uv.lock` of its own. This rule needs `uv` on PATH — `check` exits 2 with an error if it is missing, never a silent skip. The first run creates a `.venv` inside each scanned package and downloads its dependencies; later runs reuse it.
+
+- **Structure limits**, fixed constants, no config, no baseline — every one of these is a finding regardless of how long it's been true:
+  - a scanned file has at most 500 physical lines.
+  - a directory has at most 10 entries, where an entry is a scanned `.py` file directly in it or a subdirectory holding scanned `.py` files, transitively; `__init__.py` and `__main__.py` don't count as entries (they're still scanned and still count toward the other limits).
+  - a package root (the same `pyproject.toml` `[project]`-table directory the privacy and dependency rules anchor on) has at most 100 scanned files, each file counted against its nearest (innermost) package root.
+  - a file has at most 15 public top-level names (no leading `_`): `def`/`async def`/`class`, a plain or annotated assignment target (including tuple-unpacking), or a `type X = ...` alias, at top level or nested in a top-level `if`/`try` block (including `elif`/`else`, `except` handlers, `finally`). Imports never count. A top-level function (not a class — `@dataclass` sits on most models) a decorator registers doesn't count either: FastAPI, Typer/Click, Dagster, pytest and the like derive part of their contract (route `operationId`, CLI command name, asset key, fixture name) from the function's name, so counting it toward the width cap would pressure someone into renaming or restructuring around a name the framework, not this tool, owns. Any decorator counts — there's no list of framework names.
+
+## The 3 subcommands
+
+- `pymodularity check <repo> [--no-deps]` — run all four rules above, print findings, exit 1 on any finding (`--no-deps` skips the dependency-declaration rule).
+- `pymodularity graph <repo> --out DIR [--html]` — write one mermaid view per directory under `DIR`: `index.md` everywhere, plus a clickable `index.html` per view with `--html` (needs network access in the browser to load mermaid from a CDN).
+- `pymodularity metrics <repo>` — print a coupling report to stdout: reach (dependents/dependencies, transitive) and a `score` per file and per directory; interface width (names other code imports from a unit); exposure share (how much of what a file defines actually gets used elsewhere); entry files (how much of a directory outside code actually reaches into); misplaced files (files whose closest partners sit mostly in another directory). Always exits 0 — a report, never a gate.
+
+## Blind spots
+
+`pymodularity` shows import coupling only, a lower bound on logical coupling ("if A changes, must B?"). Coupling that bypasses Python imports stays invisible:
+
+- HTTP APIs, shared database schemas and tables, config keys and env vars, message and file formats, string-keyed registries, runtime `sys.path` edits.
+- Two files with no edge here can still force each other's edits. **Never read a missing edge as independence.**
+
+Other limits:
+
+- a `warning: ambiguous import` line (printed to stderr) means several files in the repo match one import; no edge is drawn for it.
+- an import that only resolves through a runtime `sys.path` edit is matched by file path, which can pick the wrong file.
+- a third-party name that happens to equal a package folder elsewhere in the repo draws a false edge.
+- test directories (`tests/`, `test/`) and test files (`test_*.py`, `*_test.py`, `conftest.py`) are always skipped, no flag — a test importing a sibling would otherwise draw a production dependency that production never has.
+- `metrics` is a report on numbers that keep moving even on a repo that passes `check` clean; gating on it rewards gaming the number (for example, replacing an import with a string-keyed registry) instead of actually lowering coupling.

pymodularity-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "pymodularity"
+version = "0.2.0"
+description = "See and check a repo's real Python imports: a privacy convention on PEP 8 underscores, an import-cycle ban, and a coupling report, all derived from the code."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+
+[[project.authors]]
+name = "Tilo Himmelsbach"
+
+[project.urls]
+Homepage = "https://github.com/dertilo/pymodularity"
+Repository = "https://github.com/dertilo/pymodularity"
+Issues = "https://github.com/dertilo/pymodularity/issues"
+
+[project.scripts]
+pymodularity = "pymodularity.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "basedpyright",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.7,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 90
+target-version = "py311"
+
+[tool.basedpyright]
+include = [
+    "src",
+    "tests",
+]
+pythonVersion = "3.11"
+reportUnusedCallResult = false
+reportAny = false

pymodularity-0.2.0/pyproject.toml.orig

@@ -0,0 +1,34 @@
+[project]
+name = "pymodularity"
+version = "0.2.0"
+description = "See and check a repo's real Python imports: a privacy convention on PEP 8 underscores, an import-cycle ban, and a coupling report, all derived from the code."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Tilo Himmelsbach" }]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/dertilo/pymodularity"
+Repository = "https://github.com/dertilo/pymodularity"
+Issues = "https://github.com/dertilo/pymodularity/issues"
+
+[project.scripts]
+pymodularity = "pymodularity.cli:main"
+
+[dependency-groups]
+dev = ["pytest", "ruff", "basedpyright"]
+
+[build-system]
+requires = ["uv_build>=0.10.7,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 90
+target-version = "py311"
+
+[tool.basedpyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+reportUnusedCallResult = false
+reportAny = false

pymodularity-0.2.0/src/pymodularity/__init__.py

@@ -0,0 +1,5 @@
+"""pymodularity: see and check a repo's real Python imports."""
+
+from pymodularity.cli import __version__
+
+__all__ = ["__version__"]

pymodularity-0.2.0/src/pymodularity/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for `python -m pymodularity`."""
+
+from pymodularity.cli import main
+
+if __name__ == "__main__":
+    # nosemgrep: no-raise-outside-boundary  # boundary: CLI entry point, the process exit boundary
+    raise SystemExit(main())

pymodularity-0.2.0/src/pymodularity/_check.py

@@ -0,0 +1,161 @@
+"""The privacy rules `pymodularity check` enforces (the cycle ban itself
+lives in `_cycles`), and the printing of all check findings."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from pymodularity._cycles import CycleFinding
+from pymodularity._parse.graph import EdgeNames
+from pymodularity._parse.names import is_private_name, module_comp
+
+
+def _owning_package_root(rel: Path, package_roots: Sequence[Path]) -> Path:
+    for root in package_roots:
+        if root != Path(".") and rel.is_relative_to(root):
+            return root
+    return Path(".")
+
+
+def _visibility_scope(rel: Path, package_roots: Sequence[Path]) -> Path:
+    """The directory whose subtree may import rel: the private owner of its
+    innermost private file/dir component, or the repo root (everyone) if rel
+    has no private component (relative to its package root). Several private
+    parts each restrict; the narrowest (innermost) one wins."""
+    root = _owning_package_root(rel, package_roots)
+    sub = rel.relative_to(root) if root != Path(".") else rel
+    comp = module_comp(sub.parts)
+    for k in range(len(comp) - 1, -1, -1):
+        if is_private_name(comp[k]):
+            return root / Path(*comp[:k]) if comp[:k] else root
+    return Path(".")
+
+
+@dataclass(frozen=True, slots=True)
+class _PrivacyViolation:
+    """An import that reaches a module private to a directory it is not
+    under."""
+
+    importer: Path
+    target: Path
+    owner: Path
+
+
+def find_privacy_violations(
+    edge_names: EdgeNames, package_roots: Sequence[Path]
+) -> tuple[_PrivacyViolation, ...]:
+    violations: list[_PrivacyViolation] = []
+    scope_cache: dict[Path, Path] = {}
+
+    def scope_of(rel: Path) -> Path:
+        if rel not in scope_cache:
+            scope_cache[rel] = _visibility_scope(rel, package_roots)
+        return scope_cache[rel]
+
+    for importer_rel, target_rel in edge_names:
+        scope = scope_of(target_rel)
+        if importer_rel.is_relative_to(scope):
+            continue
+        violations.append(_PrivacyViolation(importer_rel, target_rel, scope))
+
+    violations.sort(key=lambda v: (str(v.importer), str(v.target)))
+    return tuple(violations)
+
+
+@dataclass(frozen=True, slots=True)
+class _NameOwner:
+    """Where a name imported `from target_rel import _x` is private to."""
+
+    owner: Path
+    owner_is_dir: bool
+
+
+def _name_owner(target_rel: Path) -> _NameOwner:
+    """A package (`__init__.py` file, or a namespace package directory with
+    no `__init__.py`) makes its names visible to files under that directory;
+    a single module file makes its names visible to no other file at all."""
+    if target_rel.name == "__init__.py":
+        return _NameOwner(target_rel.parent, True)
+    if target_rel.suffix != ".py":
+        return _NameOwner(target_rel, True)
+    return _NameOwner(target_rel, False)
+
+
+@dataclass(frozen=True, slots=True)
+class _NameViolation:
+    """An import of a private name (`from m import _x`) that reaches
+    outside the directory (package) or file that name is private to."""
+
+    importer: Path
+    target: Path
+    name: str
+    owner: Path
+    owner_is_dir: bool
+
+
+def find_name_violations(edge_names: EdgeNames) -> tuple[_NameViolation, ...]:
+    violations: list[_NameViolation] = []
+    for (importer_rel, target_rel), names in edge_names.items():
+        for name in names:
+            if not is_private_name(name):
+                continue
+            owner_info = _name_owner(target_rel)
+            if owner_info.owner_is_dir and importer_rel.is_relative_to(owner_info.owner):
+                continue
+            violations.append(
+                _NameViolation(
+                    importer_rel,
+                    target_rel,
+                    name,
+                    owner_info.owner,
+                    owner_info.owner_is_dir,
+                )
+            )
+    violations.sort(key=lambda v: (str(v.importer), str(v.target), v.name))
+    return tuple(violations)
+
+
+def print_check_findings(
+    cycle_findings: Sequence[CycleFinding],
+    distinct_file_cycles: int,
+    privacy_violations: Sequence[_PrivacyViolation],
+    name_violations: Sequence[_NameViolation],
+) -> bool:
+    """Prints findings, returns True if any finding exists."""
+    any_finding = (
+        bool(cycle_findings) or bool(privacy_violations) or bool(name_violations)
+    )
+
+    print(
+        f"## Cycles: {len(cycle_findings)} in directory views, "
+        + f"{distinct_file_cycles} at file level"
+    )
+    if cycle_findings:
+        print(
+            "(a directory view merges each child directory into one node, "
+            + "so a view's cycles need not match the file-level cycles: "
+            + "2 directories can import each other with no file-level cycle, "
+            + "and several file-level cycles can merge into one)"
+        )
+    for cf in cycle_findings:
+        directory_label = "repo root" if cf.directory == Path(".") else str(cf.directory)
+        print(f"- {directory_label}: {len(cf.members)} nodes")
+        print(f"  members: {', '.join(str(m) for m in cf.members)}")
+        print(f"  example: {' -> '.join(str(n) for n in cf.example)}")
+        for edge in cf.example_files:
+            print(f"    {edge.importer} -> {edge.target}")
+    print()
+
+    total_private = len(privacy_violations) + len(name_violations)
+    print(f"## Private-item violations: {total_private} finding(s)")
+    for v in privacy_violations:
+        print(f"- {v.importer} -> {v.target}: allowed only inside {v.owner}")
+    for nv in name_violations:
+        scope = "directory" if nv.owner_is_dir else "file"
+        print(
+            f"- {nv.importer} -> {nv.target}: name {nv.name} private to "
+            + f"{scope} {nv.owner}"
+        )
+    print()
+
+    return any_finding

pymodularity-0.2.0/src/pymodularity/_cycles.py

@@ -0,0 +1,244 @@
+"""Tarjan SCC, on the directory view edges `_view_edges.build_view`
+produces (feeding both `check`'s cycle ban and the Cycles section of
+`graph`'s views), and the file-level cycle count on the raw file graph."""
+
+import itertools
+from collections.abc import Mapping, Sequence
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from pathlib import Path
+
+from pymodularity._parse.graph import EdgeKey, EdgeNames
+from pymodularity._view_edges import PairEdges, build_view, compute_inside_nodes
+
+
+@dataclass(frozen=True, slots=True)
+class _MutualPair:
+    """Two SCC members with edges in both directions, and each direction's
+    distinct (importer file, target file) pair count."""
+
+    a: Path
+    b: Path
+    a_to_b_files: int
+    b_to_a_files: int
+
+
+@dataclass(frozen=True, slots=True)
+class _SccEdge:
+    """One directed edge inside a strongly connected component."""
+
+    src: Path
+    tgt: Path
+    files: int
+
+
+@dataclass(frozen=True, slots=True)
+class _Scc:
+    """A strongly connected component (size >= 2) among a view's inside
+    children, on the edges the view draws."""
+
+    members: tuple[Path, ...]
+    mutual_pairs: tuple[_MutualPair, ...]
+    edges: tuple[_SccEdge, ...]
+
+
+def _tarjan_sccs(
+    nodes: AbstractSet[Path], adj: Mapping[Path, AbstractSet[Path]]
+) -> tuple[tuple[Path, ...], ...]:
+    """Iterative Tarjan (explicit stack, no recursion) so large views can't
+    hit the recursion limit."""
+    counter = 0
+    index: dict[Path, int] = {}
+    lowlink: dict[Path, int] = {}
+    on_stack: dict[Path, bool] = {}
+    stack: list[Path] = []
+    sccs: list[list[Path]] = []
+
+    for start in sorted(nodes, key=str):
+        if start in index:
+            continue
+        work: list[tuple[Path, list[Path], int]] = [
+            (start, sorted(adj.get(start, ()), key=str), 0)
+        ]
+        index[start] = lowlink[start] = counter
+        counter += 1
+        stack.append(start)
+        on_stack[start] = True
+
+        while work:
+            v, children, pos = work[-1]
+            advanced = False
+            while pos < len(children):
+                w = children[pos]
+                pos += 1
+                if w not in index:
+                    index[w] = lowlink[w] = counter
+                    counter += 1
+                    stack.append(w)
+                    on_stack[w] = True
+                    work[-1] = (v, children, pos)
+                    work.append((w, sorted(adj.get(w, ()), key=str), 0))
+                    advanced = True
+                    break
+                if on_stack.get(w, False):
+                    lowlink[v] = min(lowlink[v], index[w])
+            if advanced:
+                continue
+            work[-1] = (v, children, pos)
+            work.pop()
+            if work:
+                parent = work[-1][0]
+                lowlink[parent] = min(lowlink[parent], lowlink[v])
+            if lowlink[v] == index[v]:
+                comp: list[Path] = []
+                while True:
+                    w = stack.pop()
+                    on_stack[w] = False
+                    comp.append(w)
+                    if w == v:
+                        break
+                sccs.append(comp)
+    return tuple(tuple(comp) for comp in sccs)
+
+
+def compute_sccs(
+    inside_nodes: AbstractSet[Path], pair_edges: PairEdges
+) -> tuple[_Scc, ...]:
+    adj: dict[Path, set[Path]] = {n: set() for n in inside_nodes}
+    file_counts: dict[EdgeKey, int] = {}
+    for (src, tgt), file_pairs in pair_edges.items():
+        if src in inside_nodes and tgt in inside_nodes:
+            adj[src].add(tgt)
+            file_counts[(src, tgt)] = len(file_pairs)
+
+    raw = [comp for comp in _tarjan_sccs(inside_nodes, adj) if len(comp) >= 2]
+
+    result: list[_Scc] = []
+    for comp in raw:
+        members = sorted(comp, key=str)
+        member_set = set(comp)
+        mutual_pairs: list[_MutualPair] = []
+        seen: set[frozenset[Path]] = set()
+        for a in members:
+            for b in members:
+                if a == b:
+                    continue
+                if (a, b) in file_counts and (b, a) in file_counts:
+                    key = frozenset((a, b))
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    mutual_pairs.append(
+                        _MutualPair(a, b, file_counts[(a, b)], file_counts[(b, a)])
+                    )
+        mutual_pairs.sort(key=lambda mp: (str(mp.a), str(mp.b)))
+        edges = sorted(
+            (
+                _SccEdge(s, t, c)
+                for (s, t), c in file_counts.items()
+                if s in member_set and t in member_set
+            ),
+            key=lambda e: (str(e.src), str(e.tgt)),
+        )
+        result.append(_Scc(tuple(members), tuple(mutual_pairs), tuple(edges)))
+
+    result.sort(key=lambda scc: (-len(scc.members), str(scc.members[0])))
+    return tuple(result)
+
+
+def _find_example_cycle(
+    members: Sequence[Path], pair_edges: PairEdges
+) -> tuple[Path, ...]:
+    """One concrete node loop (first == last) through the SCC, via DFS."""
+    member_set = set(members)
+    adj: dict[Path, list[Path]] = {m: [] for m in members}
+    for src, tgt in pair_edges:
+        if src in member_set and tgt in member_set and src != tgt:
+            adj[src].append(tgt)
+    for neighbors in adj.values():
+        neighbors.sort(key=str)
+
+    start = members[0]
+    stack: list[Path] = [start]
+    visited: set[Path] = {start}
+
+    def dfs(node: Path) -> bool:
+        for nxt in adj[node]:
+            if nxt == start and len(stack) > 1:
+                return True
+            if nxt not in visited:
+                visited.add(nxt)
+                stack.append(nxt)
+                if dfs(nxt):
+                    return True
+                stack.pop()
+        return False
+
+    # an SCC guarantees a loop through start, so dfs always finds one
+    dfs(start)
+    return (*stack, start)
+
+
+@dataclass(frozen=True, slots=True)
+class _FileEdge:
+    """One concrete (importer file, target file) import edge."""
+
+    importer: Path
+    target: Path
+
+
+def _example_file_edges(
+    example: Sequence[Path], pair_edges: PairEdges
+) -> tuple[_FileEdge, ...]:
+    out: list[_FileEdge] = []
+    for a, b in itertools.pairwise(example):
+        file_pairs = pair_edges.get((a, b))
+        if file_pairs:
+            best = min(file_pairs, key=lambda p: (str(p[0]), str(p[1])))
+            out.append(_FileEdge(best[0], best[1]))
+    return tuple(out)
+
+
+@dataclass(frozen=True, slots=True)
+class CycleFinding:
+    """One SCC (size >= 2) found in one directory's view, with a concrete
+    example loop through file-level edges."""
+
+    directory: Path
+    members: tuple[Path, ...]
+    example: tuple[Path, ...]
+    example_files: tuple[_FileEdge, ...]
+
+
+def _find_cycle_findings(
+    directory: Path, inside_nodes: AbstractSet[Path], pair_edges: PairEdges
+) -> tuple[CycleFinding, ...]:
+    findings: list[CycleFinding] = []
+    for scc in compute_sccs(inside_nodes, pair_edges):
+        example = _find_example_cycle(scc.members, pair_edges)
+        findings.append(
+            CycleFinding(
+                directory, scc.members, example, _example_file_edges(example, pair_edges)
+            )
+        )
+    return tuple(findings)
+
+
+def count_file_level_cycles(adj: Mapping[Path, AbstractSet[Path]]) -> int:
+    """Distinct cycles on the raw file-level graph, ignoring any directory
+    view's aggregation -- the number of genuinely separate root causes."""
+    sccs = _tarjan_sccs(set(adj), adj)
+    return sum(1 for comp in sccs if len(comp) >= 2)
+
+
+def find_all_cycle_findings(
+    dirs_with_py: AbstractSet[Path], edge_names: EdgeNames
+) -> tuple[CycleFinding, ...]:
+    """The cycle ban `check` enforces: every directory's view, scanned for
+    SCCs (size >= 2) among its inside children."""
+    findings: list[CycleFinding] = []
+    for directory in sorted(dirs_with_py, key=str):
+        pair_edges = build_view(directory, edge_names)
+        inside_nodes = compute_inside_nodes(directory, pair_edges)
+        findings.extend(_find_cycle_findings(directory, inside_nodes, pair_edges))
+    return tuple(findings)