@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/test/test-pinned-emit.ts

@@ -0,0 +1,49 @@
+import type { TypeScriptApi } from '#scripts/review/comment-ranges'
+import { test_pinned_functions } from './test-pinned-functions'
+import { test_pinned_logic, type Hunk } from './test-pinned-logic'
+import { test_pinned_rewire } from './test-pinned-rewire'
+
+// Which hunks `josh test:pinned` can probe at all (joshuafolkken/kit#4647). A hunk whose revert leaves
+// the emitted JavaScript as it was — a comment, a type, a blank line — changes nothing a test runs, so
+// no test can pin it, and listing it `unpinned` would stop every `josh run:review` that edited one.
+// Only a script file is compared: a Svelte component's markup is not TypeScript.
+
+function emitted(api: TypeScriptApi, file: string, content: string): string {
+	const compiler_options = { removeComments: true, target: api.ScriptTarget.ESNext }
+
+	return api.transpileModule(content, { compilerOptions: compiler_options, fileName: file })
+		.outputText
+}
+
+function changes_runtime(api: TypeScriptApi, content: string, hunk: Hunk): boolean {
+	if (!test_pinned_functions.is_script(hunk.file)) return true
+	const reverted = test_pinned_logic.revert(content, hunk)
+
+	return emitted(api, hunk.file, reverted) !== emitted(api, hunk.file, content)
+}
+
+interface RuntimeRead {
+	hunks: Array<Hunk>
+	rewired: number
+}
+
+// The hunks to probe, each beside its file's content: the ones whose revert changes the emitted code,
+// less the rewires (`test-pinned-rewire.ts`), which are counted.
+function probed_of(
+	api: TypeScriptApi,
+	hunks: ReadonlyArray<Hunk>,
+	contents: ReadonlyArray<string>,
+): RuntimeRead {
+	const runtime = hunks
+		.map((hunk, index) => ({ hunk, content: contents[index] ?? '' }))
+		.filter((read) => changes_runtime(api, read.content, read.hunk))
+	const probed = runtime.filter(
+		(read) => !test_pinned_rewire.is_rewire(api, read.content, read.hunk),
+	)
+
+	return { hunks: probed.map((read) => read.hunk), rewired: runtime.length - probed.length }
+}
+
+const test_pinned_emit = { changes_runtime, probed_of }
+
+export { test_pinned_emit }

package/scripts/test/test-pinned-functions.ts

