@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/test/test-pinned-logic.ts

@@ -0,0 +1,145 @@
+import { test_declared_logic } from './test-declared-logic'
+import { related_scope } from './test-related-scope'
+
+// The pure half of `josh test:pinned` (joshuafolkken/kit#4516): read a `git diff -U0` into hunks, put
+// one hunk's old lines back into the changed file, and split the hunks at the run's cap. The run itself
+// is `test-pinned.ts`.
+
+const DEFAULT_MAX_HUNKS = 20
+const HEADER = /^@@ -\d+(?:,\d+)? \+(?<start>\d+)(?:,(?<count>\d+))? @@/u
+const FILE_HEADER = '+++ b/'
+const SECTION_HEADER = 'diff --git '
+const OLD_LINE = '-'
+const OLD_FILE_HEADER = '--- '
+const LINE_BREAK = '\n'
+const GREEN_REASON = 'reverting it left every related test green'
+const NO_TEST_REASON = 'no related test ran with it reverted'
+
+interface Hunk {
+	file: string
+	// The first changed line of the working file; for a pure deletion, the line the removed ones sat after.
+	new_start: number
+	new_count: number
+	old_lines: Array<string>
+}
+
+interface HunkSplit {
+	checked: ReadonlyArray<Hunk>
+	unchecked: ReadonlyArray<Hunk>
+}
+
+// A reverted hunk nothing went red on: `is_green` when its related tests ran and passed, otherwise none
+// ran at all — no related test, or a vitest that stopped before running one.
+interface UnpinnedHunk extends Hunk {
+	is_green: boolean
+}
+
+interface PinnedReport {
+	unpinned: ReadonlyArray<UnpinnedHunk>
+	unchecked: ReadonlyArray<Hunk>
+	max_hunks: number
+}
+
+interface DiffWalk {
+	file: string
+	hunks: Array<Hunk>
+}
+
+// A test file is never reverted, and only a file vitest can walk an import graph back from has related
+// tests to run.
+function is_target(file: string): boolean {
+	return !test_declared_logic.is_test_file(file) && related_scope.is_relatable(file)
+}
+
+// An omitted count is one line (`@@ -3 +3 @@`).
+function count_of(group: string | undefined): number {
+	return group === undefined ? 1 : Number(group)
+}
+
+function hunk_from(file: string, line: string): Hunk | undefined {
+	const groups = HEADER.exec(line)?.groups
+	if (groups === undefined) return undefined
+
+	return {
+		file,
+		new_start: Number(groups['start']),
+		new_count: count_of(groups['count']),
+		old_lines: [],
+	}
+}
+
+function is_old_line(line: string): boolean {
+	return line.startsWith(OLD_LINE) && !line.startsWith(OLD_FILE_HEADER)
+}
+
+// Each file section starts unnamed, so a `+++` line this does not read (a quoted path with a space)
+// leaves its hunks on no file rather than on the previous one.
+function file_after(file: string, line: string): string {
+	if (line.startsWith(FILE_HEADER)) return line.slice(FILE_HEADER.length)
+
+	return line.startsWith(SECTION_HEADER) ? '' : file
+}
+
+function step(walk: DiffWalk, line: string): void {
+	walk.file = file_after(walk.file, line)
+	const hunk = hunk_from(walk.file, line)
+
+	if (hunk !== undefined) walk.hunks.push(hunk)
+	else if (is_old_line(line)) walk.hunks.at(-1)?.old_lines.push(line.slice(OLD_LINE.length))
+}
+
+// One `-U0` diff into its hunks, in diff order. The `+` lines are not kept: the working file already
+// holds them, at `new_start` for `new_count` lines.
+function parse_hunks(diff: string): Array<Hunk> {
+	const walk: DiffWalk = { file: '', hunks: [] }
+
+	for (const line of diff.split(LINE_BREAK)) step(walk, line)
+
+	return walk.hunks.filter((hunk) => is_target(hunk.file))
+}
+
+// A pure deletion's `new_start` names the line before the gap, so the old lines go in after it.
+function start_index(hunk: Hunk): number {
+	return hunk.new_count === 0 ? hunk.new_start : hunk.new_start - 1
+}
+
+// The working file's content with this one hunk put back to the base's lines.
+function revert(content: string, hunk: Hunk): string {
+	const lines = content.split(LINE_BREAK)
+
+	lines.splice(start_index(hunk), hunk.new_count, ...hunk.old_lines)
+
+	return lines.join(LINE_BREAK)
+}
+
+function split(hunks: ReadonlyArray<Hunk>, max_hunks: number): HunkSplit {
+	return { checked: hunks.slice(0, max_hunks), unchecked: hunks.slice(max_hunks) }
+}
+
+function location(hunk: Hunk): string {
+	return `${hunk.file}:${String(Math.max(hunk.new_start, 1))}`
+}
+
+function format(report: PinnedReport): string {
+	const unpinned = report.unpinned.map(
+		(hunk) => `unpinned ${location(hunk)} — ${hunk.is_green ? GREEN_REASON : NO_TEST_REASON}`,
+	)
+	const unchecked = report.unchecked.map(
+		(hunk) => `unchecked ${location(hunk)} — over the ${String(report.max_hunks)}-hunk cap`,
+	)
+
+	return [...unpinned, ...unchecked].join(LINE_BREAK)
+}
+
+const test_pinned_logic = {
+	DEFAULT_MAX_HUNKS,
+	format,
+	is_target,
+	location,
+	parse_hunks,
+	revert,
+	split,
+}
+
+export type { Hunk, PinnedReport, UnpinnedHunk }
+export { test_pinned_logic }

