@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/lint/import-graph.ts

@@ -0,0 +1,279 @@
+import path from 'node:path'
+import { input_fingerprint } from '#scripts/gate/input-fingerprint'
+import { file_reader } from '#scripts/lib/read-file'
+import type ts from 'typescript'
+
+// What a file's lint verdict reads besides the file itself: every file its imports reach, followed
+// through the project's own files and stopped at a package's. A type-aware rule's verdict on a file
+// is about the types of those, so a cached verdict holds only while all of them do
+// (joshuafolkken/kit#4415).
+//
+// The modules are resolved as the type checker resolves them — the project's `tsconfig.json`, its
+// paths and `package.json` imports — because a resolution of our own would follow a different file
+// than the one whose types the rule read. A package's file is named by its resolved path rather than
+// read: that path carries the installed version, and a package's files change with nothing else.
+const TSCONFIG = 'tsconfig.json'
+const NODE_MODULES = 'node_modules'
+const MODULE_STATEMENT = /^(?:import|export)\b/mu
+const GLOBAL_DECLARATION = /^declare (?:global|module|namespace)\b/mu
+
+type TypeScript = typeof ts
+
+interface Dependency {
+	file: string
+	external: boolean
+}
+
+interface Resolver {
+	typescript: TypeScript
+	options: ts.CompilerOptions
+}
+
+interface GraphContext extends Resolver {
+	root: string
+	resolution_cache: ts.ModuleResolutionCache
+	ambient: ReadonlyArray<Dependency>
+	dependencies: Map<string, ReadonlyArray<Dependency>>
+	content_hashes: Map<string, string>
+}
+
+interface ProjectConfig {
+	options: ts.CompilerOptions
+	file_names: ReadonlyArray<string>
+	config_files: ReadonlyArray<string>
+}
+
+interface ImportGraph {
+	closure_hash: (file: string) => string
+}
+
+// `typescript` is an optional peer: a project without it has no type-aware rule to go stale.
+async function load_typescript(): Promise<TypeScript | undefined> {
+	try {
+		const module = await import('typescript')
+
+		return module.default
+	} catch {
+		return undefined
+	}
+}
+
+// A configuration that does not parse fails the type check, which reports it; here it only leaves
+// the options the parse did reach. `config_files` are `tsconfig.json` and every file it extends: a
+// type-aware verdict reads the compiler options — `strict` decides what is `any` — so a changed
+// option is a changed input like a changed import.
+function parsed_config(typescript: TypeScript, root: string): ProjectConfig | undefined {
+	const config_file = path.join(root, TSCONFIG)
+	if (!typescript.sys.fileExists(config_file)) return undefined
+	const source = typescript.readJsonConfigFile(config_file, typescript.sys.readFile)
+	const parsed = typescript.parseJsonSourceFileConfigFileContent(
+		source,
+		typescript.sys,
+		root,
+		undefined,
+		config_file,
+	)
+
+	return {
+		options: parsed.options,
+		file_names: parsed.fileNames,
+		config_files: [config_file, ...(source.extendedSourceFiles ?? [])],
+	}
+}
+
+// A package is named by its resolved path only while that path sits in an install. A workspace or
+// `link:` package resolves through its symlink to source the project edits — a path that carries no
+// version — so its files are read like the project's own.
+function is_installed(file: string): boolean {
+	return file.split(path.sep).includes(NODE_MODULES)
+}
+
+function as_dependency(
+	file: string | undefined,
+	external: boolean | undefined,
+): Dependency | undefined {
+	if (file === undefined) return undefined
+
+	return { file, external: external === true && is_installed(file) }
+}
+
+// A file named by its path from the one naming it: a `/// <reference path>`, or a relative import the
+// checker cannot resolve — a `.svelte` component — whose file is still the one it names.
+function relative_to(specifier: string, file: string): Dependency {
+	return { file: path.resolve(path.dirname(file), specifier), external: false }
+}
+
+function resolve_module(
+	context: GraphContext,
+	specifier: string,
+	file: string,
+): Dependency | undefined {
+	const { typescript, options, resolution_cache } = context
+	const resolved = typescript.resolveModuleName(
+		specifier,
+		file,
+		options,
+		typescript.sys,
+		resolution_cache,
+	).resolvedModule
+
+	if (resolved !== undefined) {
+		return as_dependency(resolved.resolvedFileName, resolved.isExternalLibraryImport)
+	}
+
+	if (!specifier.startsWith('.')) return undefined
+
+	return relative_to(specifier, file)
+}
+
+function resolve_type(resolver: Resolver, name: string, file: string): Dependency | undefined {
+	const { typescript, options } = resolver
+	const resolved = typescript.resolveTypeReferenceDirective(
+		name,
+		file,
+		options,
+		typescript.sys,
+	).resolvedTypeReferenceDirective
+
+	return as_dependency(resolved?.resolvedFileName, resolved?.isExternalLibraryImport)
+}
+
+function references_of(context: GraphContext, file: string): Array<Dependency | undefined> {
+	const processed = context.typescript.preProcessFile(
+		file_reader.read_if_readable(file) ?? '',
+		true,
+		true,
+	)
+
+	return [
+		...processed.importedFiles.map((reference) =>
+			resolve_module(context, reference.fileName, file),
+		),
+		...processed.referencedFiles.map((reference) => relative_to(reference.fileName, file)),
+		...processed.typeReferenceDirectives.map((reference) =>
+			resolve_type(context, reference.fileName, file),
+		),
+	]
+}
+
+function direct_dependencies(context: GraphContext, file: string): ReadonlyArray<Dependency> {
+	const known = context.dependencies.get(file)
+	if (known !== undefined) return known
+	const found = references_of(context, file).filter((dependency) => dependency !== undefined)
+
+	context.dependencies.set(file, found)
+
+	return found
+}
+
+// A file reaches files that never import it when it is a script or declares a global or a module —
+// SvelteKit's `src/app.d.ts` `App.Locals`, say, or a `.ts` module's `declare global` augmentation;
+// one that only exports is read through its imports like any other module.
+function is_ambient(file: string): boolean {
+	const content = file_reader.read_if_readable(file) ?? ''
+
+	return GLOBAL_DECLARATION.test(content) || !MODULE_STATEMENT.test(content)
+}
+
+// What every file reads without importing it: the project's ambient declarations, the type packages
+// its compiler options load (`types`, or every `@types` package when it is unset), and the
+// configuration files those options come from.
+function ambient_of(resolver: Resolver, root: string, config: ProjectConfig): Array<Dependency> {
+	const config_file = path.join(root, TSCONFIG)
+	const declarations = [
+		...config.file_names.filter((file) => is_ambient(file)),
+		...config.config_files,
+	].map((file) => ({ file, external: false }))
+	const types = resolver.typescript
+		.getAutomaticTypeDirectiveNames(resolver.options, resolver.typescript.sys)
+		.map((name) => resolve_type(resolver, name, config_file))
+		.filter((dependency) => dependency !== undefined)
+
+	return [...declarations, ...types]
+}
+
+function content_hash(context: GraphContext, file: string): string {
+	const known = context.content_hashes.get(file)
+	if (known !== undefined) return known
+	const computed = input_fingerprint.of_file(file)
+
+	context.content_hashes.set(file, computed)
+
+	return computed
+}
+
+// Every file the imports reach, the starting file excluded: its own content is the cache's key
+// already, and a file that imports itself through a cycle is still only that one key.
+function is_unvisited(
+	dependency: Dependency,
+	start: string,
+	reached: Map<string, Dependency>,
+): boolean {
+	return dependency.file !== start && !reached.has(dependency.file)
+}
+
+// Dependencies joined to what is reached, and those inside the project queued to be followed.
+function join(
+	dependencies: ReadonlyArray<Dependency>,
+	start: string,
+	reached: Map<string, Dependency>,
+): Array<string> {
+	const next = dependencies.filter((dependency) => is_unvisited(dependency, start, reached))
+
+	for (const dependency of next) reached.set(dependency.file, dependency)
+
+	return next.filter((dependency) => !dependency.external).map((dependency) => dependency.file)
+}
+
+function reachable(context: GraphContext, file: string): Map<string, Dependency> {
+	const reached = new Map<string, Dependency>()
+	const pending = [file, ...join(context.ambient, file, reached)]
+
+	for (let current = pending.pop(); current !== undefined; current = pending.pop()) {
+		pending.push(...join(direct_dependencies(context, current), file, reached))
+	}
+
+	return reached
+}
+
+// Named from the root rather than absolutely: a lane's seed and the gate's cache sharing rebase the
+// cache file into another checkout, where an absolute name would drop every entry.
+function token_of(context: GraphContext, dependency: Dependency): string {
+	const name = path.relative(context.root, dependency.file)
+	if (dependency.external) return name
+
+	return `${name}:${content_hash(context, dependency.file)}`
+}
+
+function closure_hash(context: GraphContext, file: string): string {
+	const tokens = [...reachable(context, file).values()].map((dependency) =>
+		token_of(context, dependency),
+	)
+
+	return input_fingerprint.of_entries(tokens)
+}
+
+// Undefined where nothing type-aware can run: no `typescript`, or no `tsconfig.json` at the root.
+async function create(root: string): Promise<ImportGraph | undefined> {
+	const typescript = await load_typescript()
+	if (typescript === undefined) return undefined
+	const parsed = parsed_config(typescript, root)
+	if (parsed === undefined) return undefined
+	const { options } = parsed
+	const context: GraphContext = {
+		root,
+		typescript,
+		options,
+		resolution_cache: typescript.createModuleResolutionCache(root, (name) => name, options),
+		ambient: ambient_of({ typescript, options }, root, parsed),
+		dependencies: new Map(),
+		content_hashes: new Map(),
+	}
+
+	return { closure_hash: (file) => closure_hash(context, file) }
+}
+
+const import_graph = { create }
+
+export type { ImportGraph }
+export { import_graph }

