@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/test/test-related-touched.ts

@@ -0,0 +1,84 @@
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+import { related_scope, type RelatedScope } from './test-related-scope'
+
+// `josh test:related --touched` — the implementation loop's re-check (joshuafolkken/kit#5237). A change
+// near a hub reaches hundreds of test files, and paying that reach after every small edit repeats it
+// minutes apart. **The touched scope reads no test-read map and no import graph**: it is the diff's own
+// test files and, for each changed module `foo.ts`, its colocated `foo.test.ts` and `foo.*.test.ts`.
+// What an edit breaks further away is the full-reach run's to find, so a touched run leaves no green
+// record (`scoped-green.ts`) and is recorded in the lane ledger under its own kind.
+
+const TOUCHED_FLAG = '--touched'
+const TOUCHED_KIND = 'touched'
+const TEST_SUFFIX = '.test.ts'
+const TOUCHED_REASON = 'the diff test files and the tests named after its modules'
+const NOTHING_TOUCHED_REASON = 'no test file is in the diff or named after a changed module'
+
+type ListDirectory = (directory: string) => ReadonlyArray<string>
+
+// A directory that cannot be listed holds no test to run.
+function list_directory(directory: string): ReadonlyArray<string> {
+	try {
+		return readdirSync(directory)
+	} catch {
+		return []
+	}
+}
+
+function is_named_after(module_file: string, name: string): boolean {
+	const stem = path.basename(module_file, path.extname(module_file))
+
+	return name.startsWith(`${stem}.`) && name.endsWith(TEST_SUFFIX)
+}
+
+// A test file of the diff runs itself while it is still on disk; a module runs its same-named tests.
+function tests_of(root: string, file: string, list: ListDirectory): Array<string> {
+	const directory = path.dirname(file)
+	const names = list(path.join(root, directory))
+
+	if (file.endsWith(TEST_SUFFIX)) return names.includes(path.basename(file)) ? [file] : []
+	if (!related_scope.is_relatable(file)) return []
+
+	return names
+		.filter((name) => is_named_after(file, name))
+		.map((name) => path.join(directory, name))
+}
+
+function touched_tests(
+	root: string,
+	changed: ReadonlyArray<string>,
+	list: ListDirectory = list_directory,
+): Array<string> {
+	return [...new Set(changed.flatMap((file) => tests_of(root, file, list)))]
+}
+
+// `changed` is repository-root-relative; `undefined` — a diff git could not read — runs the whole suite,
+// as an unreadable change does for the full-reach run.
+function touched_scope(
+	root: string,
+	changed: ReadonlyArray<string> | undefined,
+	list: ListDirectory = list_directory,
+): RelatedScope {
+	const { UNREADABLE_REASON } = related_scope
+
+	if (changed === undefined) return { mode: 'all', files: [], reason: UNREADABLE_REASON }
+
+	const files = touched_tests(root, changed, list).map((file) => path.join(root, file))
+
+	if (files.length === 0) return { mode: 'none', files: [], reason: NOTHING_TOUCHED_REASON }
+
+	return { mode: 'related', files, reason: TOUCHED_REASON }
+}
+
+const test_related_touched = {
+	NOTHING_TOUCHED_REASON,
+	TOUCHED_FLAG,
+	TOUCHED_KIND,
+	TOUCHED_REASON,
+	touched_scope,
+	touched_tests,
+}
+
+export type { ListDirectory }
+export { test_related_touched }

package/scripts/test/test-related.ts

