@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/gate/gate-report.ts

@@ -2,10 +2,12 @@ import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { josh_verdict } from '#scripts/josh/josh-verdict'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 import { status_icons } from '#scripts/lib/status-icons'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { NOT_USED_MARKER, NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
 import { test_unit_guard } from '#scripts/test/test-unit-guard'
+import { gate_labels } from './gate-labels'
 import { gate_log } from './gate-log'
-import { gate_plan } from './gate-plan'
+import { verification_tail } from './verification-tail'
 
 // The gate's console reporting, split out of `verification-gate.ts` so that file stays under its line
 // ceiling while it grows the scoped pre-check and the failure summary. Nothing
@@ -31,6 +33,18 @@ interface GateStepResult extends BufferedProcessResult {
 	// Set when the check was not started because its inputs match the record taken at this time
 	// (`check-reuse.ts`).
 	reused_at?: string | undefined
+	// The CPU milliseconds the check's process tree spent, where the gate could read it (`check-cpu.ts`).
+	cpu_ms?: number | undefined
+	// The check's place in the core budget, absent on a check that claimed none (`gate-run-steps.ts`).
+	claim?: CheckClaim | undefined
+}
+
+// The width a check asked the core budget for, the width it ran at and how long it waited for it, so
+// whether a unit claim's wait for room paid off is read per run (joshuafolkken/kit#4451).
+interface CheckClaim {
+	requested: number
+	granted: number
+	waited_ms: number
 }
 
 function is_gate_step_failed(result: GateStepResult): boolean {
@@ -85,7 +99,7 @@ function checker_lines(result: GateStepResult): ReadonlyArray<string> {
 }
 
 function has_checker_warning(result: GateStepResult): boolean {
-	if (!gate_plan.WARNING_CHECKER_LABELS.includes(result.label)) return false
+	if (!gate_labels.WARNING_CHECKER_LABELS.includes(result.label)) return false
 
 	return checker_lines(result).some((line) =>
 		WARNING_MARKERS.some((marker) => line.includes(marker)),
@@ -147,7 +161,6 @@ function should_print_body(result: GateStepResult, is_verbose: boolean): boolean
 // Seconds to one decimal, which is the resolution the answer is read at: the question a gate's
 // timing answers is "which of the four is the long pole", and no check is ever separated from
 // another by less than a tenth of a second.
-const MS_PER_SECOND = 1000
 const SECONDS_DECIMALS = 1
 
 function format_seconds(elapsed_ms: number): string {
@@ -189,15 +202,16 @@ function print_gate_step(result: GateStepResult, is_verbose: boolean): void {
 function format_failure_actions(failed: ReadonlyArray<GateStepResult>): string {
 	if (failed.length === 0) return ''
 
-	const lines = failed.map(
-		(result) => `  ${FAIL_ICON} ${result.label} — re-run: pnpm ${result.command}`,
+	const lines = failed.map((result) =>
+		verification_tail.format_rerun(result.label, `pnpm ${result.command}`),
 	)
 
 	return `${GATE_COMMAND} — next:\n${lines.join('\n')}\n`
 }
 
 // **A check that started past the core budget is said in the summary, not only in the log**.
-// The wait cap admits a check that waited two minutes whatever the budget says,
+// The wait cap admits a check that waited two minutes whatever the budget says — sooner where outside
+// load holds it and does not ease —
 // so a gate that ran over-subscribed would otherwise look exactly like one that fitted.
 function format_budget_notes(results: ReadonlyArray<GateStepResult>): string {
 	const lines = results.flatMap((result) =>
@@ -243,10 +257,10 @@ function print_gate_summary(
 		failed.length === 0
 			? format_green_verdict(results, total)
 			: josh_verdict.format_gate_failed(failed.map((result) => result.label).join(', '), total)
-	const notes = format_budget_notes(results)
+	const failures = `${format_budget_notes(results)}${format_failure_actions(failed)}`
 
 	process.stdout.write(
-		`\n${notes}${format_failure_actions(failed)}${gate_log.format_log_notice(log_path)}${verdict}\n`,
+		`\n${verification_tail.format_tail({ failures, log: { path: log_path }, verdict })}`,
 	)
 }
 
@@ -285,5 +299,5 @@ const gate_report = {
 	report_gate_steps,
 }
 
-export type { GateReport, GateStep, GateStepResult }
+export type { CheckClaim, GateReport, GateStep, GateStepResult }
 export { gate_report }

package/scripts/gate/gate-run-steps.ts

@@ -2,17 +2,25 @@ import { availableParallelism } from 'node:os'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { buffered_process } from '#scripts/lib/buffered-process'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
-import { core_budget } from './core-budget'
+import { check_cpu, type CheckCpu } from './check-cpu'
+import { core_budget, type Admission } from './core-budget'
+import { free_cores } from './free-cores'
+import { gate_labels } from './gate-labels'
 import { gate_plan, type GatePlan } from './gate-plan'
-import type { GateStep, GateStepResult } from './gate-report'
-import { build_gate_step } from './gate-steps'
+import type { CheckClaim, GateStep, GateStepResult } from './gate-report'
+import { build_gate_step, with_granted_workers } from './gate-steps'
 import { project_checks } from './project-checks'
 
 // Running the gate's checks: each one under its place in the machine-wide budget, a reused one
 // (`check-reuse.ts`) without starting it. `verification-gate.ts` decides what runs and records the
 // outcome; this module only runs it.
 
-async function run_gate_step(step: GateStep): Promise<GateStepResult> {
+// `cpu` is the gate's shared reader, so concurrent checks each take their own growth; a lone call
+// reads its child alone from a baseline of its own.
+async function run_gate_step(
+	step: GateStep,
+	cpu: CheckCpu = check_cpu.check_cpu_reader(),
+): Promise<GateStepResult> {
 	if (step.skip_reason !== undefined) {
 		return {
 			label: step.label,
@@ -28,7 +36,7 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 		step.cwd === undefined ? {} : { cwd: step.cwd },
 	)
 
-	return { label: step.label, command: step.command_args.join(' '), ...result }
+	return { label: step.label, command: step.command_args.join(' '), ...result, cpu_ms: cpu() }
 }
 
 // This gate's share of the machine, resolved once at the gate's entry and carried down as one value.
@@ -54,7 +62,11 @@ function default_budget(): BudgetContext {
 interface ReservedStep {
 	step: GateStep
 	weight: number
+	// The check's own `reserved_cores`, the key `gate_plan.lightest_first` orders the pool's queue by.
+	reserved_cores: number
 	memory_mb: number
+	// The plan's `--maxWorkers` for the unit suite, the width the free memory bounds once it is admitted.
+	worker_cap: number | undefined
 	// When the check's own green record was taken, for a check `check-reuse.ts` found reusable.
 	reused_at: string | undefined
 }
@@ -71,7 +83,9 @@ async function build_reserved_steps(
 		plan.checks.map(async (check) => ({
 			step: await build_gate_step(check, process.cwd(), plan),
 			weight: gate_plan.check_weight(check, plan, available_cores),
+			reserved_cores: check.reserved_cores,
 			memory_mb: gate_plan.check_memory(check, plan, available_cores),
+			worker_cap: plan.unit_worker_cap,
 			reused_at: reused.get(check.label),
 		})),
 	)
@@ -90,6 +104,34 @@ function reused_result(step: GateStep, reused_at: string): GateStepResult {
 	}
 }
 
+// What the check asked the budget for and what it ran at, for its ledger row (`gate-ledger.ts`).
+function claim_of(requested: number, admission: Admission): CheckClaim {
+	return {
+		requested,
+		granted: admission.granted ?? requested,
+		waited_ms: admission.waited_ms ?? 0,
+	}
+}
+
+// **The unit step's width is bounded by the free memory too** (joshuafolkken/kit#4528). The plan's cap
+// and the granted width are sized from the cores alone, and the `--maxWorkers` they become skips the
+// guard's own reading (`test-unit-guard.ts`), so the memory is read here, once the claim is admitted
+// and the suite is about to start. The free cores are not applied: the admission has already narrowed
+// the claim to them (joshuafolkken/kit#4167).
+async function admitted_step(
+	reserved: ReservedStep,
+	admission: Admission,
+	available_cores: number,
+): Promise<GateStep> {
+	if (reserved.step.label !== gate_labels.UNIT_LABEL) return reserved.step
+
+	const { memory_workers } = await free_cores.read({ available_cores })
+	const asked = admission.granted ?? reserved.worker_cap
+	const workers = unit_worker_share.cap_to_free(asked, memory_workers, available_cores)
+
+	return with_granted_workers(reserved.step, workers)
+}
+
 // **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
@@ -98,24 +140,49 @@ function reused_result(step: GateStep, reused_at: string): GateStepResult {
 async function run_reserved_step(
 	reserved: ReservedStep,
 	budget: BudgetContext,
+	cpu: CheckCpu,
 ): Promise<GateStepResult> {
 	if (reserved.reused_at !== undefined) return reused_result(reserved.step, reserved.reused_at)
-	if (!budget.is_reserved) return await run_gate_step(reserved.step)
+	if (!budget.is_reserved) return await run_gate_step(reserved.step, cpu)
 
 	return await core_budget.with_core_reservation(
 		reserved.weight,
 		async (admission) => ({
-			...(await run_gate_step(reserved.step)),
+			...(await run_gate_step(
+				await admitted_step(reserved, admission, budget.available_cores),
+				cpu,
+			)),
 			budget_note: core_budget.describe_overflow(admission),
+			claim: claim_of(reserved.weight, admission),
 		}),
 		{
 			budget: budget.available_cores,
 			memory_mb: reserved.memory_mb,
 			command: `gate ${reserved.step.label}`,
+			is_unit: reserved.step.label === gate_labels.UNIT_LABEL,
 		},
 	)
 }
 
+// The pool's queue in the order `resolve_concurrency` counted it (joshuafolkken/kit#4609), so the
+// checks its width admitted are the ones that start, and one over the share waits for a slot rather
+// than taking one ahead of a zero-weight check. Each result goes back to its check's declaration
+// position, so the printed sections keep their order.
+async function run_lightest_first(
+	reserved: ReadonlyArray<ReservedStep>,
+	concurrency: number,
+	run: (entry: ReservedStep) => Promise<GateStepResult>,
+): Promise<ReadonlyArray<GateStepResult>> {
+	const indexed = reserved.map((entry, index) => ({ entry, index }))
+	const queue = gate_plan.lightest_first(indexed, ({ entry }) => entry.reserved_cores)
+	const finished = await bounded_pool.bounded_map(queue, concurrency, async ({ entry, index }) => ({
+		index,
+		result: await run(entry),
+	}))
+
+	return finished.toSorted((left, right) => left.index - right.index).map(({ result }) => result)
+}
+
 // `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
@@ -129,6 +196,7 @@ async function run_gate_steps(
 	reused: ReusedChecks = new Map(),
 ): Promise<ReadonlyArray<GateStepResult>> {
 	const reserved = await build_reserved_steps(plan, budget.available_cores, reused)
+	const cpu = check_cpu.check_cpu_reader()
 
 	// **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
@@ -136,10 +204,10 @@ async function run_gate_steps(
 	// 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(
+			await run_lightest_first(
 				reserved,
 				plan.concurrency,
-				async (entry) => await run_reserved_step(entry, budget),
+				async (entry) => await run_reserved_step(entry, budget, cpu),
 			),
 	)
 }

package/scripts/gate/gate-skip.ts

@@ -1,4 +1,4 @@
-import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { review_brief } from '#scripts/review/review-brief'
 import { review_stamps } from '#scripts/review/review-stamps'
 
@@ -64,8 +64,35 @@ const FORCE_FLAG = '--force'
 // rewritten by the hook's own install each cost minutes before anyone could tell them apart.
 type GateReuse = { stamp: FileMapStamp } | { miss: string }
 
+const NO_BASE = 'the merge base could not be read'
+const NO_CHANGE = 'no file differs from the merge base'
+
+// The fingerprint of every declared check's tools and environment (`verification-inputs.ts`).
+const INPUTS_MOVED = 'a checked tool or environment variable changed since the green gate'
+const BASE_MOVED = 'the merge base moved since the green gate'
+
 function base_moved(recorded: string | undefined, base: string): string {
-	return `the merge base moved since the green gate (${recorded ?? 'none'} → ${base})`
+	return `${BASE_MOVED} (${recorded ?? 'none'} → ${base})`
+}
+
+function stamp_miss(stamp: FileMapStamp, base: string): string | undefined {
+	if (stamp.base !== base) return base_moved(stamp.base, base)
+
+	return review_stamps.gate_stamp.describes_inputs(stamp) ? undefined : INPUTS_MOVED
+}
+
+const NO_MATCHING_RECORD = 'no green gate record matches the changed files'
+
+// joshuafolkken/kit#5214: a record that exists but covers other files is told apart from no record
+// at all, with the sizes of the two maps, so a log shows how far the tree had moved past it.
+function record_miss(recorded: FileMapStamp | undefined, tree: Record<string, string>): string {
+	if (recorded === undefined) return NO_MATCHING_RECORD
+
+	const changed = String(Object.keys(tree).length)
+	const covered = String(Object.keys(recorded.files).length)
+	const differing = String(file_map_stamp.changed_since(recorded, tree).length)
+
+	return `${NO_MATCHING_RECORD} (${changed} changed, record covers ${covered}, ${differing} differ)`
 }
 
 function gate_reuse(
@@ -73,15 +100,36 @@ function gate_reuse(
 	base: string | undefined,
 	source?: string,
 ): GateReuse {
-	if (base === undefined) return { miss: 'the merge base could not be read' }
-	if (Object.keys(tree).length === 0) return { miss: 'no file differs from the merge base' }
+	if (base === undefined) return { miss: NO_BASE }
+	if (Object.keys(tree).length === 0) return { miss: NO_CHANGE }
 
-	const stamp = review_brief.matching_stamp(review_stamps.gate_stamp.read(source), tree)
+	const recorded = review_stamps.gate_stamp.read(source)
+	const stamp = review_brief.matching_stamp(recorded, tree)
 
-	if (stamp === undefined) return { miss: 'no green gate record matches the changed files' }
-	if (stamp.base !== base) return { miss: base_moved(stamp.base, base) }
+	if (stamp === undefined) return { miss: record_miss(recorded, tree) }
+
+	const miss = stamp_miss(stamp, base)
+
+	return miss === undefined ? { stamp } : { miss }
+}
 
-	return { stamp }
+// joshuafolkken/kit#5234: the kind of a miss, read off the sentence `gate_reuse` wrote, so a ledger
+// counts the reasons without a second wording of them. A record that covers other files is checked
+// before no record at all, since its sentence starts with the other's. A miss no prefix names is
+// `other`; a hook's own refusals are told apart first, by `hook_gate_reuse.miss_kind`.
+const MISS_KINDS: ReadonlyArray<readonly [string, string]> = [
+	[NO_BASE, 'no-base'],
+	[NO_CHANGE, 'no-change'],
+	[`${NO_MATCHING_RECORD} (`, 'record-differs'],
+	[NO_MATCHING_RECORD, 'no-record'],
+	[BASE_MOVED, 'base-moved'],
+	[INPUTS_MOVED, 'inputs-moved'],
+]
+
+const OTHER_MISS = 'other'
+
+function miss_kind(miss: string): string {
+	return MISS_KINDS.find(([prefix]) => miss.startsWith(prefix))?.[1] ?? OTHER_MISS
 }
 
 function stamp_of(reuse: GateReuse): FileMapStamp | undefined {
@@ -143,6 +191,7 @@ const gate_skip = {
 	format_reuse_notice,
 	format_skip,
 	gate_reuse,
+	miss_kind,
 	reusable_green_gate,
 	stamp_of,
 }

package/scripts/gate/gate-static-group.ts

@@ -0,0 +1,60 @@
+import { gate_labels } from './gate-labels'
+import type { GateCheck } from './gate-plan'
+
+// **CI runs the static set as three parallel legs, and each leg is still `josh gate`**
+// (joshuafolkken/kit#5215). One runner ran all seven checks for about four minutes while every unit
+// shard was done in two, so `static-checks` was the merge's critical path. The legs are a matrix over
+// the names below, each running `pnpm josh gate --no-unit --static-group=<name>`, so CI keeps the
+// gate's one definition of every check and its all-failures-in-one-pass summary rather than restating
+// the commands per job. `gate-static-group.test.ts` pins the partition: every static check is in
+// exactly one group, and the workflow's matrix names exactly these groups.
+//
+// The split follows the weights: lint alone (the cold-cache outlier), the type check with the
+// unused-export walk (both build a TypeScript program), and the light rest together.
+const STATIC_GROUP_FLAG_PREFIX = '--static-group='
+
+const STATIC_GROUPS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	lint: [gate_labels.LINT_LABEL],
+	types: [gate_labels.TYPE_CHECK_LABEL, gate_labels.EXPORTS_LABEL],
+	rest: [
+		gate_labels.SPELL_CHECK_LABEL,
+		gate_labels.BEHAVIOR_LABEL,
+		gate_labels.METRICS_LABEL,
+		gate_labels.LOCKFILE_LABEL,
+	],
+}
+
+// The group an argument names, or `undefined` when it is not the flag or names no group — so an
+// unknown group is refused with every other unknown argument.
+function group_of(argument: string): string | undefined {
+	if (!argument.startsWith(STATIC_GROUP_FLAG_PREFIX)) return undefined
+
+	const name = argument.slice(STATIC_GROUP_FLAG_PREFIX.length)
+
+	return Object.hasOwn(STATIC_GROUPS, name) ? name : undefined
+}
+
+function find_group(arguments_: ReadonlyArray<string>): string | undefined {
+	return arguments_.map((argument) => group_of(argument)).find((name) => name !== undefined)
+}
+
+function narrow_checks(
+	checks: ReadonlyArray<GateCheck>,
+	group: string | undefined,
+): ReadonlyArray<GateCheck> {
+	if (group === undefined) return checks
+
+	const labels = STATIC_GROUPS[group] ?? []
+
+	return checks.filter((check) => labels.includes(check.label))
+}
+
+const gate_static_group = {
+	STATIC_GROUPS,
+	STATIC_GROUP_FLAG_PREFIX,
+	find_group,
+	group_of,
+	narrow_checks,
+}
+
+export { gate_static_group }

package/scripts/gate/gate-steps.ts

@@ -1,10 +1,11 @@
+import { gate_labels } from './gate-labels'
 import { gate_plan, type GateCheck, type GatePlan } from './gate-plan'
 import type { GateStep } from './gate-report'
 import { project_checks } from './project-checks'
 import { type_check_step } from './type-check-step'
 
 const JOSH = 'josh'
-const { TYPE_CHECK_LABEL, UNIT_LABEL } = gate_plan
+const { TYPE_CHECK_LABEL, UNIT_LABEL } = gate_labels
 const UNIT_WORKER_FLAG = '--maxWorkers'
 
 function unit_worker_args(check: GateCheck, plan: GatePlan): ReadonlyArray<string> {
@@ -42,6 +43,17 @@ async function build_gate_step(
 	return { label: check.label, command_args, cwd, skip_reason }
 }
 
+// The unit step at a narrower worker count: the one its claim was admitted at past the wait cap
+// (`core_admission.narrowed_weight`), or the one the free memory holds (`gate-run-steps.ts`). Any
+// other step, or one left as asked, is returned unchanged.
+function with_granted_workers(step: GateStep, granted: number | undefined): GateStep {
+	if (granted === undefined || step.label !== UNIT_LABEL) return step
+
+	const kept = step.command_args.filter((argument) => !argument.startsWith(`${UNIT_WORKER_FLAG}=`))
+
+	return { ...step, command_args: [...kept, `${UNIT_WORKER_FLAG}=${String(granted)}`] }
+}
+
 async function build_gate_steps(
 	start_directory: string,
 	plan: GatePlan = gate_plan.resolve_gate_plan(),
@@ -51,4 +63,4 @@ async function build_gate_steps(
 	)
 }
 
-export { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG }
+export { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG, with_granted_workers }

package/scripts/gate/gate-tree.ts

@@ -30,9 +30,11 @@ async function read_changed_files(): Promise<Record<string, string>> {
 }
 
 // The resolver lives in `git/change-base.ts`, because the review brief
-// needs exactly this reading and a second copy of it is the clone `CLAUDE.md` prohibits.
+// needs exactly this reading and a second copy of it is the clone `CLAUDE.md` prohibits. It is read
+// through a merge in progress, as the file map is (joshuafolkken/kit#5307): a map measured from the
+// later base beside `HEAD`'s older one would let a re-merged default branch reuse a stale record.
 async function read_base(): Promise<string | undefined> {
-	return await change_base.resolved()
+	return await change_base.resolved_through_merge()
 }
 
 // The two readings are independent, so they are started together rather than one after the other.

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

@@ -103,6 +103,12 @@ interface HookReuse {
 	source?: string | undefined
 }
 
+const ARGUMENTS_MISS = 'arguments were passed to the hook'
+
+function force_miss(force_environment: string): string {
+	return `${force_environment} is set`
+}
+
 // The stamp rather than a boolean, for the same reason `gate_skip.gate_reuse` hands one back: the
 // caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
 // printing. A refusal carries its reason instead.
@@ -111,19 +117,30 @@ interface HookReuse {
 // 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 hook_reuse(input: HookReuse): GateReuse {
-	if (input.extra_arguments.length > 0) return { miss: 'arguments were passed to the hook' }
-	if (is_force_requested(input.force_env)) return { miss: `${input.force_env} is set` }
+	if (input.extra_arguments.length > 0) return { miss: ARGUMENTS_MISS }
+	if (is_force_requested(input.force_env)) return { miss: force_miss(input.force_env) }
 	if (!input.is_tree_carried) return { miss: input.carry_miss }
 
 	return gate_skip.gate_reuse(input.tree.files, input.tree.base, input.source)
 }
 
+// joshuafolkken/kit#5234: the kind of a refusal `hook_reuse` answered, the hook's own three refusals
+// told apart before the gate's, so a ledger counts each without a second wording of the sentences.
+function miss_kind(miss: string, input: Pick<HookReuse, 'carry_miss' | 'force_env'>): string {
+	if (miss === ARGUMENTS_MISS) return 'arguments'
+	if (miss === force_miss(input.force_env)) return 'forced'
+	if (miss === input.carry_miss) return 'tree-not-carried'
+
+	return gate_skip.miss_kind(miss)
+}
+
 const hook_gate_reuse = {
 	GATE_REUSING_TARGETS,
 	hook_reuse,
 	is_force_requested,
 	is_index_matching_worktree,
 	is_worktree_clean,
+	miss_kind,
 	read_status_lines,
 }
 

package/scripts/gate/input-fingerprint.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// **The one fingerprint every kept result is computed with** (joshuafolkken/kit#4497). A reuse of a
+// verdict holds only while what it read holds, and each reader of a verdict once computed that on its
+// own — the ESLint cache's import closure, the test-read map's dirty files, the gate's tool versions —
+// so a miss in one (joshuafolkken/kit#4407, #4415, #4423, #4425) was a miss nowhere else. Every one now
+// digests a file, a set of files and a set of named entries here.
+
+// The digest of a path that does not exist, or cannot be read, so it still differs from any content.
+const ABSENT = 'absent'
+
+function of_content(content: Buffer | string): string {
+	return stamp_file.digest(content)
+}
+
+// One digest over `entries`, independent of their order.
+function of_entries(entries: Iterable<string>): string {
+	return of_content([...entries].toSorted((left, right) => left.localeCompare(right)).join('\n'))
+}
+
+function of_file(file_path: string): string {
+	try {
+		return of_content(readFileSync(file_path))
+	} catch {
+		return ABSENT
+	}
+}
+
+// Each of `relatives` (relative to `root`) keyed to the digest of its content, in path order.
+function of_files(root: string, relatives: Iterable<string>): Record<string, string> {
+	const sorted = [...new Set(relatives)].toSorted((left, right) => left.localeCompare(right))
+
+	return Object.fromEntries(
+		sorted.map((relative) => [relative, of_file(path.join(root, relative))]),
+	)
+}
+
+const input_fingerprint = { ABSENT, of_entries, of_file, of_files }
+
+export { input_fingerprint }