@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/lint/import-move.ts

@@ -0,0 +1,275 @@
+import type ts from 'typescript'
+import {
+	rename_identifier,
+	type RenameResult,
+	type Replacement,
+	type TypeScriptApi,
+} from './rename-identifier'
+
+// The rewrite behind `josh rename <name> <name> --import <from> <to>` (joshuafolkken/kit#5792): one
+// named import moved to another module under the same name.
+//
+// **Only the named import moves, never the declaration's other names.** `import { a, b } from 'x'`
+// moving `b` keeps `import { a } from 'x'` and adds `import { b } from 'y'` below it; a declaration
+// the name was alone in takes the new specifier instead. A file already importing names from the new
+// module gets the name in that declaration instead, and a declaration it leaves empty goes
+// (joshuafolkken/kit#5800); `import type { … }` takes only a type-only name. A type-only name stays
+// type-only. Only the name and its comma are cut, so a comment in the braces stays. Nothing but
+// import declarations is read, so strings, keys and other uses of the name are never touched. A name
+// imported twice from the old module is not guessed at: the file counts as untouched.
+
+const BLANK = /[\t ]/u
+
+interface MoveRequest {
+	name: string
+	from: string
+	to: string
+}
+
+interface Moving {
+	declaration: ts.ImportDeclaration
+	element: ts.ImportSpecifier
+}
+
+function specifier_of(api: TypeScriptApi, declaration: ts.ImportDeclaration): string | undefined {
+	const { moduleSpecifier: module_specifier } = declaration
+
+	return api.isStringLiteral(module_specifier) ? module_specifier.text : undefined
+}
+
+function imports_from(
+	api: TypeScriptApi,
+	source: ts.SourceFile,
+	specifier: string,
+): ReadonlyArray<ts.ImportDeclaration> {
+	return source.statements
+		.filter((statement) => api.isImportDeclaration(statement))
+		.filter((declaration) => specifier_of(api, declaration) === specifier)
+}
+
+function elements_of(
+	api: TypeScriptApi,
+	declaration: ts.ImportDeclaration,
+): ReadonlyArray<ts.ImportSpecifier> {
+	const bindings = declaration.importClause?.namedBindings
+
+	if (bindings === undefined || !api.isNamedImports(bindings)) return []
+
+	return bindings.elements
+}
+
+function named(
+	api: TypeScriptApi,
+	declaration: ts.ImportDeclaration,
+	name: string,
+): ReadonlyArray<ts.ImportSpecifier> {
+	return elements_of(api, declaration).filter(
+		(element) => (element.propertyName ?? element.name).text === name,
+	)
+}
+
+function moving_of(
+	api: TypeScriptApi,
+	source: ts.SourceFile,
+	request: MoveRequest,
+): Moving | undefined {
+	const found = imports_from(api, source, request.from).flatMap((declaration) =>
+		named(api, declaration, request.name).map((element) => ({ declaration, element })),
+	)
+
+	return found.length === 1 ? found[0] : undefined
+}
+
+function quoted(declaration: ts.ImportDeclaration, specifier: string): string {
+	const quote = declaration.getSourceFile().text.charAt(declaration.moduleSpecifier.getStart())
+
+	return `${quote}${specifier}${quote}`
+}
+
+// The element without its `type` keyword, which moves to the new declaration's own `import type`.
+function bare_text(element: ts.ImportSpecifier): string {
+	const { propertyName: property_name, name } = element
+
+	return property_name === undefined ? name.text : `${property_name.getText()} as ${name.text}`
+}
+
+// `import type { … }`'s `type`, which covers every name in the clause.
+function type_keyword(api: TypeScriptApi, clause: ts.ImportClause): string {
+	return clause.phaseModifier === api.SyntaxKind.TypeKeyword ? 'type ' : ''
+}
+
+function is_type_only(keyword: string, element: ts.ImportSpecifier): boolean {
+	return keyword !== '' || element.isTypeOnly
+}
+
+function insert_edit(moving: Moving, keyword: string, to: string): Replacement {
+	const { declaration, element } = moving
+	const is_type = is_type_only(keyword, element)
+	const text = `\nimport ${is_type ? 'type ' : ''}{ ${bare_text(element)} } from ${quoted(declaration, to)}`
+
+	return { start: declaration.getEnd(), end: declaration.getEnd(), text }
+}
+
+// A declaration from the new module with named imports the name can join: `import type { … }` takes
+// a type-only name alone.
+function accepts(api: TypeScriptApi, declaration: ts.ImportDeclaration, is_type: boolean): boolean {
+	const clause = declaration.importClause
+
+	if (clause === undefined || elements_of(api, declaration).length === 0) return false
+
+	return is_type || type_keyword(api, clause) === ''
+}
+
+// The moved name after the joined declaration's last one; a type-only name joining a value
+// declaration keeps an inline `type`.
+function joined_text(
+	api: TypeScriptApi,
+	last: ts.ImportSpecifier,
+	element: ts.ImportSpecifier,
+	is_type: boolean,
+): string {
+	const inline = is_type && type_keyword(api, last.parent.parent) === '' ? 'type ' : ''
+
+	return `, ${inline}${bare_text(element)}`
+}
+
+// The moved name appended to the new module's existing declaration (joshuafolkken/kit#5800), so the
+// file never imports the same module twice.
+function merge_edit(
+	api: TypeScriptApi,
+	moving: Moving,
+	keyword: string,
+	to: string,
+): Replacement | undefined {
+	const { declaration, element } = moving
+	const is_type = is_type_only(keyword, element)
+	const into = imports_from(api, declaration.getSourceFile(), to).find(
+		(candidate) => candidate !== declaration && accepts(api, candidate, is_type),
+	)
+	const last = into === undefined ? undefined : elements_of(api, into).at(-1)
+	if (last === undefined) return undefined
+
+	return {
+		start: last.getEnd(),
+		end: last.getEnd(),
+		text: joined_text(api, last, element, is_type),
+	}
+}
+
+// The whole declaration with its line break, for a name that was alone in it and joined another.
+function drop_edit(declaration: ts.ImportDeclaration): Replacement {
+	const { text } = declaration.getSourceFile()
+	const end = declaration.getEnd()
+	const line_end = text.charAt(end) === '\n' ? end + 1 : end
+
+	return { start: declaration.getStart(), end: line_end, text: '' }
+}
+
+function specifier_edit(declaration: ts.ImportDeclaration, to: string): Replacement {
+	const { moduleSpecifier: module_specifier } = declaration
+
+	return {
+		start: module_specifier.getStart(),
+		end: module_specifier.getEnd(),
+		text: quoted(declaration, to),
+	}
+}
+
+function blank_end(text: string, at: number): number {
+	let end = at
+
+	while (BLANK.test(text.charAt(end))) end += 1
+
+	return end
+}
+
+function blank_start(text: string, at: number): number {
+	let start = at
+
+	while (BLANK.test(text.charAt(start - 1))) start -= 1
+
+	return start
+}
+
+// The first token after `node`, skipping comments, so a comma inside a comment is never taken for it.
+function comma_after(api: TypeScriptApi, node: ts.Node): number {
+	const { text } = node.getSourceFile()
+	const scanner = api.createScanner(api.ScriptTarget.Latest, true)
+
+	scanner.setText(text, node.getEnd())
+	scanner.scan()
+
+	return scanner.getTokenStart()
+}
+
+// The name and the comma that separates it — the one after it, else (the last name, with no trailing
+// comma) the one before it. What sits between, a comment included, stays for the formatter.
+function cut_edits(api: TypeScriptApi, element: ts.ImportSpecifier): ReadonlyArray<Replacement> {
+	const { elements } = element.parent
+	const { text } = element.getSourceFile()
+	const at = elements.indexOf(element)
+	const previous = elements[at - 1]
+
+	if (previous === undefined || elements.hasTrailingComma || at < elements.length - 1) {
+		const after = comma_after(api, element) + 1
+
+		return [{ start: element.getStart(), end: blank_end(text, after), text: '' }]
+	}
+
+	const before = comma_after(api, previous)
+	const start = blank_start(text, element.getStart())
+
+	return [
+		{ start: before, end: before + 1, text: '' },
+		{ start, end: element.getEnd(), text: '' },
+	]
+}
+
+// A declaration the name was alone in: it joins another and goes, else it takes the new specifier.
+function alone_edits(
+	declaration: ts.ImportDeclaration,
+	merge: Replacement | undefined,
+	to: string,
+): ReadonlyArray<Replacement> {
+	if (merge === undefined) return [specifier_edit(declaration, to)]
+
+	return [drop_edit(declaration), merge]
+}
+
+function edits_of(
+	api: TypeScriptApi,
+	moving: Moving,
+	clause: ts.ImportClause,
+	to: string,
+): ReadonlyArray<Replacement> {
+	const { element } = moving
+	const keyword = type_keyword(api, clause)
+	const merge = merge_edit(api, moving, keyword, to)
+	const add = merge ?? insert_edit(moving, keyword, to)
+
+	if (element.parent.elements.length > 1) return [...cut_edits(api, element), add]
+	if (clause.name === undefined) return alone_edits(moving.declaration, merge, to)
+
+	return [{ start: clause.name.getEnd(), end: element.parent.getEnd(), text: '' }, add]
+}
+
+// Never `is_taken`: the name keeps its local binding, so the move binds nothing new.
+function rewrite(
+	api: TypeScriptApi,
+	file_name: string,
+	text: string,
+	request: MoveRequest,
+): RenameResult {
+	const source = api.createSourceFile(file_name, text, api.ScriptTarget.Latest, true)
+	const moving = moving_of(api, source, request)
+	const clause = moving?.declaration.importClause
+	if (moving === undefined || clause === undefined) return { text, count: 0, is_taken: false }
+	const edits = edits_of(api, moving, clause, request.to)
+
+	return { text: rename_identifier.apply(text, edits), count: 1, is_taken: false }
+}
+
+const import_move = { rewrite }
+
+export type { MoveRequest }
+export { import_move }

