@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/lint/lint-parallel.ts

@@ -12,6 +12,7 @@ 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 { lint_gate_scope } from './lint-gate-scope'
@@ -42,6 +43,11 @@ interface LintRunOptions {
 
 const COLD_RUN: LintRunOptions = { warm_daemon: false }
 
+interface LintPair {
+	prettier: BufferedProcessResult
+	eslint: BufferedProcessResult
+}
+
 // 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)
@@ -62,8 +68,13 @@ async function run_eslint(eslint: EslintRun): Promise<BufferedProcessResult> {
 	})
 }
 
+// execa strips the child's final newline, so each output is closed here: unclosed, the next tool's
+// output, or the timing line, would start on the same line as prettier's last one.
 function write_output(result: BufferedProcessResult): void {
-	if (result.output) process.stdout.write(result.output)
+	const { output } = result
+	if (!output) return
+
+	process.stdout.write(output.endsWith('\n') ? output : `${output}\n`)
 }
 
 function skipped(check: string, reason: string): BufferedProcessResult {
@@ -118,24 +129,59 @@ 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.
-async function run_lint_checks(
+async function run_lint_pair(
 	prettier_args: ReadonlyArray<string>,
 	eslint_args: ReadonlyArray<string>,
 	cache_file: string,
-	options: LintRunOptions = COLD_RUN,
-): Promise<number> {
+	options: LintRunOptions,
+): Promise<LintPair> {
 	const directory = process.cwd()
 	const [prettier, eslint] = await Promise.all([
 		run_prettier(directory, prettier_args),
 		run_checked_eslint(directory, { args: eslint_args, cache_file, ...options }),
 	])
 
+	return { prettier, eslint }
+}
+
+function write_lint_pair({ prettier, eslint }: LintPair): number {
 	write_output(with_ran_notice('prettier', prettier, eslint))
 	write_output(with_ran_notice('eslint', eslint, prettier))
 
 	return lint_exit_code(prettier, eslint)
 }
 
+async function run_lint_checks(
+	prettier_args: ReadonlyArray<string>,
+	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))
+}
+
+// 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)
+
+	return `lint timing — prettier ${prettier_seconds} · eslint ${eslint_seconds}\n`
+}
+
+async function run_timed_lint_checks(
+	prettier_args: ReadonlyArray<string>,
+	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))
+
+	return exit_code
+}
+
 async function run_lint_parallel_checks(): Promise<number> {
 	return await run_lint_checks(PRETTIER_ARGS, ESLINT_ARGS, ESLINT_CACHE_FILE)
 }