package/scripts/test/test-pinned-main.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { test_pinned } from './test-pinned'
+import { test_pinned_logic, type PinnedReport } from './test-pinned-logic'
+
+// The `josh test:pinned` entry: read `--max`, run, print one line per unpinned or unchecked hunk, and
+// exit non-zero when any checked hunk is unpinned. An unchecked hunk alone does not fail the run — it
+// was not asked about.
+
+const CLEAN_EXIT = 0
+const FAILED_EXIT = 1
+const ARGV_OFFSET = 2
+const USAGE = [
+	'Usage: josh test:pinned [--max <n>] [--help]',
+	'  revert each changed hunk of a non-test code file and run its related tests;',
+	'  prints `unpinned <file>:<line>` for a hunk no test went red on, and',
+	`  \`unchecked <file>:<line>\` past the --max cap (default ${String(test_pinned_logic.DEFAULT_MAX_HUNKS)})`,
+].join('\n')
+
+const PARSE_ARGS_OPTIONS = {
+	help: { type: 'boolean', short: 'h', default: false },
+	max: { type: 'string' },
+} as const
+
+const HELP_FLAGS: ReadonlySet<string> = new Set(['--help', '-h'])
+
+// A `--max` that is not a whole number above zero is a refusal, not the default.
+function valid_max(raw: string | undefined): number | undefined {
+	const max = Number(raw ?? test_pinned_logic.DEFAULT_MAX_HUNKS)
+
+	return Number.isSafeInteger(max) && max > 0 ? max : undefined
+}
+
+// `undefined` prints the usage: a help request, an unknown flag, or a missing or invalid `--max`.
+function max_hunks_of(argv: ReadonlyArray<string>): number | undefined {
+	try {
+		const { values } = parseArgs({ args: [...argv], options: PARSE_ARGS_OPTIONS, strict: true })
+
+		return values.help ? undefined : valid_max(values.max)
+	} catch {
+		return undefined
+	}
+}
+
+// Clean for an explicit help request; a refusal for anything the parse did not understand.
+function print_usage(argv: ReadonlyArray<string>): number {
+	process.stderr.write(`${USAGE}\n`)
+
+	return argv.some((argument) => HELP_FLAGS.has(argument)) ? CLEAN_EXIT : FAILED_EXIT
+}
+
+function output(report: PinnedReport): string {
+	const unpinned = String(report.unpinned.length)
+	const unchecked = String(report.unchecked.length)
+	const lines = [`unpinned ${unpinned} · unchecked ${unchecked}`, test_pinned_logic.format(report)]
+
+	return `${lines.filter((line) => line !== '').join('\n')}\n`
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<number> {
+	const max_hunks = max_hunks_of(argv)
+	if (max_hunks === undefined) return print_usage(argv)
+
+	const report = await test_pinned.run(max_hunks)
+
+	process.stdout.write(output(report))
+
+	return report.unpinned.length === 0 ? CLEAN_EXIT : FAILED_EXIT
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await main(process.argv.slice(ARGV_OFFSET))
+}
+
+const test_pinned_main = { main }
+
+export { test_pinned_main }

package/scripts/test/test-pinned.ts

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { base_tree, type BaseTree } from '#scripts/git/base-tree'
+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 {
+	test_pinned_logic,
+	type Hunk,
+	type PinnedReport,
+	type UnpinnedHunk,
+} from './test-pinned-logic'
+import { test_red } from './test-red'
+import type { RedVerdict } 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 TREE_PREFIX = 'josh-test-pinned-'
+const HEAD = 'HEAD'
+
+// `--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. 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 verdict with this one hunk reverted. The file is put back before the next hunk runs, or that
+// hunk's tests would also see this revert.
+async function verdict_of(tree: BaseTree, hunk: Hunk): Promise<RedVerdict> {
+	const target = path.join(tree.tree, hunk.file)
+	const content = await readFile(target, 'utf8')
+
+	await writeFile(target, test_pinned_logic.revert(content, hunk))
+
+	try {
+		return await test_red.verdict_in(tree, ['related', hunk.file, '--run'])
+	} finally {
+		await writeFile(target, content)
+	}
+}
+
+// One hunk at a time: two reverts in flight would share the tree, and each run is already a whole vitest.
+// Green and no-test both leave a hunk unpinned: either way nothing went red when it was reverted.
+async function unpinned_in(
+	tree: BaseTree,
+	hunks: ReadonlyArray<Hunk>,
+): Promise<Array<UnpinnedHunk>> {
+	const unpinned: Array<UnpinnedHunk> = []
+
+	for (const hunk of hunks) {
+		// eslint-disable-next-line no-await-in-loop -- the hunks share one tree, so each revert waits for the last restore
+		const verdict = await verdict_of(tree, hunk)
+		if (verdict !== 'red') unpinned.push({ ...hunk, is_green: verdict === 'green' })
+	}
+
+	return unpinned
+}
+
+async function unpinned_on(
+	paths: ReadonlyArray<string>,
+	hunks: ReadonlyArray<Hunk>,
+): Promise<Array<UnpinnedHunk>> {
+	if (hunks.length === 0) return []
+
+	return await base_tree.with_tree(TREE_PREFIX, HEAD, async (tree) => {
+		await base_tree.copy_in(tree.tree, paths)
+
+		return await unpinned_in(tree, hunks)
+	})
+}
+
+// No merge-base (not a repository, no default branch) checks nothing, as `josh test:red` does.
+async function run(max_hunks: number): Promise<PinnedReport> {
+	const base = await change_base.resolved()
+	const changed = await changed_paths.read_changed_paths(false)
+	const paths = changed.filter((file) => existsSync(file))
+	const targets = paths.filter((file) => test_pinned_logic.is_target(file))
+	const hunks = base === undefined ? [] : await read_hunks(base, targets)
+	const { checked, unchecked } = test_pinned_logic.split(hunks, max_hunks)
+
+	return { unpinned: await unpinned_on(paths, checked), unchecked, max_hunks }
+}
+
+const test_pinned = { run }
+
+export { test_pinned }

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

@@ -0,0 +1,264 @@
+import { readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+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 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).
+const MAP_VERSION = 6
+
+const MAP_DIRECTORY = 'josh'
+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],
+	['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.
+function lookup_keys(relative: string, recorded: ReadonlySet<string>): Array<string> {
+	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 the recorded tree held, 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.
+function in_unread_directory(map: ReadMap, relative: string): boolean {
+	const directory = path.dirname(relative)
+
+	if (!map.directories.includes(directory)) return false
+
+	return Object.keys(map.readers).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, MAP_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 }

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

@@ -0,0 +1,91 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { input_fingerprint } from '#scripts/gate/input-fingerprint'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_command } from '#scripts/git/git-command'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { test_read_map, type ReadMap } from './test-read-map'
+import { test_read_trace } from './test-read-trace'
+
+// When a unit run records the test-read map, and how the records become one. **Only a run of the
+// whole suite records**: a map is read as "nothing else reads this file", which a narrowed, sharded
+// or filtered run cannot vouch for. **Only a green run replaces the map**: a failed test may have
+// stopped before the read it would have made.
+
+type RecordingEnvironment = Record<string, string>
+
+const RUN_SUBCOMMAND = 'run'
+
+// The one flag a whole-suite run still carries — the gate's worker cap, which sizes the run without
+// narrowing it.
+const WORKER_FLAG_PREFIX = '--maxWorkers'
+
+const RECORD_DIRECTORY_PREFIX = 'josh-test-reads-'
+
+function is_recordable(vitest_arguments: ReadonlyArray<string>): boolean {
+	const [subcommand, ...flags] = vitest_arguments
+
+	return subcommand === RUN_SUBCOMMAND && flags.every((flag) => flag.startsWith(WORKER_FLAG_PREFIX))
+}
+
+// Every directory the commit holds, NUL-separated so a name git would quote reads as itself.
+async function commit_directories(commit: string): Promise<Array<string>> {
+	const output = await git_spawn.read(['ls-tree', '-r', '-d', '--name-only', '-z', commit])
+
+	return output.split('\0').filter((listed) => listed.length > 0)
+}
+
+type TreeSnapshot = Pick<ReadMap, 'commit' | 'dirty' | 'directories'>
+
+// The tree the run read: the commit, every file that differed from it with its content's digest, and
+// the directories it holds. **Read before the run starts**: a digest taken after it would vouch for
+// an edit made while the tests ran as content they read.
+async function tree_snapshot(root: string): Promise<TreeSnapshot> {
+	const commit = await git_command.head_commit()
+	const dirty = input_fingerprint.of_files(root, await changed_paths.read_changed_since(commit))
+
+	return { commit, dirty, directories: await commit_directories(commit) }
+}
+
+// A map that cannot be written — no git, a read-only common directory — leaves the previous map in
+// place, and a narrowing over a stale map is refused by the commit it names.
+function save_map(root: string, directory: string, snapshot: TreeSnapshot): void {
+	try {
+		const readers = test_read_map.merge_records(test_read_map.collect_records(directory))
+
+		test_read_map.write_map(root, { version: test_read_map.MAP_VERSION, ...snapshot, readers })
+	} catch {
+		// The previous map stays; the run's own result is unaffected.
+	}
+}
+
+async function with_read_recording(
+	root: string,
+	vitest_arguments: ReadonlyArray<string>,
+	run: (environment: RecordingEnvironment) => Promise<number>,
+): Promise<number> {
+	if (!is_recordable(vitest_arguments)) return await run({})
+
+	const directory = mkdtempSync(path.join(tmpdir(), RECORD_DIRECTORY_PREFIX))
+
+	try {
+		// Settled rather than awaited, so a tree git cannot read records no map and fails no run.
+		const [tree] = await Promise.allSettled([tree_snapshot(root)])
+		const exit_code = await run({
+			[test_read_trace.RECORD_DIRECTORY_KEY]: directory,
+			[test_read_trace.ROOT_KEY]: root,
+		})
+
+		if (exit_code === 0 && tree.status === 'fulfilled') save_map(root, directory, tree.value)
+
+		return exit_code
+	} finally {
+		rmSync(directory, { recursive: true, force: true })
+	}
+}
+
+const test_read_recording = { is_recordable, with_read_recording }
+
+export type { RecordingEnvironment }
+export { test_read_recording }