@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -1,31 +1,42 @@
 import path from 'node:path'
-import {
-	changed_file_scope,
-	type ChangedFileScope,
-	type ScopeInputs,
-	type ScopeVocabulary,
-} from '#scripts/git/changed-file-scope'
-
-// The whole unit suite is expensive. Measured warm on kit, that is 384 files
-// and 6,616 tests — 13.9s wall and 110s of CPU, 84% of everything the four gate checks spend, and
-// an implementation loop paid it again on every re-check. The same tree narrowed to one changed
-// file runs 31 files and 566 tests in 2.4s (7.9s of CPU, −93%).
+import { changed_file_scope, type ChangedFileScope } from '#scripts/git/changed-file-scope'
+import { test_declared_logic } from './test-declared-logic'
+import { test_read_map, type ReadMap } from './test-read-map'
+import { whole_suite_files } from './whole-suite-files'
+
+// The whole unit suite is expensive — the largest share of what the gate checks spend, and an
+// implementation loop paid it again on every re-check — while one changed file narrows it to a small
+// fraction. `josh lane:stats` reports what `test:unit` costs now.
 //
-// **This narrowing is added in front of the whole suite, never in place of it.** A test that breaks
-// without importing what changed — a marker suite reading a document, a fixture compared against a
-// generated file — is invisible to a module graph, so the verification gate keeps running
-// `josh test:unit` over everything before the commit.
+// **The verification gate runs this narrowing in place of the whole suite** (joshuafolkken/kit#4065),
+// which is safe only because it reaches every test a change can break. A changed module reaches
+// the tests importing it through `vitest related`, and the tests reading it as data through the
+// test-read map a whole-suite run records (`test-read-map.ts`). A changed document, config or
+// snapshot — which no module graph holds — reaches the modules that read it through that map alone. **Whatever neither can answer runs the whole suite**: no map, a
+// non-code file added since the recorded tree that no recorded test read, where a test read inside its
+// directory or the tree did not hold it, or a file every test
+// depends on — each counted only when this change moved it (joshuafolkken/kit#4527). A non-code file the recorded tree already held and no test read is one no test reads
+// (joshuafolkken/kit#4073), and so is one added since to a directory the tree held and no test read
+// inside (joshuafolkken/kit#4303), so a change made only of those runs nothing. CI runs the whole suite
+// regardless, so a read the recorder could not see — one a child process makes — is still caught
+// before the merge.
 //
-// The decision this file makes is which extensions vitest can walk a module graph back from, and
-// what to print about it. Everything the decision shares with `josh lint:related` — reading the
-// change, dropping what the tree no longer holds, and the two fallbacks — is
-// `changed-file-scope.ts`, so the two commands cannot drift apart about what "changed" means.
+// Everything the decision shares with `josh lint:related` — the fallback line, the file listing and
+// the unreadable-change reason — is `changed-file-scope.ts`, so the two commands cannot drift apart
+// about what they print.
+
+// The third answer only this command has: the change is known to reach no test, so nothing runs.
+// `files` holds the changed files that settled it, for the line that says why.
+interface NoTestScope {
+	mode: 'none'
+	files: ReadonlyArray<string>
+	reason: string
+}
 
-type RelatedScope = ChangedFileScope
+type RelatedScope = ChangedFileScope | NoTestScope
 
