crapkit 0.2.0__py3-none-any.whl

crapkit/scaffold.py

@@ -0,0 +1,361 @@
+"""Repo sniffing for `crapkit init`: tracked files in, a starter crapkit.toml out. Pure."""
+from __future__ import annotations
+
+import json
+from typing import NamedTuple
+
+from .universe import LANGUAGE_EXTENSIONS, exclude_matcher, excluded
+
+_EXT_LANGUAGE = {ext: lang for lang, exts in LANGUAGE_EXTENSIONS.items() for ext in exts}
+
+DEFAULT_EXCLUDES = (
+    "**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**",
+    "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py",
+    # runner config files the docs themselves tell users to create; globs are
+    # whole-path, so the root form and the nested form are both required
+    "*.config.ts", "*.config.js", "*.config.mts",
+    "**/*.config.ts", "**/*.config.js", "**/*.config.mts",
+)
+
+_MATCH_DEFAULT_EXCLUDE = exclude_matcher(DEFAULT_EXCLUDES)
+
+
+def _language_of(path: str) -> str | None:
+    for ext, lang in _EXT_LANGUAGE.items():
+        if path.endswith(ext):
+            return lang
+    return None
+
+
+def _scoped_source(path: str) -> str | None:
+    """The top-level dir when this is a scopeable source file, else None.
+    Root-level loose files and dot-dirs make bad scopes; the excludes drop
+    generated trees and tests the same way inventory later will."""
+    top, _, rest = path.partition("/")
+    if not rest or top.startswith(".") or excluded(path, _MATCH_DEFAULT_EXCLUDE):
+        return None
+    return top if _language_of(path) else None
+
+
+def source_candidates(files: list[str]) -> list[str]:
+    """The paths init would put in a scope. Counting them over the UNTRACKED set
+    is how init tells "you are in the wrong directory" from "you never ran
+    `git add`" — crapkit reads `git ls-files` and sees neither case any other way.
+    """
+    paths = (raw.replace("\\", "/") for raw in files)
+    return [p for p in paths if _scoped_source(p)]
+
+
+def sniff_scopes(files: list[str]) -> dict[str, tuple[str, ...]]:
+    """Top-level source dirs -> their languages, sorted both ways for stable output."""
+    langs: dict[str, set[str]] = {}
+    for raw in files:
+        path = raw.replace("\\", "/")
+        top = _scoped_source(path)
+        if top is None:
+            continue
+        langs.setdefault(top, set()).add(_language_of(path))
+    return {d: tuple(sorted(v)) for d, v in sorted(langs.items())}
+
+
+class LaneSpec(NamedTuple):
+    """A lane init can write live, plus the scope languages it measures."""
+    name: str
+    command: str
+    artifact: str
+    parser: str
+    languages: tuple[str, ...]
+
+
+PYTEST_MARKERS = ("pyproject.toml", "pytest.ini", "setup.cfg")
+
+_PY_LANGUAGES = ("python",)
+_JS_LANGUAGES = ("javascript", "tsx", "typescript")
+_JS_RUNNER_COMMAND = {"jest": "npx jest --coverage", "vitest": "npx vitest run --coverage"}
+
+# Every artifact a scaffolded lane writes lands under .crapkit/, which init
+# ignores in the same breath. A 14-lane repo that let each runner default grew
+# fifteen coverage-* directories and seven junit files at its root, one per
+# lane, and nothing in the tree said which lane owned which.
+_COV_DIR = ".crapkit/cov"
+_PY_ARTIFACT = f"{_COV_DIR}/py.json"
+_JS_COV_DIR = f"{_COV_DIR}/js"
+_JS_ARTIFACT = f"{_JS_COV_DIR}/coverage-final.json"
+_JS_DEFAULT_ARTIFACT = "coverage/coverage-final.json"
+
+# Each runner spells "write the coverage report here" its own way and rejects
+# the other's spelling outright.
+_JS_REPORTS_DIR_FLAG = {"jest": "--coverageDirectory=",
+                        "vitest": "--coverage.reportsDirectory="}
+
+
+def _pytest_lane(markers: frozenset[str], interpreter: str) -> LaneSpec | None:
+    if not markers.intersection(PYTEST_MARKERS):
+        return None
+    return LaneSpec("py", f"{interpreter} -m pytest --cov --cov-branch "
+                          f"--cov-report=json:{_PY_ARTIFACT}",
+                    _PY_ARTIFACT, "coveragepy", _PY_LANGUAGES)
+
+
+def _npm_test_script(scripts: dict) -> str | None:
+    """The script name npm would run tests with: "test" when it exists, else the
+    alphabetically first name starting with "test", so the choice never moves."""
+    if "test" in scripts:
+        return "test"
+    named = sorted(name for name in scripts if name.startswith("test"))
+    return named[0] if named else None
+
+
+def _js_runner_command(dev_dependencies: dict) -> str | None:
+    for runner in sorted(_JS_RUNNER_COMMAND):
+        if runner in dev_dependencies:
+            return _JS_RUNNER_COMMAND[runner]
+    return None
+
+
+def _load_json(text: str) -> dict:
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _js_routing(dev_dependencies: dict) -> str:
+    """The flag that moves this runner's coverage directory under .crapkit/, or
+    "" when package.json names neither runner or both.
+
+    `npm test` can run anything, so devDependencies is the only thing that names
+    the runner — and naming it wrong is worse than the litter: jest exits on
+    vitest's `--coverage.reportsDirectory` and vitest exits on jest's
+    `--coverageDirectory`. Unresolved, the lane keeps the directory its runner
+    already defaults to and doctor says so.
+    """
+    named = [runner for runner in sorted(_JS_REPORTS_DIR_FLAG) if runner in dev_dependencies]
+    return f" {_JS_REPORTS_DIR_FLAG[named[0]]}{_JS_COV_DIR}" if len(named) == 1 else ""
+
+
+def _js_lane(package_json: str) -> LaneSpec | None:
+    """A test script, or vitest/jest in devDependencies: either says the repo
+    already knows how to produce istanbul coverage."""
+    package = _load_json(package_json)
+    script = _npm_test_script(package.get("scripts", {}))
+    command = (f"npm run {script} -- --coverage" if script
+               else _js_runner_command(package.get("devDependencies", {})))
+    if command is None:
+        return None
+    routing = _js_routing(package.get("devDependencies", {}))
+    artifact = _JS_ARTIFACT if routing else _JS_DEFAULT_ARTIFACT
+    return LaneSpec("js", command + routing, artifact, "istanbul", _JS_LANGUAGES)
+
+
+def detect_lanes(markers: frozenset[str], package_json: str, *,
+                 interpreter: str = "python") -> tuple[LaneSpec, ...]:
+    """The lanes this repo can already run, decided from files alone.
+
+    Nothing is executed and nothing is imported: presence of a pytest marker
+    file, and what package.json says about itself, are the whole signal.
+    """
+    found = (_pytest_lane(markers, interpreter), _js_lane(package_json))
+    return tuple(lane for lane in found if lane)
+
+
+def _quoted(names) -> str:
+    return ", ".join(f'"{name}"' for name in names)
+
+
+def _scope_stanza(name: str, languages: tuple[str, ...]) -> list[str]:
+    return ["[[scope]]", f'name = "{name}"', f'paths = ["{name}"]',
+            f"languages = [{_quoted(languages)}]", ""]
+
+
+def _exclude_stanza() -> list[str]:
+    return ["[exclude]", f"globs = [{_quoted(DEFAULT_EXCLUDES)}]", ""]
+
+
+def _lane_stanza(lane: LaneSpec, scope_names: tuple[str, ...]) -> list[str]:
+    return ["[[lane]]", f'name = "{lane.name}"', f'command = "{lane.command}"',
+            f'artifact = "{lane.artifact}"', f'parser = "{lane.parser}"',
+            f"scopes = [{_quoted(scope_names)}]", ""]
+
+
+def _scopes_for(lane: LaneSpec, scopes: dict[str, tuple[str, ...]]) -> tuple[str, ...]:
+    return tuple(name for name, languages in scopes.items()
+                 if set(languages).intersection(lane.languages))
+
+
+def live_lanes(lanes: tuple[LaneSpec, ...],
+               scopes: dict[str, tuple[str, ...]]) -> tuple[LaneSpec, ...]:
+    """The detected lanes init actually writes: the ones with a scope to measure.
+
+    A lane with an empty scopes list measures nothing, so it goes back to being a
+    template rather than papering over the gap — and it leaves no artifact behind
+    either, which is what the .gitignore side of init needs to know.
+    """
+    return tuple(lane for lane in lanes if _scopes_for(lane, scopes))
+
+
+def _live_lanes(lanes: tuple[LaneSpec, ...],
+                scopes: dict[str, tuple[str, ...]]) -> tuple[list[str], set[str]]:
+    """Stanzas for the lanes init writes, and the parsers they cover."""
+    lines: list[str] = []
+    covered = set()
+    for lane in live_lanes(lanes, scopes):
+        lines += _lane_stanza(lane, _scopes_for(lane, scopes))
+        covered.add(lane.parser)
+    return lines, covered
+
+
+_TEMPLATES = {
+    "coveragepy": ("# [[lane]]", '# name = "py"',
+                   '# command = "python -m pytest --cov --cov-branch '
+                   f'--cov-report=json:{_PY_ARTIFACT}"',
+                   f'# artifact = "{_PY_ARTIFACT}"', '# parser = "coveragepy"'),
+    "istanbul": ("# [[lane]]", '# name = "js"',
+                 '# command = "npx vitest run --coverage '
+                 f'{_JS_REPORTS_DIR_FLAG["vitest"]}{_JS_COV_DIR}"',
+                 f'# artifact = "{_JS_ARTIFACT}"', '# parser = "istanbul"'),
+}
+
+
+# `crapkit test-scoped FILES` runs one of these per scope. A scope with no
+# template exits 3, so the stub is written for every scope init found; the value
+# is the runner that scope's language usually uses, and the whole block stays
+# commented because only the repo knows whether that command is the right one.
+_SCOPED_TEST_COMMANDS = {
+    "python": "python -m pytest {files} -q -p no:cacheprovider",
+    "javascript": "npx vitest run {files}",
+    "tsx": "npx vitest run {files}",
+    "typescript": "npx vitest run {files}",
+}
+_SCOPED_TEST_PLACEHOLDER = "<your test command> {files}"
+
+
+def _scoped_test_command(languages: tuple[str, ...]) -> str:
+    for language in languages:
+        if language in _SCOPED_TEST_COMMANDS:
+            return _SCOPED_TEST_COMMANDS[language]
+    return _SCOPED_TEST_PLACEHOLDER
+
+
+def _runner_confirmed(languages: tuple[str, ...], confirmed: frozenset[str]) -> bool:
+    return any(lang in confirmed and lang in _SCOPED_TEST_COMMANDS for lang in languages)
+
+
+def _confirmed_languages(lanes: tuple[LaneSpec, ...]) -> frozenset[str]:
+    """Languages whose scoped command a detected lane already proves.
+
+    Only pytest: the presence signal that wrote the py coverage lane makes
+    `python -m pytest {files}` known-good. The js runners stay unconfirmed on
+    purpose — which vitest or jest config a file-scoped run needs is exactly
+    what presence detection cannot see."""
+    return frozenset({"python"} if any(" -m pytest " in ln.command for ln in lanes) else ())
+
+
+def _scoped_entry_lines(scopes: dict[str, tuple[str, ...]], live: bool) -> list[str]:
+    prefix = "" if live else "# "
+    return [f'{prefix}{name} = "{_scoped_test_command(languages)}"'
+            for name, languages in scopes.items()]
+
+
+def _scoped_tests_stub(scopes: dict[str, tuple[str, ...]],
+                       confirmed: frozenset[str] = frozenset()) -> list[str]:
+    """The [crapkit.scoped_tests] block: live entries for scopes whose runner a
+    detected lane proves, commented templates for the rest.
+
+    A confirmed runner written commented would hand doctor a warning about a
+    gap init could have closed. Every commented line still uncomments as
+    written: a stub a reader has to rewrite before it parses is no better than
+    the nothing that used to be here.
+    """
+    live = {n: l for n, l in scopes.items() if _runner_confirmed(l, confirmed)}
+    rest = {n: l for n, l in scopes.items() if n not in live}
+    intro = ["# `crapkit test-scoped FILES` runs one command per scope, with {files}",
+             "# replaced by that scope's files, each quoted."]
+    return intro + _live_block(live) + _commented_block(rest, bool(live)) + [""]
+
+
+def _live_block(live: dict[str, tuple[str, ...]]) -> list[str]:
+    if not live:
+        return []
+    return ["[crapkit.scoped_tests]"] + _scoped_entry_lines(live, True)
+
+
+def _commented_block(rest: dict[str, tuple[str, ...]], has_live: bool) -> list[str]:
+    if not rest:
+        return []
+    header = ["# Uncomment what fits:"] + ([] if has_live else ["# [crapkit.scoped_tests]"])
+    return header + _scoped_entry_lines(rest, False)
+
+
+def _template_lines(covered: set[str], scope_list: str) -> list[str]:
+    # the template's scope is a placeholder on purpose: writing a real scope
+    # name pointed a TS lane template at a python project's sources
+    del scope_list
+    lines: list[str] = []
+    for parser in sorted(_TEMPLATES):
+        if parser not in covered:
+            lines += [*_TEMPLATES[parser], '# scopes = ["<your-scope>"]', ""]
+    if not lines:
+        return []
+    return ["# Declare one [[lane]] per coverage command, then run `crapkit coverage`.", *lines]
+
+
+def starter_toml(scopes: dict[str, tuple[str, ...]], lanes: tuple[LaneSpec, ...] = ()) -> str:
+    lines = ["[crapkit]", "target = 6", ""]
+    for name, languages in scopes.items():
+        lines += _scope_stanza(name, languages)
+    lines += _exclude_stanza()
+    live, covered = _live_lanes(lanes, scopes)
+    return "\n".join(lines + live + _template_lines(covered, _quoted(scopes))
+                     + _scoped_tests_stub(scopes, _confirmed_languages(lanes)))
+
+
+_STORE_IGNORE = ".crapkit/"
+
+
+def _artifact_ignore(artifact: str) -> str:
+    """What to ignore for one lane's artifact. A file inside a directory ignores
+    the DIRECTORY: istanbul writes a whole coverage/ tree beside
+    coverage-final.json, and ignoring the one file leaves the rest untracked."""
+    top, sep, _ = artifact.partition("/")
+    return f"{top}/" if sep else top
+
+
+def _runner_droppings(lane: LaneSpec) -> list[str]:
+    """What the lane's runner leaves beside the artifact; a pytest lane drops
+    coverage's data file and bytecode caches into the consumer's tree."""
+    return [".coverage", "__pycache__/"] if lane.parser == "coveragepy" else []
+
+
+def gitignore_entries(lanes: tuple[LaneSpec, ...]) -> list[str]:
+    """Everything adopting crapkit will drop in the consumer's tree: its own
+    store, the artifact of each lane init wrote, and the runner's droppings.
+    Order is stable and duplicates collapse, so two lanes sharing a directory
+    ignore it once."""
+    entries = [_STORE_IGNORE, *(entry for lane in lanes
+                                for entry in (_artifact_ignore(lane.artifact),
+                                              *_runner_droppings(lane)))]
+    return list(dict.fromkeys(entries))
+
+
+def _appended(current: str, entries: list[str]) -> str:
+    """The new entries under their own heading, after whatever was already there."""
+    block = "# crapkit\n" + "".join(f"{entry}\n" for entry in entries)
+    if not current:
+        return block
+    separator = "\n" if current.endswith("\n") else "\n\n"
+    return current + separator + block
+
+
+def gitignore_update(current: str, lanes: tuple[LaneSpec, ...]) -> tuple[str, list[str]]:
+    """The .gitignore this repo needs, and the entries it gained. Pure.
+
+    Idempotent: an entry the file already carries is never written twice, so a
+    repo that adopted crapkit by hand gets no duplicate lines.
+    """
+    present = {line.strip() for line in current.splitlines()}
+    added = [entry for entry in gitignore_entries(lanes) if entry not in present]
+    if not added:
+        return current, []
+    return _appended(current, added), added

