@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,91 @@
+// The verdict `josh test:declared` prints, decided from the changed paths alone
+// (joshuafolkken/kit#2118).
+//
+// **The input is a set of paths, never a judgement.** The spelling of a test file is fixed by
+// `eslint/rules/test-filename.js` (`*.test.ts` / `*.e2e.ts`), and the mechanically-exempt non-runtime
+// paths are an enumeration — docs and editor/IDE settings. So "a runtime file changed and no test file
+// changed with it" is a set comparison, which is exactly the reason `CLAUDE.md` gives for it not being
+// a judgement.
+//
+// **The exemption is deliberately conservative, and it is the opposite of `review-level.ts`'s inert
+// set.** That set keeps documentation *out* because a human reading the prose is the only thing that
+// can catch a defect in it; this set keeps documentation *in* because a test could never have caught a
+// prose defect either way. The two answer different questions, so sharing one list would be wrong, not
+// a clone avoided. Here only paths that are mechanically certain to touch no runtime code are exempt —
+// the non-executable config and cosmetic-asset arms of `CLAUDE.md`'s "Non-runtime updates" exception
+// stay `required`, and a person declares that exception in the Step 0 work summary. Under-exempting
+// costs one declared exception; over-exempting ships an untested runtime change.
+
+type Verdict = 'required' | 'exempt' | 'satisfied'
+
+// A change that carries a test. `.svelte.test.ts` ends with `.test.ts`, so the two suffixes cover it.
+const TEST_SUFFIXES: ReadonlyArray<string> = ['.e2e.ts', '.test.ts']
+
+// docs, and the editor/IDE settings that neither execute nor ship a runtime path. The strings are
+// matched against `CLAUDE.md`'s enumeration by `test-declared-document-rule.test.ts`, the same way
+// `review-level-document-rule.test.ts` pins the inert set.
+const EXEMPT_PATHS: ReadonlyArray<string> = ['.editorconfig']
+const EXEMPT_PREFIXES: ReadonlyArray<string> = ['.idea/', '.vscode/', 'prompts/']
+const EXEMPT_SUFFIXES: ReadonlyArray<string> = ['.md']
+
+function normalize(paths: ReadonlyArray<string>): Array<string> {
+	return paths.map((path) => path.trim()).filter((path) => path !== '')
+}
+
+function is_test_file(path: string): boolean {
+	return TEST_SUFFIXES.some((suffix) => path.endsWith(suffix))
+}
+
+function is_exempt(path: string): boolean {
+	if (EXEMPT_PATHS.includes(path)) return true
+
+	return (
+		EXEMPT_SUFFIXES.some((suffix) => path.endsWith(suffix)) ||
+		EXEMPT_PREFIXES.some((prefix) => path.startsWith(prefix))
+	)
+}
+
+// A runtime file is one that is neither a test nor exempt. Its presence with no test file beside it is
+// the whole of what `required` reports.
+function is_runtime(path: string): boolean {
+	return !is_test_file(path) && !is_exempt(path)
+}
+
+// **A test file changed → `satisfied`, whatever else did.** A runtime file with no test beside it →
+// `required`. Everything left — an all-exempt change, and the empty diff — is `exempt`, because there
+// is no runtime file the change failed to test.
+function verdict_for(paths: ReadonlyArray<string>): Verdict {
+	const changed = normalize(paths)
+
+	if (changed.some((path) => is_test_file(path))) return 'satisfied'
+	if (changed.some((path) => is_runtime(path))) return 'required'
+
+	return 'exempt'
+}
+
+// The runtime files with no test beside them — the `required` detail line, so the answer says which
+// files it is about rather than only that it refused.
+function runtime_files(paths: ReadonlyArray<string>): Array<string> {
+	return normalize(paths).filter((path) => is_runtime(path))
+}
+
+// The paths that made the change exempt — the `exempt` detail line.
+function exempt_files(paths: ReadonlyArray<string>): Array<string> {
+	return normalize(paths).filter((path) => is_exempt(path))
+}
+
+const test_declared_logic = {
+	EXEMPT_PATHS,
+	EXEMPT_PREFIXES,
+	EXEMPT_SUFFIXES,
+	TEST_SUFFIXES,
+	exempt_files,
+	is_exempt,
+	is_runtime,
+	is_test_file,
+	runtime_files,
+	verdict_for,
+}
+
+export type { Verdict }
+export { test_declared_logic }

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

