@joshuafolkken/kit 1.872.0

package/scripts/gate/gate-skip.ts

@@ -0,0 +1,123 @@
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { review_brief } from '#scripts/review/review-brief'
+import { review_stamps } from '#scripts/review/review-stamps'
+
+// Whether `josh gate` already has the answer it is about to spend 47–50 seconds computing again
+// (joshuafolkken/kit#1328).
+//
+// The record has existed since joshuafolkken/kit#1241: `record_green_gate` writes the digest of every
+// changed file the four checks were green on, and `josh review:brief` reads it back to print
+// `Already verified`. The gate itself never read it, so a second run over an unedited tree started
+// four processes to reach a conclusion already on disk. **This is reuse of a result, not a check
+// dropped**: the bytes the skip answers for are the bytes the record was written from, compared one
+// by one.
+//
+// **The tree comparison is `review_brief.matching_stamp`, not a second copy of it.** "There is a
+// record and nothing it covers has moved" is one question with one answer, and a gate that decided it
+// differently from the brief printed beside it would be two commands disagreeing about the same tree.
+//
+// **A file map does not describe a tree on its own, because it is a diff.** It lists what differs
+// from the commit the branch was cut from — its merge base with the default branch since
+// joshuafolkken/kit#1527 — so everything the record says stays true while that base moves underneath
+// it. Two shapes of that, one obvious and one not:
+//
+// - Straight after `git switch main && git pull` the map is **empty**, and an empty map compares
+//   equal to any other empty map however many commits the pull brought in. `epicrun` runs exactly
+//   that pair of commands between children.
+// - Fetch an advanced default branch and rebase a feature branch onto it, and the map can come back
+//   **byte-identical** — the same files still differ by the same digests — over a working tree whose
+//   every other file has been replaced by code no check has read. The rebase moves `HEAD`, so it
+//   moves the merge base with it, and the base check still catches this.
+//
+// **What no longer refuses a reuse is another lane merging into the shared default branch**
+// (joshuafolkken/kit#1527). In a linked work tree the default branch's ref is shared, but the merge
+// base is a commit: an advance this branch is an ancestor of does not move it, and nothing this
+// checkout's four checks read has changed — so refusing there would have discarded a record that
+// still describes the tree exactly.
+//
+// So the record pins the commit the map was taken against, and both halves have to match. The empty
+// map is refused on top of that rather than left to the base check, because a skip there buys nothing
+// worth the argument: a tree with no changed file is not where a run spends its gate time.
+//
+// Two refusals need no code here. A gate that went red writes no record at all, so the re-verification
+// after a fix finds nothing to reuse; and joshuafolkken/kit#1261's join before the commit follows a
+// `josh bump`, which edits `package.json` into the map.
+//
+// **What is reused is a silent green run.** `record_green_gate` withholds the record from a run that
+// printed anything — a skip notice, or a check that passed with warnings — because the skip prints no
+// check bodies at all, and a record taken from such a run would make those lines disappear from every
+// later run over the same tree.
+
+// The escape hatch, for the times a person knows something outside the tree moved — a `pnpm install`,
+// a toolchain change, a cache thrown away. It lives beside the decision it overrides rather than with
+// the gate's other flag, so removing the skip would take its flag with it.
+const FORCE_FLAG = '--force'
+
+// The stamp rather than a boolean, for the same reason `review_brief.matching_stamp` hands one back:
+// the caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
+// printing. The source is a parameter so a test can plant a record without overwriting the one a real
+// run relies on — `josh gate` and `josh review:brief` share one path by design.
+//
+// A `base` that could not be read is `undefined`, and an older record carries none: both compare
+// unequal to anything, so the gate runs its checks. No base means no reuse, never reuse without one.
+function reusable_green_gate(
+	tree: Record<string, string>,
+	base: string | undefined,
+	source?: string,
+): FileMapStamp | undefined {
+	if (base === undefined || Object.keys(tree).length === 0) return undefined
+
+	const stamp = review_brief.matching_stamp(review_stamps.gate_stamp.read(source), tree)
+
+	if (stamp?.base !== base) return undefined
+
+	return stamp
+}
+
+// **The sentence claims the result, and never merely the omission.** "verification skipped" on its
+// own reads as `Not verified` — the one thing this output must not be mistaken for, since the run
+// goes on to a commit on the strength of it. So the line says what passed, on which tree and when,
+// and names the flag or the variable that runs the checks anyway.
+//
+// **One sentence, every reader of the record** (joshuafolkken/kit#1381). The gate says it, the
+// pre-push hook says it and the pre-commit hook says it, and three copies of a claim this load-bearing
+// would not have stayed the same sentence — the clone `CLAUDE.md` prohibits. What differs between them
+// is four fragments and nothing else, so those are the parameters and the shape is not.
+interface ReuseNotice {
+	// The noun phrase that `passed on it` is said of — `the unit tests`, `the type check`.
+	subject: string
+	// What the git operation about to happen carries, where the reader has a narrower condition than
+	// the gate's own. Empty for the gate, which speaks about the working tree it just read.
+	carried_clause: string
+	taken_at: string
+	// How a person runs the checks anyway: a flag where they type the command, a variable where the
+	// command line belongs to `lefthook/base.yml`.
+	force_hint: string
+	// What that hint re-runs, so the last clause reads as English in each caller — `the four checks`,
+	// `them`, `it`.
+	rerun_object: string
+}
+
+function format_reuse_notice(notice: ReuseNotice): string {
+	return (
+		`✔ this tree is already green — ${notice.subject} passed on it at ${notice.taken_at} ` +
+		`(\`pnpm josh gate\`)${notice.carried_clause}.\n` +
+		`  Reusing that result; nothing was re-run. \`${notice.force_hint}\` runs ${notice.rerun_object} anyway.`
+	)
+}
+
+function format_skip(taken_at: string): string {
+	return format_reuse_notice({
+		subject: 'lint, the type check, the spell check and the unit tests all',
+		carried_clause: '',
+		taken_at,
+		force_hint: `pnpm josh gate ${FORCE_FLAG}`,
+		rerun_object: 'the four checks',
+	})
+}
+
+const gate_skip = { FORCE_FLAG, format_reuse_notice, format_skip, reusable_green_gate }
+
+export type { ReuseNotice }
+
+export { gate_skip }