crapkit/score.py

@@ -0,0 +1,255 @@
+"""CRAP scoring and the coverage join. Pure.
+
+The inventory is the master list: every function gets a scored row. Coverage
+joins by path plus span overlap. Flags never conflate: measured (a lane's
+artifact spoke about the file), untested (lane covers the scope, artifact
+silent on this function), no-lane (no lane covers the scope at all), cc-only
+(the scope declares coverage_optional, so no coverage number can exist).
+The three zero-coverage flags all score cov=0; the flag says whether the
+missing number is a testing gap, a tooling gap, or by design.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import NamedTuple
+
+from .coverage_istanbul import FnCoverage
+from .snapshot import InventoryRow
+
+
+def crap(ccn: int, cov: float) -> float:
+    return ccn * ccn * (1.0 - cov) ** 3 + ccn
+
+
+_GRADES = ((0.02, "A"), (0.05, "B"), (0.10, "C"), (0.20, "D"))
+
+
+def grade(over_target: int, total: int) -> str:
+    """One letter for over-target density; A+ is reserved for zero debt."""
+    if over_target == 0:
+        return "A+"
+    ratio = over_target / total
+    for bound, letter in _GRADES:
+        if ratio < bound:
+            return letter
+    return "F"
+
+
+class ScoredRow(NamedTuple):
+    scope: str
+    path: str
+    long_name: str
+    start: int
+    end: int
+    ccn_std: int
+    ccn_mod: int
+    ccn: int
+    nloc: int
+    params: int
+    nesting: int
+    cov: float
+    flag: str
+    crap: float
+    remedy: str
+    cognitive: int = 0  # Sonar-spec cognitive complexity; reporting only, never gated
+
+
+_FIELD_TYPES = (str, str, str, int, int, int, int, int, int, int, int,
+                float, str, float, str, int)
+_SCORED_HEADER = "\t".join(ScoredRow._fields)
+# One %s per field, built once. %s of every field is str() of it, so the bytes
+# do not move; a row is a tuple, so it IS the argument list and the per-row
+# generator, the join and the concatenation all disappear (179 -> 116 ms on
+# 140,922 rows). Derived from _fields rather than written out, so a new column
+# cannot leave the template a field short.
+_SCORED_ROW = "\t".join(["%s"] * len(ScoredRow._fields)) + "\n"
+
+
+def scored_tsv_lines(rows: list[ScoredRow]) -> Iterator[str]:
+    """Header then one newline-terminated line per row. With no rows the header
+    is the empty string, so the file stays the single newline it always was."""
+    yield (_SCORED_HEADER if rows else "") + "\n"
+    for r in rows:
+        yield _SCORED_ROW % r
+
+
+def parse_scored_row(line: str) -> ScoredRow:
+    """One exported line back to a row. str() of every field round-trips through
+    its own constructor, floats included, so the re-emitted bytes are identical."""
+    parts = line.split("\t")
+    if len(parts) != len(_FIELD_TYPES):
+        raise ValueError(f"scored row has {len(parts)} fields, expected {len(_FIELD_TYPES)}: {line!r}")
+    return ScoredRow(*[cast(part) for cast, part in zip(_FIELD_TYPES, parts)])
+
+
+def parse_scored_tsv(text: str) -> list[ScoredRow]:
+    return [parse_scored_row(line) for line in text.splitlines()
+            if line.strip() and line != _SCORED_HEADER]
+
+
+def _overlap(a_start: int, a_end: int, b_start: int, b_end: int) -> int:
+    return max(0, min(a_end, b_end) - max(a_start, b_start) + 1)
+
+
+def _best_match(row: InventoryRow, candidates: list[FnCoverage]) -> FnCoverage | None:
+    # Exact start beats raw overlap, and on remaining ties the tightest span wins:
+    # a nested function must join its own entry, never its enclosing function's
+    # (an enclosing match would inherit the parent's coverage and understate risk).
+    # Identical-span twins (two lanes measuring the same file) keep the BETTER
+    # measurement — the true union of branch hits is at least the max, and lane
+    # declaration order must never change a score.
+    best, best_key = None, None
+    for fn in candidates:
+        o = _overlap(row.start, row.end, fn.start, fn.end)
+        if o <= 0:
+            continue
+        key = (fn.start == row.start, o, -(fn.end - fn.start), fn.coverage)
+        if best_key is None or key > best_key:
+            best, best_key = fn, key
+    return best
+
+
+def _remedy(ccn: int, score: float, ceiling: int) -> str:
+    if ccn > ceiling:
+        return "decompose"
+    return "ok" if score <= ceiling else "add-tests"
+
+
+def _finish(row, cov: float, flag: str, *, target: int, scope_targets) -> ScoredRow:
+    # cc-only is the pre-commit hook's rule: crap IS ccn, so _remedy can only
+    # answer ok or decompose. Feeding it cov=0 through the formula would say
+    # add-tests about code no test can reach.
+    score = float(row.ccn) if flag == "cc-only" else crap(row.ccn, cov)
+    ceiling = scope_targets.get(row.scope, target) if scope_targets else target
+    # Positional, and NOT *row: cognitive is last in both tuples with four
+    # fields between, so splicing the row in whole lands it in cov. Building
+    # this row is a third of the join's cost at 140,922 rows — **row._asdict()
+    # built a throwaway dict per row and looked every field up by name.
+    return ScoredRow(row[0], row[1], row[2], row[3], row[4], row[5], row[6], row[7],
+                     row[8], row[9], row[10],
+                     cov, flag, score, _remedy(row[7], score, ceiling), row[11])
+
+
+def _named_overlay_cov(row, by_key: dict) -> tuple[float, str]:
+    # by_key is grouped on (path, long_name) up front: filtering the whole
+    # path's candidates per row made this O(rows x candidates) per file
+    # (measured 2,998,554 comparisons on a whole-repo rescore). The nearest-start
+    # tie-break is unchanged, and min() still keeps the FIRST nearest twin
+    # because the group holds the baseline's own order.
+    named = by_key.get((row.path, row.long_name))
+    if named:
+        return min(named, key=lambda c: abs(c.start - row.start)).cov, "measured"
+    return 0.0, "untested"
+
+
+def _cov_without_join(row, lane_scopes: set, cc_only_scopes) -> tuple[float, str] | None:
+    """The verdict for a row no coverage artifact can speak about, else None.
+
+    coverage_optional is checked FIRST: such a scope needs no lane, so the
+    no-lane fallback would otherwise hide it behind a tooling gap it does
+    not have.
+    """
+    if row.scope in cc_only_scopes:
+        return 0.0, "cc-only"
+    if row.scope not in lane_scopes:
+        return 0.0, "no-lane"
+    return None
+
+
+def _start_index(coverage_by_path: dict) -> dict[str, dict[int, list[FnCoverage]]]:
+    """path -> {start line: the candidates declaring it}, in candidate order.
+
+    91.5% of joinable rows share a start line with some candidate, and the scan
+    that found it compared every candidate on the path: 936,818 pairwise
+    comparisons on the consumer repo. Bucket order is the candidates' own order, which
+    is what keeps a dead-even tie resolving to the same twin.
+    """
+    index = {}
+    for path, candidates in coverage_by_path.items():
+        buckets: dict[int, list[FnCoverage]] = {}
+        for fn in candidates:
+            buckets.setdefault(fn.start, []).append(fn)
+        index[path] = buckets
+    return index
+
+
+def _best_exact(row, bucket) -> FnCoverage | None:
+    """The winner among candidates whose start EQUALS the row's, or None when
+    none of them overlaps it.
+
+    _best_match's key leads with (fn.start == row.start): True here and False
+    for every candidate outside this bucket, so a winner here is the winner
+    over the whole path. The remaining terms are that key's tail, and
+    max(a_start, b_start) is row.start by construction.
+    """
+    best, best_key = None, None
+    for fn in bucket:
+        o = min(row.end, fn.end) - row.start + 1
+        if o <= 0:
+            continue
+        key = (o, -(fn.end - fn.start), fn.coverage)
+        if best_key is None or key > best_key:
+            best, best_key = fn, key
+    return best
+
+
+def _span_join_cov(row, coverage_by_path: dict, start_index: dict) -> tuple[float, str]:
+    candidates = coverage_by_path.get(row.path)
+    if candidates is None:
+        return 0.0, "untested"
+    # The bucket answers for most rows; the scan is the fallback for a row that
+    # starts where no candidate does, or whose bucket overlaps it nowhere.
+    match = _best_exact(row, start_index[row.path].get(row.start, ()))
+    if match is None:
+        match = _best_match(row, candidates)
+    if match is None:
+        return 0.0, "untested"
+    return match.coverage, "measured"
+
+
+def overlay_stale_coverage(
+    rows: list[InventoryRow],
+    baseline_scored: list["ScoredRow"],
+    *,
+    lane_scopes: set[str],
+    target: int = 6,
+    scope_targets: dict[str, int] | None = None,
+    cc_only_scopes: frozenset[str] = frozenset(),
+) -> list[ScoredRow]:
+    """Rescore fresh complexity against a BASELINE run's coverage.
+
+    Joins by function NAME only (edits shift spans, names survive), nearest
+    start among same-name twins. A renamed or new function joins NOTHING —
+    a span join here would hand it a neighbour's stale number and mislead
+    the preview. Coverage values are the baseline's; the caller labels them
+    stale.
+    """
+    by_key: dict[tuple[str, str], list[ScoredRow]] = {}
+    for r in baseline_scored:
+        if r.flag == "measured":
+            by_key.setdefault((r.path, r.long_name), []).append(r)
+
+    scored = []
+    for row in rows:
+        cov, flag = (_cov_without_join(row, lane_scopes, cc_only_scopes)
+                     or _named_overlay_cov(row, by_key))
+        scored.append(_finish(row, cov, flag, target=target, scope_targets=scope_targets))
+    return scored
+
+
+def score_rows(
+    rows: list[InventoryRow],
+    coverage_by_path: dict[str, list[FnCoverage]],
+    *,
+    lane_scopes: set[str],
+    target: int = 6,
+    scope_targets: dict[str, int] | None = None,
+    cc_only_scopes: frozenset[str] = frozenset(),
+) -> list[ScoredRow]:
+    start_index = _start_index(coverage_by_path)
+    scored = []
+    for r in rows:
+        cov, flag = (_cov_without_join(r, lane_scopes, cc_only_scopes)
+                     or _span_join_cov(r, coverage_by_path, start_index))
+        scored.append(_finish(r, cov, flag, target=target, scope_targets=scope_targets))
+    return scored

crapkit/snapshot.py

@@ -0,0 +1,51 @@
+"""Canonical inventory rows and exports. Pure.
+
+Scored rows carry no timestamps and sort totally, so identical inputs produce
+byte-identical exports; run metadata lives on the run row in the store, never here.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from typing import NamedTuple
+
+from .merge import FunctionRecord
+
+
+class InventoryRow(NamedTuple):
+    scope: str
+    path: str
+    long_name: str
+    start: int
+    end: int
+    ccn_std: int
+    ccn_mod: int
+    ccn: int
+    nloc: int
+    params: int
+    nesting: int
+    cognitive: int = 0  # Sonar-spec cognitive complexity; reporting only, never gated
+
+
+def build_inventory_rows(by_scope: dict[str, list[FunctionRecord]]) -> list[InventoryRow]:
+    rows = [
+        InventoryRow(scope, r.path, r.long_name, r.start, r.end,
+                     r.ccn_std, r.ccn_mod, r.ccn, r.nloc, r.params, r.nesting,
+                     r.cognitive)
+        for scope, records in by_scope.items()
+        for r in records
+    ]
+    rows.sort(key=lambda r: (r.scope, r.path, r.start, r.end, r.long_name))
+    return rows
+
+
+def tsv_lines(rows: Iterable[InventoryRow]) -> Iterator[str]:
+    """The export document, one newline-terminated line at a time.
+
+    A generator, not a joined string: at 140k functions the list of lines plus
+    the joined document cost 44 MiB of transient copies of rows that already
+    exist. The caller writes these straight to a file opened with
+    newline="\\n", which is where the byte-identical guarantee is kept.
+    """
+    yield "\t".join(InventoryRow._fields) + "\n"
+    for r in rows:
+        yield "\t".join(str(v) for v in r) + "\n"