@joshuafolkken/kit 1.872.0

package/scripts/gate/scoped-green.ts

@@ -0,0 +1,260 @@
+import { file_map_stamp, type FileMapStampAccess } from '#scripts/josh/file-map-stamp'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { review_brief } from '#scripts/review/review-brief'
+import { review_stamps } from '#scripts/review/review-stamps'
+import { gate_tree, type GateTree } from './gate-tree'
+
+// Whether the two scoped checks have been green on *this exact tree* by the time the review is
+// briefed (joshuafolkken/kit#1511).
+//
+// **The commands were already shipped; what was missing was when they run.** joshuafolkken/kit#1298
+// and joshuafolkken/kit#1257 gave the run `lint:related` and `test:related`, and
+// joshuafolkken/kit#1383 and joshuafolkken/kit#1246 stopped it re-running the whole gate per edit.
+// None of them says the pair has to have answered before the review starts, and `fullrun #1503` is
+// what that costs: the gate and round 1 were started on a tree neither check had ever read, three
+// findings then arrived on three separate round trips with fourteen edits between them, and the
+// rework ran 282 seconds — 31% of a 905-second run. The same run proves the cheap half: the one call
+// that ran both checks together took 13.8 seconds and produced two of the three findings at once.
+//
+// **It fixes when the checks run, never whether they run, and never what they check.** Nothing here
+// skips a check, narrows one, or reinterprets its output — a green record buys ordering and nothing
+// else, and `josh gate` still runs its four checks exactly as before. That is the boundary
+// joshuafolkken/kit#1420 sits on the far side of: that issue asked to *reuse* a scoped check's result
+// instead of re-running it and was closed as not needed, and this record does not revive it.
+//
+// **The judgement is the gate's own, not a second one.** "There is a record and nothing it covers has
+// moved" is `review_brief.matching_stamp` plus the base equality `gate_skip.reusable_green_gate`
+// already compares, over the same `FileMapStamp` shape written to the same kind of file. A second
+// definition of "this tree is unchanged" is the clone `CLAUDE.md` prohibits, and it is exactly where
+// two commands would start disagreeing about one working tree.
+//
+// **It refuses `josh review:brief`, and now the local `josh gate` too, but never CI's**
+// (joshuafolkken/kit#2296). The brief was the first refusal point because it is where `review:attest`
+// mints the nonce a round is counted against, so no countable review round bypasses it. But the gate
+// itself runs *before* the brief, and a run that reached it on a tree the scoped pair had never read
+// paid for the gap anyway — so `verification-gate.ts` reads this same record one step earlier and
+// refuses to start. The one gate that must never be refused is CI's: `.github/workflows/ci.yml` runs
+// `pnpm josh gate --verbose --no-unit`, with no scoped check in front of it, so the gate's pre-check
+// fires only when the unit suite is included — which excludes `--no-unit` — and never under `--force`.
+
+// The escape hatch, on by default like every other distributed guard: a convention nobody can turn
+// off is one a person cannot get past on the day the record is wrong about their tree.
+const SWITCH_ENV_KEY = 'JOSH_SCOPED_GREEN'
+
+const SUCCESS_EXIT_CODE = 0
+
+const LINT_SCRIPT = 'lint:related'
+const TEST_SCRIPT = 'test:related'
+const LINT_COMMAND = `pnpm josh ${LINT_SCRIPT}`
+const TEST_COMMAND = `pnpm josh ${TEST_SCRIPT}`
+
+interface ScopedCheck {
+	script: string
+	command: string
+	stamp: FileMapStampAccess
+	// Present and `undefined` rather than optional: under `exactOptionalPropertyTypes` an absent
+	// property and one holding `undefined` are different types, and the value here comes from an
+	// optional field of `ScopedSources`.
+	source: string | undefined
+}
+
+// The record paths, overridable so a test can plant one without overwriting the record a real run in
+// this checkout relies on — the same reason `gate_skip.reusable_green_gate` takes a `source`.
+interface ScopedSources {
+	lint?: string
+	test?: string
+}
+
+function checks_of(sources: ScopedSources): ReadonlyArray<ScopedCheck> {
+	return [
+		{
+			script: LINT_SCRIPT,
+			command: LINT_COMMAND,
+			stamp: review_stamps.lint_related_stamp,
+			source: sources.lint,
+		},
+		{
+			script: TEST_SCRIPT,
+			command: TEST_COMMAND,
+			stamp: review_stamps.test_related_stamp,
+			source: sources.test,
+		},
+	]
+}
+
+// **An unreadable record reads as an absent one, and that is the safe direction.** `read` swallows a
+// malformed or foreign file and answers `undefined`, so the two cases are indistinguishable here —
+// and the consequence of treating one as the other is a single 14-second scoped run, against the
+// alternative of briefing a review on a tree nothing has checked.
+function describes_tree(check: ScopedCheck, tree: Record<string, string>, base: string): boolean {
+	const stamp = review_brief.matching_stamp(check.stamp.read(check.source), tree)
+
+	return stamp !== undefined && file_map_stamp.describes_base(stamp, base)
+}
+
+// **Whether there is a tree to speak about at all**, asked once and used from both ends: the reader
+// refuses nothing when it is false, and the writer records nothing. Two copies of it would be two
+// answers to one question — the reader could then refuse over a tree the writer had declined to
+// vouch for, which is a wedge with no way out.
+//
+// An empty file map is a tree with nothing for a scoped check to read, and a base that could not be
+// resolved is git failing to answer rather than evidence about the tree.
+function is_describable(files: Record<string, string>, base: string | undefined): base is string {
+	return base !== undefined && Object.keys(files).length > 0
+}
+
+// **The switch is the third state that must never refuse**, and it is a person's decision rather than
+// a reading — so it sits on the reader alone. A run with the guard turned off still records, which is
+// what lets turning it back on take effect immediately.
+function is_answerable(tree: Record<string, string>, base: string | undefined): base is string {
+	if (!hook_decision.is_switch_enabled(SWITCH_ENV_KEY)) return false
+
+	return is_describable(tree, base)
+}
+
+function stale_checks(
+	tree: Record<string, string>,
+	base: string | undefined,
+	sources: ScopedSources,
+): ReadonlyArray<ScopedCheck> {
+	if (!is_answerable(tree, base)) return []
+
+	return checks_of(sources).filter((check) => !describes_tree(check, tree, base))
+}
+
+function missing_checks(
+	tree: Record<string, string>,
+	base: string | undefined,
+	sources: ScopedSources = {},
+): ReadonlyArray<string> {
+	return stale_checks(tree, base, sources).map((check) => check.command)
+}
+
+// The same answer as `missing_checks`, as the `josh` script names a caller runs rather than the
+// command lines a refusal prints — so the ship supervisor (joshuafolkken/kit#2500) meets the
+// precondition itself by running exactly what the refusal would have asked for.
+function missing_scripts(
+	tree: Record<string, string>,
+	base: string | undefined,
+	sources: ScopedSources = {},
+): ReadonlyArray<string> {
+	return stale_checks(tree, base, sources).map((check) => check.script)
+}
+
+const REFUSAL_HEADLINE = '⛔ scoped checks not green on this tree'
+
+// **The way out travels with the refusal.** A message saying only "not verified" leaves the caller
+// holding the same question and no sanctioned answer, which is how the checks ended up after the
+// review in the first place. So the text names the one command that closes it, what it costs, and
+// that reissuing this call is the expected next move.
+function refusal(missing: ReadonlyArray<string>): string {
+	return (
+		`${REFUSAL_HEADLINE}: ${missing.join(' and ')} ` +
+		'have not passed on the files this branch changed. The gate and review round 1 start together, ' +
+		'so a brief composed now describes a tree neither check has read — joshuafolkken/kit#1503 spent ' +
+		'282 seconds, 31% of the run, picking up one lint rule and one failing test at a time after its ' +
+		'review had already started. Run them in one call — ' +
+		`\`${LINT_COMMAND} && ${TEST_COMMAND}\`, measured at 13.8 seconds — and reissue this command. ` +
+		'The record fixes when the checks run and never whether they run: nothing is skipped, narrowed ' +
+		'or reused because of it. `prompts/review.md` → "The scoped checks answer on the last edit".'
+	)
+}
+
+function refusal_for(
+	tree: Record<string, string>,
+	base: string | undefined,
+	sources: ScopedSources = {},
+): string | undefined {
+	const missing = missing_checks(tree, base, sources)
+
+	return missing.length === 0 ? undefined : refusal(missing)
+}
+
+// **A record is written only by a bare invocation, and any argument at all withholds it.** A path
+// narrows which files were read; a flag can narrow just as hard behind a spelling that looks like
+// every other flag — `--shard`, `--project`, `--testNamePattern` and `--exclude` all exit 0 having
+// run a fraction of the suite. Telling a narrowing flag from a reporter flag would be a judgement
+// maintained per runner, and getting it wrong writes a full green record for a partial run. Requiring
+// a bare invocation costs at most one extra scoped run and cannot fail in the unsafe direction.
+function is_recordable_scope(command_arguments: ReadonlyArray<string>): boolean {
+	return command_arguments.length === 0
+}
+
+// Read *before* the checks start, so what they were green on can be compared with what the tree looked
+// like when they finished — and read at all only when a record could follow it.
+async function read_before(
+	command_arguments: ReadonlyArray<string>,
+): Promise<GateTree | undefined> {
+	if (!is_recordable_scope(command_arguments)) return undefined
+
+	return await gate_tree.read_gate_tree()
+}
+
+// **A tree that moved while the checks were in flight is not the tree they read** — an editor save,
+// or the `PostToolUse` formatter rewriting a file mid-run. This is the comparison `record_green_gate`
+// makes for the gate's own record, asked here for the same reason: without it a record vouches for
+// bytes no check ever saw, it does so silently, and it does so in the unsafe direction.
+function is_unmoved(before: GateTree, after: GateTree): boolean {
+	if (before.base !== after.base) return false
+
+	return JSON.stringify(before.files) === JSON.stringify(after.files)
+}
+
+function record_green(stamp: FileMapStampAccess, tree: GateTree, target?: string): void {
+	if (!is_describable(tree.files, tree.base)) return
+
+	try {
+		stamp.write(tree.files, target, tree.base)
+	} catch {
+		/* a record that could not be written re-runs the checks rather than skipping them */
+	}
+}
+
+// `before` is `undefined` both when the arguments ruled a record out and when the caller decided the
+// run was inconclusive — a vitest the guard skipped rather than ran, say. Either way there is nothing
+// to vouch for, and the two do not need telling apart here.
+interface GreenRecord {
+	before: GateTree | undefined
+	exit_code: number
+	// Where the record lands, defaulted by the stamp itself. It exists for the same reason
+	// `record_green` and `gate_skip.reusable_green_gate` take one: without it this function can only
+	// write the real per-checkout record, so a suite exercising it would vouch for the surrounding
+	// run's own tree — the second-writer trap joshuafolkken/kit#1437 and joshuafolkken/kit#1441
+	// closed for the gate and round-1 records.
+	target?: string
+}
+
+async function record_if_green(stamp: FileMapStampAccess, record: GreenRecord): Promise<void> {
+	const { before, exit_code, target } = record
+
+	if (
+		before === undefined ||
+		exit_code !== SUCCESS_EXIT_CODE ||
+		!is_unmoved(before, await gate_tree.read_gate_tree())
+	) {
+		return
+	}
+
+	record_green(stamp, before, target)
+}
+
+const scoped_green = {
+	LINT_COMMAND,
+	LINT_SCRIPT,
+	REFUSAL_HEADLINE,
+	SWITCH_ENV_KEY,
+	TEST_COMMAND,
+	TEST_SCRIPT,
+	is_recordable_scope,
+	is_unmoved,
+	missing_checks,
+	missing_scripts,
+	read_before,
+	record_green,
+	record_if_green,
+	refusal,
+	refusal_for,
+}
+
+export type { GreenRecord, ScopedSources }
+export { scoped_green }

