@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -2,9 +2,15 @@
 import { existsSync, globSync } from 'node:fs'
 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.
+const WORKER_FLAGS = /^(?:--workers(?:=|$)|-j)/u
 const FAIL_EXIT_CODE = 1
 const ARGV_START = 2
 const PLAYWRIGHT_PACKAGE = path.join('node_modules', '@playwright', 'test')
@@ -45,15 +51,36 @@ function has_e2e_tests(project_directory: string): boolean {
 	return matches.length > 0
 }
 
+// **A local run's worker count is the weight it reserved** (joshuafolkken/kit#3944). Playwright's own
+// default is half the cores, which no ledger entry stood for; CI keeps its config's count, and a
+// count the caller names wins.
+function playwright_arguments(extra_arguments: ReadonlyArray<string>): ReadonlyArray<string> {
+	const is_count_named = extra_arguments.some((argument) => WORKER_FLAGS.test(argument))
+
+	if (is_count_named || environment_flags.is_ci_enabled(process.env['CI'])) return extra_arguments
+
+	return [`--workers=${String(core_budget.CORE_WEIGHTS.e2e)}`, ...extra_arguments]
+}
+
 async function run_playwright(extra_arguments: ReadonlyArray<string>): Promise<number> {
-	const result = await execa(PNPM, ['exec', 'playwright', 'test', ...extra_arguments], {
-		stdio: 'inherit',
-		reject: false,
-	})
+	const result = await execa(
+		PNPM,
+		['exec', 'playwright', 'test', ...playwright_arguments(extra_arguments)],
+		{ stdio: 'inherit', reject: false },
+	)
 
 	return result.exitCode ?? FAIL_EXIT_CODE
 }
 