@@ -0,0 +1,116 @@
+import type { TypeScriptApi } from '#scripts/review/comment-ranges'
+import type ts from 'typescript'
+import type { Hunk } from './test-pinned-logic'
+
+// The added-file half of `josh test:pinned` (joshuafolkken/kit#4647). Reverting an added file is a
+// missing module every importer fails on, so its functions are probed instead: each top-level function
+// — a `function` declaration, a `const` bound to a function, or a function member of a top-level object
+// literal (a namespace object) — becomes one hunk whose lines carry that function with its body
+// replaced by a throw. `test_pinned_logic.revert` puts those lines in, so a probe runs as a hunk does.
+//
+// Only a script file is parsed: a Svelte component's markup is not TypeScript, and its script block
+// holds no module-level function an importer calls by name.
+
+const STUB_BODY = "{ throw new Error('josh test:pinned') }"
+const SCRIPT_FILE = /\.[cm]?[jt]sx?$/u
+const LINE_BREAK = '\n'
+const DEFAULT_NAME = 'default'
+
+type FunctionValue = ts.ArrowFunction | ts.FunctionExpression
+
+interface FunctionSite {
+	name: string
+	extent: ts.Node
+	body: ts.Node
+}
+
+function is_script(file: string): boolean {
+	return SCRIPT_FILE.test(file)
+}
+
+function is_function_value(api: TypeScriptApi, node: ts.Node | undefined): node is FunctionValue {
+	if (node === undefined) return false
+
+	return api.isArrowFunction(node) || api.isFunctionExpression(node)
+}
+
+function member_site(
+	api: TypeScriptApi,
+	owner: string,
+	member: ts.ObjectLiteralElementLike,
+): Array<FunctionSite> {
+	if (api.isMethodDeclaration(member) && member.body !== undefined) {
+		return [{ name: `${owner}.${member.name.getText()}`, extent: member, body: member.body }]
+	}
+
+	if (!api.isPropertyAssignment(member) || !is_function_value(api, member.initializer)) return []
+
+	return [
+		{ name: `${owner}.${member.name.getText()}`, extent: member, body: member.initializer.body },
+	]
+}
+
+function declaration_sites(
+	api: TypeScriptApi,
+	declaration: ts.VariableDeclaration,
+): Array<FunctionSite> {
+	const { initializer } = declaration
+	const name = declaration.name.getText()
+
+	if (is_function_value(api, initializer)) {
+		return [{ name, extent: declaration, body: initializer.body }]
+	}
+
+	if (initializer === undefined || !api.isObjectLiteralExpression(initializer)) return []
+
+	return initializer.properties.flatMap((member) => member_site(api, name, member))
+}
+
+// An overload signature has no body to replace.
+function function_site(statement: ts.FunctionDeclaration): Array<FunctionSite> {
+	if (statement.body === undefined) return []
+
+	return [{ name: statement.name?.text ?? DEFAULT_NAME, extent: statement, body: statement.body }]
+}
+
+function statement_sites(api: TypeScriptApi, statement: ts.Statement): Array<FunctionSite> {
+	if (api.isFunctionDeclaration(statement)) return function_site(statement)
+	if (!api.isVariableStatement(statement)) return []
+
+	return statement.declarationList.declarations.flatMap((declaration) =>
+		declaration_sites(api, declaration),
+	)
+}
+
+// The whole lines the function spans, with its body swapped for the throw: the hunk replaces lines,
+// so a signature sharing a line with other code keeps that code.
+function stub_hunk(file: string, source: ts.SourceFile, site: FunctionSite): Hunk {
+	const start = site.extent.getStart(source)
+	const first = source.getLineAndCharacterOfPosition(start).line
+	const last = source.getLineAndCharacterOfPosition(site.extent.getEnd()).line
+	const offset = start - source.getLineAndCharacterOfPosition(start).character
+	const lines = source.text.slice(offset, source.getLineEndOfPosition(site.extent.getEnd()))
+	const before = lines.slice(0, site.body.getStart(source) - offset)
+	const stubbed = `${before}${STUB_BODY}${lines.slice(site.body.getEnd() - offset)}`
+
+	return {
+		file,
+		new_start: first + 1,
+		new_count: last - first + 1,
+		old_lines: stubbed.split(LINE_BREAK),
+		new_lines: lines.split(LINE_BREAK),
+		function_name: site.name,
+	}
+}
+
+function stub_hunks(api: TypeScriptApi, file: string, content: string): Array<Hunk> {
+	const source = api.createSourceFile(file, content, api.ScriptTarget.Latest, true)
+
+	return source.statements
+		.flatMap((statement) => statement_sites(api, statement))
+		.map((site) => stub_hunk(file, source, site))
+}
+
+const test_pinned_functions = { STUB_BODY, is_script, stub_hunks }
+
+export { test_pinned_functions }

package/scripts/test/test-pinned-ledger.ts

