repotour 1.0.0__py3-none-any.whl

repotour/__init__.py

@@ -0,0 +1,5 @@
+"""Repotour: generate a codebase tour for new contributors."""
+
+from importlib.metadata import version
+
+__version__ = version("repotour")

repotour/__main__.py

@@ -0,0 +1,5 @@
+"""Allows `python -m repotour`."""
+
+from repotour.cli import app
+
+app()

repotour/analyzers/base.py

@@ -0,0 +1,29 @@
+"""The analyzer contract. Each analyzer produces one section of the tour."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from repotour.model.snapshot import RepoSnapshot
+from repotour.model.tour import Evidence
+
+
+@dataclass
+class AnalyzerResult:
+    analyzer: str
+    data: dict[str, Any]  # analyzer-specific, JSON-serializable
+    evidence: list[Evidence] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+
+class Analyzer(Protocol):
+    name: str
+    version: int  # bump to invalidate this analyzer's cache
+    depends_on: tuple[str, ...]
+
+    def run(
+        self,
+        snapshot: RepoSnapshot,
+        inputs: dict[str, AnalyzerResult],
+    ) -> AnalyzerResult: ...

repotour/analyzers/basics.py

@@ -0,0 +1,73 @@
+"""Basics a newcomer expects: README, tests, contributing guide, license, CI.
+
+Each missing item is a claim whose evidence states what was looked for.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from repotour import repopath
+from repotour.model.snapshot import RepoSnapshot
+from repotour.model.tour import Evidence, MissingBasic
+
+CI_FILES = frozenset(
+    {
+        ".gitlab-ci.yml",
+        ".travis.yml",
+        "azure-pipelines.yml",
+        "bitbucket-pipelines.yml",
+        "Jenkinsfile",
+        ".circleci/config.yml",
+        ".drone.yml",
+        "appveyor.yml",
+    }
+)
+CI_DIRS = (".github/workflows/", ".buildkite/", ".woodpecker/")
+
+
+def find_missing(snapshot: RepoSnapshot) -> tuple[MissingBasic, ...]:
+    paths = [f.path for f in snapshot.files]
+    checks: list[tuple[str, Callable[[], bool], str, str]] = [
+        ("README", lambda: any(_at_root(p) and _stem(p) == "readme" for p in paths),
+         "README*", "a README at the repository root"),
+        ("tests", lambda: any(f.category == "test" for f in snapshot.files),
+         "tests", "any file classified as a test"),
+        ("contributing guide", lambda: any(_is_contributing(p) for p in paths),
+         "CONTRIBUTING*", "CONTRIBUTING* at the root, in docs/, or in .github/"),
+        ("license", lambda: any(_at_root(p) and _is_license(p) for p in paths),
+         "LICENSE*", "LICENSE*, LICENCE*, or COPYING* at the repository root"),
+        ("CI configuration", lambda: any(_is_ci(p) for p in paths),
+         ".github/workflows/", "GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure, "
+         "Travis, Bitbucket, Buildkite, Drone, or AppVeyor configuration"),
+    ]  # fmt: skip
+    return tuple(
+        MissingBasic(
+            item=item,
+            evidence=(Evidence(kind="file", ref=ref, detail=f"looked for {looked_for}"),),
+        )
+        for item, present, ref, looked_for in checks
+        if not present()
+    )
+
+
+def _at_root(path: str) -> bool:
+    return "/" not in path
+
+
+def _stem(path: str) -> str:
+    return repopath.stem(path).lower()
+
+
+def _is_contributing(path: str) -> bool:
+    parent = repopath.parent(path)
+    return parent in (".", "docs", ".github") and _stem(path) == "contributing"
+
+
+def _is_license(path: str) -> bool:
+    name = repopath.name(path).upper()
+    return name.startswith(("LICENSE", "LICENCE", "COPYING"))
+
+
+def _is_ci(path: str) -> bool:
+    return path in CI_FILES or path.startswith(CI_DIRS)

repotour/analyzers/bulk.py

