crapkit 0.2.0__py3-none-any.whl

crapkit/coverage_py.py

@@ -0,0 +1,87 @@
+"""coverage.py JSON report parser. Pure: report text in, per-file function coverage out.
+
+Requires the per-function regions coverage.py has emitted since 7.6.0 and the
+start_line key from 7.13.1; requires branch data (the consuming lane must run
+with branch coverage on) so the coverage term measures the same structure the
+complexity term counts. Function spans come from start_line and the maximum
+executed/missing line, the closest thing the report offers to an end line.
+"""
+from __future__ import annotations
+
+import json
+
+from .coverage_istanbul import FnCoverage
+from .errors import ToolError
+
+
+def _fn_coverage(name: str, fn: dict) -> FnCoverage:
+    summary = fn.get("summary", {})
+    lines = list(fn.get("executed_lines", ())) + list(fn.get("missing_lines", ()))
+    start = fn.get("start_line") or (min(lines) if lines else 0)
+    end = max(lines) if lines else start
+    return FnCoverage(name=name, start=start, end=end,
+                      invoked=summary.get("covered_lines", 0) > 0,
+                      branches_total=summary.get("num_branches", 0),
+                      branches_covered=summary.get("covered_branches", 0),
+                      statements_total=summary.get("num_statements", 0),
+                      statements_covered=summary.get("covered_lines", 0))
+
+
+def _file_functions(raw_path: str, data: dict) -> list[FnCoverage]:
+    functions = data.get("functions")
+    if functions is None:
+        raise ToolError(
+            f"coverage.py report has no function regions for {raw_path!r} — needs coverage >= 7.6")
+    # the "" key is the "(no function)" module-level bucket
+    fns = [_fn_coverage(name, fn) for name, fn in functions.items() if name]
+    return sorted(fns, key=lambda f: f.start)
+
+
+def parse_coveragepy_missing(text: str, *, path_prefix: str) -> dict[str, set[int]]:
+    """Per measured file, the lines coverage.py reports as never run."""
+    try:
+        report = json.loads(text)
+        prefix = (path_prefix.rstrip("/") + "/") if path_prefix else ""
+        return {prefix + p.replace("\\", "/"): set(data.get("missing_lines", ()))
+                for p, data in report.get("files", {}).items()}
+    except Exception as exc:
+        raise ToolError(f"unparseable coverage.py report: {exc}") from exc
+
+
+def _line_contexts(raw: dict) -> dict[int, list[str]]:
+    out = {}
+    for line, contexts in raw.items():
+        tests = sorted({c.split("|")[0] for c in contexts if c})
+        if tests:
+            out[int(line)] = tests
+    return out
+
+
+def parse_coveragepy_contexts(text: str, *, path_prefix: str) -> dict[str, dict[int, list[str]]]:
+    """line -> test ids per file, from a report made with --show-contexts and
+    dynamic_context = test_function. The empty module-import context is not a test."""
+    try:
+        report = json.loads(text)
+        prefix = (path_prefix.rstrip("/") + "/") if path_prefix else ""
+        out = {}
+        for p, data in report.get("files", {}).items():
+            contexts = _line_contexts(data.get("contexts", {}))
+            if contexts:
+                out[prefix + p.replace("\\", "/")] = contexts
+        return out
+    except Exception as exc:
+        raise ToolError(f"unparseable coverage.py report: {exc}") from exc
+
+
+def parse_coveragepy(text: str, *, path_prefix: str) -> dict[str, list[FnCoverage]]:
+    try:
+        report = json.loads(text)
+        if not report.get("meta", {}).get("branch_coverage"):
+            raise ToolError("coverage.py report lacks branch data — run the lane with branch coverage on")
+        prefix = (path_prefix.rstrip("/") + "/") if path_prefix else ""
+        return {prefix + raw_path.replace("\\", "/"): _file_functions(raw_path, data)
+                for raw_path, data in report.get("files", {}).items()}
+    except ToolError:
+        raise
+    except Exception as exc:
+        raise ToolError(f"unparseable coverage.py report: {exc}") from exc