package/scripts/lint/import-test-inputs.ts

@@ -0,0 +1,97 @@
+import { file_reader } from '#scripts/lib/read-file'
+import { test_inputs } from '#scripts/test/test-inputs'
+import type ts from 'typescript'
+import { type_only_imports } from './type-only-imports'
+
+type Resolve = (specifier: string, file: string) => { file: string; external: boolean } | undefined
+
+const DECLARATION_EXTENSION = /\.d\.[cm]?ts$/u
+const TYPESCRIPT_EXTENSION = /\.[cm]?tsx?$/u
+const JAVASCRIPT_EXTENSIONS = ['js', 'jsx', 'mjs', 'cjs']
+
+// TypeScript can resolve a declaration or prefer TS over an existing JS sibling, while the runner
+// executes JS. Without a runtime resolution proof these inputs must be run again.
+function is_runtime_source(typescript: typeof ts, file: string): boolean {
+	if (DECLARATION_EXTENSION.test(file)) return false
+	if (!TYPESCRIPT_EXTENSION.test(file)) return true
+
+	return JAVASCRIPT_EXTENSIONS.every(
+		(extension) =>
+			!typescript.sys.fileExists(file.replace(TYPESCRIPT_EXTENSION, () => `.${extension}`)),
+	)
+}
+
+function dependencies_of(
+	typescript: typeof ts,
+	resolve: Resolve,
+	file: string,
+	content: string,
+): ReadonlyArray<string> | undefined {
+	const specifiers = type_only_imports.runtime_specifiers(typescript, file, content)
+	// Package imports and aliases may pick a different runtime condition than the type checker.
+	const dependencies = specifiers
+		.filter((name) => name !== 'vitest')
+		.map((name) => (name.startsWith('.') ? resolve(name, file) : undefined))
+
+	if (dependencies.some((dependency) => dependency === undefined || dependency.external)) {
+		return undefined
+	}
+
+	return dependencies.flatMap((dependency) => dependency?.file ?? [])
+}
+
+function read_source(
+	typescript: typeof ts,
+	resolve: Resolve,
+	file: string,
+): ReadonlyArray<string> | undefined {
+	if (!is_runtime_source(typescript, file)) return undefined
+	const content = file_reader.read_if_readable(file)
+	if (content === undefined || !test_inputs.is_closed(typescript, file, content)) return undefined
+
+	return dependencies_of(typescript, resolve, file, content)
+}
+
+function unvisited(
+	file: string,
+	reached: ReadonlySet<string>,
+	read: (file: string) => ReadonlyArray<string> | undefined,
+): ReadonlyArray<string> | undefined {
+	return reached.has(file) ? [] : read(file)
+}
+
+function closure(
+	file: string,
+	read: (file: string) => ReadonlyArray<string> | undefined,
+): ReadonlyArray<string> | undefined {
+	const reached = new Set<string>()
+	const pending = [file]
+
+	for (let current = pending.pop(); current !== undefined; current = pending.pop()) {
+		const dependencies = unvisited(current, reached, read)
+		if (dependencies === undefined) return undefined
+		reached.add(current)
+		pending.push(...dependencies)
+	}
+
+	return [...reached]
+}
+
+function create(
+	typescript: typeof ts,
+	resolve: Resolve,
+): (file: string) => ReadonlyArray<string> | undefined {
+	const cache = new Map<string, ReadonlyArray<string> | undefined>()
+
+	function read(file: string): ReadonlyArray<string> | undefined {
+		if (!cache.has(file)) cache.set(file, read_source(typescript, resolve, file))
+
+		return cache.get(file)
+	}
+
+	return (file) => closure(file, read)
+}
+
+const import_test_inputs = { create }
+
+export { import_test_inputs }

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