@@ -0,0 +1,50 @@
+"""Bulk commits: commits so broad they say nothing about who works on what.
+
+A commit is bulk if it touches more files than `thresholds.bulk_commit_files`
+or is listed in `.git-blame-ignore-revs` (as committed at HEAD) or in config
+`ignore_revs`. Ignore lists may use abbreviated SHAs.
+"""
+
+from __future__ import annotations
+
+from repotour.model.history import CommitRecord
+from repotour.model.snapshot import RepoSnapshot
+
+IGNORE_REVS_FILE = ".git-blame-ignore-revs"
+MIN_ABBREVIATED_SHA = 7
+
+
+def find_bulk(snapshot: RepoSnapshot, commits: tuple[CommitRecord, ...]) -> dict[str, str]:
+    """Map each bulk commit's SHA to the reason it is bulk."""
+    listed = _listed_revs(snapshot)
+    limit = snapshot.config.thresholds.bulk_commit_files
+    bulk: dict[str, str] = {}
+    for commit in commits:
+        reason = _listed_reason(commit.sha, listed)
+        if reason is None and len(commit.files) > limit:
+            reason = f"touches {len(commit.files)} files"
+        if reason is not None:
+            bulk[commit.sha] = reason
+    return bulk
+
+
+def _listed_revs(snapshot: RepoSnapshot) -> list[tuple[str, str]]:
+    revs: list[tuple[str, str]] = []
+    if IGNORE_REVS_FILE in snapshot.contents:
+        text = snapshot.read_bytes(IGNORE_REVS_FILE).decode("utf-8", "replace")
+        for line in text.splitlines():
+            rev = line.split("#", 1)[0].strip().lower()
+            if len(rev) >= MIN_ABBREVIATED_SHA:
+                revs.append((rev, f"listed in {IGNORE_REVS_FILE}"))
+    for rev in snapshot.config.ignore_revs:
+        cleaned = rev.strip().lower()
+        if len(cleaned) >= MIN_ABBREVIATED_SHA:
+            revs.append((cleaned, "listed in config ignore_revs"))
+    return revs
+
+
+def _listed_reason(sha: str, listed: list[tuple[str, str]]) -> str | None:
+    for rev, reason in listed:
+        if sha.startswith(rev):
+            return reason
+    return None

repotour/analyzers/commands.py