crapkit/covstream.py

@@ -0,0 +1,320 @@
+"""Coverage artifacts read off the file instead of out of a string.
+
+The whole-document parsers take `text`, so the caller must already hold the
+artifact: `read_bytes()` plus its UTF-8 decode put two copies of a 150 MB
+artifact on the heap before a single function is attributed. The splitter in
+coverage_istanbul already decodes one member at a time; this module gives it a
+window that refills from a handle instead of a string that holds everything.
+
+Peak becomes O(chunk + largest member) rather than O(artifact): 322.6 -> 52.1 MB
+on a 150 MB istanbul artifact, for byte-identical output and the same sha256.
+
+Both shapes are split the same way. An istanbul artifact IS the {path: coverage}
+object, so its members are files. A coverage.py report wraps them one level down
+in "files", so the walk descends into that member and hands the rest back whole.
+"""
+from __future__ import annotations
+
+import codecs
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import IO, Iterator
+
+from .coverage_istanbul import (_CLOSE_RE, _DECODER, _MEMBER_RE, _OPEN_RE,
+                                FnCoverage, _dead_lines, _file_coverage, _rel_path)
+from .errors import ToolError
+
+CHUNK = 1 << 20
+
+# The inner close: one object ending inside a larger document, with no claim
+# about what follows. _CLOSE_RE anchors at the end of the text and is the outer
+# document's business.
+_CLOSE_INNER = re.compile(r"\s*\}")
+
+
+class _Window:
+    """A sliding decoded window over a byte stream, plus the sha256 of the bytes
+    that went past. Offsets stay valid across a refill because refilling only
+    appends; only drop() ever moves them, and it says so."""
+
+    def __init__(self, handle: IO[bytes], chunk: int = CHUNK):
+        self._handle = handle
+        self._chunk = max(chunk, 1)
+        self._decoder = codecs.getincrementaldecoder("utf-8")()
+        self.hasher = hashlib.sha256()
+        self.buf = ""
+        self.pos = 0
+        self.eof = False
+
+    def refill(self) -> bool:
+        """Pull one more chunk into the window. False once the stream is spent."""
+        if self.eof:
+            return False
+        raw = self._handle.read(self._chunk)
+        if not raw:
+            self.eof = True
+            self.buf += self._decoder.decode(b"", True)
+            return False
+        self.hasher.update(raw)
+        self.buf += self._decoder.decode(raw)
+        return True
+
+    def drop(self, i: int) -> None:
+        """Consume through offset `i`. Compaction is amortized: slicing the
+        window on every member copies the whole tail each time, so the offset
+        moves and the copy happens only once the consumed prefix is a chunk."""
+        self.pos = i
+        if self.pos >= self._chunk:
+            self.buf = self.buf[self.pos:]
+            self.pos = 0
+
+
+# --- window-driven splitting ----------------------------------------------
+
+def _usable(w: _Window, member) -> bool:
+    """A member header the window can be trusted on. One that runs to the very
+    edge is not trustworthy mid-stream: the key string, or the whitespace after
+    the colon, may continue in bytes not read yet."""
+    return member is not None and (member.end() < len(w.buf) or w.eof)
+
+
+def _next_member(w: _Window):
+    """The next member header, or None once the object closed or the stream ran
+    out. Refills only while the window can neither produce a header nor prove
+    the object ended, so a closing brace does not drag the rest of the file in."""
+    while True:
+        member = _MEMBER_RE.match(w.buf, w.pos)
+        if _usable(w, member):
+            return member
+        if _CLOSE_INNER.match(w.buf, w.pos) is not None:
+            return None
+        if not w.refill():
+            return None
+
+
+def _whole_value(w: _Window, start: int):
+    """The decoded value and its end offset, or None while the window may still
+    be hiding more of it. A value ending exactly at the edge is not whole: a
+    bare number would otherwise decode as its own truncated prefix."""
+    try:
+        value, end = _DECODER.raw_decode(w.buf, start)
+    except ValueError:
+        return None
+    return (value, end) if end < len(w.buf) or w.eof else None
+
+
+def _decode_value(w: _Window, start: int):
+    """raw_decode at `start`, growing the window until the value is whole."""
+    while True:
+        whole = _whole_value(w, start)
+        if whole is not None:
+            return whole
+        if not w.refill():
+            return _DECODER.raw_decode(w.buf, start)
+
+
+def _enter_object(w: _Window, what: str) -> None:
+    while _OPEN_RE.match(w.buf, w.pos) is None and w.refill():
+        pass
+    opening = _OPEN_RE.match(w.buf, w.pos)
+    if opening is None:
+        raise ValueError(f"{what} is not a JSON object")
+    w.drop(opening.end())
+
+
+def _expect_document_end(w: _Window) -> None:
+    while w.refill():
+        pass
+    if _CLOSE_RE.match(w.buf, w.pos) is None:
+        raise ValueError(f"unexpected content at {w.buf[w.pos:w.pos + 80]!r}")
+
+
+def _take_member(w: _Window, member) -> tuple[str, object]:
+    """Decode one member's value and step the window past it."""
+    key, start = member.group(1), member.end()
+    value, end = _decode_value(w, start)
+    w.drop(end)
+    return json.loads(key), value
+
+
+def split_window(w: _Window) -> Iterator[tuple[str, object]]:
+    """(key, value) per member of the outer object, one value live at a time.
+    The same pairs in the same order as coverage_istanbul.split_top_level."""
+    _enter_object(w, "istanbul artifact")
+    while True:
+        member = _next_member(w)
+        if member is None:
+            _expect_document_end(w)
+            return
+        yield _take_member(w, member)
+
+
+# --- coverage.py: the same walk, one level down ---------------------------
+
+def _leave_object(w: _Window, what: str) -> None:
+    close = _CLOSE_INNER.match(w.buf, w.pos)
+    if close is None:
+        raise ValueError(f"unterminated {what}")
+    w.drop(close.end())
+
+
+def _walk_nested(w: _Window, start: int) -> Iterator[tuple[str, object, str]]:
+    """The members of the object at `start`, one at a time."""
+    w.pos = start
+    _enter_object(w, "coverage.py report: 'files'")
+    while True:
+        member = _next_member(w)
+        if member is None:
+            _leave_object(w, "coverage.py report: 'files' object")
+            return
+        key, value = _take_member(w, member)
+        yield key, value, "sub"
+
+
+def walk_report(w: _Window, target: str) -> Iterator[tuple[str, object, str]]:
+    """(key, value, kind) per top-level member. kind is "member" for an ordinary
+    decoded value and "sub" for one member of the `target` object, so meta and
+    totals arrive whole and "files" arrives one file at a time."""
+    _enter_object(w, "coverage.py report")
+    while True:
+        member = _next_member(w)
+        if member is None:
+            # A walk that just stops at the first unreadable byte reports zero
+            # dark lines, which is indistinguishable from a fully covered repo.
+            _expect_document_end(w)
+            return
+        if json.loads(member.group(1)) == target:
+            yield from _walk_nested(w, member.end())
+            continue
+        key, value = _take_member(w, member)
+        yield key, value, "member"
+
+
+# --- public readers --------------------------------------------------------
+
+def _window(path: Path | str, chunk: int) -> tuple[_Window, IO[bytes]]:
+    handle = open(path, "rb")
+    return _Window(handle, chunk), handle
+
+
+def _guarded(work, message: str):
+    """Run a walk, reporting any parse failure the way the whole-document
+    parsers do. A ToolError the walk raised itself is already the right error
+    and keeps its own wording."""
+    try:
+        return work()
+    except ToolError:
+        raise
+    except Exception as exc:
+        raise ToolError(f"{message}: {exc}") from exc
+
+
+_BAD_ISTANBUL = "unparseable istanbul artifact"
+_BAD_REPORT = "unparseable coverage.py report"
+_NO_BRANCH = "coverage.py report lacks branch data — run the lane with branch coverage on"
+
+
+def _istanbul_map(w: _Window, repo_root: str, per_file) -> dict:
+    out = {}
+    for abs_path, cov in split_window(w):
+        out[_rel_path(abs_path, repo_root)] = per_file(cov)
+    return out
+
+
+def parse_istanbul_file(path: Path | str, *, repo_root: str, chunk: int = CHUNK
+                        ) -> tuple[dict[str, list[FnCoverage]], str]:
+    """Per-file function coverage plus the sha256 of the artifact's own bytes.
+    Same result as parse_istanbul(path.read_text(), ...), same digest as
+    sha256(path.read_bytes()), without either whole copy ever existing."""
+    w, handle = _window(path, chunk)
+    with handle:
+        per_file = _guarded(lambda: _istanbul_map(w, repo_root, _file_coverage),
+                            _BAD_ISTANBUL)
+    if not per_file:
+        raise ToolError(
+            "istanbul artifact is empty (zero files) — the coverage run measured nothing")
+    return per_file, w.hasher.hexdigest()
+
+
+def parse_istanbul_missing_file(path: Path | str, *, repo_root: str,
+                                chunk: int = CHUNK) -> dict[str, set[int]]:
+    """Per measured file, the lines whose statement never ran."""
+    w, handle = _window(path, chunk)
+    with handle:
+        return _guarded(lambda: _istanbul_map(w, repo_root, _dead_lines), _BAD_ISTANBUL)
+
+
+def _prefix(path_prefix: str) -> str:
+    return (path_prefix.rstrip("/") + "/") if path_prefix else ""
+
+
+def _meta_has_branch(key: str, value: object) -> bool:
+    if key != "meta" or not isinstance(value, dict):
+        return False
+    return bool(value.get("branch_coverage"))
+
+
+def _require_branch(seen: bool) -> None:
+    if not seen:
+        raise ToolError(_NO_BRANCH)
+
+
+def _add_file(out: dict, prefix: str, raw_path: str, data: dict, to_functions):
+    """Record one file's functions, or hand back the error it raised.
+
+    The error is CARRIED, not thrown: the whole-document parser saw the report
+    before it read a single file, so it always refused a report with no branch
+    data first. Members are not ordered — json.dump(sort_keys=True) writes
+    "files" ahead of "meta" — so streaming only keeps that precedence by
+    finishing the walk before it decides which complaint wins.
+    """
+    try:
+        out[prefix + raw_path.replace("\\", "/")] = to_functions(raw_path, data)
+        return None
+    except Exception as exc:
+        return exc
+
+
+def _coveragepy_functions(w: _Window, prefix: str) -> dict:
+    """path -> function coverage, refusing a report with no branch data."""
+    from .coverage_py import _file_functions
+
+    out: dict = {}
+    branch, failure = False, None
+    for key, value, kind in walk_report(w, "files"):
+        if kind == "member":
+            branch = branch or _meta_has_branch(key, value)
+            continue
+        failure = failure or _add_file(out, prefix, key, value, _file_functions)
+    _require_branch(branch)
+    if failure is not None:
+        raise failure
+    return out
+
+
+def parse_coveragepy_file(path: Path | str, *, path_prefix: str, chunk: int = CHUNK
+                          ) -> tuple[dict[str, list[FnCoverage]], str]:
+    """Per-file function coverage plus the sha256 of the report's own bytes."""
+    w, handle = _window(path, chunk)
+    with handle:
+        per_file = _guarded(lambda: _coveragepy_functions(w, _prefix(path_prefix)),
+                            _BAD_REPORT)
+    return per_file, w.hasher.hexdigest()
+
+
+def _coveragepy_missing(w: _Window, prefix: str) -> dict[str, set[int]]:
+    out: dict[str, set[int]] = {}
+    for key, value, kind in walk_report(w, "files"):
+        if kind == "sub":
+            out[prefix + key.replace("\\", "/")] = set(value.get("missing_lines", ()))
+    return out
+
+
+def parse_coveragepy_missing_file(path: Path | str, *, path_prefix: str,
+                                  chunk: int = CHUNK) -> dict[str, set[int]]:
+    """Per measured file, the lines coverage.py reports as never run."""
+    w, handle = _window(path, chunk)
+    with handle:
+        return _guarded(lambda: _coveragepy_missing(w, _prefix(path_prefix)), _BAD_REPORT)

