@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -0,0 +1,103 @@
+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' | 'change' | 'directories'>
+
+// A checkout with no change base (no default-branch ref) still records its map, with no change to
+// discount: every read then counts, which narrows less, never wrongly.
+async function own_change(): Promise<Array<string>> {
+	try {
+		return await changed_paths.read_changed_paths(false)
+	} catch {
+		return []
+	}
+}
+
+// The tree the run read: the commit, every file that differed from it with its content's digest, the
+// checkout's change from its change base, 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))
+	const change = await own_change()
+
+	return { commit, dirty, change, 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 }

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

@@ -0,0 +1,166 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// What one recorded read says, decided without touching `fs`: which repository path was read, and
+// which module read it. `test-read-capture.ts`, armed by the `test-read-recorder.ts` setup file,
+// feeds this from inside every unit worker; everything here is pure so the decisions are testable without patching `fs`.
+//
+// **The reader is the outermost repository frame on the stack, not the test file alone.** Under
+// `isolate: false` a module that reads a document at load time is evaluated once per worker, so its
+// read lands on whichever test imported it first. Recording the module whose evaluation made the read
+// lets `vitest related` widen the read to every test that imports it, on any worker. A read a test
+// makes has the test outermost, so a shared helper it reads through — every test importing it — is
+// never the reader (joshuafolkken/kit#4417). The test file is recorded beside it, because an async
+// callback (a directory walk inside a dependency) leaves no repository frame at all.
+//
+// **Only a module's evaluation makes a module the reader** (joshuafolkken/kit#5033). A read a named
+// function makes after an `await` has that function outermost, since the continuation drops the test
+// that called it: `import-graph.ts` read some 3,700 paths that way, and `vitest related` widened each
+// to every test importing it. Such a read belongs to the test running it, recorded beside, so an
+// outermost frame with a function name records no module. A module's top-level code runs with no
+// function name; so does an anonymous callback, which keeps the widening — the safe side. A top-level
+// `await` of a named function that reads after an `await` of its own narrows to the first importing
+// test; no module does that today, and CI's whole suite would catch the miss.
+
+type ReadRecords = Record<string, Array<string>>
+
+// The worker setup file and the run that starts it agree on these two names and nothing else. They
+// live here rather than beside the map because the setup file is loaded before any test's
+// `vi.mock`: whatever it imports, no test can mock.
+const RECORD_DIRECTORY_KEY = 'JOSH_TEST_READS_DIRECTORY'
+const ROOT_KEY = 'JOSH_TEST_READS_ROOT'
+
+const FILE_URL_PREFIX = 'file://'
+const NODE_MODULES = 'node_modules'
+const GIT_DIRECTORY = '.git'
+const ROOT_ENTRY = '.'
+
+// **What a read depends on is decided by the call, not by the path alone.** Reading or probing a
+// path depends on that path; listing a directory depends on its direct entries; a recursive listing
+// depends on everything beneath it. The two directory kinds are keyed with a glob-shaped suffix so
+// the map keeps one shape: `scripts/*` is a listing of `scripts`, `scripts/**` a walk over it, and a
+// listing of the root is `*`.
+type ReadKind = 'path' | 'listing' | 'walk'
+
+const LISTING_READS: ReadonlySet<string> = new Set([
+	'readdir',
+	'readdirSync',
+	'opendir',
+	'opendirSync',
+])
+
+const KIND_SUFFIX: Record<Exclude<ReadKind, 'path'>, string> = { listing: '*', walk: '**' }
+
+function is_recursive(options: unknown): boolean {
+	return (
+		typeof options === 'object' && options !== null && Reflect.get(options, 'recursive') === true
+	)
+}
+
+// The kind of read an `fs` call by this name makes, given its second argument.
+function read_kind(name: string, options: unknown): ReadKind {
+	if (!LISTING_READS.has(name)) return 'path'
+
+	return is_recursive(options) ? 'walk' : 'listing'
+}
+
+function read_key(relative: string, kind: ReadKind): string {
+	return kind === 'path' ? relative : path.join(relative, KIND_SUFFIX[kind])
+}
+
+// The file a call site's script name points at — an absolute path or a `file://` URL — or
+// `undefined` for a `node:` internal or an evaluated string.
+function script_path(script_name: string): string | undefined {
+	if (script_name.startsWith(FILE_URL_PREFIX)) return fileURLToPath(script_name)
+
+	return path.isAbsolute(script_name) ? script_name : undefined
+}
+
+function is_outside(relative: string): boolean {
+	return relative.startsWith('..') || path.isAbsolute(relative)
+}
+
+function is_ignored(relative: string): boolean {
+	const segments = relative.split(path.sep)
+
+	return segments.includes(NODE_MODULES) || segments[0] === GIT_DIRECTORY
+}
+
+// A path relative to the root, or `undefined` when it lies outside it or inside a directory no test
+// result depends on. The root itself is `.`.
+function repository_path(root: string, file_path: string): string | undefined {
+	const relative = path.relative(root, file_path)
+
+	if (relative === '') return ROOT_ENTRY
+
+	return is_outside(relative) || is_ignored(relative) ? undefined : relative
+}
+
+// The path an `fs` call names. A descriptor or a buffer names no path this map can key on.
+function read_target(argument: unknown, cwd: string): string | undefined {
+	if (typeof argument === 'string') return path.resolve(cwd, argument)
+	if (argument instanceof URL) return fileURLToPath(argument)
+
+	return undefined
+}
+
+// One call site: its script name, and the name of the function running there — empty for a module's
+// top-level code or an anonymous callback.
+interface CallFrame {
+	script_name: string
+	function_name: string
+}
+
+interface ReaderQuery {
+	root: string
+	// Every call site, innermost first.
+	frames: ReadonlyArray<CallFrame>
+	// The recorder's own file, which is always the top frame and never the reader.
+	recorder: string
+}
+
+function frame_reader(query: ReaderQuery, frame: CallFrame): string | undefined {
+	const file_path = script_path(frame.script_name)
+
+	if (file_path === undefined || file_path === query.recorder) return undefined
+
+	const relative = repository_path(query.root, file_path)
+
+	return relative === ROOT_ENTRY ? undefined : relative
+}
+
+function stack_reader(query: ReaderQuery): string | undefined {
+	const outermost = query.frames.findLast((frame) => frame_reader(query, frame) !== undefined)
+
+	if (outermost?.function_name !== '') return undefined
+
+	return frame_reader(query, outermost)
+}
+
+function add_reader(records: Map<string, Set<string>>, read_path: string, reader: string): void {
+	const readers = records.get(read_path) ?? new Set<string>()
+
+	readers.add(reader)
+	records.set(read_path, readers)
+}
+
+function to_records(records: ReadonlyMap<string, ReadonlySet<string>>): ReadRecords {
+	return Object.fromEntries([...records].map(([read_path, readers]) => [read_path, [...readers]]))
+}
+
+const test_read_trace = {
+	RECORD_DIRECTORY_KEY,
+	ROOT_ENTRY,
+	ROOT_KEY,
+	add_reader,
+	read_key,
+	read_kind,
+	read_target,
+	repository_path,
+	script_path,
+	stack_reader,
+	to_records,
+}
+
+export type { CallFrame, ReadKind, ReaderQuery, ReadRecords }
+export { test_read_trace }

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

