@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/test/direct-importers.ts

@@ -0,0 +1,185 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { test_declared_logic } from './test-declared-logic'
+import { whole_suite_files } from './whole-suite-files'
+
+// **The test files that import a module directly, read off their text** (joshuafolkken/kit#5122). A
+// file every test imports (`whole_suite_files.EVERY_TEST_IMPORTS`) sends `vitest related` to the whole
+// suite, so `josh test:related` and the `josh test:pinned` probe hand vitest the test files importing it
+// directly instead. The whole suite still runs once, in the gate's `test:unit` and in every CI shard.
+//
+// The same reading decides which heavy test files a scoped run keeps (`related-heavy-tests.ts`).
+
+const PACKAGE_FILE = 'package.json'
+const WILDCARD = '*'
+const CURRENT_DIRECTORY_PREFIX = './'
+const NUL = '\0'
+
+// The module specifiers a source names in a static or dynamic import, an export-from or a `vi.mock`.
+const SPECIFIER_PATTERN = /(?:\bfrom\s+|\bimport\s*\(\s*|\bimport\s+|\bmock\(\s*)["']([^"']+)["']/gu
+
+type ImportMap = Readonly<Record<string, string>>
+
+interface SourceReader {
+	imports: ImportMap
+	read_source: (file: string) => string | undefined
+}
+
+// Repository-relative, `/`-separated and without its extension — the one key a specifier and a changed
+// file are compared by, since an import names `./thing`, `./thing.ts` or `./thing.js` alike.
+function module_key(file: string): string {
+	const posix = file.split(path.sep).join(path.posix.sep)
+
+	return posix.slice(0, posix.length - path.posix.extname(posix).length)
+}
+
+function specifiers_of(source: string): Array<string> {
+	return [...source.matchAll(SPECIFIER_PATTERN)].flatMap((match) => match.slice(1))
+}
+
+function alias_target(specifier: string, imports: ImportMap): string | undefined {
+	const exact = imports[specifier]
+
+	if (exact !== undefined) return exact
+
+	const key = Object.keys(imports).find(
+		(pattern) => pattern.endsWith(WILDCARD) && specifier.startsWith(pattern.slice(0, -1)),
+	)
+
+	if (key === undefined) return undefined
+
+	return imports[key]?.split(WILDCARD).join(specifier.slice(key.length - 1))
+}
+
+function relative_target(specifier: string, from: string): string {
+	return path.posix.join(path.posix.dirname(from), specifier)
+}
+
+// The repository-relative module key a specifier names, or `undefined` for a package import.
+function resolve_specifier(
+	specifier: string,
+	from: string,
+	imports: ImportMap,
+): string | undefined {
+	if (specifier.startsWith('.')) return module_key(relative_target(specifier, from))
+
+	const target = alias_target(specifier, imports)
+
+	if (target === undefined) return undefined
+
+	return module_key(path.posix.normalize(target.replace(CURRENT_DIRECTORY_PREFIX, '')))
+}
+
+// Whether `source`, the text of `from`, imports one of the `scoped` module keys directly.
+function names_any(
+	source: string,
+	from: string,
+	scoped: ReadonlySet<string>,
+	imports: ImportMap,
+): boolean {
+	return specifiers_of(source).some((specifier) => {
+		const resolved = resolve_specifier(specifier, from, imports)
+
+		return resolved !== undefined && scoped.has(resolved)
+	})
+}
+
+function read_imports(root: string): ImportMap {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path.join(root, PACKAGE_FILE), 'utf8'))
+		const imports: unknown = Reflect.get(new Object(parsed), 'imports')
+
+		if (typeof imports !== 'object' || imports === null) return {}
+
+		// A conditional entry (`{ "node": … }`) names no single file, so it resolves nothing.
+		return Object.fromEntries(
+			Object.entries(imports).filter(
+				(entry): entry is [string, string] => typeof entry[1] === 'string',
+			),
+		)
+	} catch {
+		return {}
+	}
+}
+
+function read_source_at(root: string, file: string): string | undefined {
+	try {
+		return readFileSync(path.join(root, file), 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function source_reader(root: string): SourceReader {
+	return { imports: read_imports(root), read_source: (file) => read_source_at(root, file) }
+}
+
+// The test files the work tree at `root` holds, tracked or not but not ignored, repository-relative.
+async function test_files(root: string): Promise<Array<string>> {
+	const listed = await git_spawn.read(['-C', root, 'ls-files', '-coz', '--exclude-standard'])
+
+	return listed.split(NUL).filter((file) => test_declared_logic.is_test_file(file))
+}
+
+// The test files of `tests` importing `file` directly; an unreadable one imports nothing.
+function importers_among(
+	file: string,
+	tests: ReadonlyArray<string>,
+	reader: SourceReader,
+): Array<string> {
+	const scoped = new Set([module_key(file)])
+
+	return tests.filter((test) => {
+		const source = reader.read_source(test)
+
+		return source !== undefined && names_any(source, test, scoped, reader.imports)
+	})
+}
+
+function every_test_imports_of(files: ReadonlyArray<string>): Array<string> {
+	return files.filter((file) => whole_suite_files.EVERY_TEST_IMPORTS.has(path.normalize(file)))
+}
+
+// Whether a command argument, relative to the working directory or absolute, is a file every test imports.
+function is_every_test_import(root: string, argument: string): boolean {
+	return whole_suite_files.EVERY_TEST_IMPORTS.has(path.relative(root, path.resolve(argument)))
+}
+
+// For each of `files`, the test files in the work tree at `root` importing it directly; a file no test
+// imports directly maps to none.
+async function importers_of(
+	root: string,
+	files: ReadonlyArray<string>,
+): Promise<Map<string, Array<string>>> {
+	if (files.length === 0) return new Map()
+
+	const tests = await test_files(root)
+	const reader = source_reader(root)
+
+	return new Map(files.map((file) => [file, importers_among(file, tests, reader)]))
+}
+
+// `importers_of` for the `files` every test imports; any other file is left out, for vitest to walk
+// its graph.
+async function every_test_importers(
+	root: string,
+	files: ReadonlyArray<string>,
+): Promise<Map<string, Array<string>>> {
+	return await importers_of(root, every_test_imports_of(files))
+}
+
+const direct_importers = {
+	every_test_importers,
+	every_test_imports_of,
+	importers_of,
+	is_every_test_import,
+	module_key,
+	names_any,
+	resolve_specifier,
+	source_reader,
+	specifiers_of,
+}
+
+export type { ImportMap, SourceReader }
+export { direct_importers }

package/scripts/test/pure-files-entries.ts

@@ -0,0 +1,83 @@
+import path from 'node:path'
+import { git_command } from '#scripts/git/git-command'
+import { file_reader } from '#scripts/lib/read-file'
+
+// **`tools/test/pure-files.ts` is a whole-suite file only for what is not its entries**
+// (joshuafolkken/kit#5001). The vitest config imports it, so `vitest related` widens to every test on
+// it, but an entry added, removed or rewritten moves only that test file between the pure and the
+// isolated project. A change made of entry lines alone therefore reaches the moved entries and the two
+// tests that hold the list to the classifier; any other line — an import, the export — still runs the
+// whole suite.
+
+const PURE_FILES_PATH = path.join('tools', 'test', 'pure-files.ts')
+const LIST_TESTS: ReadonlyArray<string> = [
+	path.join('tools', 'test', 'pure-files.test.ts'),
+	path.join('tools', 'test', 'classify-isolation.test.ts'),
+]
+const ENTRY_LINE = /^\t'(?<entry>[^']+)',$/u
+
+function entry_of(line: string): string | undefined {
+	return ENTRY_LINE.exec(line)?.groups?.['entry']
+}
+
+function lines_of(text: string): Array<string> {
+	return text.trimEnd().split('\n')
+}
+
+function frame_of(text: string): string {
+	return lines_of(text)
+		.filter((line) => entry_of(line) === undefined)
+		.join('\n')
+}
+
+function entries_of(text: string): Set<string> {
+	return new Set(lines_of(text).flatMap((line) => entry_of(line) ?? []))
+}
+
+function missing_from(entries: ReadonlySet<string>, other: ReadonlySet<string>): Array<string> {
+	return [...entries].filter((entry) => !other.has(entry))
+}
+
+// The entries one text holds and the other does not, or `undefined` when anything but entry lines
+// differs — the answer that keeps the whole suite.
+function moved_entries(before: string, after: string): ReadonlyArray<string> | undefined {
+	if (frame_of(before) !== frame_of(after)) return undefined
+
+	const was = entries_of(before)
+	const is = entries_of(after)
+
+	return [...missing_from(is, was), ...missing_from(was, is)]
+}
+
+// The test files an entries-only change reaches, the list's own tests first.
+function tests_of(entries: ReadonlyArray<string>): ReadonlyArray<string> {
+	return [...LIST_TESTS, ...entries]
+}
+
+async function base_text(): Promise<string | undefined> {
+	try {
+		return await git_command.show_file(`${await git_command.change_base()}:${PURE_FILES_PATH}`)
+	} catch {
+		return undefined
+	}
+}
+
+// The entries this branch moved in the list against its change base, or `undefined` when the list did
+// not change, changed beyond its entries, or either side cannot be read.
+async function read_moved(
+	root: string,
+	changed: ReadonlyArray<string> | undefined,
+): Promise<ReadonlyArray<string> | undefined> {
+	if (changed?.includes(PURE_FILES_PATH) !== true) return undefined
+
+	const before = await base_text()
+	const after = file_reader.read_if_readable(path.join(root, PURE_FILES_PATH))
+
+	if (before === undefined || after === undefined) return undefined
+
+	return moved_entries(before, after)
+}
+
+const pure_files_entries = { PURE_FILES_PATH, moved_entries, read_moved, tests_of }
+
+export { pure_files_entries }

package/scripts/test/related-heavy-tests.ts

@@ -0,0 +1,81 @@
+import path from 'node:path'
+import { direct_importers, type SourceReader } from './direct-importers'
+import type { RelatedScope } from './test-related-scope'
+import { unit_durations, type Durations } from './unit-durations'
+import { vitest_cli_excludes } from './vitest-cli-excludes'
+
+// **A scoped run leaves out the heavy test files a change reaches only indirectly**
+// (joshuafolkken/kit#5105). A hub module's change reaches the integration tests importing it through
+// the shared harnesses, and a scoped run's wall clock is bounded below by its longest file — over
+// `HEAVY_TEST_MS` each — whatever else it narrows. A heavy file still runs when this change moved it,
+// the module it is named for, or a file it imports directly, so the test written for a module is never
+// left out with it, even when it reaches that module through a harness.
+//
+// "Heavy" is read off the CI shards' duration record (`unit-durations.json`), never a named list, so
+// a file that slows down or speeds up moves in or out on the record's next refresh. The whole-suite
+// fallback and every CI shard carry no exclusion, so a heavy file left out here still runs before the
+// merge.
+
+const HEAVY_TEST_MS = 10_000
+const { EXCLUDE_FLAG } = vitest_cli_excludes
+// The suffix a test file's module key carries past the module it is named for.
+const TEST_SUFFIX_PATTERN = /(?:\.integration)?\.test$/u
+const { module_key } = direct_importers
+
+interface HeavyReader extends SourceReader {
+	durations: Durations
+}
+
+function heavy_tests(durations: Durations): Array<string> {
+	return Object.keys(durations).filter((file) => (durations[file] ?? 0) > HEAVY_TEST_MS)
+}
+
+function imports_directly(file: string, scoped: ReadonlySet<string>, reader: HeavyReader): boolean {
+	const source = reader.read_source(file)
+
+	if (source === undefined) return true
+
+	return direct_importers.names_any(source, file, scoped, reader.imports)
+}
+
+function is_kept(file: string, scoped: ReadonlySet<string>, reader: HeavyReader): boolean {
+	const key = module_key(file)
+
+	if (scoped.has(key) || scoped.has(key.replace(TEST_SUFFIX_PATTERN, ''))) return true
+
+	return imports_directly(file, scoped, reader)
+}
+
+// The heavy files to leave out of a scoped run: every one this scope neither holds, names nor imports from.
+function excluded_tests(scoped_files: ReadonlyArray<string>, reader: HeavyReader): Array<string> {
+	const scoped = new Set(scoped_files.map((file) => module_key(file)))
+
+	return heavy_tests(reader.durations).filter((file) => !is_kept(file, scoped, reader))
+}
+
+function file_reader(root: string): HeavyReader {
+	return { ...direct_importers.source_reader(root), durations: unit_durations.read(root) }
+}
+
+// The `--exclude` flags a scope's vitest run carries: none unless it narrowed to related files.
+function exclude_flags(
+	scope: RelatedScope,
+	root: string,
+	reader: HeavyReader = file_reader(root),
+): Array<string> {
+	if (scope.mode !== 'related') return []
+
+	const scoped = scope.files.map((file) => path.relative(root, file))
+
+	return excluded_tests(scoped, reader).flatMap((file) => [EXCLUDE_FLAG, file])
+}
+
+const related_heavy_tests = {
+	EXCLUDE_FLAG,
+	HEAVY_TEST_MS,
+	exclude_flags,
+	heavy_tests,
+}
+
+export type { HeavyReader }
+export { related_heavy_tests }

package/scripts/test/test-declared-changed.ts

@@ -75,8 +75,8 @@ function restore_injection(previous: ReadonlyArray<string> | undefined): void {
 	injected.paths = previous
 }
 
-// The seam the `rule_delivery` call path needs. `is_untested_commit` reads the
-// tree at trigger time rather than from an argument, so a unit test driving `rule_delivery` cannot reach
+// The seam the `delivered_rules.delivery` call path needs. `is_untested_commit` reads the
+// tree at trigger time rather than from an argument, so a unit test driving `delivered_rules.delivery` cannot reach
 // `current_verdict`'s `paths` port from the outside. Running `body` inside `with_paths` fixes the read
 // to `paths` for its duration and restores it afterwards — the `PreToolUse` production path, which never
 // calls this, still reads the live tree.

package/scripts/test/test-declared.ts

@@ -27,7 +27,7 @@ const ARGV_OFFSET = 2
 const NO_DECLARATIONS =
 	'no Test: declarations parsed from stdin — pipe the Step 0 work summary in, e.g. `pnpm josh test:declared --match < summary.md`'
 
-// **An unknown flag is a refusal, not a default** — `scripts/time/time-cli.ts` states the same
+// **An unknown flag is a refusal, not a default** — `tools/time/time-cli.ts` states the same
 // convention. Ignoring `--foo` and re-printing the verdict is what sent a
 // reader off to read the source by hand, so a misspelled or retired flag stops here with the usage.
 const PARSE_ARGS_OPTIONS = {

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

@@ -4,7 +4,9 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { environment_flags } from '@joshuafolkken/kit/env'
 import { core_budget } from '#scripts/gate/core-budget'
+import { gate_tree } from '#scripts/gate/gate-tree'
 import { execa } from 'execa'
+import { test_e2e_stamp } from './test-e2e-stamp'
 
 const PNPM = 'pnpm'
 // `--workers`, `--workers=<n>` and Playwright's `-j` short form.
@@ -93,9 +95,30 @@ async function run_guarded_e2e(
 	return 0
 }
 
+// A filter (`--grep`, a file, `--project`) answers for part of the suite, so only a run whose every
+// argument is a worker count answers for the whole of it.
+function is_whole_suite(extra_arguments: ReadonlyArray<string>): boolean {
+	return extra_arguments.every((argument) => WORKER_FLAGS.test(argument))
+}
+
+// A green answer — a pass or a printed skip — is recorded against the tree it ran on, which is what a
+// stop before commit asks (`test-e2e-stamp.ts`). The tree is read before the run, so an edit made while
+// the suite ran leaves a record that matches nothing.
+async function run_and_record(
+	project_directory: string,
+	extra_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	const tree = await gate_tree.read_gate_tree()
+	const exit_code = await run_guarded_e2e(project_directory, extra_arguments)
+
+	if (exit_code === 0 && is_whole_suite(extra_arguments)) test_e2e_stamp.record(tree)
+
+	return exit_code
+}
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	const extra_arguments = process.argv.slice(ARGV_START)
-	const exit_code = await run_guarded_e2e(process.cwd(), extra_arguments)
+	const exit_code = await run_and_record(process.cwd(), extra_arguments)
 
 	process.exit(exit_code)
 }
@@ -104,6 +127,7 @@ const test_e2e_guard = {
 	resolve_guard_action,
 	is_playwright_installed,
 	has_e2e_tests,
+	is_whole_suite,
 	run_guarded_e2e,
 }
 

package/scripts/test/test-e2e-stamp.ts

@@ -0,0 +1,38 @@
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { review_brief } from '#scripts/review/review-brief'
+import { review_stamps } from '#scripts/review/review-stamps'
+
+// The record that `josh test:e2e` answered green on this exact tree (joshuafolkken/kit#4156). A stop
+// before commit — `halfrun`'s, `needs-human-review`'s — has no CI E2E job behind it, so the stop asks
+// this record instead of trusting that the run remembered to run the suite.
+//
+// **A printed skip is recorded too**: a project with no suite, or without `@playwright/test`, has
+// answered the question, and refusing its stop would make the record a requirement no such project
+// could meet. **Any edit after the run moves the tree**, so the record no longer matches — the same
+// reading the gate's own record takes (`gate-skip.ts`).
+
+// Swallowed: a record not written is the safe answer — the stop refuses and the run re-runs the suite.
+function record(tree: GateTree, target?: string): void {
+	try {
+		review_stamps.e2e_stamp.write(tree.files, target, tree.base)
+	} catch {
+		/* no record — the stop asks for the suite again */
+	}
+}
+
+// An unread base or an unreadable record answers no: nothing established, nothing concluded.
+function is_current(tree: GateTree, source?: string): boolean {
+	if (tree.base === undefined) return false
+
+	const stamp = review_brief.matching_stamp(review_stamps.e2e_stamp.read(source), tree.files)
+
+	return stamp?.base === tree.base
+}
+
+async function is_current_tree(): Promise<boolean> {
+	return is_current(await gate_tree.read_gate_tree())
+}
+
+const test_e2e_stamp = { is_current, is_current_tree, record }
+
+export { test_e2e_stamp }

package/scripts/test/test-no-base.ts

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { project_checks } from '#scripts/gate/project-checks'
+import { no_base_checkout } from '#scripts/git/no-base-checkout'
+import { test_related_claim } from './test-related-claim'
+import { related_scope } from './test-related-scope'
+import { test_unit_guard } from './test-unit-guard'
+
+// **The second pass of `josh test:related` for a change that touches how the base branch is
+// resolved** (joshuafolkken/kit#4710). A lane has a local `main`; CI's checkout has none, so a diff
+// against a bare `main` passes every local check and fails only in CI. The related tests of each such
+// file run again in `no-base-checkout.ts`'s checkout, which has none either.
+//
+// **A change that touches none of it runs nothing more** — no checkout, no vitest — so the gate takes
+// no longer for it. **Nor does a consumer project**: the checkout holds only what git tracks, and a
+// consumer's vitest config can read a generated, ignored file (`.svelte-kit/tsconfig.json`) it lacks.
+
+// The names a file that resolves the base, or reads a diff against it, carries — the modules'
+// own, and the bare default-branch name a caller could hand git.
+const BASE_NAMES: ReadonlyArray<string> = [
+	'change_base',
+	'default_branch',
+	'diff_main',
+	"'main'",
+	'"main"',
+]
+
+// Shared with `test-related.ts`'s own reading of which files name another: a file it cannot read
+// names nothing.
+function text_of(file_path: string): string {
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+function names_any(text: string, names: ReadonlyArray<string>): boolean {
+	return names.some((name) => text.includes(name))
+}
+
+function touches_base(root: string, file: string): boolean {
+	if (!related_scope.is_relatable(file)) return false
+
+	return names_any(text_of(path.join(root, file)), BASE_NAMES)
+}
+
+function touching(root: string, changed: ReadonlyArray<string>): Array<string> {
+	return changed.filter((file) => touches_base(root, file))
+}
+
+async function run_in_checkout(
+	root: string,
+	files: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+): Promise<number> {
+	const directory = await no_base_checkout.create(root)
+
+	try {
+		return await test_unit_guard.run_vitest_in(directory, ['related', ...files, '--run', ...flags])
+	} finally {
+		no_base_checkout.remove(directory)
+	}
+}
+
+async function run_if_touched(
+	root: string,
+	changed: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+): Promise<number> {
+	const files = project_checks.is_kit_repository(root) ? touching(root, changed) : []
+
+	if (files.length === 0) return 0
+
+	process.stdout.write(
+		`josh test:related: ${String(files.length)} changed file(s) touch the base branch's resolution — their related tests run again in a checkout with no local main, as CI's has none\n`,
+	)
+
+	// Its own claim, since the first pass released its own before this one starts.
+	return await test_related_claim.with_unit_claim(
+		files,
+		async () => await run_in_checkout(root, files, flags),
+	)
+}
+
+const test_no_base = { names_any, run_if_touched, text_of, touching }
+
+export { test_no_base }