@@ -0,0 +1,106 @@
+import { test_type_logic, type TestType } from './test-type-logic'
+
+// The Step 0 declaration lines checked against the tests actually in the working-tree change set
+// (joshuafolkken/kit#2181). `CLAUDE.md` Step 0 fixes the shape of each line —
+// `<what changes> — Test: <Unit|E2E> — <path> — <what it verifies>` — and `testing-guide.md` §0 asks
+// that the count of declared tests match the count added, yet nothing read the correspondence. This
+// reads it: for every declaration, whether the declared type matches the path, whether the path was
+// really changed, and whether a colocated test of that type is in the diff.
+
+// The em-dash separator the declaration line is written with — space, em-dash, space.
+const FIELD_SEPARATOR = ' — '
+const TEST_MARKER = 'Test:'
+const TYPES: ReadonlyArray<TestType> = [test_type_logic.UNIT, test_type_logic.E2E]
+
+type MatchStatus = 'match' | 'type-mismatch' | 'path-missing' | 'test-not-created'
+
+interface Declaration {
+	declared_type: TestType
+	path: string
+}
+
+interface MatchResult extends Declaration {
+	status: MatchStatus
+}
+
+// The directory a path lives in, kept with its trailing slash so a same-directory test compares equal.
+// A path with no slash lives at the root, whose directory is the empty string.
+function directory_of(path: string): string {
+	const slash = path.lastIndexOf('/')
+
+	return slash === -1 ? '' : path.slice(0, slash + 1)
+}
+
+// The declared type named after `Test:` in a field, or undefined when the field is not a `Test:` field
+// or names neither type.
+function type_in_field(field: string): TestType | undefined {
+	const trimmed = field.trim()
+	if (!trimmed.startsWith(TEST_MARKER)) return undefined
+
+	const value = trimmed.slice(TEST_MARKER.length).trim()
+
+	return TYPES.find((type) => type === value)
+}
+
+// One declaration parsed from a summary line, or undefined when the line carries no `Test:` field with
+// a recognized type and a path after it.
+function parse_line(line: string): Declaration | undefined {
+	const fields = line.split(FIELD_SEPARATOR)
+	const marker = fields.findIndex((field) => type_in_field(field) !== undefined)
+	const marker_field = fields[marker]
+	const path_field = fields[marker + 1]
+	if (marker_field === undefined || path_field === undefined) return undefined
+
+	const declared_type = type_in_field(marker_field)
+	if (declared_type === undefined) return undefined
+
+	return { declared_type, path: path_field.trim() }
+}
+
+function parse_declarations(summary: string): ReadonlyArray<Declaration> {
+	return summary
+		.split('\n')
+		.map((line) => parse_line(line))
+		.filter((declaration): declaration is Declaration => declaration !== undefined)
+}
+
+const SUFFIX_FOR: Record<TestType, string> = {
+	Unit: '.test.ts',
+	E2E: '.e2e.ts',
+}
+
+// A changed test file of the declared type sits in the same directory as the declared path — an equal
+// directory, so a test one level down does not count as beside it.
+function has_colocated_test(declaration: Declaration, changed: ReadonlyArray<string>): boolean {
+	const directory = directory_of(declaration.path)
+	const suffix = SUFFIX_FOR[declaration.declared_type]
+
+	return changed.some((path) => directory_of(path) === directory && path.endsWith(suffix))
+}
+
+function status_for(declaration: Declaration, changed: ReadonlyArray<string>): MatchStatus {
+	if (!changed.includes(declaration.path)) return 'path-missing'
+
+	if (test_type_logic.test_type_for(declaration.path) !== declaration.declared_type) {
+		return 'type-mismatch'
+	}
+
+	if (!has_colocated_test(declaration, changed)) return 'test-not-created'
+
+	return 'match'
+}
+
+// The status of every declaration in the summary against the change set, so the caller can print each
+// mismatch. The whole change set is passed through — the declared path is matched against it directly,
+// and `has_colocated_test` reads the test files in it.
+function match_report(summary: string, changed: ReadonlyArray<string>): ReadonlyArray<MatchResult> {
+	return parse_declarations(summary).map((declaration) => ({
+		...declaration,
+		status: status_for(declaration, changed),
+	}))
+}
+
+const test_declared_match = { directory_of, match_report, parse_declarations }
+
+export type { Declaration, MatchResult, MatchStatus }
+export { test_declared_match }