package/scripts/lint/lint-gate-scope.ts

@@ -0,0 +1,102 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { environment_flags } from '@joshuafolkken/kit/env'
+import { gate_plan } from '#scripts/gate/gate-plan'
+import { verification_inputs } from '#scripts/gate/verification-inputs'
+import {
+	changed_file_scope,
+	type ChangedFileScope,
+	type ScopeVocabulary,
+} from '#scripts/git/changed-file-scope'
+import {
+	ESLINT_CACHE_FILE,
+	ESLINT_CACHE_FLAGS,
+	PRETTIER_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
+import { lint_related_scope, type LintCaches } from './lint-related-scope'
+
+// `josh lint --changed` — the lint `josh gate` runs (joshuafolkken/kit#4085): the branch's changed
+// files rather than the whole tree.
+//
+// **Narrowing gives up only the files the branch did not change.** The whole-tree run answers such a
+// file from its cache entry unless the files its imports reach changed (`eslint-cache-dependencies.ts`,
+// joshuafolkken/kit#4415); this run does not lint it at all, so an unchanged file that a changed
+// import broke is caught by the whole-tree run alone. The other files that run actually lints are
+// the changed ones, and those are exactly the ones this run names.
+//
+// What a cache entry does not see falls back to the whole tree: a configuration the lint check declares
+// (`verification-inputs.ts`) — a toolchain or ignore file, the eslint configuration and kit's own rules,
+// the TypeScript configuration the type-aware rules read — and a change that cannot be read. CI lints the whole tree on every run,
+// so the narrowed gate always has the full check behind it.
+
+interface NarrowedLint {
+	prettier: ReadonlyArray<string>
+	eslint: ReadonlyArray<string>
+	eslint_cache_file: string
+}
+
+type Environment = Readonly<Record<string, string | undefined>>
+
+const GATE_CACHES: LintCaches = {
+	eslint_file: ESLINT_CACHE_FILE,
+	eslint_flags: ESLINT_CACHE_FLAGS,
+	prettier_flags: PRETTIER_CACHE_FLAGS,
+}
+
+const CI_REASON = 'CI lints the whole tree'
+const CONFIG_REASON = 'a changed file configures the toolchain or the linters'
+
+const VOCABULARY: ScopeVocabulary = {
+	label: 'josh lint --changed',
+	fallback_suffix: 'checking the whole tree instead',
+	narrowed_suffix: 'checking only them',
+}
+
+function all_scope(reason: string): ChangedFileScope {
+	return { mode: 'all', files: [], reason }
+}
+
+// The lint check's declared configurations (`verification-inputs.ts`), as the since-green narrowing
+// reads them too.
+function configures_lint(files: ReadonlyArray<string>, root: string): boolean {
+	return verification_inputs.configures(
+		gate_plan.LINT_LABEL,
+		files.map((file) => path.relative(root, file).split(path.sep).join('/')),
+	)
+}
+
+// `files` are absolute, as `changed_file_scope.read_changed_files` answers them; `undefined` is a
+// change that could not be read.
+function resolve_gate_scope(
+	files: ReadonlyArray<string> | undefined,
+	root: string,
+	environment: Environment,
+): ChangedFileScope {
+	if (environment_flags.is_ci_enabled(environment['CI'])) return all_scope(CI_REASON)
+	if (files !== undefined && configures_lint(files, root)) return all_scope(CONFIG_REASON)
+
+	return changed_file_scope.resolve_scope(files, lint_related_scope.scope_inputs(existsSync))
+}
+
+function narrowed_run(files: ReadonlyArray<string>): NarrowedLint {
+	return {
+		prettier: lint_related_scope.prettier_arguments(files, GATE_CACHES),
+		eslint: lint_related_scope.eslint_arguments(files, GATE_CACHES),
+		eslint_cache_file: GATE_CACHES.eslint_file,
+	}
+}
+
+function describe_scope(scope: ChangedFileScope, root: string): string {
+	return changed_file_scope.describe_scope(scope, root, VOCABULARY)
+}
+
+const lint_gate_scope = {
+	CHANGED_FLAG: '--changed',
+	CI_REASON,
+	CONFIG_REASON,
+	describe_scope,
+	narrowed_run,
+	resolve_gate_scope,
+}
+
+export { lint_gate_scope }

package/scripts/lint/lint-parallel-main.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
+import { lint_parallel } from './lint-parallel'
+
+// The `josh lint` entry, kept apart from `lint-parallel.ts` because `lint-related.ts` imports that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+//
+// `process.exitCode` rather than `process.exit()`: both reports are buffered and written in one go,
+// and `process.exit()` truncates a piped stdout at its buffer size — which is exactly how this
+// command is read when `josh gate` runs it as one of four concurrent checks. Setting the code lets
+// the writes drain and the process end on its own, which it can, since both children have already
+// exited by here.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await lint_parallel.run_lint_command(
+		process.argv.slice(changed_file_scope.ARGV_START),
+	)
+}