@@ -1,3 +1,4 @@
+import node_path from 'node:path'
 import { issue_bug_label } from '#scripts/issue/issue-bug-label'
 import { json_value } from '#scripts/lib/json-value'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
@@ -11,7 +12,15 @@ import { test_declared_logic } from './test-declared-logic'
 // that test catches anything — the added and changed tests run against the merge-base, and at least one
 // of them has to fail there.
 
-type RedVerdict = 'red' | 'green' | 'no-test' | 'test-only'
+type RedVerdict = 'red' | 'green' | 'no-test' | 'stopped' | 'test-only'
+
+// One run's verdict and the test files that failed in it. `ran` is the number of test files the run
+// ran, absent on a verdict read back from a cache (joshuafolkken/kit#5078).
+interface RedProbe {
+	verdict: RedVerdict
+	failed: ReadonlyArray<string>
+	ran?: number
+}
 
 // The declaration a bug-fix Issue carries under its background heading, in the same slot as the
 // behavior-change declaration (`behavior-change-lint.ts`). Read from the declaration, never inferred,
@@ -55,23 +64,53 @@ function ran_file_count(report: string): number {
 	return json_value.parse_with(report, REPORT_SCHEMA)?.testResults.length ?? 0
 }
 
-// `no-test` when nothing ran; otherwise a failing run is `red` — the test caught the pre-fix tree — and
-// a passing one is `green`.
+// The test files a run failed in, as `josh test:pinned` stores them beside a `red` verdict
+// (joshuafolkken/kit#4790). Vitest names each by its absolute path, under the tree's own path or its real
+// one — a macOS temporary directory sits behind `/var` → `/private/var` — so each is read relative to the
+// first of `roots` it sits under. An unreadable report fails none.
+const RESULT_SCHEMA = z.object({ name: z.string(), status: z.string() })
+const RESULTS_SCHEMA = z.object({ testResults: z.array(RESULT_SCHEMA) })
+const FAILED_STATUS = 'failed'
+const PARENT_PREFIX = '..'
+
+function is_inside(name: string): boolean {
+	return !name.startsWith(PARENT_PREFIX) && !node_path.isAbsolute(name)
+}
+
+function relative_in(roots: ReadonlyArray<string>, file: string): Array<string> {
+	const relatives = roots.map((root) => node_path.relative(root, file))
+
+	return relatives.filter((name) => is_inside(name)).slice(0, 1)
+}
+
+function failed_files(report: string, roots: ReadonlyArray<string>): Array<string> {
+	const results = json_value.parse_with(report, RESULTS_SCHEMA)?.testResults ?? []
+
+	return results
+		.filter((result) => result.status === FAILED_STATUS)
+		.flatMap((result) => relative_in(roots, result.name))
+}
+
+// `no-test` when nothing ran and vitest passed with no tests; `stopped` when nothing ran and it failed
+// anyway — its config could not load, so no test was ever asked (joshuafolkken/kit#5043). Otherwise a
+// failing run is `red` — the test caught the pre-fix tree — and a passing one is `green`.
 function verdict_for(test_count: number, is_failed: boolean): RedVerdict {
-	if (test_count === 0) return 'no-test'
+	if (test_count === 0) return is_failed ? 'stopped' : 'no-test'
 
 	return is_failed ? 'red' : 'green'
 }
 
 // Only `green` on a declared bug fix is refused. `no-test` is already `josh test:declared`'s refusal
