@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/test/test-related.ts

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
-import { gate_plan } from '#scripts/gate/gate-plan'
+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'
@@ -9,9 +9,17 @@ 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 { 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, type ScopeRequest } from './test-related-scope'
+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.
@@ -36,15 +44,6 @@ function conclusive_tree(before: GateTree | undefined): GateTree | undefined {
 	return test_unit_guard.is_running(process.cwd()) ? before : undefined
 }
 
-// The change a narrowing reads, and the map it reads it against. `is_unmoved` is the since-green
-// reading's positive fact that nothing moved since this command was last green on this checkout.
-// `synced` is the part of the change a main sync brought in, kept for the run's ledger record, and
-// `since_map` the part the change since the map's tree joined to what this change moved.
-type ChangeReading = Pick<ScopeRequest, 'changed' | 'map' | 'since_map'> & {
-	is_unmoved?: true
-	synced?: ReadonlyArray<string>
-}
-
 // 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(
@@ -84,8 +83,8 @@ async function change_since(
 
 // **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 still reaches its readers — a source file only when it names what moved — but only
-// this branch's change can send the run to the whole suite. A branch change git cannot read marks nothing.
+// `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)
 
@@ -101,8 +100,8 @@ async function map_change(root: string, map: ReadMap): Promise<ChangeReading> {
 // 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 — a source file
-// there only when it names a file the arguments moved (`naming_moved`).
+// 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>,
@@ -118,34 +117,29 @@ async function explicit_change(
 	return { changed: [...named, ...since_map], map, since_map }
 }
 
-// **A non-code file a main sync brought in is not this branch's change** (joshuafolkken/kit#4572), so it
-// joins `since_map`: it still reaches the tests reading it, but never sends the run to the whole suite —
-// main's CI verified it. A synced module stays a moved file, so `vitest related` still walks to the
-// tests importing it, a branch-only one among them. A branch change git cannot read marks nothing.
-async function synced_data(synced: ReadonlyArray<string>): Promise<ReadonlyArray<string>> {
-	const data = synced.filter((file) => !related_scope.is_relatable(file))
-
-	if (data.length === 0) return []
-
-	const branch = (await branch_change()) ?? data
+// **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 data.filter((file) => !branch.includes(file))
+	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 — its test files, and a source file only when it names a moved file
-// (`naming_moved`) — so such a module runs the tests importing it. Nothing moved runs nothing; no map,
+// 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 since_green.read_moved_parts(
-		review_stamps.test_related_stamp,
-		gate_plan.UNIT_LABEL,
-	)
+	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
 
@@ -153,37 +147,50 @@ async function since_green_change(
 
 	if (moved.length === 0) return { changed: [], map, is_unmoved: true }
 
-	const change = await explicit_change(root, moved, map)
+	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`)
 
-	const since_map = [...(change.since_map ?? []), ...(await synced_data(parts.synced))]
-
-	return { ...change, since_map, synced: parts.synced }
+	return test_related_moved.moved_reading(change, parts, branch, split)
 }
 
-async function whole_change(root: string, map: ReadMap | undefined): Promise<ChangeReading> {
-	const since = await since_green_change(root, map)
+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 = command_arguments
-		.filter((argument) => !changed_file_scope.is_flag(argument))
-		.map((file) => path.relative(root, path.resolve(file)))
+	const explicit = explicit_files(root, command_arguments)
 
 	return explicit.length > 0
 		? await explicit_change(root, explicit, map)
-		: await whole_change(root, 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
@@ -203,41 +210,50 @@ async function recorded_files(change: ChangeReading): Promise<ReadonlySet<string
 	)
 }
 
-function text_of(file_path: string): string {
-	try {
-		return readFileSync(file_path, 'utf8')
-	} catch {
-		return ''
-	}
-}
-
-// Each file's text is read once, however many names it is checked for.
-function names_any(text: string, names: ReadonlyArray<string>): boolean {
-	return names.some((name) => text.includes(name))
-}
-
 // **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.
+// `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 = [] } = change
+	const { changed = [], since_map = [], branch = changed } = change
 	const names = changed
-		.filter((file) => !since_map.includes(file))
+		.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))
+	const code = since_map.filter(
+		(file) => related_scope.is_relatable(file) && !test_related_moved.is_whole_suite(file),
+	)
 
