pymodularity 0.2.0__py3-none-any.whl

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/__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/_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/_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)

pymodularity/_deps.py

@@ -0,0 +1,258 @@
+"""The dependency-declaration rule `pymodularity check` enforces: shells out
+to deptry, pinned to one exact version, once per package root (a directory
+with a pyproject.toml [project] table found by `_parse.packages`), via
+`uv run --directory <pkg> --with deptry==<pin> --frozen deptry . --json-output
+<tmp>`. A package is skipped (not a failure) if it declares no runtime
+dependencies, or has no uv.lock of its own (uv run --frozen fails with exit
+2 and "Unable to find lockfile"). Any other deptry failure, or JSON that
+does not parse, is a finding-level failure. `uv` missing from PATH is a
+hard error (exit 2), never a silent skip.
+
+Imported only by `cli`; must not import `_check`, `_metrics`, `_scores` or
+`_views` (this rule is independent of the import-graph checks)."""
+
+import json
+import re
+import shutil
+import subprocess
+import tempfile
+import tomllib
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import cast
+
+from pymodularity._parse.packages import find_package_roots
+
+_DEPTRY_VERSION = "0.25.1"
+
+_NO_LOCKFILE_MARKER = "Unable to find lockfile"
+
+
+@dataclass(frozen=True, slots=True)
+class _KnownPosition:
+    line: int
+    column: int
+
+
+@dataclass(frozen=True, slots=True)
+class _UnknownPosition:
+    """deptry reports a finding with no file position (line/column null in
+    its JSON)."""
+
+
+_Position = _KnownPosition | _UnknownPosition
+
+
+@dataclass(frozen=True, slots=True)
+class _DepFinding:
+    """One deptry finding, scoped to the package it was found in."""
+
+    pkg: Path
+    file: str
+    position: _Position
+    code: str
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class _Skipped:
+    pkg: Path
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class _Failed:
+    """deptry failed to run on a package, or its JSON output did not
+    parse."""
+
+    pkg: Path
+    stderr_tail: str
+
+
+@dataclass(frozen=True, slots=True)
+class _DepsResult:
+    findings: tuple[_DepFinding, ...] = ()
+    skipped: tuple[_Skipped, ...] = field(default_factory=tuple)
+    failed: tuple[_Failed, ...] = field(default_factory=tuple)
+
+
+def _has_runtime_dependencies(pyproject: Path) -> bool:
+    with pyproject.open("rb") as f:
+        data = tomllib.load(f)
+    project = cast(dict[str, object], data.get("project", {}))
+    deps = project.get("dependencies", [])
+    return isinstance(deps, list) and len(cast(list[object], deps)) > 0
+
+
+def _nested_exclusions(pkg: Path, package_roots: Sequence[Path]) -> tuple[Path, ...]:
+    """Subdirectories of pkg that are themselves package roots, relative to
+    pkg, so a package's own scan does not re-scan a nested package."""
+    nested: list[Path] = []
+    for other in package_roots:
+        if other == pkg:
+            continue
+        try:
+            rel = other.relative_to(pkg)
+        except ValueError:
+            continue
+        nested.append(rel)
+    return tuple(nested)
+
+
+def _position_from(line: object, column: object) -> _Position:
+    if isinstance(line, int) and isinstance(column, int):
+        return _KnownPosition(line, column)
+    return _UnknownPosition()
+
+
+@dataclass(frozen=True, slots=True)
+class _ParseError:
+    """deptry's JSON output did not have the shape this parser expects."""
+
+    message: str
+
+
+def _parse_deptry_json(raw: str, pkg: Path) -> tuple[_DepFinding, ...] | _ParseError:
+    try:
+        data = cast(object, json.loads(raw))
+    except json.JSONDecodeError as exc:
+        return _ParseError(str(exc))
+    if not isinstance(data, list):
+        return _ParseError("expected a JSON list")
+    findings: list[_DepFinding] = []
+    for item in cast(list[object], data):
+        if not isinstance(item, dict):
+            return _ParseError("expected a JSON object per finding")
+        item = cast(dict[str, object], item)
+        err = cast(dict[str, object], item.get("error", {}))
+        loc = cast(dict[str, object], item.get("location", {}))
+        code = err.get("code", "?")
+        message = err.get("message", "")
+        file = loc.get("file", "?")
+        if (
+            not isinstance(code, str)
+            or not isinstance(message, str)
+            or not isinstance(file, str)
+        ):
+            return _ParseError("expected str fields in error/location")
+        findings.append(
+            _DepFinding(
+                pkg=pkg,
+                file=file,
+                position=_position_from(loc.get("line"), loc.get("column")),
+                code=code,
+                message=message,
+            )
+        )
+    return tuple(findings)
+
+
+def _run_deptry_on(
+    repo: Path, pkg: Path, package_roots: Sequence[Path], tmp_dir: Path
+) -> _Skipped | _Failed | tuple[_DepFinding, ...]:
+    pkg_abs = repo / pkg
+    cmd = [
+        "uv",
+        "run",
+        "--directory",
+        str(pkg_abs),
+        "--with",
+        f"deptry=={_DEPTRY_VERSION}",
+        "--frozen",
+        "deptry",
+        ".",
+        "--no-ansi",
+    ]
+    for rel in _nested_exclusions(pkg, package_roots):
+        pattern = "^" + re.escape(rel.as_posix()) + "(/|$)"
+        cmd += ["--extend-exclude", pattern]
+    json_out = tmp_dir / f"{pkg.as_posix().replace('/', '__') or 'root'}.json"
+    cmd += ["--json-output", str(json_out)]
+
+    proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
+
+    if json_out.exists():
+        parsed = _parse_deptry_json(json_out.read_text(), pkg)
+        if isinstance(parsed, _ParseError):
+            return _Failed(pkg, parsed.message)
+        return parsed
+    if proc.returncode == 2 and _NO_LOCKFILE_MARKER in proc.stderr:
+        return _Skipped(pkg, "no uv.lock found (uv run --frozen needs one)")
+    tail = "\n".join(proc.stderr.strip().splitlines()[-20:]) or "(no stderr output)"
+    return _Failed(pkg, tail)
+
+
+@dataclass(frozen=True, slots=True)
+class UvMissing:
+    """`uv` is not on PATH; the dependency-declaration rule cannot run at
+    all, never a silent skip."""
+
+
+def run_dependency_checks(repo: Path) -> _DepsResult | UvMissing:
+    """Scans every package root under repo with deptry, one uv-managed
+    environment per package."""
+    if shutil.which("uv") is None:
+        return UvMissing()
+
+    package_roots = find_package_roots(repo)
+    findings: list[_DepFinding] = []
+    skipped: list[_Skipped] = []
+    failed: list[_Failed] = []
+
+    with tempfile.TemporaryDirectory(prefix="pymodularity_deps_") as tmp:
+        tmp_dir = Path(tmp)
+        for pkg in package_roots:
+            pyproject = repo / pkg / "pyproject.toml"
+            if not _has_runtime_dependencies(pyproject):
+                skipped.append(_Skipped(pkg, "declares no dependencies"))
+                continue
+            outcome = _run_deptry_on(repo, pkg, package_roots, tmp_dir)
+            if isinstance(outcome, _Skipped):
+                skipped.append(outcome)
+            elif isinstance(outcome, _Failed):
+                failed.append(outcome)
+            else:
+                findings.extend(outcome)
+
+    findings.sort(key=lambda f: (str(f.pkg), f.file, _sort_pos(f.position)))
+    skipped.sort(key=lambda s: str(s.pkg))
+    failed.sort(key=lambda f: str(f.pkg))
+    return _DepsResult(
+        findings=tuple(findings), skipped=tuple(skipped), failed=tuple(failed)
+    )
+
+
+def _sort_pos(position: _Position):
+    """Sort key for a position: (0, 0) for the unknown case sorts first,
+    same ordering `deptry_all.py` uses. No return-type annotation here
+    deliberately -- `tuple[int, int]` as a *named* return type is the
+    anti-pattern `prefer-named-types-over-tuples` flags; an unlabeled
+    sort-key return isn't."""
+    if isinstance(position, _KnownPosition):
+        return (position.line, position.column)
+    return (0, 0)
+
+
+def print_deps_findings(result: _DepsResult) -> bool:
+    """Prints the dependency-declaration section, returns True if any
+    finding or failure exists (failures are finding-level, same exit
+    behavior as a finding)."""
+    any_finding = bool(result.findings) or bool(result.failed)
+
+    print(f"## Dependency declarations: {len(result.findings)} finding(s)")
+    for f in result.findings:
+        loc = (
+            f"{f.pkg}/{f.file}:{f.position.line}:{f.position.column}"
+            if isinstance(f.position, _KnownPosition)
+            else f"{f.pkg}/{f.file}"
+        )
+        print(f"{loc}: {f.code} {f.message}")
+    for failure in result.failed:
+        print(f"- {failure.pkg}: deptry failed to run or its output did not parse")
+        print(failure.stderr_tail)
+    for s in result.skipped:
+        print(f"- {s.pkg}: skipped ({s.reason})")
+    print()
+
+    return any_finding