crapkit 0.2.0__py3-none-any.whl

crapkit/config.py

@@ -0,0 +1,289 @@
+"""crapkit.toml parsing. Pure: text in, Config out; every rejection is a ConfigError (exit 3)."""
+from __future__ import annotations
+
+import tomllib
+from typing import NamedTuple
+
+from .errors import ConfigError
+
+SUPPORTED_LANGUAGES = frozenset({"typescript", "tsx", "javascript", "python", "swift"})
+SUPPORTED_PARSERS = frozenset({"istanbul", "coveragepy"})
+DEFAULT_TARGET = 6
+
+_SOURCE_SUFFIXES = (".ts", ".tsx", ".mts", ".js", ".jsx", ".mjs", ".py")
+
+
+class Scope(NamedTuple):
+    name: str
+    paths: tuple[str, ...]
+    languages: tuple[str, ...]
+    target: int | None = None  # per-scope ceiling; None = the repo default
+    # Code no test can reach (production-only scripts, generated shims): scored
+    # cc-only, and no lane has to claim it.
+    coverage_optional: bool = False
+
+
+class Lane(NamedTuple):
+    name: str
+    command: str
+    artifact: str
+    parser: str
+    scopes: tuple[str, ...]
+    cwd: str = ""
+    path_prefix: str = ""
+    env: tuple[tuple[str, str], ...] = ()
+    full_suite: bool = True
+    container_ok: bool = False
+    results_artifact: str = ""
+    timeout_seconds: int = 0  # 0 = no crapkit-owned timeout
+    retries: int = 0
+    retest_command: str = ""  # {tests} template for the flake retry before exit 8
+
+
+def _validate_coveragepy_command(name: str, command: str) -> None:
+    # Subset coverage under a suite with cross-file pollution is run-order-dependent;
+    # a full-suite lane refuses positional narrowing. Scoped suites opt out with
+    # full_suite = false, an explicit and reviewable decision.
+    tokens = command.split()
+    if "pytest" not in " ".join(tokens):
+        return
+    seen_pytest = False
+    for tok in tokens:
+        if tok.endswith("pytest"):
+            seen_pytest = True
+            continue
+        if seen_pytest and not tok.startswith("-"):
+            raise ConfigError(
+                f"lane {name!r}: positional argument {tok!r} narrows a full-suite coverage run; "
+                f"drop it or set full_suite = false deliberately")
+
+
+def _asks_for_coverage(tokens: list[str]) -> bool:
+    return any(t == "--coverage" or t.startswith("--coverage") for t in tokens)
+
+
+def _first_filter_position(tokens: list[str]) -> int:
+    # Only tokens after the test runner's `run` subcommand can be positional file
+    # filters; the runner script path itself (node scripts/run-vitest.mjs ...) is not.
+    return tokens.index("run") + 1 if "run" in tokens else 0
+
+
+def _is_file_filter(tok: str, preceding: str) -> bool:
+    if tok.startswith("-"):
+        return False  # a flag (e.g. --coverage.exclude=**/*.test.ts) is never a positional filter
+    return tok.endswith(_SOURCE_SUFFIXES) and preceding != "--config"
+
+
+def _validate_istanbul_command(name: str, command: str) -> None:
+    # The measured vitest trap: any file filter passed beside --coverage silently
+    # narrows the coverage include set. A lane command is fixed configuration, so
+    # the combination is a config error, not a runtime surprise.
+    tokens = command.split()
+    if not _asks_for_coverage(tokens):
+        return
+    for i in range(_first_filter_position(tokens), len(tokens)):
+        if _is_file_filter(tokens[i], tokens[i - 1]):
+            raise ConfigError(
+                f"lane {name!r}: file filter {tokens[i]!r} combined with --coverage silently narrows "
+                f"the coverage include set; drop the filter or use a dedicated config")
+
+
+class Config(NamedTuple):
+    target: int = DEFAULT_TARGET
+
+    @property
+    def scope_targets(self) -> dict[str, int]:
+        """Every scope's effective ceiling: its own target or the repo default."""
+        return {s.name: (s.target if s.target is not None else self.target) for s in self.scopes}
+
+    @property
+    def coverage_optional_scopes(self) -> frozenset[str]:
+        """The scopes scored cc-only: no coverage join, and no lane required."""
+        return frozenset(s.name for s in self.scopes if s.coverage_optional)
+
+    @property
+    def scope_paths(self) -> dict[str, tuple[str, ...]]:
+        """Every scope's declared paths, by name — what a lane's scopes resolve to."""
+        return {s.name: s.paths for s in self.scopes}
+    scopes: tuple[Scope, ...] = ()
+    exclude_globs: tuple[str, ...] = ()
+    max_file_bytes: int | None = None  # files bigger than this leave the corpus; None = no limit
+    churn_window_months: int = 12
+    worklist_floor: int = 5
+    worklist_top: int = 50
+    lanes: tuple[Lane, ...] = ()
+    ratchet_file: str = "crapkit-ratchet.tsv"
+    alert_command: str = ""
+    scoped_tests: tuple[tuple[str, str], ...] = ()
+    mutation_command: str = ""  # the suite run once per mutant; nonzero exit = killed
+    mutation_timeout_seconds: int = 300  # a mutant that loops forever counts as killed
+    mutation_workers: int = 1  # >1 runs mutants in that many detached git worktrees
+    diff_uncovered_max: int | None = None  # verify exit 9 past this many dead changed lines
+    debt_max_age_months: int | None = None  # ratchet report --enforce flags older marks
+    repayment_min_per_30d: int | None = None  # --enforce flags a stalled burn-down
+    max_parallel_lanes: int = 1  # lanes running at once; 1 = strictly serial
+    analysis_workers: int = 0  # lizard pool size; 0 = one worker per core
+    # Operational traps the repo learned the hard way. They lived as TOML
+    # comments, which the parser drops, so no payload could ever quote them.
+    notes: tuple[str, ...] = ()
+    # Only the scopes that wrote one, so a scope with nothing to say costs a
+    # payload no key. A plain dict, because these end up in --json output.
+    scope_notes: dict[str, tuple[str, ...]] = {}
+
+
+def load_config_text(text: str) -> Config:
+    try:
+        raw = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"crapkit.toml does not parse: {exc}") from exc
+    try:
+        return _build_config(raw)
+    except KeyError as exc:
+        raise ConfigError(f"crapkit.toml is missing a required key: {exc}") from exc
+
+
+def _parse_scope(row: dict) -> Scope:
+    languages = tuple(row.get("languages", ()))
+    unknown = set(languages) - SUPPORTED_LANGUAGES
+    if unknown:
+        raise ConfigError(f"unsupported language(s) {sorted(unknown)} in scope {row.get('name')!r}")
+    scope_target = row.get("target")
+    if scope_target is not None and (not isinstance(scope_target, int) or scope_target < 1):
+        raise ConfigError(f"scope {row.get('name')!r}: target must be a positive int, got {scope_target!r}")
+    return Scope(name=row["name"], paths=tuple(row["paths"]), languages=languages,
+                 target=scope_target,
+                 coverage_optional=bool(row.get("coverage_optional", False)))
+
+
+def _notes(row: dict, where: str) -> tuple[str, ...]:
+    """The `notes` list, rejected unless every entry is a string.
+
+    A bare `notes = "..."` is the trap TOML sets: it is iterable, so it would
+    load as one note per letter and every reader would print them that way.
+    """
+    raw = row.get("notes", [])
+    if not isinstance(raw, list) or not all(isinstance(item, str) for item in raw):
+        raise ConfigError(f"{where}: notes must be a list of strings, got {raw!r}")
+    return tuple(raw)
+
+
+def _parse_scopes(rows) -> tuple[tuple[Scope, ...], dict[str, tuple[str, ...]]]:
+    """Every [[scope]] row and its notes, off ONE walk of the rows.
+
+    Notes hang on the same rows the scopes come from, so collecting them in a
+    second pass would re-read and re-validate every row for nothing — and, when
+    the rows arrive as an iterator, would find none of them.
+    """
+    scopes: list[Scope] = []
+    notes: dict[str, tuple[str, ...]] = {}
+    for row in rows:
+        scope = _parse_scope(row)
+        scopes.append(scope)
+        row_notes = _notes(row, f"scope {scope.name!r}")
+        if row_notes:
+            notes[scope.name] = row_notes
+    return tuple(scopes), notes
+
+
+def _validate_lane_command(parser: str, full_suite: bool, name: str, command: str) -> None:
+    if parser == "istanbul":
+        _validate_istanbul_command(name, command)
+    if parser == "coveragepy" and full_suite:
+        _validate_coveragepy_command(name, command)
+
+
+def _parse_lane(row: dict, scope_names: set) -> Lane:
+    parser = row["parser"]
+    if parser not in SUPPORTED_PARSERS:
+        raise ConfigError(f"lane {row.get('name')!r}: unsupported parser {parser!r}")
+    lane_scopes = tuple(row.get("scopes", ()))
+    unknown_scopes = set(lane_scopes) - scope_names
+    if unknown_scopes:
+        raise ConfigError(f"lane {row.get('name')!r} references undeclared scope(s) {sorted(unknown_scopes)}")
+    full_suite = bool(row.get("full_suite", True))
+    _validate_lane_command(parser, full_suite, row.get("name", "?"), row["command"])
+    return Lane(name=row["name"], command=row["command"], artifact=row["artifact"],
+                parser=parser, scopes=lane_scopes,
+                cwd=row.get("cwd", ""), path_prefix=row.get("path_prefix", ""),
+                env=tuple(sorted((str(k), str(v)) for k, v in row.get("env", {}).items())),
+                full_suite=full_suite, container_ok=bool(row.get("container_ok", False)),
+                results_artifact=row.get("results_artifact", ""),
+                timeout_seconds=_nonneg_int(row, "timeout_seconds"),
+                retries=_nonneg_int(row, "retries"),
+                retest_command=row.get("retest_command", ""))
+
+
+def _nonneg_int(row: dict, key: str) -> int:
+    value = row.get(key, 0)
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        raise ConfigError(
+            f"lane {row.get('name', '?')!r}: {key} must be a non-negative int, got {value!r}")
+    return value
+
+
+def _reject_shared_artifacts(lanes: list) -> None:
+    seen_artifacts: dict[str, str] = {}
+    for lane in lanes:
+        for artifact in filter(None, (lane.artifact, lane.results_artifact)):
+            if artifact in seen_artifacts and seen_artifacts[artifact] != lane.name:
+                raise ConfigError(
+                    f"lanes {seen_artifacts[artifact]!r} and {lane.name!r} share the artifact path "
+                    f"{artifact!r}; reused paths cross-attribute coverage under --reuse-artifacts")
+            seen_artifacts[artifact] = lane.name
+
+
+def _build_config(raw: dict) -> Config:
+    scope_rows = raw.get("scope", [])
+    if not scope_rows:
+        raise ConfigError("crapkit.toml declares no [[scope]] — nothing to analyze")
+    scopes, scope_notes = _parse_scopes(scope_rows)
+    scope_names = {s.name for s in scopes}
+    lanes = [_parse_lane(row, scope_names) for row in raw.get("lane", [])]
+    _reject_shared_artifacts(lanes)
+    main = raw.get("crapkit", {})
+    return Config(
+        target=int(main.get("target", DEFAULT_TARGET)),
+        scopes=scopes,
+        exclude_globs=tuple(raw.get("exclude", {}).get("globs", ())),
+        max_file_bytes=_optional_int(raw.get("exclude", {}), "max_file_bytes"),
+        churn_window_months=int(main.get("churn_window_months", 12)),
+        worklist_floor=int(main.get("worklist_floor", 5)),
+        worklist_top=int(main.get("worklist_top", 50)),
+        lanes=tuple(lanes),
+        ratchet_file=main.get("ratchet_file", "crapkit-ratchet.tsv"),
+        alert_command=main.get("alert_command", ""),
+        scoped_tests=tuple(sorted((str(k), str(v)) for k, v in main.get("scoped_tests", {}).items())),
+        mutation_command=main.get("mutation_command", ""),
+        mutation_timeout_seconds=int(main.get("mutation_timeout_seconds", 300)),
+        mutation_workers=_positive_int(main, "mutation_workers", 1),
+        diff_uncovered_max=_optional_int(main, "diff_uncovered_max"),
+        debt_max_age_months=_optional_int(main, "debt_max_age_months"),
+        repayment_min_per_30d=_optional_int(main, "repayment_min_per_30d"),
+        max_parallel_lanes=_bounded_int(main, "max_parallel_lanes", default=1, minimum=1),
+        analysis_workers=_bounded_int(main, "analysis_workers", default=0, minimum=0),
+        notes=_notes(main, "[crapkit]"),
+        scope_notes=scope_notes,
+    )
+
+
+def _bounded_int(main: dict, key: str, *, default: int, minimum: int) -> int:
+    value = main.get(key, default)
+    if not isinstance(value, int) or isinstance(value, bool) or value < minimum:
+        raise ConfigError(f"{key} must be an int >= {minimum}, got {value!r}")
+    return value
+
+
+def _positive_int(main: dict, key: str, default: int) -> int:
+    value = main.get(key, default)
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise ConfigError(f"{key} must be a positive int, got {value!r}")
+    return value
+
+
+def _optional_int(main: dict, key: str) -> int | None:
+    value = main.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        raise ConfigError(f"{key} must be a non-negative int, got {value!r}")
+    return value