@@ -62,6 +62,7 @@ function configures_lint(files: ReadonlyArray<string>, root: string): boolean {
 	return verification_inputs.configures(
 		gate_labels.LINT_LABEL,
 		files.map((file) => path.relative(root, file).split(path.sep).join('/')),
+		root,
 	)
 }
 

package/scripts/lint/lint-parallel.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs'
 import { project_checks } from '#scripts/gate/project-checks'
 import { changed_file_scope } from '#scripts/git/changed-file-scope'
 import {
@@ -12,59 +13,114 @@ import {
 	type BufferedProcessResult,
 } from '#scripts/lib/buffered-process'
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
-import { time_format } from '#scripts/time-runtime/time-format'
-import { eslint_cache_dependencies } from './eslint-cache-dependencies'
-import { eslint_daemon } from './eslint-daemon'
+import { eslint_cache_dependencies, type CacheDrop } from './eslint-cache-dependencies'
+import { eslint_daemon, type DaemonCall, type DaemonState } from './eslint-daemon'
+import { eslint_heap } from './eslint-heap'
 import { lint_gate_scope } from './lint-gate-scope'
+import { lint_shard, type LintShard } from './lint-shard'
+import { lint_timing } from './lint-timing'
 
 // 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.
 // A copy here would keep writing the old location the day that constant
 // moves, with every test still green.
-const WHOLE_TREE = '.'
-const ESLINT_ARGS = ['exec', 'eslint', WHOLE_TREE, ...ESLINT_CACHE_FLAGS] as const
+function eslint_args_of(shard: LintShard | undefined): ReadonlyArray<string> {
+	return ['exec', 'eslint', ...lint_shard.eslint_targets(shard), ...ESLINT_CACHE_FLAGS]
+}
+
+const ESLINT_ARGS = eslint_args_of(undefined)
 
 // 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
+function prettier_check_args(targets: ReadonlyArray<string>): ReadonlyArray<string> {
+	return ['exec', 'prettier', '--check', ...targets, ...PRETTIER_CACHE_FLAGS]
+}
+
+const PRETTIER_ARGS = prettier_check_args([lint_shard.WHOLE_TREE])
+
+// The whole tree as this project formats it (`project_checks.prettier_targets`).
+function project_prettier_args(): ReadonlyArray<string> {
+	return prettier_check_args(
+		project_checks.prettier_targets(process.cwd(), [lint_shard.WHOLE_TREE]),
+	)
+}
+
+// `undefined` is a shard that leaves formatting to the other one (`lint-shard.ts`).
+type PrettierArguments = ReadonlyArray<string> | undefined
+
+// Not a skip notice: prettier is used here, only by the other shard.
+const LEFT_TO_FORMATTING_SHARD: BufferedProcessResult = {
+	output: `josh prettier: ${lint_shard.FORMATTING_SHARD_REASON}.\n`,
+	exit_code: 0,
+	elapsed_ms: 0,
+}
+
+function prettier_args_of(shard: LintShard | undefined): PrettierArguments {
+	return lint_shard.checks_formatting(shard) ? project_prettier_args() : undefined
+}
+
+const GATE_TIMING_LABEL = 'lint'
 
 // What one eslint run is made of: the child's arguments and the cache file they name.
 interface EslintRun {
 	args: ReadonlyArray<string>
 	cache_file: string
 	warm_daemon: boolean
+	call?: DaemonCall | undefined
+}
+
+// The name a run's timing line carries and what it read (`lint-timing.ts`).
+interface LintRunTiming {
+	label: string
+	targets: string
 }
 
 // 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.
+// `josh lint:related` names a `timing` too, so its run prints where its seconds went (joshuafolkken/kit#5712).
 interface LintRunOptions {
 	warm_daemon: boolean
+	timing?: LintRunTiming | undefined
+	// What a warm run records beside the daemon (`eslint-daemon-calls.ts`).
+	call?: DaemonCall | undefined
 }
 
 const COLD_RUN: LintRunOptions = { warm_daemon: false }
 
+// Whether the eslint cache was there once the lane's cache sharing had run, before eslint read it,
+// how many of its entries the dependency guard dropped, and what a warm run did with the daemon
+// (`eslint_daemon.run_or_cold`).
+interface EslintResult extends BufferedProcessResult {
+	is_cached?: boolean | undefined
+	drop?: CacheDrop | undefined
+	daemon?: DaemonState | undefined
+}
+
 interface LintPair {
 	prettier: BufferedProcessResult
-	eslint: BufferedProcessResult
+	eslint: EslintResult
 }
 
-// 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)
+// The warm daemon when asked for and reachable, else the cold eslint it falls back to.
+async function run_eslint_process(eslint: EslintRun): Promise<EslintResult> {
+	if (eslint.warm_daemon) return await eslint_daemon.run_or_cold(eslint.args, eslint.call)
 
-	return await buffered_process.run_buffered_process(eslint.args)
+	return await eslint_heap.run_cold(eslint.args)
 }
 
 // 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> {
+async function run_eslint(eslint: EslintRun): Promise<EslintResult> {
 	const { cache_file } = eslint
 
 	return await lane_cache_run.run(cache_file, async () => {
-		return await eslint_cache_dependencies.guard(
+		const is_cached = existsSync(cache_file)
+		const { result, drop } = await eslint_cache_dependencies.guard_counted(
 			cache_file,
 			async () => await run_eslint_process(eslint),
 		)
+
+		return { ...result, is_cached, drop }
 	})
 }
 
@@ -83,18 +139,17 @@ function skipped(check: string, reason: string): BufferedProcessResult {
 
 async function run_prettier(
 	directory: string,
-	prettier_args: ReadonlyArray<string>,
+	prettier_args: PrettierArguments,
 ): Promise<BufferedProcessResult> {
+	if (prettier_args === undefined) return LEFT_TO_FORMATTING_SHARD
+
 	const reason = project_checks.prettier_skip_reason(directory)
 	if (reason !== undefined) return skipped('prettier', reason)
 
-	return await buffered_process.run_buffered_process(prettier_args)
+	return await buffered_process.run_buffered_direct(prettier_args)
 }
 
-async function run_checked_eslint(
-	directory: string,
-	eslint: EslintRun,
-): Promise<BufferedProcessResult> {
+async function run_checked_eslint(directory: string, eslint: EslintRun): Promise<EslintResult> {
 	const reason = project_checks.eslint_skip_reason(directory)
 	if (reason !== undefined) return skipped('eslint', reason)
 
@@ -130,7 +185,7 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 // run would have skipped. The skip reasons answer nothing for a full
 // project, so the one path serves both profiles.
 async function run_lint_pair(
-	prettier_args: ReadonlyArray<string>,
+	prettier_args: PrettierArguments,
 	eslint_args: ReadonlyArray<string>,
 	cache_file: string,
 	options: LintRunOptions,
@@ -151,72 +206,122 @@ function write_lint_pair({ prettier, eslint }: LintPair): number {
 	return lint_exit_code(prettier, eslint)
 }
 
+function timing_line(pair: LintPair, label: string, facts: ReadonlyArray<string>): string {
+	const { prettier, eslint } = pair
+
+	return lint_timing.line({
+		label,
+		prettier_ms: prettier.elapsed_ms,
+		eslint_ms: eslint.elapsed_ms,
+		facts,
+	})
+}
+
+// A run that never asked for the daemon, or skipped eslint, names none.
+function daemon_fact(eslint: EslintResult): string {
+	return eslint.daemon ?? 'cold process'
+}
+
+function drop_fact({ dropped, total }: CacheDrop): string {
+	return `${String(dropped)} of ${String(total)} cache entries dropped`
+}
+
+// The drop is named only where the cache was there to drop from.
+function cache_fact(eslint: EslintResult): string {
+	if (eslint.is_cached !== true) return 'cache absent'
+
+	return eslint.drop === undefined ? 'cache present' : `cache present · ${drop_fact(eslint.drop)}`
+}
+
+// A run that names a `timing` prints its line after the linters' output: the tools' seconds, then
+// what it read, the daemon it found and the cache it started from (joshuafolkken/kit#5712).
 async function run_lint_checks(
-	prettier_args: ReadonlyArray<string>,
+	prettier_args: PrettierArguments,
 	eslint_args: ReadonlyArray<string>,
 	cache_file: string,
 	options: LintRunOptions = COLD_RUN,
 ): Promise<number> {
-	return write_lint_pair(await run_lint_pair(prettier_args, eslint_args, cache_file, options))
-}
+	const { timing } = options
+
+	if (timing === undefined) {
+		return write_lint_pair(await run_lint_pair(prettier_args, eslint_args, cache_file, options))
+	}
+
+	const pair = await run_lint_pair(prettier_args, eslint_args, cache_file, options)
+	const exit_code = write_lint_pair(pair)
+	const facts = [timing.targets, daemon_fact(pair.eslint), cache_fact(pair.eslint)]
 
-// joshuafolkken/kit#5116: the gate times `lint` as one step, and the two tools run side by side, so
-// the step's seconds name neither tool as the long pole. This line, the gate's lint alone, does.
-function timing_line({ prettier, eslint }: LintPair): string {
-	const prettier_seconds = time_format.format_seconds(prettier.elapsed_ms)
-	const eslint_seconds = time_format.format_seconds(eslint.elapsed_ms)
+	process.stdout.write(timing_line(pair, timing.label, facts))
 
-	return `lint timing — prettier ${prettier_seconds} · eslint ${eslint_seconds}\n`
+	return exit_code
 }
 
 async function run_timed_lint_checks(
-	prettier_args: ReadonlyArray<string>,
+	prettier_args: PrettierArguments,
 	eslint_args: ReadonlyArray<string>,
 	cache_file: string,
 ): Promise<number> {
 	const pair = await run_lint_pair(prettier_args, eslint_args, cache_file, COLD_RUN)
 	const exit_code = write_lint_pair(pair)
 
-	process.stdout.write(timing_line(pair))
+	// joshuafolkken/kit#5116: the gate times `lint` as one step, so only this line names the long pole;
+	// its cache fact says how much of a slow CI lint the dependency guard sent back to eslint (#6984).
+	process.stdout.write(timing_line(pair, GATE_TIMING_LABEL, [cache_fact(pair.eslint)]))
 
 	return exit_code
 }
 
-async function run_lint_parallel_checks(): Promise<number> {
-	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS, ESLINT_CACHE_FILE)
+async function run_lint_parallel_checks(options: LintRunOptions = COLD_RUN): Promise<number> {
+	return await run_lint_checks(project_prettier_args(), ESLINT_ARGS, ESLINT_CACHE_FILE, options)
 }
 
 // `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> {
+// whole tree — or its `--shard` — 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. A narrowed run reads the
+// changed files whatever the shard: both shards then lint them, which costs a repeat and loses nothing.
+async function run_whole_lint_checks(
+	scope_line: string,
+	shard: LintShard | undefined,
+): Promise<number> {
+	process.stdout.write(`${scope_line}${lint_shard.describe(shard)}\n`)
+
+	return await run_timed_lint_checks(
+		prettier_args_of(shard),
+		eslint_args_of(shard),
+		ESLINT_CACHE_FILE,
+	)
+}
+
+async function run_changed_lint_checks(shard: LintShard | undefined): 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)
+	const scope_line = lint_gate_scope.describe_scope(scope, root)
 
-	process.stdout.write(`${lint_gate_scope.describe_scope(scope, root)}\n`)
-
-	if (scope.mode === 'all') {
-		return await run_timed_lint_checks(PRETTIER_ARGS, ESLINT_ARGS, ESLINT_CACHE_FILE)
-	}
+	if (scope.mode === 'all') return await run_whole_lint_checks(scope_line, shard)
 
+	process.stdout.write(`${scope_line}\n`)
 	const narrowed = lint_gate_scope.narrowed_run(scope.files)
 
 	return await run_timed_lint_checks(narrowed.prettier, narrowed.eslint, narrowed.eslint_cache_file)
 }
 
 async function run_lint_command(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const shard = lint_shard.shard_of(command_arguments)
+
 	if (command_arguments.includes(lint_gate_scope.CHANGED_FLAG)) {
-		return await run_changed_lint_checks()
+		return await run_changed_lint_checks(shard)
 	}
 
-	return await run_lint_parallel_checks()
+	return await run_lint_checks(prettier_args_of(shard), eslint_args_of(shard), ESLINT_CACHE_FILE)
 }
 
 const lint_parallel = {
+	run_eslint,
 	run_lint_checks,
 	run_lint_command,
 	run_lint_parallel_checks,
 }
 
+export type { LintRunTiming }
 export { ESLINT_ARGS, lint_parallel, PRETTIER_ARGS }