package/scripts/gate/type-check-step.ts

@@ -0,0 +1,90 @@
+import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { execa } from 'execa'
+
+// joshuafolkken/kit#934: `josh gate`'s type-check step used to be `tsc --noEmit` for every project.
+// A SvelteKit project type-checks with `svelte-check` behind `svelte-kit sync`, so the fixed step
+// both missed every `.svelte` type error and failed outright on a clean checkout, where `./$types`
+// has not been generated yet.
+//
+// The step is therefore asked of the application layer rather than assumed. Two rules decide it:
+//
+// 1. **Only the project's own toolkit counts.** The shim is found by walking up from the working
+//    directory to a `node_modules/.bin`, the same walk pnpm performs — never by running
+//    `pnpm <bin>`, which falls through to a globally installed toolkit and would run a SvelteKit
+//    type check on a project that is not one.
+// 2. **The command exists only if the toolkit says so.** The resolved shim is run with no
+//    subcommand and the usage line it prints is read, exactly as the `verify-ui` skill decides
+//    whether a `shot` command exists. Presence of the toolkit is not presence of the command:
+//    app-kit gained `check:ci` in one version and `shot` in another.
+
+const DEFAULT_TYPE_CHECK_ARGS: ReadonlyArray<string> = ['josh', 'check']
+// Ordered: `check:ci` is the strict variant a gate wants; `check` is the fast dev-loop one, taken
+// only by a toolkit that has no strict variant.
+const PREFERRED_COMMANDS: ReadonlyArray<string> = ['check:ci', 'check']
+const TOOLKIT_BINS: ReadonlyArray<string> = ['josh-app', 'josh-game']
+// `Usage: josh-app <init|sync|check|check:ci|…>` — the commands are the `|`-separated group that
+// follows the literal `Usage:`. Anchoring on that word rather than on a line start matters twice
+// over: the output is stdout and stderr merged, which execa joins without inserting a newline, and
+// a bracketed warning printed first would otherwise be read as the command list.
+const USAGE_COMMANDS_PATTERN = /Usage:[^<>\n]*<([^<>\n]+)>/u
+const COMMAND_SEPARATOR = '|'
+// A toolkit that prints its usage answers in milliseconds; anything slower is hung.
+const USAGE_TIMEOUT_MS = 30_000
+
+function parse_usage_commands(output: string): ReadonlyArray<string> {
+	const group = USAGE_COMMANDS_PATTERN.exec(output)?.[1]
+	if (group === undefined) return []
+
+	return group.split(COMMAND_SEPARATOR).map((command) => command.trim())
+}
+
+// Run with no subcommand. A toolkit answers with its usage line whether that exits 0 or not, so the
+// output is read rather than the status; a shim that cannot be spawned at all yields nothing. The
+// spawn is async so the probe overlaps the gate's other three checks instead of delaying them.
+async function read_toolkit_commands(bin_path: string): Promise<ReadonlyArray<string>> {
+	try {
+		const result = await execa(bin_path, [], {
+			all: true,
+			reject: false,
+			timeout: USAGE_TIMEOUT_MS,
+		})
+
+		return parse_usage_commands(result.all)
+	} catch {
+		return []
+	}
+}
+
+function find_preferred_command(commands: ReadonlyArray<string>): string | undefined {
+	return PREFERRED_COMMANDS.find((preferred) => commands.includes(preferred))
+}
+
+async function resolve_toolkit_step(
+	start_directory: string,
+	bin_name: string,
+): Promise<ReadonlyArray<string> | undefined> {
+	const bin_path = find_local_bin_upwards(start_directory, bin_name)
+	if (bin_path === undefined) return undefined
+
+	const command = find_preferred_command(await read_toolkit_commands(bin_path))
+
+	return command === undefined ? undefined : [bin_name, command]
+}
+
+// The command the gate spawns through `pnpm`, so a toolkit step resolves the same shim `pnpm` would.
+async function resolve_type_check_args(start_directory: string): Promise<ReadonlyArray<string>> {
+	for (const bin_name of TOOLKIT_BINS) {
+		const step = await resolve_toolkit_step(start_directory, bin_name)
+		if (step !== undefined) return step
+	}
+
+	return DEFAULT_TYPE_CHECK_ARGS
+}
+
+const type_check_step = {
+	parse_usage_commands,
+	resolve_toolkit_step,
+	resolve_type_check_args,
+}
+
+export { DEFAULT_TYPE_CHECK_ARGS, type_check_step }