@@ -1,11 +1,25 @@
-#!/usr/bin/env tsx
 import { existsSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { gate_labels } from '#scripts/gate/gate-labels'
 import type { GateTree } from '#scripts/gate/gate-tree'
+import { input_fingerprint } from '#scripts/gate/input-fingerprint'
+import { moved_paths } from '#scripts/gate/moved-paths'
 import { scoped_green } from '#scripts/gate/scoped-green'
+import { since_green } from '#scripts/gate/since-green'
 import { changed_file_scope } from '#scripts/git/changed-file-scope'
+import { changed_paths } from '#scripts/git/changed-paths'
 import { review_stamps } from '#scripts/review/review-stamps'
-import { related_scope } from './test-related-scope'
+import { direct_importers } from './direct-importers'
+import { pure_files_entries } from './pure-files-entries'
+import { related_heavy_tests } from './related-heavy-tests'
+import { test_no_base } from './test-no-base'
+import { test_read_map, type ReadMap } from './test-read-map'
+import { test_related_claim } from './test-related-claim'
+import { test_related_moved, type ChangeReading } from './test-related-moved'
+import { test_related_record, type RunInput } from './test-related-record'
+import { related_scope, type RelatedScope } from './test-related-scope'
+import { test_related_synced } from './test-related-synced'
+import { test_related_touched } from './test-related-touched'
 import { test_unit_guard } from './test-unit-guard'
 
 // `josh test:related` — the unit check an implementation loop runs between edits.
@@ -30,26 +44,378 @@ function conclusive_tree(before: GateTree | undefined): GateTree | undefined {
 	return test_unit_guard.is_running(process.cwd()) ? before : undefined
 }
 
-async function run_related_tests(command_arguments: ReadonlyArray<string>): Promise<number> {
-	const root = await changed_file_scope.repository_root_or_cwd()
-	const scope = await changed_file_scope.resolve_command_scope({
-		command_arguments,
+// A failure answers `undefined` rather than an empty list: the two are opposite inputs to
+// `resolve_scope`, and only one of them means "could not tell".
+async function read_or_undefined(
+	read: () => Promise<ReadonlyArray<string>>,
+): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		return await read()
+	} catch {
+		return undefined
+	}
+}
+
+async function branch_change(): Promise<ReadonlyArray<string> | undefined> {
+	return await read_or_undefined(async () => await changed_paths.read_changed_paths(false))
+}
+
+// **The change a map answers for is the change since the tree it was recorded on** — its commit and
+// the content its dirty files held then (`test_read_map.changed_since_tree`). A commit git can no
+// longer resolve — a pruned or foreign map — leaves the branch change with no map, which runs the
+// whole suite on any non-code file.
+async function change_since(
+	root: string,
+	map: ReadMap,
+): Promise<ReadonlyArray<string> | undefined> {
+	const since = await read_or_undefined(
+		async () => await changed_paths.read_changed_since(map.commit),
+	)
+
+	if (since === undefined) return undefined
+
+	return test_read_map.changed_since_tree(
+		map,
+		since,
+		input_fingerprint.of_files(root, Object.keys(map.dirty)),
+	)
+}
+
+// **The map's tree is whichever lane last ran the whole suite green**, so the change since it holds that
+// lane's own branch change too (joshuafolkken/kit#4527). What this branch did not change is marked
+// `since_map`: it reaches vitest only as a code file naming what moved, and only this branch's change
+// can send the run to the whole suite (joshuafolkken/kit#4896). A branch change git cannot read marks nothing.
+async function map_change(root: string, map: ReadMap): Promise<ChangeReading> {
+	const changed = await change_since(root, map)
+
+	if (changed === undefined) return { changed: await branch_change(), map: undefined }
+
+	const branch = await branch_change()
+
+	if (branch === undefined) return { changed, map }
+
+	return { changed, map, since_map: changed.filter((file) => !branch.includes(file)) }
+}
+
+// Explicit file arguments win over the git reading, which is what makes the narrowing testable by
+// hand and usable from a hook that already knows which file it just wrote. **The map still answers
+// only for the change since its tree**, so that change joins the arguments: a test added since the
+// map was recorded is in no entry, and only its own appearance in the change runs it — when it names
+// a file the arguments moved (`naming_moved`), as a source file there does.
+async function explicit_change(
+	root: string,
+	explicit: ReadonlyArray<string>,
+	map: ReadMap | undefined,
+): Promise<ChangeReading> {
+	const since = map === undefined ? undefined : await change_since(root, map)
+
+	if (since === undefined) return { changed: explicit, map: undefined }
+
+	const named = new Set(explicit)
+	const since_map = since.filter((file) => !named.has(file))
+
+	return { changed: [...named, ...since_map], map, since_map }
+}
+
+// **The whole-suite leg never narrows by a green a bare run recorded past a file every test imports**:
+// that green vouches only for the file's direct importers (joshuafolkken/kit#5122), so while this
+// branch changes one, the gate's unit leg reads the whole branch change.
+async function is_green_narrowable(is_whole: boolean): Promise<boolean> {
+	if (!is_whole) return true
+
+	return direct_importers.every_test_imports_of((await branch_change()) ?? []).length === 0
+}
+
+// **What moved since this command's last green run** (`since-green.ts`), read as explicit arguments
+// are. A moved file — code or not — reaches the tests reading it as data through the map, whose
+// entries hold no module that started reading it after the map's tree; the change since that tree
+// joins the list — a code file of it only when it names a moved file (`naming_moved`) — so such a
+// module runs the tests importing it. Nothing moved runs nothing; no map,
+// or one git can no longer diff against, answers `undefined`, which reads the whole branch change.
+async function since_green_change(
+	root: string,
+	map: ReadMap | undefined,
+	is_whole: boolean,
+): Promise<ChangeReading | undefined> {
+	const parts = (await is_green_narrowable(is_whole))
+		? await since_green.read_moved_parts(review_stamps.test_related_stamp, gate_labels.UNIT_LABEL)
+		: undefined
+
+	if (parts === undefined) return undefined
+
+	const moved = moved_paths.union_of(parts)
+
+	if (moved.length === 0) return { changed: [], map, is_unmoved: true }
+
+	const branch = await branch_change()
+	const split = await test_related_synced.split(root, parts.synced, branch, map)
+	const change = await explicit_change(
+		root,
+		test_related_moved.narrowed_moved(moved, split, branch, map),
+		map,
+	)
+
+	if (change.map === undefined) return undefined
+
+	process.stdout.write(`${since_green.describe(related_scope.COMMAND_LABEL, moved)}\n`)
+
+	return test_related_moved.moved_reading(change, parts, branch, split)
+}
+
+async function whole_change(
+	root: string,
+	map: ReadMap | undefined,
+	is_whole: boolean,
+): Promise<ChangeReading> {
+	const since = await since_green_change(root, map, is_whole)
+
+	if (since !== undefined) return since
+
+	return map === undefined ? { changed: await branch_change(), map } : await map_change(root, map)
+}
+
+function explicit_files(root: string, command_arguments: ReadonlyArray<string>): Array<string> {
+	return command_arguments
+		.filter((argument) => !changed_file_scope.is_flag(argument))
+		.map((file) => path.relative(root, path.resolve(file)))
+}
+
+async function read_change(
+	root: string,
+	command_arguments: ReadonlyArray<string>,
+	is_whole: boolean,
+): Promise<ChangeReading> {
+	const map = test_read_map.read_map(root)
+	const explicit = explicit_files(root, command_arguments)
+
+	return explicit.length > 0
+		? await explicit_change(root, explicit, map)
+		: await whole_change(root, map, is_whole)
+}
+
+// **The changed non-code files the map's tree held and that did not already differ from it** — the
+// ones whose having no reader in the map means no test reads them. A file that was dirty when the
+// map was recorded is left out, since the tree the tests read then was not the commit's. A git
+// failure holds none, which runs the whole suite on any of them.
+async function recorded_files(change: ChangeReading): Promise<ReadonlySet<string>> {
+	const { changed, map } = change
+
+	if (changed === undefined || map === undefined) return new Set()
+
+	const dirty = new Set(Object.keys(map.dirty))
+	const candidates = changed.filter((file) => !related_scope.is_relatable(file) && !dirty.has(file))
+
+	return new Set(
+		await read_or_undefined(async () => await changed_paths.read_held_at(map.commit, candidates)),
+	)
+}
+
+// **The code files of the change since the map that name a file this change moved** — read off their
+// text, the one place a file-system read added since the map's tree shows (`is_code_input` in
+// `test-related-scope.ts`, joshuafolkken/kit#4532). A file the tree no longer holds names nothing. A
+// file every test depends on is never one: handed to vitest it runs the whole suite unannounced, and
+// only this branch's own change of it may do that (joshuafolkken/kit#4993). **Only this branch's own
+// change names**, where it was read: a main sync's file — a shared test, or one main deleted — would
+// match main's own sources, which vitest widens to hundreds of tests (joshuafolkken/kit#5041).
+function naming_moved(root: string, change: ChangeReading): ReadonlySet<string> {
+	const { changed = [], since_map = [], branch = changed } = change
+	const names = changed
+		.filter((file) => !since_map.includes(file) && branch.includes(file))
+		.map((file) => path.basename(file))
+	const code = since_map.filter(
+		(file) => related_scope.is_relatable(file) && !test_related_moved.is_whole_suite(file),
+	)
+
+	// Each file's text is read once, however many names it is checked for.
+	return new Set(
+		code.filter((file) =>
+			test_no_base.names_any(test_no_base.text_of(path.join(root, file)), names),
+		),
+	)
+}
+
+// A file every test imports narrows to its direct importers unless `is_whole`: the gate's unit leg, and
+// the gate's reuse of it, keep the whole suite for it (`gate_labels.KEEP_WHOLE_SUITE_FLAG`).
+async function scope_of(
+	root: string,
+	change: ChangeReading,
+	is_whole: boolean,
+): Promise<RelatedScope> {
+	const recorded = await recorded_files(change)
+	const naming = naming_moved(root, change)
+	const pure_entries = await pure_files_entries.read_moved(root, change.changed)
+	const narrowed = is_whole ? [] : (change.changed ?? [])
+	const importers = await direct_importers.every_test_importers(root, narrowed)
+
+	return related_scope.resolve_scope({
 		root,
-		inputs: related_scope.scope_inputs(existsSync),
+		...change,
+		recorded,
+		naming_moved: naming,
+		pure_entries,
+		every_test_importers: importers,
+		is_present: existsSync,
+	})
+}
+
+// **Whether a set of changed files can reach any test**, answered by the decision this command
+// narrows with, so the gate's reuse of a green unit step (`check-inputs.ts`) can never trust a change
+// this command would have run tests for. Unknown reaches: no map, or one recorded on a tree git can
+// no longer diff against. The change since the map joins the paths as it does for explicit
+// arguments, so a test added or edited after the map was recorded still reaches when it names a path.
+async function reaches_tests(root: string, paths: ReadonlyArray<string>): Promise<boolean> {
+	if (paths.length === 0) return false
+
+	const change = await explicit_change(root, paths, test_read_map.read_map(root))
+
+	if (change.map === undefined) return true
+
+	const scope = await scope_of(root, change, true)
+
+	return scope.mode !== 'none'
+}
+
+// A change known to reach no test succeeds without starting vitest, and says why.
+async function run_scope(
+	scope: RelatedScope,
+	root: string,
+	command_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	const description = related_scope.describe_scope(scope, root)
+
+	if (scope.mode === 'none') {
+		process.stdout.write(`${description}\n`)
+
+		return 0
+	}
+
+	const vitest_arguments = related_scope.vitest_arguments(scope, [
+		...changed_file_scope.flags_of(command_arguments),
+		...related_heavy_tests.exclude_flags(scope, root),
+	])
+
+	return await test_related_claim.with_unit_claim(
+		scope.mode === 'related' ? scope.files : undefined,
+		async () =>
+			await test_unit_guard.run_guarded_vitest(
+				process.cwd(),
+				vitest_arguments,
+				related_scope.COMMAND_NAME,
+				description,
+			),
+	)
+}
+
+async function resolve_change(
+	root: string,
+	change: ChangeReading,
+	is_whole: boolean,
+): Promise<RelatedScope> {
+	const { UNMOVED_REASON } = related_scope
+
+	if (change.is_unmoved === true) return { mode: 'none', files: [], reason: UNMOVED_REASON }
+
+	return await scope_of(root, change, is_whole)
+}
+
+async function read_run_input(
+	root: string,
+	command_arguments: ReadonlyArray<string>,
+	is_whole: boolean,
+): Promise<RunInput> {
+	const change = await read_change(root, command_arguments, is_whole)
+	const scope = await resolve_change(root, change, is_whole)
+
+	const { changed, synced = [], since_map = [], branch } = change
+
+	return { scope, root, changed, synced, since_map, branch }
+}
+
+// Every run is timed and counted into the lane ledger (joshuafolkken/kit#4465).
+async function run_and_record(
+	input: RunInput,
+	command_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	const started = performance.now()
+	const { exit_code, test_files } = await test_related_record.with_test_count(
+		async () => await run_scope(input.scope, input.root, command_arguments),
+	)
+
+	await test_related_record.record_run(input, {
+		elapsed_ms: performance.now() - started,
+		test_files,
 	})
 
+	return exit_code
+}
+
+// **The no-base pass is part of the run's verdict**, so a green record — the one `josh ship` and the
+// gate reuse — never vouches for a tree whose base-touching code fails in CI's checkout. It runs
+// only after a green first pass (`test-no-base.ts`), and only over this branch's own files: those
+// the map's tree or a main sync joined were verified by main's CI.
+async function with_no_base_pass(
+	input: RunInput,
+	command_arguments: ReadonlyArray<string>,
+	exit_code: number,
+): Promise<number> {
+	if (exit_code !== 0) return exit_code
+
+	const flags = changed_file_scope.flags_of(command_arguments)
+	const joined = new Set([...input.since_map, ...input.synced])
+	const own = (input.changed ?? []).filter((file) => !joined.has(file))
+
+	return await test_no_base.run_if_touched(input.root, own, flags)
+}
+
+// A non-code argument is resolved through the map, and a file every test imports through its
+// importers, rather than handed to vitest, so only the other code arguments can be ones vitest was not
+// given.
+function report_unhanded(
+	root: string,
+	command_arguments: ReadonlyArray<string>,
+	scope: RelatedScope,
+): void {
 	changed_file_scope.report_unusable_arguments(
-		command_arguments,
+		command_arguments.filter(
+			(argument) =>
+				related_scope.is_relatable(argument) &&
+				!direct_importers.is_every_test_import(root, argument),
+		),
 		scope,
 		related_scope.COMMAND_LABEL,
 	)
+}
+
+// **A `--touched` run is the implementation loop's** (`test-related-touched.ts`): it reads its scope off
+// the change alone and leaves no green record, so `josh review:brief` and the gate's reuse count only
+// a full-reach run.
+async function run_touched(given: ReadonlyArray<string>): Promise<number> {
+	const { TOUCHED_FLAG, TOUCHED_KIND } = test_related_touched
+	const command_arguments = given.filter((argument) => argument !== TOUCHED_FLAG)
+	const root = await changed_file_scope.repository_root_or_cwd()
+	const explicit = explicit_files(root, command_arguments)
+	const changed = explicit.length > 0 ? explicit : await branch_change()
+	const scope = test_related_touched.touched_scope(root, changed)
+	const input = { scope, root, changed, synced: [], since_map: [], kind: TOUCHED_KIND }
+
+	return await run_and_record(input, command_arguments)
+}
+
+async function run_related_tests(given: ReadonlyArray<string>): Promise<number> {
+	if (given.includes(test_related_touched.TOUCHED_FLAG)) return await run_touched(given)
+
+	const { KEEP_WHOLE_SUITE_FLAG } = gate_labels
+	const command_arguments = given.filter((argument) => argument !== KEEP_WHOLE_SUITE_FLAG)
+	const root = await changed_file_scope.repository_root_or_cwd()
+	const input = await read_run_input(root, command_arguments, given.includes(KEEP_WHOLE_SUITE_FLAG))
+
+	report_unhanded(root, command_arguments, input.scope)
 
 	const before = await scoped_green.read_before(command_arguments)
-	const exit_code = await test_unit_guard.run_guarded_vitest(
-		process.cwd(),
-		related_scope.vitest_arguments(scope, changed_file_scope.flags_of(command_arguments)),
-		related_scope.COMMAND_NAME,
-		related_scope.describe_scope(scope, root),
+	const exit_code = await with_no_base_pass(
+		input,
+		command_arguments,
+		await run_and_record(input, command_arguments),
 	)
 
 	await scoped_green.record_if_green(review_stamps.test_related_stamp, {
@@ -60,10 +426,6 @@ async function run_related_tests(command_arguments: ReadonlyArray<string>): Prom
 	return exit_code
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run_related_tests(process.argv.slice(changed_file_scope.ARGV_START))
-}
-
-const test_related = { run_related_tests }
+const test_related = { reaches_tests, run_related_tests }
 
 export { test_related }

package/scripts/test/test-unit-guard-main.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { test_unit_guard } from './test-unit-guard'
+
+// The `josh test:unit` entry, kept apart from `test-unit-guard.ts` because the gate and the pre-push
+// hook import that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await test_unit_guard.run_guarded_unit(
+		process.cwd(),
+		process.argv.slice(ARGV_OFFSET),
+	)
+}

package/scripts/test/test-unit-guard.ts

@@ -1,19 +1,20 @@
-#!/usr/bin/env tsx
 import { existsSync, globSync } from 'node:fs'
 import { availableParallelism } from 'node:os'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { PROJECT_ENVIRONMENT_KEYS } from '#ports'
+import { core_budget } from '#scripts/gate/core-budget'
 import { free_cores } from '#scripts/gate/free-cores'
 import { project_checks } from '#scripts/gate/project-checks'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
 import { execa } from 'execa'
 import { project_test_script, type ProjectScriptState } from './project-test-script'
 import { SKIP_MARKER } from './skip-marker'
+import { test_read_recording, type RecordingEnvironment } from './test-read-recording'
 import { unit_worker_share } from './unit-worker-share'
+import { vitest_failure_summary } from './vitest-failure-summary'
 
 const PNPM = 'pnpm'
 const FAIL_EXIT_CODE = 1
-const ARGV_START = 2
 const VITEST_PACKAGE = path.join('node_modules', 'vitest')
 const UNIT_GLOB = '**/*.{test,spec}.{ts,js}'
 const NODE_MODULES = 'node_modules'
@@ -178,35 +179,80 @@ function isolated_unit_environment(
 // both count "alone" and both run uncapped. Inside the marker the number is identical — this run's own
 // record is now on disk and `is_nested_run` therefore contributes nothing — and the window is gone.
 //
+// **The share is bounded by the claim the run was admitted on** (`unit_worker_share.cap_to_claim`), so
+// a share read after admission never opens more workers than the ledger holds for it
+// (joshuafolkken/kit#4235).
+//
 // **The machine is read only when no count was typed.** The reading waits out a sample window, and a
-// caller's `--maxWorkers` — the gate's cap among them, already bounded by the same reading — wins
-// whatever it says.
+// caller's `--maxWorkers` wins whatever it says. The gate's cap is one: its admission narrows it to the
+// free cores, and its unit step bounds it by the free memory once admitted (`gate-run-steps.ts`).
 async function vitest_share(vitest_arguments: ReadonlyArray<string>): Promise<number | undefined> {
 	if (unit_worker_share.has_worker_flag(vitest_arguments)) return undefined
 
 	const available_cores = availableParallelism()
+	// The cores and the memory free right now (joshuafolkken/kit#4528), from one reading.
 	const free = await free_cores.read({ available_cores })
+	const share = unit_worker_share.current_share(
+		available_cores,
+		unit_worker_share.live_run_count(),
+		free,
+	)
+
+	return unit_worker_share.cap_to_claim(share, core_budget.held_unit_claim())
+}
+
+async function execute_vitest(
+	vitest_arguments: ReadonlyArray<string>,
+	recording: RecordingEnvironment,
+	directory: string,
+): Promise<number> {
+	// Shown as it runs and kept as well, so a failed run can end with its summary (joshuafolkken/kit#4869).
+	const result = await execa(PNPM, ['exec', 'vitest', ...vitest_arguments], {
+		cwd: directory,
+		env: { ...isolated_unit_environment(), ...recording },
+		extendEnv: false,
+		stdin: 'inherit',
+		stdout: ['inherit', 'pipe'],
+		stderr: ['inherit', 'pipe'],
+		all: true,
+		reject: false,
+	})
+	const exit_code = result.exitCode ?? FAIL_EXIT_CODE
+
+	vitest_failure_summary.report(vitest_arguments, result.all, exit_code)
 
-	return unit_worker_share.current_share(available_cores, unit_worker_share.live_run_count(), free)
+	return exit_code
 }
 
-async function run_vitest(vitest_arguments: ReadonlyArray<string>): Promise<number> {
+// A whole-suite run also records the test-read map `josh test:related` narrows by. `directory` is
+// where vitest runs — another checkout's for `test-no-base.ts`, this process's otherwise.
+async function run_vitest(
+	vitest_arguments: ReadonlyArray<string>,
+	directory: string = process.cwd(),
+): Promise<number> {
 	return await unit_worker_share.with_run_marker(async () => {
-		const sized = unit_worker_share.worker_arguments(
-			vitest_arguments,
-			await vitest_share(vitest_arguments),
+		const sized = [
+			...vitest_arguments,
+			...unit_worker_share.worker_arguments(vitest_arguments, await vitest_share(vitest_arguments)),
+		]
+		const root = await changed_file_scope.repository_root_or_cwd()
+
+		return await test_read_recording.with_read_recording(
+			root,
+			sized,
+			async (recording) => await execute_vitest(sized, recording, directory),
 		)
-		const result = await execa(PNPM, ['exec', 'vitest', ...vitest_arguments, ...sized], {
-			env: isolated_unit_environment(),
-			extendEnv: false,
-			stdio: 'inherit',
-			reject: false,
-		})
-
-		return result.exitCode ?? FAIL_EXIT_CODE
 	})
 }
 
+// The same funnel, run in another checkout of this project — whose `node_modules` is this one's.
+async function run_vitest_in(
+	directory: string,
+	vitest_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	return await run_vitest(vitest_arguments, directory)
+}
+
 // The label names the command the notice is printed for, so a skipped scoped run says
 // `josh test:related` rather than reporting itself as the full suite. `SKIP_MARKER` is unchanged
 // either way: the gate reads that word, never the label.
@@ -262,13 +308,6 @@ async function run_guarded_unit(
 	return await run_guarded_vitest(project_directory, ['run', ...extra_arguments])
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	const extra_arguments = process.argv.slice(ARGV_START)
-	const exit_code = await run_guarded_unit(process.cwd(), extra_arguments)
-
-	process.exit(exit_code)
-}
-
 const test_unit_guard = {
 	SKIP_MARKER,
 	guard_action,
@@ -280,6 +319,8 @@ const test_unit_guard = {
 	isolated_unit_environment,
 	run_guarded_unit,
 	run_guarded_vitest,
+	run_vitest_in,
+	vitest_share,
 }
 
 export type { GuardAction }