@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -0,0 +1,194 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { import_graph, type ImportGraph } from '#scripts/lint/import-graph'
+import { test_declared_logic } from './test-declared-logic'
+import { test_pinned_cache_logic } from './test-pinned-cache-logic'
+import { test_pinned_spawn, type TestSpawn } from './test-pinned-spawn'
+import { related_scope } from './test-related-scope'
+import { whole_suite_files } from './whole-suite-files'
+
+// What one `josh test:pinned` verdict rests on, read off the import graph (joshuafolkken/kit#4873): the
+// `basis` `test-pinned-cache-logic.ts` holds a verdict by past the tree-wide digests. The graph is built
+// on the first basis asked for, so a rerun the tree-wide digests already hold builds none — unless a
+// changed fixture asks `probed_files` for its reach.
+//
+// **Where no graph can be built (no `typescript`, no `tsconfig.json`) every basis is undefined**, and a
+// verdict holds only by the tree-wide digests, as before.
+
+const NUL = '\0'
+const FIXTURE_MARK = '-fixture'
+
+// `related` names the tests reaching a file, which `test-pinned-cache-logic.ts` turns into a basis.
+interface Reach {
+	related: (file: string) => Promise<Array<string> | undefined>
+	failed: (tests: ReadonlyArray<string>) => Promise<string | undefined>
+}
+
+// What a basis is read against: the base commit, each changed non-test path with its content's digest,
+// and each test file's.
+interface ReachInputs {
+	commit: string
+	code: ReadonlyArray<string>
+	digests: ReadonlyMap<string, string>
+	test_digests: ReadonlyMap<string, string>
+}
+
+// One file and how many test files its imports reach.
+interface ReachedCount {
+	file: string
+	count: number
+}
+
+interface GraphView {
+	graph: ImportGraph
+	universe: ReadonlyArray<string>
+	spawn: TestSpawn
+}
+
+// Every file in the work tree, tracked or untracked but not ignored. `-z` lists a path as it is,
+// where `core.quotePath` would quote a non-ASCII one.
+async function work_tree_files(): Promise<Array<string>> {
+	const listed = await git_spawn.read(['ls-files', '-coz', '--exclude-standard'])
+
+	return listed.split(NUL).filter((file) => file !== '')
+}
+
+// Every code file the work tree holds, as absolute paths the graph resolves to.
+async function code_universe(): Promise<Array<string>> {
+	const files = await work_tree_files()
+	const code = files.filter((file) => related_scope.is_relatable(file) && existsSync(file))
+
+	return code.map((file) => path.resolve(file))
+}
+
+async function view_of(): Promise<GraphView | undefined> {
+	const graph = await import_graph.create(process.cwd())
+	if (graph === undefined) return undefined
+
+	const universe = await code_universe()
+
+	return { graph, universe, spawn: test_pinned_spawn.create(graph, universe) }
+}
+
+// A code file nothing imports that is not a test: a config, a setup file or a CLI a test spawns.
+function is_root(view: GraphView, file: string): boolean {
+	const relative = path.relative(process.cwd(), file)
+	if (test_declared_logic.is_test_file(relative)) return false
+
+	return view.graph.importers([file], view.universe).size <= 1
+}
+
+// A changed path no graph ties to the tests that read it: a non-code file a test reads, or one every
+// test depends on without importing it (the vitest config, the setup files, the lock).
+function is_shared(file: string): boolean {
+	return (
+		!related_scope.is_relatable(file) ||
+		whole_suite_files.WHOLE_SUITE_FILES.has(path.normalize(file))
+	)
+}
+
+// A shared path, or a code file a root reaches — the root itself or a module it imports, which a test
+// spawning it runs past any closure.
+function is_asset(view: GraphView, file: string): boolean {
+	if (is_shared(file)) return true
+	const reached = view.graph.runtime_importers([path.resolve(file)], view.universe)
+
+	return [...reached].some((reader) => is_root(view, reader))
+}
+
+// The mark of the test-only modules `package.json`'s `files` keeps out of the published package.
+function is_fixture(file: string): boolean {
+	return path.basename(file).includes(FIXTURE_MARK)
+}
+
+// The changed files `josh test:pinned` probes (joshuafolkken/kit#4879): a fixture no root reaches only
+// moves what its tests cover, so its hunks hold no runtime behavior a test could pin. One a root reaches is
+// kept, and so is every fixture where no graph can be built; the graph is built only for a fixture.
+async function probed_files(files: ReadonlyArray<string>): Promise<Array<string>> {
+	if (files.every((file) => !is_fixture(file))) return [...files]
+	const view = await view_of()
+	if (view === undefined) return [...files]
+
+	return files.filter((file) => !is_fixture(file) || is_asset(view, file))
+}
+
+// The test files whose runtime imports reach `file` — the graph vitest walks (joshuafolkken/kit#5368).
+function related_of(view: GraphView, file: string): Array<string> {
+	const reached = view.graph.runtime_importers([path.resolve(file)], view.universe)
+
+	return [...reached]
+		.map((reader) => path.relative(process.cwd(), reader))
+		.filter((reader) => test_declared_logic.is_test_file(reader))
+}
+
+// How many test files the imports of `files` reach, a listed test counting itself — what
+// `josh test:related` sizes its core claim by before vitest walks the same graph
+// (joshuafolkken/kit#5135). Undefined where no graph can be built.
+async function reached_test_count(files: ReadonlyArray<string>): Promise<number | undefined> {
+	const view = await view_of()
+	if (view === undefined) return undefined
+
+	return new Set(files.flatMap((file) => related_of(view, file))).size
+}
+
+// Each file's own `reached_test_count`, over one graph — what `josh test:reach` prints
+// (joshuafolkken/kit#5238). Undefined where no graph can be built.
+async function reached_test_counts(
+	files: ReadonlyArray<string>,
+): Promise<Array<ReachedCount> | undefined> {
+	const view = await view_of()
+	if (view === undefined) return undefined
+
+	return files.map((file) => ({ file, count: related_of(view, file).length }))
+}
+
+// None where no failed test is named or one is gone: what such a red rests on, no graph names. Past
+// the failed tests' closures it rests on the shared paths and on each file they can start, with its
+// closure (joshuafolkken/kit#5261) — a root no failed test names moves no verdict of theirs.
+function failed_of(
+	view: GraphView,
+	tests: ReadonlyArray<string>,
+	inputs: ReachInputs,
+): string | undefined {
+	if (tests.length === 0 || tests.some((test) => !inputs.test_digests.has(test))) return undefined
+	const started = view.spawn.started(tests.map((test) => path.resolve(test)))
+	const run = [...tests, ...[...started].map((file) => path.relative(process.cwd(), file))]
+	const closures = run.map((file) => [file, view.graph.closure_hash(path.resolve(file))] as const)
+	const assets = inputs.code.filter((file) => is_shared(file) || started.has(path.resolve(file)))
+	const change = test_pinned_cache_logic.change_of(inputs.commit, assets, inputs.digests)
+
+	return test_pinned_cache_logic.red_basis(change, closures)
+}
+
+function create(inputs: ReachInputs): Reach {
+	const held: { view?: Promise<GraphView | undefined> } = {}
+
+	async function related(file: string): Promise<Array<string> | undefined> {
+		held.view ??= view_of()
+		const read = await held.view
+
+		return read === undefined ? undefined : related_of(read, file)
+	}
+
+	async function failed(tests: ReadonlyArray<string>): Promise<string | undefined> {
+		held.view ??= view_of()
+		const read = await held.view
+
+		return read === undefined ? undefined : failed_of(read, tests, inputs)
+	}
+
+	return { related, failed }
+}
+
+const test_pinned_reach = {
+	code_universe,
+	create,
+	probed_files,
+	reached_test_count,
+	reached_test_counts,
+	work_tree_files,
+}
+
+export type { Reach, ReachedCount, ReachInputs }
+export { test_pinned_reach }

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

