@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/test/test-pinned.ts

@@ -0,0 +1,311 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { change_base } from '#scripts/git/change-base'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { review_code_tree } from '#scripts/review/review-code-tree'
+import { test_pinned_cache, type LoadedCache, type Reached } from './test-pinned-cache'
+import { test_pinned_cache_logic, type Known, type Recheck } from './test-pinned-cache-logic'
+import { test_pinned_emit } from './test-pinned-emit'
+import { test_pinned_functions } from './test-pinned-functions'
+import type { PinnedOrigin } from './test-pinned-ledger'
+import {
+	test_pinned_logic,
+	type Hunk,
+	type HunkOutcome,
+	type PinnedReport,
+} from './test-pinned-logic'
+import { test_pinned_probe, type CheckOptions, type Probe } from './test-pinned-probe'
+import { test_pinned_reach, type Reach } from './test-pinned-reach'
+import type { Staged } from './test-pinned-stage'
+import { test_red } from './test-red'
+import type { RedProbe } from './test-red-logic'
+
+// `josh test:pinned` (joshuafolkken/kit#4516) — put each changed hunk of a non-test code file back to
+// the merge-base's lines, one at a time, run that file's related tests, and list the hunks no test went
+// red on: the "reverting it stays green" finding a review used to stop a lane on.
+//
+// **The reverts happen in a detached worktree at HEAD, never the caller's checkout** (`base-tree.ts`).
+// The changed files are copied in from the working tree first, so what is reverted is the change as it
+// stands, committed or not, and each hunk's file is restored before the next one runs.
+
+const HEAD = 'HEAD'
+
+interface StubRead {
+	hunks: ReadonlyArray<Hunk>
+	unparsed: ReadonlyArray<string>
+}
+
+// `rewired` counts the changed hunks left out as a rewire (`test-pinned-rewire.ts`).
+interface ProbeRead extends StubRead {
+	rewired: number
+}
+
+interface RunOptions {
+	max_hunks: number
+	is_cached_only: boolean
+	is_first_unpinned?: boolean
+	rewired?: number
+	origin?: PinnedOrigin | undefined
+}
+
+// One run's probing: the checked hunks, what the cache knows of each, and the cache they are written to.
+interface ProbeRun {
+	hunks: ReadonlyArray<Hunk>
+	known: ReadonlyArray<Known>
+	cache: LoadedCache
+	keys: ReadonlyArray<string>
+	options: RunOptions
+}
+
+// Each hunk's verdict, and how many of the fresh probes ran in stages.
+interface Verdicts {
+	verdicts: Array<RedProbe | undefined>
+	staged: Staged
+}
+
+const NO_OUTCOME: HunkOutcome = { unpinned: [], stopped: [] }
+const NO_REPORT = { ...NO_OUTCOME, unchecked: [], unparsed: [] } as const
+
+// `--diff-filter=M`: an added file's one hunk is the whole file, and reverting it is a missing module
+// every importer fails on, which says nothing about the tests — its functions are probed instead
+// (`stub_hunks_of`). The prefixes are pinned: a user's `diff.mnemonicPrefix` writes `+++ w/<file>`,
+// which would read as no hunk at all.
+async function read_hunks(base: string, files: ReadonlyArray<string>): Promise<Array<Hunk>> {
+	if (files.length === 0) return []
+	const diff_args = ['diff', '-U0', '--no-color', '--no-ext-diff', '--diff-filter=M']
+	const prefix_args = ['--src-prefix=a/', '--dst-prefix=b/', base, '--']
+
+	return test_pinned_logic.parse_hunks(
+		await git_spawn.read([...diff_args, ...prefix_args, ...files]),
+	)
+}
+
+// The key of each hunk, read off the working file its lines sit in now.
+async function keys_of(hunks: ReadonlyArray<Hunk>): Promise<Array<string>> {
+	const contents = await Promise.all(hunks.map(async (hunk) => await readFile(hunk.file, 'utf8')))
+
+	return test_pinned_cache_logic.distinct(
+		hunks.map((hunk, index) => test_pinned_cache_logic.hunk_key(hunk, contents[index] ?? '')),
+	)
+}
+
+// The verdict the cache already holds; one left to recheck holds none yet.
+function held_of(known: Known): RedProbe | undefined {
+	return test_pinned_cache_logic.is_recheck(known) ? undefined : known
+}
+
+function recheck_of(known: Known): Recheck | undefined {
+	return test_pinned_cache_logic.is_recheck(known) ? known : undefined
+}
+
+// The hunks no held verdict covers, each with its recheck where the cache named one.
+function probes_of(hunks: ReadonlyArray<Hunk>, known: ReadonlyArray<Known>): Array<Probe> {
+	return hunks
+		.map((hunk, index) => ({ hunk, index, recheck: recheck_of(known[index]) }))
+		.filter((probe) => held_of(known[probe.index]) === undefined)
+}
+
+// The probes in the order they run: the fewest tests reached first (`test_pinned_logic.by_reach`),
+// each file's count read once and carried on its probes, which a wide one runs in stages by
+// (`test-pinned-stage.ts`); a file with no graph to read counts as 0.
+async function by_reach(probes: ReadonlyArray<Probe>, reach: Reach): Promise<Array<Probe>> {
+	const files = test_pinned_cache_logic.distinct(probes.map((probe) => probe.hunk.file))
+	const related = await Promise.all(files.map(async (file) => await reach.related(file)))
+	const counts = new Map(files.map((file, index) => [file, related[index]?.length ?? 0]))
+	const counted = probes.map((probe) => ({ ...probe, reach: counts.get(probe.hunk.file) }))
+
+	return test_pinned_logic.by_reach(counted, counts)
+}
+
+function reached_of(verdicts: ReadonlyArray<RedProbe | undefined>): Array<Reached> {
+	return verdicts.flatMap((verdict, index) => (verdict === undefined ? [] : [[index, verdict]]))
+}
+
+// The fresh run's options: the hunks the cache held, then the run's own.
+function check_options(held: number, options: RunOptions): CheckOptions {
+	return {
+		held,
+		rewired: options.rewired ?? 0,
+		is_first_unpinned: options.is_first_unpinned === true,
+		origin: options.origin,
+	}
+}
+
+// Each hunk's verdict: the cached one where it still holds, else a fresh run's, in the hunks' order.
+// The held ones are written first and each fresh one as it is reached (`test_pinned_cache.writer`).
+// Under `is_first_unpinned` a hunk the run stopped before keeps no verdict.
+async function verdicts_on(paths: ReadonlyArray<string>, probing: ProbeRun): Promise<Verdicts> {
+	const verdicts = probing.known.map((entry) => held_of(entry))
+	const reached = reached_of(verdicts)
+	const probes = await by_reach(probes_of(probing.hunks, probing.known), probing.cache.reach)
+	const writer = test_pinned_cache.writer(probing.cache, probing.keys)
+	const options = check_options(reached.length, probing.options)
+
+	await writer.record(reached)
+	const checked = await test_pinned_probe.checked_on(
+		paths,
+		probes,
+		async (index, verdict) => {
+			verdicts[index] = verdict
+			await writer.record([[index, verdict]])
+		},
+		options,
+	)
+
+	return { verdicts, staged: checked.staged }
+}
+
+function outcome_of(
+	hunks: ReadonlyArray<Hunk>,
+	verdicts: ReadonlyArray<RedProbe | undefined>,
+): HunkOutcome {
+	const is_held = verdicts.every((verdict) => verdict !== undefined)
+
+	return { ...test_pinned_logic.outcome(hunks, verdicts), is_held }
+}
+
+// The hunks a run probed and stopped before (`is_first_unpinned`); none, no `cut` key.
+function cut_of(
+	hunks: ReadonlyArray<Hunk>,
+	verdicts: ReadonlyArray<RedProbe | undefined>,
+): Pick<HunkOutcome, 'cut'> {
+	const cut = hunks.filter((_hunk, index) => verdicts[index] === undefined)
+
+	return cut.length === 0 ? {} : { cut }
+}
+
+// A fresh cached verdict is reused without a run (`test-pinned-cache.ts`); every hunk's verdict is
+// stored again, so a rerun on the same tree starts no vitest. `is_cached_only` runs no probe: only the
+// verdicts the cache holds are read, and nothing is written.
+async function outcome_on(
+	base: string,
+	paths: ReadonlyArray<string>,
+	hunks: ReadonlyArray<Hunk>,
+	options: RunOptions,
+): Promise<HunkOutcome> {
+	if (hunks.length === 0) return NO_OUTCOME
+	const cache = await test_pinned_cache.load(base, hunks)
+	const keys = await keys_of(hunks)
+	const known = await test_pinned_cache.known(
+		cache,
+		keys,
+		hunks.map((hunk) => hunk.file),
+	)
+
+	if (options.is_cached_only) {
+		return outcome_of(
+			hunks,
+			known.map((entry) => held_of(entry)),
+		)
+	}
+
+	const { verdicts, staged } = await verdicts_on(paths, { hunks, known, cache, keys, options })
+
+	return { ...outcome_of(hunks, verdicts), ...cut_of(hunks, verdicts), staged }
+}
+
+// A target the base's tree does not hold is added — committed on the branch or still untracked.
+async function added_scripts(base: string, targets: ReadonlyArray<string>): Promise<Array<string>> {
+	const held = new Set(await changed_paths.read_held_at(base, targets))
+
+	return targets.filter((file) => !held.has(file) && test_pinned_functions.is_script(file))
+}
+
+// Without `typescript` (an optional peer in a consumer) no function can be read, so every added file
+// is reported unchecked rather than passed as pinned.
+async function stub_hunks_of(added: ReadonlyArray<string>): Promise<StubRead> {
+	const api = review_code_tree.load_typescript(process.cwd())
+	if (api === undefined) return { hunks: [], unparsed: added }
+	const contents = await Promise.all(added.map(async (file) => await readFile(file, 'utf8')))
+	const hunks = added.flatMap((file, index) =>
+		test_pinned_functions.stub_hunks(api, file, contents[index] ?? ''),
+	)
+
+	return { hunks, unparsed: [] }
+}
+
+// A changed hunk whose revert emits the same JavaScript, or a rewire, is dropped before the cap
+// (`test-pinned-emit.ts`), so neither is `unchecked`; without `typescript` every hunk is kept, so the
+// run checks more rather than less.
+async function runtime_hunks(hunks: ReadonlyArray<Hunk>): Promise<ProbeRead> {
+	const api = review_code_tree.load_typescript(process.cwd())
+	if (api === undefined) return { hunks: [...hunks], unparsed: [], rewired: 0 }
+	const contents = await Promise.all(hunks.map(async (hunk) => await readFile(hunk.file, 'utf8')))
+
+	return { ...test_pinned_emit.probed_of(api, hunks, contents), unparsed: [] }
+}
+
+async function read_probes(base: string, targets: ReadonlyArray<string>): Promise<ProbeRead> {
+	const stubs = await stub_hunks_of(await added_scripts(base, targets))
+	const changed = await runtime_hunks(await read_hunks(base, targets))
+	const hunks = [...changed.hunks, ...stubs.hunks]
+
+	return { hunks, unparsed: stubs.unparsed, rewired: changed.rewired }
+}
+
+// The work tree's files that differ from `commit`, deleted ones dropped. Read since `HEAD` they are
+// what the worktree at `HEAD` needs copied in to hold the work tree — a conflicted merge's incoming
+// files included; read since the change base they are this branch's own change.
+async function existing_since(commit: string): Promise<Array<string>> {
+	const changed = await changed_paths.read_changed_since(commit)
+
+	return changed.filter((file) => existsSync(file))
+}
+
+async function report_on(
+	base: string,
+	options: RunOptions,
+	has_runner: boolean,
+): Promise<PinnedReport> {
+	const { max_hunks } = options
+	const paths = await existing_since(HEAD)
+	const changed = await existing_since(base)
+	const targets = await test_pinned_reach.probed_files(
+		changed.filter((file) => test_pinned_logic.is_target(file)),
+	)
+	const probes = await read_probes(base, targets)
+	const { checked, unchecked } = test_pinned_logic.split(probes.hunks, has_runner ? max_hunks : 0)
+	const outcome = await outcome_on(base, paths, checked, { ...options, rewired: probes.rewired })
+
+	return { ...outcome, unchecked, unparsed: probes.unparsed, max_hunks, has_runner }
+}
+
+async function report(options: RunOptions): Promise<PinnedReport> {
+	const base = await change_base.resolved_through_merge()
+	const has_runner = test_red.has_runner()
+	if (base === undefined) return { ...NO_REPORT, max_hunks: options.max_hunks, has_runner }
+
+	return await report_on(base, options, has_runner)
+}
+
+// No merge-base (not a repository, no default branch) checks nothing, as `josh test:red` does. The cap
+// is shared: changed hunks first, then the added files' functions. Without Vitest (a consumer that has
+// none) no probe runs, so every one is unchecked rather than unpinned. `is_first_unpinned` starts no
+// probe once one is unpinned (joshuafolkken/kit#5153): the hunks left are reported `cut`. `origin` is
+// what started the run, for its ledger row.
+async function run(
+	max_hunks: number,
+	is_first_unpinned = false,
+	origin?: PinnedOrigin,
+): Promise<PinnedReport> {
+	return await report({ max_hunks, is_cached_only: false, is_first_unpinned, origin })
+}
+
+// The unpinned hunks the cache already answers for this tree, probing nothing (joshuafolkken/kit#4936):
+// what a check still running — or one stopped mid-way — has reached for the hunks that did not move.
+async function cached(max_hunks: number): Promise<PinnedReport> {
+	return await report({ max_hunks, is_cached_only: true })
+}
+
+// The cached report when the cache holds every checked hunk's verdict for this tree, probing nothing
+// (joshuafolkken/kit#5078); `undefined` when a hunk moved or was never probed, so the caller probes.
+async function held_report(max_hunks: number): Promise<PinnedReport | undefined> {
+	const read = await cached(max_hunks)
+
+	return read.is_held === true ? read : undefined
+}
+
+const test_pinned = { cached, held_report, run }
+
+export { test_pinned }