+// Only a run reserves: a skip starts nothing, and a claim there could wait out a full ledger for it.
+async function run_reserved_playwright(extra_arguments: ReadonlyArray<string>): Promise<number> {
+	return await core_budget.with_command_reservation(
+		core_budget.CORE_WEIGHTS.e2e,
+		async () => await run_playwright(extra_arguments),
+		{ command: 'test:e2e' },
+	)
+}
+
 async function run_guarded_e2e(
 	project_directory: string,
 	extra_arguments: ReadonlyArray<string>,
@@ -61,16 +88,37 @@ async function run_guarded_e2e(
 	const is_installed = is_playwright_installed(project_directory)
 	const has_tests = has_e2e_tests(project_directory)
 	const action = resolve_guard_action(is_installed, has_tests)
-	if (action === 'run') return await run_playwright(extra_arguments)
+	if (action === 'run') return await run_reserved_playwright(extra_arguments)
 
 	console.info(`josh test:e2e: ${SKIP_REASONS[action]} — skipping Playwright 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)
 }
@@ -79,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-pinned-logic.ts

@@ -0,0 +1,145 @@
+import { test_declared_logic } from './test-declared-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`.
+
+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 LINE_BREAK = '\n'
+const GREEN_REASON = 'reverting it left every related test green'
+const NO_TEST_REASON = 'no related test ran with it reverted'
+
+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>
+}
+
+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 none
+// ran at all — no related test, or a vitest that stopped before running one.
+interface UnpinnedHunk extends Hunk {
+	is_green: boolean
+}
+
+interface PinnedReport {
+	unpinned: ReadonlyArray<UnpinnedHunk>
+	unchecked: ReadonlyArray<Hunk>
+	max_hunks: number
+}
+
+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: [],
+	}
+}
+
+function is_old_line(line: string): boolean {
+	return line.startsWith(OLD_LINE) && !line.startsWith(OLD_FILE_HEADER)
+}
+
+// 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.
+function file_after(file: string, line: string): string {
+	if (line.startsWith(FILE_HEADER)) return line.slice(FILE_HEADER.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) walk.hunks.push(hunk)
+	else if (is_old_line(line)) walk.hunks.at(-1)?.old_lines.push(line.slice(OLD_LINE.length))
+}
+
+// One `-U0` diff into its hunks, in diff order. The `+` lines are not kept: the working file already
+// holds them, at `new_start` for `new_count` lines.
+function parse_hunks(diff: string): Array<Hunk> {
+	const walk: DiffWalk = { file: '', hunks: [] }
+
+	for (const line of diff.split(LINE_BREAK)) step(walk, line)
+
+	return walk.hunks.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) }
+}
+
+function location(hunk: Hunk): string {
+	return `${hunk.file}:${String(Math.max(hunk.new_start, 1))}`
+}
+
+function format(report: PinnedReport): string {
+	const unpinned = report.unpinned.map(
+		(hunk) => `unpinned ${location(hunk)} — ${hunk.is_green ? GREEN_REASON : NO_TEST_REASON}`,
+	)
+	const unchecked = report.unchecked.map(
+		(hunk) => `unchecked ${location(hunk)} — over the ${String(report.max_hunks)}-hunk cap`,
+	)
+
+	return [...unpinned, ...unchecked].join(LINE_BREAK)
+}
+
+const test_pinned_logic = {
+	DEFAULT_MAX_HUNKS,
+	format,
+	is_target,
+	location,
+	parse_hunks,
+	revert,
+	split,
+}
+
+export type { Hunk, PinnedReport, UnpinnedHunk }
+export { test_pinned_logic }

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { test_pinned } from './test-pinned'
+import { test_pinned_logic, type PinnedReport } from './test-pinned-logic'
+
+// The `josh test:pinned` entry: read `--max`, run, print one line per unpinned or unchecked hunk, and
+// exit non-zero when any checked hunk is unpinned. An unchecked hunk alone does not fail the run — it
+// was not asked about.
+
+const CLEAN_EXIT = 0
+const FAILED_EXIT = 1
+const ARGV_OFFSET = 2
+const USAGE = [
+	'Usage: josh test:pinned [--max <n>] [--help]',
+	'  revert each changed hunk of a non-test code file and run its related tests;',
+	'  prints `unpinned <file>:<line>` for a hunk no test went red on, and',
+	`  \`unchecked <file>:<line>\` past the --max cap (default ${String(test_pinned_logic.DEFAULT_MAX_HUNKS)})`,
+].join('\n')
+
+const PARSE_ARGS_OPTIONS = {
+	help: { type: 'boolean', short: 'h', default: false },
+	max: { type: 'string' },
+} as const
+
+const HELP_FLAGS: ReadonlySet<string> = new Set(['--help', '-h'])
+
+// A `--max` that is not a whole number above zero is a refusal, not the default.
+function valid_max(raw: string | undefined): number | undefined {
+	const max = Number(raw ?? test_pinned_logic.DEFAULT_MAX_HUNKS)
+
+	return Number.isSafeInteger(max) && max > 0 ? max : undefined
+}
+
+// `undefined` prints the usage: a help request, an unknown flag, or a missing or invalid `--max`.
+function max_hunks_of(argv: ReadonlyArray<string>): number | undefined {
+	try {
+		const { values } = parseArgs({ args: [...argv], options: PARSE_ARGS_OPTIONS, strict: true })
+
+		return values.help ? undefined : valid_max(values.max)
+	} catch {
+		return undefined
+	}
+}
+
+// Clean for an explicit help request; a refusal for anything the parse did not understand.
+function print_usage(argv: ReadonlyArray<string>): number {
+	process.stderr.write(`${USAGE}\n`)
+
+	return argv.some((argument) => HELP_FLAGS.has(argument)) ? CLEAN_EXIT : FAILED_EXIT
+}
+
+function output(report: PinnedReport): string {
+	const unpinned = String(report.unpinned.length)
+	const unchecked = String(report.unchecked.length)
+	const lines = [`unpinned ${unpinned} · unchecked ${unchecked}`, test_pinned_logic.format(report)]
+
+	return `${lines.filter((line) => line !== '').join('\n')}\n`
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<number> {
+	const max_hunks = max_hunks_of(argv)
+	if (max_hunks === undefined) return print_usage(argv)
+
+	const report = await test_pinned.run(max_hunks)
+
+	process.stdout.write(output(report))
+
+	return report.unpinned.length === 0 ? CLEAN_EXIT : FAILED_EXIT
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await main(process.argv.slice(ARGV_OFFSET))
+}
+
+const test_pinned_main = { main }
+
+export { test_pinned_main }

package/scripts/test/test-pinned.ts

@@ -0,0 +1,100 @@
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+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'
+import { git_spawn } from '#scripts/git/git-spawn'
+import {
+	test_pinned_logic,
+	type Hunk,
+	type PinnedReport,
+	type UnpinnedHunk,
+} from './test-pinned-logic'
+import { test_red } from './test-red'
+import type { RedVerdict } from './test-red-logic'
+
+// `josh test:pinned` (joshuafolkken/kit#4516) — put each changed hunk of a non-test code file back to
+// the merge-base's lines, one at a time, run that file's related tests, and list the hunks no test went
+// red on: the "reverting it stays green" finding a review used to stop a lane on.
+//
+// **The reverts happen in a detached worktree at HEAD, never the caller's checkout** (`base-tree.ts`).
+// The changed files are copied in from the working tree first, so what is reverted is the change as it
+// stands, committed or not, and each hunk's file is restored before the next one runs.
+
+const TREE_PREFIX = 'josh-test-pinned-'
+const HEAD = 'HEAD'
+
+// `--diff-filter=M`: an added file's one hunk is the whole file, and reverting it is a missing module
+// every importer fails on, which says nothing about the tests. The prefixes are pinned: a user's
+// `diff.mnemonicPrefix` writes `+++ w/<file>`, which would read as no hunk at all.
+async function read_hunks(base: string, files: ReadonlyArray<string>): Promise<Array<Hunk>> {
+	if (files.length === 0) return []
+	const diff_args = ['diff', '-U0', '--no-color', '--no-ext-diff', '--diff-filter=M']
+	const prefix_args = ['--src-prefix=a/', '--dst-prefix=b/', base, '--']
+
+	return test_pinned_logic.parse_hunks(
+		await git_spawn.read([...diff_args, ...prefix_args, ...files]),
+	)
+}
+
+// The verdict with this one hunk reverted. The file is put back before the next hunk runs, or that
+// hunk's tests would also see this revert.
+async function verdict_of(tree: BaseTree, hunk: Hunk): Promise<RedVerdict> {
+	const target = path.join(tree.tree, hunk.file)
+	const content = await readFile(target, 'utf8')
+
+	await writeFile(target, test_pinned_logic.revert(content, hunk))
+
+	try {
+		return await test_red.verdict_in(tree, ['related', hunk.file, '--run'])
+	} finally {
+		await writeFile(target, content)
+	}
+}
+
+// One hunk at a time: two reverts in flight would share the tree, and each run is already a whole vitest.
+// Green and no-test both leave a hunk unpinned: either way nothing went red when it was reverted.
+async function unpinned_in(
+	tree: BaseTree,
+	hunks: ReadonlyArray<Hunk>,
+): Promise<Array<UnpinnedHunk>> {
+	const unpinned: Array<UnpinnedHunk> = []
+
+	for (const hunk of hunks) {
+		// eslint-disable-next-line no-await-in-loop -- the hunks share one tree, so each revert waits for the last restore
+		const verdict = await verdict_of(tree, hunk)
+		if (verdict !== 'red') unpinned.push({ ...hunk, is_green: verdict === 'green' })
+	}
+
+	return unpinned
+}
+
+async function unpinned_on(
+	paths: ReadonlyArray<string>,
+	hunks: ReadonlyArray<Hunk>,
+): Promise<Array<UnpinnedHunk>> {
+	if (hunks.length === 0) return []
+
+	return await base_tree.with_tree(TREE_PREFIX, HEAD, async (tree) => {
+		await base_tree.copy_in(tree.tree, paths)
+
+		return await unpinned_in(tree, hunks)
+	})
+}
+
+// No merge-base (not a repository, no default branch) checks nothing, as `josh test:red` does.
+async function run(max_hunks: number): Promise<PinnedReport> {
+	const base = await change_base.resolved()
+	const changed = await changed_paths.read_changed_paths(false)
+	const paths = changed.filter((file) => existsSync(file))
+	const targets = paths.filter((file) => test_pinned_logic.is_target(file))
+	const hunks = base === undefined ? [] : await read_hunks(base, targets)
+	const { checked, unchecked } = test_pinned_logic.split(hunks, max_hunks)
+
+	return { unpinned: await unpinned_on(paths, checked), unchecked, max_hunks }
+}
+
+const test_pinned = { run }
+
+export { test_pinned }