package/scripts/gate/gate-tree.ts

@@ -0,0 +1,49 @@
+import { change_base } from '#scripts/git/change-base'
+import { review_tree } from '#scripts/review/review-tree'
+
+// The two readings a green-gate record is written from and compared against: the digest of every
+// changed file, and the commit that map is a diff against (joshuafolkken/kit#1241,
+// joshuafolkken/kit#1328).
+//
+// They live here rather than inside `verification-gate.ts` because there are now two readers — the
+// gate, which reuses a green record instead of re-running its four checks, and the pre-push hook,
+// which reuses the same record instead of re-running the unit suite (joshuafolkken/kit#1334). A
+// second copy of the pair would be the clone `CLAUDE.md` prohibits, and it would not have stayed
+// identical: what these functions really encode is which failure direction is safe, and a copy is
+// where that decision gets made twice.
+//
+// **A failed read is `undefined` or an empty map, never a throw.** Neither reader is entitled to fail
+// because git could not answer; both are entitled to conclude that nothing can be reused. The gate
+// then runs its checks and the hook runs the suite, which is the direction that costs seconds rather
+// than correctness.
+
+interface GateTree {
+	files: Record<string, string>
+	base: string | undefined
+}
+
+async function read_changed_files(): Promise<Record<string, string>> {
+	try {
+		return await review_tree.read_changed_tree()
+	} catch {
+		return {}
+	}
+}
+
+// The resolver lives in `git/change-base.ts` since joshuafolkken/kit#1537, because the review brief
+// needs exactly this reading and a second copy of it is the clone `CLAUDE.md` prohibits.
+async function read_base(): Promise<string | undefined> {
+	return await change_base.resolved()
+}
+
+// The two readings are independent, so they are started together rather than one after the other.
+async function read_gate_tree(): Promise<GateTree> {
+	const [files, base] = await Promise.all([read_changed_files(), read_base()])
+
+	return { files, base }
+}
+
+const gate_tree = { read_base, read_changed_files, read_gate_tree }
+
+export type { GateTree }
+export { gate_tree }

