@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lib/stamped-memo.ts

@@ -0,0 +1,63 @@
+import { lstatSync } from 'node:fs'
+
+// An answer remembered per key, recomputed only when the key's stamp changes (joshuafolkken/kit#4263).
+//
+// **`run:board` redraws every second, and most of what it reads has not changed since the last
+// redraw.** A process's app name, a ledger's parsed lines and a work tree's git config were computed
+// again on every pass, and on a saturated machine those passes stopped the spinner for 45–200ms. The
+// stamp is what says "this has changed": a file's `file_stamp`, or a constant where the key alone
+// decides the answer.
+
+const NO_STAMP = ''
+const STAMP_SEPARATOR = ':'
+
+interface Remembered<Value> {
+	stamp: string
+	value: Value
+}
+
+interface StampedMemo<Value> {
+	// `compute`'s answer for `key`, run only when `key` was never seen or its stamp moved since.
+	of: (key: string, stamp: string, compute: () => Value) => Value
+	// Forget every key outside `keys` — a process gone from the table, so the memo cannot grow unbounded.
+	keep: (keys: ReadonlySet<string>) => void
+}
+
+function create<Value>(): StampedMemo<Value> {
+	const answers = new Map<string, Remembered<Value>>()
+
+	return {
+		of(key, stamp, compute) {
+			const known = answers.get(key)
+
+			if (known?.stamp === stamp) return known.value
+
+			const value = compute()
+
+			answers.set(key, { stamp, value })
+
+			return value
+		},
+		keep(keys) {
+			for (const key of answers.keys()) if (!keys.has(key)) answers.delete(key)
+		},
+	}
+}
+
+// What changes when a file is rewritten, appended to, replaced or re-owned: its inode, its modification
+// and change times and its size. An absent or unreadable file is `NO_STAMP`, so it reads again once
+// it appears.
+function file_stamp(file: string): string {
+	try {
+		const status = lstatSync(file)
+
+		return [status.ino, status.mtimeMs, status.ctimeMs, status.size].join(STAMP_SEPARATOR)
+	} catch {
+		return NO_STAMP
+	}
+}
+
+const stamped_memo = { NO_STAMP, create, file_stamp }
+
+export { stamped_memo }
+export type { StampedMemo }

package/scripts/lib/stdout-on-stderr.ts

@@ -0,0 +1,24 @@
+// Runs work whose own reports go to stdout with stdout pointed at stderr, for a caller whose stdout is
+// a contract: the `Stop` hook's decision envelope, and `josh run:hold`'s single verdict token.
+
+type StreamWrite = typeof process.stdout.write
+
+function set_stdout_write(stream_write: StreamWrite): void {
+	process.stdout.write = stream_write
+}
+
+async function run<T>(work: () => Promise<T>): Promise<T> {
+	const saved = { write: process.stdout.write.bind(process.stdout) }
+
+	set_stdout_write(process.stderr.write.bind(process.stderr))
+
+	try {
+		return await work()
+	} finally {
+		set_stdout_write(saved.write)
+	}
+}
+
+const stdout_on_stderr = { run }
+
+export { stdout_on_stderr }

package/scripts/lib/timeouts.ts

@@ -3,6 +3,12 @@
 // limit stays stuck where it stopped and never comes back, so every such
 // call takes one of these, and a value used in more than one place is named once here.
 
+// The unit conversions every duration is read and printed through. They sit beside the limits because a
+// limit is the most common thing they convert; a second copy in a caller is a clone of these two lines.
+const MS_PER_SECOND = 1000
+const SECONDS_PER_MINUTE = 60
+const MS_PER_MINUTE = MS_PER_SECOND * SECONDS_PER_MINUTE
+
 // A probe that only asks the local machine (`ps`, `lsof`, `git config`) on a path something else is
 // waiting on. Failing answers "cannot tell", which every caller handles, so anything slower is a fault.
 const PROBE_TIMEOUT_MS = 2000