-// The extensions vitest can walk a module graph back from. A changed `.md`, `.yaml` or `.json` is
-// dropped rather than passed through: `vitest related` would match no test file for it, and a run
-// narrowed to nothing at all is the one outcome this module exists to prevent.
+// The extensions vitest can walk a module graph back from. Every other changed file is resolved
+// through the test-read map instead.
 const RELATABLE_EXTENSIONS: ReadonlySet<string> = new Set([
 	'.ts',
 	'.tsx',
@@ -38,8 +49,24 @@ const RELATABLE_EXTENSIONS: ReadonlySet<string> = new Set([
 	'.svelte',
 ])
 
+const { WHOLE_SUITE_FILES } = whole_suite_files
 const { UNREADABLE_REASON } = changed_file_scope
-const NOTHING_RELATABLE_REASON = 'no changed file is one a test can import'
+const NOTHING_RELATABLE_REASON = 'no changed file is one a test can import or read'
+const NO_MAP_REASON = 'no test-read map covers the changed non-code file'
+const UNMOVED_REASON = 'nothing moved since its last green run on this checkout'
+const WHOLE_SUITE_SUFFIX = 'affects every test'
+const UNRECORDED_SUFFIX = 'is read by no recorded test'
+
+// The stable kind each full-suite reason falls under, so the gate ledger counts the fallbacks by why
+// rather than by the file a reason names (joshuafolkken/kit#4397).
+const FALLBACK_KINDS: ReadonlyArray<{ kind: string; reason: string }> = [
+	{ kind: 'unreadable', reason: UNREADABLE_REASON },
+	{ kind: 'nothing-relatable', reason: NOTHING_RELATABLE_REASON },
+	{ kind: 'no-map', reason: NO_MAP_REASON },
+	{ kind: 'whole-suite-file', reason: WHOLE_SUITE_SUFFIX },
+	{ kind: 'unrecorded-file', reason: UNRECORDED_SUFFIX },
+]
+const OTHER_FALLBACK = 'other'
 
 // The command this narrowing belongs to, defined once: the guard prints it when it skips, and the
 // line below prints it in front of every decision.
@@ -47,42 +74,197 @@ const COMMAND_NAME = 'test:related'
 const COMMAND_LABEL = `josh ${COMMAND_NAME}`
 const { LISTED_FILE_LIMIT } = changed_file_scope
 
-const VOCABULARY: ScopeVocabulary = {
+const VOCABULARY = {
 	label: COMMAND_LABEL,
 	fallback_suffix: 'running the full unit suite instead',
 	narrowed_suffix: 'running only the tests related to them',
 }
 
+const NONE_SUFFIX = 'running no tests'
+
 const RUN_FLAG = '--run'
 const RELATED_SUBCOMMAND = 'related'
 const RUN_SUBCOMMAND = 'run'
 
+// Bundled so the CLI and the tests hand the decision the same five facts.
+interface ScopeRequest {
+	root: string
+	// Repository-root-relative paths, or `undefined` when the change could not be read.
+	changed: ReadonlyArray<string> | undefined
+	map: ReadMap | undefined
+	// The changed non-code files the map's tree held, and that did not differ from it when the map
+	// was recorded — the ones whose having no reader in the map means no test reads them.
+	recorded: ReadonlySet<string>
+	is_present: (file_path: string) => boolean
+	// The part of `changed` that joined only because it differs from the map's tree — which another
+	// lane's branch records — not because this change moved it. A non-code file of it still adds the
+	// tests reading it, a source file only through `naming_moved`, but neither ever sends the run to
+	// the whole suite: this tree verified it already, or main's CI did (joshuafolkken/kit#4527).
+	since_map?: ReadonlyArray<string>
+	// The source files of `since_map` that name a file this change moved — with its test files, the
+	// only ones of that part handed to vitest (joshuafolkken/kit#4532). See `is_code_input`.
+	naming_moved?: ReadonlySet<string>
+}
+
+// What the decision narrows to: the files to hand vitest, and the changed files known to reach no
+// test.
+interface Selection {
+	files: ReadonlyArray<string>
+	unread: ReadonlyArray<string>
+}
+
+// Either the selection the changed non-code files resolve to, or why they cannot be resolved — with
+// the repository-root-relative files that sent the run to the whole suite, where a file did.
+type MapResolution = Selection | { reason: string; triggers?: ReadonlyArray<string> }
+
 function is_relatable(file_path: string): boolean {
 	return RELATABLE_EXTENSIONS.has(path.extname(file_path))
 }
 
-// The three inputs that make the shared narrowing this command's, handed over as one value so the
-// CLI and the two functions below cannot disagree about any of them.
-function scope_inputs(is_present: (file_path: string) => boolean): ScopeInputs {
-	return { is_present, is_selectable: is_relatable, nothing_reason: NOTHING_RELATABLE_REASON }
+function is_moved(request: ScopeRequest, file: string): boolean {
+	return request.since_map?.includes(file) !== true
+}
+
+// **A source file only the map's tree differs by — another lane's change, or main's since — is handed
+// to vitest only when it names a file this change moved** (joshuafolkken/kit#4532). Leaving the rest
+// out is safe: an import of a moved module is reached from that module itself, since `vitest related`
+// walks every test file's graph rather than the map's; the one read neither the graph nor the map sees
+// is a file-system read added since the map's tree, and such a read names the file it reads. A test
+// file of that part always joins: the map holds no entry for it, it may reach a moved file through a
+// helper's read rather than its own, and it runs only itself. A read whose path is assembled from
+// fragments or listed from a directory is missed here and caught by CI's whole suite before the merge,
+// as a child process's read is.
+function is_code_input(request: ScopeRequest, file: string): boolean {
+	if (!is_relatable(file)) return false
+	if (is_moved(request, file) || test_declared_logic.is_test_file(file)) return true
+
+	return request.naming_moved?.has(file) === true
+}
+
+// A full-suite scope's `files` are the changed files that sent it there (joshuafolkken/kit#4510), as a
+// `none` scope's are the ones that settled it; the printed line still names only the first.
+function all_scope(reason: string, triggers: ReadonlyArray<string> = [], root = ''): RelatedScope {
+	return { mode: 'all', files: triggers.map((file) => path.join(root, file)), reason }
+}
+
+// A file no recorded test read narrows only when the recorded tree held it, or held its directory and
+// no recorded test read inside that: any other file added since is one the recorder never saw, so its
+// having no reader says nothing.
+function resolve_through_map(others: ReadonlyArray<string>, request: ScopeRequest): MapResolution {
+	const { map, recorded } = request
+
+	if (others.length === 0) return { files: [], unread: [] }
+	if (map === undefined) return { reason: `${NO_MAP_REASON} ${String(others[0])}` }
+
+	const unread = others.filter((file) => test_read_map.readers_of(map, file).length === 0)
+	const unknown = unread.filter(
+		(file) =>
+			is_moved(request, file) &&
+			!recorded.has(file) &&
+			!test_read_map.in_unread_directory(map, file),
+	)
+
+	if (unknown.length > 0) {
+		return { reason: `${String(unknown[0])} ${UNRECORDED_SUFFIX}`, triggers: unknown }
+	}
+
+	return { files: others.flatMap((file) => test_read_map.readers_of(map, file)), unread }
+}
+
+// A changed module is also data to a test that reads it through `fs` rather than importing it, and
+// `vitest related` cannot see that read. Unlike a non-code file, a module the map does not hold
+// still narrows — through the module graph alone.
+function code_readers(code: ReadonlyArray<string>, map: ReadMap | undefined): Array<string> {
+	if (map === undefined) return []
+
+	return code.flatMap((file) => test_read_map.readers_of(map, file))
+}
+
+function none_scope(unread: ReadonlyArray<string>, root: string): NoTestScope {
+	const files = unread.map((file) => path.join(root, file))
+
+	return { mode: 'none', files, reason: `${String(files.length)} changed file(s) no test reads` }
 }
 
-function select_related_files(
-	paths: ReadonlyArray<string>,
-	is_present: (file_path: string) => boolean,
-): Array<string> {
-	return changed_file_scope.select_files(paths, scope_inputs(is_present))
+// Nothing to select is "no test" only when something settled it; an empty or vanished selection
+// still runs the whole suite.
+function narrowed_scope(selection: Selection, request: ScopeRequest): RelatedScope {
+	if (selection.files.length === 0 && selection.unread.length > 0) {
+		return none_scope(selection.unread, request.root)
+	}
+
+	const present = [...new Set(selection.files)]
+		.map((file) => path.join(request.root, file))
+		.filter((file) => request.is_present(file))
+
+	if (present.length === 0) return all_scope(NOTHING_RELATABLE_REASON)
+
+	return { mode: 'related', files: present, reason: `${String(present.length)} related file(s)` }
 }
 
-function resolve_scope(
-	paths: ReadonlyArray<string> | undefined,
-	is_present: (file_path: string) => boolean,
-): RelatedScope {
-	return changed_file_scope.resolve_scope(paths, scope_inputs(is_present))
+// `undefined` and `[]` are deliberately different inputs. The first says the change could not be
+// read; the second says it was read and held nothing to relate.
+function resolve_scope(request: ScopeRequest): RelatedScope {
+	const { changed, root } = request
+
+	if (changed === undefined) return all_scope(UNREADABLE_REASON)
+
+	const whole = changed.filter((file) => WHOLE_SUITE_FILES.has(file) && is_moved(request, file))
+
+	if (whole.length > 0) return all_scope(`${String(whole[0])} ${WHOLE_SUITE_SUFFIX}`, whole, root)
+
+	const code = changed.filter((file) => is_code_input(request, file))
+	const resolution = resolve_through_map(
+		changed.filter((file) => !is_relatable(file)),
+		request,
+	)
+
+	if ('reason' in resolution) return all_scope(resolution.reason, resolution.triggers, root)
+
+	const files = [...code, ...code_readers(code, request.map), ...resolution.files]
+
+	return narrowed_scope({ files, unread: resolution.unread }, request)
 }
 
 function describe_scope(scope: RelatedScope, root: string): string {
-	return changed_file_scope.describe_scope(scope, root, VOCABULARY)
+	if (scope.mode !== 'none') return changed_file_scope.describe_scope(scope, root, VOCABULARY)
+
+	const listing = changed_file_scope.format_file_list(scope.files, root)
+
+	return `${COMMAND_LABEL}: ${scope.reason} — ${NONE_SUFFIX}.\n${listing}`
+}
+
+function reason_kind(reason: string): string {
+	return FALLBACK_KINDS.find((entry) => reason.includes(entry.reason))?.kind ?? OTHER_FALLBACK
+}
+
+// The kind of full-suite fallback a run's output names, read off the line `describe_scope` printed, or
+// `undefined` when the run narrowed or ran nothing.
+function fallback_kind(output: string): string | undefined {
+	const prefix = `${COMMAND_LABEL}: `
+	const suffix = ` — ${VOCABULARY.fallback_suffix}.`
+	const line = output
+		.split('\n')
+		.map((candidate) => candidate.trim())
+		.find((candidate) => candidate.startsWith(prefix) && candidate.endsWith(suffix))
+
+	if (line === undefined) return undefined
+
+	return reason_kind(line.slice(prefix.length, -suffix.length))
+}
+
+// The stable name a scope is recorded under: its mode when it narrowed or ran nothing, else the kind of
+// full-suite fallback its reason falls under (joshuafolkken/kit#4465).
+function scope_kind(scope: RelatedScope): string {
+	return scope.mode === 'all' ? reason_kind(scope.reason) : scope.mode
+}
+
+// Whether a run's output is the since-green no-op — nothing moved, so no test ran — read off the line
+// `describe_scope` printed, so the gate ledger never times it as a unit run (joshuafolkken/kit#4457).
+function is_unmoved(output: string): boolean {
+	const line = `${COMMAND_LABEL}: ${UNMOVED_REASON} — ${NONE_SUFFIX}.`
+
+	return output.split('\n').some((candidate) => candidate.trim() === line)
 }
 
 // `--run` is what keeps `vitest related` out of watch mode; the `run` sub-command already implies it
@@ -91,7 +273,7 @@ function vitest_arguments(
 	scope: RelatedScope,
 	extra_flags: ReadonlyArray<string> = [],
 ): ReadonlyArray<string> {
-	if (scope.mode === 'all') return [RUN_SUBCOMMAND, ...extra_flags]
+	if (scope.mode !== 'related') return [RUN_SUBCOMMAND, ...extra_flags]
 
 	return [RELATED_SUBCOMMAND, ...scope.files, RUN_FLAG, ...extra_flags]
 }
@@ -101,14 +283,18 @@ const related_scope = {
 	COMMAND_NAME,
 	LISTED_FILE_LIMIT,
 	NOTHING_RELATABLE_REASON,
+	NO_MAP_REASON,
+	UNMOVED_REASON,
 	UNREADABLE_REASON,
 	describe_scope,
+	fallback_kind,
 	is_relatable,
+	is_unmoved,
 	resolve_scope,
-	scope_inputs,
-	select_related_files,
+	scope_kind,
 	vitest_arguments,
 }
 
 export type { ScopeMode } from '#scripts/git/changed-file-scope'
+export type { RelatedScope, ScopeRequest }
 export { related_scope }