pymodularity 0.2.0__py3-none-any.whl

pymodularity/_parse/graph.py

@@ -0,0 +1,334 @@
+"""File discovery and file-level edge collection: build the whole-repo
+Python import graph with ast (stdlib only), driving `_resolve`'s index and
+resolution functions through one ast walk per file, plus the
+`build_graph` entry point every subcommand calls. `EdgeKey`/`EdgeNames`,
+the file-level edge types every downstream module shares, live here too."""
+
+import ast
+import os
+import sys
+from collections.abc import Mapping, Sequence
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from pathlib import Path
+
+from pymodularity._parse._resolve import (
+    Ambiguous,
+    Index,
+    ModuleCandidates,
+    Resolved,
+    SuffixIndex,
+    build_index,
+    path_components,
+    resolve_exact,
+    resolve_relative,
+)
+
+# (importer_rel, target_rel) file-level import edge
+EdgeKey = tuple[Path, Path]
+EdgeNames = Mapping[EdgeKey, frozenset[str]]
+# an ambiguous-import warning: the importing file and its candidate targets
+_AmbiguityWarning = tuple[Path, tuple[Path, ...]]
+# a resolved absolute/relative import: target file, imported names (if any)
+_ResolvedImport = tuple[Path, frozenset[str]]
+
+_SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".venv",
+        "venv",
+        "node_modules",
+        "__pycache__",
+        "build",
+        "dist",
+        "tests",
+        "test",
+    }
+)
+
+
+def should_skip_dir(name: str) -> bool:
+    return name in _SKIP_DIRS or name.startswith(".")
+
+
+def _is_test_file(name: str) -> bool:
+    return name == "conftest.py" or name.startswith("test_") or name.endswith("_test.py")
+
+
+def _find_py_files(repo: Path) -> tuple[Path, ...]:
+    files: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(repo):
+        dirnames[:] = [d for d in dirnames if not should_skip_dir(d)]
+        for fn in filenames:
+            if fn.endswith(".py") and not _is_test_file(fn):
+                files.append(Path(dirpath) / fn)
+    return tuple(files)
+
+
+def _assign_target_names(target: ast.expr) -> tuple[str, ...]:
+    """Names bound by one assignment target, recursing into tuple/list
+    unpacking (including a starred element)."""
+    if isinstance(target, ast.Name):
+        return (target.id,)
+    if isinstance(target, (ast.Tuple, ast.List)):
+        names: list[str] = []
+        for elt in target.elts:
+            inner = elt.value if isinstance(elt, ast.Starred) else elt
+            names.extend(_assign_target_names(inner))
+        return tuple(names)
+    return ()
+
+
+def _names_from_stmt(stmt: ast.stmt) -> tuple[str, ...]:
+    """Names one statement defines: def/async def/class, plain or annotated
+    assignment (including tuple-unpacking), `type X = ...`, or the same
+    recursively inside an `if`/`try` block's branches (body, elif/else,
+    except handlers, finally). Imports never count."""
+    if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        return (stmt.name,)
+    if isinstance(stmt, ast.Assign):
+        names: list[str] = []
+        for target in stmt.targets:
+            names.extend(_assign_target_names(target))
+        return tuple(names)
+    if isinstance(stmt, ast.AnnAssign):
+        return _assign_target_names(stmt.target)
+    if type(stmt).__name__ == "TypeAlias":
+        # `type X = ...` (py3.12+); accessed by name, not ast.TypeAlias,
+        # since this project's declared pythonVersion (3.11) doesn't know
+        # that attribute, and ast.parse itself only ever yields this node
+        # when running under a 3.12+ interpreter.
+        name_node: object = getattr(stmt, "name", None)
+        return (name_node.id,) if isinstance(name_node, ast.Name) else ()
+    if isinstance(stmt, ast.If):
+        return tuple(n for s in (*stmt.body, *stmt.orelse) for n in _names_from_stmt(s))
+    if isinstance(stmt, ast.Try):
+        branches = (*stmt.body, *stmt.orelse, *stmt.finalbody)
+        names = [n for s in branches for n in _names_from_stmt(s)]
+        for handler in stmt.handlers:
+            names.extend(n for s in handler.body for n in _names_from_stmt(s))
+        return tuple(names)
+    return ()
+
+
+def _top_level_defined_names(tree: ast.Module) -> frozenset[str]:
+    """Names this module defines at top level: def, async def, class, plain
+    or annotated assignment (including tuple-unpacking), `type X = ...`, and
+    the same nested in a top-level `if`/`try` block. Imports don't count."""
+    defined: set[str] = set()
+    for stmt in tree.body:
+        defined.update(_names_from_stmt(stmt))
+    return frozenset(defined)
+
+
+def _registered_names_from_stmt(stmt: ast.stmt) -> tuple[str, ...]:
+    """Names of top-level functions (not classes) a decorator registers --
+    FastAPI routes, Typer/Click commands, Dagster assets, pytest fixtures --
+    including the same nested in a top-level `if`/`try` block. Any
+    decorator counts; there's no list of framework names."""
+    if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        return (stmt.name,) if stmt.decorator_list else ()
+    if isinstance(stmt, ast.If):
+        return tuple(
+            n for s in (*stmt.body, *stmt.orelse) for n in _registered_names_from_stmt(s)
+        )
+    if isinstance(stmt, ast.Try):
+        branches = (*stmt.body, *stmt.orelse, *stmt.finalbody)
+        names = [n for s in branches for n in _registered_names_from_stmt(s)]
+        for handler in stmt.handlers:
+            names.extend(n for s in handler.body for n in _registered_names_from_stmt(s))
+        return tuple(names)
+    return ()
+
+
+def _top_level_registered_names(tree: ast.Module) -> frozenset[str]:
+    """Names this module's top-level decorated functions define (not
+    classes -- `@dataclass` sits on most models), including the same
+    nested in a top-level `if`/`try` block."""
+    registered: set[str] = set()
+    for stmt in tree.body:
+        registered.update(_registered_names_from_stmt(stmt))
+    return frozenset(registered)
+
+
+@dataclass(frozen=True, slots=True)
+class _CollectedEdges:
+    """What one parse of a repo's files collects: file-level import edges
+    (with their imported names), the ambiguous-import warnings raised along
+    the way, each file's top-level defined names, and each file's
+    decorator-registered names (a subset of defined_names)."""
+
+    edge_names: EdgeNames
+    warnings: tuple[_AmbiguityWarning, ...]
+    defined_names: Mapping[Path, frozenset[str]]
+    registered_names: Mapping[Path, frozenset[str]]
+
+
+def _collect_edges(
+    repo: Path,
+    py_files: Sequence[Path],
+    module_candidates: ModuleCandidates,
+    suffix_index: SuffixIndex,
+) -> _CollectedEdges:
+    # (importer_rel, target_rel) -> set of imported names (empty = no names,
+    # e.g. a plain "import x.y" or a "from a import b" where b is itself the
+    # resolved submodule rather than a name defined inside it)
+    edge_names: dict[EdgeKey, set[str]] = {}
+    warnings: list[_AmbiguityWarning] = []
+    defined_names: dict[Path, frozenset[str]] = {}
+    registered_names: dict[Path, frozenset[str]] = {}
+    for f in sorted(py_files):
+        rel = f.relative_to(repo)
+        try:
+            text = f.read_text(encoding="utf-8")
+            tree = ast.parse(text, filename=str(f))
+        except (SyntaxError, UnicodeDecodeError) as e:
+            print(f"warning: skipping {rel}: {e}", file=sys.stderr)
+            continue
+
+        defined_names[rel] = _top_level_defined_names(tree)
+        registered_names[rel] = _top_level_registered_names(tree)
+        importer_dir_parts = path_components(rel.parent)
+        targets: list[_ResolvedImport] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    dotted = alias.name.split(".")
+                    res = resolve_exact(
+                        dotted, importer_dir_parts, suffix_index, module_candidates
+                    )
+                    if isinstance(res, Ambiguous):
+                        warnings.append((rel, res.candidates))
+                    elif isinstance(res, Resolved):
+                        targets.append((res.path, frozenset()))
+            elif isinstance(node, ast.ImportFrom):
+                if node.level and node.level > 0:
+                    requests: list[tuple[tuple[str, ...], frozenset[str]]]
+                    if node.module:
+                        requests = [
+                            (
+                                tuple(node.module.split(".")),
+                                frozenset(alias.name for alias in node.names),
+                            )
+                        ]
+                    else:
+                        requests = [((alias.name,), frozenset()) for alias in node.names]
+                    for module_parts, names_here in requests:
+                        res = resolve_relative(
+                            module_parts,
+                            node.level,
+                            importer_dir_parts,
+                            module_candidates,
+                        )
+                        if isinstance(res, Resolved):
+                            targets.append((res.path, names_here))
+                else:
+                    module_parts = node.module.split(".") if node.module else []
+                    for alias in node.names:
+                        res = resolve_exact(
+                            module_parts + [alias.name],
+                            importer_dir_parts,
+                            suffix_index,
+                            module_candidates,
+                        )
+                        if isinstance(res, Ambiguous):
+                            warnings.append((rel, res.candidates))
+                            continue
+                        if isinstance(res, Resolved):
+                            targets.append((res.path, frozenset()))
+                            continue
+                        res = resolve_exact(
+                            module_parts,
+                            importer_dir_parts,
+                            suffix_index,
+                            module_candidates,
+                        )
+                        if isinstance(res, Ambiguous):
+                            warnings.append((rel, res.candidates))
+                        elif isinstance(res, Resolved):
+                            targets.append((res.path, frozenset({alias.name})))
+
+        for t, names_here in targets:
+            trel = t.relative_to(repo)
+            if trel == rel:
+                continue
+            edge_names.setdefault((rel, trel), set()).update(names_here)
+
+    frozen_edge_names: EdgeNames = {k: frozenset(v) for k, v in edge_names.items()}
+    return _CollectedEdges(
+        frozen_edge_names,
+        tuple(warnings),
+        defined_names,
+        registered_names,
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class _FileGraph:
+    """The raw file-level import graph: forward adjacency and its reverse."""
+
+    adj: Mapping[Path, frozenset[Path]]
+    radj: Mapping[Path, frozenset[Path]]
+
+
+def _build_file_graph(nodes: AbstractSet[Path], edge_names: EdgeNames) -> _FileGraph:
+    """Same edges `check`'s cycle rule uses: no self-edges (_collect_edges
+    already drops those), duplicates already collapsed by edge_names' dict
+    keys."""
+    adj: dict[Path, set[Path]] = {n: set() for n in nodes}
+    radj: dict[Path, set[Path]] = {n: set() for n in nodes}
+    for importer_rel, target_rel in edge_names:
+        if importer_rel in adj and target_rel in adj and importer_rel != target_rel:
+            adj[importer_rel].add(target_rel)
+            radj[target_rel].add(importer_rel)
+    frozen_adj = {n: frozenset(s) for n, s in adj.items()}
+    frozen_radj = {n: frozenset(s) for n, s in radj.items()}
+    return _FileGraph(frozen_adj, frozen_radj)
+
+
+@dataclass(frozen=True, slots=True)
+class _RepoGraph:
+    """Every structure every subcommand needs, built once from one parse of
+    `repo`: the file list, the directories holding Python code, the
+    file-level import edges (and their imported names), each file's
+    top-level defined names, each file's decorator-registered names, and
+    the forward/reverse file adjacency."""
+
+    py_files: tuple[Path, ...]
+    dirs_with_py: frozenset[Path]
+    edge_names: EdgeNames
+    defined_names: Mapping[Path, frozenset[str]]
+    registered_names: Mapping[Path, frozenset[str]]
+    adj: Mapping[Path, frozenset[Path]]
+    radj: Mapping[Path, frozenset[Path]]
+
+
+def build_graph(repo: Path) -> _RepoGraph:
+    """Parses `repo` once and builds every structure every subcommand needs.
+    Prints ambiguous-import warnings to stderr along the way. Reach and
+    file/directory scores are not computed here -- `check` never uses
+    them, so `graph` and `metrics` compute them in their own run_*
+    path."""
+    py_files = _find_py_files(repo)
+    idx: Index = build_index(repo, py_files)
+    collected = _collect_edges(repo, py_files, idx.module_candidates, idx.suffix_index)
+
+    for importer_rel, cands in collected.warnings:
+        cand_strs = ", ".join(str(c.relative_to(repo)) for c in cands)
+        print(
+            f"warning: ambiguous import in {importer_rel}: candidates {cand_strs}",
+            file=sys.stderr,
+        )
+
+    nodes = frozenset(f.relative_to(repo) for f in py_files)
+    file_graph = _build_file_graph(nodes, collected.edge_names)
+
+    return _RepoGraph(
+        py_files,
+        idx.dirs_with_py,
+        collected.edge_names,
+        collected.defined_names,
+        collected.registered_names,
+        file_graph.adj,
+        file_graph.radj,
+    )

pymodularity/_parse/names.py

@@ -0,0 +1,24 @@
+"""Name/module-path helpers shared by `_check` (privacy enforcement),
+`_summary` (rendering) and `_resolve`/`_graph` (import resolution)."""
+
+
+def module_comp(parts: tuple[str, ...]) -> tuple[str, ...]:
+    """Dotted components for a module path. `parts` is usually a .py file's
+    relative path, but a directory (namespace package, or a target equal to
+    its own package root) is also valid: empty parts stay empty, and a
+    directory component (no `.py` suffix) is kept as-is rather than having
+    3 chars stripped off."""
+    if not parts:
+        return ()
+    if parts[-1] == "__init__.py":
+        return parts[:-1]
+    if parts[-1].endswith(".py"):
+        return parts[:-1] + (parts[-1][:-3],)
+    return parts
+
+
+def is_private_name(name: str) -> bool:
+    """A name private by Rust's convention, ported to PEP 8 underscores:
+    one leading underscore, not a dunder, not the bare `_` placeholder
+    name."""
+    return name.startswith("_") and not name.startswith("__") and name != "_"

pymodularity/_parse/packages.py

@@ -0,0 +1,32 @@
+"""Package-root discovery: directories whose pyproject.toml has a
+[project] table, used by `_check` (the privacy rule's package-root anchor)
+and `_deps` (the dependency-declaration rule's per-package scan unit)."""
+
+import os
+import tomllib
+from pathlib import Path
+
+from pymodularity._parse.graph import should_skip_dir
+
+
+def _has_project_table(pyproject: Path) -> bool:
+    try:
+        with pyproject.open("rb") as f:
+            data = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError):
+        return False
+    return "project" in data
+
+
+def find_package_roots(repo: Path) -> tuple[Path, ...]:
+    """Directories (relative to repo) whose pyproject.toml has a [project]
+    table, used only to anchor the privacy rule's "package root". Sorted
+    deepest-first so the closest ancestor is found first."""
+    roots: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(repo):
+        dirnames[:] = [d for d in dirnames if not should_skip_dir(d)]
+        if "pyproject.toml" in filenames and _has_project_table(
+            Path(dirpath) / "pyproject.toml"
+        ):
+            roots.append(Path(dirpath).relative_to(repo))
+    return tuple(sorted(roots, key=lambda p: len(p.parts), reverse=True))