@@ -0,0 +1,301 @@
+"""How to install, run, and test the project, quoted from its own files.
+
+Sources come in priority tiers. For each purpose (install, run, test), only
+the highest tier that defines that purpose is used, so a Makefile's `test`
+target hides the CI workflow's test step. Commands are never invented.
+
+1. Makefile targets and justfile recipes
+2. package.json scripts
+3. pyproject.toml task runners, tox.ini, noxfile.py
+4. GitHub Actions workflow steps (install and test only)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+from repotour.model.snapshot import RepoSnapshot
+from repotour.model.tour import Command, Evidence
+
+PURPOSES = ("install", "run", "test")
+MAX_PER_PURPOSE = 5
+MAX_OTHER = 8
+SOURCES_LOOKED_AT = (
+    "Makefile, justfile, package.json scripts, pyproject.toml task runners, "
+    "tox.ini, noxfile.py, and GitHub Actions workflows"
+)
+
+_INSTALL_NAMES = frozenset({"install", "setup", "bootstrap", "deps", "dependencies", "init"})
+_RUN_NAMES = frozenset({"run", "start", "serve", "server", "dev", "develop"})
+_TEST_NAME = re.compile(r"^(test|tests|spec|e2e|unit)([-_:].*)?$")
+
+_MAKE_TARGET = re.compile(r"^([A-Za-z0-9][\w.-]*)\s*:(?![:=])", re.MULTILINE)
+_JUST_RECIPE = re.compile(r"^@?([A-Za-z0-9][\w-]*)(?:\s+[^:=\n]*)?:(?!=)", re.MULTILINE)
+_NOX_SESSION = re.compile(r"@nox\.session(?:\([^)]*\))?\s*\ndef\s+(\w+)")
+_CI_INSTALL = re.compile(
+    r"\b(pip3? install|uv sync|uv pip install|poetry install|pdm install|pipenv install"
+    r"|npm (ci|install)|yarn install|pnpm install|bun install|bundle install"
+    r"|go mod download|cargo fetch|composer install)\b"
+)
+_CI_TEST = re.compile(
+    r"\b(pytest|tox|nox|go test|cargo test|npm (run )?test|yarn test|pnpm test|bun test"
+    r"|make test|jest|vitest|mocha|rspec|phpunit|unittest|mvn test|gradle test)\b"
+)
+
+
+@dataclass(frozen=True)
+class _Found:
+    purpose: str
+    command: str
+    ref: str
+    detail: str
+
+
+def find_commands(snapshot: RepoSnapshot) -> tuple[tuple[Command, ...], list[str]]:
+    finder = _Finder(snapshot)
+    tiers = [
+        finder.makefile() + finder.justfile(),
+        finder.package_json(),
+        finder.pyproject() + finder.tox() + finder.nox(),
+        finder.workflows(),
+    ]
+    chosen: list[_Found] = []
+    for purpose in PURPOSES:
+        for tier in tiers:
+            matching = [f for f in tier if f.purpose == purpose]
+            if matching:
+                chosen.extend(matching[:MAX_PER_PURPOSE])
+                break
+    others = [f for tier in tiers for f in tier if f.purpose == "other"]
+    chosen.extend(others[:MAX_OTHER])
+    commands = tuple(
+        Command(
+            purpose=f.purpose,
+            command=f.command,
+            evidence=(Evidence(kind="file", ref=f.ref, detail=f.detail),),
+        )
+        for f in chosen
+    )
+    return commands, finder.warnings
+
+
+def purpose_of(name: str) -> str:
+    lowered = name.lower()
+    if lowered in _INSTALL_NAMES:
+        return "install"
+    if lowered in _RUN_NAMES:
+        return "run"
+    if _TEST_NAME.match(lowered):
+        return "test"
+    return "other"
+
+
+class _Finder:
+    def __init__(self, snapshot: RepoSnapshot) -> None:
+        self.snapshot = snapshot
+        self.all_paths = {f.path for f in snapshot.files}
+        self.warnings: list[str] = []
+
+    def makefile(self) -> list[_Found]:
+        path = next(
+            (p for p in ("Makefile", "makefile", "GNUmakefile") if p in self.all_paths), None
+        )
+        if path is None:
+            return []
+        text = self._text(path)
+        found = []
+        for match in _MAKE_TARGET.finditer(text):
+            name = match.group(1)
+            if name.startswith(".") or "%" in name:
+                continue
+            recipe = _first_recipe_line(text, match.end())
+            detail = f"target {name}: {recipe}" if recipe else f"target {name}"
+            found.append(_Found(purpose_of(name), f"make {name}", path, detail))
+        return _sorted_unique(found)
+
+    def justfile(self) -> list[_Found]:
+        path = next((p for p in ("justfile", "Justfile", ".justfile") if p in self.all_paths), None)
+        if path is None:
+            return []
+        text = self._text(path)
+        found = []
+        for match in _JUST_RECIPE.finditer(text):
+            name = match.group(1)
+            recipe = _first_recipe_line(text, match.end())
+            detail = f"recipe {name}: {recipe}" if recipe else f"recipe {name}"
+            found.append(_Found(purpose_of(name), f"just {name}", path, detail))
+        return _sorted_unique(found)
+
+    def package_json(self) -> list[_Found]:
+        data = self._parse("package.json", json.loads)
+        scripts = data.get("scripts") if isinstance(data, dict) else None
+        if not isinstance(scripts, dict):
+            return []
+        manager = self._package_manager()
+        found = []
+        for name, body in scripts.items():
+            if not isinstance(body, str):
+                continue
+            found.append(
+                _Found(
+                    purpose_of(name),
+                    _script_command(manager, name),
+                    "package.json",
+                    f'script "{name}": {body}',
+                )
+            )
+        return _sorted_unique(found)
+
+    def pyproject(self) -> list[_Found]:
+        data = self._parse("pyproject.toml", tomllib.loads)
+        tool = data.get("tool") if isinstance(data, dict) else None
+        if not isinstance(tool, dict):
+            return []
+        found: list[_Found] = []
+        runners = (
+            ("poe", "tasks", "poe"),
+            ("taskipy", "tasks", "task"),
+            ("pdm", "scripts", "pdm run"),
+        )
+        for section, key, prefix in runners:
+            tasks = _get(tool, section, key)
+            if isinstance(tasks, dict):
+                for name in tasks:
+                    if not name.startswith("_"):
+                        found.append(
+                            _Found(
+                                purpose_of(name),
+                                f"{prefix} {name}",
+                                "pyproject.toml",
+                                f"[tool.{section}.{key}] {name}",
+                            )
+                        )
+        envs = _get(tool, "hatch", "envs")
+        if isinstance(envs, dict):
+            for env_name, env in envs.items():
+                scripts = env.get("scripts") if isinstance(env, dict) else None
+                if not isinstance(scripts, dict):
+                    continue
+                for name in scripts:
+                    target = name if env_name == "default" else f"{env_name}:{name}"
+                    found.append(
+                        _Found(
+                            purpose_of(name),
+                            f"hatch run {target}",
+                            "pyproject.toml",
+                            f"[tool.hatch.envs.{env_name}.scripts] {name}",
+                        )
+                    )
+        return _sorted_unique(found)
+
+    def tox(self) -> list[_Found]:
+        if "tox.ini" not in self.all_paths:
+            return []
+        return [_Found("test", "tox", "tox.ini", "tox configuration")]
+
+    def nox(self) -> list[_Found]:
+        if "noxfile.py" not in self.all_paths:
+            return []
+        sessions = _NOX_SESSION.findall(self._text("noxfile.py"))
+        return _sorted_unique(
+            [_Found(purpose_of(s), f"nox -s {s}", "noxfile.py", f"session {s}") for s in sessions]
+        )
+
+    def workflows(self) -> list[_Found]:
+        found: list[_Found] = []
+        workflow_paths = sorted(
+            p
+            for p in self.all_paths
+            if p.startswith(".github/workflows/") and p.endswith((".yml", ".yaml"))
+        )
+        for path in workflow_paths:
+            data = self._parse(path, yaml.safe_load)
+            jobs = data.get("jobs") if isinstance(data, dict) else None
+            if not isinstance(jobs, dict):
+                continue
+            for job_name, job in jobs.items():
+                steps = job.get("steps") if isinstance(job, dict) else None
+                for step in steps if isinstance(steps, list) else []:
+                    run = step.get("run") if isinstance(step, dict) else None
+                    if not isinstance(run, str):
+                        continue
+                    for line in (ln.strip() for ln in run.splitlines()):
+                        purpose = _ci_purpose(line)
+                        if purpose is not None:
+                            found.append(_Found(purpose, line, path, f"job {job_name}"))
+        unique: dict[tuple[str, str], _Found] = {}
+        for f in found:
+            unique.setdefault((f.purpose, f.command), f)
+        return list(unique.values())
+
+    def _package_manager(self) -> str:
+        for lockfile, manager in (
+            ("pnpm-lock.yaml", "pnpm"),
+            ("yarn.lock", "yarn"),
+            ("bun.lockb", "bun"),
+            ("bun.lock", "bun"),
+        ):
+            if lockfile in self.all_paths:
+                return manager
+        return "npm"
+
+    def _text(self, path: str) -> str:
+        return self.snapshot.read_bytes(path).decode("utf-8", "replace")
+
+    def _parse(self, path: str, loader: Any) -> Any:
+        if path not in self.all_paths:
+            return None
+        try:
+            return loader(self._text(path))
+        except (ValueError, yaml.YAMLError) as exc:
+            # Manifests are reported once, by project detection; only report others.
+            if path not in ("package.json", "pyproject.toml"):
+                self.warnings.append(f"{path}: could not be parsed ({exc})")
+            return None
+
+
+def _script_command(manager: str, name: str) -> str:
+    if name in ("test", "start") and manager != "bun":
+        return f"{manager} {name}"
+    return f"{manager} run {name}"
+
+
+def _first_recipe_line(text: str, offset: int) -> str | None:
+    for line in text[offset:].splitlines()[1:]:
+        if not line.strip():
+            continue
+        if line.startswith(("\t", "    ")):
+            text = line.strip().lstrip("@")
+            return f"{text[:-1].rstrip()} …" if text.endswith("\\") else text
+        return None
+    return None
+
+
+def _ci_purpose(line: str) -> str | None:
+    if not line or line.startswith(("#", "echo ", "cd ")) or "${{" in line:
+        return None
+    if _CI_INSTALL.search(line):
+        return "install"
+    if _CI_TEST.search(line):
+        return "test"
+    return None
+
+
+def _sorted_unique(found: list[_Found]) -> list[_Found]:
+    unique = {f.command: f for f in found}
+    return sorted(unique.values(), key=lambda f: f.command)
+
+
+def _get(table: dict[str, Any], *keys: str) -> Any:
+    value: Any = table
+    for key in keys:
+        if not isinstance(value, dict):
+            return None
+        value = value.get(key)
+    return value

repotour/analyzers/dependencies.py

@@ -0,0 +1,226 @@
+"""Dependency graph: which modules import which, inside the repository.
+
+Only static imports count. Test, generated, and vendored files are left out.
+Imports that resolve outside the repository are counted, not drawn. A file
+that fails to parse becomes a warning and is skipped.
+
+PageRank (over importer -> imported edges) names the core modules; modules
+nothing imports that are not entry points (and not empty) are leaf modules. Graphs over
+`thresholds.graph_max_nodes` collapse to directories unless `full_graph`.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+from collections.abc import Callable
+
+from repotour.analyzers.base import AnalyzerResult
+from repotour.graph.collapse import ROOT_GROUP, collapse
+from repotour.graph.pagerank import pagerank
+from repotour.languages import ADAPTERS
+from repotour.languages.base import LanguageAdapter, RawImport
+from repotour.model.serde import to_data
+from repotour.model.snapshot import RepoSnapshot
+from repotour.model.tour import (
+    CoreModule,
+    DependencyGraphSection,
+    Evidence,
+    ExternalImports,
+    GraphNode,
+    ImportEdge,
+    LeafModule,
+)
+from repotour.scan.filetypes import is_peripheral
+
+EXTERNAL_EXAMPLES = 5
+PARTIAL_EXAMPLES = 5
+MAX_LEAVES = 10
+GRAPH_CATEGORIES = ("source",)
+
+
+class DependenciesAnalyzer:
+    name = "dependencies"
+    version = 6
+    depends_on: tuple[str, ...] = ("entry_points",)
+
+    def run(self, snapshot: RepoSnapshot, inputs: dict[str, AnalyzerResult]) -> AnalyzerResult:
+        all_paths = [f.path for f in snapshot.files]
+        candidates = [f.path for f in snapshot.files if f.category in GRAPH_CATEGORIES]
+        warnings: list[str] = []
+        languages: list[str] = []
+        nodes: list[str] = []
+        lines: dict[tuple[str, str], int] = {}  # (source, target) -> first import line
+        external: dict[str, tuple[str, RawImport]] = {}  # name -> first (path, import)
+        reached: set[str] = set()  # files reached by some import (whole Go packages)
+
+        for adapter in ADAPTERS:
+            paths = sorted(p for p in candidates if adapter.handles(p))
+            if not paths:
+                continue
+            languages.append(adapter.name)
+            parsed = _parse_all(adapter, paths, snapshot, warnings)
+            index = adapter.build_index(list(parsed), all_paths, _reader(snapshot))
+            nodes.extend(parsed)
+            for path, imports in parsed.items():
+                for raw in imports:
+                    targets = adapter.resolve(raw, path, index)
+                    if not targets and not raw.module.startswith((".", "/")):
+                        external.setdefault(adapter.external_name(raw), (path, raw))
+                    for target in targets:
+                        if target != path:
+                            lines.setdefault((path, target), raw.line)
+                            reached.update(adapter.imported_together(target, index))
+
+        nodes.sort()
+        edges = sorted(lines)
+        ranks = pagerank(nodes, edges)
+        entry_paths = _entry_paths(inputs)
+        config = snapshot.config
+        limit = len(nodes) if config.full_graph else config.thresholds.graph_max_nodes
+        drawn = collapse(nodes, edges, ranks, max(limit, 1))
+        empty = {f.path for f in snapshot.files if f.lines == 0}
+        leaves = _leaves([n for n in nodes if n not in empty | reached], edges, entry_paths)
+
+        section = DependencyGraphSection(
+            languages=tuple(sorted(languages)),
+            modules=len(nodes),
+            imports=len(edges),
+            depth=drawn.depth,
+            nodes=tuple(GraphNode(id=g, modules=len(drawn.members[g])) for g in drawn.nodes),
+            edges=tuple(
+                _edge(source, target, behind, lines)
+                for (source, target), behind in sorted(drawn.edges.items())
+            ),
+            omitted=drawn.omitted,
+            external=_external_claim(external),
+            core=_core(nodes, edges, ranks, config.thresholds.core_module_share),
+            leaves=tuple(leaves[:MAX_LEAVES]),
+            leaves_omitted=max(0, len(leaves) - MAX_LEAVES),
+        )
+        data = to_data(section)
+        # Module-level graph for the reading order (the drawn graph may be collapsed).
+        data["module_edges"] = [[s, t, lines[(s, t)]] for s, t in edges]
+        data["ranks"] = ranks
+        return AnalyzerResult(analyzer=self.name, data=data, warnings=warnings)
+
+
+def _reader(snapshot: RepoSnapshot) -> Callable[[str], str]:
+    def read(path: str) -> str:
+        return snapshot.read_bytes(path).decode("utf-8", "replace")
+
+    return read
+
+
+def _parse_all(
+    adapter: LanguageAdapter, paths: list[str], snapshot: RepoSnapshot, warnings: list[str]
+) -> dict[str, tuple[RawImport, ...]]:
+    """Imports per file. tree-sitter recovers from syntax it does not know, so
+    a partially parsed file keeps the imports it yielded; all such files are
+    reported in one warning rather than one each."""
+    parsed: dict[str, tuple[RawImport, ...]] = {}
+    partial: list[str] = []
+    for path in paths:
+        result = snapshot.parse(adapter, path)
+        if result.has_error:
+            partial.append(path)
+        parsed[path] = result.imports
+    if partial:
+        examples = ", ".join(partial[:PARTIAL_EXAMPLES])
+        more = (
+            f", and {len(partial) - PARTIAL_EXAMPLES} more"
+            if len(partial) > PARTIAL_EXAMPLES
+            else ""
+        )
+        warnings.append(
+            f"{len(partial)} {adapter.name} file{'' if len(partial) == 1 else 's'} had syntax "
+            f"the parser could not fully read; their imports were still used: {examples}{more}"
+        )
+    return parsed
+
+
+def _entry_paths(inputs: dict[str, AnalyzerResult]) -> set[str]:
+    result = inputs.get("entry_points")
+    entries = result.data.get("entries", []) if result is not None else []
+    return {e["path"] for e in entries if isinstance(e, dict)}
+
+
+def _edge(
+    source: str, target: str, behind: list[tuple[str, str]], lines: dict[tuple[str, str], int]
+) -> ImportEdge:
+    first = behind[0]
+    detail = f"line {lines[first]}"
+    if len(behind) > 1 or (source, target) != first:
+        detail = f"{len(behind)} module import{'' if len(behind) == 1 else 's'}, e.g. {detail}"
+    return ImportEdge(
+        source=source,
+        target=target,
+        count=len(behind),
+        evidence=(Evidence(kind="import", ref=f"{first[0]} -> {first[1]}", detail=detail),),
+    )
+
+
+def _core(
+    nodes: list[str], edges: list[tuple[str, str]], ranks: dict[str, float], share: float
+) -> tuple[CoreModule, ...]:
+    importers: dict[str, list[str]] = {n: [] for n in nodes}
+    for source, target in edges:
+        importers[target].append(source)
+    ordered = sorted(nodes, key=lambda n: (-ranks[n], n))
+    position = {n: i + 1 for i, n in enumerate(ordered)}
+    imported = [n for n in ordered if importers[n] and not is_peripheral(n)]
+    count = min(len(imported), max(1, math.ceil(len(nodes) * share))) if imported else 0
+    return tuple(
+        CoreModule(
+            path=n,
+            importers=len(importers[n]),
+            rank=position[n],
+            evidence=(
+                Evidence(
+                    kind="import",
+                    ref=f"{importers[n][0]} -> {n}",
+                    detail=f"imported by {len(importers[n])} module"
+                    f"{'' if len(importers[n]) == 1 else 's'}; "
+                    f"PageRank {position[n]} of {len(nodes)}",
+                ),
+            ),
+        )
+        for n in imported[:count]
+    )
+
+
+def _leaves(
+    nodes: list[str], edges: list[tuple[str, str]], entry_paths: set[str]
+) -> list[LeafModule]:
+    in_degree = Counter(target for _, target in edges)
+    return [
+        LeafModule(
+            path=n,
+            evidence=(
+                Evidence(kind="file", ref=n, detail="no module imports it; not an entry point"),
+            ),
+        )
+        for n in nodes
+        if in_degree[n] == 0 and n not in entry_paths and not is_peripheral(n)
+    ]
+
+
+def _external_claim(external: dict[str, tuple[str, RawImport]]) -> ExternalImports | None:
+    if not external:
+        return None
+    names = sorted(external)
+    return ExternalImports(
+        count=len(names),
+        examples=tuple(names[:EXTERNAL_EXAMPLES]),
+        evidence=tuple(
+            Evidence(
+                kind="import",
+                ref=f"{external[name][0]} -> {name}",
+                detail=f"line {external[name][1].line}",
+            )
+            for name in names[:3]
+        ),
+    )
+
+
+__all__ = ["ROOT_GROUP", "DependenciesAnalyzer"]