package/scripts/gate/hook-gate-reuse.ts

@@ -0,0 +1,130 @@
+import { git_command } from '#scripts/git/git-command'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { observation_ledger } from '#scripts/observations/observation-ledger'
+import { gate_skip } from './gate-skip'
+import type { GateTree } from './gate-tree'
+
+// What the two git hooks share when they decline to re-run a check `pnpm josh gate` already passed on
+// this tree (joshuafolkken/kit#1381).
+//
+// The pre-push hook got this behavior first (joshuafolkken/kit#1334) and the pre-commit type check is
+// the second reader of the same record. Everything that is the same in both lives here rather than in
+// each of them: the escape hatch, the pre-filter in front of the record, and the one `git status`
+// reading both narrow themselves from. **The record comparison itself is not here either** — it is
+// `gate_skip.reusable_green_gate`, joshuafolkken/kit#1328's, so a hook cannot answer "is this tree
+// still the recorded one" differently from the gate printing its answer beside it.
+//
+// **Every condition added here only ever narrows.** The gate's own three — the file map matches, the
+// base commit the map is a diff against matches, and the map is non-empty — are necessary and never
+// sufficient for a hook, because the gate speaks about the **working tree** while a hook guards what a
+// git operation is about to carry. Where the two can differ, the hook runs the check. Any reading that
+// could not be taken fails the same way: "we could not tell" must never resolve to "no need to check".
+
+// The `josh` targets that decline a check on the strength of this record (joshuafolkken/kit#1786).
+//
+// **It is declared beside the mechanism rather than beside the reader.** `josh layers` reports which
+// checks run in more than one layer, and two of the rows it prints are not the repetition they look
+// like: the pre-commit type check and the pre-push unit run are skipped outright where a green gate
+// already covers the tree. A reader that carried its own copy of this list would go on printing a
+// retired name the day a hook is rewired, which is the drift `hook-gate-reuse.test.ts` pins by
+// comparing this list against the files that actually import this module.
+const GATE_REUSING_TARGETS: ReadonlyArray<string> = ['pre-commit-type-check', 'pre-push-unit']
+
+// `git status --porcelain` prints `XY PATH` per difference — `X` the index against HEAD, `Y` the
+// working tree against the index — so column 1 is the one that says whether the staged content is
+// what is on disk. An untracked file is `??`, which fails this test too.
+const WORKTREE_COLUMN = 1
+const UNMODIFIED = ' '
+
+// The escape hatch, for the times a person knows something outside the tree moved — a `pnpm install`,
+// a toolchain change, a cache thrown away. An environment variable rather than the gate's `--force`
+// flag because a hook's command line belongs to `lefthook/base.yml`: nobody types that invocation, so
+// a flag alone would be unreachable at the moment it is wanted. Each hook names its own variable and
+// passes it in, so the two escape hatches cannot be confused for one another.
+//
+// Any value at all, empty string aside: this is read from a shell, where `JOSH_…_FORCE=1` and
+// `JOSH_…_FORCE=true` are the two spellings a person reaches for and neither should be the one that
+// silently does nothing.
+function is_force_requested(force_environment: string): boolean {
+	return (process.env[force_environment] ?? '') !== ''
+}
+
+// `undefined` rather than an empty list when the reading failed, so a caller cannot mistake "git said
+// nothing" for "git could not be asked". Every predicate below treats the two differently.
+//
+// **The observation ledger is dropped from the reading, and it is the one line that may be**
+// (joshuafolkken/kit#1756). Since that issue `pnpm josh git` excludes `docs/observations.md` from
+// what it stages, so a parent's appended line sits modified-but-never-staged for the whole interval
+// between the append and the next `pnpm josh observations:flush` — and every condition below reads a
+// non-empty status as "this operation carries a tree no check has read". Left in, one ledger line
+// would send every commit and every push in the primary checkout back to the full gate for days,
+// which is the reuse this module exists to grant. **Dropping it is sound because nothing can carry
+// it**: the exclusion means the index and the push are byte-for-byte the recorded tree whatever the
+// ledger says, and the ledger's own content is checked by the CI of the pull request the flush opens.
+async function read_status_lines(): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		const status = await git_command.status()
+
+		return status
+			.split('\n')
+			.filter((line) => line !== '')
+			.filter((line) => !observation_ledger.is_ledger_line(line))
+	} catch {
+		return undefined
+	}
+}
+
+// The pre-push condition: nothing differs from HEAD at all, untracked files included, so the commit
+// being pushed is byte-for-byte the tree the record was taken from.
+function is_worktree_clean(lines: ReadonlyArray<string> | undefined): boolean {
+	return lines?.length === 0
+}
+
+// The pre-commit condition: the commit carries the **index**, so what must match the recorded working
+// tree is the index rather than HEAD. Staged-only entries (`M `, `A `, `R `) pass; an unstaged edit
+// (` M`), a partially staged file (`MM`) and an untracked file (`??`) each mean the commit is a tree no
+// check has read, and send the hook back to the full check.
+function is_index_matching_worktree(lines: ReadonlyArray<string> | undefined): boolean {
+	return lines?.every((line) => line[WORKTREE_COLUMN] === UNMODIFIED) === true
+}
+
+interface HookReuse {
+	// The gate's own two readings — the changed-file map and the commit it is a diff against — taken
+	// from `gate-tree.ts` rather than read a second way here.
+	tree: GateTree
+	// The hook-specific narrowing: whether what this git operation carries is the tree the record
+	// describes. `is_worktree_clean` for a push, `is_index_matching_worktree` for a commit.
+	is_tree_carried: boolean
+	extra_arguments: ReadonlyArray<string>
+	force_env: string
+	// The record to read, so a test can plant one without overwriting the record a live run relies on.
+	// `| undefined` is explicit because `exactOptionalPropertyTypes` is on: each hook passes its own
+	// optional parameter straight through, and omitting it would refuse the value it always has.
+	source?: string | undefined
+}
+
+// The stamp rather than a boolean, for the same reason `gate_skip.reusable_green_gate` hands one back:
+// the caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
+// printing.
+//
+// **Any argument at all refuses the reuse**, not only the force flag. A caller who narrowed the run
+// asked for that run rather than for a recorded result about a whole tree, and a hook's own line passes
+// none, so this costs it nothing.
+function reusable_green_hook(input: HookReuse): FileMapStamp | undefined {
+	if (input.extra_arguments.length > 0 || is_force_requested(input.force_env)) return undefined
+	if (!input.is_tree_carried) return undefined
+
+	return gate_skip.reusable_green_gate(input.tree.files, input.tree.base, input.source)
+}
+
+const hook_gate_reuse = {
+	GATE_REUSING_TARGETS,
+	is_force_requested,
+	is_index_matching_worktree,
+	is_worktree_clean,
+	read_status_lines,
+	reusable_green_hook,
+}
+
+export type { HookReuse }
+export { hook_gate_reuse }