@@ -0,0 +1,196 @@
+import { gate_log } from '#scripts/gate/gate-log'
+import type { KeptLog } from '#scripts/gate/verification-tail'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { test_pinned_cache_logic } from './test-pinned-cache-logic'
+import type { PinnedOrigin } from './test-pinned-ledger'
+import { test_pinned_logic, type PinnedReport, type ReportParts } from './test-pinned-logic'
+
+// The answer `josh test:pinned --record` leaves for `josh run:review --join` (joshuafolkken/kit#4770):
+// the printed report and its unpinned count, keyed to the checkout. `run:review` starts the check in
+// the background beside the gate and the brief, so the join — a later process — reads it here.
+//
+// **Each answer is filed under its launch's token**, so a read answers only for the token it asks
+// with: a check an earlier start left running can still write after the next start cleared the record,
+// and its answer — about a tree the join never asked about — lands in its own file rather than over
+// this launch's. The token comes from the command line, so the file name carries its digest.
+
+const RECORD_PREFIX = 'josh-test-pinned-record-'
+const TOKEN_KEY_LENGTH = 16
+const SITE_KEY_LENGTH = 16
+const NOT_RUN_NOTE = '`josh test:pinned` could not run, so nothing was checked: '
+const FIRST_UNPINNED_FLAG = '--first-unpinned'
+const LIST_PREFIX = 'josh-test-pinned-list-'
+const LIST_SUFFIX = '.log'
+const LIST_HEADER = 'josh test:pinned — every unpinned and unchecked place'
+
+type UnpinnedHunk = PinnedReport['unpinned'][number]
+
+// `unpinned` holds one key per unpinned place (`site_of`); an identical place in the same file takes its
+// occurrence number, so a copy added later is a place no record holds.
+// `text`, `counts` and `log` are the printed report's parts (`test_pinned_logic.report_text`).
+interface PinnedSummary extends ReportParts {
+	unpinned: ReadonlyArray<string>
+	// What a check still running reached so far; it is shown, never judged or remembered as the answer.
+	is_partial?: boolean
+	// A `--first-unpinned` check that stopped before some hunks (joshuafolkken/kit#5153): its unpinned
+	// places are not every one, so no reason accepts it as the whole answer.
+	is_cut?: boolean
+	// How many hunks a cut check did not probe, for the note on the probe that goes on with them
+	// (joshuafolkken/kit#5327).
+	remaining?: number
+}
+
+// A place's key leaves out its line, so merging the default branch in, which moves the line, keeps the
+// key (joshuafolkken/kit#4775): the file, the function, and a digest of the lines the change replaced
+// and the lines it put in their place.
+function site_of(hunk: UnpinnedHunk): string {
+	const body = JSON.stringify([hunk.new_count, hunk.old_lines, hunk.new_lines ?? []])
+	const key = stamp_file.digest(body).slice(0, SITE_KEY_LENGTH)
+	const place = hunk.function_name === undefined ? hunk.file : `${hunk.file} ${hunk.function_name}`
+
+	return `${place} ${key}`
+}
+
+// **The full list goes to a log once any place is folded** (joshuafolkken/kit#5188): the printed report
+// counts the unchecked places by reason, so the list is kept where a `tail` cannot cut it.
+function kept_log(report: PinnedReport, root: string): KeptLog | undefined {
+	if (!test_pinned_logic.has_unchecked(report)) return undefined
+	const output = test_pinned_logic.format(report)
+	const target = stamp_file.stamp_path(LIST_PREFIX, root, LIST_SUFFIX)
+
+	return { path: gate_log.write_gate_log([{ header: LIST_HEADER, output }], target) }
+}
+
+function summary_with(report: PinnedReport, log: KeptLog | undefined): PinnedSummary {
+	const summary = {
+		...test_pinned_logic.report_parts(report),
+		log,
+		unpinned: test_pinned_cache_logic.distinct(report.unpinned.map((hunk) => site_of(hunk))),
+	}
+
+	return report.cut === undefined
+		? summary
+		: { ...summary, is_cut: true, remaining: report.cut.length }
+}
+
+function summary_of(report: PinnedReport, root: string = PROJECT_ROOT): PinnedSummary {
+	return summary_with(report, kept_log(report, root))
+}
+
+// What a check still running has reached so far (joshuafolkken/kit#4936): `note` says the rest is to
+// come. It keeps no list: the per-checkout list log is the finished check's, which its record names.
+function partial_summary(report: PinnedReport, note: string): PinnedSummary {
+	const summary = summary_with(report, undefined)
+
+	return { ...summary, text: `${note}\n${summary.text}`, is_partial: true }
+}
+
+// A check that could not run checked nothing, so it names no unpinned place and the run fails open.
+function not_run_summary(error: unknown): PinnedSummary {
+	const message = error instanceof Error ? error.message : String(error)
+
+	return { text: `${NOT_RUN_NOTE}${message}\n`, unpinned: [] }
+}
+
+function record_path(token: string, root: string = PROJECT_ROOT): string {
+	const key = stamp_file.digest(token).slice(0, TOKEN_KEY_LENGTH)
+
+	return stamp_file.stamp_path(`${RECORD_PREFIX}${key}-`, root)
+}
+
+function write(token: string, summary: PinnedSummary, root: string = PROJECT_ROOT): void {
+	stamp_file.write_stamp(record_path(token, root), { token, ...summary })
+}
+
+function is_text_list(value: unknown): value is Array<string> {
+	return Array.isArray(value) && value.every((item) => typeof item === 'string')
+}
+
+// A kept log's path, absent from the record when its write failed.
+function log_of(value: unknown): KeptLog | undefined {
+	if (typeof value !== 'object' || value === null) return undefined
+	const kept = value as Record<string, unknown>
+
+	return { path: typeof kept['path'] === 'string' ? kept['path'] : undefined }
+}
+
+// The counts line and the log: absent from a check that could not run.
+function tail_of(record: Record<string, unknown>): Pick<PinnedSummary, 'counts' | 'log'> {
+	const { counts, log } = record
+
+	return typeof counts === 'string' ? { counts, log: log_of(log) } : {}
+}
+
+// The count of hunks a cut check did not probe: absent from a record written before it was kept.
+function remaining_of(record: Record<string, unknown>): Pick<PinnedSummary, 'remaining'> {
+	const { remaining } = record
+
+	return typeof remaining === 'number' ? { remaining } : {}
+}
+
+function to_summary(record: Record<string, unknown>): PinnedSummary | undefined {
+	const { text, unpinned, is_cut } = record
+
+	if (typeof text !== 'string' || !is_text_list(unpinned)) return undefined
+	const summary = { text, unpinned, ...tail_of(record) }
+
+	return is_cut === true ? { ...summary, is_cut, ...remaining_of(record) } : summary
+}
+
+function parsed(raw: string): Record<string, unknown> | undefined {
+	try {
+		const value: unknown = JSON.parse(raw)
+
+		return typeof value === 'object' && value !== null
+			? (value as Record<string, unknown>)
+			: undefined
+	} catch {
+		return undefined
+	}
+}
+
+function read(token: string, root: string = PROJECT_ROOT): PinnedSummary | undefined {
+	const raw = stamp_file.read_stamp_text(record_path(token, root))
+	const record = raw === undefined ? undefined : parsed(raw)
+
+	if (record?.['token'] !== token) return undefined
+
+	return to_summary(record)
+}
+
+function clear(token: string, root: string = PROJECT_ROOT): void {
+	stamp_file.remove_stamp(record_path(token, root))
+}
+
+// A recorded launch's `josh test:pinned` arguments, the token last. **With no `--unpinned-ok` reason it
+// stops at the first unpinned hunk** (joshuafolkken/kit#5153): the launcher stops on it whatever the
+// rest say. Under a reason every hunk is probed, since a reason accepts the list as the whole answer.
+// `origin` names the launcher on the run's ledger row (joshuafolkken/kit#5262). `is_whole` probes every
+// hunk with no reason: the background probe that goes on past a cut check's stop (joshuafolkken/kit#5327).
+function launch_argv(
+	token: string,
+	reason: string | undefined,
+	origin: PinnedOrigin,
+	is_whole = false,
+): Array<string> {
+	const cut = reason === undefined && !is_whole ? [FIRST_UNPINNED_FLAG] : []
+
+	return ['test:pinned', ...cut, '--origin', origin, '--record', token]
+}
+
+const test_pinned_record = {
+	clear,
+	launch_argv,
+	is_text_list,
+	not_run_summary,
+	parsed,
+	partial_summary,
+	read,
+	record_path,
+	summary_of,
+	write,
+}
+
+export type { PinnedSummary }
+export { test_pinned_record }

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