crapkit/diffparse.py

@@ -0,0 +1,98 @@
+"""Parse `git diff -U0` output into per-file changed line ranges. Pure.
+
+Ranges are new-side. A pure deletion (zero new lines) still marks the line it
+happened at, so a function shrunk by an edit is still a touched function.
+Paths come from the +++ header (the new side survives renames) and decode
+git's C-style quoting via the churn module's helper.
+
+Hunk body lines are consumed by the counts the @@ header declares, never
+pattern-matched: an added source line whose text starts with "++ " arrives as
+"+++ <text>" and would otherwise read as a file header, repointing every later
+hunk at a phantom path the gate never checks.
+"""
+from __future__ import annotations
+
+import re
+
+from .churn import _unquote_git_path
+
+_HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+
+
+def _spend_body_line(line: str, rem_old: int, rem_new: int) -> tuple[int, int] | None:
+    """Charge one line to the hunk body still owed, returning what remains.
+
+    None means the line is diff structure, not body: either nothing is owed or
+    the hunk ended early.
+    """
+    if rem_old <= 0 and rem_new <= 0:
+        return None
+    if line.startswith("\\"):  # ""
+        return rem_old, rem_new
+    if line.startswith("-"):
+        return rem_old - 1, rem_new
+    if line.startswith("+"):
+        return rem_old, rem_new - 1
+    # -U0 hunks contain only +/- lines; anything else means the hunk ended
+    # early (truncated or synthetic diff) - reparse it normally.
+    return None
+
+
+def _open_file(line: str, ranges: dict[str, list[tuple[int, int]]]) -> str | None:
+    """Point the parser at the file a `+++ ` header names; None for /dev/null."""
+    target = line[4:].strip()
+    if target == "/dev/null":
+        return None
+    target = _unquote_git_path(target)
+    path = target[2:] if target.startswith("b/") else target
+    path = path.replace("\\", "/")
+    ranges.setdefault(path, [])
+    return path
+
+
+def _new_side_range(start: int, count: int) -> tuple[int, int]:
+    """New-side span a hunk covers."""
+    if count == 0:  # pure deletion: mark the touch point
+        return max(start, 1), max(start, 1)
+    return start, start + count - 1
+
+
+def _record_hunk(
+    m: re.Match[str], current: str | None, ranges: dict[str, list[tuple[int, int]]]
+) -> tuple[int, int]:
+    """Land the hunk's range on the current file and return the body counts it owes.
+
+    An omitted count in the @@ header means one line. A hunk with no current
+    file still declares a body to consume.
+    """
+    rem_old = int(m.group(2)) if m.group(2) is not None else 1
+    rem_new = int(m.group(4)) if m.group(4) is not None else 1
+    if current is not None:
+        ranges[current].append(_new_side_range(int(m.group(3)), rem_new))
+    return rem_old, rem_new
+
+
+def _files_with_hunks(
+    ranges: dict[str, list[tuple[int, int]]],
+) -> dict[str, list[tuple[int, int]]]:
+    """Drop files a header introduced but no hunk ever touched."""
+    return {p: r for p, r in ranges.items() if r}
+
+
+def changed_ranges(diff_text: str) -> dict[str, list[tuple[int, int]]]:
+    ranges: dict[str, list[tuple[int, int]]] = {}
+    current: str | None = None
+    rem_old = rem_new = 0
+    for line in diff_text.splitlines():
+        owed = _spend_body_line(line, rem_old, rem_new)
+        if owed is not None:
+            rem_old, rem_new = owed
+            continue
+        rem_old = rem_new = 0
+        if line.startswith("+++ "):
+            current = _open_file(line, ranges)
+            continue
+        m = _HUNK.match(line)
+        if m:
+            rem_old, rem_new = _record_hunk(m, current, ranges)
+    return _files_with_hunks(ranges)