package/scripts/gate/pre-commit-type-check.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { execa } from 'execa'
+import { gate_skip } from './gate-skip'
+import { gate_tree, type GateTree } from './gate-tree'
+import { hook_gate_reuse } from './hook-gate-reuse'
+import { DEFAULT_TYPE_CHECK_ARGS, type_check_step } from './type-check-step'
+
+// The pre-commit hook's type check, which no longer re-runs a project-wide `tsc --noEmit` that a green
+// gate already covers (joshuafolkken/kit#1381).
+//
+// Measured on this repository: `pnpm exec tsc --noEmit` over the whole project takes 3.8–4.4s warm, and
+// `pnpm josh git -y` pays it on every commit — a `fullrun` commits twice — seconds after `pnpm josh
+// gate` printed the same project-wide type check green on the same tree. The pre-commit hook runs its
+// commands in parallel, so that one check is what the hook's wall time was.
+//
+// **It is the one project-wide check left in the hook.** cspell, prettier and eslint there read only
+// `{staged_files}`, which is a different scope from the gate's project-wide run and costs 0.3–1.0s each
+// in parallel; skipping them would buy about half a second and would trade a narrow reading for a
+// recorded wide one. So they are untouched, and so are `prevent-main-commit` and `secretlint`, which
+// the gate does not run at all and which are therefore duplicates of nothing.
+//
+// **The decision is joshuafolkken/kit#1328's, imported rather than restated** — `hook_gate_reuse`
+// carries what this shares with the pre-push hook (joshuafolkken/kit#1334) and defers the record
+// comparison itself to `gate_skip.reusable_green_gate`. A hook answering "is this still the recorded
+// tree" differently from the gate beside it would be two commands disagreeing about one tree.
+//
+// **What this adds is one condition, and it only ever narrows.** The record describes the **working
+// tree**; a commit carries the **index**. Stage half of a green tree and the map still matches while the
+// commit being made is a tree no check ever read. So the reuse also requires the index to match the
+// working tree — which is what `pnpm josh git` leaves behind once it has staged — and any doubt whatever
+// sends the hook back to the full check.
+
+// The escape hatch's name; the shared reading of it is `hook_gate_reuse.is_force_requested`.
+const FORCE_ENV = 'JOSH_PRE_COMMIT_FORCE'
+
+const PNPM = 'pnpm'
+
+// Exactly what `lefthook/base.yml` ran before this wrapper existed. **The set of checks is unchanged**:
+// what changes is only whether an already-passed check is executed again on an unchanged tree.
+const TYPE_CHECK_ARGUMENTS: ReadonlyArray<string> = ['exec', 'tsc', '--noEmit']
+
+// What an argument this command does not take exits with. A type error's own code comes from `tsc`.
+const REFUSED_EXIT_CODE = 1
+
+// `process.argv` is [runner, script, ...arguments].
+const FIRST_ARGUMENT_INDEX = 2
+
+// The gate's own two readings plus the one this hook adds.
+interface CommitTree extends GateTree {
+	is_index_matching_worktree: boolean
+}
+
+// **The record says the gate's four checks were green; it does not say *which* type check ran.**
+// `type-check-step.ts` resolves that per project (joshuafolkken/kit#934): a project carrying a
+// `josh-app` / `josh-game` shim has the toolkit's `check:ci` as its gate step, and this hook's step is
+// `tsc --noEmit`. Reusing across that difference would skip `tsc --noEmit` on the strength of a
+// different check — a `.ts` file inside the root `tsconfig.json` but outside the one `svelte-check` is
+// pointed at is exactly the error that would then reach a commit.
+//
+// So the reuse is refused wherever the two are not the same command, and the resolution is asked of
+// `type_check_step` rather than re-derived here. **The hook's own command is unchanged either way**:
+// what this narrows is only when an identical check is not re-run.
+//
+// **The `catch` is the module's invariant, not defensiveness**: a reading that could not be taken says
+// nothing about which check ran, and "we could not tell" must resolve to running the check.
+async function is_recorded_check_this_check(start_directory: string): Promise<boolean> {
+	try {
+		const resolved = await type_check_step.resolve_type_check_args(start_directory)
+
+		return resolved.join(' ') === DEFAULT_TYPE_CHECK_ARGS.join(' ')
+	} catch {
+		return false
+	}
+}
+
+// The readings are independent, so they are started together rather than one after the other.
+async function read_commit_tree(): Promise<CommitTree> {
+	const [tree, lines] = await Promise.all([
+		gate_tree.read_gate_tree(),
+		hook_gate_reuse.read_status_lines(),
+	])
+
+	return { ...tree, is_index_matching_worktree: hook_gate_reuse.is_index_matching_worktree(lines) }
+}
+
+// **The type-check identity is asked last, because it is the only reading that can spawn a process.**
+// `resolve_type_check_args` probes a toolkit shim for its usage line, and on a project that has one the
+// reuse is refused anyway — so asking it before the record had matched would put a subprocess on the
+// force path, on a dirty index, and on every commit of a project that can never reuse.
+async function reusable_green_commit(
+	tree: CommitTree,
+	extra_arguments: ReadonlyArray<string>,
+	source?: string,
+	start_directory: string = process.cwd(),
+): Promise<FileMapStamp | undefined> {
+	const reusable = hook_gate_reuse.reusable_green_hook({
+		tree,
+		is_tree_carried: tree.is_index_matching_worktree,
+		extra_arguments,
+		force_env: FORCE_ENV,
+		source,
+	})
+
+	if (reusable === undefined) return undefined
+
+	return (await is_recorded_check_this_check(start_directory)) ? reusable : undefined
+}
+
+// **Nothing is forwarded to `tsc`, and an argument is refused rather than dropped.** `tsc --noEmit
+// <file>` ignores `tsconfig.json`, so forwarding a path would silently narrow the very check this
+// command exists to run in full — and ignoring the argument in silence would look like it had been
+// honored. `--force` is the one argument this command takes, and it is consumed here.
+function format_refusal(unexpected: ReadonlyArray<string>): string {
+	return (
+		`✗ josh pre-commit-type-check takes no argument but \`${gate_skip.FORCE_FLAG}\`; ` +
+		`refusing ${unexpected.join(' ')}.\n` +
+		`  It type-checks the whole project, so a path here would narrow the check rather than scope it.`
+	)
+}
+
+function format_skip(taken_at: string): string {
+	return gate_skip.format_reuse_notice({
+		subject: 'the type check',
+		carried_clause: ', and this commit carries that same tree',
+		taken_at,
+		force_hint: `${FORCE_ENV}=1 git commit`,
+		rerun_object: 'it',
+	})
+}
+
+// The exit code is resolved through `spawn-exit.ts` rather than `exitCode ?? 1`, so a spawn that never
+// produced a code — `tsc` missing from PATH — is reported as such instead of being reported as a type
+// error. Either way it is non-zero and the commit is blocked.
+async function run_type_check(): Promise<number> {
+	const result = await execa(PNPM, [...TYPE_CHECK_ARGUMENTS], { stdio: 'inherit', reject: false })
+
+	return resolve_spawn_exit(PNPM, result)
+}
+
+function unexpected_arguments(extra_arguments: ReadonlyArray<string>): ReadonlyArray<string> {
+	return extra_arguments.filter((argument) => argument !== gate_skip.FORCE_FLAG)
+}
+
+async function run_pre_commit_type_check(
+	extra_arguments: ReadonlyArray<string> = [],
+	source?: string,
+): Promise<number> {
+	const unexpected = unexpected_arguments(extra_arguments)
+
+	if (unexpected.length > 0) {
+		process.stderr.write(`${format_refusal(unexpected)}\n`)
+
+		return REFUSED_EXIT_CODE
+	}
+
+	const reusable = await reusable_green_commit(await read_commit_tree(), extra_arguments, source)
+
+	if (reusable === undefined) return await run_type_check()
+
+	process.stdout.write(`${format_skip(reusable.taken_at)}\n`)
+
+	return 0
+}
+
+// `process.exitCode` rather than `process.exit()`: a non-zero code has to block the commit, and exiting
+// outright truncates a piped stdout — which for a failing type check is the output that says why.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_pre_commit_type_check(process.argv.slice(FIRST_ARGUMENT_INDEX))
+}
+
+const pre_commit_type_check = {
+	FORCE_ENV,
+	TYPE_CHECK_ARGUMENTS,
+	format_refusal,
+	format_skip,
+	is_recorded_check_this_check,
+	read_commit_tree,
+	reusable_green_commit,
+	run_pre_commit_type_check,
+	unexpected_arguments,
+}
+
+export type { CommitTree }
+export { pre_commit_type_check }