@joshuafolkken/kit 1.1514.0 → 1.1784.0

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
+}

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

@@ -0,0 +1,119 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { lane_ledger, type TestRelatedRecord } from '#scripts/lane/lane-ledger'
+import { related_scope, type RelatedScope } from './test-related-scope'
+import { unit_count_file } from './unit-count-file'
+
+// What one `josh test:related` run leaves in the lane ledger (joshuafolkken/kit#4465): how much of its
+// input was the change itself, what a main sync brought in and what the test-read map added, the
+// scope it settled on, how many test files vitest ran and how long it took — so `josh lane:stats`
+// can tell a run widened by its input from one vitest widened by itself.
+
+const COUNT_FILE_NAME = 'count'
+
+// The facts the run knew before vitest started: the scope, and the change it was resolved from.
+interface RunInput {
+	scope: RelatedScope
+	root: string
+	// Repository-root-relative, as the change was read; `undefined` when it could not be.
+	changed: ReadonlyArray<string> | undefined
+	// The part of `changed` a main sync brought in, empty outside a since-green reading.
+	synced: ReadonlyArray<string>
+	// The part of `changed` the change since the test-read map's tree joined to the named or moved
+	// files — main merges that landed after the map among them — never the run's own change. It holds
+	// the synced non-code files as well, which the record counts as `synced` alone.
+	since_map: ReadonlyArray<string>
+}
+
+interface RunResult {
+	elapsed_ms: number
+	test_files: number | undefined
+}
+
+function set_count_target(target: string | undefined): void {
+	const { COUNT_FILE_ENVIRONMENT } = unit_count_file
+
+	if (target === undefined) Reflect.deleteProperty(process.env, COUNT_FILE_ENVIRONMENT)
+	else process.env[COUNT_FILE_ENVIRONMENT] = target
+}
+
+// An unwritable temp root leaves the run uncounted rather than failing the tests it would only measure.
+function count_directory(): string | undefined {
+	try {
+		return mkdtempSync(path.join(tmpdir(), 'josh-test-related-'))
+	} catch {
+		return undefined
+	}
+}
+
+// Runs `run` with the unit reporter told where to write the run's test-file count, and reads it back.
+// A run that started no vitest writes none, which is an absent count rather than zero.
+async function with_test_count(
+	run: () => Promise<number>,
+): Promise<{ exit_code: number; test_files: number | undefined }> {
+	const directory = count_directory()
+
+	if (directory === undefined) return { exit_code: await run(), test_files: undefined }
+
+	const file = path.join(directory, COUNT_FILE_NAME)
+	const previous = process.env[unit_count_file.COUNT_FILE_ENVIRONMENT]
+
+	set_count_target(file)
+
+	try {
+		return { exit_code: await run(), test_files: unit_count_file.read_count(file) }
+	} finally {
+		set_count_target(previous)
+		rmSync(directory, { recursive: true, force: true })
+	}
+}
+
+// The scope's files the change did not name — the map's readers and the code readers it added.
+function readers_of(input: RunInput, changed: ReadonlySet<string>): number {
+	if (input.scope.mode !== 'related') return 0
+
+	return input.scope.files.filter((file) => !changed.has(path.relative(input.root, file))).length
+}
+
+function part_of(part: ReadonlyArray<string>, changed: ReadonlySet<string>): number {
+	return part.filter((file) => changed.has(file)).length
+}
+
+// The changed files that sent a full-suite run there, repository-root-relative, or none.
+function triggers_of(input: RunInput): Partial<TestRelatedRecord> {
+	if (input.scope.mode !== 'all' || input.scope.files.length === 0) return {}
+
+	return { trigger_files: input.scope.files.map((file) => path.relative(input.root, file)) }
+}
+
+function record_of(input: RunInput, result: RunResult): TestRelatedRecord {
+	const changed = new Set(input.changed)
+	const synced = part_of(input.synced, changed)
+	// A synced non-code file is in `since_map` too (`synced_data` in `test-related.ts`), counted once.
+	const since_map = part_of(
+		input.since_map.filter((file) => !input.synced.includes(file)),
+		changed,
+	)
+	const record = {
+		scope: related_scope.scope_kind(input.scope),
+		changed: changed.size - synced - since_map,
+		synced,
+		since_map,
+		readers: readers_of(input, changed),
+		...triggers_of(input),
+		elapsed_ms: Math.round(result.elapsed_ms),
+	}
+
+	return result.test_files === undefined ? record : { ...record, test_files: result.test_files }
+}
+
+// Best-effort, as every ledger write is.
+async function record_run(input: RunInput, result: RunResult, ledger?: string): Promise<void> {
+	await lane_ledger.record_test_related(record_of(input, result), ledger)
+}
+
+const test_related_record = { record_of, record_run, with_test_count }
+
+export type { RunInput, RunResult }
+export { test_related_record }