blot-git 0.2.0__tar.gz → 0.3.0__tar.gz

{blot_git-0.2.0 → blot_git-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blot-git
-Version: 0.2.0
+Version: 0.3.0
 Summary: A pre-commit check that has read your project's history: warns when a change removes a fix, re-adds a fixed bug, or forgets a file that always changes too.
 Project-URL: Homepage, https://github.com/Sym-jay/Blot
 Project-URL: Issues, https://github.com/Sym-jay/Blot/issues
@@ -42,6 +42,8 @@ pip install blot-git
 cd your-repo
 blot index           # one-time, builds .git/blot.db
 blot install-hook    # adds Blot to your pre-commit hook
+blot why src/app.py:42   # which commit explains this line, skipping refactors
+blot index --github  # optional: issue/PR titles and labels via the gh CLI
 ```
 
 > **Status:** pre-alpha. All three checks work. Replayed on 500 recent commits each of Flask, requests, Express, Django and React, Blot warns on 0.6–10% of commits; see the bench results on GitHub. Please report false alarms.

{blot_git-0.2.0 → blot_git-0.3.0}/README.md

@@ -59,6 +59,34 @@ Remove it any time with `blot install-hook --uninstall`. Settings go in `[tool.b
 
 Or with the [pre-commit](https://pre-commit.com) framework, see `.pre-commit-hooks.yaml`.
 
+## Ask why a line exists
+
+```
+$ blot why src/flask/app.py:355
+src/flask/app.py:355
+  | self_ref = weakref.ref(self)
+  explained by  8efea0cc  2020-10-03  Break reference cycle created by default in Flask instances.  [bug fix]
+  traced past   0ec7f713  2023-06-11  Split the App and Blueprint into Sansio and IO parts  [refactor]
+```
+
+`blot why FILE:LINE` (or `FILE:START-END`) finds the commit that explains a line, skipping commits that only moved it. Plain `git blame` stops at the refactor.
+
+## Issue and PR titles (optional)
+
+```bash
+blot index --github
+```
+
+With the [GitHub CLI](https://cli.github.com) logged in, Blot fetches the titles and labels of the issues and PRs your fix commits mention, so warnings read `fixes #2935 "copy_current_request_context copies old session object"` (a real Flask issue) instead of a bare number. A `bug` label makes a commit count as a load-bearing fix; a fix-looking commit whose issues are only labelled `enhancement` or `documentation` is demoted. Refreshes only fetch what's new. Repos with GitHub Issues turned off (they track bugs elsewhere) are skipped.
+
+## Measure it on your repo
+
+```bash
+blot bench --replay 500
+```
+
+Re-checks your last 500 commits as if each were being committed, and lists every warning Blot would have shown. See [bench/README.md](bench/README.md).
+
 ## Docs
 
 - [What is this? (simple explanation)](docs/EXPLAINER.md)

{blot_git-0.2.0 → blot_git-0.3.0}/docs/PRD.md

@@ -190,8 +190,8 @@ The user either reads the linked issue and adjusts the change, or commits anyway
 |---|---|---|
 | 1 | **M1: index + config + hook installer** | `blot index` builds the DB on Flask in under 10 s; `install-hook` is safe with existing hooks |
 | 2 | **M2: three checks** | All unit tests pass, including the "trace past refactor" test (currently skipped) |
-| 3 | **M3: `why` + `--github` + output polish** | The Flask case prints the 2020 fix with the #3761 link |
-| 4 | **M4: bench + launch** | 30 bench cases, precision ≥ 80%, PyPI release, README GIF, Show HN / r/Python post |
+| 3 | **M3: `why` + `--github` + output polish** ✅ | The Flask case prints the 2020 fix, traced past the 2023 refactor; `--github` adds issue titles and labels |
+| 4 | **M4: bench + launch** (bench ✅, launch pending) | 30 bench cases, precision ≥ 80%, PyPI release, README GIF, Show HN / r/Python post |
 
 ## 13. Open questions
 

{blot_git-0.2.0 → blot_git-0.3.0}/docs/PYPI.md

@@ -17,6 +17,8 @@ pip install blot-git
 cd your-repo
 blot index           # one-time, builds .git/blot.db
 blot install-hook    # adds Blot to your pre-commit hook
+blot why src/app.py:42   # which commit explains this line, skipping refactors
+blot index --github  # optional: issue/PR titles and labels via the gh CLI
 ```
 
 > **Status:** pre-alpha. All three checks work. Replayed on 500 recent commits each of Flask, requests, Express, Django and React, Blot warns on 0.6–10% of commits; see the bench results on GitHub. Please report false alarms.

{blot_git-0.2.0 → blot_git-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "blot-git"
-version = "0.2.0"
+version = "0.3.0"
 description = "A pre-commit check that has read your project's history: warns when a change removes a fix, re-adds a fixed bug, or forgets a file that always changes too."
 readme = "docs/PYPI.md"  # text-only; the GitHub README's relative Sora images break on PyPI
 license = { text = "MIT" }

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/__init__.py

@@ -1,3 +1,3 @@
 """blot: history-aware pre-commit checks."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/bench.py

@@ -50,6 +50,9 @@ class _ReplayStore:
     def get_commit(self, sha: str) -> CommitRow | None:
         return self._full.get_commit(sha)
 
+    def describe_issue(self, ref: str) -> str:
+        return self._full.describe_issue(ref)
+
     def fixes_that_removed(self, line_hash: str) -> list[tuple[str, str]]:
         return [(p, s) for p, s in self._full.fixes_that_removed(line_hash) if self._is_ancestor(s)]
 

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/checks/base.py

@@ -53,9 +53,13 @@ def is_skipped(path: str, config: Config) -> bool:
     return any(fnmatch(path, p) for p in patterns)
 
 
-def describe_commit(row: CommitRow) -> str:
-    """Evidence line: 'abc1234 "subject" (2020-10-03, fixes #3761)'."""
+def describe_commit(row: CommitRow, store: Store | None = None) -> str:
+    """Evidence line: '8efea0c "subject" (2020-10-03, fixes #3761 "Memory leak in app")'.
+
+    Issue titles appear once `blot index --github` has fetched them.
+    """
     details = [row.date[:10]]
     if row.issues:
-        details.append("fixes " + ", ".join(row.issues))
+        refs = [store.describe_issue(ref) for ref in row.issues] if store else row.issues
+        details.append("fixes " + ", ".join(refs))
     return f'{row.sha[:7]} "{row.subject}" ({", ".join(details)})'

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/checks/readded_bug.py

@@ -61,6 +61,6 @@ class ReaddedBug(Check):
                     self.id, change.path, number,
                     "You're adding back a line that a bug fix removed.\n"
                     "Check that this doesn't bring the bug back.",
-                    [describe_commit(row)], row.severity,
+                    [describe_commit(row, store)], row.severity,
                 ))
         return findings

blot_git-0.3.0/src/blot/checks/removed_fix.py

@@ -0,0 +1,62 @@
+"""Check 1: you're deleting or editing lines that a load-bearing bug fix added.
+
+Algorithm:
+    1. for each file, take the removed lines (old line numbers)
+    2. `git blame -w -M -C --porcelain -L a,b HEAD -- <old_path>` for those ranges
+    3. if the blamed commit is a refactor (classify.is_refactor), re-blame at its parent
+       on the original path, up to 3 hops
+    4. warn if the final commit's severity >= config.min_severity
+
+"The original path" is found in the refactor's own diff: the line it deleted with the same
+normalized text, preferring the same path. That is how a file split is followed back.
+"""
+
+from __future__ import annotations
+
+from blot.checks.base import Check, Finding, describe_commit, is_skipped
+from blot.diff import KeptLines, is_meaningful_line, normalize_line
+from blot.trace import RefactorOrigins, trace_lines
+
+class RemovedFix(Check):
+    id = "removed-fix"
+    description = "Changing code that a bug fix added"
+
+    def run(self, changes, store, config) -> list[Finding]:
+        origins = RefactorOrigins(store.repo)
+        findings: list[Finding] = []
+        # a line that reappears anywhere in the change was moved, not removed
+        moved = {normalize_line(text) for c in changes for _, text in c.added}
+        for change in changes:
+            if change.old_path is None or not change.removed or is_skipped(change.old_path, config):
+                continue
+            # reformatted or extended in place (quotes, wrapping, type hints): not removed either
+            kept = KeptLines([text for _, text in change.added])
+            # blank, generic (imports, `return`) and prose lines say nothing about the fix
+            texts = {
+                n: t for n, t in change.removed
+                if is_meaningful_line(normalize_line(t)) and normalize_line(t) not in moved and not kept.keeps(t)
+            }
+            if not texts:
+                continue
+
+            trail = trace_lines(store, store.rev, change.old_path, texts, origins)
+
+            reported: set[str] = set()
+            for n in sorted(trail):
+                sha, via = trail[n].sha, trail[n].via
+                row = store.get_commit(sha)
+                if row is None or row.is_refactor or row.severity < config.min_severity or sha in reported:
+                    continue
+                reported.add(sha)  # one finding per fix per file, at its first line
+                evidence = [describe_commit(row, store)]
+                for ref_sha in via:
+                    ref = store.get_commit(ref_sha)
+                    if ref is not None:
+                        evidence.append(f'traced past refactor {ref_sha[:7]} "{ref.subject}"')
+                findings.append(Finding(
+                    self.id, change.old_path, n,
+                    "You're removing or changing a line that a bug fix added.\n"
+                    "Check that the bug it fixed can't come back.",
+                    evidence, row.severity,
+                ))
+        return findings

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/classify.py

@@ -122,6 +122,29 @@ def is_refactor(commit: CommitInfo) -> bool:
     return big and balanced
 
 
+_BUG_LABEL = re.compile(r"\b(?:bug|regression|security|crash|defect|vulnerability|cve)\b", re.IGNORECASE)
+_NOT_BUG_LABEL = re.compile(
+    r"\b(?:enhancement|feature|feature request|documentation|docs|question|chore|refactor\w*|"
+    r"dependencies|ci|tests?|cleanup|performance)\b",
+    re.IGNORECASE,
+)
+
+
+def adjust_for_labels(subject: str, severity: int, labels: list[str]) -> int:
+    """Re-judge a commit using its issues' labels (from `blot index --github`).
+
+    A bug-type label makes it load-bearing. Only "not a bug" labels (enhancement, docs, ...) demote
+    a fix-looking commit to routine, unless its subject names a real defect (crash, leak, CVE...).
+    """
+    if not labels:
+        return severity
+    if any(_BUG_LABEL.search(label) for label in labels):
+        return max(severity, 2)
+    if severity >= 2 and all(_NOT_BUG_LABEL.search(label) for label in labels) and not _DEFECT.search(subject):
+        return 1
+    return severity
+
+
 def linked_issues(commit: CommitInfo) -> list[str]:
     """Issue references in the message, in order, without duplicates."""
     seen: dict[str, None] = {}

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/cli.py

@@ -22,11 +22,23 @@ from blot.report import render
 def _cmd_index(args: argparse.Namespace) -> int:
     from blot.index import build_index
 
-    result = build_index(args.repo, full=args.full, github=args.github)
+    result = build_index(args.repo, full=args.full)
     if not args.quiet:
         kind = "full" if result.full else "incremental"
         print(f"blot: indexed {result.commits} commits ({result.fixes} load-bearing fixes), "
               f"{kind}, in {result.seconds:.1f}s")
+    if args.github:
+        from blot.github import enrich
+        from blot.store import Store
+
+        store = Store.open(args.repo)
+        got = enrich(args.repo, store)
+        store.close()
+        if got.status != "ok":
+            print(f"blot: --github skipped: {got.status}", file=sys.stderr)
+        elif not args.quiet:
+            print(f"blot: GitHub: {got.fetched} issues/PRs fetched ({got.missing} not found); "
+                  f"{got.upgraded} commits upgraded to bug fix, {got.demoted} demoted by their labels")
     return 0
 
 
@@ -51,7 +63,22 @@ def _cmd_check(args: argparse.Namespace) -> int:
 
 
 def _cmd_why(args: argparse.Namespace) -> int:
-    raise NotImplementedError("TODO(M3): trace a line to its explaining commits")
+    from blot.store import Store
+    from blot.why import WhyError, explain, render
+
+    store = Store.open(args.repo)
+    if store is None:
+        print("blot: no index yet, run `blot index` first", file=sys.stderr)
+        return 1
+    try:
+        path, explained = explain(store, args.location, args.rev)
+    except WhyError as exc:
+        print(f"blot: {exc}", file=sys.stderr)
+        return 1
+    text = render(store, path, explained)
+    store.close()
+    print(text, end="")
+    return 0
 
 
 def _cmd_install_hook(args: argparse.Namespace) -> int:
@@ -101,7 +128,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     p = sub.add_parser("index", help="build or refresh the local history index")
     p.add_argument("--full", action="store_true", help="rebuild from scratch instead of incrementally")
-    p.add_argument("--github", action="store_true", help="add PR/issue data via the gh CLI (milestone M3)")
+    p.add_argument("--github", action="store_true", help="also fetch issue/PR titles and labels with the gh CLI")
     p.add_argument("--quiet", action="store_true", help="print nothing on success (for git hooks)")
     p.set_defaults(func=_cmd_index)
 
@@ -112,8 +139,9 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--format", choices=["text", "json"], default="text")
     p.set_defaults(func=_cmd_check)
 
-    p = sub.add_parser("why", help="show the history behind a line")
-    p.add_argument("location", metavar="FILE:LINE")
+    p = sub.add_parser("why", help="show the commit that explains a line, past refactors")
+    p.add_argument("location", metavar="FILE:LINE", help="e.g. src/app.py:42 or src/app.py:40-48")
+    p.add_argument("--rev", default="HEAD", help="explain the file as of this commit (default: HEAD)")
     p.set_defaults(func=_cmd_why)
 
     p = sub.add_parser("install-hook", help="add blot to .git/hooks/pre-commit")

blot_git-0.3.0/src/blot/github.py

@@ -0,0 +1,131 @@
+"""`blot index --github`: issue and PR titles and labels, fetched with the user's `gh` login.
+
+Only commits that look like fixes are looked up, in batches of 50 per GraphQL call, and refs that are
+already stored are skipped, so a refresh costs nothing until new fixes land. Labels sharpen fix
+detection: a `bug`/`regression`/`security` label makes a commit load-bearing, while a fix-looking
+commit whose issues are only labelled `enhancement`/`documentation` is demoted.
+
+Nothing is sent anywhere except GitHub's API, through `gh`. Repos with GitHub Issues disabled are
+skipped: their `#N` refs usually point at another tracker (Django uses Trac), and looking them up on
+GitHub would attach the wrong titles.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from blot.classify import adjust_for_labels
+from blot.git import run_git
+from blot.store import Store
+
+BATCH = 50
+_REMOTE = re.compile(r"github\.com[:/](?P<owner>[\w.-]+)/(?P<name>[\w.-]+?)(?:\.git)?/?$")
+_NUMBER = re.compile(r"^(?:#|gh-)(\d+)$", re.IGNORECASE)
+
+Runner = Callable[[str], dict]  # GraphQL query -> parsed JSON response
+
+
+@dataclass
+class EnrichResult:
+    status: str  # "ok", or why nothing was fetched
+    fetched: int = 0
+    missing: int = 0
+    upgraded: int = 0
+    demoted: int = 0
+
+
+def github_repo(repo: str) -> tuple[str, str] | None:
+    for remote in ("origin", "upstream"):
+        try:
+            url = run_git(repo, "remote", "get-url", remote).strip()
+        except subprocess.CalledProcessError:
+            continue
+        m = _REMOTE.search(url)
+        if m:
+            return m.group("owner"), m.group("name")
+    return None
+
+
+def gh_runner(query: str) -> dict:
+    """Run a GraphQL query through `gh`. Partial results (some refs not found) still parse."""
+    done = subprocess.run(["gh", "api", "graphql", "-f", f"query={query}"], capture_output=True,
+                          text=True, encoding="utf-8", errors="replace")
+    if not done.stdout.strip():
+        raise RuntimeError(done.stderr.strip() or "gh api graphql failed")
+    return json.loads(done.stdout)
+
+
+def _label_names(node: dict) -> list[str]:
+    return [n["name"] for n in (node.get("labels") or {}).get("nodes", [])]
+
+
+_FIELDS = "title labels(first: 10) { nodes { name } }"
+
+
+def _query(owner: str, name: str, numbers: list[int]) -> str:
+    parts = [
+        f"n{n}: issueOrPullRequest(number: {n}) {{ __typename "
+        f"... on Issue {{ {_FIELDS} }} "
+        f"... on PullRequest {{ {_FIELDS} closingIssuesReferences(first: 5) {{ nodes {{ {_FIELDS} }} }} }} }}"
+        for n in numbers
+    ]
+    return f'{{ repository(owner: "{owner}", name: "{name}") {{ hasIssuesEnabled {" ".join(parts)} }} }}'
+
+
+def enrich(repo: str, store: Store, runner: Runner | None = None) -> EnrichResult:
+    found = github_repo(repo)
+    if found is None:
+        return EnrichResult("no GitHub remote (origin or upstream)")
+    if runner is None:
+        if shutil.which("gh") is None:
+            return EnrichResult("the GitHub CLI `gh` isn't installed (https://cli.github.com)")
+        runner = gh_runner
+    owner, name = found
+
+    fixes = store.commits_with_issues(min_severity=1)
+    known = store.known_issue_refs()
+    wanted = sorted({ref for row in fixes for ref in row.issues if _NUMBER.match(ref) and ref not in known})
+
+    result = EnrichResult("ok")
+    for i in range(0, len(wanted), BATCH):
+        batch = wanted[i:i + BATCH]
+        numbers = [int(_NUMBER.match(ref).group(1)) for ref in batch]
+        try:
+            data = (runner(_query(owner, name, numbers)).get("data") or {}).get("repository") or {}
+        except (RuntimeError, json.JSONDecodeError) as exc:
+            return EnrichResult(f"GitHub lookup failed: {exc}", result.fetched, result.missing)
+        if i == 0 and data.get("hasIssuesEnabled") is False:
+            return EnrichResult(f"GitHub Issues are disabled for {owner}/{name}; its #N refs probably point to "
+                                "another tracker, so they were not looked up")
+        rows = []
+        for ref, n in zip(batch, numbers):
+            node = data.get(f"n{n}")
+            if not node:
+                rows.append((ref, "", [], "missing"))
+                result.missing += 1
+                continue
+            labels = _label_names(node)
+            for linked in (node.get("closingIssuesReferences") or {}).get("nodes", []):
+                labels += _label_names(linked)
+            kind = "pr" if node["__typename"] == "PullRequest" else "issue"
+            rows.append((ref, node.get("title", ""), sorted(set(labels)), kind))
+            result.fetched += 1
+        store.add_issues(rows)
+
+    # re-judge every fix-looking commit with what its issues' labels say
+    for row in fixes:
+        labels = [label for ref in row.issues if (got := store.issue(ref)) for label in got[1]]
+        new = adjust_for_labels(row.subject, row.severity, labels)
+        if new != row.severity:
+            store.set_severity(row.sha, new)
+            if new > row.severity:
+                result.upgraded += 1
+            else:
+                result.demoted += 1
+    store.commit()
+    return result

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/index.py

@@ -105,7 +105,6 @@ def _removed_lines(repo: str, shas: list[str]) -> list[tuple[str, str, str]]:
 def build_index(
     repo: str,
     full: bool = False,
-    github: bool = False,
     config: Config | None = None,
     upto: str = "HEAD",
     db_path: str | None = None,
@@ -147,6 +146,4 @@ def build_index(
     store.set_meta("last_sha", head)
     store.commit()
     store.close()
-    if github:
-        print("blot: --github enrichment arrives in milestone M3; indexed git history only.")
     return IndexResult(len(parsed), len(fix_shas), time.perf_counter() - start, rebuild)

{blot_git-0.2.0 → blot_git-0.3.0}/src/blot/store.py

@@ -16,7 +16,7 @@ from dataclasses import dataclass
 
 from blot.git import git_dir
 
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2  # 2: issues table (blot index --github)
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
@@ -30,6 +30,7 @@ CREATE TABLE IF NOT EXISTS file_commits (path TEXT PRIMARY KEY, count INTEGER);
 CREATE TABLE IF NOT EXISTS cochange (
     path_a TEXT, path_b TEXT, support INTEGER, PRIMARY KEY (path_a, path_b)
 );
+CREATE TABLE IF NOT EXISTS issues (ref TEXT PRIMARY KEY, title TEXT, labels TEXT, kind TEXT);
 """
 
 
@@ -163,6 +164,38 @@ class Store:
         ]
         return sorted(result, key=lambda r: (-r[2], -r[1], r[0]))
 
+    # --- issues and PRs (blot index --github) ----------------------------------------------
+
+    def add_issues(self, rows: list[tuple[str, str, list[str], str]]) -> None:
+        """(ref like "#3761", title, labels, kind "issue"/"pr"/"missing")."""
+        self.conn.executemany(
+            "INSERT OR REPLACE INTO issues VALUES (?, ?, ?, ?)",
+            [(ref, title, ",".join(labels), kind) for ref, title, labels, kind in rows],
+        )
+
+    def known_issue_refs(self) -> set[str]:
+        return {r[0] for r in self.conn.execute("SELECT ref FROM issues")}
+
+    def issue(self, ref: str) -> tuple[str, list[str]] | None:
+        row = self.conn.execute("SELECT title, labels, kind FROM issues WHERE ref=?", (ref,)).fetchone()
+        if row is None or row[2] == "missing":
+            return None
+        return row[0], [label for label in row[1].split(",") if label]
+
+    def describe_issue(self, ref: str) -> str:
+        """'#3761 "Memory leak in app"' when the title is known, else just '#3761'."""
+        found = self.issue(ref)
+        return f'{ref} "{found[0]}"' if found else ref
+
+    def set_severity(self, sha: str, severity: int) -> None:
+        self.conn.execute("UPDATE commits SET severity=? WHERE sha=?", (severity, sha))
+
+    def commits_with_issues(self, min_severity: int = 0) -> list[CommitRow]:
+        rows = self.conn.execute(
+            "SELECT sha FROM commits WHERE issues != '' AND severity >= ?", (min_severity,)
+        ).fetchall()
+        return [r for r in (self.get_commit(sha) for (sha,) in rows) if r is not None]
+
     def stats(self) -> dict[str, int]:
         q = lambda sql: self.conn.execute(sql).fetchone()[0]  # noqa: E731
         return {

blot_git-0.3.0/src/blot/trace.py

@@ -0,0 +1,115 @@
+"""Find the commit that explains a line, seeing past commits that only moved code.
+
+`git blame` answers "who last touched this line". When that is a refactor (a file split, a rename,
+a mass reformat), the reason the line exists is older. For each such hop we look up where the
+refactor took the line from (the line it deleted with the same normalized text, preferring the
+same path) and blame again at the refactor's parent, up to MAX_HOPS times.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from blot.diff import normalize_line, parse_unified_diff
+from blot.git import run_git
+
+if TYPE_CHECKING:
+    from blot.store import Store
+
+MAX_HOPS = 3
+
+
+def _ranges(numbers: list[int]) -> list[tuple[int, int]]:
+    """Collapse sorted line numbers into inclusive (start, end) runs."""
+    runs: list[tuple[int, int]] = []
+    for n in sorted(set(numbers)):
+        if runs and n == runs[-1][1] + 1:
+            runs[-1] = (runs[-1][0], n)
+        else:
+            runs.append((n, n))
+    return runs
+
+
+def blame(repo: str, rev: str, path: str, lines: list[int]) -> dict[int, tuple[str, str, int]]:
+    """{line: (sha, path in that commit, line in that commit)} via one porcelain blame call."""
+    args = ["blame", "-w", "-M", "-C", "--porcelain"]
+    for start, end in _ranges(lines):
+        args += ["-L", f"{start},{end}"]
+    try:
+        out = run_git(repo, *args, rev, "--", path)
+    except subprocess.CalledProcessError:
+        return {}
+    result: dict[int, tuple[str, str, int]] = {}
+    filenames: dict[str, str] = {}
+    sha, orig, final = "", 0, 0
+    for line in out.splitlines():
+        if line.startswith("\t"):
+            result[final] = (sha, filenames.get(sha, path), orig)
+        elif line.startswith("filename "):
+            filenames[sha] = line[9:]
+        else:
+            parts = line.split(" ")
+            if len(parts) >= 3 and len(parts[0]) == 40 and parts[1].isdigit() and parts[2].isdigit():
+                sha, orig, final = parts[0], int(parts[1]), int(parts[2])
+    return result
+
+
+class RefactorOrigins:
+    """Where a refactor commit took each line from: normalized text -> [(old path, old line)]."""
+
+    def __init__(self, repo: str):
+        self.repo = repo
+        self.cache: dict[str, dict[str, list[tuple[str, int]]]] = {}
+
+    def find(self, sha: str, path: str, text: str) -> tuple[str, int] | None:
+        if sha not in self.cache:
+            origins: dict[str, list[tuple[str, int]]] = {}
+            try:
+                diff = run_git(self.repo, "show", "--format=", "-U0", "--no-color", "--no-ext-diff", "-M", sha)
+            except subprocess.CalledProcessError:
+                diff = ""
+            for change in parse_unified_diff(diff):
+                for number, removed in change.removed:
+                    origins.setdefault(normalize_line(removed), []).append((change.old_path or change.path, number))
+            self.cache[sha] = origins
+        candidates = self.cache[sha].get(normalize_line(text), [])
+        same_path = [c for c in candidates if c[0] == path]
+        return (same_path or candidates or [None])[0]
+
+
+
+@dataclass
+class Trail:
+    sha: str  # the commit that explains the line
+    path: str  # the line's path in that commit
+    line: int  # the line's number in that commit
+    via: list[str] = field(default_factory=list)  # refactor commits traced past, newest first
+
+
+def trace_lines(store: Store, rev: str, path: str, texts: dict[int, str],
+                origins: RefactorOrigins | None = None) -> dict[int, Trail]:
+    """{line number at `rev`: Trail} for the given lines of `path` (text keyed by line number)."""
+    repo = store.repo
+    origins = origins or RefactorOrigins(repo)
+    trail = {n: Trail(sha, p, o) for n, (sha, p, o) in blame(repo, rev, path, list(texts)).items() if n in texts}
+    for _ in range(MAX_HOPS):
+        pending: dict[tuple[str, str], list[tuple[int, int]]] = {}  # (parent rev, path) -> [(line, origin line)]
+        for n, t in trail.items():
+            row = store.get_commit(t.sha)
+            if row is None or not row.is_refactor:
+                continue
+            origin = origins.find(t.sha, t.path, texts[n])
+            if origin is None:
+                continue
+            pending.setdefault((f"{t.sha}^", origin[0]), []).append((n, origin[1]))
+        if not pending:
+            break
+        for (parent, origin_path), items in pending.items():
+            earlier = blame(repo, parent, origin_path, [o for _, o in items])
+            for n, o in items:
+                if o in earlier:
+                    sha, p, line = earlier[o]
+                    trail[n] = Trail(sha, p, line, [*trail[n].via, trail[n].sha])
+    return trail