@@ -150,11 +196,13 @@ async function run_changed_lint_checks(): Promise<number> {
 
 	process.stdout.write(`${lint_gate_scope.describe_scope(scope, root)}\n`)
 
-	if (scope.mode === 'all') return await run_lint_parallel_checks()
+	if (scope.mode === 'all') {
+		return await run_timed_lint_checks(PRETTIER_ARGS, ESLINT_ARGS, ESLINT_CACHE_FILE)
+	}
 
 	const narrowed = lint_gate_scope.narrowed_run(scope.files)
 
-	return await run_lint_checks(narrowed.prettier, narrowed.eslint, narrowed.eslint_cache_file)
+	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> {

package/scripts/lint/lint-related.ts

@@ -2,12 +2,18 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { document_byte_check } from '#scripts/document/document-byte-check'
-import { gate_plan } from '#scripts/gate/gate-plan'
+import { document_checks } from '#scripts/document/document-checks'
+import { unused_members_check } from '#scripts/exports/unused-members-check'
+import { gate_labels } from '#scripts/gate/gate-labels'
+import type { GateTree } from '#scripts/gate/gate-tree'
+import { metrics_totals } from '#scripts/gate/metrics-totals'
 import { scoped_green } from '#scripts/gate/scoped-green'
 import { since_green } from '#scripts/gate/since-green'
+import { structural_checks } from '#scripts/gate/structural-checks'
+import { verification_tail } from '#scripts/gate/verification-tail'
 import { changed_file_scope, type ChangedFileScope } from '#scripts/git/changed-file-scope'
 import { review_stamps } from '#scripts/review/review-stamps'
+import { split_early_notice } from '#scripts/split/split-early-notice'
 import { lint_parallel } from './lint-parallel'
 import { lint_related_scope } from './lint-related-scope'
 
@@ -44,34 +50,85 @@ async function lint_exit_code(scope: ChangedFileScope): Promise<number> {
 	)
 }
 
-// The byte check over the same scope the lint just ran: the resolved file list when narrowed, and
-// the whole budget when lint fell back to the whole tree — so the byte check is a superset in the
-// fallback exactly as lint is, never an empty list that would pass silently.
-function byte_check_exit_code(scope: ChangedFileScope, root: string): number {
-	if (scope.mode === 'all') return document_byte_check.check_all(root)
+// The document checks over the same scope the lint just ran: the resolved file list when narrowed,
+// and the whole budget when lint fell back to the whole tree — so each is a superset in the
+// fallback exactly as lint is, never an empty list that would pass silently. Both run, so one edit
+// reports its byte ceiling and its ratchets (`document-ratchet-check.ts`) in one pass.
+function document_check_exit_code(scope: ChangedFileScope, root: string): number {
+	if (scope.mode === 'all') return document_checks.check_all(root)
 
-	return document_byte_check.check_files(root, scope.files)
+	return document_checks.check_files(root, scope.files)
 }
 
-// The lint result folded together with the fast byte-ceiling check: the
-// same check the gate's `document-byte-budget.test.ts` runs, brought forward to this between-edits
-// path so a mandated documentation update over its ceiling surfaces in seconds. It reads no change
+interface LintOutcome {
+	stage: string
+	exit_code: number
+}
+
+const UNMOVED: LintOutcome = { stage: 'unmoved', exit_code: 0 }
+
+function is_failed(outcome: LintOutcome): boolean {
+	return outcome.exit_code !== 0
+}
+
+// The lint result folded together with the fast document checks: the
+// same checks the gate's `document-byte-budget.test.ts`, `command-reference.test.ts` and
+// `issue-citation-budget.test.ts` run, brought forward to this between-edits path so a mandated
+// documentation update over a ceiling surfaces in seconds. It reads no change
 // of its own — it takes the files this run already resolved, so the git contract is the lint
-// command's alone. A lint failure is reported as-is; only a green lint runs the byte check, so the
+// command's alone. A lint failure is reported as-is; only a green lint runs the document checks, so the
 // two never race to the exit code, and a green tree here is green on both — which is what the record
-// below then vouches for.
-async function scoped_exit_code(scope: ChangedFileScope, root: string): Promise<number> {
-	const lint_exit = await lint_exit_code(scope)
-	if (lint_exit !== 0) return lint_exit
+// below then vouches for. The structural checks (`structural-checks.ts`) run beside the lint rather
+// than after it, so their whole-program scan costs no wall clock the lint has not already spent.
+//
+// The gate's `exports` check comes after them on the same terms: a namespace member nothing reads is
+// reported here for the namespaces the changed files declare or import directly
+// (joshuafolkken/kit#4645, joshuafolkken/kit#4649), rather than at ship's pre-detach gate. The
+// fallback scans the whole program, a superset as the lint's is.
+//
+// The outcome names the stage that failed first, which the verdict line names (joshuafolkken/kit#5162).
+async function scoped_outcome(scope: ChangedFileScope, root: string): Promise<LintOutcome> {
+	const structural = structural_checks.run_structural(scope, root)
+	const lint = { stage: 'lint', exit_code: await lint_exit_code(scope) }
+	const failed = [lint, { stage: 'structural', exit_code: await structural }].find((outcome) =>
+		is_failed(outcome),
+	)
+
+	if (failed !== undefined) return failed
+	// The linters' buffered output ends without a newline; keep the checks' own lines apart from it.
+	process.stdout.write('\n')
+	const documents = { stage: 'documents', exit_code: document_check_exit_code(scope, root) }
+	if (is_failed(documents)) return documents
+
+	const files = scope.mode === 'all' ? undefined : scope.files
 
-	return byte_check_exit_code(scope, root)
+	return {
+		stage: 'unused members',
+		exit_code: await unused_members_check.run_unused_members(root, files),
+	}
 }
 
-// **A bare run reads only what moved since its last green run** (`since-green.ts`), while a lintable file
-// is among it; otherwise the whole branch change, as before.
-async function since_green_scope(root: string): Promise<ChangedFileScope | undefined> {
-	const moved = await since_green.read_moved(review_stamps.lint_related_stamp, gate_plan.LINT_LABEL)
+// **A bare run reads only what moved since its last green run** (`since-green.ts`), against the tree
+// its green record is read from, so one run reads the gate tree once (joshuafolkken/kit#4655).
+// Explicit file arguments read no tree, so they never consult the record.
+async function read_since_green(
+	before: GateTree | undefined,
+): Promise<ReadonlyArray<string> | undefined> {
+	if (before === undefined) return undefined
+
+	return await since_green.read_moved(
+		review_stamps.lint_related_stamp,
+		gate_labels.LINT_LABEL,
+		undefined,
+		before,
+	)
+}
 
+// Narrowed to what moved while a lintable file is among it; otherwise the whole branch change, as before.
+function since_green_scope(
+	root: string,
+	moved: ReadonlyArray<string> | undefined,
+): ChangedFileScope | undefined {
 	if (moved === undefined) return undefined
 
 	const inputs = lint_related_scope.scope_inputs(existsSync)
@@ -87,8 +144,9 @@ async function since_green_scope(root: string): Promise<ChangedFileScope | undef
 async function resolve_lint_scope(
 	command_arguments: ReadonlyArray<string>,
 	root: string,
+	moved: ReadonlyArray<string> | undefined,
 ): Promise<ChangedFileScope> {
-	const since = command_arguments.length === 0 ? await since_green_scope(root) : undefined
+	const since = since_green_scope(root, moved)
 
 	if (since !== undefined) return since
 
@@ -99,17 +157,33 @@ async function resolve_lint_scope(
 	})
 }
 
+// In kit, a metrics total grown past the merge-base is reported after the lint and changes no exit
+// code (`metrics-totals.ts`). The totals are a whole-repository pass, so only a green bare run pays
+// for it: a red lint is edited again anyway, and a run narrowed by file arguments is a spot check.
+async function outcome_with_notice(
+	command_arguments: ReadonlyArray<string>,
+	scope: ChangedFileScope,
+	root: string,
+): Promise<LintOutcome> {
+	const outcome = await scoped_outcome(scope, root)
+	if (is_failed(outcome) || command_arguments.length > 0) return outcome
+
+	const notice = await metrics_totals.growth_notice(root)
+
+	// On a line of its own: a linter's buffered output need not end with a newline.
+	if (notice !== undefined) process.stdout.write(`\n${notice}\n`)
+
+	return outcome
+}
+
 // The narrowing line is printed before either child starts, so a scoped run is never read as a
 // whole one, and a fallback says which of the two it was rather than looking like a narrow run
 // that found nothing.
-//
-// **A green run leaves a record of the tree it was green on**, so
-// `josh review:brief` can tell a tree this check has read from one it has not. What the record means,
-// and the three states in which it is withheld, are `scoped-green.ts`.
-async function run_related_lint(command_arguments: ReadonlyArray<string>): Promise<number> {
-	const root = await changed_file_scope.repository_root_or_cwd()
-	const scope = await resolve_lint_scope(command_arguments, root)
-
+function report_scope(
+	command_arguments: ReadonlyArray<string>,
+	scope: ChangedFileScope,
+	root: string,
+): void {
 	changed_file_scope.report_unusable_arguments(
 		command_arguments,
 		scope,
@@ -117,17 +191,64 @@ async function run_related_lint(command_arguments: ReadonlyArray<string>): Promi
 	)
 	report_ignored_flags(command_arguments)
 	process.stdout.write(`${lint_related_scope.describe_scope(scope, root)}\n`)
+}
+
+// **Nothing moved since the last green run lints nothing** (joshuafolkken/kit#4593), as
+// `josh test:related` runs no test.
+function report_unmoved(): LintOutcome {
+	process.stdout.write(
+		`${lint_related_scope.COMMAND_LABEL}: ${since_green.UNMOVED_REASON} — linting nothing.\n`,
+	)
+
+	return UNMOVED
+}
+
+async function checked_outcome(
+	command_arguments: ReadonlyArray<string>,
+	root: string,
+	moved: ReadonlyArray<string> | undefined,
+): Promise<LintOutcome> {
+	if (moved?.length === 0) return report_unmoved()
 
+	const scope = await resolve_lint_scope(command_arguments, root, moved)
+
+	report_scope(command_arguments, scope, root)
+
+	return await outcome_with_notice(command_arguments, scope, root)
+}
+
+// The run's last line names the stage that failed, or says it passed; the console is the only copy of
+// the output, so there is no log notice (`verification-tail.ts`).
+function report_verdict(outcome: LintOutcome): void {
+	const failed = is_failed(outcome) ? [outcome.stage] : []
+	const verdict = verification_tail.format_verdict(lint_related_scope.COMMAND_LABEL, failed)
+
+	process.stdout.write(`\n${verification_tail.format_tail({ failures: '', verdict })}`)
+}
+
+// **A green run leaves a record of the tree it was green on**, so
+// `josh review:brief` can tell a tree this check has read from one it has not. What the record means,
+// and the three states in which it is withheld, are `scoped-green.ts`. An unmoved run records too, as
+// `josh test:related`'s does: a main sync can move the base while moving no path, and a record left on
+// the old base would refuse `josh gate` while every re-run kept linting nothing.
+async function run_related_lint(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const root = await changed_file_scope.repository_root_or_cwd()
 	const before = await scoped_green.read_before(command_arguments)
-	const exit_code = await scoped_exit_code(scope, root)
+	const moved = await read_since_green(before)
+	const outcome = await checked_outcome(command_arguments, root, moved)
 
-	await scoped_green.record_if_green(review_stamps.lint_related_stamp, { before, exit_code })
+	report_verdict(outcome)
+	await scoped_green.record_if_green(review_stamps.lint_related_stamp, {
+		before,
+		exit_code: outcome.exit_code,
+	})
 
-	return exit_code
+	return outcome.exit_code
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_related_lint(process.argv.slice(changed_file_scope.ARGV_START))
+	await split_early_notice.surface()
 }
 
 const lint_related = { run_related_lint }

package/scripts/lint/rename-cli.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env tsx
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { format_edited_payload } from '#scripts/hooks/format-edited-file'
+import { rename_identifier, type RenameRequest, type TypeScriptApi } from './rename-identifier'
+
+// `josh rename <old> <new> [--import <old-specifier> <new-specifier>] <file...>` — one identifier, and
+// the import specifier it moved with, renamed across files in one call (joshuafolkken/kit#5236), where
+// a lane would otherwise spend one Read and one Edit per file.
+//
+// **All or nothing**: a file the rename would not touch is named and nothing is written, since a path
+// passed by mistake means the file list is not the one the caller thinks it is. Each written file is
+// then formatted the way the edit hook formats an edited one — a Bash write gets no hook.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const IMPORT_FLAG = '--import'
+const SPECIFIER_COUNT = 2
+// What the TypeScript parser reads whole; a `.svelte` file's markup would be parsed as script.
+const SCRIPT_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+])
+const IDENTIFIER = /^[$A-Z_a-z][\w$]*$/u
+const USAGE = `Usage: josh rename <old-identifier> <new-identifier> [${IMPORT_FLAG} <old-specifier> <new-specifier>] <file...>`
+
+interface RenameArguments {
+	request: RenameRequest
+	files: ReadonlyArray<string>
+}
+
+interface FileRename {
+	file: string
+	text: string
+	count: number
+	is_taken: boolean
+}
+
+type Formatter = (files: ReadonlyArray<string>) => Promise<void>
+
+interface SplitArguments {
+	specifier: RenameRequest['specifier']
+	rest: ReadonlyArray<string>
+}
+
+function split_import(argv: ReadonlyArray<string>): SplitArguments | undefined {
+	const at = argv.indexOf(IMPORT_FLAG)
+
+	if (at === -1) return { specifier: undefined, rest: argv }
+	const [from, to] = argv.slice(at + 1, at + 1 + SPECIFIER_COUNT)
+	if (from === undefined || to === undefined) return undefined
+
+	return { specifier: [from, to], rest: argv.toSpliced(at, 1 + SPECIFIER_COUNT) }
+}
+
+function arguments_of(split: SplitArguments): RenameArguments | undefined {
+	const [old_name = '', new_name = '', ...files] = split.rest
+
+	if (!IDENTIFIER.test(old_name) || !IDENTIFIER.test(new_name)) return undefined
+
+	return { request: { old_name, new_name, specifier: split.specifier }, files }
+}
+
+function parse(argv: ReadonlyArray<string>): RenameArguments | undefined {
+	const split = split_import(argv)
+	const parsed = split === undefined ? undefined : arguments_of(split)
+
+	return parsed?.files.length === 0 ? undefined : parsed
+}
+
+function refuse(reason: string, files: ReadonlyArray<string>): number {
+	console.error(`josh rename: ${reason}: ${files.join(', ')} — nothing was written`)
+
+	return FAILURE_EXIT_CODE
+}
+
+function rename_all(api: TypeScriptApi, parsed: RenameArguments): ReadonlyArray<FileRename> {
+	return parsed.files.map((file) => ({
+		file,
+		...rename_identifier.rewrite(api, file, readFileSync(file, 'utf8'), parsed.request),
+	}))
+}
+
+async function write_all(
+	renames: ReadonlyArray<FileRename>,
+	formatter: Formatter,
+): Promise<number> {
+	for (const rename of renames) {
+		writeFileSync(rename.file, rename.text)
+		console.info(`${rename.file}: ${String(rename.count)}`)
+	}
+
+	await formatter(renames.map((rename) => rename.file))
+
+	return 0
+}
+
+function file_refusal(files: ReadonlyArray<string>): number | undefined {
+	const missing = files.filter((file) => !existsSync(file))
+	if (missing.length > 0) return refuse('no such file', missing)
+	const unparsed = files.filter((file) => !SCRIPT_EXTENSIONS.has(path.extname(file)))
+
+	return unparsed.length > 0 ? refuse('not a TypeScript or JavaScript file', unparsed) : undefined
+}
+
+function files_where(
+	renames: ReadonlyArray<FileRename>,
+	is_match: (rename: FileRename) => boolean,
+): ReadonlyArray<string> {
+	return renames.filter((rename) => is_match(rename)).map((rename) => rename.file)
+}
+
+// The rename matches by spelling, so a file that already binds the new name could end up with one
+// binding shadowing or merging with another; it is refused rather than guessed at.
+function rename_refusal(renames: ReadonlyArray<FileRename>, new_name: string): number | undefined {
+	const untouched = files_where(renames, (rename) => rename.count === 0)
+	if (untouched.length > 0) return refuse('no replacement', untouched)
+	const taken = files_where(renames, (rename) => rename.is_taken)
+
+	return taken.length > 0 ? refuse(`\`${new_name}\` is already bound`, taken) : undefined
+}
+
+async function apply(
+	api: TypeScriptApi,
+	parsed: RenameArguments,
+	formatter: Formatter,
+): Promise<number> {
+	const file_stop = file_refusal(parsed.files)
+	if (file_stop !== undefined) return file_stop
+	const renames = rename_all(api, parsed)
+
+	return rename_refusal(renames, parsed.request.new_name) ?? (await write_all(renames, formatter))
+}
+
+// The edit hook's own formatter, one file at a time: each run rewrites the file the next may import.
+async function format_files(
+	files: ReadonlyArray<string>,
+	format_one: typeof format_edited_payload = format_edited_payload,
+): Promise<void> {
+	for (const file of files) {
+		const payload = JSON.stringify({ tool_input: { file_path: path.resolve(file) } })
+		// eslint-disable-next-line no-await-in-loop -- formatters rewrite files the next run reads
+		const diagnostics = await format_one(payload, process.cwd())
+
+		if (diagnostics !== undefined) console.info(diagnostics)
+	}
+}
+
+async function run(
+	argv: ReadonlyArray<string>,
+	api: TypeScriptApi,
+	formatter: Formatter = format_files,
+): Promise<number> {
+	const parsed = parse(argv)
+
+	if (parsed !== undefined) return await apply(api, parsed, formatter)
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	const typescript = await import('typescript')
+
+	process.exitCode = await run(argv, typescript.default)
+}
+
+const rename_cli = { USAGE, format_files, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { rename_cli }