crapkit/coupling.py

@@ -0,0 +1,89 @@
+"""Change coupling from the churn git log. Pure.
+
+Files that keep landing in the same commits are coupled, whatever the import
+graph says — the hidden dependency the compiler cannot show. Bulk commits are
+skipped for pairing: a 40-file sweep says nothing about any particular pair.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from itertools import combinations
+
+MAX_COMMIT_FILES = 30
+
+
+def _commit_file_sets(lines: Iterable[str]) -> Iterator[set[str]]:
+    """One file set per commit, yielded as the log streams past.
+
+    A %x01 line opens a commit and every non-blank line until the next one is a
+    path. Empty sets are yielded rather than skipped: they add no file counts
+    and form no pairs, so the caller cannot tell them from a skip.
+    """
+    files: set[str] = set()
+    past_header = False
+    for raw in lines:
+        line = raw.strip()
+        if line.startswith("\x01"):
+            yield files
+            files, past_header = set(), True
+            continue
+        if past_header and line:
+            files.add(line.replace("\\", "/"))
+        past_header = True  # a log starting mid-commit opens on a severed header
+    yield files
+
+
+def _rank_pairs(file_counts: dict, pair_counts: dict, min_support: int,
+                min_confidence: float, top: int | None) -> list[dict]:
+    out = []
+    for (a, b), support in pair_counts.items():
+        if support < min_support:
+            continue
+        confidence = max(support / file_counts[a], support / file_counts[b])
+        if confidence < min_confidence:
+            continue
+        out.append({"files": [a, b], "support": support, "confidence": round(confidence, 4)})
+    out.sort(key=lambda p: (-p["support"] * p["confidence"], p["files"]))
+    return out if top is None else out[:top]
+
+
+def _partner(pair: dict, path: str) -> dict:
+    a, b = pair["files"]
+    return {"path": b if a == path else a, "support": pair["support"],
+            "confidence": pair["confidence"]}
+
+
+def partners(lines: Iterable[str], path: str, *, min_support: int = 5,
+             min_confidence: float = 0.5, top: int = 5) -> list[dict]:
+    """One file's coupled partners, best first.
+
+    Ranked over EVERY qualifying pair before the cut: a global top applied first
+    would drop a quiet file's own partners behind the repo's noisiest pairs and
+    report it as uncoupled.
+    """
+    ranked = change_coupling_lines(lines, min_support=min_support,
+                                   min_confidence=min_confidence, top=None)
+    return [_partner(p, path) for p in ranked if path in p["files"]][:top]
+
+
+def change_coupling(log_text: str, *, min_support: int = 5, min_confidence: float = 0.5,
+                    top: int | None = 50) -> list[dict]:
+    """Whole-text entrypoint: the log already in hand."""
+    return change_coupling_lines(log_text.splitlines(), min_support=min_support,
+                                 min_confidence=min_confidence, top=top)
+
+
+def change_coupling_lines(lines: Iterable[str], *, min_support: int = 5,
+                          min_confidence: float = 0.5, top: int | None = 50) -> list[dict]:
+    """Streaming entrypoint: the log is consumed once, one commit at a time."""
+    commits = _commit_file_sets(lines)
+    file_counts: dict[str, int] = {}
+    pair_counts: dict[tuple[str, str], int] = {}
+    for files in commits:
+        for f in files:
+            file_counts[f] = file_counts.get(f, 0) + 1
+        if len(files) > MAX_COMMIT_FILES:
+            continue
+        for pair in combinations(sorted(files), 2):
+            pair_counts[pair] = pair_counts.get(pair, 0) + 1
+    return _rank_pairs(file_counts, pair_counts, min_support, min_confidence, top)

crapkit/coverage_istanbul.py

@@ -0,0 +1,225 @@
+"""Istanbul coverage-final.json parser. Pure: JSON text in, per-file function coverage out.
+
+Branch hits map into function spans by line containment. A function with no
+branches inside its span falls back to STATEMENT coverage in that span, and
+only with no statements either to invocation (hit or not) — a straight-line
+function half-executed must not read as fully covered. Written for the
+AST-remapped output of @vitest/coverage-v8 >= 3.2, which is istanbul-schema-identical.
+
+The artifact is a flat {abs_path: coverage} object and only one file's coverage
+is ever needed at a time, so the outer object is SPLIT rather than parsed:
+split_top_level walks the members and decodes each value on its own. A
+whole-document json.loads on a 157 MB artifact peaked at 1,432 MB against
+335 MB for the split, for the same output.
+"""
+from __future__ import annotations
+
+import heapq
+import json
+import re
+from typing import Iterator, NamedTuple
+
+from .errors import ToolError
+
+
+class FnCoverage(NamedTuple):
+    name: str
+    start: int
+    end: int
+    invoked: bool
+    branches_total: int
+    branches_covered: int
+    statements_total: int = 0
+    statements_covered: int = 0
+
+    @property
+    def coverage(self) -> float:
+        if self.branches_total > 0:
+            return self.branches_covered / self.branches_total
+        if self.statements_total > 0:
+            return self.statements_covered / self.statements_total
+        return 1.0 if self.invoked else 0.0
+
+
+def _rel_path(abs_path: str, repo_root: str) -> str:
+    norm = abs_path.replace("\\", "/")
+    root = repo_root.replace("\\", "/").rstrip("/") + "/"
+    return norm[len(root):] if norm.startswith(root) else norm
+
+
+# --- top-level splitter ----------------------------------------------------
+# One member's opening: whitespace, the separating comma, the key string, the
+# colon. The key pattern is string-aware — an escaped quote inside a Windows
+# path must not end it — and its alternation is unambiguous (a character is
+# either not a quote/backslash, or an escape pair), so it scans linearly and
+# cannot backtrack.
+_MEMBER_RE = re.compile(r'\s*,?\s*("(?:[^"\\]|\\.)*")\s*:\s*', re.DOTALL)
+_OPEN_RE = re.compile(r"\s*\{")
+_CLOSE_RE = re.compile(r"\s*\}\s*\Z")
+
+# raw_decode reads ONE value at a position and reports where it ended, which is
+# what makes the split possible without writing a second parser. Hand-rolled
+# brace matching finds the same boundary but pays a Python loop iteration per
+# structural character: 4.75s of a 5.4s parse on a 21.6 MB artifact, against
+# 0.23s here, because this scanner is the C one.
+_DECODER = json.JSONDecoder()
+
+
+def split_top_level(text: str) -> Iterator[tuple[str, object]]:
+    """Yield (key, value) per member of the outer object, decoding one value at
+    a time. Equivalent to json.loads(text).items() except that the whole
+    document is never a live dict: each value is dropped as the caller steps
+    past it, so peak memory tracks the LARGEST file, not their sum."""
+    opening = _OPEN_RE.match(text)
+    if opening is None:
+        raise ValueError("istanbul artifact is not a JSON object")
+    i = opening.end()
+    while True:
+        member = _MEMBER_RE.match(text, i)
+        if member is None:
+            _expect_end(text, i)
+            return
+        value, i = _DECODER.raw_decode(text, member.end())
+        yield json.loads(member.group(1)), value
+
+
+def _expect_end(text: str, i: int) -> None:
+    if _CLOSE_RE.match(text, i) is None:
+        raise ValueError(f"unexpected content at offset {i}")
+
+
+def _iter_files(text: str, repo_root: str) -> Iterator[tuple[str, dict]]:
+    """(repo-relative path, coverage object) per artifact member. One file's
+    coverage is live at a time; the previous one is unreferenced on the next step."""
+    for abs_path, cov in split_top_level(text):
+        yield _rel_path(abs_path, repo_root), cov
+
+
+# --- span attribution ------------------------------------------------------
+# mutable span layout while attributing: [name, start, end, invoked, b_total, b_cov, s_total, s_cov]
+_B_TOTAL, _B_COV, _S_TOTAL, _S_COV = 4, 5, 6, 7
+
+
+def _fn_spans(cov: dict) -> list[list]:
+    spans = []
+    for fid, fn in cov.get("fnMap", {}).items():
+        start = fn["decl"]["start"]["line"]
+        end = fn.get("loc", {}).get("end", {}).get("line") or start
+        invoked = cov.get("f", {}).get(fid, 0) > 0
+        spans.append([fn.get("name") or "(anonymous)", start, end, invoked, 0, 0, 0, 0])
+    spans.sort(key=lambda s: s[1])
+    return spans
+
+
+def _branch_line(branch: dict) -> int | None:
+    return branch.get("loc", {}).get("start", {}).get("line")
+
+
+def _stmt_line(stmt: dict) -> int | None:
+    return stmt.get("start", {}).get("line")
+
+
+def _query_lines(cov: dict) -> set[int]:
+    """Every line the attribution will ask about, branches and statements both."""
+    lines = {_branch_line(b) for b in cov.get("branchMap", {}).values()}
+    lines |= {_stmt_line(s) for s in cov.get("statementMap", {}).values()}
+    lines.discard(None)
+    return lines
+
+
+def _push_started(heap: list, ordered: list[list], nxt: int, line: int) -> int:
+    while nxt < len(ordered) and ordered[nxt][1] <= line:
+        span = ordered[nxt]
+        heapq.heappush(heap, (span[2] - span[1], -span[1], nxt, span))
+        nxt += 1
+    return nxt
+
+
+def _drop_ended(heap: list, line: int) -> None:
+    """Discard spans that closed before this line. Safe to do lazily and only at
+    the top: query lines only increase, so anything popped here can never
+    contain a later line either."""
+    while heap and heap[0][3][2] < line:
+        heapq.heappop(heap)
+
+
+def _span_owners(fn_spans: list[list], lines: set[int]) -> dict[int, list | None]:
+    """line -> innermost containing span. A hit inside a nested function belongs
+    to that function, never to its encloser — else the nested one reads through
+    its encloser and the encloser answers for lines it can't fix.
+
+    Sweeping spans by start into a heap keyed (length, -start, index) settles
+    that in O((F + Q) log F) instead of a scan per query. The index term is
+    load-bearing: it is the sorted position, so an exact tie on (length, -start)
+    resolves to the span the old linear scan met first."""
+    ordered = sorted(fn_spans, key=lambda s: s[1])
+    heap: list[tuple] = []
+    owners: dict[int, list | None] = {}
+    nxt = 0
+    for line in sorted(lines):
+        nxt = _push_started(heap, ordered, nxt, line)
+        _drop_ended(heap, line)
+        owners[line] = heap[0][3] if heap else None
+    return owners
+
+
+def _attach_branches(owners: dict[int, list | None], cov: dict) -> None:
+    hits_by_id = cov.get("b", {})
+    for bid, branch in cov.get("branchMap", {}).items():
+        best = owners.get(_branch_line(branch))
+        if best is not None:
+            hits = hits_by_id.get(bid, [])
+            best[_B_TOTAL] += len(hits)
+            best[_B_COV] += sum(1 for h in hits if h > 0)
+
+
+def _attach_statements(owners: dict[int, list | None], cov: dict) -> None:
+    hits_by_id = cov.get("s", {})
+    for sid, stmt in cov.get("statementMap", {}).items():
+        best = owners.get(_stmt_line(stmt))
+        if best is not None:
+            best[_S_TOTAL] += 1
+            best[_S_COV] += 1 if hits_by_id.get(sid, 0) > 0 else 0
+
+
+def _file_coverage(cov: dict) -> list[FnCoverage]:
+    fn_spans = _fn_spans(cov)
+    owners = _span_owners(fn_spans, _query_lines(cov))
+    _attach_branches(owners, cov)
+    _attach_statements(owners, cov)
+    return [FnCoverage(*s) for s in fn_spans]
+
+
+def _dead_lines(cov: dict) -> set[int]:
+    hits_by_id = cov.get("s", {})
+    dead = {_stmt_line(stmt)
+            for sid, stmt in cov.get("statementMap", {}).items()
+            if hits_by_id.get(sid, 0) == 0}
+    dead.discard(None)
+    return dead
+
+
+def parse_istanbul_missing(text: str, *, repo_root: str) -> dict[str, set[int]]:
+    """Per measured file, the lines whose statement never ran — the
+    diff-coverage ground truth. Files with everything executed map to set()."""
+    try:
+        missing: dict[str, set[int]] = {}
+        for rel_path, cov in _iter_files(text, repo_root):
+            missing[rel_path] = _dead_lines(cov)
+        return missing
+    except Exception as exc:
+        raise ToolError(f"unparseable istanbul artifact: {exc}") from exc
+
+
+def parse_istanbul(text: str, *, repo_root: str) -> dict[str, list[FnCoverage]]:
+    try:
+        per_file: dict[str, list[FnCoverage]] = {}
+        for rel_path, cov in _iter_files(text, repo_root):
+            per_file[rel_path] = _file_coverage(cov)
+        if not per_file:
+            raise ToolError("istanbul artifact is empty (zero files) — the coverage run measured nothing")
+        return per_file
+    except ToolError:
+        raise
+    except Exception as exc:
+        raise ToolError(f"unparseable istanbul artifact: {exc}") from exc