@@ -0,0 +1,80 @@
+import type { TestPinnedRecord } from '#scripts/lane/lane-ledger'
+import { lane_ledger_schema } from '#scripts/lane/lane-ledger-schema'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { lane_paths } from '#scripts/lane/lane-paths'
+import type { Hunk } from './test-pinned-logic'
+import type { RedProbe } from './test-red-logic'
+
+// One `test-pinned` ledger row per `josh test:pinned` run that probed (joshuafolkken/kit#5078): how
+// many hunks the verdict cache answered, and each probed hunk's test files and wall time, so
+// `josh lane:breakdown` can say what a long ship pre-detach spent its probe on.
+
+interface ProbeTime {
+	file: string
+	tests?: number | undefined
+	elapsed_ms: number
+}
+
+function time_of(hunk: Hunk, verdict: RedProbe, elapsed_ms: number): ProbeTime {
+	return { file: hunk.file, tests: verdict.ran, elapsed_ms }
+}
+
+// What started a run (joshuafolkken/kit#5262): `run:review`'s background check, the ship's pre-detach,
+// or a `josh test:pinned` typed by hand.
+type PinnedOrigin = NonNullable<TestPinnedRecord['origin']>
+
+const MANUAL_ORIGIN: PinnedOrigin = 'manual'
+const BACKGROUND_ORIGIN: PinnedOrigin = 'run-review'
+
+// A `--origin` value: none is `manual`, one not named above `undefined`.
+function origin_of(raw: string | undefined): PinnedOrigin | undefined {
+	if (raw === undefined) return MANUAL_ORIGIN
+	const parsed = lane_ledger_schema.pinned_origin_schema.safeParse(raw)
+
+	return parsed.success ? parsed.data : undefined
+}
+
+// The hunks a run did not probe: `held` the cache answered, `rewired` left out as a rewire; and what
+// started it, `manual` when unnamed.
+interface Skipped {
+	held: number
+	rewired: number
+	origin?: PinnedOrigin | undefined
+}
+
+async function record(
+	skipped: Skipped,
+	probes: ReadonlyArray<ProbeTime>,
+	elapsed_ms: number,
+): Promise<void> {
+	await lane_ledger_write.record_test_pinned({
+		issue: lane_paths.issue_here(),
+		held: skipped.held,
+		rewired: skipped.rewired,
+		probes: [...probes],
+		elapsed_ms,
+		origin: skipped.origin ?? MANUAL_ORIGIN,
+	})
+}
+
+// A background check stopped before its answer writes no row of its own, so its stop writes this one:
+// the wall time it ran, and nothing it probed. `origin` is its launcher: `run:review`'s check, or the
+// pre-detach's probe of the hunks past its stop (joshuafolkken/kit#5327).
+async function record_discarded(
+	elapsed_ms: number,
+	origin: PinnedOrigin = BACKGROUND_ORIGIN,
+): Promise<void> {
+	await lane_ledger_write.record_test_pinned({
+		issue: lane_paths.issue_here(),
+		held: 0,
+		probes: [],
+		elapsed_ms,
+		origin,
+		discarded: true,
+	})
+}
+
+const test_pinned_ledger = { BACKGROUND_ORIGIN, origin_of, record, record_discarded, time_of }
+
+export type { PinnedOrigin, ProbeTime }
+export { test_pinned_ledger }

package/scripts/test/test-pinned-logic.ts