package/scripts/lint/lint-parallel.ts

@@ -1,6 +1,5 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { project_checks } from '#scripts/gate/project-checks'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
 import {
 	ESLINT_CACHE_FILE,
 	ESLINT_CACHE_FLAGS,
@@ -13,7 +12,9 @@ import {
 	type BufferedProcessResult,
 } from '#scripts/lib/buffered-process'
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
-import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-recheck'
+import { eslint_cache_dependencies } from './eslint-cache-dependencies'
+import { eslint_daemon } from './eslint-daemon'
+import { lint_gate_scope } from './lint-gate-scope'
 
 // This — not the `lint:eslint` map entry — is the eslint invocation `josh gate` reaches, so the
 // cache flags come from the same constant the ignore rules are asserted against.
@@ -21,29 +22,43 @@ import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-r
 // moves, with every test still green.
 const WHOLE_TREE = '.'
 const ESLINT_ARGS = ['exec', 'eslint', WHOLE_TREE, ...ESLINT_CACHE_FLAGS] as const
-const WHOLE_TREE_RECHECK: CrossFileRecheckOptions = {
-	cache_file: ESLINT_CACHE_FILE,
-	patterns: [WHOLE_TREE],
-}
 
 // Prettier's cache stays this checkout's own, never shared through `lane_cache_run` as eslint's is:
 // its entries do not survive a move (`josh-command-types.ts` → `GATE_CACHE_SPECS`).
 const PRETTIER_ARGS = ['exec', 'prettier', '--check', WHOLE_TREE, ...PRETTIER_CACHE_FLAGS] as const
 
-// What one eslint run is made of: the child's arguments, and what re-reading a cached cross-file report
-// (`cross-file-recheck.ts`) needs to ask the same question again — the cache file and the targets.
+// What one eslint run is made of: the child's arguments and the cache file they name.
 interface EslintRun {
 	args: ReadonlyArray<string>
-	recheck: CrossFileRecheckOptions
+	cache_file: string
+	warm_daemon: boolean
+}
+
+// Whether eslint may go through the checkout's warm daemon (`eslint-daemon.ts`). `josh lint:related`
+// asks for it; the gate's own lint does not, so its whole-tree run stays one cold process of its own.
+interface LintRunOptions {
+	warm_daemon: boolean
+}
+
+const COLD_RUN: LintRunOptions = { warm_daemon: false }
+
+// The warm daemon when asked for and reachable, else the cold `pnpm exec eslint` it falls back to.
+async function run_eslint_process(eslint: EslintRun): Promise<BufferedProcessResult> {
+	if (eslint.warm_daemon) return await eslint_daemon.run_or_cold(eslint.args)
+
+	return await buffered_process.run_buffered_process(eslint.args)
 }
 
-// The finished report is re-read before it is returned, inside the lane's cache sharing, because
-// the re-reading uses that same cache file.
+// The run sits inside the lane's cache sharing, between dropping the entries whose imports changed
+// and recording what the fresh ones read (`eslint-cache-dependencies.ts`).
 async function run_eslint(eslint: EslintRun): Promise<BufferedProcessResult> {
-	return await lane_cache_run.run(eslint.recheck.cache_file, async () => {
-		const result = await buffered_process.run_buffered_process(eslint.args)
+	const { cache_file } = eslint
 
-		return await cross_file_recheck.verify(result, eslint.recheck)
+	return await lane_cache_run.run(cache_file, async () => {
+		return await eslint_cache_dependencies.guard(
+			cache_file,
+			async () => await run_eslint_process(eslint),
+		)
 	})
 }
 
@@ -103,19 +118,16 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 // and through the same basic-project skip, so a narrowed run never reaches a tool the whole-tree
 // run would have skipped. The skip reasons answer nothing for a full
 // project, so the one path serves both profiles.
-//
-// A narrowed run re-reads a cached cross-file report too (`cross-file-recheck.ts`): one change's
-// files can hold both the reported file and the one it reads, and fixing the second leaves the
-// first's cached report standing.
 async function run_lint_checks(
 	prettier_args: ReadonlyArray<string>,
 	eslint_args: ReadonlyArray<string>,
-	recheck: CrossFileRecheckOptions,
+	cache_file: string,
+	options: LintRunOptions = COLD_RUN,
 ): Promise<number> {
 	const directory = process.cwd()
 	const [prettier, eslint] = await Promise.all([
 		run_prettier(directory, prettier_args),
-		run_checked_eslint(directory, { args: eslint_args, recheck }),
+		run_checked_eslint(directory, { args: eslint_args, cache_file, ...options }),
 	])
 
 	write_output(with_ran_notice('prettier', prettier, eslint))
@@ -125,18 +137,38 @@ async function run_lint_checks(
 }
 
 async function run_lint_parallel_checks(): Promise<number> {
-	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS, WHOLE_TREE_RECHECK)
+	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS, ESLINT_CACHE_FILE)
 }
 
-// `process.exitCode` rather than `process.exit()`: both reports are buffered and written here in
-// one go, and `process.exit()` truncates a piped stdout at its buffer size — which is exactly how
-// this command is read when `josh gate` runs it as one of four concurrent checks. Setting the code
-// lets the writes drain and the process end on its own, which it can, since both children have
-// already exited by here.
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run_lint_parallel_checks()
+// `josh lint --changed`, the gate's lint: the branch's changed files on the gate's own caches, or the
+// whole tree where `lint-gate-scope.ts` cannot narrow. The line naming the decision is printed first,
+// so a narrowed run is never read as a whole one.
+async function run_changed_lint_checks(): Promise<number> {
+	const root = await changed_file_scope.repository_root_or_cwd()
+	const files = await changed_file_scope.read_changed_files(root)
+	const scope = lint_gate_scope.resolve_gate_scope(files, root, process.env)
+
+	process.stdout.write(`${lint_gate_scope.describe_scope(scope, root)}\n`)
+
+	if (scope.mode === 'all') return await run_lint_parallel_checks()
+
+	const narrowed = lint_gate_scope.narrowed_run(scope.files)
+
+	return await run_lint_checks(narrowed.prettier, narrowed.eslint, narrowed.eslint_cache_file)
 }
 
-const lint_parallel = { run_lint_checks, run_lint_parallel_checks }
+async function run_lint_command(command_arguments: ReadonlyArray<string>): Promise<number> {
+	if (command_arguments.includes(lint_gate_scope.CHANGED_FLAG)) {
+		return await run_changed_lint_checks()
+	}
+
+	return await run_lint_parallel_checks()
+}
+
+const lint_parallel = {
+	run_lint_checks,
+	run_lint_command,
+	run_lint_parallel_checks,
+}
 
 export { ESLINT_ARGS, lint_parallel, PRETTIER_ARGS }

package/scripts/lint/lint-related-scope.ts

@@ -10,15 +10,12 @@ import {
 	ESLINT_RELATED_CACHE_FLAGS,
 	PRETTIER_RELATED_CACHE_FLAGS,
 } from '#scripts/josh/josh-command-types'
-import type { CrossFileRecheckOptions } from './cross-file-recheck'
 
 // `josh lint` reads the whole repository on every call, and an implementation loop calls it after
 // every few edits — re-reading files the change never touched.
 //
-// **This narrowing is added in front of the whole check, never in place of it.** `josh gate` still
-// runs `josh lint` over everything before the commit: a formatting rule can be broken by a file the
-// change did not name (a shared config, a generated snapshot), and only the whole-tree run sees
-// that. What the narrowing replaces is the repeat calls in between.
+// The gate narrows its own lint the same way, with its own caches and a whole-tree fallback for a
+// changed toolchain or lint configuration (`lint-gate-scope.ts`), and CI lints the whole tree.
 //
 // The decision this file makes is which extensions the two linters read, and how each of them is
 // asked about a file list instead of a directory. Everything it shares with `josh test:related` —
@@ -95,41 +92,49 @@ function describe_scope(scope: ChangedFileScope, root: string): string {
 	return changed_file_scope.describe_scope(scope, root, VOCABULARY)
 }
 
+// Where a narrowed run keeps its caches. `josh lint:related` keeps its own and the gate its own, for
+// the reason `eslint_arguments` gives below; a narrowed gate run on the gate's caches loses none of
+// the whole-tree entries, since a file it does not visit is not pruned (`josh-command-types.ts`).
+interface LintCaches {
+	eslint_file: string
+	eslint_flags: ReadonlyArray<string>
+	prettier_flags: ReadonlyArray<string>
+}
+
+const RELATED_CACHES: LintCaches = {
+	eslint_file: ESLINT_RELATED_CACHE_FILE,
+	eslint_flags: ESLINT_RELATED_CACHE_FLAGS,
+	prettier_flags: PRETTIER_RELATED_CACHE_FLAGS,
+}
+
 // The scoped run's own cache file, for the reason eslint's below gives: prettier too rewrites its
 // cache file whole, so a narrowed run sharing the gate's would discard entries a concurrent gate wrote.
-function prettier_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
-	return [...PRETTIER_ARGS, ...files, ...PRETTIER_RELATED_CACHE_FLAGS]
+function prettier_arguments(
+	files: ReadonlyArray<string>,
+	caches: LintCaches = RELATED_CACHES,
+): ReadonlyArray<string> {
+	return [...PRETTIER_ARGS, ...files, ...caches.prettier_flags]
 }
 
 // The cache file is this command's own rather than the gate's, because the two run at the same time.
-// `josh gate` lints the whole tree beside the review while an
+// `josh gate` lints beside the review while an
 // implementation loop calls this command between edits, and each eslint run rewrites its cache file
 // whole from the copy it loaded at start-up — so on one file the run that finished last would
 // discard the other's entries, and a narrowed run finishing during a whole-tree run would roll the
 // cache back to its pre-gate state. Sharing would let a narrowed run warm the gate's cache only for
 // pruning, which says nothing about two writers. It is the same judgement the edit hook's own cache
 // file makes.
-//
-// **What is narrowed is still only the target list, never the gate.** `josh gate` runs `josh lint`
-// over the whole tree before any commit; this file decides which files a repeat call reads.
-function eslint_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
-	return [...ESLINT_ARGS, ...files, ...ESLINT_RELATED_CACHE_FLAGS, ...ESLINT_SCOPED_FLAGS]
-}
-
-// What re-reading a cached cross-file report (`cross-file-recheck.ts`) needs to ask the narrowed run's question
-// again: the same targets, the same cache file, and the Node API's spelling of `--no-warn-ignored`.
-function cross_file_recheck_options(files: ReadonlyArray<string>): CrossFileRecheckOptions {
-	return {
-		cache_file: ESLINT_RELATED_CACHE_FILE,
-		patterns: files,
-		eslint_options: { warnIgnored: false },
-	}
+function eslint_arguments(
+	files: ReadonlyArray<string>,
+	caches: LintCaches = RELATED_CACHES,
+): ReadonlyArray<string> {
+	return [...ESLINT_ARGS, ...files, ...caches.eslint_flags, ...ESLINT_SCOPED_FLAGS]
 }
 
 const lint_related_scope = {
 	COMMAND_LABEL,
-	cross_file_recheck_options,
 	NOTHING_LINTABLE_REASON,
+	RELATED_CACHES,
 	describe_scope,
 	eslint_arguments,
 	is_lintable,
@@ -137,4 +142,5 @@ const lint_related_scope = {
 	scope_inputs,
 }
 
+export type { LintCaches }
 export { lint_related_scope }