-// when a runtime file changed, a declared fix that touched only docs has nothing to reproduce, and a
-// `test-only` fix runs the same code on the merge-base as on HEAD.
+// when a runtime file changed, a declared fix that touched only docs has nothing to reproduce, a
+// `stopped` run asked no test, so it is neither red evidence nor green, and a `test-only` fix runs the
+// same code on the merge-base as on HEAD.
 function is_refused(body: string, verdict: RedVerdict): boolean {
 	return verdict === 'green' && is_bug_fix(body)
 }
 
 const test_red_logic = {
 	BUG_DECLARATION_LINE,
+	failed_files,
 	is_bug_fix,
 	is_refused,
 	is_test_only,
@@ -80,5 +119,5 @@ const test_red_logic = {
 	verdict_for,
 }
 
-export type { RedVerdict }
+export type { RedProbe, RedVerdict }
 export { test_red_logic }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { test_red } from './test-red'
+
+// The `josh test:red` entry, kept apart from `test-red.ts` because `test-red-commit.ts` imports 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_red.main(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/test/test-red.ts

@@ -1,27 +1,29 @@
 import { existsSync } from 'node:fs'
-import { copyFile, mkdir, readFile } from 'node:fs/promises'
+import { readFile, realpath, rm } from 'node:fs/promises'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 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_location_environment } from '#scripts/git/git-location-environment'
 import { execa } from 'execa'
-import { test_red_logic, type RedVerdict } from './test-red-logic'
+import { test_red_logic, type RedProbe, type RedVerdict } from './test-red-logic'
+import { vitest_cache_directory } from './vitest-cache-directory'
 
 // `josh test:red` — run the added and changed Vitest files against the pre-fix tree and print `red`,
