@joshuafolkken/kit 1.1514.0 → 1.1784.0

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,9 +1,14 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { project_checks } from '#scripts/gate/project-checks'
-import { ESLINT_CACHE_FLAGS, PRETTIER_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
@@ -43,7 +48,11 @@ async function run_format(directory: string): Promise<number> {
 	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