package/scripts/test/test-declared.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env tsx
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { test_declared_changed } from './test-declared-changed'
+import { test_declared_logic, type Verdict } from './test-declared-logic'
+import { test_declared_match, type MatchResult } from './test-declared-match'
+import { test_type_logic } from './test-type-logic'
+
+// `josh test:declared` — prints one of `required` / `exempt` / `satisfied` to stdout from the
+// working-tree diff, with the reason on stderr (joshuafolkken/kit#2118). The verdict is
+// `test-declared-logic.ts`, the tree read is `test-declared-changed.ts`. This command is the way a
+// person confirms the same answer by hand; the refusal itself is delivered by the `test-declared` row
+// of `delivered-rules.ts` at the commit stage.
+//
+// `--match` reads a Step 0 work summary on stdin and checks each declared `Test: <type> — <path>`
+// line against the change set, printing `match` / `type-mismatch` / `path-missing` /
+// `test-not-created` per line and exiting non-zero on any mismatch (joshuafolkken/kit#2181).
+
+const CLEAN_EXIT = 0
+const MISMATCH_EXIT = 1
+const MATCH_STATUS = 'match'
+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
+// convention (joshuafolkken/kit#2297). 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 = {
+	help: { type: 'boolean', short: 'h', default: false },
+	match: { type: 'boolean', default: false },
+} as const
+
+const USAGE = [
+	'Usage: josh test:declared [--match] [--help]',
+	'  (no flags)  print required | exempt | satisfied for the working-tree diff',
+	'  --match     read a Step 0 work summary on stdin and check each `Test:` line against the',
+	'              change set, e.g. `pnpm josh test:declared --match < summary.md`',
+	'  --help, -h  print this usage',
+].join('\n')
+
+// The one command a `required` verdict leaves to run next: declare a test for each named runtime file,
+// then verify the declarations against the change set (joshuafolkken/kit#2297). Printed after the
+// detail so the verdict-to-detail mapping the report test pins stays untouched.
+const NEXT_STEP =
+	'next: declare a test for each runtime file above, then verify with `pnpm josh test:declared --match < summary.md`'
+
+interface Options {
+	is_help: boolean
+	is_match: boolean
+}
+
+// The parsed flags, or `undefined` when an unknown one was passed — the strict parse is what turns a
+// typo into a refusal rather than a silent re-print of the verdict.
+function parse(argv: ReadonlyArray<string>): Options | undefined {
+	try {
+		const { values } = parseArgs({ args: [...argv], options: PARSE_ARGS_OPTIONS, strict: true })
+
+		return { is_help: values.help, is_match: values.match }
+	} catch {
+		return undefined
+	}
+}
+
+// The next command a verdict leaves to run, or `undefined` when there is nothing to do next. Only
+// `required` owes one — an untested runtime change is the one verdict a person acts on.
+function next_step(verdict: Verdict): string | undefined {
+	return verdict === 'required' ? NEXT_STEP : undefined
+}
+
+// A runtime file with the test type its path calls for, so the required detail says which kind of
+// test to add rather than only that one is missing (joshuafolkken/kit#2181).
+function typed_runtime_file(path: string): string {
+	return `${test_type_logic.test_type_for(path)} — ${path}`
+}
+
+// The word is stdout so a caller can read it alone; the reason — which files, and why — is stderr.
+function detail_for(verdict: Verdict, paths: ReadonlyArray<string>): string {
+	if (verdict === 'required') {
+		const typed = test_declared_logic.runtime_files(paths).map((path) => typed_runtime_file(path))
+
+		return `runtime files with no test: ${typed.join(', ')}`
+	}
+
+	if (verdict === 'exempt') {
+		return `exempt paths: ${test_declared_logic.exempt_files(paths).join(', ')}`
+	}
+
+	return 'a test file changed'
+}
+
+function report(paths: ReadonlyArray<string>): { detail: string; verdict: Verdict } {
+	const verdict = test_declared_logic.verdict_for(paths)
+
+	return { detail: detail_for(verdict, paths), verdict }
+}
+
+function run(): void {
+	const { detail, verdict } = report(test_declared_changed.read_changed_paths_sync())
+
+	process.stdout.write(`${verdict}\n`)
+	process.stderr.write(`${detail}\n`)
+
+	const next = next_step(verdict)
+
+	if (next !== undefined) process.stderr.write(`${next}\n`)
+}
+
+function format_match(result: MatchResult): string {
+	return `${result.status}: ${result.declared_type} — ${result.path}`
+}
+
+// The exit code the match run leaves: clean only when every declaration matched, so it gates. A
+// summary that parses to no declarations is a mismatch, not a pass — a forgotten pipe would otherwise
+// read as "all declarations satisfied" when nothing was checked at all.
+function run_match(summary: string, changed: ReadonlyArray<string>): number {
+	const results = test_declared_match.match_report(summary, changed)
+
+	if (results.length === 0) {
+		process.stderr.write(`${NO_DECLARATIONS}\n`)
+
+		return MISMATCH_EXIT
+	}
+
+	for (const result of results) process.stdout.write(`${format_match(result)}\n`)
+
+	return results.every((result) => result.status === MATCH_STATUS) ? CLEAN_EXIT : MISMATCH_EXIT
+}
+
+// Prints the usage and returns the exit code: clean for an explicit `--help`, a mismatch for an
+// unknown flag — the flag was not understood, so the verdict must not be re-printed as though it were.
+function print_usage(is_help: boolean): number {
+	if (is_help) {
+		process.stdout.write(`${USAGE}\n`)
+
+		return CLEAN_EXIT
+	}
+
+	process.stderr.write(`${USAGE}\n`)
+
+	return MISMATCH_EXIT
+}
+
+// Returns the exit code so the entry point assigns `process.exitCode` in one expression — an unknown
+// flag prints the usage and gates, `--help` prints it clean, the default verdict path prints and
+// returns clean, and the match path reads stdin and gates on the result.
+async function main(argv: ReadonlyArray<string>): Promise<number> {
+	const options = parse(argv)
+
+	if (options === undefined) return print_usage(false)
+	if (options.is_help) return print_usage(true)
+
+	if (!options.is_match) {
+		run()
+
+		return CLEAN_EXIT
+	}
+
+	const summary = process.stdin.isTTY ? '' : await text(process.stdin)
+
+	return run_match(summary, test_declared_changed.read_changed_paths_sync())
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await main(process.argv.slice(ARGV_OFFSET))
+}
+
+const test_declared = {
+	USAGE,
+	detail_for,
+	format_match,
+	next_step,
+	parse,
+	report,
+	run,
+	run_match,
+}
+
+export { test_declared }

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env tsx
+import { existsSync, globSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execa } from 'execa'
+
+const PNPM = 'pnpm'
+const FAIL_EXIT_CODE = 1
+const ARGV_START = 2
+const PLAYWRIGHT_PACKAGE = path.join('node_modules', '@playwright', 'test')
+const E2E_GLOB = '**/*.e2e.{ts,js}'
+const NODE_MODULES = 'node_modules'
+
+// `@playwright/test` is an optional peer dependency and the e2e suite may be empty in a
+// fresh project, so the pre-push gate must skip — not fail — when either is missing. This
+// keeps the optional peer truly optional while still running Playwright once both are present.
+type GuardAction = 'run' | 'skip-missing-package' | 'skip-no-tests'
+
+const SKIP_REASONS: Record<Exclude<GuardAction, 'run'>, string> = {
+	'skip-missing-package': '@playwright/test is not installed',
+	'skip-no-tests': 'no *.e2e.{ts,js} test files found',
+}
+
+function resolve_guard_action(is_installed: boolean, has_tests: boolean): GuardAction {
+	if (!is_installed) return 'skip-missing-package'
+	if (!has_tests) return 'skip-no-tests'
+
+	return 'run'
+}
+
+function is_playwright_installed(project_directory: string): boolean {
+	return existsSync(path.join(project_directory, PLAYWRIGHT_PACKAGE))
+}
+
+function is_in_node_modules(entry: string): boolean {
+	return entry.split(/[/\\]/u).includes(NODE_MODULES)
+}
+
+function has_e2e_tests(project_directory: string): boolean {
+	const matches = globSync(E2E_GLOB, {
+		cwd: project_directory,
+		exclude: is_in_node_modules,
+	})
+
+	return matches.length > 0
+}
+
+async function run_playwright(extra_arguments: ReadonlyArray<string>): Promise<number> {
+	const result = await execa(PNPM, ['exec', 'playwright', 'test', ...extra_arguments], {
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode ?? FAIL_EXIT_CODE
+}
+
+async function run_guarded_e2e(
+	project_directory: string,
+	extra_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	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)
+
+	console.info(`josh test:e2e: ${SKIP_REASONS[action]} — skipping Playwright e2e.`)
+
+	return 0
+}
+
+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)
+
+	process.exit(exit_code)
+}
+
+const test_e2e_guard = {
+	resolve_guard_action,
+	is_playwright_installed,
+	has_e2e_tests,
+	run_guarded_e2e,
+}
+
+export type { GuardAction }
+export { test_e2e_guard }