-	return new Set(code.filter((file) => names_any(text_of(path.join(root, file)), names)))
+	// 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),
+		),
+	)
 }
 
-async function scope_of(root: string, change: ChangeReading): Promise<RelatedScope> {
+// 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,
 		...change,
 		recorded,
 		naming_moved: naming,
+		pure_entries,
+		every_test_importers: importers,
 		is_present: existsSync,
 	})
 }
@@ -246,7 +262,7 @@ async function scope_of(root: string, change: ChangeReading): Promise<RelatedSco
 // 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.
+// 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
 
@@ -254,7 +270,7 @@ async function reaches_tests(root: string, paths: ReadonlyArray<string>): Promis
 
 	if (change.map === undefined) return true
 
-	const scope = await scope_of(root, change)
+	const scope = await scope_of(root, change, true)
 
 	return scope.mode !== 'none'
 }
@@ -273,32 +289,46 @@ async function run_scope(
 		return 0
 	}
 
-	return 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,
-		description,
+	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): Promise<RelatedScope> {
+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)
+	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)
-	const scope = await resolve_change(root, change)
+	const change = await read_change(root, command_arguments, is_whole)
+	const scope = await resolve_change(root, change, is_whole)
 
-	const { changed, synced = [], since_map = [] } = change
+	const { changed, synced = [], since_map = [], branch } = change
 
-	return { scope, root, changed, synced, since_map }
+	return { scope, root, changed, synced, since_map, branch }
 }
 
 // Every run is timed and counted into the lane ledger (joshuafolkken/kit#4465).
@@ -319,20 +349,74 @@ async function run_and_record(
 	return exit_code
 }
 
-async function run_related_tests(command_arguments: ReadonlyArray<string>): Promise<number> {
-	const root = await changed_file_scope.repository_root_or_cwd()
-	const input = await read_run_input(root, command_arguments)
+// **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))
 
-	// A non-code argument is resolved through the map rather than handed to vitest, so only the
-	// code arguments can be ones vitest was not given.
+	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.filter((argument) => related_scope.is_relatable(argument)),
-		input.scope,
+		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 run_and_record(input, command_arguments)
+	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, {
 		before: conclusive_tree(before),

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

@@ -11,6 +11,7 @@ import { project_test_script, type ProjectScriptState } from './project-test-scr
 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
@@ -203,19 +204,32 @@ async function vitest_share(vitest_arguments: ReadonlyArray<string>): Promise<nu
 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,
-		stdio: 'inherit',
+		stdin: 'inherit',
+		stdout: ['inherit', 'pipe'],
+		stderr: ['inherit', 'pipe'],
+		all: true,
 		reject: false,
 	})
+	const exit_code = result.exitCode ?? FAIL_EXIT_CODE
 
-	return result.exitCode ?? FAIL_EXIT_CODE
+	vitest_failure_summary.report(vitest_arguments, result.all, exit_code)
+
+	return exit_code
 }
 
-// A whole-suite run also records the test-read map `josh test:related` narrows by.
-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 = [
 			...vitest_arguments,
@@ -226,11 +240,19 @@ async function run_vitest(vitest_arguments: ReadonlyArray<string>): Promise<numb
 		return await test_read_recording.with_read_recording(
 			root,
 			sized,
-			async (recording) => await execute_vitest(sized, recording),
+			async (recording) => await execute_vitest(sized, recording, directory),
 		)
 	})
 }
 
+// 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.
@@ -297,6 +319,7 @@ const test_unit_guard = {
 	isolated_unit_environment,
 	run_guarded_unit,
 	run_guarded_vitest,
+	run_vitest_in,
 	vitest_share,
 }
 

package/scripts/test/unit-durations.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+// The per-file unit durations the CI shards are balanced by (joshuafolkken/kit#4467), read here so
+// the published `josh test:related` can weigh them too (joshuafolkken/kit#5105) — the reporter that
+// refreshes the record is kit-only (`tools/test/unit-duration-record.ts`). A project without the
+// record reads an empty one.
+
+type Durations = Readonly<Record<string, number>>
+
+const RECORD_FILE = 'tools/test/unit-durations.json'
+
+function parse(text: string): Durations {
+	const parsed: unknown = JSON.parse(text)
+
+	if (typeof parsed !== 'object' || parsed === null) return {}
+
+	return Object.fromEntries(
+		Object.entries(parsed).filter(
+			(entry): entry is [string, number] => typeof entry[1] === 'number',
+		),
+	)
+}
+
+// A missing or unreadable record is an empty one: every file then weighs the same fallback.
+function read(root: string): Durations {
+	try {
+		return parse(readFileSync(path.join(root, RECORD_FILE), 'utf8'))
+	} catch {
+		return {}
+	}
+}
+
+const unit_durations = {
+	RECORD_FILE,
+	parse,
+	read,
+}
+
+export type { Durations }
+export { unit_durations }