package/scripts/test/test-reach-cli.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env tsx
+import { existsSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { test_pinned_reach } from './test-pinned-reach'
+
+// `josh test:reach <file...>` — how many test files each file's imports reach, the count
+// `josh test:related` sizes its core claim by, one `<count> <file>` line per file
+// (joshuafolkken/kit#5238): an overrun filing or a baseline measures it without a hand-written probe.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: josh test:reach <file...>'
+const NO_GRAPH =
+	'josh test:reach: no import graph can be built here (no typescript or tsconfig.json)'
+
+function is_file(path: string): boolean {
+	return existsSync(path) && statSync(path).isFile()
+}
+
+// A path no file answers — absent, or a directory — reaches no test, so its `0` would read as a
+// measured count: `pnpm josh` runs from the repository root, where a path typed relative to a
+// subdirectory names nothing.
+function refusal(argv: ReadonlyArray<string>): string | undefined {
+	if (argv.length === 0) return USAGE
+	const missing = argv.filter((file) => !is_file(file))
+	if (missing.length === 0) return undefined
+
+	return `josh test:reach: no such file from the repository root: ${missing.join(', ')}`
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const refused = refusal(argv)
+
+	if (refused !== undefined) {
+		console.error(refused)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const counts = await test_pinned_reach.reached_test_counts(argv)
+
+	if (counts === undefined) {
+		console.error(NO_GRAPH)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(counts.map(({ file, count }) => `${String(count)} ${file}`).join('\n'))
+
+	return 0
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const test_reach_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { test_reach_cli }

package/scripts/test/test-read-map.ts

@@ -0,0 +1,288 @@
+import { readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { run_record_path } from '#scripts/josh/run-record-path'
+import { atomic_write } from '#scripts/lib/atomic-write'
+import { json_value } from '#scripts/lib/json-value'
+import { test_read_trace, type ReadRecords } from './test-read-trace'
+
+// The test-read map: for every repository path a full unit run read, the modules that read it.
+// `josh test:related` resolves a changed non-code file through it to the code files `vitest related`
+// can walk, so a changed document runs the tests that read it rather than the whole suite.
+//
+// **The map is valid against the tree it was recorded on, and only that tree.** It records the
+// commit and the files that differed from it, so the change a narrowing reads is the change since
+// then. A tree whose own code changed what it reads has changed that code, and `vitest related`
+// runs the tests importing it. **It lives in the git common directory**, which every lane worktree of
+// one clone shares along with the commits it names, so one lane's full run narrows the next lane's.
+// **One file per version** (joshuafolkken/kit#4423): a lane on an older kit writing its map leaves a
+// newer lane's map in place, so a version bump no longer sends either to the whole suite.
+
+interface ReadMap {
+	version: number
+	commit: string
+	// The files that differed from `commit` when the map was recorded, each with the digest of its
+	// content then (`input_fingerprint.of_files`), so one whose content has not moved since does not count as changed
+	// (joshuafolkken/kit#4425).
+	dirty: Record<string, string>
+	// The recording checkout's change as a test reads it through git — the branch diff from the change
+	// base plus the untracked files (`changed_paths.read_changed_paths`), committed or not
+	// (joshuafolkken/kit#4734).
+	change: Array<string>
+	// The directories `commit` holds, so a directory new since then is told apart from one no test
+	// read — the map's own keys cannot say which, since an unread directory has none.
+	directories: Array<string>
+	readers: ReadRecords
+}
+
+// Bumped whenever the shape, what a reader means or how `dirty` is digested changes, so a map an older
+// kit wrote reads as no map at all and the next full run writes it afresh. 6: `dirty` is
+// `input-fingerprint.ts`'s digest of every changed file (joshuafolkken/kit#4497). 7: `change`
+// (joshuafolkken/kit#4734). 8: a module is a reader only of what its evaluation read
+// (joshuafolkken/kit#5033).
+const MAP_VERSION = 8
+
+const MAP_FILE_STEM = 'test-read-map'
+const RECORD_EXTENSION = '.json'
+
+// A map file of another version no lane has written for this long belongs to no kit still running,
+// and is removed by the next write: one week.
+const STALE_AFTER_MS = 604_800_000
+
+type ReadPair = [string, string]
+
+function record_pairs(record: ReadRecords): Array<ReadPair> {
+	return Object.entries(record).flatMap(([read_path, readers]) =>
+		readers.map((reader): ReadPair => [read_path, reader]),
+	)
+}
+
+function merge_records(records: ReadonlyArray<ReadRecords>): ReadRecords {
+	const merged = new Map<string, Set<string>>()
+	const pairs = records.flatMap((record) => record_pairs(record))
+
+	for (const [read_path, reader] of pairs) {
+		test_read_trace.add_reader(merged, read_path, reader)
+	}
+
+	return test_read_trace.to_records(merged)
+}
+
+function is_object(value: unknown): value is object {
+	return typeof value === 'object' && value !== null
+}
+
+function is_string_array(value: unknown): value is Array<string> {
+	return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+}
+
+function is_read_records(value: unknown): value is ReadRecords {
+	return is_object(value) && Object.values(value).every(is_string_array)
+}
+
+function is_digest_record(value: unknown): value is Record<string, string> {
+	if (!is_object(value) || Array.isArray(value)) return false
+
+	return Object.values(value).every((digest) => typeof digest === 'string')
+}
+
+const FIELD_CHECKS: ReadonlyArray<[keyof ReadMap, (field: unknown) => boolean]> = [
+	['version', (field) => field === MAP_VERSION],
+	['commit', (field) => typeof field === 'string'],
+	['dirty', is_digest_record],
+	['change', is_string_array],
+	['directories', is_string_array],
+	['readers', is_read_records],
+]
+
+function is_read_map(value: unknown): value is ReadMap {
+	if (!is_object(value)) return false
+
+	return FIELD_CHECKS.every(([field, is_valid]) => is_valid(Reflect.get(value, field)))
+}
+
+// **The files whose content differs from the tree the map was recorded on** (joshuafolkken/kit#4425).
+// `since` is every path that differs from `map.commit` now, and `current` the digest of every path
+// that was dirty then. A path dirty then is changed only when its digest moved: counted by name, a
+// lane's own change the map was recorded over read as changed on every later run, so a gate reused
+// no green unit step whenever the lane held any code.
+function changed_since_tree(
+	map: ReadMap,
+	since: ReadonlyArray<string>,
+	current: Readonly<Record<string, string>>,
+): Array<string> {
+	const fresh = since.filter((file) => !Object.hasOwn(map.dirty, file))
+	const moved = Object.entries(map.dirty)
+		.filter(([file, digest]) => current[file] !== digest)
+		.map(([file]) => file)
+
+	return [...new Set([...fresh, ...moved])]
+}
+
+function parse_map(text: string): ReadMap | undefined {
+	const value = json_value.parse_or_undefined(text)
+
+	return is_read_map(value) ? value : undefined
+}
+
+function parse_records(text: string): ReadRecords {
+	const value = json_value.parse_or_undefined(text)
+
+	return is_read_records(value) ? value : {}
+}
+
+// Innermost first, ending at the root `.`.
+function directories_above(relative: string): Array<string> {
+	const parent = path.dirname(relative)
+
+	if (parent === relative) return []
+
+	return [parent, ...directories_above(parent)]
+}
+
+// The directories on the file's path the recorded commit did not hold, innermost first. The root
+// always existed.
+function created_directories(
+	directories: ReadonlyArray<string>,
+	recorded: ReadonlySet<string>,
+): Array<string> {
+	return directories.filter(
+		(directory) => directory !== test_read_trace.ROOT_ENTRY && !recorded.has(directory),
+	)
+}
+
+// A changed file is read by whoever read it, listed its own directory or walked any directory above
+// it. A directory new since the recording is also a new entry in the listing above it and a probe of
+// it that now answers differently; a directory that already existed reads the same to both, whatever
+// changed deeper down.
+//
+// **A run record reaches only a test that read it by name** (joshuafolkken/kit#5001): a test listing or
+// walking the root or `.josh/` reads the checkout around it, not the observation or accepted metrics
+// a lane writes after its checks went green, so those keys would run every such test for bookkeeping.
+function lookup_keys(relative: string, recorded: ReadonlySet<string>): Array<string> {
+	if (run_record_path.is_run_record(relative)) return [relative]
+
+	const directories = directories_above(relative)
+	const created = created_directories(directories, recorded)
+	const listed = [
+		directories[0] ?? test_read_trace.ROOT_ENTRY,
+		...created.map((directory) => path.dirname(directory)),
+	]
+
+	return [
+		relative,
+		...created,
+		...listed.map((directory) => test_read_trace.read_key(directory, 'listing')),
+		...directories.map((directory) => test_read_trace.read_key(directory, 'walk')),
+	]
+}
+
+function readers_of(map: ReadMap, relative: string): Array<string> {
+	const keys = lookup_keys(relative, new Set(map.directories))
+
+	return [...new Set(keys.flatMap((key) => map.readers[key] ?? []))]
+}
+
+// **A directory inside which no recorded test listed, walked or read any entry** (joshuafolkken/kit#4303).
+// A file added to it since is one no test reads, as surely as one the tree already held there: a test
+// that builds a path into it reads some file there, and one that enumerates it lists it, both of which
+// leave a key whose directory is this one — a read is recorded before it runs, so a path absent then
+// still leaves its key. **A directory new since the recording counts too** (joshuafolkken/kit#4597):
+// a probe of it or a listing of its parent is one of `readers_of`'s keys, which the caller asks first.
+// **A read of the recording tree's own change does not count** (joshuafolkken/kit#4734): a test that
+// reads this checkout's change through git reads whatever file the recording lane held, so its own
+// `.josh/metrics-accepted/<N>.json` marked that directory read and sent the next lane's to the whole
+// suite. A listing or a walk of the directory, or a read of any other file there, still counts — except
+// for a run record, which only a read of itself reaches (`lookup_keys`).
+function in_unread_directory(map: ReadMap, relative: string): boolean {
+	if (run_record_path.is_run_record(relative)) return true
+
+	const directory = path.dirname(relative)
+	const change = new Set(map.change)
+	const keys = Object.keys(map.readers).filter((key) => !change.has(key))
+
+	return keys.every((key) => path.dirname(key) !== directory)
+}
+
+function map_path(root: string, version: number = MAP_VERSION): string | undefined {
+	const common = git_common_directory.repository(root)
+	const name = `${MAP_FILE_STEM}.v${String(version)}${RECORD_EXTENSION}`
+
+	return common === undefined
+		? undefined
+		: path.join(common, git_common_directory.STATE_DIRECTORY, name)
+}
+
+// Every version's map, the unversioned one kits before joshuafolkken/kit#4423 wrote included; a
+// staging file ends in `.tmp`, not the extension.
+function is_map_file(name: string): boolean {
+	return name.startsWith(MAP_FILE_STEM) && name.endsWith(RECORD_EXTENSION)
+}
+
+// A file another lane's write pruned meanwhile has no stat, and is not this write's to remove.
+function is_stale(file_path: string, now: number): boolean {
+	const modified = statSync(file_path, { throwIfNoEntry: false })?.mtimeMs ?? now
+
+	return now - modified > STALE_AFTER_MS
+}
+
+// The map just written is never stale, so it survives its own prune.
+function prune_stale_maps(directory: string): void {
+	const now = Date.now()
+	const maps = readdirSync(directory)
+		.filter((name) => is_map_file(name))
+		.map((name) => path.join(directory, name))
+
+	for (const file_path of maps) {
+		if (is_stale(file_path, now)) rmSync(file_path, { force: true })
+	}
+}
+
+function read_text(file_path: string): string | undefined {
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function read_map(root: string): ReadMap | undefined {
+	const file_path = map_path(root)
+	const text = file_path === undefined ? undefined : read_text(file_path)
+
+	return text === undefined ? undefined : parse_map(text)
+}
+
+// Written beside the target and renamed over it, so a lane reading the map while another lane
+// replaces it reads one whole map or the other. It lands in its own version's file.
+function write_map(root: string, map: ReadMap): void {
+	const file_path = map_path(root, map.version)
+
+	if (file_path === undefined) return
+
+	atomic_write.replace_file(file_path, JSON.stringify(map))
+	prune_stale_maps(path.dirname(file_path))
+}
+
+// Every worker writes its own files into the run's directory; this reads them all back.
+function collect_records(directory: string): Array<ReadRecords> {
+	return readdirSync(directory)
+		.filter((name) => name.endsWith(RECORD_EXTENSION))
+		.map((name) => parse_records(read_text(path.join(directory, name)) ?? ''))
+}
+
+const test_read_map = {
+	MAP_VERSION,
+	changed_since_tree,
+	collect_records,
+	in_unread_directory,
+	map_path,
+	merge_records,
+	parse_map,
+	read_map,
+	readers_of,
+	write_map,
+}
+
+export type { ReadMap }
+export { test_read_map }