@@ -41,6 +47,9 @@ export {
 	HOOK_PROCESS_TIMEOUT_MS,
 	INSTALL_TIMEOUT_MS,
 	LINT_TIMEOUT_MS,
+	MS_PER_MINUTE,
+	MS_PER_SECOND,
 	PROBE_TIMEOUT_MS,
+	SECONDS_PER_MINUTE,
 	SUITE_TIMEOUT_MS,
 }

package/scripts/lib/transcript-record.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod'
+import { json_value } from './json-value'
+
+// One line of a Claude Code JSONL log — a session transcript, or the `stream-json` output of
+// `claude -p`, which writes the same `{ type, message: { id, content } }` shape. Every reader of those
+// lines parses through these schemas and takes what it needs from the record; a fix to the shape
+// reaches all of them at once.
+//
+// **Every field is optional, including `type`.** A required field would make one unexpected block
+// fail the whole array it sits in, and with it every other block on that line — an entire assistant
+// turn dropped because one tool wrote a shape no reader had seen. A block that parses to nothing
+// contributes nothing.
+
+const TEXT_TYPE = 'text'
+const TOOL_USE_TYPE = 'tool_use'
+const TOOL_RESULT_TYPE = 'tool_result'
+
+const BLOCK_SCHEMA = z.object({
+	type: z.string().nullish(),
+	text: z.string().nullish(),
+	name: z.string().nullish(),
+	id: z.string().nullish(),
+	tool_use_id: z.string().nullish(),
+	input: z.unknown().nullish(),
+	// Whether the harness wrote a `tool_result` back as a failure — absent on every other block, and
+	// on the results of tools that never report one.
+	is_error: z.boolean().nullish(),
+	// A result's body: a string or a list of blocks. Read as `unknown` because each reader flattens it
+	// its own way, and a narrower type here would drop the whole line over one odd item.
+	content: z.unknown().nullish(),
+})
+
+const CONTENT_SCHEMA = z.union([z.string(), z.array(BLOCK_SCHEMA)])
+// `id` is the assistant *message* the line belongs to; Claude Code writes one line per content block,
+// so a turn that issued two calls is several lines carrying one id.
+const MESSAGE_SCHEMA = z.object({ id: z.string().nullish(), content: CONTENT_SCHEMA.nullish() })
+
+const LINE_SCHEMA = z.object({
+	type: z.string().nullish(),
+	timestamp: z.string().nullish(),
+	gitBranch: z.string().nullish(),
+	// The two fields outside `message` the harness writes an end-of-task notice on. `unknown`, since a
+	// string here would reject every line whose `content` is a list of blocks.
+	content: z.unknown().nullish(),
+	attachment: z.unknown().nullish(),
+	message: MESSAGE_SCHEMA.nullish(),
+})
+
+type TranscriptBlock = z.infer<typeof BLOCK_SCHEMA>
+type TranscriptContent = z.infer<typeof CONTENT_SCHEMA>
+type TranscriptMessage = z.infer<typeof MESSAGE_SCHEMA>
+type TranscriptRecord = z.infer<typeof LINE_SCHEMA>
+type ToolCallBlock = TranscriptBlock & { name: string }
+
+function read(value: unknown): TranscriptRecord | undefined {
+	return LINE_SCHEMA.safeParse(value).data
+}
+
+// A blank line, a line that is not JSON and a line of another shape are one answer: `undefined`.
+function parse(line: string): TranscriptRecord | undefined {
+	return read(json_value.parse_or_undefined(line))
+}
+
+// The line's blocks. A message written as a bare string — a prompt — carries none.
+function blocks_of(record: TranscriptRecord): ReadonlyArray<TranscriptBlock> {
+	const content = record.message?.content
+
+	return Array.isArray(content) ? content : []
+}
+
+function is_tool_call(block: TranscriptBlock): block is ToolCallBlock {
+	return block.type === TOOL_USE_TYPE && typeof block.name === 'string'
+}
+
+// The calls a line made, in order. A `tool_use` block without a name is not a call anything can name.
+function tool_calls_of(record: TranscriptRecord): Array<ToolCallBlock> {
+	return blocks_of(record).filter((block) => is_tool_call(block))
+}
+
+const transcript_record = {
+	TEXT_TYPE,
+	TOOL_USE_TYPE,
+	TOOL_RESULT_TYPE,
+	read,
+	parse,
+	blocks_of,
+	tool_calls_of,
+}
+
+export type { TranscriptBlock, TranscriptContent, TranscriptMessage, TranscriptRecord }
+export { transcript_record }

