gitfence 0.1.0__py3-none-any.whl

fence/scoring/strength.py

@@ -0,0 +1,198 @@
+"""Fence Strength (how load-bearing code looks) and Change Risk (how risky an edit is).
+
+Both are sums of named factors. Each factor carries a plain-English reason, so
+`fence explain` can show exactly how a number was reached. There is no hidden
+term: value = clamp(sum(points), 0, 100).
+
+Default weights are starting values; DECISIONS.md records changes made after
+running the backtest. Any weight can be overridden in fence.toml under
+[scoring.weights] using the keys in WEIGHTS.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from fence.config import Config
+from fence.decisions.model import Factor, Score
+from fence.scoring import calibration
+
+WEIGHTS: dict[str, float] = {
+    # origin type (strongest type only)
+    "type.incident": 25, "type.security": 25, "type.data-integrity": 22,
+    "type.concurrency": 18, "type.revert": 14, "type.bugfix": 12, "type.compatibility": 10,
+    "type.dependency-pin": 10, "type.performance": 8, "type.deliberate-design": 10,
+    "type.cleanup": 0, "type.unknown": 0,
+    # evidence quality
+    "grade.A": 15, "grade.B": 10, "grade.C": 4, "grade.D": 0,
+    # links
+    "link.each": 5, "link.cap": 15,
+    "corroboration.each": 3, "corroboration.cap": 9,
+    # code
+    "code.cap": 12,
+    # history shape
+    "survival.per_year": 3, "survival.cap": 9, "survival.min_later_commits": 3,
+    "regression.each": 8, "regression.cap": 24,
+    "revert.involved": 14,
+    "test.added": 10,
+    "authors.each": 3, "authors.cap": 9,
+    # negatives
+    "neg.bulk": -10, "neg.vendored": -30, "neg.automated": -10, "neg.refactor": -6,
+    # change risk
+    "kind.delete": 1.0, "kind.loosen": 0.85, "kind.alter": 0.5, "kind.move": 0.3,
+    "risk.tests_removed": 10, "risk.linked_tests_touched": 5,
+    "risk.low_signal_share": 0.5,  # keep this share of risk on low-signal paths
+    "type.inferred_share": 0.5,  # type points kept when the type is only inferred (C/D)
+}
+
+BASE_CONFIDENCE = {"A": 0.85, "B": 0.75, "C": 0.5, "D": 0.3}
+
+
+def weights(cfg: Config) -> dict[str, float]:
+    unknown = set(cfg.scoring.weights) - set(WEIGHTS)
+    if unknown:
+        raise ValueError(f"unknown scoring weight(s): {', '.join(sorted(unknown))}")
+    return {**WEIGHTS, **cfg.scoring.weights}
+
+
+@dataclass
+class StrengthInputs:
+    decision_type: str
+    grade: str
+    links: list[str] = field(default_factory=list)  # distinct issue/PR/ticket/incident refs
+    positive_text_signals: list[str] = field(default_factory=list)  # distinct signal ids
+    code_signals: list[tuple[str, float]] = field(default_factory=list)  # (id, weight)
+    age_days: float = 0.0
+    later_commits_to_file: int = 0
+    regression_fixes: int = 0
+    revert_involved: bool = False
+    test_added: bool = False
+    distinct_authors: int = 1
+    bulk: bool = False
+    vendored: bool = False
+    automated: bool = False
+    refactor: bool = False
+    # coverage, for confidence
+    shallow: bool = False
+    not_indexed: bool = False
+    pr_unfetched: bool = False
+    offline: bool = False
+
+
+def strength(inp: StrengthInputs, cfg: Config) -> Score:
+    w = weights(cfg)
+    f: list[Factor] = []
+
+    def add(fid: str, points: float, reason: str) -> None:
+        if points:
+            f.append(Factor(fid, round(points, 1), reason))
+
+    t = inp.decision_type
+    if inp.grade in ("A", "B"):
+        add(f"type.{t}", w.get(f"type.{t}", 0), f"introduced as a {t} change")
+    else:
+        # A type guessed from keywords predicted nothing in the backtest; count it half.
+        add(f"type.{t}", w.get(f"type.{t}", 0) * w["type.inferred_share"],
+            f"looks like a {t} change (inferred, counts {w['type.inferred_share']:g}x)")
+    add(f"grade.{inp.grade}", w[f"grade.{inp.grade}"], _grade_reason(inp.grade))
+    if inp.links:
+        n = len(inp.links)
+        add("link", min(w["link.cap"], n * w["link.each"]),
+            f"linked to {n} issue/PR/ticket reference(s): {', '.join(inp.links[:3])}")
+    extra = max(0, len(inp.positive_text_signals) - 1)
+    if extra:
+        add("corroboration", min(w["corroboration.cap"], extra * w["corroboration.each"]),
+            f"{extra + 1} independent text signals agree")
+    if inp.code_signals:
+        pts = min(w["code.cap"], sum(x for _, x in inp.code_signals))
+        kinds = {sid.split(".", 1)[1].replace("_", " ") for sid, _ in inp.code_signals}
+        names = ", ".join(sorted(kinds))
+        add("code", pts, f"the code itself contains: {names}")
+    if inp.later_commits_to_file >= w["survival.min_later_commits"] and inp.age_days >= 180:
+        years = inp.age_days / 365
+        add("survival", min(w["survival.cap"], years * w["survival.per_year"]),
+            f"survived {inp.later_commits_to_file} later commits to the file "
+            f"over {years:.1f} years")
+    if inp.regression_fixes:
+        add("regression", min(w["regression.cap"], inp.regression_fixes * w["regression.each"]),
+            f"these lines were fixed again {inp.regression_fixes} time(s) later")
+    if inp.revert_involved:
+        add("revert", w["revert.involved"], "involved in a revert (reverted, or re-applied)")
+    if inp.test_added:
+        add("test", w["test.added"], "a test was added in the same change")
+    if inp.distinct_authors > 1:
+        add("authors", min(w["authors.cap"], (inp.distinct_authors - 1) * w["authors.each"]),
+            f"{inp.distinct_authors} people have touched these lines")
+    if inp.bulk:
+        add("neg.bulk", w["neg.bulk"], "landed in a very large bulk commit")
+    if inp.vendored:
+        add("neg.vendored", w["neg.vendored"], "vendored or generated path")
+    if inp.automated:
+        add("neg.automated", w["neg.automated"], "an automated or dependency-bot change")
+    if inp.refactor:
+        add("neg.refactor", w["neg.refactor"], "described as a refactor or cleanup")
+
+    value = int(round(max(0.0, min(100.0, sum(x.points for x in f)))))
+    return Score(value, cfg.scoring.band(value), confidence(inp), tuple(f), _what_would_change(inp))
+
+
+def confidence(inp: StrengthInputs) -> float:
+    c = BASE_CONFIDENCE[inp.grade]
+    if inp.shallow:
+        c -= 0.15
+    if inp.not_indexed:
+        c -= 0.2
+    if inp.pr_unfetched:
+        c -= 0.05
+    if inp.offline and inp.grade in ("C", "D"):
+        c -= 0.05
+    return round(max(0.05, min(0.95, c)), 2)
+
+
+def change_risk(
+    s: Score, kind: str, cfg: Config, *, tests_removed: bool = False,
+    path_bonus: int = 0, path_bonus_reason: str = "", low_signal: bool = False,
+) -> Score:
+    w = weights(cfg)
+    mult = w[f"kind.{kind}"]
+    f = [Factor("strength", round(s.value * mult, 1),
+                f"Fence Strength {s.value} x {mult} for a '{kind}' change")]
+    if tests_removed:
+        f.append(Factor("risk.tests_removed", w["risk.tests_removed"],
+                        "tests are removed in the same change"))
+    if path_bonus:
+        f.append(Factor("risk.path", path_bonus, path_bonus_reason or "sensitive path"))
+    if low_signal:
+        keep = w["risk.low_signal_share"]
+        cut = -round(sum(x.points for x in f) * (1 - keep), 1)
+        f.append(Factor("risk.low_signal_path", cut,
+                        f"docs/config/generated path: risk scaled by {keep:g}"))
+    value = int(round(max(0.0, min(100.0, sum(x.points for x in f)))))
+    cal = calibration.lookup(value)
+    return Score(value, cfg.scoring.band(value), s.confidence, (*f, *s.factors),
+                 s.what_would_change, round(cal.rate, 4) if cal else None,
+                 cal.n if cal else None)
+
+
+def _grade_reason(g: str) -> str:
+    return {
+        "A": "reason stated in a PR, issue or review linked to the change",
+        "B": "reason stated in the commit message or a code comment",
+        "C": "reason inferred from change shape and labels only",
+        "D": "no reason recoverable",
+    }[g]
+
+
+def _what_would_change(inp: StrengthInputs) -> tuple[str, ...]:
+    out = []
+    if inp.grade in ("C", "D"):
+        out.append("state the reason in a code comment or the PR description (raises grade)")
+    if not inp.links:
+        out.append("link the issue or incident it fixes")
+    if not inp.test_added:
+        out.append("add a test that fails without this code")
+    if inp.not_indexed:
+        out.append("run `fence index` so history is complete")
+    if inp.pr_unfetched:
+        out.append("set GITHUB_TOKEN and re-run `fence index` to read PR and issue text")
+    return tuple(out[:3])

fence/signals/catalog.py

@@ -0,0 +1,161 @@
+"""The signal catalog: every pattern Fence reads as evidence, each with an id and weight.
+
+Weights are Fence Strength points. They are starting values, tuned by the backtest
+(see DECISIONS.md), and overridable in fence.toml under [scoring.weights].
+Every signal here has its own positive and negative unit test.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+Kind = Literal["text", "label", "review", "code", "structural", "negative"]
+
+# Order matters only for picking a decision type: the first matching type wins.
+DECISION_TYPES = (
+    "incident",
+    "security",
+    "data-integrity",
+    "concurrency",
+    "revert",
+    "bugfix",
+    "compatibility",
+    "dependency-pin",
+    "performance",
+    "deliberate-design",
+    "cleanup",
+    "unknown",
+)
+
+
+@dataclass(frozen=True)
+class Signal:
+    id: str
+    kind: Kind
+    weight: float
+    description: str
+    decision_type: str | None = None
+    pattern: re.Pattern[str] | None = None
+
+
+def _rx(p: str) -> re.Pattern[str]:
+    return re.compile(p, re.IGNORECASE)
+
+
+TEXT_SIGNALS: tuple[Signal, ...] = (
+    Signal("text.incident", "text", 20, "mentions an outage, incident or postmortem", "incident",
+           _rx(r"\b(outage|incident|post-?mortem|sev[ -]?[0-4]|downtime|page[ds]? on-?call)\b")),
+    Signal("text.security", "text", 22, "mentions a vulnerability or security fix", "security",
+           _rx(r"\b(cve-\d{4}-\d{4,}|security|xss|csrf|ssrf|sql injection|injection|"
+               r"vulnerab\w*|exploit\w*|buffer overflow|auth(entication)? bypass|sanitiz\w*)\b")),
+    Signal("text.data_integrity", "text", 18, "mentions data loss, duplicates or idempotency",
+           "data-integrity",
+           _rx(r"\b(duplicate[sd]?|corrupt\w*|data loss|idempoten\w*|integrity|"
+               r"double[- ]charg\w*|lost (writes|updates|data))\b")),
+    Signal("text.concurrency", "text", 16, "mentions a race, deadlock or thread safety",
+           "concurrency",
+           _rx(r"\b(race condition|data race|races?|deadlock\w*|thread[- ]safe\w*|"
+               r"concurren\w*|mutex|atomic\w*)\b")),
+    Signal("text.hotfix", "text", 14, "marked as a hotfix", "incident", _rx(r"\bhot-?fix\w*\b")),
+    Signal("text.regression", "text", 12, "mentions a regression", "bugfix",
+           _rx(r"\bregress(ion|ions|ed)?\b")),
+    Signal("text.do_not_remove", "text", 18, "says the code must stay", "deliberate-design",
+           _rx(r"\b(do not remove|don'?t remove|do not delete|don'?t delete|must not be removed|"
+               r"needed because|required because|is necessary|load[- ]bearing)\b")),
+    Signal("text.fix", "text", 8, "describes a fix", "bugfix",
+           _rx(r"\b(fix|fixes|fixed|fixing|bug|bugs|bugfix|patch(ed)?|crash\w*|broken)\b")),
+    Signal("text.leak", "text", 10, "mentions a leak or out-of-memory", "bugfix",
+           _rx(r"\b(memory leak|leak\w*|oom|out of memory)\b")),
+    Signal("text.workaround", "text", 10, "describes a workaround", "compatibility",
+           _rx(r"\b(workaround|work around|temporary|temp fix|hack|kludge)\b")),
+    Signal("text.compat", "text", 8, "mentions compatibility or a backport", "compatibility",
+           _rx(r"\b(compat\w*|backport\w*|polyfill|shim)\b")),
+    Signal("text.dependency_pin", "text", 10, "pins or holds back a dependency", "dependency-pin",
+           _rx(r"\b(pin(ned|s)? (to|at)|hold back|downgrade\w*|lock (to|at) version)\b")),
+    Signal("text.performance", "text", 6, "mentions performance", "performance",
+           _rx(r"\b(performance|perf|latency|slow(er|ness)?|speed ?up|optimi[sz]\w*)\b")),
+    Signal("text.rollback", "text", 6, "mentions a rollback", "revert",
+           _rx(r"\b(roll ?back|rolled back)\b")),
+    Signal("text.closes_issue", "text", 12, "closes or fixes a linked issue", None,
+           _rx(r"\b(?:fix(?:es|ed)?|close[sd]?|resolve[sd]?)\s*:?\s+(?P<v>(?:[\w.-]+/[\w.-]+)?#\d+)")),
+    Signal("text.issue_ref", "text", 4, "references an issue or PR", None,
+           _rx(r"(?<![\w/&])(?P<v>(?:[\w.-]+/[\w.-]+)?#\d+)\b")),
+    Signal("text.ticket", "text", 8, "references a ticket", None,
+           re.compile(r"\b(?P<v>[A-Z][A-Z0-9]{1,9}-\d{1,7})\b")),
+    Signal("text.incident_url", "text", 12, "links an incident or status page", "incident",
+           _rx(r"(?P<v>https?://[^\s)>\]]*(?:status|incident|pagerduty|opsgenie|postmortem)"
+               r"[^\s)>\]]*)")),
+    # Negative signals: these touches say little about why code exists.
+    Signal("text.formatting", "negative", -15, "a formatting or lint change", "cleanup",
+           _rx(r"\b(reformat\w*|format(ted|ting)? (code|files|with)|formatter|lint(ing)?|"
+               r"prettier|black|gofmt|isort|whitespace|code style)\b")),
+    Signal("text.refactor", "negative", -6, "a refactor or cleanup", "cleanup",
+           _rx(r"\b(refactor\w*|clean ?up|cleaned up|tidy|tidied|rename[sd]?)\b")),
+    Signal("text.automated", "negative", -10, "an automated or generated change", "cleanup",
+           _rx(r"\b(auto-?generated|regenerat\w*|dependabot|renovate(bot)?|"
+               r"bump(ed|s)? [\w@/.-]+ from)\b")),
+)
+
+# PR/issue labels, matched against whole label names (case-insensitive).
+LABEL_SIGNALS: tuple[Signal, ...] = (
+    Signal("label.security", "label", 22, "labelled security", "security",
+           _rx(r"^(security|vulnerability|cve)\b")),
+    Signal("label.incident", "label", 20, "labelled incident/hotfix/p0", "incident",
+           _rx(r"^(incident|hotfix|p0|sev[ -]?[0-2]|outage|critical)\b")),
+    Signal("label.regression", "label", 12, "labelled regression", "bugfix",
+           _rx(r"^regression\b")),
+    Signal("label.bug", "label", 8, "labelled bug", "bugfix",
+           _rx(r"^(type: ?)?(bug|defect|fix)\b")),
+    Signal("label.performance", "label", 6, "labelled performance", "performance",
+           _rx(r"^(perf|performance)\b")),
+    Signal("label.chore", "negative", -6, "labelled chore/refactor/dependencies", "cleanup",
+           _rx(r"^(chore|refactor|dependencies|deps|documentation|docs)\b")),
+)
+
+
+def extract_labels(labels: list[str]) -> list[str]:
+    """Signal ids for a list of label names, in catalog order."""
+    out = []
+    for s in LABEL_SIGNALS:
+        if any(s.pattern.search(str(lb).strip()) for lb in labels if s.pattern):
+            out.append(s.id)
+    return out
+
+
+_BY_ID = {s.id: s for s in TEXT_SIGNALS + LABEL_SIGNALS}
+
+
+def signal(signal_id: str) -> Signal:
+    return _BY_ID[signal_id]
+
+
+def all_signals() -> tuple[Signal, ...]:
+    from fence.signals.code import CODE_SIGNALS, STRUCTURAL_SIGNALS
+
+    return TEXT_SIGNALS + CODE_SIGNALS + STRUCTURAL_SIGNALS
+
+
+MAX_DETAIL = 120
+
+
+def extract_text(text: str, *, skip_refs: frozenset[str] = frozenset()) -> list[tuple[str, str]]:
+    """(signal_id, verbatim matched text) for every text signal in `text`. Deterministic order."""
+    found: list[tuple[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    closing: set[str] = set()
+    for s in TEXT_SIGNALS:
+        assert s.pattern is not None  # noqa: S101 - every text signal has one
+        for m in s.pattern.finditer(text):
+            # Signals with a value to cite name it (?P<v>...); others cite the whole match.
+            detail = (m.group("v") if "v" in s.pattern.groupindex else m.group(0))[:MAX_DETAIL]
+            if s.id == "text.closes_issue":
+                closing.add(detail.lower())
+            if s.id == "text.issue_ref" and (detail.lower() in closing or detail in skip_refs):
+                continue  # already counted as a closing reference, or it is the PR itself
+            key = (s.id, detail)
+            if key not in seen:
+                seen.add(key)
+                found.append(key)
+    return found

fence/signals/code.py

@@ -0,0 +1,69 @@
+"""Signals read from code text and from history shape (as opposed to messages).
+
+Code signals look at the lines a decision covers; structural signals look at how
+those lines lived (survival, flip-flops, re-fixes). Both feed Fence Strength.
+"""
+
+from __future__ import annotations
+
+import re
+
+from fence.signals.catalog import Signal, _rx
+
+CODE_SIGNALS: tuple[Signal, ...] = (
+    Signal("code.warning_comment", "code", 14, "a comment warns against changing it",
+           "deliberate-design",
+           _rx(r"(?:#|//|/\*|\*|--)\s*(?:warning|important|careful|do not|don'?t|never|must|"
+               r"note)\b[^\n]{0,160}")),
+    Signal("code.hack_comment", "code", 8, "a TODO/HACK/XXX/FIXME comment", "compatibility",
+           re.compile(r"(?:#|//|/\*|\*|--)\s*(?:TODO|HACK|XXX|FIXME|WORKAROUND)\b[^\n]{0,160}")),
+    Signal("code.guard", "code", 6, "a guard clause or validation check", None,
+           re.compile(r"^\s*(?:if\b.*(?:\bis None\b|\bnull\b|\bnil\b|==\s*None|!=\s*None|"
+                      r"\bnot\b|!|<|>|len\(|\.length|\bundefined\b)|"
+                      r"if\s+err\s*!=\s*nil|assert\b|require\(|precondition|"
+                      r"raise\b|throw\b|return\s+err\b)")),
+    Signal("code.exception_handling", "code", 6, "error handling", None,
+           re.compile(r"^\s*(?:except\b|catch\s*\(|catch\b|finally\b|rescue\b|recover\(\))")),
+    Signal("code.lock", "code", 10, "a lock, mutex or atomic operation", "concurrency",
+           _rx(r"\b(lock\(|unlock\(|\.lock\b|mutex|rwlock|semaphore|synchronized|atomic\w*|"
+               r"threading\.\w*lock|with\s+[\w.]*lock\b|sync\.(Mutex|RWMutex|Once)|"
+               r"compareandset|\bcas\()")),
+    Signal("code.retry_timeout", "code", 8, "a retry, backoff, sleep or timeout", None,
+           _rx(r"\b(retr(y|ies|ying)|backoff|back_off|sleep\(|time\.sleep|settimeout|"
+               r"timeout|deadline|max_attempts|attempts?)\b")),
+    Signal("code.feature_flag", "code", 6, "behind a feature flag", None,
+           _rx(r"\b(feature[_ ]?flag|is_enabled\(|isenabled\(|flags?\.\w+|"
+               r"launchdarkly|unleash)\b")),
+    Signal("code.assertion", "code", 4, "an assertion or invariant", None,
+           _rx(r"^\s*(assert\b|assert\w*\(|invariant\(|check\w*\()")),
+)
+
+STRUCTURAL_SIGNALS: tuple[Signal, ...] = (
+    Signal("struct.survivor", "structural", 1, "survived later edits nearby (per year, capped)"),
+    Signal("struct.test_added", "structural", 10, "a test was added in the same change"),
+    Signal("struct.revert_involved", "structural", 14, "involved in a revert"),
+    Signal("struct.regression_chain", "structural", 8, "the same lines were re-fixed (per fix)"),
+    Signal("struct.flip_flop", "structural", 12, "removed and re-added before"),
+    Signal("struct.multi_author", "structural", 3, "touched or reviewed by several people (each)"),
+    Signal("struct.linked_pr", "structural", 6, "landed through a pull request"),
+    Signal("struct.constant_in_fix", "structural", 8, "a constant changed in a fix commit"),
+    Signal("struct.format_only", "negative", -20, "only formatting touched these lines"),
+    Signal("struct.bulk_change", "negative", -10, "landed in a very large bulk commit"),
+    Signal("struct.vendored", "negative", -30, "vendored or generated code"),
+)
+
+
+def match_code(lines: list[str]) -> list[tuple[str, str]]:
+    """(signal_id, verbatim line text) for code signals in `lines`."""
+    found: list[tuple[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for line in lines:
+        for s in CODE_SIGNALS:
+            assert s.pattern is not None  # noqa: S101
+            m = s.pattern.search(line)
+            if m:
+                key = (s.id, line.strip()[:160])
+                if key not in seen:
+                    seen.add(key)
+                    found.append(key)
+    return found

fence/text.py

@@ -0,0 +1,43 @@
+"""Make untrusted repository text safe to print in a terminal or PR comment."""
+
+from __future__ import annotations
+
+import unicodedata
+
+# Bidi controls can make code or commit text display differently from what it is
+# ("Trojan Source"). Zero-width characters can hide text.
+_INVISIBLE = {
+    *map(chr, range(0x202A, 0x202F)),
+    *map(chr, range(0x2066, 0x206A)),
+    "​",
+    "‌",
+    "‍",
+    "‎",
+    "‏",
+    "",
+}
+
+
+def clean(text: str, *, max_len: int = 500, keep_newlines: bool = False) -> str:
+    """Drop control and invisible characters, keep tabs as spaces, cap the length.
+
+    Escape sequences such as "\\x1b[2J" would otherwise be executed by the terminal.
+    """
+    out = []
+    for ch in text:
+        if ch == "\n" and keep_newlines:
+            out.append(ch)
+        elif ch == "\t":
+            out.append("    ")
+        elif ch in _INVISIBLE or unicodedata.category(ch) in ("Cc", "Cf", "Cs", "Co"):
+            out.append("�" if ch == "\x1b" else "")
+        else:
+            out.append(ch)
+    result = "".join(out)
+    return result if len(result) <= max_len else result[: max_len - 1] + "…"
+
+
+def quoted(text: str) -> str:
+    """Wrap a verbatim quote in delimiters it does not contain, so a quote that starts
+    with "fence" does not print as ""fence" ...". Double quotes unless the text has one."""
+    return f"'{text}'" if '"' in text else f'"{text}"'

fence/trace.py

@@ -0,0 +1,65 @@
+"""Removed ranges -> the commits that introduced them, at an explicit base revision.
+
+Plain pipeline code: no model calls, no guessing. If the diff does not match the
+base, we stop with PreimageMismatch instead of blaming lines that might be different.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from fence.diffing.ranges import RemovedRange
+from fence.git.blame import BlameLine, blame
+from fence.git.runner import GitError, Repo
+from fence.lang import Symbol, enclosing_symbol
+
+
+class PreimageMismatch(GitError):
+    """The diff's removed lines are not what the base revision contains."""
+
+
+@dataclass(frozen=True)
+class TraceResult:
+    range: RemovedRange
+    symbol: Symbol | None
+    lines: tuple[BlameLine, ...]
+
+    @property
+    def introducing(self) -> tuple[BlameLine, ...]:
+        """One BlameLine per distinct commit, in line order."""
+        seen: dict[str, BlameLine] = {}
+        for bl in self.lines:
+            seen.setdefault(bl.sha, bl)
+        return tuple(seen.values())
+
+
+def trace(
+    repo: Repo, base: str, ranges: Sequence[RemovedRange], *,
+    extra_ignore: Sequence[str] = (),
+) -> list[TraceResult]:
+    base_sha = repo.verify_ref(base)
+    by_path: dict[str, list[RemovedRange]] = {}
+    for r in ranges:
+        by_path.setdefault(r.path, []).append(r)
+
+    results: list[TraceResult] = []
+    for path, path_ranges in by_path.items():
+        text = repo.read_blob(base_sha, path)
+        base_lines = text.split("\n")
+        for r in path_ranges:
+            actual = base_lines[r.start - 1 : r.end]
+            if list(r.lines) != actual:
+                raise PreimageMismatch(
+                    f"{path}:{r.start}-{r.end} in the diff does not match {base_sha[:12]}; "
+                    "was the diff made against a different base?"
+                )
+        spans = [(r.start, r.end) for r in path_ranges]
+        blamed = {
+            bl.final_line: bl
+            for bl in blame(repo, base_sha, path, spans, extra_ignore=extra_ignore)
+        }
+        for r in path_ranges:
+            lines = tuple(blamed[n] for n in range(r.start, r.end + 1))
+            results.append(TraceResult(r, enclosing_symbol(path, text, r.start), lines))
+    return results