@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/gate/verification-gate.ts

@@ -1,19 +1,18 @@
 #!/usr/bin/env tsx
-import { availableParallelism } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { lane_ledger } from '#scripts/lane/lane-ledger'
-import { bounded_pool } from '#scripts/lib/bounded-pool'
-import { buffered_process, FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
+import { FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
-import { core_budget } from './core-budget'
+import { check_reuse, type CheckRecords } from './check-reuse'
 import { gate_ledger, type GateLedgerStart } from './gate-ledger'
 import { gate_plan, type GatePlan } from './gate-plan'
-import { gate_report, type GateStep, type GateStepResult } from './gate-report'
+import { gate_report, type GateStepResult } from './gate-report'
+import { gate_run_steps, type ReusedChecks } from './gate-run-steps'
 import { gate_skip } from './gate-skip'
 import { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG } from './gate-steps'
 import { gate_tree, type GateTree } from './gate-tree'
@@ -35,25 +34,6 @@ const { GATE_CHECKS } = gate_plan
 
 const GATE_TARGETS: ReadonlyArray<string> = GATE_CHECKS.map((check) => check.target)
 
-async function run_gate_step(step: GateStep): Promise<GateStepResult> {
-	if (step.skip_reason !== undefined) {
-		return {
-			label: step.label,
-			command: step.command_args.join(' '),
-			output: project_checks.skip_notice('check', step.skip_reason),
-			exit_code: 0,
-			elapsed_ms: 0,
-		}
-	}
-
-	const result = await buffered_process.run_buffered_process(
-		step.command_args,
-		step.cwd === undefined ? {} : { cwd: step.cwd },
-	)
-
-	return { label: step.label, command: step.command_args.join(' '), ...result }
-}
-
 // The record `josh review:brief` reads, written only on a fully green run and only with the tree it
 // was green on. `/code-review` runs in a forked process that reads none of
 // this repository's documents, so "the unit tests already passed" reaches it only if the invocation
@@ -65,7 +45,7 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 // visible on the console, and a record erasing it would have the brief tell a review agent not to
 // re-run tests that never ran. A skip of a tool the project does not use (`NOT_USED_MARKER` — eslint
 // with no ESLint configuration) is not one: nothing went unverified, so it withholds nothing
-// (`gate_report.is_unverified_skip`). A step that passed **with a checker's warnings** is withheld for the
+// (`gate_report.has_nothing_to_say`). A step that passed **with a checker's warnings** is withheld for the
 // same reason one place further on: since the record is reused instead of the checks being re-run, a
 // warning printed once would never be printed again on that tree, and hiding an eslint or
 // svelte-check finding is the same failure as hiding a skip. It is `has_checker_warning`, not
@@ -81,17 +61,13 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 //
 // The destination is a parameter so a test can exercise the record without overwriting the one a
 // real run may be relying on — `josh gate` and `josh review:brief` share one path by design.
-function has_nothing_to_say(result: GateStepResult): boolean {
-	return !gate_report.is_unverified_skip(result) && !gate_report.has_checker_warning(result)
-}
-
 async function record_green_gate(
 	results: ReadonlyArray<GateStepResult>,
 	before: Record<string, string>,
 	target?: string,
 	base?: string,
 ): Promise<void> {
-	if (results.some((result) => !has_nothing_to_say(result))) return
+	if (results.some((result) => !gate_report.has_nothing_to_say(result))) return
 
 	try {
 		const after = await review_tree.read_changed_tree()
@@ -153,94 +129,6 @@ async function with_gate_marker<T>(
 	}
 }
 
-// This gate's share of the machine, resolved once at the gate's entry and carried down as one value.
-// `available_cores` is the budget every check reserves against; `is_reserved`
-// is false for a gate nested inside another gate's unit suite — this repository's own gate tests — so
-// the outer gate reserves and every gate beneath it does not. Captured before this gate sets
-// `JOSH_UNIT_RUN_MARKED`, which is why it is read at entry rather than re-derived here.
-interface BudgetContext {
-	available_cores: number
-	is_reserved: boolean
-}
-
-function default_budget(): BudgetContext {
-	return {
-		available_cores: availableParallelism(),
-		is_reserved: !unit_worker_share.is_nested_run() && !core_budget.is_held(),
-	}
-}
-
-// A gate step paired with the cores it reserves from the machine-wide budget while it runs.
-// The weight travels with the step so `run_gate_steps` never has to re-pair a
-// step with its check by index.
-interface ReservedStep {
-	step: GateStep
-	weight: number
-	memory_mb: number
-}
-
-async function build_reserved_steps(
-	start_directory: string,
-	plan: GatePlan,
-	available_cores: number,
-): Promise<ReadonlyArray<ReservedStep>> {
-	return await Promise.all(
-		plan.checks.map(async (check) => ({
-			step: await build_gate_step(check, start_directory, plan),
-			weight: gate_plan.check_weight(check, plan, available_cores),
-			memory_mb: gate_plan.check_memory(check, plan, available_cores),
-		})),
-	)
-}
-
-// **A nested gate takes no reservation, and the budget is what makes that necessary rather than
-// merely tidy**. The unit step spawns the suite, which runs this repository's
-// own gate tests; each of those is a gate inside the outer gate's unit reservation, and a place it
-// claimed would wait for cores the outer gate cannot free until the suite — this test included —
-// finishes.
-async function run_reserved_step(
-	reserved: ReservedStep,
-	budget: BudgetContext,
-): Promise<GateStepResult> {
-	if (!budget.is_reserved) return await run_gate_step(reserved.step)
-
-	return await core_budget.with_core_reservation(
-		reserved.weight,
-		async (admission) => ({
-			...(await run_gate_step(reserved.step)),
-			budget_note: core_budget.describe_overflow(admission),
-		}),
-		{ budget: budget.available_cores, memory_mb: reserved.memory_mb },
-	)
-}
-
-// `bounded_pool` rather than a bare `Promise.all`, so the plan's `concurrency` is what decides how
-// many run at once. **The all-failures-in-one-pass property survives the
-// change** because no check ever rejects: `buffered_process` reports a non-zero exit as a value, so
-// the pool's first-failure abort — written for callers that spawn real Claude sessions — never
-// fires here and every queued check still runs. Results come back in input order however they
-// finished, which is what keeps the printed sections in declaration order. Each step first claims its
-// place in the machine-wide budget and waits while the budget is full.
-async function run_gate_steps(
-	plan: GatePlan,
-	budget: BudgetContext = default_budget(),
-): Promise<ReadonlyArray<GateStepResult>> {
-	const reserved = await build_reserved_steps(process.cwd(), plan, budget.available_cores)
-
-	// **The checks run under the held mark, so a check's own dispatch claims nothing**.
-	// Each check is a `pnpm josh <target>` child, and a target that declares
-	// a weight would otherwise claim a second place for the cores reserved for it here. A nested gate
-	// sets the mark too, since its checks are covered by the outer gate's reservation.
-	return await core_budget.with_held_mark(
-		async () =>
-			await bounded_pool.bounded_map(
-				reserved,
-				plan.concurrency,
-				async (entry) => await run_reserved_step(entry, budget),
-			),
-	)
-}
-
 // **Both markers are claims about the unit suite, so a gate that is not running it makes neither**.
 // The in-flight marker tells the next `josh review:brief` that a gate is
 // covering this tree right now, which is what stops a review agent re-running the suite; the
@@ -276,6 +164,10 @@ async function run_marked_gate<T>(
 // The concurrent-run count is read here rather than inside `gate-plan.ts` for the reason the core
 // count already is: that module stays a pure function of its inputs, and the machine is asked once and
 // handed to both calls. Counted *before* the unit step writes its own marker, so `+ 1` is this gate.
+//
+// **The free cores do not cap the plan** (joshuafolkken/kit#4167). The unit claim's admission narrows it
+// to the room the outside load leaves, read over its wait rather than once at the gate's start — a
+// width fixed off one busy instant held for the whole suite (`core_admission.is_too_narrow`).
 function announce_gate_plan(is_unit_included: boolean, available_cores: number): GatePlan {
 	const concurrent_runs = unit_worker_share.live_run_count() + unit_worker_share.SOLO_RUNS
 	const is_kit_repository = project_checks.is_kit_repository(process.cwd())
@@ -319,6 +211,31 @@ interface GateOptions {
 	// The lane ledger a finished gate's duration is appended to. Only the CLI
 	// entry resolves it, so a suite driving the gate never writes a measurement of checks that never ran.
 	ledger_path?: string | undefined
+	// Where each check's own green record lives (`check-reuse.ts`). Only the CLI entry resolves it, for
+	// the ledger's reason: a suite whose checks never ran must not record them green on the live tree.
+	check_records?: CheckRecords | undefined
+}
+
+// **Per-check records belong to the full local gate alone**: CI's `--no-unit` gate is the safety net
+// under the local reuse and stays as it was, so it neither reads nor writes one.
+function check_records_of(plan: GatePlan, options: GateOptions): CheckRecords | undefined {
+	return gate_plan.has_unit_check(plan.checks) ? options.check_records : undefined
+}
+
+async function checks_to_reuse(
+	plan: GatePlan,
+	tree: GateTree,
+	options: GateOptions,
+): Promise<ReusedChecks> {
+	const records = check_records_of(plan, options)
+
+	if (records === undefined || options.is_forced === true) return new Map()
+
+	return await check_reuse.reusable_checks(
+		plan.checks.map((check) => check.label),
+		tree,
+		records,
+	)
 }
 
 // **The gate refuses to start when the scoped pair has not been green on this tree**
@@ -374,6 +291,10 @@ async function settle_gate(
 
 	await gate_ledger.record(options.ledger, results, { elapsed_ms, is_passed })
 
+	const records = check_records_of(plan, options)
+
+	if (records !== undefined) await check_reuse.record_green_checks(results, tree, records)
+
 	if (!is_passed) return FAIL_EXIT_CODE
 
 	await record_whole_gate(plan, results, tree, options)
@@ -396,8 +317,9 @@ async function run_checked_gate(
 	const ledger = await gate_ledger.start(options.ledger_path)
 	// Resolved at the gate's entry, before this gate sets `JOSH_UNIT_RUN_MARKED`, so a gate nested in the
 	// unit suite reads the flag as set and reserves nothing.
-	const budget = default_budget()
+	const budget = gate_run_steps.default_budget()
 	const plan = announce_gate_plan(is_unit_included, budget.available_cores)
+	const reused = await checks_to_reuse(plan, tree, options)
 
 	// **The gate holds the unit-run marker for its whole run, not just its unit step.** The step that
 	// would write it is a subprocess started a second or so after the count above, so two lanes launched
@@ -406,7 +328,7 @@ async function run_checked_gate(
 	// the next lane asks; the guard inside the spawned `josh test:unit` sees the handoff and adds no
 	// second marker for the same run.
 	async function run_and_settle(): Promise<number> {
-		const results = await run_gate_steps(plan, budget)
+		const results = await gate_run_steps.run_gate_steps(plan, budget, reused)
 
 		return await settle_gate(plan, results, tree, { ...options, started_at, ledger })
 	}
@@ -422,17 +344,30 @@ function reusable_stamp(tree: GateTree, options: GateOptions): FileMapStamp | un
 	return gate_skip.reusable_green_gate(tree.files, tree.base, options.stamp_path)
 }
 
+// The reuse leaves its line in the ledger too, so `josh lane:stats` counts the gates it saved
+// (joshuafolkken/kit#4397).
+async function reuse_gate(
+	stamp: FileMapStamp,
+	options: GateOptions,
+	started_at: number,
+): Promise<number> {
+	process.stdout.write(`${gate_skip.format_skip(stamp.taken_at)}\n`)
+	await gate_ledger.record_reused(options.ledger_path, performance.now() - started_at)
+
+	return 0
+}
+
 // The two ways a gate ends before it runs a check: a green record it can reuse (exit 0), and the
 // scoped pre-check refusing a tree the pair has not been green on (exit 1). `undefined` means neither
 // fired and the checks run. **Nothing else stands between the skip and the checks.**
-function short_circuit_gate(tree: GateTree, options: GateOptions): number | undefined {
+async function short_circuit_gate(
+	tree: GateTree,
+	options: GateOptions,
+	started_at: number,
+): Promise<number | undefined> {
 	const reusable = reusable_stamp(tree, options)
 
-	if (reusable !== undefined) {
-		process.stdout.write(`${gate_skip.format_skip(reusable.taken_at)}\n`)
-
-		return 0
-	}
+	if (reusable !== undefined) return await reuse_gate(reusable, options, started_at)
 
 	const scoped_refusal = scoped_precheck_refusal(tree, options)
 
@@ -448,7 +383,7 @@ async function run_verification_gate(options: GateOptions = {}): Promise<number>
 	// four checks alone took — the gate's own bookkeeping is part of the wait either way.
 	const started_at = performance.now()
 	const tree = await gate_tree.read_gate_tree()
-	const short_circuit = short_circuit_gate(tree, options)
+	const short_circuit = await short_circuit_gate(tree, options, started_at)
 
 	if (short_circuit !== undefined) return short_circuit
 
@@ -506,6 +441,7 @@ async function run_gate_command(
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_gate_command(process.argv.slice(FIRST_ARGUMENT_INDEX), {
 		ledger_path: await lane_ledger.target(),
+		check_records: check_reuse.DEFAULT_RECORDS,
 	})
 }
 
@@ -519,11 +455,11 @@ const verification_gate = {
 	clear_gate_running,
 	mark_gate_running,
 	record_green_gate,
-	run_gate_steps,
+	run_gate_steps: gate_run_steps.run_gate_steps,
 	scoped_precheck_refusal,
 	with_gate_marker,
 	run_gate_command,
-	run_gate_step,
+	run_gate_step: gate_run_steps.run_gate_step,
 	run_verification_gate,
 }
 

package/scripts/gate/verification-inputs.ts

@@ -0,0 +1,250 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { lint_related_scope } from '#scripts/lint/lint-related-scope'
+import { gate_plan } from './gate-plan'
+import { input_fingerprint } from './input-fingerprint'
+import { toolchain_inputs } from './toolchain-inputs'
+
+// **What each verification depends on, declared once** (joshuafolkken/kit#4495). Every reuse of a
+// verdict — the whole gate (`gate-skip.ts`), one check (`check-reuse.ts`), a scoped record
+// (`scoped-green.ts`) and the since-green narrowing (`since-green.ts`) — answers from the declaration
+// here — the paths through `check-inputs.ts`, the tools and environment through `fingerprint` — so a
+// new reuse picks a declaration rather than writing its own invalidation.
+//
+// A declaration names:
+// - `is_input` — whether a path is a content input; `undefined` leaves it to `reads`.
+// - `reads` — `matched`: the inputs are the paths `is_input` accepts. `recorded`: the inputs are the
+//   files a run read, as the run recorded them — the test-read map (joshuafolkken/kit#4314), whose
+//   file digests are `input-fingerprint.ts`'s — so a path is an input only when some recorded test
+//   reads it.
+// - `is_config` — the files that configure the check: one that moves invalidates the verdict whatever
+//   else moved, and stops the since-green narrowing.
+// - `tools` — the packages whose installed version runs the check.
+// - `env` — the environment variables whose value changes the verdict.
+//
+// **A check with no declaration always runs**: `cspell` reads every text file and `behavior` reads a
+// transcript outside the tree. Naming inputs for either would be a guess, and a wrong guess is a check
+// reported green without having run. **The declarations over-approximate, never under**: a path in
+// doubt is an input. `metrics` reads the scripts it counts, the approvals under
+// `.josh/metrics-accepted/` (JSON) and the Markdown it measures (joshuafolkken/kit#4085). `lint` is
+// prettier plus eslint, so its inputs are the sources plus every file prettier formats, less what
+// prettier's own ignore files leave out — prettier answers that itself (`check-inputs.ts`).
+
+const GIT_IGNORE = '.gitignore'
+const PRETTIER_IGNORE = '.prettierignore'
+const PRETTIER_IGNORE_FILES = [GIT_IGNORE, PRETTIER_IGNORE] as const
+
+// A manifest or lock file moves the installed tools (`toolchain-inputs.ts`, the list every kept result
+// shares), and an ignore or editor file moves what prettier formats — a configuration of every
+// declared check.
+const MANIFEST = 'package.json'
+
+const TOOLCHAIN_FILES: ReadonlySet<string> = new Set([
+	...toolchain_inputs.PACKAGE_FILES.map((relative) => path.basename(relative)),
+	'.editorconfig',
+	...PRETTIER_IGNORE_FILES,
+])
+
+const PRETTIER_CONFIG_PREFIX = '.prettierrc'
+
+// A file name starting with one of these configures the TypeScript program a check compiles, and the
+// test runner for the unit step.
+const COMPILER_CONFIG_PREFIXES = ['tsconfig', 'svelte.config.'] as const
+const TEST_CONFIG_PREFIXES = [...COMPILER_CONFIG_PREFIXES, 'vitest.config.', 'vite.config.']
+
+// A file name starting with one of these, or a path under one of the directories, configures prettier,
+// eslint or the TypeScript program its type-aware rules read. Prettier keys its cache on the options
+// too, so a changed `prettier.config.*` re-checks every file the whole-tree run reads.
+const LINT_CONFIG_PREFIXES = ['eslint.config.', 'prettier.config.', ...COMPILER_CONFIG_PREFIXES]
+const LINT_CONFIG_DIRECTORIES: ReadonlySet<string> = new Set(['eslint', 'prettier', 'tsconfig'])
+
+const SOURCE_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.vue',
+	'.json',
+	'.jsonc',
+])
+
+const MARKDOWN_EXTENSION = '.md'
+// `NODE_OPTIONS` is left out: package managers and hooks set it differently around the same check,
+// and it tunes the runtime rather than what a check answers.
+const COMMON_ENV = ['NODE_ENV'] as const
+const ABSENT = 'absent'
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+// Whether prettier would leave `relative` out; `false` when prettier cannot be asked, which keeps the
+// path an input.
+type PrettierIgnored = (relative: string) => Promise<boolean>
+
+type FileTest = (relative: string, is_ignored: PrettierIgnored) => Promise<boolean>
+
+type InputReads = 'matched' | 'recorded'
+
+interface InputDeclaration {
+	readonly is_input: FileTest | undefined
+	readonly reads: InputReads
+	readonly is_config: (relative: string) => boolean
+	readonly tools: ReadonlyArray<string>
+	readonly env: ReadonlyArray<string>
+}
+
+function is_source(relative: string): boolean {
+	return SOURCE_EXTENSIONS.has(path.extname(relative))
+}
+
+async function is_lint_input(relative: string, is_ignored: PrettierIgnored): Promise<boolean> {
+	if (is_source(relative)) return true
+	if (!lint_related_scope.is_lintable(relative)) return false
+
+	return !(await is_ignored(relative))
+}
+
+async function is_source_input(relative: string): Promise<boolean> {
+	return is_source(relative)
+}
+
+async function is_metrics_input(relative: string): Promise<boolean> {
+	return is_source(relative) || path.extname(relative) === MARKDOWN_EXTENSION
+}
+
+function configures_toolchain(relative: string): boolean {
+	const name = path.basename(relative)
+
+	return TOOLCHAIN_FILES.has(name) || name.startsWith(PRETTIER_CONFIG_PREFIX)
+}
+
+function names_any(relative: string, prefixes: ReadonlyArray<string>): boolean {
+	const name = path.basename(relative)
+
+	return configures_toolchain(relative) || prefixes.some((prefix) => name.startsWith(prefix))
+}
+
+function configures_compiler(relative: string): boolean {
+	return names_any(relative, COMPILER_CONFIG_PREFIXES)
+}
+
+function configures_tests(relative: string): boolean {
+	return names_any(relative, TEST_CONFIG_PREFIXES)
+}
+
+function configures_lint(relative: string): boolean {
+	const [top = ''] = relative.split('/', 1)
+
+	return LINT_CONFIG_DIRECTORIES.has(top) || names_any(relative, LINT_CONFIG_PREFIXES)
+}
+
+const LINT: InputDeclaration = {
+	is_input: is_lint_input,
+	reads: 'matched',
+	is_config: configures_lint,
+	tools: ['prettier', 'eslint', 'typescript'],
+	env: COMMON_ENV,
+}
+
+const UNIT: InputDeclaration = {
+	is_input: undefined,
+	reads: 'recorded',
+	is_config: configures_tests,
+	tools: ['vitest', 'typescript'],
+	env: [...COMMON_ENV, 'TZ'],
+}
+
+function compiled(is_input: FileTest): InputDeclaration {
+	return {
+		is_input,
+		reads: 'matched',
+		is_config: configures_compiler,
+		tools: ['typescript'],
+		env: COMMON_ENV,
+	}
+}
+
+const DECLARATIONS: ReadonlyMap<string, InputDeclaration> = new Map([
+	[gate_plan.LINT_LABEL, LINT],
+	[gate_plan.TYPE_CHECK_LABEL, compiled(is_source_input)],
+	[gate_plan.EXPORTS_LABEL, compiled(is_source_input)],
+	[gate_plan.METRICS_LABEL, compiled(is_metrics_input)],
+	[gate_plan.UNIT_LABEL, UNIT],
+])
+
+function declaration_of(label: string): InputDeclaration | undefined {
+	return DECLARATIONS.get(label)
+}
+
+function is_declared(label: string): boolean {
+	return DECLARATIONS.has(label)
+}
+
+// Whether any of `relatives` (repository-root relative) configures the check `label` — `true` for an
+// undeclared one, which no narrowing can read past.
+function configures(label: string, relatives: ReadonlyArray<string>): boolean {
+	const declaration = DECLARATIONS.get(label)
+
+	return declaration === undefined || relatives.some((relative) => declaration.is_config(relative))
+}
+
+function tool_version(root: string, tool: string): string {
+	try {
+		const manifest: unknown = JSON.parse(
+			readFileSync(path.join(root, 'node_modules', tool, MANIFEST), 'utf8'),
+		)
+
+		return typeof manifest === 'object' && manifest !== null && 'version' in manifest
+			? String(manifest.version)
+			: ABSENT
+	} catch {
+		return ABSENT
+	}
+}
+
+function entries_of(
+	declaration: InputDeclaration,
+	root: string,
+	environment: Environment,
+): ReadonlyArray<string> {
+	return [
+		...declaration.tools.map((tool) => `tool:${tool}=${tool_version(root, tool)}`),
+		...declaration.env.map((name) => `env:${name}=${environment[name] ?? ABSENT}`),
+	]
+}
+
+// **The fingerprint of what the checks `labels` read beside the files**: the installed version of every
+// declared tool and the value of every declared environment variable, sorted into one digest. The
+// file contents are the record's own file map (`file-map-stamp.ts`) and the merge base its `base`, so a
+// reuse matches all three. One label answers a check's record; every declared label the whole gate's.
+function fingerprint(
+	labels: ReadonlyArray<string>,
+	root: string = PROJECT_ROOT,
+	environment: Environment = process.env,
+): string {
+	const declarations = labels.flatMap((label) => DECLARATIONS.get(label) ?? [])
+	const entries = new Set(
+		declarations.flatMap((declaration) => entries_of(declaration, root, environment)),
+	)
+
+	return input_fingerprint.of_entries(entries)
+}
+
+const DECLARED_LABELS: ReadonlyArray<string> = [...DECLARATIONS.keys()]
+
+const verification_inputs = {
+	configures,
+	declaration_of,
+	DECLARED_LABELS,
+	fingerprint,
+	is_declared,
+	PRETTIER_IGNORE_FILES,
+}
+
+export type { InputDeclaration, InputReads, PrettierIgnored }
+export { verification_inputs }

package/scripts/gh/gh-author-association.ts

@@ -1,14 +1,101 @@
-// Whose words kit acts on: the `author_association` REST reports with an issue or a comment, and the
-// ones that can write to the repository. On a public repository anyone can file an issue or comment,
-// so a body kit runs (`josh measure:rerun`) or copies into the ledger (`review:record`) is taken only
-// from an author with write access — and an unknown author is not a trusted one.
-const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
-const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
 
-function is_trusted(association: string | null | undefined): boolean {
-	return typeof association === 'string' && TRUSTED_ASSOCIATIONS.has(association)
+// Whose words kit acts on: the author of an issue or a comment who can write to the repository. On a
+// public repository anyone can file an issue or comment, so a body kit runs (`josh measure:rerun`) or
+// copies into the ledger (`review:record`) is taken only from an author with write access — and an
+// unknown author is not a trusted one.
+//
+// **`author_association` alone does not say "can write"** (joshuafolkken/kit#4037). `OWNER` does, so it
+// is trusted without a request. `MEMBER` is any member of the owning org, whatever their access to this
+// repository, and `COLLABORATOR` includes outside collaborators with read or triage access only — so
+// those two are asked of the collaborator-permission endpoint, once per login per process, and trusted
+// only on a write role. A lookup that fails is not trust.
+const OWNER = 'OWNER'
+const ASKED_ASSOCIATIONS: ReadonlySet<string> = new Set(['MEMBER', 'COLLABORATOR'])
+const WRITE_ROLES: ReadonlySet<string> = new Set(['admin', 'maintain', 'write'])
+// A GitHub user login, an Enterprise Managed User's `name_shortcode` included — it is placed in a REST
+// path, so anything else (a `[bot]` login, a slash) is refused before a request is made.
+const LOGIN_PATTERN = /^[\da-z](?:[\w-]*[\da-z])?$/iu
+const TRUSTED_LIST = 'OWNER, or MEMBER / COLLABORATOR with write access'
+
+const permission_schema = z.looseObject({
+	permission: z.string().nullish(),
+	role_name: z.string().nullish(),
+})
+
+// `timeout_ms` bounds the lookup for a caller inside a hook's own timeout (`issue-watch`).
+interface Author {
+	login: string | undefined
+	association: string | null | undefined
+	timeout_ms?: number | undefined
+}
+
+const answers = new Map<string, Promise<boolean | undefined>>()
+
+function permission_path(login: string): string {
+	return `${git_gh_api_path.repo_api_path()}/collaborators/${login}/permission`
+}
+
+// `role_name` names `maintain` exactly; `permission` folds it into `write`, so either answers.
+function has_write_role(raw: string): boolean {
+	const parsed = parse_json.parse_json_object_or_undefined(raw, permission_schema)
+	const roles = [parsed?.role_name, parsed?.permission]
+
+	return roles.some((role) => typeof role === 'string' && WRITE_ROLES.has(role))
+}
+
+// `undefined` for a lookup that failed, which is not an answer.
+async function ask_permission(login: string, timeout_ms?: number): Promise<boolean | undefined> {
+	try {
+		const raw = await git_gh_exec.exec_gh_api({ path: permission_path(login), timeout_ms })
+
+		return has_write_role(raw)
+	} catch {
+		return undefined
+	}
+}
+
+// A failed lookup is not remembered: the backlog driver keeps one process for hours, so one dropped
+// request would otherwise leave that author unanswered until it restarts. Only the caller's own
+// request is evicted, never a newer one another caller has stored since.
+async function can_write(login: string, timeout_ms?: number): Promise<boolean | undefined> {
+	const asked = answers.get(login) ?? ask_permission(login, timeout_ms)
+
+	answers.set(login, asked)
+
+	const has_write = await asked
+
+	if (has_write === undefined && answers.get(login) === asked) answers.delete(login)
+
+	return has_write
+}
+
+function is_user_login(login: string | undefined): login is string {
+	return login !== undefined && LOGIN_PATTERN.test(login)
+}
+
+function is_asked(author: Author): boolean {
+	return ASKED_ASSOCIATIONS.has(author.association ?? '') && is_user_login(author.login)
+}
+
+// `undefined` when the lookup failed: neither trusted nor refused, for a caller that must not settle a
+// permanent answer on it (`review-comment-round`).
+async function trust_of(author: Author): Promise<boolean | undefined> {
+	if (author.association === OWNER) return true
+	if (author.login === undefined || !is_asked(author)) return false
+
+	return await can_write(author.login, author.timeout_ms)
+}
+
+// A lookup that failed is not trust.
+async function is_trusted(author: Author): Promise<boolean> {
+	return (await trust_of(author)) === true
 }
 
-const gh_author_association = { TRUSTED_LIST, is_trusted }
+const gh_author_association = { TRUSTED_LIST, is_trusted, trust_of }
 
+export type { Author }
 export { gh_author_association }