package/scripts/lines/effective-limit.ts

@@ -1,6 +1,7 @@
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { z } from 'zod'
 
 // Resolves the `max-lines` entry the project's own eslint applies, so `pnpm josh lines` explains its
@@ -28,7 +29,6 @@ import { z } from 'zod'
 // consumer's config, never by whichever copy happens to sit beside this file.
 
 const ESLINT_MODULE = 'eslint'
-const PACKAGE_JSON = 'package.json'
 const MAX_LINES_RULE = 'max-lines'
 // A rule turned off enforces nothing, so there is no limit to report and no headroom to subtract from.
 // Both spellings occur: `calculateConfigForFile` normalizes severity to a number, but a config read by

package/scripts/lint/eslint-cache-dependencies.ts

@@ -0,0 +1,145 @@
+import { rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { file_reader } from '#scripts/lib/read-file'
+import { parse, stringify } from 'flatted'
+import { import_graph, type ImportGraph } from './import-graph'
+
+// eslint's content cache keys a verdict on the linted file's own content, so a file whose imports
+// changed underneath it keeps answering from the cache: the error a type-aware rule would now report
+// — an import that became `any`, read by `no-unsafe-assignment` — never reaches the report, and the
+// type check does not report the `no-unsafe-*` rules either (joshuafolkken/kit#4415). CI restores
+// the gate's cache file, so it answers the same stale green.
+//
+// So each cached entry also records what its verdict read: the hash of every file its imports reach
+// (`import-graph.ts`). Before a cached run, an entry whose imports no longer hash the same is dropped,
+// and eslint lints that file afresh; after it, the entries eslint wrote are given the hash taken
+// before the run, which is the state of the files that run read. An entry with no hash — one an
+// unguarded run wrote, or one from before this — is dropped as well, because nothing says what it
+// read.
+//
+// The drop clears a stale red as well as a stale green: an import rule's report — `import/no-cycle`,
+// `import-x/named` — is about another file too, and once that file changes the entry is linted
+// afresh. Only imports are followed, so a rule that reads the files importing this one — a
+// reverse-dependency rule such as `import/no-unused-modules`, a no-op under ESLint 10 — would go
+// stale here. This is the one place cache staleness is decided; it replaced the cross-file re-read that
+// once ran after a red cached run (joshuafolkken/kit#3641, #3667, #4407, #4420).
+//
+// The record rides inside eslint's own cache file, in the entry's `data` beside the results eslint
+// keeps there, rather than a file of its own: it then travels wherever the cache file does — a lane's
+// seed, CI's cache — and eslint replaces `data` whole whenever it lints the file again, so a hash can
+// never outlive the verdict it was taken for. The file is `flat-cache`'s, serialized with `flatted`.
+
+type CacheMeta = Record<string, unknown>
+
+interface CacheEntry {
+	key: string
+	value: CacheMeta
+}
+
+type Hashes = ReadonlyMap<string, string>
+
+function is_record(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function is_entry(item: unknown): item is CacheEntry {
+	if (!is_record(item)) return false
+	const { key, value } = item
+
+	return typeof key === 'string' && is_record(value)
+}
+
+function is_entries(value: unknown): value is Array<CacheEntry> {
+	return Array.isArray(value) && value.every((item: unknown) => is_entry(item))
+}
+
+function parsed_or_undefined(content: string): unknown {
+	try {
+		return parse(content)
+	} catch {
+		return undefined
+	}
+}
+
+// Undefined for a missing file and for one this cannot read as eslint writes it.
+function read_entries(cache_file: string): Array<CacheEntry> | undefined {
+	const content = file_reader.read_optional(cache_file)
+	if (content === undefined) return undefined
+	const parsed = parsed_or_undefined(content)
+
+	return is_entries(parsed) ? parsed : undefined
+}
+
+// A cache file this cannot read — a corrupt one, or one another layout wrote into a cache lanes share —
+// is removed before the run rather than left to eslint, so the run rebuilds it whole and every entry it
+// writes carries a hash (joshuafolkken/kit#4497).
+function read_or_discard(cache_file: string): Array<CacheEntry> {
+	const entries = read_entries(cache_file)
+
+	if (entries === undefined) rmSync(cache_file, { force: true })
+
+	return entries ?? []
+}
+
+function write_entries(cache_file: string, entries: ReadonlyArray<CacheEntry>): void {
+	writeFileSync(cache_file, stringify(entries))
+}
+
+function recorded_hash(entry: CacheEntry): string | undefined {
+	const { data } = entry.value
+	if (!is_record(data)) return undefined
+	const { dependencies } = data
+
+	return typeof dependencies === 'string' ? dependencies : undefined
+}
+
+// Drops every entry whose imports no longer hash as recorded, and answers the hashes it took.
+function drop_stale(cache_file: string, graph: ImportGraph): Hashes {
+	const entries = read_or_discard(cache_file)
+	const hashes = new Map(entries.map((entry) => [entry.key, graph.closure_hash(entry.key)]))
+	const kept = entries.filter((entry) => recorded_hash(entry) === hashes.get(entry.key))
+
+	if (kept.length !== entries.length) write_entries(cache_file, kept)
+
+	return hashes
+}
+
+// eslint writes `data` only for a file it linted, so an entry with `data` and no hash is one this run
+// linted. A file the run linted for the first time had no hash taken before it, so it is taken now.
+function record_entry(entry: CacheEntry, hashes: Hashes, graph: ImportGraph): boolean {
+	const { data } = entry.value
+	if (!is_record(data) || 'dependencies' in data) return false
+
+	Object.assign(data, { dependencies: hashes.get(entry.key) ?? graph.closure_hash(entry.key) })
+
+	return true
+}
+
+function record(cache_file: string, hashes: Hashes, graph: ImportGraph): void {
+	const entries = read_entries(cache_file)
+	if (entries === undefined) return
+	const recorded = entries.filter((entry) => record_entry(entry, hashes, graph))
+
+	if (recorded.length > 0) write_entries(cache_file, entries)
+}
+
+// Runs one cached eslint run between the drop and the record. A project without `typescript` or a `tsconfig.json` runs it as it was.
+async function guard<T>(
+	cache_file: string,
+	run: () => Promise<T>,
+	root: string = process.cwd(),
+): Promise<T> {
+	const graph = await import_graph.create(root)
+	if (graph === undefined) return await run()
+	const location = path.resolve(root, cache_file)
+	const hashes = drop_stale(location, graph)
+	const result = await run()
+
+	record(location, hashes, graph)
+
+	return result
+}
+
+const eslint_cache_dependencies = { guard }
+
+export { eslint_cache_dependencies }

package/scripts/lint/eslint-daemon.ts

@@ -0,0 +1,265 @@
+import { lstatSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolve_package_bin } from '#scripts/build/local-bin'
+import { toolchain_inputs } from '#scripts/gate/toolchain-inputs'
+import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { atomic_write } from '#scripts/lib/atomic-write'
+import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+import { execa } from 'execa'
+
+// One warm eslint per checkout, reached by every eslint run that is not the gate's whole tree: the
+// `PostToolUse` edit hook, `josh lint:related` and the pre-commit hook (joshuafolkken/kit#4358).
+// `eslint_d` forwards the argument list to the project's own `eslint/lib/cli.js` → `execute`, run in
+// the forwarding process's cwd, so the report, the exit code and the cache file are eslint's own:
+// measured on this repository, a CLI run and a daemon run over the same files wrote byte-identical
+// cache files, `--quiet` included, and printed identical reports.
+
+const ESLINT_DAEMON = 'eslint_d'
+const DAEMON_STOP = 'stop'
+// The pnpm argument list every eslint caller here already builds. The daemon takes what follows it.
+const PNPM_EXEC = 'exec'
+const ESLINT_BIN = 'eslint'
+const PNPM_ESLINT_PREFIX_LENGTH = 2
+const NODE_MODULES = 'node_modules'
+// `eslint_d` writes `<token> <port> <pid> <hash>` here once, when the daemon has started, and removes
+// it when the daemon stops — so its text names one daemon.
+const DAEMON_RECORD = '.eslint_d'
+// What that daemon loaded: its record's text and the fingerprint it started under, written beside it.
+const FINGERPRINT_RECORD = '.eslint_d-toolchain'
+const RECORD_SEPARATOR = '\n'
+const NO_HEAD = 'no-head'
+
+// Where this file sits inside the kit package. `eslint_d` is kit's dependency rather than the
+// consumer's, and pnpm writes a `node_modules/.bin` shim only for a project's *direct* dependencies,
+// so a consumer's project root cannot see it and this directory can.
+const MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url))
+
+interface DaemonOutcome {
+	exit_code: number
+	// stdout alone, which is what separates a report from a daemon that never answered.
+	stdout: string
+	// stdout and stderr interleaved, which is what a caller prints.
+	output: string
+}
+
+interface DaemonRecord {
+	// The running daemon's own record, or nothing when none runs.
+	daemon: string | undefined
+	// What `remember` wrote for the daemon it last saw start.
+	recorded: string | undefined
+}
+
+interface DaemonRunOptions {
+	project_root: string
+	timeout_ms?: number
+}
+
+// `eslint_d` keys its one daemon on the record beside the eslint it resolves, so a project that
+// borrows another checkout's `node_modules` through a symlink — a test fixture's temporary
+// repository — would start, restart and overwrite that checkout's daemon (joshuafolkken/kit#4386).
+function is_borrowed_install(project_root: string): boolean {
+	return (
+		lstatSync(path.join(project_root, NODE_MODULES), {
+			throwIfNoEntry: false,
+		})?.isSymbolicLink() === true
+	)
+}
+
+function resolve_daemon_cli(project_root: string): string | undefined {
+	if (is_borrowed_install(project_root)) return undefined
+
+	return (
+		resolve_package_bin(MODULE_DIRECTORY, ESLINT_DAEMON, ESLINT_DAEMON) ??
+		resolve_package_bin(project_root, ESLINT_DAEMON, ESLINT_DAEMON)
+	)
+}
+
+// The flat config, the type program's options and the installed packages a consumer's config imports
+// its rules from — typescript-eslint's project service watches none of them (joshuafolkken/kit#4494).
+function is_config_input(relative_path: string): boolean {
+	return toolchain_inputs.is_input(relative_path)
+}
+
+// The eslint arguments of a `pnpm exec eslint …` list, or nothing when the list runs another tool.
+function eslint_arguments_of(
+	pnpm_arguments: ReadonlyArray<string>,
+): ReadonlyArray<string> | undefined {
+	if (pnpm_arguments[0] !== PNPM_EXEC || pnpm_arguments[1] !== ESLINT_BIN) return undefined
+
+	return pnpm_arguments.slice(PNPM_ESLINT_PREFIX_LENGTH)
+}
+
+// **What a daemon is current for: the toolchain's content and the commit checked out.** The daemon's
+// type program keeps every source it read but did not lint, so a merge that changes those types leaves
+// typed rules failing on the old ones (joshuafolkken/kit#4443); every merge, checkout, reset, pull and
+// commit moves HEAD, the commands that move sources under the daemon without an edit the hook sees.
+// A content digest rather than a time: a copy or a checkout rewrites every mtime and leaves the
+// content alone, and an edit can keep its old mtime. Outside a repository there is no HEAD.
+function fingerprint(project_root: string): string {
+	const head = git_spawn_sync.read(['rev-parse', 'HEAD'], { cwd: project_root }) ?? NO_HEAD
+
+	return `${toolchain_inputs.digest(project_root)}:${head}`
+}
+
+// Where the eslint the daemon resolves keeps its record, or nothing without an installed eslint.
+function eslint_directory(project_root: string): string | undefined {
+	try {
+		return path.dirname(
+			createRequire(path.join(project_root, 'package.json')).resolve('eslint/package.json'),
+		)
+	} catch {
+		return undefined
+	}
+}
+
+function read_text(file: string): string | undefined {
+	try {
+		return readFileSync(file, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+function read_record(project_root: string): DaemonRecord {
+	const directory = eslint_directory(project_root)
+	if (directory === undefined) return { daemon: undefined, recorded: undefined }
+
+	return {
+		daemon: read_text(path.join(directory, DAEMON_RECORD)),
+		recorded: read_text(path.join(directory, FINGERPRINT_RECORD)),
+	}
+}
+
+function record_text(daemon: string, current: string): string {
+	return `${daemon}${RECORD_SEPARATOR}${current}`
+}
+
+// A daemon keeps the rule modules it imported first — eslint cache-busts only the config entry file —
+// so a toolchain input that moved since it started leaves it linting against the old rules, and a
+// HEAD move leaves it typing against the old sources. A daemon this module did not record — another
+// tool started it, or the record is from an older one — is stale too: nothing says what it loaded.
+// The edit hook records the daemons it starts and restarts (`remember_started`); this catches the rest.
+function is_stale(record: DaemonRecord, current: string): boolean {
+	if (record.daemon === undefined) return false
+
+	return record.recorded !== record_text(record.daemon, current)
+}
+
+// Best-effort, like the daemon's own record: one that could not be written restarts the daemon once
+// more on the next run.
+function remember(project_root: string, current: string): void {
+	const directory = eslint_directory(project_root)
+	if (directory === undefined) return
+	const daemon = read_text(path.join(directory, DAEMON_RECORD))
+	if (daemon === undefined) return
+
+	try {
+		atomic_write.replace_file(
+			path.join(directory, FINGERPRINT_RECORD),
+			record_text(daemon, current),
+		)
+	} catch {
+		// A lost record costs one restart.
+	}
+}
+
+// The edit hook starts the daemon on its first eslint fix and restarts it after a config edit, each
+// under the inputs as they are now, and a daemon's record changes with every start — so a record that
+// changed across the hook's commands names a daemon they started. Recording it keeps the next lint run
+// from stopping and cold-starting a daemon that is already current.
+function remember_started(project_root: string, before: DaemonRecord): void {
+	if (read_record(project_root).daemon === before.daemon) return
+
+	remember(project_root, fingerprint(project_root))
+}
+
+// `cwd` decides which eslint installation and which flat config answer, and `ESLINT_D_MISS=fail`
+// refuses the bundled eslint the daemon would otherwise fall back to.
+async function spawn_daemon(
+	cli: string,
+	cli_arguments: ReadonlyArray<string>,
+	options: DaemonRunOptions,
+): Promise<DaemonOutcome> {
+	const result = await execa(process.execPath, [cli, ...cli_arguments], {
+		reject: false,
+		all: true,
+		cwd: options.project_root,
+		env: { ...buffered_process.child_environment(), ESLINT_D_MISS: 'fail' },
+		extendEnv: false,
+		...(options.timeout_ms !== undefined && { timeout: options.timeout_ms }),
+	})
+
+	return { exit_code: result.exitCode ?? 1, stdout: result.stdout, output: result.all }
+}
+
+// The daemon prints every eslint line — stderr included — to its forwarder's stdout, and its own
+// start failures to stderr with nothing on stdout.
+function is_start_failure(outcome: DaemonOutcome): boolean {
+	return outcome.exit_code !== 0 && outcome.stdout.length === 0
+}
+
+// The fingerprint is taken before the run, so an input that moves while the daemon starts is caught by
+// the next one.
+async function run_current(
+	cli: string,
+	eslint_arguments: ReadonlyArray<string>,
+	options: DaemonRunOptions,
+): Promise<DaemonOutcome | undefined> {
+	const { project_root } = options
+	const current = fingerprint(project_root)
+	if (is_stale(read_record(project_root), current)) await spawn_daemon(cli, [DAEMON_STOP], options)
+
+	const outcome = await spawn_daemon(cli, eslint_arguments, options)
+	if (is_start_failure(outcome)) return undefined
+	remember(project_root, current)
+
+	return outcome
+}
+
+// The run through the warm daemon, or nothing when there is no daemon to reach or it failed to
+// start — the caller then runs its own cold route, so a project without the daemon lints as before.
+async function run(
+	pnpm_arguments: ReadonlyArray<string>,
+	options: DaemonRunOptions,
+): Promise<DaemonOutcome | undefined> {
+	const eslint_arguments = eslint_arguments_of(pnpm_arguments)
+	if (eslint_arguments === undefined) return undefined
+	const cli = resolve_daemon_cli(options.project_root)
+	if (cli === undefined) return undefined
+
+	return await run_current(cli, eslint_arguments, options)
+}
+
+// The warm run from the current directory, read as a buffered child's result, or the cold
+// `pnpm exec eslint` when the daemon cannot answer — the one fallback `josh lint:related` and the
+// pre-commit hook both take.
+async function run_or_cold(pnpm_arguments: ReadonlyArray<string>): Promise<BufferedProcessResult> {
+	const started_at = performance.now()
+	const outcome = await run(pnpm_arguments, { project_root: process.cwd() })
+	if (outcome === undefined) return await buffered_process.run_buffered_process(pnpm_arguments)
+
+	return {
+		output: outcome.output,
+		exit_code: outcome.exit_code,
+		elapsed_ms: performance.now() - started_at,
+	}
+}
+
+const eslint_daemon = {
+	eslint_arguments_of,
+	fingerprint,
+	is_config_input,
+	is_stale,
+	read_record,
+	record_text,
+	remember_started,
+	resolve_daemon_cli,
+	run,
+	run_or_cold,
+	ESLINT_DAEMON,
+}
+
+export type { DaemonOutcome, DaemonRecord }
+export { eslint_daemon }

package/scripts/lint/format.ts

@@ -1,14 +1,19 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { project_checks } from '#scripts/gate/project-checks'
-import { ESLINT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import {
+	ESLINT_CACHE_FILE,
+	ESLINT_CACHE_FLAGS,
+	PRETTIER_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { execa } from 'execa'
+import { eslint_cache_dependencies } from './eslint-cache-dependencies'
 
 const COMMAND_NAME = 'format'
 const ARGV_OFFSET = 2
 const FAIL_EXIT_CODE = 1
-const PRETTIER_ARGS = ['exec', 'prettier', '--write', '.'] as const
+const PRETTIER_WRITE_ARGS = ['exec', 'prettier', '--write', '.', ...PRETTIER_CACHE_FLAGS] as const
 const ESLINT_FIX_ARGS = ['exec', 'eslint', '.', '--fix', ...ESLINT_CACHE_FLAGS] as const
 
 async function run_step(args: ReadonlyArray<string>, directory: string): Promise<number> {
@@ -37,13 +42,17 @@ async function run_format(directory: string): Promise<number> {
 	const prettier_exit_code = await run_unless_skipped(
 		'prettier',
 		prettier_reason,
-		PRETTIER_ARGS,
+		PRETTIER_WRITE_ARGS,
 		directory,
 	)
 	if (prettier_exit_code !== 0) return prettier_exit_code
 	const eslint_reason = project_checks.eslint_skip_reason(directory)
 
-	return await run_unless_skipped('eslint', eslint_reason, ESLINT_FIX_ARGS, directory)
+	return await eslint_cache_dependencies.guard(
+		ESLINT_CACHE_FILE,
+		async () => await run_unless_skipped('eslint', eslint_reason, ESLINT_FIX_ARGS, directory),
+		directory,
+	)
 }
 
 // The argument refusal survives leaving the `sh -c` composite shape: both tools run over the whole
@@ -64,4 +73,4 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 
 const format = { run, run_format }
 
-export { ESLINT_FIX_ARGS, format }
+export { ESLINT_FIX_ARGS, format, PRETTIER_WRITE_ARGS }