-// `green`, `no-test` or `test-only`.
+// `green`, `no-test`, `stopped` or `test-only`.
 //
 // **The pre-fix tree is a detached worktree at the merge-base, never the caller's checkout**
 // (`base-tree.ts`). The tests are copied in from the working tree, so what runs is the new test
 // against the old code.
 
-const ARGV_OFFSET = 2
 const TREE_PREFIX = 'josh-test-red-'
 const REPORT_NAME = 'report.json'
+// Beside the tree, so the run's dependency optimizer never rewrites the borrowed `node_modules/.vite`
+// a gate beside it imports from (`vitest-cache-directory.ts`).
+const CACHE_NAME = 'vite-cache'
 const VITEST_BIN = path.join(base_tree.NODE_MODULES, '.bin', 'vitest')
 const USAGE =
-	'Usage: josh test:red — prints red / green / no-test / test-only for the changed tests on the merge-base'
+	'Usage: josh test:red — prints red / green / no-test / stopped / test-only for the changed tests on the merge-base'
 
 interface RedRun {
 	verdict: RedVerdict
@@ -33,22 +35,6 @@ function changed_tests(paths: ReadonlyArray<string>): Array<string> {
 	return test_red_logic.unit_test_files(paths).filter((file) => existsSync(file))
 }
 
-async function copy_one(tree: string, file: string): Promise<void> {
-	const target = path.join(tree, file)
-
-	await mkdir(path.dirname(target), { recursive: true })
-	await copyFile(file, target)
-}
-
-// Each file has its own target, and a recursive `mkdir` tolerates a sibling creating the same parent.
-async function copy_in(tree: string, files: ReadonlyArray<string>): Promise<void> {
-	await Promise.all(
-		files.map(async (file) => {
-			await copy_one(tree, file)
-		}),
-	)
-}
-
 function reporter_arguments(report: string): Array<string> {
 	// The plain `--outputFile`, not `--outputFile.json`: a config that sets `test.outputFile` as a string
 	// wins over the keyed form, which would send the report into the tree and read every run `no-test`.
@@ -59,32 +45,47 @@ async function read_report(report: string): Promise<string> {
 	return existsSync(report) ? await readFile(report, 'utf8') : ''
 }
 
-// The verdict of one run. `--passWithNoTests` keeps "the filter matched nothing" from reading as a
+// The verdict of one run over `selection` — `run <files>`, or `related <file> --run` for
+// `josh test:pinned`. `--passWithNoTests` keeps "the filter matched nothing" from reading as a
 // failure, and the JSON report — written beside the tree, never into it — says whether anything ran at
 // all, so a file the old config excludes is `no-test` rather than a `green` that refuses a correct fix.
-// A test that ran and broke, or a file that could not load against the old code, makes it `red`.
-async function verdict_in(
+// A test that ran and broke, or a file that could not load against the old code, makes it `red`, and
+// the files it broke in come back beside the verdict. The report is removed first, so a run that writes
+// none never reads the one before it.
+async function probe_in(
 	{ parent, tree }: BaseTree,
-	files: ReadonlyArray<string>,
-): Promise<RedVerdict> {
+	selection: ReadonlyArray<string>,
+): Promise<RedProbe> {
 	const report = path.join(parent, REPORT_NAME)
-	const vitest_args = ['run', '--passWithNoTests', ...reporter_arguments(report), ...files]
+	const vitest_args = [...selection, '--passWithNoTests', ...reporter_arguments(report)]
+
+	await rm(report, { force: true })
 	const result = await execa(path.join(tree, VITEST_BIN), vitest_args, {
 		cwd: tree,
-		env: git_location_environment.location_free_environment(),
+		env: {
+			...git_location_environment.location_free_environment(),
+			[vitest_cache_directory.CACHE_DIRECTORY_KEY]: path.join(parent, CACHE_NAME),
+		},
 		extendEnv: true,
 		reject: false,
 	})
-	const ran = test_red_logic.ran_file_count(await read_report(report))
+	const text = await read_report(report)
+	const ran = test_red_logic.ran_file_count(text)
 
-	return test_red_logic.verdict_for(ran, result.exitCode !== 0)
+	return {
+		verdict: test_red_logic.verdict_for(ran, result.exitCode !== 0),
+		failed: test_red_logic.failed_files(text, [tree, await realpath(tree)]),
+		ran,
+	}
 }
 
 async function verdict_on(base: string, files: ReadonlyArray<string>): Promise<RedVerdict> {
 	return await base_tree.with_tree(TREE_PREFIX, base, async (pre_fix) => {
-		await copy_in(pre_fix.tree, files)
+		await base_tree.copy_in(pre_fix.tree, files)
+
+		const probe = await probe_in(pre_fix, ['run', ...files])
 
-		return await verdict_in(pre_fix, files)
+		return probe.verdict
 	})
 }
 
@@ -92,7 +93,7 @@ async function verdict_on(base: string, files: ReadonlyArray<string>): Promise<R
 // `no-test` — there is no pre-fix tree to run against, and a guard fails open. A change whose every path
 // is a test file is `test-only` without a run: the merge-base runs the same code as HEAD.
 async function run(): Promise<RedRun> {
-	const base = await change_base.resolved()
+	const base = await change_base.resolved_through_merge()
 	const paths = await changed_paths.read_changed_paths(false)
 	const files = changed_tests(paths)
 
@@ -117,11 +118,12 @@ async function main(argv: ReadonlyArray<string>): Promise<number> {
 	return 0
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await main(process.argv.slice(ARGV_OFFSET))
+// Whether the checkout has the Vitest `probe_in` runs; without it every run would read `no-test`.
+function has_runner(): boolean {
+	return existsSync(VITEST_BIN)
 }
 
-const test_red = { run }
+const test_red = { has_runner, main, probe_in, run }
 
 export type { RedRun }
 export { test_red }

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

@@ -0,0 +1,37 @@
+import { core_budget } from '#scripts/gate/core-budget'
+import { gate_plan } from '#scripts/gate/gate-plan'
+import { test_pinned_reach } from './test-pinned-reach'
+import { related_scope } from './test-related-scope'
+
+// The cores a `josh test:related` vitest pass claims once its files are known (joshuafolkken/kit#5135):
+// a narrowed pass by the test files its imports reach — not by its own files, one of which may reach
+// hundreds — and the whole suite (`undefined`), or files no graph can be built for, by the full width
+// a direct unit run holds.
+async function claim_weight(files: ReadonlyArray<string> | undefined): Promise<number> {
+	const tests = files === undefined ? undefined : await test_pinned_reach.reached_test_count(files)
+
+	return tests === undefined ? gate_plan.direct_unit_weight() : gate_plan.scoped_unit_weight(tests)
+}
+
+// **Each vitest pass takes its claim here, not on the command entry**: the entry is reserved before
+// the scope resolves, so it could only ever claim the whole width. `vitest_share` reads this claim
+// back as the `--maxWorkers` bound. Under `josh gate` the gate's claim covers the run, so none is
+// sized.
+async function with_unit_claim(
+	files: ReadonlyArray<string> | undefined,
+	run: () => Promise<number>,
+): Promise<number> {
+	if (core_budget.is_covered()) return await run()
+
+	const weight = await claim_weight(files)
+
+	return await core_budget.with_command_reservation(weight, run, {
+		memory_mb: gate_plan.unit_memory(weight),
+		command: related_scope.COMMAND_NAME,
+		is_unit: true,
+	})
+}
+
+const test_related_claim = { with_unit_claim }
+
+export { test_related_claim }

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
+import { run_ship_removed_rows } from '#scripts/run/ship/run-ship-removed-rows'
+import { split_early_notice } from '#scripts/split/split-early-notice'
+import { test_related } from './test-related'
+
+// The `josh test:related` entry, kept apart from `test-related.ts` because `check-inputs.ts` imports
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186). A green run then shows the tests the change removed, the one place a run
+// meets them before `josh ship` (joshuafolkken/kit#4563), and any run shows the split notice once per
+// Issue when the diff has outgrown the guide (joshuafolkken/kit#4642).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const exit_code = await test_related.run_related_tests(
+		process.argv.slice(changed_file_scope.ARGV_START),
+	)
+
+	if (exit_code === 0) await run_ship_removed_rows.surface()
+	await split_early_notice.surface()
+	process.exitCode = exit_code
+}

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

@@ -0,0 +1,91 @@
+import type { MovedParts } from '#scripts/gate/moved-paths'
+import { test_declared_logic } from './test-declared-logic'
+import type { ReadMap } from './test-read-map'
+import { related_scope, type ScopeRequest } from './test-related-scope'
+import { test_related_synced, type SyncedSplit } from './test-related-synced'
+import { whole_suite_files } from './whole-suite-files'
+
+// How `josh test:related` reads what moved since its last green run (`since-green.ts`) into the change
+// it narrows by — split out of `test-related.ts`, which runs the reading.
+
+// 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. `branch` is
+// this branch's own change from its merge base, where it was read.
+type ChangeReading = Pick<ScopeRequest, 'changed' | 'map' | 'since_map'> & {
+	is_unmoved?: true
+	synced?: ReadonlyArray<string>
+	branch?: ReadonlyArray<string> | undefined
+}
+
+function is_whole_suite(file: string): boolean {
+	return whole_suite_files.WHOLE_SUITE_FILES.has(file)
+}
+
+// **A non-code file a main sync brought in is not this branch's change** (joshuafolkken/kit#4572), so it
+// joins `since_map`: it neither adds the tests reading it nor sends the run to the whole suite — main's
+// CI verified it. So does a synced file every test depends on, which the split cannot narrow
+// (joshuafolkken/kit#4993): main's CI ran the whole suite on it, and this branch's own tests run on it
+// anyway. Any other synced module is `test-related-synced.ts`'s: only this branch's change runs for it,
+// where the two meet. A branch change git cannot read marks nothing.
+function synced_data(
+	synced: ReadonlyArray<string>,
+	branch: ReadonlyArray<string> | undefined,
+): ReadonlyArray<string> {
+	const data = synced.filter((file) => !related_scope.is_relatable(file) || is_whole_suite(file))
+
+	return data.filter((file) => !(branch ?? data).includes(file))
+}
+
+// **The branch's own test files stay out of `since_map`** (joshuafolkken/kit#4393), so each runs again
+// on every bare run after a green one — the map holds no entry for a read one started since its tree.
+// Only main's and another lane's test files are left to CI (joshuafolkken/kit#4896). A branch change git
+// cannot read keeps every test file.
+function without_own_tests(
+	since_map: ReadonlyArray<string>,
+	branch: ReadonlyArray<string> | undefined,
+): ReadonlyArray<string> {
+	return since_map.filter(
+		(file) => !test_declared_logic.is_test_file(file) || branch?.includes(file) === false,
+	)
+}
+
+// The moved files handed on as explicit arguments, the synced modules the split left out taken away.
+// Where one meets this branch's change, the change runs in its place (`test-related-synced.ts`) — named
+// even when only the sync moved, since a green branch side would otherwise run nothing.
+function narrowed_moved(
+	moved: ReadonlyArray<string>,
+	split: SyncedSplit,
+	branch: ReadonlyArray<string> | undefined,
+	map: ReadMap | undefined,
+): ReadonlyArray<string> {
+	const kept = moved.filter((file) => !split.left.includes(file))
+	const own = split.shared.length === 0 ? [] : test_related_synced.own_of(branch, map)
+
+	return [...new Set([...kept, ...(own ?? [])])]
+}
+
+// The reading's `since_map`: what this branch did not change. The synced modules left out join it and
+// the change, so they settle as reaching no test rather than leaving an empty selection that runs the
+// whole suite.
+function moved_reading(
+	change: ChangeReading,
+	parts: MovedParts,
+	branch: ReadonlyArray<string> | undefined,
+	split: SyncedSplit,
+): ChangeReading {
+	const since_map = [
+		...without_own_tests(change.since_map ?? [], branch),
+		...synced_data(parts.synced, branch),
+		...split.left,
+	]
+	const changed = [...new Set([...(change.changed ?? []), ...split.left])]
+
+	return { ...change, changed, since_map: [...new Set(since_map)], synced: parts.synced, branch }
+}
+
+const test_related_moved = { is_whole_suite, moved_reading, narrowed_moved }
+
+export type { ChangeReading }
+export { test_related_moved }