crapkit/digest.py

@@ -0,0 +1,191 @@
+"""Digest and trend totals. Pure.
+
+The digest speaks only on change (an unchanged week is silence, per the
+empty-channel rule) and keeps to a handful of numbers: totals delta, the worst
+per-function regressions, improvements, and new over-target functions.
+"""
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from .score import ScoredRow, grade
+
+
+class Totals(NamedTuple):
+    functions: int
+    over_target: int
+    crap_load: float
+    avg: float
+    pct_over: float  # normalized: absolute counts grow with the repo; this does not
+
+
+class Digest(NamedTuple):
+    quiet: bool
+    lines: list[str]
+
+
+def _over_count(rows, target: int, scope_targets) -> int:
+    return sum(1 for r in rows if r.crap > (scope_targets or {}).get(r.scope, target))
+
+
+def totals_from_counts(functions: int, over_target: int, load: float) -> Totals:
+    """The rounding rule, in one place. A caller that already has the three sums
+    (store.run_totals adds them up inside the scan) must round them exactly the
+    way a caller holding the rows does, or the same run reads two ways."""
+    return Totals(
+        functions=functions,
+        over_target=over_target,
+        crap_load=round(load, 2),
+        avg=round(load / functions, 4) if functions else 0.0,
+        pct_over=round(100.0 * over_target / functions, 2) if functions else 0.0,
+    )
+
+
+def totals(rows: list[ScoredRow], *, target: int,
+           scope_targets: dict[str, int] | None = None) -> Totals:
+    return totals_from_counts(len(rows), _over_count(rows, target, scope_targets),
+                              sum(r.crap for r in rows))
+
+
+def scope_totals(rows: list[ScoredRow], *, target: int,
+                 scope_targets: dict[str, int] | None = None) -> dict[str, Totals]:
+    by_scope: dict[str, list[ScoredRow]] = {}
+    for r in rows:
+        by_scope.setdefault(r.scope, []).append(r)
+    return {scope: totals(srows, target=target, scope_targets=scope_targets)
+            for scope, srows in sorted(by_scope.items())}
+
+
+def scope_rollup(by_scope: dict[str, Totals]) -> dict[str, dict]:
+    """The per-scope block coverage --json and trend --json both publish.
+
+    One shaping in one place: the two commands reach their Totals differently
+    (rows in hand vs a GROUP BY), and a second shaping would let the same run
+    read two ways depending on which command asked.
+    """
+    return {scope: {"functions": t.functions, "over_target": t.over_target,
+                    "crap_load": t.crap_load, "grade": grade(t.over_target, t.functions)}
+            for scope, t in by_scope.items()}
+
+
+def latest_comparable_pair(runs: list[dict]) -> tuple[dict, dict] | None:
+    """The newest pair of runs with IDENTICAL lane sets.
+
+    Comparing a --lane subset run against a full run flips every out-of-subset
+    function to no-lane and manufactures phantom regressions; only like-for-like
+    pairs digest.
+    """
+    for i in range(len(runs) - 1, 0, -1):
+        cur = runs[i]
+        cur_lanes = set(cur["lanes"])
+        for j in range(i - 1, -1, -1):
+            if set(runs[j]["lanes"]) == cur_lanes:
+                return runs[j], cur
+    return None
+
+
+def skipped_runs(runs: list[dict], pair: tuple[dict, dict] | None) -> list[dict]:
+    """The runs the pair stepped over: everything after its older half except
+    its newer half. Empty exactly when the pair is the newest run and the one
+    before it.
+
+    Stepping over a run is the right move — a subset run never compares — but a
+    digest that says nothing about it reports an older delta in this week's
+    voice. On the flagship consumer that printed runs 17 -> 19 while run 22 sat
+    in the store, and nothing on any surface said 22 existed.
+    """
+    if pair is None:
+        return []
+    prev, cur = pair
+    return [r for r in runs[runs.index(prev) + 1:] if r["id"] != cur["id"]]
+
+
+_Key = tuple[str, str]  # (path, long_name): what identifies a function across runs
+_Move = tuple[float, ScoredRow, ScoredRow]  # (delta, before, after)
+_Delta = tuple[float, ScoredRow]
+
+
+class _Changes(NamedTuple):
+    """What moved between two runs, bucketed the way the digest reports it."""
+    regressions: list[_Delta]
+    improvements: list[_Delta]
+    appeared: list[ScoredRow]
+
+    def nothing_moved(self) -> bool:
+        return not (self.regressions or self.improvements or self.appeared)
+
+
+def _by_key(rows: list[ScoredRow]) -> dict[_Key, ScoredRow]:
+    return {(r.path, r.long_name): r for r in rows}
+
+
+def _moves(prev_by_key: dict[_Key, ScoredRow],
+           cur_by_key: dict[_Key, ScoredRow]) -> list[_Move]:
+    """Every function measured in both runs, paired with how far its CRAP moved."""
+    return [(row.crap - prev_by_key[key].crap, prev_by_key[key], row)
+            for key, row in cur_by_key.items() if key in prev_by_key]
+
+
+def _regressions(moves: list[_Move]) -> list[_Delta]:
+    return [(delta, after) for delta, _before, after in moves if delta > 0.01]
+
+
+def _improvements(moves: list[_Move], target: int) -> list[_Delta]:
+    """Only a function that WAS over target improves; drift below it is not news."""
+    return [(delta, after) for delta, before, after in moves
+            if delta < -0.01 and before.crap > target]
+
+
+def _appeared(prev_by_key: dict[_Key, ScoredRow], cur_by_key: dict[_Key, ScoredRow],
+              target: int) -> list[ScoredRow]:
+    """Functions the previous run never saw; new code under target is not news."""
+    return [row for key, row in cur_by_key.items()
+            if key not in prev_by_key and row.crap > target]
+
+
+def _changes_between(prev: list[ScoredRow], cur: list[ScoredRow], target: int) -> _Changes:
+    prev_by_key, cur_by_key = _by_key(prev), _by_key(cur)
+    moves = _moves(prev_by_key, cur_by_key)
+    return _Changes(
+        regressions=_regressions(moves),
+        improvements=_improvements(moves, target),
+        appeared=_appeared(prev_by_key, cur_by_key, target),
+    )
+
+
+def _totals_line(t_prev: Totals, t_cur: Totals) -> str:
+    return (f"CRAP load {t_prev.crap_load} -> {t_cur.crap_load}; "
+            f"over target {t_prev.over_target} -> {t_cur.over_target}; "
+            f"functions {t_prev.functions} -> {t_cur.functions}")
+
+
+def _fn_line(prefix: str, row: ScoredRow) -> str:
+    return f"{prefix}: {row.path} {row.long_name} (crap {row.crap:.1f})"
+
+
+def _regression_lines(regressions: list[_Delta], top: int) -> list[str]:
+    return [_fn_line(f"regressed +{delta:.1f}", row)
+            for delta, row in sorted(regressions, key=lambda x: -x[0])[:top]]
+
+
+def _appeared_lines(appeared: list[ScoredRow], top: int) -> list[str]:
+    return [_fn_line("new over target", row)
+            for row in sorted(appeared, key=lambda r: -r.crap)[:top]]
+
+
+def _improvement_lines(improvements: list[_Delta], top: int) -> list[str]:
+    return [_fn_line(f"improved {delta:.1f}", row)
+            for delta, row in sorted(improvements, key=lambda x: x[0])[:top]]
+
+
+def build_digest(prev: list[ScoredRow], cur: list[ScoredRow], *, target: int, top: int = 5) -> Digest:
+    t_prev, t_cur = totals(prev, target=target), totals(cur, target=target)
+    changed = _changes_between(prev, cur, target)
+    if t_prev == t_cur and changed.nothing_moved():
+        return Digest(quiet=True, lines=[])
+    return Digest(quiet=False, lines=[
+        _totals_line(t_prev, t_cur),
+        *_regression_lines(changed.regressions, top),
+        *_appeared_lines(changed.appeared, top),
+        *_improvement_lines(changed.improvements, top),
+    ])