pymodularity/_scores.py

@@ -0,0 +1,135 @@
+"""Reach (transitive dependents/dependencies) and the file/directory
+scores derived from it: `compute_scores`, the shared first step `graph`,
+`metrics` and the view summary all build on."""
+
+from collections.abc import Mapping
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _reachable_set(start: Path, adj: Mapping[Path, AbstractSet[Path]]) -> frozenset[Path]:
+    """Every other node `start` can reach, following `adj` (BFS/DFS, order
+    doesn't matter); `start` itself never counts even inside a cycle back
+    to itself."""
+    seen: set[Path] = set()
+    stack = [start]
+    while stack:
+        node = stack.pop()
+        for nxt in adj.get(node, ()):
+            if nxt != start and nxt not in seen:
+                seen.add(nxt)
+                stack.append(nxt)
+    return frozenset(seen)
+
+
+@dataclass(frozen=True, slots=True)
+class _Reach:
+    """Per file: the set of dependents (other files with an import path to
+    it) and the set of dependencies (other files it has an import path
+    to), both transitive."""
+
+    dependents: Mapping[Path, frozenset[Path]]
+    dependencies: Mapping[Path, frozenset[Path]]
+
+
+def _compute_reach(
+    nodes: AbstractSet[Path],
+    adj: Mapping[Path, AbstractSet[Path]],
+    radj: Mapping[Path, AbstractSet[Path]],
+) -> _Reach:
+    dependents = {n: _reachable_set(n, radj) for n in nodes}
+    dependencies = {n: _reachable_set(n, adj) for n in nodes}
+    return _Reach(dependents, dependencies)
+
+
+@dataclass(frozen=True, slots=True)
+class FileScore:
+    """A file's score: dependents x dependencies, both transitive."""
+
+    path: Path
+    dependents: int
+    dependencies: int
+    score: int
+
+
+@dataclass(frozen=True, slots=True)
+class DirScore:
+    """A directory's score, measured across its own boundary, repo-wide:
+    `reach_in` is how many files outside the directory reach some file
+    inside it (transitively); `reach_out` is how many files outside it
+    are reached by some file inside it (transitively); score = in x out."""
+
+    path: Path
+    reach_in: int
+    reach_out: int
+    score: int
+
+
+def _compute_file_scores(
+    nodes: AbstractSet[Path],
+    dependents: Mapping[Path, AbstractSet[Path]],
+    dependencies: Mapping[Path, AbstractSet[Path]],
+) -> Mapping[Path, FileScore]:
+    scores: dict[Path, FileScore] = {}
+    for n in nodes:
+        d_in = len(dependents[n])
+        d_out = len(dependencies[n])
+        scores[n] = FileScore(n, d_in, d_out, d_in * d_out)
+    return scores
+
+
+@dataclass(frozen=True, slots=True)
+class _Scores:
+    """`graph` and `metrics`'s shared first step's result: file and
+    directory scores, computed from reach."""
+
+    file_scores: Mapping[Path, FileScore]
+    dir_scores: Mapping[Path, DirScore]
+
+
+def compute_scores(
+    dirs_with_py: AbstractSet[Path],
+    adj: Mapping[Path, AbstractSet[Path]],
+    radj: Mapping[Path, AbstractSet[Path]],
+) -> _Scores:
+    """`graph` and `metrics`'s shared first step: reach, then file and
+    directory scores from it."""
+    nodes = set(adj)
+    reach = _compute_reach(nodes, adj, radj)
+    file_scores = _compute_file_scores(nodes, reach.dependents, reach.dependencies)
+    dir_scores = _compute_dir_scores(dirs_with_py, reach.dependents, reach.dependencies)
+    return _Scores(file_scores, dir_scores)
+
+
+def ancestor_dirs(rel: Path) -> tuple[Path, ...]:
+    """The directory holding `rel` and every ancestor directory up to the
+    repo root ('.'), inclusive."""
+    out = [rel.parent]
+    while out[-1] != Path("."):
+        out.append(out[-1].parent)
+    return tuple(out)
+
+
+def _compute_dir_scores(
+    dirs_with_py: AbstractSet[Path],
+    dependents: Mapping[Path, AbstractSet[Path]],
+    dependencies: Mapping[Path, AbstractSet[Path]],
+) -> Mapping[Path, DirScore]:
+    dir_in: dict[Path, set[Path]] = {}
+    dir_out: dict[Path, set[Path]] = {}
+    for f, dep_set in dependents.items():
+        for d in ancestor_dirs(f):
+            if d in dirs_with_py:
+                dir_in.setdefault(d, set()).update(dep_set)
+    for f, dep_set in dependencies.items():
+        for d in ancestor_dirs(f):
+            if d in dirs_with_py:
+                dir_out.setdefault(d, set()).update(dep_set)
+
+    scores: dict[Path, DirScore] = {}
+    for d in dirs_with_py:
+        in_count = sum(1 for g in dir_in.get(d, set()) if not g.is_relative_to(d))
+        out_count = sum(1 for g in dir_out.get(d, set()) if not g.is_relative_to(d))
+        scores[d] = DirScore(d, in_count, out_count, in_count * out_count)
+    return scores