@@ -0,0 +1,148 @@
+import type { TypeScriptApi } from '#scripts/review/comment-ranges'
+import type { Identifier, Node } from 'typescript'
+import { test_pinned_functions } from './test-pinned-functions'
+import { test_pinned_logic, type Hunk } from './test-pinned-logic'
+
+// Which hunks `josh test:pinned` does not probe as a rewire (joshuafolkken/kit#5235): an import moved
+// to another module under a new name, or a call renamed to it. Put back alone, such a hunk reads a name
+// nothing in the file binds, so a test goes red exactly when it runs that line — the hunk has no
+// behavior of its own to pin. A hunk that changes anything besides the names is still probed.
+
+interface Names {
+	bound: Set<string>
+	used: Set<string>
+	imported: Set<string>
+}
+
+interface Token {
+	kind: number
+	text: string
+}
+
+function is_called(api: TypeScriptApi, parent: Node, node: Identifier): boolean {
+	if (!api.isCallExpression(parent) && !api.isNewExpression(parent)) return false
+
+	return parent.expression === node || parent.arguments?.includes(node) === true
+}
+
+// A read of the name's value: the object of a member access, a callee or an argument. Any other
+// position is left out, so a name read elsewhere never makes a hunk a rewire.
+function is_use(api: TypeScriptApi, node: Identifier): boolean {
+	const { parent } = node
+	if (api.isPropertyAccessExpression(parent)) return parent.expression === node
+
+	return is_called(api, parent, node)
+}
+
+function is_import(api: TypeScriptApi, parent: Node): boolean {
+	return (
+		api.isImportSpecifier(parent) || api.isImportClause(parent) || api.isNamespaceImport(parent)
+	)
+}
+
+// Any node's own name counts as bound — a property name too — so a binding is never missed.
+function add_name(api: TypeScriptApi, node: Identifier, names: Names): void {
+	const { parent } = node
+	if (is_use(api, node)) names.used.add(node.text)
+	if (!('name' in parent) || parent.name !== node) return
+	names.bound.add(node.text)
+	if (is_import(api, parent)) names.imported.add(node.text)
+}
+
+function names_in(api: TypeScriptApi, node: Node, names: Names): void {
+	if (api.isIdentifier(node)) add_name(api, node, names)
+	api.forEachChild(node, (child) => {
+		names_in(api, child, names)
+	})
+}
+
+function names_of(api: TypeScriptApi, file: string, content: string): Names {
+	const names = { bound: new Set<string>(), used: new Set<string>(), imported: new Set<string>() }
+
+	names_in(api, api.createSourceFile(file, content, api.ScriptTarget.ESNext, true), names)
+
+	return names
+}
+
+// The names read and bound nowhere in the file, globals left out.
+function unbound_of(names: Names): Array<string> {
+	return [...names.used].filter(
+		(name) => !names.bound.has(name) && !Object.hasOwn(globalThis, name),
+	)
+}
+
+function tokens_of(api: TypeScriptApi, text: string): Array<Token> {
+	const target = api.ScriptTarget.ESNext
+	const scanner = api.createScanner(target, true, api.LanguageVariant.Standard, text)
+	const end = api.SyntaxKind.EndOfFileToken
+	const tokens: Array<Token> = []
+
+	for (let kind = scanner.scan(); kind !== end; kind = scanner.scan()) {
+		tokens.push({ kind, text: scanner.getTokenText() })
+	}
+
+	return tokens
+}
+
+// A rename the revert undoes: from a name it leaves unbound to one the file imports now.
+interface Swap {
+	from: ReadonlySet<string>
+	to: ReadonlySet<string>
+}
+
+function is_same_token(token: Token, other: Token | undefined, swap: Swap): boolean {
+	if (other?.kind !== token.kind) return false
+
+	return token.text === other.text || (swap.from.has(token.text) && swap.to.has(other.text))
+}
+
+// Whether two token runs differ only where `swap` renames the old token to the new one.
+function is_renamed_only(
+	olds: ReadonlyArray<Token>,
+	news: ReadonlyArray<Token>,
+	swap: Swap,
+): boolean {
+	if (olds.length !== news.length) return false
+
+	return olds.every((token, index) => is_same_token(token, news[index], swap))
+}
+
+function is_import_only(api: TypeScriptApi, file: string, text: string): boolean {
+	const source = api.createSourceFile(file, text, api.ScriptTarget.ESNext, true)
+
+	return source.statements.every((statement) => api.isImportDeclaration(statement))
+}
+
+function new_text_of(content: string, hunk: Hunk): string {
+	const start = hunk.new_start - 1
+
+	return content
+		.split('\n')
+		.slice(start, start + hunk.new_count)
+		.join('\n')
+}
+
+// The hunk's lines are import declarations alone, or the same code with only the names swapped.
+function is_name_swap(api: TypeScriptApi, hunk: Hunk, new_text: string, swap: Swap): boolean {
+	const old_text = hunk.old_lines.join('\n')
+	const is_imports = is_import_only(api, hunk.file, old_text)
+	if (is_imports && is_import_only(api, hunk.file, new_text)) return true
+
+	return is_renamed_only(tokens_of(api, old_text), tokens_of(api, new_text), swap)
+}
+
+function is_rewire(api: TypeScriptApi, content: string, hunk: Hunk): boolean {
+	if (!test_pinned_functions.is_script(hunk.file)) return false
+	const after = names_of(api, hunk.file, content)
+	const before = names_of(api, hunk.file, test_pinned_logic.revert(content, hunk))
+	const unbound_now = new Set(unbound_of(after))
+	const unbound = unbound_of(before).filter((name) => !unbound_now.has(name))
+	if (unbound.length === 0) return false
+	const swap = { from: new Set(unbound), to: after.imported }
+
+	return is_name_swap(api, hunk, new_text_of(content, hunk), swap)
+}
+
+const test_pinned_rewire = { is_rewire }
+
+export { test_pinned_rewire }

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

