@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/split/split-resolution.ts

@@ -0,0 +1,107 @@
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { SPLIT_ROUTE_LABEL } from '#scripts/issue/issue-labels'
+import { issue_read } from '#scripts/issue/issue-read'
+import { session_cite } from '#scripts/issue/session-cite'
+import {
+	lane_ledger,
+	type LedgerEntry,
+	type SplitFiledEntry,
+	type SplitNoticeEntry,
+} from '#scripts/lane/lane-ledger'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { split_assess } from './split-assess'
+
+// **What answers a split notice** (joshuafolkken/kit#4695). Of the lanes the notice reached, none split
+// and none recorded why it stayed one Issue (joshuafolkken/kit#4676): the notice asked, and nothing
+// checked. The pre-gate `josh run:cut` now does. A noticed Issue passes once it has either answer:
+//
+// - **a split child** — a `josh issue:file --route split` filed from its lane, recorded in the lane
+//   ledger as the filing lands;
+// - **a reason** — a trusted Issue comment carrying the filing's own reason line
+//   (`split_assess.REASON_PREFIX`), so one declaration reads the same at filing and before the gate.
+
+const { REASON_PREFIX } = split_assess
+const NOTICE_SECTION = `split-assessment.md → "${split_assess.NOTICE_SECTION}"`
+const UNREAD_NOTE = 'Its comments could not be read, so no recorded reason was found. '
+
+function is_notice(entry: LedgerEntry): entry is SplitNoticeEntry {
+	return entry.kind === lane_ledger.KIND.SPLIT_NOTICE
+}
+
+function is_split_child(entry: LedgerEntry): entry is SplitFiledEntry {
+	return entry.kind === lane_ledger.KIND.SPLIT_FILED
+}
+
+// The ledger's split notices, oldest first — `josh lane:stats` counts the lanes they reached.
+function notices(entries: ReadonlyArray<LedgerEntry>): ReadonlyArray<SplitNoticeEntry> {
+	return entries.filter((entry) => is_notice(entry))
+}
+
+// The Issues whose lane filed a split child.
+function split_issues(entries: ReadonlyArray<LedgerEntry>): ReadonlySet<number> {
+	return new Set(entries.filter((entry) => is_split_child(entry)).map((entry) => entry.issue))
+}
+
+function is_reason_line(line: string): boolean {
+	const text = line.trim()
+
+	return text.startsWith(REASON_PREFIX) && text !== REASON_PREFIX
+}
+
+function has_reason(bodies: ReadonlyArray<string>): boolean {
+	return bodies.some((body) => body.split('\n').some((line) => is_reason_line(line)))
+}
+
+// The trusted comments' bodies, or `undefined` when the listing could not be read.
+async function trusted_comments(issue: number): Promise<ReadonlyArray<string> | undefined> {
+	const json = await git_gh_issue_read.issue_list_comments(String(issue))
+	const comments = await issue_read.parse_comments(json)
+
+	return comments === undefined ? undefined : issue_read.trusted_bodies(comments)
+}
+
+function refusal_text(notice: SplitNoticeEntry, bodies: ReadonlyArray<string> | undefined): string {
+	const counted = `${String(notice.files)} file(s), ${String(notice.lines)} line(s), tests excluded`
+	const unread = bodies === undefined ? UNREAD_NOTE : ''
+	const answers = `post an Issue comment with the line \`${REASON_PREFIX} <理由>\`, or file the rest with \`pnpm josh issue:file --route split\``
+
+	return `${session_cite.issue(notice.issue)} got the split notice (${counted}) and has neither a recorded reason nor a split child. ${unread}Either ${answers}, then run \`pnpm josh run:cut ${String(notice.issue)}\` again — ${NOTICE_SECTION}`
+}
+
+// The refusal for a noticed Issue that has no answer yet, else `undefined`. The ledger is read first,
+// so an Issue the notice never reached costs no GitHub read.
+async function refusal(
+	issue: number,
+	entries: ReadonlyArray<LedgerEntry>,
+): Promise<string | undefined> {
+	const notice = notices(entries).findLast((entry) => entry.issue === issue)
+
+	if (notice === undefined || split_issues(entries).has(issue)) return undefined
+	const bodies = await trusted_comments(issue)
+
+	return bodies !== undefined && has_reason(bodies) ? undefined : refusal_text(notice, bodies)
+}
+
+// The refusal against this repository's lane ledger; outside a repository there is none to read.
+async function ledger_refusal(issue: number): Promise<string | undefined> {
+	const ledger = await lane_ledger.target()
+
+	return ledger === undefined ? undefined : await refusal(issue, lane_ledger.read_entries(ledger))
+}
+
+interface Filing {
+	route: string | undefined
+	found_during: string | undefined
+	child: string
+}
+
+// What `josh issue:file` just filed: a split child is recorded against the lane it was found in. Any
+// other route, and a filing found in no lane, record nothing.
+async function record_child({ route, found_during, child }: Filing): Promise<void> {
+	if (route !== SPLIT_ROUTE_LABEL || found_during === undefined) return
+	await lane_ledger_write.record_split_filed({ issue: Number(found_during), child })
+}
+
+const split_resolution = { ledger_refusal, notices, record_child, refusal, split_issues }
+
+export { split_resolution }

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