pymodularity/_structure.py

@@ -0,0 +1,168 @@
+"""The structure-limit rules (file size, directory fan-out, package size,
+public top-level-name count per file) `pymodularity check` enforces. All
+limits are fixed constants, no config, no baseline. Imported only by
+`cli`."""
+
+from collections.abc import Mapping, Sequence
+from collections.abc import Set as AbstractSet
+from dataclasses import dataclass
+from pathlib import Path
+
+from pymodularity._parse.packages import find_package_roots
+
+_MAX_FILE_LINES = 500
+_MAX_DIR_ENTRIES = 10
+_MAX_PACKAGE_FILES = 100
+_MAX_PUBLIC_NAMES = 15
+
+# __init__.py and __main__.py don't count as directory entries (rule 2);
+# every other scanned file counts fully for every rule.
+_STRUCTURAL_FILES = frozenset({"__init__.py", "__main__.py"})
+
+
+def _is_public(name: str) -> bool:
+    return not name.startswith("_")
+
+
+@dataclass(frozen=True, slots=True)
+class _FileTooLong:
+    file: Path
+    lines: int
+
+
+@dataclass(frozen=True, slots=True)
+class _DirTooManyEntries:
+    directory: Path
+    entries: int
+
+
+@dataclass(frozen=True, slots=True)
+class _PackageTooManyFiles:
+    package: Path
+    files: int
+
+
+@dataclass(frozen=True, slots=True)
+class _FileTooWide:
+    file: Path
+    names: int
+
+
+@dataclass(frozen=True, slots=True)
+class _StructureFindings:
+    too_long: tuple[_FileTooLong, ...] = ()
+    too_many_entries: tuple[_DirTooManyEntries, ...] = ()
+    package_too_big: tuple[_PackageTooManyFiles, ...] = ()
+    too_wide: tuple[_FileTooWide, ...] = ()
+
+
+def _is_direct_child(child: Path, parent: Path) -> bool:
+    if child == parent:
+        return False
+    if parent == Path("."):
+        return len(child.parts) == 1
+    return child.parent == parent
+
+
+def _find_file_size_violations(
+    repo: Path, py_files: Sequence[Path]
+) -> tuple[_FileTooLong, ...]:
+    out: list[_FileTooLong] = []
+    for f in py_files:
+        n = len(f.read_text(encoding="utf-8").splitlines())
+        if n > _MAX_FILE_LINES:
+            out.append(_FileTooLong(f.relative_to(repo), n))
+    out.sort(key=lambda v: str(v.file))
+    return tuple(out)
+
+
+def _find_dir_entry_violations(
+    dirs_with_py: AbstractSet[Path], py_files: Sequence[Path], repo: Path
+) -> tuple[_DirTooManyEntries, ...]:
+    rels = [f.relative_to(repo) for f in py_files]
+    out: list[_DirTooManyEntries] = []
+    for d in dirs_with_py:
+        file_entries = sum(
+            1 for r in rels if r.parent == d and r.name not in _STRUCTURAL_FILES
+        )
+        dir_entries = sum(1 for c in dirs_with_py if _is_direct_child(c, d))
+        total = file_entries + dir_entries
+        if total > _MAX_DIR_ENTRIES:
+            out.append(_DirTooManyEntries(d, total))
+    out.sort(key=lambda v: str(v.directory))
+    return tuple(out)
+
+
+def _owning_package(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 _find_package_size_violations(
+    repo: Path, py_files: Sequence[Path]
+) -> tuple[_PackageTooManyFiles, ...]:
+    package_roots = find_package_roots(repo)
+    counts: dict[Path, int] = {}
+    for f in py_files:
+        root = _owning_package(f.relative_to(repo), package_roots)
+        counts[root] = counts.get(root, 0) + 1
+    out = [
+        _PackageTooManyFiles(pkg, n)
+        for pkg, n in counts.items()
+        if n > _MAX_PACKAGE_FILES
+    ]
+    out.sort(key=lambda v: str(v.package))
+    return tuple(out)
+
+
+def _find_file_width_violations(
+    defined_names: Mapping[Path, frozenset[str]],
+    registered_names: Mapping[Path, frozenset[str]],
+) -> tuple[_FileTooWide, ...]:
+    out: list[_FileTooWide] = []
+    for f, names in defined_names.items():
+        registered = registered_names.get(f, frozenset())
+        public_count = sum(1 for n in names if _is_public(n) and n not in registered)
+        if public_count > _MAX_PUBLIC_NAMES:
+            out.append(_FileTooWide(f, public_count))
+    out.sort(key=lambda v: str(v.file))
+    return tuple(out)
+
+
+def find_structure_findings(
+    repo: Path,
+    py_files: Sequence[Path],
+    dirs_with_py: AbstractSet[Path],
+    defined_names: Mapping[Path, frozenset[str]],
+    registered_names: Mapping[Path, frozenset[str]],
+) -> _StructureFindings:
+    return _StructureFindings(
+        too_long=_find_file_size_violations(repo, py_files),
+        too_many_entries=_find_dir_entry_violations(dirs_with_py, py_files, repo),
+        package_too_big=_find_package_size_violations(repo, py_files),
+        too_wide=_find_file_width_violations(defined_names, registered_names),
+    )
+
+
+def print_structure_findings(findings: _StructureFindings) -> bool:
+    total = (
+        len(findings.too_long)
+        + len(findings.too_many_entries)
+        + len(findings.package_too_big)
+        + len(findings.too_wide)
+    )
+    print(f"## Structure limits: {total} finding(s)")
+    for v in findings.too_long:
+        print(f"- {v.file}: {v.lines} lines (limit {_MAX_FILE_LINES})")
+    for v in findings.too_many_entries:
+        label = "repo root" if v.directory == Path(".") else str(v.directory)
+        print(f"- {label}: {v.entries} entries (limit {_MAX_DIR_ENTRIES})")
+    for v in findings.package_too_big:
+        label = "repo root" if v.package == Path(".") else str(v.package)
+        print(f"- {label}: {v.files} files (limit {_MAX_PACKAGE_FILES})")
+    for v in findings.too_wide:
+        print(f"- {v.file}: {v.names} public names (limit {_MAX_PUBLIC_NAMES})")
+    print()
+    return total > 0