package/scripts/test/unit-worker-share.ts

@@ -19,8 +19,9 @@ import { unit_run_marker } from './unit-run-marker'
 // worker.
 //
 // **The division activates only under concurrency.** One run in flight — every solo run, CI included
-// — gets exactly the number the gate and the hook produced before this module existed, so a quiet
-// machine behaves bit for bit as it did and only the condition that was measured broken changes.
+// — gets no share from it; what bounds a solo run is the claim it was admitted on (`cap_to_claim`),
+// which for a direct run is vitest's own default on a small machine such as a four-core CI runner
+// (`gate_plan.direct_unit_weight`, joshuafolkken/kit#4607).
 //
 // **The run markers and their division of the machine are `unit-run-marker.ts`**, the part the vitest
 // config imports (joshuafolkken/kit#4572); the capacity and claim bounds and the flag handling are here.
@@ -86,8 +87,8 @@ interface UnitClaim {
 // **The share never exceeds the claim the run was admitted on** (joshuafolkken/kit#4235). The share is
 // read after admission, when fewer runs may be in flight than when the weight was sized, and a share
 // wider than the claim puts workers on the machine the ledger does not hold. The claim bounds a solo
-// share too: vitest's own choice is one worker per core but one, wider than any weight the ledger
-// reserves for a unit run, so leaving it in place would open workers no claim holds. The claim holds
+// share too: vitest's own choice is one worker per core but one, wider than the weight the ledger
+// reserves for a unit run from seven cores up, so leaving it in place would open workers no claim holds. The claim holds
 // vitest's own process as well, so its workers are the claim less that core.
 function cap_to_claim(share: number | undefined, claim: UnitClaim | undefined): number | undefined {
 	if (claim === undefined) return share

package/scripts/test/vitest-cache-directory.ts

@@ -0,0 +1,19 @@
+// The Vite cache directory `vitest.config.ts` hands a vitest run in a throwaway tree (joshuafolkken/kit#4770).
+//
+// **A tree from `base-tree.ts` borrows this checkout's `node_modules`**, and vitest keys its dependency
+// optimizer's cache by project name alone, so a `josh test:red` / `josh test:pinned` run beside the gate
+// re-bundled the same `node_modules/.vite/vitest/<hash>/deps_ssr` the gate was importing from, and a gate
+// file failed on a deleted `execa.js`. The tree's run names a directory of its own through
+// `CACHE_DIRECTORY_KEY`; any other run leaves it unset and keeps Vite's default.
+
+const CACHE_DIRECTORY_KEY = 'JOSH_VITEST_CACHE_DIR'
+
+function config_cache_directory(environment: NodeJS.ProcessEnv = process.env): string | undefined {
+	const directory = environment[CACHE_DIRECTORY_KEY] ?? ''
+
+	return directory === '' ? undefined : directory
+}
+
+const vitest_cache_directory = { CACHE_DIRECTORY_KEY, config_cache_directory }
+
+export { vitest_cache_directory }

package/scripts/test/vitest-cli-excludes.ts

@@ -0,0 +1,14 @@
+// **A command line's `--exclude` reaches both unit projects** (joshuafolkken/kit#5105): vitest applies
+// the flag to the root config alone, which the inline projects of `tools/test/unit-projects.ts` do not
+// inherit, so without this it excluded nothing. `josh test:related` passes it to leave the heavy files
+// out of a scoped run. A leaf module, since `vitest.config.ts` imports it.
+
+const EXCLUDE_FLAG = '--exclude'
+
+function cli_excludes(argv: ReadonlyArray<string>): Array<string> {
+	return argv.slice(1).filter((_argument, index) => argv[index] === EXCLUDE_FLAG)
+}
+
+const vitest_cli_excludes = { EXCLUDE_FLAG, cli_excludes }
+
+export { vitest_cli_excludes }