foothold 0.1.1__py3-none-any.whl

foothold/__init__.py

@@ -0,0 +1,3 @@
+"""Foothold: turn an unfamiliar repository into a reading path."""
+
+__version__ = "0.1.0"

foothold/analyze.py

@@ -0,0 +1,40 @@
+"""Orchestrates the offline pass: collect -> graph -> rank -> RepoMap."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from foothold.collectors import churn_by_path, collect_markers, collect_modules
+from foothold.config import Config
+from foothold.graph import build_graph, find_cycles, find_entrypoints, rank
+from foothold.models import Module, RepoMap, Score
+
+
+def _untested(modules: dict[str, Module], scores: list[Score]) -> list[str]:
+    """Source modules with no test file whose name references them."""
+    blob = " ".join(m.path for m in modules.values() if m.is_test)
+    out = []
+    for score in scores[:50]:
+        stem = Path(score.path).stem
+        if stem not in blob:
+            out.append(score.path)
+    return out
+
+
+def analyze(root: Path, config: Config | None = None) -> RepoMap:
+    config = config or Config.load(root)
+    modules, edges = collect_modules(root, config.excludes)
+    graph = build_graph(modules, edges, root_alias=root.name)
+    churn = churn_by_path(root)
+    scores = rank(graph, modules, churn, config.weights)
+    source_paths = [m.path for m in modules.values() if not m.is_test]
+    return RepoMap(
+        root=str(root),
+        modules=modules,
+        edges=edges,
+        scores=scores,
+        entrypoints=find_entrypoints(graph, modules),
+        markers=collect_markers(root, source_paths),
+        untested=_untested(modules, scores),
+        cycles=find_cycles(graph),
+    )

foothold/cli.py

@@ -0,0 +1,151 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from foothold import __version__
+from foothold.analyze import analyze
+from foothold.config import Config
+from foothold.issues import propose
+from foothold.narrator import NarratorError, narrate
+from foothold.narrator.client import build_context, estimate_tokens
+from foothold.render import render_architecture, render_map
+
+app = typer.Typer(
+    add_completion=False,
+    help="Turn an unfamiliar repository into a reading path.",
+    no_args_is_help=True,
+)
+console = Console()
+err = Console(stderr=True)
+
+
+def _version(value: bool) -> None:
+    if value:
+        console.print(__version__)
+        raise typer.Exit
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", callback=_version, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    """Foothold reads a repository the way a senior engineer does on day one."""
+
+
+@app.command("map")
+def map_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository root."),
+    top: int = typer.Option(30, "--top", "-n", help="How many files to show."),
+    as_json: bool = typer.Option(False, "--json", help="Machine-readable output."),
+) -> None:
+    """Rank the files that hold the repository together. Offline, no API key."""
+    repo = analyze(path.resolve())
+    if not repo.modules:
+        err.print("[red]No Python modules found.[/red] Foothold v0.1 is Python-only.")
+        raise typer.Exit(1)
+    if as_json:
+        console.print_json(
+            json.dumps(
+                {
+                    "root": repo.root,
+                    "modules": len(repo.modules),
+                    "loc": repo.loc_total,
+                    "entrypoints": [repo.modules[n].path for n in repo.entrypoints],
+                    "cycles": repo.cycles,
+                    "scores": [asdict(s) for s in repo.scores[:top]],
+                }
+            )
+        )
+        return
+    render_map(repo, top=top)
+
+
+@app.command("docs")
+def docs_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository root."),
+    out: Path = typer.Option(Path("ARCHITECTURE.md"), "--out", "-o"),
+    top: int = typer.Option(20, "--top", "-n"),
+    narrate_flag: bool = typer.Option(False, "--narrate", help="Add model-written prose."),
+    yes: bool = typer.Option(False, "--yes", help="Skip the spend confirmation."),
+) -> None:
+    """Write ARCHITECTURE.md. Deterministic unless --narrate is passed."""
+    repo = analyze(path.resolve())
+    narrative = None
+    if narrate_flag:
+        config = Config.load(path.resolve())
+        tokens = estimate_tokens(build_context(repo, top=top))
+        if not yes:
+            typer.confirm(f"Send ~{tokens:,} tokens to {config.model}?", abort=True)
+        try:
+            narrative, usage = narrate(repo, model=config.model, top=top)
+            err.print(
+                f"[dim]{usage.prompt_tokens}+{usage.completion_tokens} tokens, "
+                f"~${usage.cost_usd():.4f}[/dim]"
+            )
+        except NarratorError as exc:
+            err.print(f"[yellow]{exc} Falling back to the deterministic document.[/yellow]")
+    try:
+        out.write_text(render_architecture(repo, top=top, narrative=narrative), encoding="utf-8")
+    except OSError as exc:
+        # A bad --out path is user error, not a crash: no traceback, just the reason.
+        err.print(f"[red]Cannot write {out}: {exc.strerror}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(f"Wrote [bold]{out}[/bold]")
+
+
+@app.command("explain")
+def explain_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository root."),
+    top: int = typer.Option(25, "--top", "-n"),
+    yes: bool = typer.Option(False, "--yes"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print the context, send nothing."),
+) -> None:
+    """Explain the repository in prose, grounded in the ranked map."""
+    repo = analyze(path.resolve())
+    config = Config.load(path.resolve())
+    context = build_context(repo, top=top)
+    if dry_run:
+        console.print(context)
+        return
+    if not yes:
+        typer.confirm(f"Send ~{estimate_tokens(context):,} tokens to {config.model}?", abort=True)
+    try:
+        text, usage = narrate(repo, model=config.model, top=top)
+    except NarratorError as exc:
+        err.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+    console.print(text)
+    err.print(f"[dim]~${usage.cost_usd():.4f}[/dim]")
+
+
+@app.command("issues")
+def issues_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository root."),
+    limit: int = typer.Option(10, "--max", "-n"),
+    as_markdown: bool = typer.Option(False, "--markdown"),
+) -> None:
+    """Propose good-first-issue candidates. Offline, no API key."""
+    repo = analyze(path.resolve())
+    candidates = propose(repo, limit=limit)
+    if not candidates:
+        console.print("No candidates found.")
+        return
+    for candidate in candidates:
+        if as_markdown:
+            console.print(f"### {candidate.title}\n\n{candidate.body}\n")
+        else:
+            console.print(f"[bold]{candidate.title}[/bold]")
+            console.print(f"  [dim]{candidate.labels} · {candidate.difficulty}[/dim]")
+
+
+if __name__ == "__main__":
+    app()

foothold/collectors/__init__.py

@@ -0,0 +1,5 @@
+from foothold.collectors.git_history import churn_by_path
+from foothold.collectors.markers import collect_markers
+from foothold.collectors.python_ast import collect_modules
+
+__all__ = ["churn_by_path", "collect_markers", "collect_modules"]

foothold/collectors/git_history.py

@@ -0,0 +1,43 @@
+"""Churn signal derived from git history via subprocess.
+
+Only ``git log`` is invoked, with an explicit argv list and no shell. A repo
+without git, or a shallow clone, degrades to a zero churn signal rather than
+failing the run.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections import Counter
+from pathlib import Path
+
+
+def churn_by_path(root: Path, since: str = "18.months") -> dict[str, int]:
+    """Return {relative path: number of commits touching it}."""
+    try:
+        proc = subprocess.run(
+            [
+                "git",
+                "-C",
+                str(root),
+                "log",
+                f"--since={since}",
+                "--name-only",
+                "--pretty=format:",
+                "--no-merges",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return {}
+    if proc.returncode != 0:
+        return {}
+    counts: Counter[str] = Counter()
+    for line in proc.stdout.splitlines():
+        line = line.strip()
+        if line.endswith(".py"):
+            counts[line] += 1
+    return dict(counts)

foothold/collectors/markers.py

@@ -0,0 +1,31 @@
+"""Extract TODO/FIXME/HACK/XXX markers - raw material for issue candidates."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from foothold.models import Marker
+
+PATTERN = re.compile(r"#\s*(TODO|FIXME|HACK|XXX)\b[:\s]*(.*)", re.IGNORECASE)
+
+
+def collect_markers(root: Path, paths: list[str]) -> list[Marker]:
+    markers: list[Marker] = []
+    for rel in paths:
+        try:
+            text = (root / rel).read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            match = PATTERN.search(line)
+            if match:
+                markers.append(
+                    Marker(
+                        path=rel,
+                        lineno=lineno,
+                        kind=match.group(1).upper(),
+                        text=match.group(2).strip()[:160],
+                    )
+                )
+    return markers

foothold/collectors/python_ast.py

@@ -0,0 +1,108 @@
+"""Parse Python sources into Module records and raw import edges.
+
+Deliberately uses the stdlib ``ast`` module: no third-party parser, no network,
+no execution of the analysed code. Foothold never imports the repository it is
+reading.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from foothold.models import Edge, Module
+
+TEST_HINTS = ("tests/", "test_", "_test.py", "conftest.py")
+
+
+def _is_test(rel: str) -> bool:
+    name = Path(rel).name
+    return (
+        rel.startswith("tests/")
+        or "/tests/" in rel
+        or name.startswith("test_")
+        or name.endswith("_test.py")
+        or name == "conftest.py"
+    )
+
+
+def module_name(rel: str) -> str:
+    """Map ``src/pkg/mod.py`` -> ``pkg.mod`` and ``pkg/__init__.py`` -> ``pkg``."""
+    parts = list(Path(rel).with_suffix("").parts)
+    if parts and parts[0] in {"src", "lib"}:
+        parts = parts[1:]
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(parts)
+
+
+def _public_defs(tree: ast.Module) -> tuple[str, ...]:
+    out: list[str] = []
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) and (
+            not node.name.startswith("_")
+        ):
+            out.append(node.name)
+    return tuple(out)
+
+
+def _resolve_relative(current: str, node: ast.ImportFrom) -> str | None:
+    """Turn ``from ..graph import build`` inside ``a.b.c`` into ``a.graph.build``."""
+    if node.level == 0:
+        return node.module
+    base = current.split(".")
+    anchor = base[: len(base) - node.level + 1] if node.level > 1 else base
+    prefix = ".".join(anchor[:-1] if node.level == 1 else anchor)
+    if not prefix:
+        # ``from . import x`` inside a top-level module: the anchor is the root
+        return node.module or ""
+    return f"{prefix}.{node.module}" if node.module else prefix
+
+
+def parse_file(root: Path, rel: str) -> tuple[Module, list[Edge]]:
+    source = (root / rel).read_text(encoding="utf-8", errors="replace")
+    tree = ast.parse(source, filename=rel)
+    mod = module_name(rel)
+    edges: list[Edge] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            edges.extend(Edge(mod, alias.name, node.lineno) for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            target = _resolve_relative(mod, node)
+            if target is None:
+                continue
+            if target:
+                edges.append(Edge(mod, target, node.lineno))
+                edges.extend(Edge(mod, f"{target}.{a.name}", node.lineno) for a in node.names)
+            else:
+                # ``from . import x`` anchored at the repository root
+                edges.extend(Edge(mod, a.name, node.lineno) for a in node.names)
+    module = Module(
+        path=rel,
+        module=mod,
+        loc=source.count("\n") + 1,
+        is_test=_is_test(rel),
+        is_package_init=Path(rel).name == "__init__.py",
+        defines=_public_defs(tree),
+        docstring=ast.get_docstring(tree),
+    )
+    return module, edges
+
+
+def collect_modules(root: Path, excludes: tuple[str, ...]) -> tuple[dict[str, Module], list[Edge]]:
+    """Walk the tree once, returning modules keyed by dotted name and raw edges."""
+    modules: dict[str, Module] = {}
+    edges: list[Edge] = []
+    for file in sorted(root.rglob("*.py")):
+        rel = file.relative_to(root).as_posix()
+        if any(part in excludes for part in Path(rel).parts):
+            continue
+        try:
+            module, file_edges = parse_file(root, rel)
+        except (SyntaxError, UnicodeDecodeError, ValueError):
+            continue
+        if not module.module:
+            continue
+        modules[module.module] = module
+        edges.extend(file_edges)
+    return modules, edges

foothold/config.py

@@ -0,0 +1,70 @@
+"""Configuration loading and ranking weights."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+
+    HAVE_TOML = True
+else:  # pragma: no cover - exercised on 3.10 only
+    try:
+        import tomli as tomllib
+
+        HAVE_TOML = True
+    except ModuleNotFoundError:
+        HAVE_TOML = False
+
+DEFAULT_EXCLUDES = (
+    ".git",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    "build",
+    "dist",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    "site-packages",
+)
+
+
+@dataclass(frozen=True)
+class Weights:
+    """Relative weight of each ranking signal. Must be documented, not magic."""
+
+    centrality: float = 0.45
+    churn: float = 0.30
+    fan_in: float = 0.15
+    size: float = 0.10
+
+
+@dataclass(frozen=True)
+class Config:
+    excludes: tuple[str, ...] = DEFAULT_EXCLUDES
+    weights: Weights = Weights()
+    top: int = 30
+    model: str = "gpt-4o-mini"
+    max_input_tokens: int = 12_000
+
+    @staticmethod
+    def load(root: Path) -> Config:
+        """Read .foothold.toml if present; fall back to defaults."""
+        path = root / ".foothold.toml"
+        if not path.exists() or not HAVE_TOML:
+            return Config()
+        with path.open("rb") as fh:
+            raw = tomllib.load(fh).get("foothold", {})
+        weights = Weights(**raw.get("weights", {}))
+        return Config(
+            excludes=tuple(raw.get("excludes", DEFAULT_EXCLUDES)),
+            weights=weights,
+            top=int(raw.get("top", 30)),
+            model=str(raw.get("model", "gpt-4o-mini")),
+            max_input_tokens=int(raw.get("max_input_tokens", 12_000)),
+        )

foothold/graph/__init__.py

@@ -0,0 +1,4 @@
+from foothold.graph.build import build_graph, find_cycles, find_entrypoints
+from foothold.graph.rank import rank
+
+__all__ = ["build_graph", "find_cycles", "find_entrypoints", "rank"]

foothold/graph/build.py

@@ -0,0 +1,79 @@
+"""Build the in-project import graph.
+
+External imports are dropped on purpose: the question Foothold answers is
+"which files in *this* repository hold it together", and third-party packages
+add nodes without adding signal.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from foothold.models import Edge, Module
+
+
+def _longest_known_prefix(target: str, known: set[str]) -> str | None:
+    """``pkg.mod.func`` imported from ``pkg.mod`` resolves to ``pkg.mod``."""
+    parts = target.split(".")
+    for cut in range(len(parts), 0, -1):
+        candidate = ".".join(parts[:cut])
+        if candidate in known:
+            return candidate
+    return None
+
+
+def _resolve(target: str, known: set[str], root_alias: str | None) -> str | None:
+    """Resolve an import target to an in-project module, or None if external.
+
+    ``root_alias`` handles the common case of pointing Foothold at a package
+    directory (``foothold map ./rich``) rather than the repository root: inside
+    that tree ``from rich.console import X`` must resolve to the local
+    ``console`` module. Only that one prefix is stripped - blanket suffix
+    matching would map ``os.path`` onto a local ``path.py``.
+    """
+    direct = _longest_known_prefix(target, known)
+    if direct is not None:
+        return direct
+    if root_alias and target.startswith(f"{root_alias}."):
+        return _longest_known_prefix(target[len(root_alias) + 1 :], known)
+    return None
+
+
+def build_graph(
+    modules: dict[str, Module], edges: list[Edge], root_alias: str | None = None
+) -> nx.DiGraph:
+    graph = nx.DiGraph()
+    for name, module in modules.items():
+        graph.add_node(name, path=module.path, loc=module.loc, is_test=module.is_test)
+    known = set(modules)
+    for edge in edges:
+        dst = _resolve(edge.dst, known, root_alias)
+        if dst is None or dst == edge.src or edge.src not in known:
+            continue
+        if graph.has_edge(edge.src, dst):
+            graph[edge.src][dst]["weight"] += 1
+        else:
+            graph.add_edge(edge.src, dst, weight=1, lineno=edge.lineno)
+    return graph
+
+
+def find_entrypoints(graph: nx.DiGraph, modules: dict[str, Module]) -> list[str]:
+    """Modules nothing else imports, excluding tests and empty ``__init__`` files."""
+    out = [
+        name
+        for name in graph.nodes
+        if graph.in_degree(name) == 0
+        and not modules[name].is_test
+        and not (modules[name].is_package_init and modules[name].loc < 5)
+    ]
+    return sorted(out, key=lambda n: (-modules[n].loc, n))
+
+
+def find_cycles(graph: nx.DiGraph, limit: int = 10) -> list[list[str]]:
+    """Import cycles - the places where a newcomer's mental model breaks first."""
+    cycles: list[list[str]] = []
+    for cycle in nx.simple_cycles(graph):
+        cycles.append(sorted(cycle))
+        if len(cycles) >= limit:
+            break
+    return cycles

foothold/graph/rank.py

@@ -0,0 +1,117 @@
+"""Rank modules by how much of the system they explain.
+
+score = w_c * pagerank + w_h * churn + w_f * fan_in + w_s * size
+
+All four components are min-max normalised to [0, 1] over the repository, so a
+score is comparable within a repo but not across repos. The weights live in
+``Config.weights`` and are printable via ``foothold map --explain-scoring``:
+a ranking a user cannot interrogate is a ranking a user cannot trust.
+"""
+
+from __future__ import annotations
+
+import math
+
+import networkx as nx
+
+from foothold.config import Weights
+from foothold.models import Module, Score
+
+
+def pagerank(
+    graph: nx.DiGraph, alpha: float = 0.85, iterations: int = 60, tol: float = 1.0e-8
+) -> dict[str, float]:
+    """Power-iteration PageRank in pure Python.
+
+    ``networkx.pagerank`` pulls in scipy and numpy - roughly 100 MB of wheels for
+    a CLI whose graphs have hundreds of nodes, not millions. Sixty iterations of
+    a dict-based power method is exact enough for a ranking and keeps the install
+    to three small dependencies.
+    """
+    nodes = list(graph.nodes)
+    if not nodes:
+        return {}
+    n = len(nodes)
+    rank_of = dict.fromkeys(nodes, 1.0 / n)
+    out_weight = {
+        u: sum(d.get("weight", 1) for _, _, d in graph.out_edges(u, data=True)) for u in nodes
+    }
+    dangling = [u for u in nodes if out_weight[u] == 0]
+
+    for _ in range(iterations):
+        previous = rank_of
+        leaked = alpha * sum(previous[u] for u in dangling) / n
+        rank_of = {u: (1.0 - alpha) / n + leaked for u in nodes}
+        for u, v, data in graph.edges(data=True):
+            if out_weight[u]:
+                rank_of[v] += alpha * previous[u] * data.get("weight", 1) / out_weight[u]
+        if sum(abs(rank_of[u] - previous[u]) for u in nodes) < tol * n:
+            break
+    return rank_of
+
+
+def _normalise(values: dict[str, float]) -> dict[str, float]:
+    if not values:
+        return {}
+    lo, hi = min(values.values()), max(values.values())
+    if math.isclose(lo, hi):
+        return dict.fromkeys(values, 0.0)
+    return {k: (v - lo) / (hi - lo) for k, v in values.items()}
+
+
+def rank(
+    graph: nx.DiGraph,
+    modules: dict[str, Module],
+    churn: dict[str, int],
+    weights: Weights,
+) -> list[Score]:
+    targets = [n for n in graph.nodes if not modules[n].is_test]
+    if not targets:
+        return []
+    # Edges point importer -> imported, so PageRank on the graph as-built already
+    # rewards "many things depend on me". Reversing it would rank the modules with
+    # the most imports, which is the opposite of what a newcomer needs.
+    scores_pr = pagerank(graph) if graph.number_of_edges() else {}
+
+    raw_centrality = {n: float(scores_pr.get(n, 0.0)) for n in targets}
+    raw_churn = {n: float(churn.get(modules[n].path, 0)) for n in targets}
+    raw_fan_in = {n: float(graph.in_degree(n)) for n in targets}
+    raw_size = {n: math.log1p(modules[n].loc) for n in targets}
+
+    norm_c = _normalise(raw_centrality)
+    norm_h = _normalise(raw_churn)
+    norm_f = _normalise(raw_fan_in)
+    norm_s = _normalise(raw_size)
+
+    scores: list[Score] = []
+    for name in targets:
+        total = (
+            weights.centrality * norm_c[name]
+            + weights.churn * norm_h[name]
+            + weights.fan_in * norm_f[name]
+            + weights.size * norm_s[name]
+        )
+        reasons = []
+        if norm_f[name] > 0.6:
+            reasons.append(f"imported by {int(raw_fan_in[name])} modules")
+        if norm_h[name] > 0.6:
+            reasons.append(f"{int(raw_churn[name])} commits in 18 months")
+        if norm_c[name] > 0.6:
+            reasons.append("high transitive reach")
+        if modules[name].loc > 400:
+            reasons.append(f"{modules[name].loc} lines")
+        scores.append(
+            Score(
+                module=name,
+                path=modules[name].path,
+                total=round(total, 4),
+                centrality=round(norm_c[name], 4),
+                churn=round(norm_h[name], 4),
+                fan_in=int(raw_fan_in[name]),
+                fan_out=int(graph.out_degree(name)),
+                loc=modules[name].loc,
+                reasons=reasons,
+            )
+        )
+    scores.sort(key=lambda s: (-s.total, s.module))
+    return scores