@@ -0,0 +1,81 @@
+import path from 'node:path'
+import type { ImportGraph } from '#scripts/lint/import-graph'
+import { test_declared_logic } from './test-declared-logic'
+
+// The code a failed test can run past its import closure (joshuafolkken/kit#5261): a test starts a CLI
+// by naming its file in a string, so a file a string literal of the test or of a module it imports
+// names is one it may start, and so is a file the strings that one runs name in turn — the command a
+// spawned dispatcher starts by its path. Only these, with their closures, are what a `josh
+// test:pinned` red rests on besides the test's own closure; an edit to code nothing named reaches
+// leaves the red held. A comment starts nothing, so its file names are not read.
+//
+// A name is a file's whole base name in one string or template span, so a file named by another with
+// the same base name counts too, erring toward re-probing. A name built across template spans or
+// written without its extension is not read, so a fix to that CLI leaves its red held.
+
+const TOKEN = /[\w.-]+/gu
+
+interface TestSpawn {
+	started: (tests: ReadonlyArray<string>) => ReadonlySet<string>
+}
+
+// Each non-test code file of `universe` under its base name.
+function index_of(universe: ReadonlyArray<string>): Map<string, Array<string>> {
+	const index = new Map<string, Array<string>>()
+
+	for (const file of universe) {
+		if (test_declared_logic.is_test_file(path.relative(process.cwd(), file))) continue
+		const name = path.basename(file)
+
+		index.set(name, [...(index.get(name) ?? []), file])
+	}
+
+	return index
+}
+
+function names_in(text: string, index: ReadonlyMap<string, ReadonlyArray<string>>): Array<string> {
+	return (text.match(TOKEN) ?? []).flatMap((token) => index.get(token) ?? [])
+}
+
+// `read` answered once per file for the graph's lifetime, however many reds ask it.
+function memoized(read: (file: string) => Array<string>): (file: string) => Array<string> {
+	const known = new Map<string, Array<string>>()
+
+	return function answer(file: string): Array<string> {
+		const found = known.get(file) ?? read(file)
+
+		known.set(file, found)
+
+		return found
+	}
+}
+
+function create(graph: ImportGraph, universe: ReadonlyArray<string>): TestSpawn {
+	const index = index_of(universe)
+	const names_of = memoized((file) => names_in(graph.strings(file).join(' '), index))
+	// What `file` runs names: its own strings and those of every module its imports reach.
+	const named_from = memoized((file) => [
+		...new Set([file, ...graph.closure(file)].flatMap((read) => names_of(read))),
+	])
+
+	function started(tests: ReadonlyArray<string>): ReadonlySet<string> {
+		const found = new Set<string>()
+		const pending = [...tests]
+
+		for (let current = pending.pop(); current !== undefined; current = pending.pop()) {
+			const next = named_from(current).filter((file) => !found.has(file))
+
+			for (const file of next) found.add(file)
+			pending.push(...next)
+		}
+
+		return found
+	}
+
+	return { started }
+}
+
+const test_pinned_spawn = { create }
+
+export type { TestSpawn }
+export { test_pinned_spawn }

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