@@ -0,0 +1,333 @@
+import { verification_tail, type KeptLog } from '#scripts/gate/verification-tail'
+import { test_declared_logic } from './test-declared-logic'
+import { test_pinned_stage, type Staged } from './test-pinned-stage'
+import type { RedProbe, RedVerdict } from './test-red-logic'
+import { related_scope } from './test-related-scope'
+
+// The pure half of `josh test:pinned` (joshuafolkken/kit#4516): read a `git diff -U0` into hunks, put
+// one hunk's old lines back into the changed file, and split the hunks at the run's cap. The run itself
+// is `test-pinned.ts`; an added file's hunks are its functions (`test-pinned-functions.ts`).
+
+const DEFAULT_MAX_HUNKS = 20
+const HEADER = /^@@ -\d+(?:,\d+)? \+(?<start>\d+)(?:,(?<count>\d+))? @@/u
+const FILE_HEADER = '+++ b/'
+const SECTION_HEADER = 'diff --git '
+const OLD_LINE = '-'
+const OLD_FILE_HEADER = '--- '
+const NEW_LINE = '+'
+const FILE_HEADER_MARK = '+++ '
+const OLD_FILE_PATH = '--- a/'
+const LINE_BREAK = '\n'
+const GREEN_REASON = 'reverting it left every related test green'
+const NO_TEST_REASON = 'no related test ran with it reverted'
+const STUB_GREEN_REASON = 'replacing its body with a throw left every related test green'
+const STUB_NO_TEST_REASON = 'no related test ran with its body replaced by a throw'
+const UNPARSED_REASON = 'an added file, and typescript is not installed to read its functions'
+const NO_RUNNER_REASON = 'vitest is not installed to run its related tests'
+const STOPPED_REASON = 'vitest stopped before any test ran with it reverted'
+const CUT_REASON = 'not probed: the run stopped at the first unpinned hunk'
+const STOPPED_VERDICT: RedVerdict = 'stopped'
+const SETTLED_VERDICTS: ReadonlySet<RedVerdict> = new Set<RedVerdict>(['red', STOPPED_VERDICT])
+
+interface Hunk {
+	file: string
+	// The first changed line of the working file; for a pure deletion, the line the removed ones sat after.
+	new_start: number
+	new_count: number
+	old_lines: Array<string>
+	// The working file's lines the hunk spans (`+` lines; an added file's probe, the function's): a revert
+	// never reads them, but an unpinned place's key does (`test-pinned-record.ts`), since two changes of one
+	// length share the rest.
+	new_lines?: Array<string>
+	// Set on an added file's probe (`test-pinned-functions.ts`): the function the old lines put back
+	// with its body replaced by a throw.
+	function_name?: string
+}
+
+interface HunkSplit {
+	checked: ReadonlyArray<Hunk>
+	unchecked: ReadonlyArray<Hunk>
+}
+
+// A reverted hunk nothing went red on: `is_green` when its related tests ran and passed, otherwise
+// vitest passed with no related test to run.
+interface UnpinnedHunk extends Hunk {
+	is_green: boolean
+}
+
+interface HunkOutcome {
+	unpinned: ReadonlyArray<UnpinnedHunk>
+	// Hunks whose revert stopped vitest before any test ran (joshuafolkken/kit#5043) — a config that
+	// imports the file could not load. No test was asked, so it is neither pinned nor unpinned.
+	stopped: ReadonlyArray<Hunk>
+	// Hunks a `--first-unpinned` run did not probe once one was unpinned (joshuafolkken/kit#5153): the
+	// run fails already, so the rest wait for the next run.
+	cut?: ReadonlyArray<Hunk>
+	// Whether every checked hunk had a verdict — false when a cache-only read found one the cache no
+	// longer holds (joshuafolkken/kit#5078).
+	is_held?: boolean
+	// How many fresh probes the direct importers decided or escalated (joshuafolkken/kit#5292).
+	staged?: Staged
+}
+
+interface PinnedReport extends HunkOutcome {
+	unchecked: ReadonlyArray<Hunk>
+	// Added files whose functions could not be read, so none of them was probed.
+	unparsed: ReadonlyArray<string>
+	max_hunks: number
+	// False when no Vitest is installed to run a probe, so every hunk is `unchecked` rather than run and
+	// read as a `no-test` unpinned one.
+	has_runner: boolean
+}
+
+interface UncheckedPlace {
+	place: string
+	why: string
+}
+
+// A report as printed (joshuafolkken/kit#5188): `text` is its lines above the counts line, each ending in
+// a newline; `counts` is absent for a check that could not run, and `log` where no full list was kept.
+interface ReportParts {
+	text: string
+	counts?: string | undefined
+	log?: KeptLog | undefined
+}
+
+interface DiffWalk {
+	file: string
+	hunks: Array<Hunk>
+}
+
+// A test file is never reverted, and only a file vitest can walk an import graph back from has related
+// tests to run.
+function is_target(file: string): boolean {
+	return !test_declared_logic.is_test_file(file) && related_scope.is_relatable(file)
+}
+
+// An omitted count is one line (`@@ -3 +3 @@`).
+function count_of(group: string | undefined): number {
+	return group === undefined ? 1 : Number(group)
+}
+
+function hunk_from(file: string, line: string): Hunk | undefined {
+	const groups = HEADER.exec(line)?.groups
+	if (groups === undefined) return undefined
+
+	return {
+		file,
+		new_start: Number(groups['start']),
+		new_count: count_of(groups['count']),
+		old_lines: [],
+		new_lines: [],
+	}
+}
+
+function is_old_line(line: string): boolean {
+	return line.startsWith(OLD_LINE) && !line.startsWith(OLD_FILE_HEADER)
+}
+
+function is_new_line(line: string): boolean {
+	return line.startsWith(NEW_LINE) && !line.startsWith(FILE_HEADER_MARK)
+}
+
+function record_line(hunk: Hunk | undefined, line: string): void {
+	if (hunk === undefined) return
+	if (is_old_line(line)) hunk.old_lines.push(line.slice(OLD_LINE.length))
+	else if (is_new_line(line)) hunk.new_lines?.push(line.slice(NEW_LINE.length))
+}
+
+// Each file section starts unnamed, so a `+++` line this does not read (a quoted path with a space)
+// leaves its hunks on no file rather than on the previous one. A deleted file (`+++ /dev/null`) keeps
+// the name its `--- a/` line gave it.
+function file_after(file: string, line: string): string {
+	if (line.startsWith(FILE_HEADER)) return line.slice(FILE_HEADER.length)
+	if (line.startsWith(OLD_FILE_PATH)) return line.slice(OLD_FILE_PATH.length)
+
+	return line.startsWith(SECTION_HEADER) ? '' : file
+}
+
+function step(walk: DiffWalk, line: string): void {
+	walk.file = file_after(walk.file, line)
+	const hunk = hunk_from(walk.file, line)
+
+	if (hunk === undefined) record_line(walk.hunks.at(-1), line)
+	else walk.hunks.push(hunk)
+}
+
+// One `-U0` diff (`a/` and `b/` prefixes) into every file's hunks, in diff order — also read by
+// `prose-stale-cli.ts` for the lines a diff removed and added.
+function all_hunks(diff: string): Array<Hunk> {
+	const walk: DiffWalk = { file: '', hunks: [] }
+
+	for (const line of diff.split(LINE_BREAK)) step(walk, line)
+
+	return walk.hunks
+}
+
+// The hunks a revert probes. A revert puts the old lines back over the working file's `new_count` lines
+// at `new_start`.
+function parse_hunks(diff: string): Array<Hunk> {
+	return all_hunks(diff).filter((hunk) => is_target(hunk.file))
+}
+
+// A pure deletion's `new_start` names the line before the gap, so the old lines go in after it.
+function start_index(hunk: Hunk): number {
+	return hunk.new_count === 0 ? hunk.new_start : hunk.new_start - 1
+}
+
+// The working file's content with this one hunk put back to the base's lines.
+function revert(content: string, hunk: Hunk): string {
+	const lines = content.split(LINE_BREAK)
+
+	lines.splice(start_index(hunk), hunk.new_count, ...hunk.old_lines)
+
+	return lines.join(LINE_BREAK)
+}
+
+function split(hunks: ReadonlyArray<Hunk>, max_hunks: number): HunkSplit {
+	return { checked: hunks.slice(0, max_hunks), unchecked: hunks.slice(max_hunks) }
+}
+
+// The probes, the ones whose file reaches the fewest tests first (joshuafolkken/kit#5153), so a run
+// that stops at its first unpinned hunk reaches it soonest; a file `reach` lacks counts as 0, and
+// equal counts keep their order.
+function by_reach<T extends { hunk: Hunk }>(
+	probes: ReadonlyArray<T>,
+	reach: ReadonlyMap<string, number>,
+): Array<T> {
+	function count(probe: T): number {
+		return reach.get(probe.hunk.file) ?? 0
+	}
+
+	return probes.toSorted((first, second) => count(first) - count(second))
+}
+
+// `green` and `no-test` leave a hunk unpinned: either way nothing went red when it was reverted.
+function is_unpinned(probe: RedProbe): boolean {
+	return !SETTLED_VERDICTS.has(probe.verdict)
+}
+
+// A hunk with no verdict yet is neither pinned nor unpinned.
+function unpinned_of(hunk: Hunk, probe: RedProbe | undefined): Array<UnpinnedHunk> {
+	if (probe === undefined || !is_unpinned(probe)) return []
+
+	return [{ ...hunk, is_green: probe.verdict === 'green' }]
+}
+
+function stopped_of(hunk: Hunk, probe: RedProbe | undefined): Array<Hunk> {
+	return probe?.verdict === STOPPED_VERDICT ? [hunk] : []
+}
+
+// Each checked hunk by its verdict, in the hunks' order: `red` pins it, `stopped` sets it aside, and
+// any other leaves it unpinned.
+function outcome(
+	hunks: ReadonlyArray<Hunk>,
+	verdicts: ReadonlyArray<RedProbe | undefined>,
+): HunkOutcome {
+	return {
+		unpinned: hunks.flatMap((hunk, index) => unpinned_of(hunk, verdicts[index])),
+		stopped: hunks.flatMap((hunk, index) => stopped_of(hunk, verdicts[index])),
+	}
+}
+
+function location(hunk: Hunk): string {
+	const line = `${hunk.file}:${String(Math.max(hunk.new_start, 1))}`
+
+	return hunk.function_name === undefined ? line : `${line} ${hunk.function_name}`
+}
+
+function reason(hunk: UnpinnedHunk): string {
+	if (hunk.function_name === undefined) return hunk.is_green ? GREEN_REASON : NO_TEST_REASON
+
+	return hunk.is_green ? STUB_GREEN_REASON : STUB_NO_TEST_REASON
+}
+
+function unchecked_reason(report: PinnedReport): string {
+	return report.has_runner ? `over the ${String(report.max_hunks)}-hunk cap` : NO_RUNNER_REASON
+}
+
+function unpinned_lines(report: PinnedReport): Array<string> {
+	return report.unpinned.map((hunk) => `unpinned ${location(hunk)} — ${reason(hunk)}`)
+}
+
+function place_of(hunk: Hunk, why: string): UncheckedPlace {
+	return { place: location(hunk), why }
+}
+
+// Every unchecked place with its reason, in the full list's order.
+function unchecked_places(report: PinnedReport): Array<UncheckedPlace> {
+	return [
+		...report.unchecked.map((hunk) => place_of(hunk, unchecked_reason(report))),
+		...report.stopped.map((hunk) => place_of(hunk, STOPPED_REASON)),
+		...(report.cut ?? []).map((hunk) => place_of(hunk, CUT_REASON)),
+		...report.unparsed.map((file) => ({ place: file, why: UNPARSED_REASON })),
+	]
+}
+
+// Whether the printed report folds any place, so the full list is worth keeping.
+function has_unchecked(report: PinnedReport): boolean {
+	return unchecked_places(report).length > 0
+}
+
+// One line per unpinned or unchecked place — the full list `josh test:pinned` keeps in its log.
+function format(report: PinnedReport): string {
+	const unchecked = unchecked_places(report).map((item) => `unchecked ${item.place} — ${item.why}`)
+
+	return [...unpinned_lines(report), ...unchecked].join(LINE_BREAK)
+}
+
+// The unchecked places folded to one line per reason (joshuafolkken/kit#5188): a cap's overflow listed
+// one line each pushed the unpinned places, and what to do about them, out of a `tail` window.
+function folded_unchecked(report: PinnedReport): Array<string> {
+	const counts = new Map<string, number>()
+
+	for (const { why } of unchecked_places(report)) counts.set(why, (counts.get(why) ?? 0) + 1)
+
+	return [...counts].map(([why, count]) => `unchecked ${String(count)} — ${why}`)
+}
+
+function counts_line(report: PinnedReport): string {
+	const unchecked = String(unchecked_places(report).length)
+
+	const staged = test_pinned_stage.counts_suffix(report.staged)
+
+	return `unpinned ${String(report.unpinned.length)} · unchecked ${unchecked}${staged}`
+}
+
+// The report's parts: each unpinned place and the folded unchecked lines, and the counts line.
+function report_parts(report: PinnedReport): ReportParts {
+	const lines = [...unpinned_lines(report), ...folded_unchecked(report)]
+
+	return { text: lines.map((line) => `${line}${LINE_BREAK}`).join(''), counts: counts_line(report) }
+}
+
+// What `josh test:pinned`, `josh run:review` and the ship's pre-detach print, in the verification-tail
+// shape (`verification-tail.ts`): the places, then `note` (what to do about them, each line ending in a
+// newline), then where the full list went, and the counts line last. Without a counts line — a check
+// that could not run — the text and the note alone.
+function report_text(parts: ReportParts, note = ''): string {
+	const failures = `${parts.text}${note}`
+	if (parts.counts === undefined) return failures
+
+	return verification_tail.format_tail({ failures, log: parts.log, verdict: parts.counts })
+}
+
+const test_pinned_logic = {
+	all_hunks,
+	DEFAULT_MAX_HUNKS,
+	by_reach,
+	format,
+	has_unchecked,
+	is_target,
+	is_unpinned,
+	location,
+	outcome,
+	parse_hunks,
+	report_parts,
+	report_text,
+	revert,
+	split,
+}
+
+export type { Hunk, HunkOutcome, PinnedReport, ReportParts, UnpinnedHunk }
+export { test_pinned_logic }