@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -0,0 +1,264 @@
+import { readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { atomic_write } from '#scripts/lib/atomic-write'
+import { json_value } from '#scripts/lib/json-value'
+import { test_read_trace, type ReadRecords } from './test-read-trace'
+
+// The test-read map: for every repository path a full unit run read, the modules that read it.
+// `josh test:related` resolves a changed non-code file through it to the code files `vitest related`
+// can walk, so a changed document runs the tests that read it rather than the whole suite.
+//
+// **The map is valid against the tree it was recorded on, and only that tree.** It records the
+// commit and the files that differed from it, so the change a narrowing reads is the change since
+// then. A tree whose own code changed what it reads has changed that code, and `vitest related`
+// runs the tests importing it. **It lives in the git common directory**, which every lane worktree of
+// one clone shares along with the commits it names, so one lane's full run narrows the next lane's.
+// **One file per version** (joshuafolkken/kit#4423): a lane on an older kit writing its map leaves a
+// newer lane's map in place, so a version bump no longer sends either to the whole suite.
+
+interface ReadMap {
+	version: number
+	commit: string
+	// The files that differed from `commit` when the map was recorded, each with the digest of its
+	// content then (`input_fingerprint.of_files`), so one whose content has not moved since does not count as changed
+	// (joshuafolkken/kit#4425).
+	dirty: Record<string, string>
+	// The directories `commit` holds, so a directory new since then is told apart from one no test
+	// read — the map's own keys cannot say which, since an unread directory has none.
+	directories: Array<string>
+	readers: ReadRecords
+}
+
+// Bumped whenever the shape, what a reader means or how `dirty` is digested changes, so a map an older
+// kit wrote reads as no map at all and the next full run writes it afresh. 6: `dirty` is
+// `input-fingerprint.ts`'s digest of every changed file (joshuafolkken/kit#4497).
+const MAP_VERSION = 6
+
+const MAP_DIRECTORY = 'josh'
+const MAP_FILE_STEM = 'test-read-map'
+const RECORD_EXTENSION = '.json'
+
+// A map file of another version no lane has written for this long belongs to no kit still running,
+// and is removed by the next write: one week.
+const STALE_AFTER_MS = 604_800_000
+
+type ReadPair = [string, string]
+
+function record_pairs(record: ReadRecords): Array<ReadPair> {
+	return Object.entries(record).flatMap(([read_path, readers]) =>
+		readers.map((reader): ReadPair => [read_path, reader]),
+	)
+}
+
+function merge_records(records: ReadonlyArray<ReadRecords>): ReadRecords {
+	const merged = new Map<string, Set<string>>()
+	const pairs = records.flatMap((record) => record_pairs(record))
+
+	for (const [read_path, reader] of pairs) {
+		test_read_trace.add_reader(merged, read_path, reader)
+	}
+
+	return test_read_trace.to_records(merged)
+}
+
+function is_object(value: unknown): value is object {
+	return typeof value === 'object' && value !== null
+}
+
+function is_string_array(value: unknown): value is Array<string> {
+	return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+}
+
+function is_read_records(value: unknown): value is ReadRecords {
+	return is_object(value) && Object.values(value).every(is_string_array)
+}
+
+function is_digest_record(value: unknown): value is Record<string, string> {
+	if (!is_object(value) || Array.isArray(value)) return false
+
+	return Object.values(value).every((digest) => typeof digest === 'string')
+}
+
+const FIELD_CHECKS: ReadonlyArray<[keyof ReadMap, (field: unknown) => boolean]> = [
+	['version', (field) => field === MAP_VERSION],
+	['commit', (field) => typeof field === 'string'],
+	['dirty', is_digest_record],
+	['directories', is_string_array],
+	['readers', is_read_records],
+]
+
+function is_read_map(value: unknown): value is ReadMap {
+	if (!is_object(value)) return false
+
+	return FIELD_CHECKS.every(([field, is_valid]) => is_valid(Reflect.get(value, field)))
+}
+
+// **The files whose content differs from the tree the map was recorded on** (joshuafolkken/kit#4425).
+// `since` is every path that differs from `map.commit` now, and `current` the digest of every path
+// that was dirty then. A path dirty then is changed only when its digest moved: counted by name, a
+// lane's own change the map was recorded over read as changed on every later run, so a gate reused
+// no green unit step whenever the lane held any code.
+function changed_since_tree(
+	map: ReadMap,
+	since: ReadonlyArray<string>,
+	current: Readonly<Record<string, string>>,
+): Array<string> {
+	const fresh = since.filter((file) => !Object.hasOwn(map.dirty, file))
+	const moved = Object.entries(map.dirty)
+		.filter(([file, digest]) => current[file] !== digest)
+		.map(([file]) => file)
+
+	return [...new Set([...fresh, ...moved])]
+}
+
+function parse_map(text: string): ReadMap | undefined {
+	const value = json_value.parse_or_undefined(text)
+
+	return is_read_map(value) ? value : undefined
+}
+
+function parse_records(text: string): ReadRecords {
+	const value = json_value.parse_or_undefined(text)
+
+	return is_read_records(value) ? value : {}
+}
+
+// Innermost first, ending at the root `.`.
+function directories_above(relative: string): Array<string> {
+	const parent = path.dirname(relative)
+
+	if (parent === relative) return []
+
+	return [parent, ...directories_above(parent)]
+}
+
+// The directories on the file's path the recorded commit did not hold, innermost first. The root
+// always existed.
+function created_directories(
+	directories: ReadonlyArray<string>,
+	recorded: ReadonlySet<string>,
+): Array<string> {
+	return directories.filter(
+		(directory) => directory !== test_read_trace.ROOT_ENTRY && !recorded.has(directory),
+	)
+}
+
+// A changed file is read by whoever read it, listed its own directory or walked any directory above
+// it. A directory new since the recording is also a new entry in the listing above it and a probe of
+// it that now answers differently; a directory that already existed reads the same to both, whatever
+// changed deeper down.
+function lookup_keys(relative: string, recorded: ReadonlySet<string>): Array<string> {
+	const directories = directories_above(relative)
+	const created = created_directories(directories, recorded)
+	const listed = [
+		directories[0] ?? test_read_trace.ROOT_ENTRY,
+		...created.map((directory) => path.dirname(directory)),
+	]
+
+	return [
+		relative,
+		...created,
+		...listed.map((directory) => test_read_trace.read_key(directory, 'listing')),
+		...directories.map((directory) => test_read_trace.read_key(directory, 'walk')),
+	]
+}
+
+function readers_of(map: ReadMap, relative: string): Array<string> {
+	const keys = lookup_keys(relative, new Set(map.directories))
+
+	return [...new Set(keys.flatMap((key) => map.readers[key] ?? []))]
+}
+
+// **A directory the recorded tree held, inside which no recorded test listed, walked or read any
+// entry** (joshuafolkken/kit#4303). A file added to it since is one no test reads, as surely as one
+// the tree already held there: a test that builds a path into it reads some file there, and one that
+// enumerates it lists it, both of which leave a key whose directory is this one.
+function in_unread_directory(map: ReadMap, relative: string): boolean {
+	const directory = path.dirname(relative)
+
+	if (!map.directories.includes(directory)) return false
+
+	return Object.keys(map.readers).every((key) => path.dirname(key) !== directory)
+}
+
+function map_path(root: string, version: number = MAP_VERSION): string | undefined {
+	const common = git_common_directory.repository(root)
+	const name = `${MAP_FILE_STEM}.v${String(version)}${RECORD_EXTENSION}`
+
+	return common === undefined ? undefined : path.join(common, MAP_DIRECTORY, name)
+}
+
+// Every version's map, the unversioned one kits before joshuafolkken/kit#4423 wrote included; a
+// staging file ends in `.tmp`, not the extension.
+function is_map_file(name: string): boolean {
+	return name.startsWith(MAP_FILE_STEM) && name.endsWith(RECORD_EXTENSION)
+}
+
+// A file another lane's write pruned meanwhile has no stat, and is not this write's to remove.
+function is_stale(file_path: string, now: number): boolean {
+	const modified = statSync(file_path, { throwIfNoEntry: false })?.mtimeMs ?? now
+
+	return now - modified > STALE_AFTER_MS
+}
+
+// The map just written is never stale, so it survives its own prune.
+function prune_stale_maps(directory: string): void {
+	const now = Date.now()
+	const maps = readdirSync(directory)
+		.filter((name) => is_map_file(name))
+		.map((name) => path.join(directory, name))
+
+	for (const file_path of maps) {
+		if (is_stale(file_path, now)) rmSync(file_path, { force: true })
+	}
+}
+
+function read_text(file_path: string): string | undefined {
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function read_map(root: string): ReadMap | undefined {
+	const file_path = map_path(root)
+	const text = file_path === undefined ? undefined : read_text(file_path)
+
+	return text === undefined ? undefined : parse_map(text)
+}
+
+// Written beside the target and renamed over it, so a lane reading the map while another lane
+// replaces it reads one whole map or the other. It lands in its own version's file.
+function write_map(root: string, map: ReadMap): void {
+	const file_path = map_path(root, map.version)
+
+	if (file_path === undefined) return
+
+	atomic_write.replace_file(file_path, JSON.stringify(map))
+	prune_stale_maps(path.dirname(file_path))
+}
+
+// Every worker writes its own files into the run's directory; this reads them all back.
+function collect_records(directory: string): Array<ReadRecords> {
+	return readdirSync(directory)
+		.filter((name) => name.endsWith(RECORD_EXTENSION))
+		.map((name) => parse_records(read_text(path.join(directory, name)) ?? ''))
+}
+
+const test_read_map = {
+	MAP_VERSION,
+	changed_since_tree,
+	collect_records,
+	in_unread_directory,
+	map_path,
+	merge_records,
+	parse_map,
+	read_map,
+	readers_of,
+	write_map,
+}
+
+export type { ReadMap }
+export { test_read_map }

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

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

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

@@ -0,0 +1,148 @@
+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.
+
+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
+}
+
+interface ReaderQuery {
+	root: string
+	// The script name of every call site, innermost first.
+	scripts: ReadonlyArray<string>
+	// The recorder's own file, which is always the top frame and never the reader.
+	recorder: string
+}
+
+function frame_reader(query: ReaderQuery, script_name: string): string | undefined {
+	const file_path = script_path(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 {
+	return query.scripts
+		.map((script_name) => frame_reader(query, script_name))
+		.findLast((reader) => reader !== undefined)
+}
+
+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 { ReadKind, ReaderQuery, ReadRecords }
+export { test_read_trace }

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,7 +1,6 @@
 import { existsSync } from 'node:fs'
-import { copyFile, mkdir, readFile } from 'node:fs/promises'
+import { readFile, 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'
@@ -16,7 +15,6 @@ import { test_red_logic, type RedVerdict } from './test-red-logic'
 // (`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'
 const VITEST_BIN = path.join(base_tree.NODE_MODULES, '.bin', 'vitest')
@@ -33,22 +31,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,16 +41,20 @@ 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`.
+// A test that ran and broke, or a file that could not load against the old code, makes it `red`. The
+// report is removed first, so a run that writes none never reads the one before it.
 async function verdict_in(
 	{ parent, tree }: BaseTree,
-	files: ReadonlyArray<string>,
+	selection: ReadonlyArray<string>,
 ): Promise<RedVerdict> {
 	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(),
@@ -82,9 +68,9 @@ async function verdict_in(
 
 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)
 
-		return await verdict_in(pre_fix, files)
+		return await verdict_in(pre_fix, ['run', ...files])
 	})
 }
 
@@ -117,11 +103,7 @@ 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))
-}
-
-const test_red = { run }
+const test_red = { main, run, verdict_in }
 
 export type { RedRun }
 export { test_red }

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

@@ -0,0 +1,18 @@
+#!/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 { 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).
+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()
+	process.exitCode = exit_code
+}