@@ -0,0 +1,70 @@
+import type { RedProbe } from './test-red-logic'
+
+// The stages of one `josh test:pinned` probe (joshuafolkken/kit#5292): a hunk whose file reaches far
+// more test files than import it directly runs those importers first, since a revert's red almost
+// always lands there, and the whole reach only when they do not go red. A narrow file runs its reach
+// once, as before.
+
+// A reach of this many test files is wide whatever the direct importers number.
+const WIDE_REACH = 100
+// A reach this many times the direct importers is wide.
+const WIDE_RATIO = 3
+
+// What a fresh probe runs: `direct` first where the reach is wide, then `reach` unless `direct` went red.
+interface StagePlan {
+	direct?: ReadonlyArray<string> | undefined
+	reach: ReadonlyArray<string>
+}
+
+// How many probes the direct importers decided, and how many escalated to the whole reach.
+interface Staged {
+	direct: number
+	escalated: number
+}
+
+type StageRun = (files: ReadonlyArray<string>) => Promise<RedProbe>
+
+function none(): Staged {
+	return { direct: 0, escalated: 0 }
+}
+
+// No direct importer, or as many as the reach, leaves no smaller first stage to run.
+function is_wide(reach: number, direct: number): boolean {
+	if (direct === 0 || direct >= reach) return false
+
+	return reach >= WIDE_REACH || reach >= WIDE_RATIO * direct
+}
+
+// The plan for `file`, read off its `direct` importers and how many test files its imports `reach`.
+function plan_over(file: string, direct: ReadonlyArray<string>, reach: number): StagePlan {
+	return is_wide(reach, direct.length) ? { direct, reach: [file] } : { reach: [file] }
+}
+
+// The verdict over `plan`, each stage run through `run` and tallied into `staged`: a red from the
+// direct importers decides, anything else is answered by the whole reach.
+async function staged_verdict(plan: StagePlan, run: StageRun, staged: Staged): Promise<RedProbe> {
+	if (plan.direct === undefined) return await run(plan.reach)
+	const first = await run(plan.direct)
+
+	if (first.verdict === 'red') {
+		staged.direct += 1
+
+		return first
+	}
+
+	staged.escalated += 1
+
+	return await run(plan.reach)
+}
+
+// The counts line's tail, empty when no probe ran in stages.
+function counts_suffix(staged: Staged | undefined): string {
+	if (staged === undefined || staged.direct + staged.escalated === 0) return ''
+
+	return ` · direct ${String(staged.direct)} · escalated ${String(staged.escalated)}`
+}
+
+const test_pinned_stage = { WIDE_RATIO, WIDE_REACH, counts_suffix, none, plan_over, staged_verdict }
+
+export type { Staged, StagePlan }
+export { test_pinned_stage }