gitmole 0.3.0__py3-none-any.whl

gitmole/run.py

@@ -0,0 +1,407 @@
+"""Resolve the target, plan the tool invocations, and run them concurrently."""
+from __future__ import annotations
+
+import calendar
+import datetime as dt
+import importlib.util
+import json
+import os
+import re
+import signal
+import subprocess
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor, wait, FIRST_COMPLETED
+
+from . import blame, filetypes, identity
+
+MAAT_SCRIPT = os.path.join(os.path.dirname(os.path.realpath(__file__)), "maat.py")
+BLAME_SCRIPT = os.path.join(os.path.dirname(os.path.realpath(__file__)), "blame.py")
+FUNCTIONS_SCRIPT = os.path.join(os.path.dirname(os.path.realpath(__file__)), "functions.py")
+LEAKS_SCRIPT = os.path.join(os.path.dirname(os.path.realpath(__file__)), "leaks.py")
+# lizard's duplicate finder keeps a hash node per token, and every pool worker grows to 1.5-2 GB on a
+# large repo; the blame default (cores minus two) exhausted a 16 GB machine. Two workers is the ceiling
+# when it runs. Without it lizard is fast (well under a second per thousand files) and uses the blame workers.
+FUNCTIONS_MAX_PROCS = 2
+
+MONTH = 30 * 24 * 3600  # git-of-theseus sampling interval in seconds
+
+# Data-like files that inflate git-of-theseus without saying anything about code age.
+DATA_IGNORES = ["*.csv", "*.json", "*.lock", "*.min.js", "*.min.css", "*.svg", "*.map",
+                "vendor/**", "node_modules/**", "third_party/**", "dist/**", "build/**"]
+
+_ORG = re.compile(r"^[\w.-]+/\*$")
+_OWNER_REPO = re.compile(r"^[\w.-]+/[\w.-]+$")
+_URL = re.compile(r"^(https?://|git@|ssh://)")
+
+
+def classify_target(target: str) -> tuple:
+    if os.path.isdir(target):
+        return ("path", os.path.abspath(target))
+    if _ORG.match(target):
+        return ("org", target[:-2])
+    if _URL.match(target) or _OWNER_REPO.match(target):
+        return ("remote", target)
+    raise ValueError(f"{target!r} is neither a directory, owner/repo, nor a git URL")
+
+
+def repo_name(target: str) -> str:
+    tail = target.rstrip("/").rsplit("/", 1)[-1]
+    return tail[:-4] if tail.endswith(".git") else tail
+
+
+def output_dir(kind: str, repo_dir: str, explicit, cwd: str = None) -> str:
+    if explicit:
+        return os.path.abspath(explicit)
+    name = f"analysis-{repo_name(repo_dir)}"
+    base = os.path.dirname(repo_dir) if kind == "path" else (cwd or os.getcwd())
+    return os.path.join(base, name)
+
+
+class GhError(RuntimeError):
+    """gh failed; the message is its stderr."""
+
+
+def _gh(argv: list) -> str:
+    return subprocess.run(argv, check=True, capture_output=True, text=True).stdout
+
+
+def _wrap(fn, argv):
+    try:
+        return fn(argv)
+    except subprocess.CalledProcessError as e:
+        raise GhError((e.stderr or "").strip() or f"{' '.join(argv)} exited {e.returncode}") from None
+    except FileNotFoundError:
+        raise GhError("gh is not installed or not on PATH") from None
+
+
+def list_repos(owner: str, lister=_gh) -> list:
+    """Names of the owner's non-archived repositories via gh's REST calls. Raises GhError.
+
+    Your own account lists private repos too; an organisation uses the org endpoint
+    (private repos included where the token allows); anyone else gets public repos."""
+    me = _wrap(lister, ["gh", "api", "user", "--jq", ".login"]).strip()
+    if me == owner:
+        path = "user/repos?affiliation=owner&per_page=100"
+    else:
+        try:
+            _wrap(lister, ["gh", "api", f"orgs/{owner}", "--jq", ".login"])
+            path = f"orgs/{owner}/repos?per_page=100"
+        except GhError:
+            path = f"users/{owner}/repos?per_page=100"
+    out = _wrap(lister, ["gh", "api", "--paginate", path, "--jq", ".[] | select(.archived | not) | .name"])
+    return sorted(set(out.split()))
+
+
+def clone(target: str, dest_parent: str, runner=_gh) -> str:
+    """Clone a remote target with gh (so private repos use the existing auth). Raises GhError."""
+    dest = os.path.join(dest_parent, repo_name(target))
+    _wrap(runner, ["gh", "repo", "clone", target, dest, "--", "--quiet"])
+    return dest
+
+
+def env_path() -> str:
+    """PATH with pip's user bin dirs added."""
+    parts = []
+    lib = os.path.expanduser("~/Library/Python")
+    if os.path.isdir(lib):
+        parts += [os.path.join(lib, v, "bin") for v in sorted(os.listdir(lib), reverse=True)]
+    return os.pathsep.join(parts + [os.environ.get("PATH", "")])
+
+
+REQUIRED_TOOLS = ["scc", "git-sizer", "gitleaks"]
+PLOT_TOOLS = ["git-of-theseus-analyze"]
+
+
+def has_tool(name: str, path: str = None) -> bool:
+    path = env_path() if path is None else path
+    return any(os.access(os.path.join(d, name), os.X_OK) for d in path.split(os.pathsep) if d)
+
+
+def missing_tools(plots: bool = False, path: str = None) -> list:
+    path = env_path() if path is None else path
+    wanted = REQUIRED_TOOLS + (PLOT_TOOLS if plots else [])
+    return [t for t in wanted if not has_tool(t, path)]
+
+
+def has_lizard(finder=importlib.util.find_spec) -> bool:
+    """lizard is a Python module run with this interpreter, so PATH says nothing about it."""
+    return finder("lizard") is not None
+
+
+# Everything a run writes besides meta.json and run.log. Removed before each run so a reused
+# --out directory never shows a previous run's data as this run's (a step skipped or killed
+# this time would otherwise leave last time's file in place).
+OUTPUTS = ["size.json", "repo-health.txt", "secrets.json", "log.txt", "activity.json", "functions.csv", "duplicates.txt",
+           "theseus/cohorts.json", "theseus/authors.json", "theseus/survival.json", "code-age.png", "survival.png", "trend.json"]
+OUTPUT_GLOBS = ["maat-*.csv"]
+# directories a run writes: the backtest sub-report, and the temporary checkouts the trend and
+# backtest steps make under the output directory (a SIGKILL leaves those behind).
+OUTPUT_DIR_GLOBS = ["backtest", ".backtest-tree-*", ".trend-*"]
+
+
+def clear_outputs(out_dir: str) -> None:
+    import glob
+    import shutil
+    paths = [os.path.join(out_dir, n) for n in OUTPUTS]
+    for g in OUTPUT_GLOBS:
+        paths += glob.glob(os.path.join(out_dir, g))
+    for g in OUTPUT_DIR_GLOBS:
+        paths += glob.glob(os.path.join(out_dir, g))
+    for path in paths:
+        if os.path.isdir(path):
+            shutil.rmtree(path, ignore_errors=True)
+        elif os.path.isfile(path):
+            os.remove(path)
+
+
+def plan(repo_dir: str, out_dir: str, branch: str = "HEAD", age: bool = True, plots: bool = False,
+         procs: int = None, interval: int = MONTH, ignore=(), types: str = None, now: str = None, since: str = None,
+         lizard: bool = False, duplicates: bool = False, trend: bool = True, samples: int = 12, backtest: str = None) -> list:
+    o = lambda name: os.path.join(out_dir, name)  # noqa: E731
+    log = o("log.txt")
+    ignores = [x for pattern in ignore for x in ("--ignore", pattern)]
+    type_args = ["--types", types] if types else []
+    blame_argv = [sys.executable, BLAME_SCRIPT, repo_dir, out_dir, "--procs", str(procs or blame.default_procs()), *ignores, *type_args, "--aliases", o("meta.json")]
+    theseus_argv = ["git-of-theseus-analyze", ".", "--branch", branch, "--outdir", o("theseus"),
+                    "--procs", str(procs or os.cpu_count() or 2), "--interval", str(interval), *ignores]
+    steps = [
+        {"name": "scc", "argv": ["scc", "--by-file", "--format", "json"], "stdout": o("size.json"), "deps": []},
+        {"name": "git-sizer", "argv": ["git-sizer", "--verbose"], "stdout": o("repo-health.txt"), "deps": []},
+        {"name": "gitleaks", "argv": [sys.executable, LEAKS_SCRIPT, o("secrets.json")], "stdout": None, "deps": []},   # hashes the values before anything is written
+        {"name": "git-log", "argv": [*filetypes.GIT, "log", "--all", "--use-mailmap", "--numstat", "--date=iso-strict", "--pretty=format:--%h--%ad--%aN--%s", "--no-renames"], "stdout": log, "deps": []},
+        {"name": "change analysis", "argv": [sys.executable, MAAT_SCRIPT, log, out_dir, *type_args, *(["--now", now] if now else []), *(["--since", since] if since else []), "--aliases", o("meta.json")], "stdout": None, "deps": ["git-log"]},
+    ]
+    if lizard:
+        workers = procs or blame.default_procs()
+        if duplicates:
+            workers = min(workers, FUNCTIONS_MAX_PROCS)
+        steps.append({"name": "functions", "argv": [sys.executable, FUNCTIONS_SCRIPT, repo_dir, out_dir, "--procs", str(workers), *ignores, *type_args,
+                                                    *(["--duplicates"] if duplicates else [])],
+                      "stdout": None, "deps": []})
+    if trend:
+        steps.append({"name": "trend", "argv": [sys.executable, "-m", "gitmole.trend", out_dir, "--samples", str(samples)],
+                      "stdout": None, "deps": ["scc", "change analysis"]})
+    if backtest:
+        steps.append({"name": "backtest", "argv": [sys.executable, "-m", "gitmole.backtest", out_dir, "--until", backtest],
+                      "stdout": None, "deps": ["git-log", "change analysis"]})
+    if age:
+        steps.append({"name": "code age", "argv": blame_argv, "stdout": None, "deps": []})
+    if plots:
+        steps += [
+            {"name": "git-of-theseus", "argv": theseus_argv, "stdout": None, "deps": ["code age"] if age else []},
+            {"name": "theseus stack plot", "argv": ["git-of-theseus-stack-plot", o("theseus/cohorts.json"), "--outfile", o("code-age.png")], "stdout": None, "deps": ["git-of-theseus"]},
+            {"name": "theseus survival plot", "argv": ["git-of-theseus-survival-plot", o("theseus/survival.json"), "--outfile", o("survival.png")], "stdout": None, "deps": ["git-of-theseus"]},
+        ]
+    return steps
+
+
+_RELATIVE = re.compile(r"^(\d+)([ymd])$")
+
+
+def parse_since(spec: str, today: str) -> str:
+    """'2y' | '18m' | '90d' | 'YYYY-MM-DD' -> 'YYYY-MM-DD', relative to `today`. Raises ValueError."""
+    from . import maat
+
+    hint = "--since wants 2y, 18m, 90d or YYYY-MM-DD"
+    spec = (spec or "").strip().lower()
+    m = _RELATIVE.match(spec)
+    try:
+        if not m:
+            date = dt.date.fromisoformat(maat.validate_now(spec))
+        else:
+            n, unit = int(m.group(1)), m.group(2)
+            base = dt.date.fromisoformat(today)
+            if unit == "d":
+                date = base - dt.timedelta(days=n)
+            else:
+                months = n * 12 if unit == "y" else n
+                y, mo = base.year, base.month - months
+                while mo <= 0:
+                    y, mo = y - 1, mo + 12
+                date = dt.date(y, mo, min(base.day, calendar.monthrange(y, mo)[1]))
+    except (ValueError, OverflowError):
+        raise ValueError(f"{hint}, got {spec!r}") from None
+    if date.year < 1970:
+        raise ValueError(f"{hint}; git cannot represent dates before 1970, got {spec!r}")
+    return date.isoformat()
+
+
+class Control:
+    """Shared cancellation state: tracks running process groups so Ctrl-C can kill them all."""
+
+    def __init__(self):
+        self.cancelled = threading.Event()
+        self._procs = set()
+        self._lock = threading.Lock()
+
+    def register(self, proc):
+        with self._lock:
+            self._procs.add(proc)
+
+    def unregister(self, proc):
+        with self._lock:
+            self._procs.discard(proc)
+
+    def cancel(self):
+        self.cancelled.set()
+        with self._lock:
+            procs = list(self._procs)
+        for proc in procs:
+            _killpg(proc)
+
+
+def _killpg(proc):
+    try:
+        os.killpg(proc.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+
+def _run_step(argv, cwd, env, stdout, stderr, timeout, control: Control = None):
+    """Run one command in its own process group so a timeout or Ctrl-C can kill its children too.
+
+    stdin is /dev/null: these tools never need input, and letting them inherit an
+    interactive terminal as a new session leader corrupts the parent's tty (EIO)."""
+    proc = subprocess.Popen(argv, cwd=cwd, env=env, stdin=subprocess.DEVNULL,
+                            stdout=stdout, stderr=stderr, start_new_session=True)
+    if control:
+        control.register(proc)
+    try:
+        rc = proc.wait(timeout=timeout)
+        return "cancelled" if control and control.cancelled.is_set() else rc
+    except subprocess.TimeoutExpired:
+        _killpg(proc)
+        proc.wait()
+        return "timeout"
+    finally:
+        if control:
+            control.unregister(proc)
+
+
+def execute(steps: list, log_path: str, cwd: str = None, workers: int = 6, on_start=None, on_done=None,
+            timeout: float = None, control: Control = None) -> dict:
+    """Run steps concurrently, honouring deps. Returns {name: returncode | 'skipped' | 'timeout' | 'cancelled'}."""
+    results = {}
+    lock = threading.Lock()
+    package_parent = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+    env = dict(os.environ, PATH=env_path(),
+               PYTHONPATH=os.pathsep.join([package_parent] + [p for p in [os.environ.get("PYTHONPATH", "")] if p]))
+    pending = {s["name"]: s for s in steps}
+
+    def run_one(step):
+        if on_start:
+            on_start(step["name"])
+        with open(log_path, "a") as log:
+            log.write(f"\n==> {step['name']}: {' '.join(step['argv'])}\n")
+            log.flush()
+            out = open(step["stdout"], "w") if step["stdout"] else log
+            try:
+                rc = _run_step(step["argv"], cwd, env, out, log, timeout, control)
+                if rc == "timeout":
+                    log.write(f"==> {step['name']}: killed after {timeout}s timeout\n")
+            finally:
+                if step["stdout"]:
+                    out.close()
+        return step["name"], rc
+
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        futures = set()
+        while pending or futures:
+            for name in list(pending):
+                step = pending[name]
+                if control and control.cancelled.is_set():
+                    results[name] = "cancelled"
+                    del pending[name]
+                    if on_done:
+                        on_done(name, "cancelled")
+                elif any(results.get(d) not in (None, 0) for d in step["deps"]):
+                    results[name] = "skipped"
+                    del pending[name]
+                    if on_done:
+                        on_done(name, "skipped")
+                elif all(results.get(d) == 0 for d in step["deps"]):
+                    futures.add(pool.submit(run_one, step))
+                    del pending[name]
+            if not futures:
+                continue
+            done, futures = wait(futures, return_when=FIRST_COMPLETED)
+            for f in done:
+                name, rc = f.result()
+                with lock:
+                    results[name] = rc
+                if on_done:
+                    on_done(name, rc)
+    return results
+
+
+def _git(repo_dir: str, *args) -> str:
+    return subprocess.run(["git", *args], cwd=repo_dir, check=True, capture_output=True, text=True).stdout
+
+
+def estimate_blames(repo_dir: str, interval: int = MONTH, ignore=(), sample: int = 25, types=filetypes.DEFAULT) -> dict:
+    """Cost of the blame passes: a timed projection for the HEAD pass (seconds) and
+    tracked files times sampled commits for git-of-theseus (blames)."""
+    files = len(_git(repo_dir, "ls-files").splitlines())
+    times = [int(t) for t in _git(repo_dir, "log", "--format=%ct").split()]
+    span = (max(times) - min(times)) if times else 0
+    samples = min(len(times), span // interval + 1) if times else 0
+    projection = blame.estimate(repo_dir, ignore=ignore, sample=sample, types=types)
+    return {"files": files, "samples": samples, "blames": files * samples,
+            "seconds": projection["seconds"], "code_files": projection["files"]}
+
+
+def collect_meta(repo_dir: str, since: str = None) -> dict:
+    """Repository facts from git. The window (author date >= since) bounds the commit count, the
+    date range and the identity table; aliases are merged over the whole history so blame and
+    ownership keep merging people who have no commits in the window, and `first_date_all` keeps the
+    date of the first commit of all so the backtest can still measure the whole history. Bots
+    (renovate, dependabot, GitHub Actions and anything named *[bot]) are counted apart under
+    "bots", not as identities."""
+    from collections import Counter
+
+    from .load import parse_authors_log
+
+    lines = _git(repo_dir, "log", "--all", "--use-mailmap", "--format=%ad\t%aN\t%aE", "--date=short").splitlines()
+    all_rows = [l.split("\t", 2) for l in lines if l.count("\t") == 2]
+    rows = [r for r in all_rows if not identity.is_bot(r[1], r[2])]
+    all_windowed = [r for r in all_rows if not since or r[0] >= since]
+    windowed = [r for r in all_windowed if not identity.is_bot(r[1], r[2])]
+    dates = [r[0] for r in all_windowed]
+    all_dates = [r[0] for r in all_rows]
+    bots = Counter(n for _, n, e in all_windowed if identity.is_bot(n, e))
+    all_identities = identity.merge(parse_authors_log("\n".join(f"{n}\t{e}" for _, n, e in rows)))
+    meta = {
+        "name": repo_name(repo_dir),
+        "path": repo_dir,
+        "branch": _git(repo_dir, "rev-parse", "--abbrev-ref", "HEAD").strip(),
+        "commits": len(dates),
+        "first_date": min(dates) if dates else "",
+        "first_date_all": min(all_dates) if all_dates else "",   # unwindowed: the backtest asks how long the history is
+        "last_date": max(dates) if dates else "",
+        "identities": identity.merge(parse_authors_log("\n".join(f"{n}\t{e}" for _, n, e in windowed))),
+        "bots": [{"name": n, "commits": c} for n, c in sorted(bots.items(), key=lambda kv: (-kv[1], kv[0]))],
+        "aliases": {a["name"]: i["name"] for i in all_identities for a in i.get("aliases", [])},
+    }
+    if since:
+        meta["since"] = since
+    return meta
+
+
+def changed_files(repo_dir: str, base: str) -> list:
+    """Paths that differ between the merge base with `base` and HEAD, sorted. ValueError when git refuses."""
+    proc = subprocess.run([*filetypes.GIT, "diff", "-z", "--name-only", f"{base}...HEAD"], cwd=repo_dir, capture_output=True)
+    if proc.returncode != 0:
+        raise ValueError((proc.stderr.decode("utf-8", "replace").strip() or f"git diff {base}...HEAD failed"))
+    return sorted(p.decode("utf-8", "surrogateescape") for p in proc.stdout.split(b"\0") if p)
+
+
+def save_meta(meta: dict, out_dir: str) -> None:
+    with open(os.path.join(out_dir, "meta.json"), "w") as fh:
+        json.dump(meta, fh, indent=2)
+
+
+def write_meta(repo_dir: str, out_dir: str) -> dict:
+    meta = collect_meta(repo_dir)
+    save_meta(meta, out_dir)
+    return meta

gitmole/textfmt.py

@@ -0,0 +1,91 @@
+"""Small text helpers that make the report easier to read: path elision, finding grouping, tallies."""
+from __future__ import annotations
+
+import re
+
+ELLIPSIS = "…"
+
+
+def shorten_path(path: str, max_len: int) -> str:
+    """Elide middle directories so the path fits, keeping the file name whole:
+    a/b/c/d/e.py -> a/…/d/e.py -> …/d/e.py -> …/e.py."""
+    if len(path) <= max_len or "/" not in path:
+        return path
+    parts = path.split("/")
+    candidates = [f"{parts[0]}/{ELLIPSIS}/" + "/".join(parts[-2:])] if len(parts) > 3 else []
+    if len(parts) > 2:
+        candidates.append(f"{ELLIPSIS}/" + "/".join(parts[-2:]))
+    candidates.append(f"{ELLIPSIS}/{parts[-1]}")
+    for c in candidates:
+        if len(c) <= max_len:
+            return c
+    return candidates[-1]
+
+
+def times(n: int) -> str:
+    """How often something happened, in words for the small numbers: once, twice, 3 times."""
+    return {1: "once", 2: "twice"}.get(n, f"{n} times")
+
+
+_ADVICE_VERBS = ("Add ", "Set ", "Rotate ", "Pair ", "Rerun ", "Expect ", "Consider ", "Use ", "Review ", "Merge ", "Split ", "Move ", "Extract ")
+_SENTENCE_END = re.compile(r"(?<=[.!?])\s+(?=[A-Z])")
+
+
+def split_advice(detail: str):
+    """(statement, advice): the last sentence is advice when it is an instruction and there is
+    more than one sentence. The statement loses its trailing period only when advice was split off."""
+    sentences = _SENTENCE_END.split(detail.strip())
+    if len(sentences) < 2 or not sentences[-1].startswith(_ADVICE_VERBS):
+        return detail.strip(), None
+    statement = " ".join(sentences[:-1]).rstrip(".")
+    return statement, sentences[-1]
+
+
+def _statement_and_advice(f: dict):
+    """A finding's facts and its next step. Rules say which part is the advice; for a finding
+    without that field (older JSON, a hand-made dict) the last sentence is taken when it is an
+    instruction."""
+    detail = f["detail"].strip()
+    advice = f.get("advice")
+    if advice:
+        statement = detail[:-len(advice)].rstrip() if detail.endswith(advice) else detail
+        return statement.rstrip("."), advice
+    return split_advice(detail)
+
+
+def group_findings(findings: list) -> list:
+    """Merge findings that share a title into one entry with an item list and the distinct next
+    steps its items carry, in first-seen order. Order: by severity, then first appearance."""
+    order = {"critical": 0, "warning": 1, "info": 2}
+    groups, index = [], {}
+    for f in findings:
+        statement, advice = _statement_and_advice(f)
+        key = f["title"]
+        if key not in index:
+            index[key] = len(groups)
+            groups.append({"severity": f["severity"], "title": key, "items": [], "advice": []})
+        g = groups[index[key]]
+        g["items"].append(statement)
+        if advice and advice not in g["advice"]:
+            g["advice"].append(advice)
+        if order[f["severity"]] < order[g["severity"]]:
+            g["severity"] = f["severity"]
+    for g in groups:
+        if len(g["items"]) > 1:
+            g["title"] = f"{g['title']} ({len(g['items'])})"
+    groups.sort(key=lambda g: order[g["severity"]])
+    return groups
+
+
+def tally(findings: list) -> str:
+    counts = {"critical": 0, "warning": 0, "info": 0}
+    for f in findings:
+        counts[f["severity"]] += 1
+    parts = []
+    if counts["critical"]:
+        parts.append(f"{counts['critical']} critical")
+    if counts["warning"]:
+        parts.append(f"{counts['warning']} warning" + ("s" if counts["warning"] != 1 else ""))
+    if counts["info"]:
+        parts.append(f"{counts['info']} note" + ("s" if counts["info"] != 1 else ""))
+    return ", ".join(parts) if parts else "nothing flagged"

gitmole/trend.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Complexity over time for the top hotspots: scc on each file's contents at sampled commits.
+
+Runs as a pipeline step: `python -m gitmole.trend OUT_DIR [--repo DIR] [--samples N] [--top N]`,
+from inside the repository (or with --repo). Reads size.json and maat-revisions.csv the earlier
+steps wrote, picks the top hotspots still in the tree, and writes trend.json:
+{"samples": [DATE, ...], "files": {PATH: [[DATE, complexity, code], ...]}}.
+
+The pure helpers below are also what the renderer and the findings use."""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import subprocess
+import sys
+import tempfile
+
+from . import filetypes, hotspots, load, maat
+
+BLOCKS = "▁▂▃▄▅▆▇█"
+
+
+def sample_dates(first: str, last: str, n: int) -> list:
+    a, b = dt.date.fromisoformat(first), dt.date.fromisoformat(last)
+    if b <= a:
+        return [last]
+    span = (b - a).days
+    n = max(2, min(n, span // 28 + 1))
+    out = [(a + dt.timedelta(days=round(span * i / (n - 1)))).isoformat() for i in range(n)]
+    out[-1] = last
+    return out
+
+
+def change_over_year(series: list, last_date: str) -> str:
+    if len(series) < 2:
+        return "-"
+    year_ago = maat.months_before(last_date, 12)
+    before = [s for s in series if s[0] <= year_ago]
+    base = before[-1] if before else series[0]
+    then, now = base[1], series[-1][1]
+    if not then:
+        return "-"
+    pct = round(100 * (now - then) / then)
+    if abs(pct) < 10:
+        return "="
+    return f"{pct:+d}%"
+
+
+def sparkline(series: list) -> str:
+    """One block per sample, scaled between the smallest and the largest. Fewer than two samples
+    draw nothing: a single block would read as a flat trend nobody measured."""
+    values = [s[1] for s in series]
+    if len(values) < 2:
+        return ""
+    lo, hi = min(values), max(values)
+    if hi == lo:
+        return BLOCKS[0] * len(values)
+    return "".join(BLOCKS[int((v - lo) / (hi - lo) * (len(BLOCKS) - 1))] for v in values)
+
+
+def rev_before(repo: str, date: str, end_of_day: bool = True):
+    """The last commit at or before `date` by committer date, or None when there is none.
+
+    The two callers want different edges of the day. A trend sample is "the code as it stood on
+    that date", so it takes everything committed during the day (T23:59:59). The backtest asks
+    "what did we know before T", so it must stop as the day begins (T00:00:00) and leave the
+    commits made on T itself to the future it is being scored against.
+
+    Raises RuntimeError with git's own message when git fails: an unreadable repository is not
+    the same answer as a history that does not reach back that far."""
+    bound = f"{date}T23:59:59" if end_of_day else f"{date}T00:00:00"
+    proc = subprocess.run(["git", "rev-list", "-1", f"--before={bound}", "HEAD"], cwd=repo, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise RuntimeError((proc.stderr or "").strip().splitlines()[0] if (proc.stderr or "").strip()
+                           else f"git rev-list --before={bound} exited {proc.returncode}")
+    return proc.stdout.strip() or None
+
+
+def measure(repo: str, rev: str, files: list, out_dir: str) -> dict:
+    """{path: (complexity, code)} for the files that exist at rev, from one scc run over their contents.
+
+    The copies go under `out_dir`, not the system temp directory, so a SIGKILL leaves them where
+    the next run's clear_outputs finds them instead of filling /tmp."""
+    out = {}
+    with tempfile.TemporaryDirectory(dir=out_dir, prefix=".trend-") as tmp:
+        present = []
+        for path in files:
+            proc = subprocess.run([*filetypes.GIT, "show", f"{rev}:{path}"], cwd=repo, capture_output=True)
+            if proc.returncode != 0:
+                continue
+            target = os.path.join(tmp, path)
+            os.makedirs(os.path.dirname(target), exist_ok=True)
+            with open(target, "wb") as fh:
+                fh.write(proc.stdout)
+            present.append(path)
+        if not present:
+            return out
+        scc = subprocess.run(["scc", "--by-file", "--format", "json"], cwd=tmp, capture_output=True, text=True)
+        if scc.returncode != 0:
+            return out
+        for path, info in load.parse_scc(scc.stdout)["files"].items():
+            out[path] = (info["complexity"], info["code"])
+    return out
+
+
+def top_files(out_dir: str, n: int) -> list:
+    meta = json.loads(load._read(out_dir, "meta.json") or "{}")
+    size = load.parse_scc(load._read(out_dir, "size.json"), filetypes.parse(meta["file_types"]) if "file_types" in meta else None)
+    revisions = load.parse_maat_csv(load._read(out_dir, "maat-revisions.csv"))
+    ranked = hotspots.ranked({"size": size, "revisions": revisions})
+    return [h["entity"] for h in ranked if h["code"] is not None][:n]
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("out")
+    p.add_argument("--repo", default=".")
+    p.add_argument("--samples", type=int, default=12)
+    p.add_argument("--top", type=int, default=10)
+    args = p.parse_args(argv)
+    meta = json.loads(load._read(args.out, "meta.json") or "{}")
+    if not (meta.get("first_date") and meta.get("last_date") and os.path.exists(os.path.join(args.out, "size.json"))
+            and os.path.exists(os.path.join(args.out, "maat-revisions.csv"))):
+        print("trend: meta.json with dates, size.json and maat-revisions.csv are needed", file=sys.stderr)
+        return 2
+    files = top_files(args.out, args.top)
+    dates = sample_dates(meta["first_date"], meta["last_date"], args.samples)
+    series = {f: [] for f in files}
+    for date in dates:
+        try:
+            rev = rev_before(args.repo, date)
+        except RuntimeError as e:
+            print(f"trend: {e}", file=sys.stderr)
+            return 2
+        if not rev:
+            continue
+        for path, (cplx, code) in measure(args.repo, rev, files, args.out).items():
+            series[path].append([date, cplx, code])
+    data = {"samples": dates, "files": series}
+    fd, tmp = tempfile.mkstemp(dir=args.out, prefix=".trend-", suffix=".json")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh)
+        os.replace(tmp, os.path.join(args.out, "trend.json"))
+    finally:
+        if os.path.exists(tmp):
+            os.remove(tmp)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())