@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/lib/error-message.ts

@@ -7,7 +7,7 @@ function message_of(error: unknown): string {
 const DEBUG_ENV_KEY = 'JOSH_DEBUG'
 
 // A catch that folds a failure into a state verdict — "dirty", "not merged", "not written" — leaves no
-// trace of why by default, so a wrong verdict cannot be followed back to its cause (joshuafolkken/kit#3067).
+// trace of why by default, so a wrong verdict cannot be followed back to its cause.
 // `JOSH_DEBUG` set to any non-blank value writes the swallowed reason to stderr; unset, nothing changes.
 function trace_swallowed(where: string, error: unknown): void {
 	if ((process.env[DEBUG_ENV_KEY] ?? '').trim() === '') return

package/scripts/lib/json-value.ts

@@ -1,10 +1,12 @@
-// Reading JSON that may not be JSON (joshuafolkken/kit#1151).
+import type { z } from 'zod'
+
+// Reading JSON that may not be JSON.
 //
 // Readers under `scripts/` parse text that a defect, a truncated write or an older format can make
 // unparseable — a transcript line, a settings file, an MCP declaration, a lock record, CLI output —
 // and every one of them answers "could not read this" rather than throwing, because a single bad line
 // must not fail a whole report. They had begun to carry a copy of the same try/catch each; this is the
-// one copy, and `is_record` beside it is the one object test (joshuafolkken/kit#2986).
+// one copy, and `is_record` beside it is the one object test.
 
 function parse_or_undefined(text: string): unknown {
 	try {
@@ -14,12 +16,24 @@ function parse_or_undefined(text: string): unknown {
 	}
 }
 
+// The same read with a shape asked of it: text that is not JSON and JSON the schema rejects both
+// answer `undefined`, which is what a best-effort reader of a record, a payload or CLI output wants.
+// A reader that must tell the two apart, or keep a shape change visible, is `parse-json-array.ts`.
+function parse_with<T>(text: string, schema: z.ZodType<T>): T | undefined {
+	const value = parse_or_undefined(text)
+	if (value === undefined) return undefined
+
+	const parsed = schema.safeParse(value)
+
+	return parsed.success ? parsed.data : undefined
+}
+
 // A plain object, as opposed to an array or a primitive. `typeof null` is `'object'`, and an array
 // answers `'object'` too, so both have to be excluded by hand before a key lookup means anything.
 function is_record(value: unknown): value is Record<string, unknown> {
 	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-const json_value = { parse_or_undefined, is_record }
+const json_value = { parse_or_undefined, parse_with, is_record }
 
 export { json_value }

package/scripts/lib/poll.ts

@@ -2,7 +2,7 @@
 //
 // **Three modules had already written the same three-line `sleep`** — `gh/git-pr-checks.ts`,
 // `eval/eval-run.ts` and `propagate/propagate-publish.ts` — and the release command's tag watch
-// (joshuafolkken/kit#1169) would have been the fourth. `CLAUDE.md` → "No clones — single-source"
+// would have been the fourth. `CLAUDE.md` → "No clones — single-source"
 // reads an existing duplication as the signal to single-source it rather than as a license to add to
 // it, so the definition moved here and those three import it.
 //

package/scripts/lib/status-icons.ts

@@ -1,4 +1,4 @@
-// The icons josh prints in front of a result line (joshuafolkken/kit#1361).
+// The icons josh prints in front of a result line.
 //
 // They were one character each, declared beside whichever command printed them — the verification
 // gate, the health check, the propagation run — and that was harmless while nothing ever *read*
@@ -11,9 +11,9 @@
 // the health check use `✔`, and unifying those would change what a command prints in order to tidy a
 // constant — a decision about output, not about single-sourcing.
 //
-// **The success icon is read too since joshuafolkken/kit#1374.** `josh-verdict.ts` reads the gate's
+// **The success icon is read too.** `josh-verdict.ts` reads the gate's
 // `✔ verification gate passed` line to tell a green gate from the third-party warning bodies it
-// forwards, so the pass icon is now under the same rule the failure icon has been under: declared
+// forwards, so the pass icon is under the same rule as the failure icon: declared
 // once, imported by the printer and the reader alike.
 
 const FAIL_ICON = '✗'

package/scripts/lib/timed-fetch.ts

@@ -1,6 +1,6 @@
 import { FETCH_TIMEOUT_MS } from './timeouts'
 
-// **The one place in `scripts/` that calls the global `fetch`** (joshuafolkken/kit#2981). Every request
+// **The one place in `scripts/` that calls the global `fetch`**. Every request
 // carries a time limit, so a stalled connection rejects instead of holding an unattended run forever;
 // `timed-fetch-usage.test.ts` refuses a direct `fetch` call anywhere else. The signal also bounds the
 // body read, because the response stream aborts with it.

package/scripts/lib/timeouts.ts

@@ -1,6 +1,6 @@
 // Shared time limits for the calls that leave the process — a network request or a spawned command.
 // An unattended run (a lane, `followup`, a backlog drain) that waits on a request or a command with no
-// limit stays stuck where it stopped and never comes back (joshuafolkken/kit#2981), so every such
+// limit stays stuck where it stopped and never comes back, so every such
 // call takes one of these, and a value used in more than one place is named once here.
 
 // A probe that only asks the local machine (`ps`, `lsof`, `git config`) on a path something else is

package/scripts/lines/bytes-command.ts

@@ -9,7 +9,7 @@ import { resident_budget } from '#scripts/document/resident-budget'
 // The package root, resolved from this file rather than the caller's working directory.
 const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url))
 
-// `josh bytes` — the byte counterpart of `josh lines` (joshuafolkken/kit#2176). A mandated
+// `josh bytes` — the byte counterpart of `josh lines`. A mandated
 // documentation update that grows an agent-read document past its byte ceiling is invisible until
 // `pnpm josh gate` reports it 80–90 seconds in, and the raise that follows is rework. This answers
 // the same question before that: how many bytes each budgeted document already has, its ceiling, and
@@ -81,8 +81,7 @@ function remaining_phrase(remaining: number): string {
 }
 
 // The resident document is held by a fixed limit rather than a block ratchet, and loosening it is
-// Tier C, so its row names the headroom or the overage but never a value to raise it to
-// (joshuafolkken/kit#3171).
+// Tier C, so its row names the headroom or the overage but never a value to raise it to.
 function resident_row(status: DocumentStatus): string {
 	const counts = `${status.current.toString()}/${status.recorded.toString()} bytes`
 
@@ -147,7 +146,7 @@ function entry_status_of(entry: string, recorded: number): EntryStatus {
 
 // The primary budget, one row per entry: the total each workflow entry reads against its recorded
 // ceiling and the headroom left — printed on every scan, so the main budget is no longer a number the
-// gate reveals only when it fails (joshuafolkken/kit#2271).
+// gate reveals only when it fails.
 function entry_row(status: EntryStatus): string {
 	const counts = `${status.current.toString()}/${status.recorded.toString()} bytes`
 

package/scripts/lines/effective-limit.ts

@@ -3,21 +3,18 @@ import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { z } from 'zod'
 
-// joshuafolkken/kit#1454: `pnpm josh lines` asked the project's own eslint how many code lines a file
-// has, and then explained that answer against **kit's** `max-lines` entry. In kit the two are the same
-// object, so nothing showed; in a consumer whose `eslint.config.js` overrides the rule after
-// `create_base_config`, the report and the gate described different limits — and the report was the one
-// that was wrong, while `line-budget.ts` opens by declaring that agreeing with the gate is the whole of
-// its purpose.
+// Resolves the `max-lines` entry the project's own eslint applies, so `pnpm josh lines` explains its
+// count against the limit the gate enforces — in a consumer whose `eslint.config.js` overrides the
+// rule after `create_base_config`, kit's own entry would describe a different limit.
 //
-// **The limit is therefore asked of the configuration the gate actually applies, per file.** A flat
+// **The limit is asked of the configuration the gate actually applies, per file.** A flat
 // config block can key an override on a `files` pattern, so "the project's limit" is not one number: a
 // consumer that raises `max-lines` for generated code and leaves it alone elsewhere enforces two, and a
 // report that picked either would be wrong about the other set.
 //
 // **The counting options travel with it, and that is not a widening of the subject.** `skipBlankLines`
 // and `skipComments` decide what a code line *is*, and taking them from kit while taking the count from
-// the consumer's eslint is the same defect wearing a different number. Both now come from the same
+// the consumer's eslint would mismatch the two the same way. Both come from the same
 // resolved entry, so there is one source rather than two that can disagree.
 //
 // **This is the resolution `eslint --print-config` performs, not a second linter.** `line-budget.ts`
@@ -43,7 +40,11 @@ interface ConfigResolver {
 	calculateConfigForFile: (file_path: string) => Promise<unknown>
 }
 
-type ResolverConstructor = new (options: { cwd: string }) => ConfigResolver
+// eslint's own camelCase name for the option, kept apart from the object that spells it.
+const CONFIG_FILE_OPTION = 'overrideConfigFile'
+
+type ResolverOptions = { cwd: string } & Partial<Record<typeof CONFIG_FILE_OPTION, string>>
+type ResolverConstructor = new (options: ResolverOptions) => ConfigResolver
 
 // The module is imported from a path computed at runtime, so its shape is checked rather than assumed:
 // a build that no longer exports `ESLint` must answer "no limit" instead of throwing past the caller.
@@ -100,13 +101,19 @@ function options_in(config: unknown): LineRuleOptions | undefined {
 // the consumer's own eslint. Every failure — no eslint there, a build without the export, a config that
 // throws while loading — is the same answer, and it is "no limit" rather than kit's number: falling
 // back to kit's is precisely the defect this file exists to remove, and it would be silent.
-async function resolver_for(project_root: string): Promise<ConfigResolver | undefined> {
+async function resolver_for(
+	project_root: string,
+	config_file: string | undefined,
+): Promise<ConfigResolver | undefined> {
 	try {
 		const require_from = createRequire(path.join(project_root, PACKAGE_JSON))
 		const loaded: unknown = await import(pathToFileURL(require_from.resolve(ESLINT_MODULE)).href)
 		const eslint_module = module_schema.parse(loaded)
 
-		return new eslint_module.ESLint({ cwd: project_root })
+		return new eslint_module.ESLint({
+			cwd: project_root,
+			...(config_file !== undefined && { [CONFIG_FILE_OPTION]: config_file }),
+		})
 	} catch {
 		return undefined
 	}
@@ -128,12 +135,18 @@ async function entry_for(
 // One resolver for the whole call: the configuration is loaded and cached once, and every path after
 // the first is a lookup rather than a load. That is what makes a per-file limit affordable at all.
 // Keyed by the absolute path, so the caller's spelling of a path does not have to match.
+//
+// `config_file` names the configuration to ask instead of the one `project_root` holds, with
+// `project_root` still the directory its `files` patterns are matched from — what `josh metrics` needs
+// to hold another commit's tree to this checkout's limits (`metrics-code-lines.ts`).
 async function options_for(
 	file_paths: ReadonlyArray<string>,
 	project_root: string,
+	config_file?: string,
 ): Promise<ReadonlyMap<string, LineRuleOptions>> {
 	const found = new Map<string, LineRuleOptions>()
-	const resolver = file_paths.length === 0 ? undefined : await resolver_for(project_root)
+	const resolver =
+		file_paths.length === 0 ? undefined : await resolver_for(project_root, config_file)
 
 	if (resolver === undefined) return found
 

package/scripts/lines/line-budget.ts

@@ -3,17 +3,14 @@ import { statSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { LINT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { z } from 'zod'
 import { effective_limit, type LineRuleOptions } from './effective-limit'
 
-// joshuafolkken/kit#1425: the file line limit was only ever reported *after* the writing was done.
-// Measured by hand from run #1406's transcript (PR #1422, 45.8 minutes), 19.8% of the whole run —
-// 543 seconds — went on reacting to `max-lines` once the implementation was already finished:
-// `pnpm josh gate` five times and `pnpm josh lint` four, of which 115 seconds was tool execution and
-// the remaining 353 was model time in between. The splitting itself was correct work; what was wrong
-// is that it was decided after the fact rather than at design time.
+// Reports each file's line headroom before the writing starts, so a split is decided at design time
+// rather than after the gate reports `max-lines`.
 //
 // **The limit is not changed here, and nothing in this file counts lines its own way.** That is the
 // trap a headroom report walks into: a second counting method becomes a way to satisfy the limit by
@@ -22,21 +19,16 @@ import { effective_limit, type LineRuleOptions } from './effective-limit'
 // invocation `pnpm josh lint` reaches, with `max-lines` lowered to 0 so the rule reports
 // unconditionally and its message carries the count it would have compared against the real limit.
 //
-// **Running ESLint in process instead was tried first and is wrong.** `new Linter().verify(...)` and
-// `new ESLint().lintFiles(...)` both answer **one line lower than the `eslint` CLI on any file that
-// starts with `#!`** — measured on eslint 10.10.0 with this repository's own config, `301` from the
-// CLI against `300` from either API for the same file. Every `scripts/*.ts` entry point has a
-// hashbang, so an in-process count would have been quietly wrong for most of this package while the
-// gate went on failing at a number the report never showed. Spawning costs a process; agreeing with
+// **The count comes from the `eslint` CLI, not the in-process API.** `new Linter().verify(...)` and
+// `new ESLint().lintFiles(...)` both answer **one line lower than the CLI on any file that starts with
+// `#!`**, and every `scripts/*.ts` entry point has a hashbang. Spawning costs a process; agreeing with
 // the gate is the whole point of the report.
 //
-// **joshuafolkken/kit#1454: the limit and the counting options come from the same place the count
-// does.** They used to be read from kit's own `eslint/rules/code-quality.js` while the count was asked
-// of the project's eslint — identical in kit, and two different rules in a consumer that overrides
-// `max-lines` after `create_base_config`. `effective-limit.ts` resolves the entry the project's own
-// eslint applies **to each file**, and nothing in this file reads kit's copy any more. Where no entry
-// can be resolved there is no budget, and the count is reported without one: falling back to kit's
-// number would restore the defect and do it silently.
+// **The limit and the counting options come from the same place the count does.**
+// `effective-limit.ts` resolves the `max-lines` entry the project's own eslint applies **to each
+// file**, so a consumer that overrides `max-lines` after `create_base_config` is held to its own rule.
+// Where no entry can be resolved there is no budget, and the count is reported without one: falling
+// back to kit's number would report a limit the project does not enforce.
 
 const MAX_LINES_RULE = 'max-lines'
 // The rule reports when the count is **greater than** `max`, and 0 is the lowest value its own schema
@@ -60,13 +52,9 @@ const NO_CODE_LINES = 0
 const COUNT_PATTERN = /\((\d+)\)/u
 const COUNT_GROUP = 1
 
-// **Why 85%, and how it lines up with joshuafolkken/kit#1249.** That issue asks for the same shape
-// for a distributed document's resident budget and is still open with nothing settled, so there is no
-// number there to copy; what it and joshuafolkken/kit#951 settle is the *form* — a margin that turns
-// "at the limit" into a warning while there is still room to write the fix. Matching the resident
-// reserve's fraction instead (2,000 of 60,000 bytes, 3.3%) would leave 10 lines of margin, less than
-// one function is allowed to be, which is a warning arriving with nowhere left to go. 45 lines is a
-// little under two functions at the 25-line function limit — enough to write the split into.
+// **Why 85%.** The margin turns "at the limit" into a warning while there is still room to write the
+// fix: 45 lines of a 300-line limit is a little under two functions at the 25-line function limit —
+// enough to write the split into.
 const NEAR_LIMIT_FRACTION = 0.85
 const PERCENT = 100
 
@@ -81,15 +69,14 @@ const PNPM_EXEC = 'exec'
 const FORMAT_FLAGS: ReadonlyArray<string> = ['--format', 'json', '--no-inline-config']
 const RULE_FLAG = '--rule'
 // **No `--cache`, and a `--cache-location` all the same.** An eslint run started *without* `--cache`
-// deletes whatever `--cache-location` names, which is how the edit hook once wiped the gate's cache
-// (joshuafolkken/kit#1332) — so the flag has to be here, pointed somewhere harmless, even though this
+// deletes whatever `--cache-location` names, which would wipe the gate's cache — so the flag has to be here, pointed somewhere harmless, even though this
 // probe keeps no cache. It keeps none because the only key available is the checkout, and two
 // `josh lines` calls at once in one repository — routine with parallel agents here — would then be two
-// unsynchronized writers of one file. A cold run is a couple of seconds against the 543 this report
-// exists to save, so the cache is not worth a shared-state hazard.
+// unsynchronized writers of one file. A cold run is a couple of seconds, so the cache is not worth a
+// shared-state hazard.
 //
-// **The path is per probe, not per call** (joshuafolkken/kit#1454). Since the counting method decides
-// how many probes one call starts, two of them can now run concurrently — and each deletes whatever
+// **The path is per probe, not per call.** Since the counting method decides how many probes one call
+// starts, two of them can run concurrently — and each deletes whatever
 // `--cache-location` names as it starts, so one shared path would have them racing to unlink the file
 // the other just made. The option set's own key is folded into the name, which makes the paths
 // distinct exactly when the probes are.
@@ -100,9 +87,14 @@ const CACHE_KEY_LENGTH = 8
 // Only the two fields this reads. `ruleId` is nullable on a parse error or an ignore warning, and
 // both of those are answers — "no count for this path" — rather than failures.
 const message_schema = z.object({ ruleId: z.string().nullish(), message: z.string() })
-const results_schema = z.array(
-	z.object({ filePath: z.string(), messages: z.array(message_schema) }),
-)
+const result_schema = z.object({ filePath: z.string(), messages: z.array(message_schema) })
+const results_schema = z.array(result_schema)
+
+type LintResult = z.infer<typeof result_schema>
+
+// The rule entry the probe hands eslint — as `--rule` JSON to the CLI, as `overrideConfig` rules to
+// the Node API.
+type ProbeRules = Record<string, [typeof PROBE_SEVERITY, LineRuleOptions & { max: number }]>
 
 interface LineBudget {
 	code_lines: number
@@ -113,7 +105,7 @@ interface LineBudget {
 
 // `limit` is carried beside the budget, and it is not the same thing as `budget.limit`: a path this
 // project enforces no `max-lines` on has no limit at all, and the caller has to be able to say that
-// rather than say the count failed (joshuafolkken/kit#1454).
+// rather than say the count failed.
 interface FileBudget {
 	file_path: string
 	limit: number | undefined
@@ -150,10 +142,12 @@ function budget_of(code_lines: number, limit: number): LineBudget {
 
 // The counting options are the project's own, so a consumer that turns `skipComments` off is counted
 // its way. Lowering `max` is the only change the probe makes.
+function probe_rules(options: LineRuleOptions): ProbeRules {
+	return { [MAX_LINES_RULE]: [PROBE_SEVERITY, { ...options, max: PROBE_MAX }] }
+}
+
 function probe_rule(options: LineRuleOptions): string {
-	return JSON.stringify({
-		[MAX_LINES_RULE]: [PROBE_SEVERITY, { ...options, max: PROBE_MAX }],
-	})
+	return JSON.stringify(probe_rules(options))
 }
 
 function cache_prefix(key: string): string {
@@ -176,8 +170,7 @@ function probe_arguments(group: ProbeGroup, project_root: string): Array<string>
 // The project's own eslint, through its own shim when there is one and `pnpm exec` when there is not
 // — the same two routes every other command in this package reaches a local binary by. The lookup
 // **walks up** from the given directory, because pnpm does: resolving only the directory the command
-// was invoked in would disagree with the very binary it spawns, which is joshuafolkken/kit#934 and the
-// reason `local-bin.ts` ships this variant.
+// was invoked in would disagree with the very binary it spawns.
 function probe_command(project_root: string, probe_args: ReadonlyArray<string>): Array<string> {
 	const shim = find_local_bin_upwards(project_root, ESLINT_BIN)
 
@@ -237,13 +230,12 @@ function count_or_zero(
 
 // Keyed by the absolute path eslint reports, so the caller's spelling of a path does not have to
 // match it. A path eslint refused is simply absent, and the caller reports that rather than a number.
-function counts_in(raw_output: string | undefined = 'null'): ReadonlyMap<string, number> {
+// The results are eslint's own objects whether they arrived as the CLI's JSON or from the Node API,
+// so `josh metrics` reads its in-process run through this same reading.
+function counts_from(results: ReadonlyArray<LintResult>): ReadonlyMap<string, number> {
 	const counts = new Map<string, number>()
-	const parsed = results_schema.safeParse(JSON.parse(raw_output))
 
-	if (!parsed.success) return counts
-
-	for (const result of parsed.data) {
+	for (const result of results) {
 		const code_lines = count_or_zero(result.messages)
 
 		if (code_lines !== undefined) counts.set(path.resolve(result.filePath), code_lines)
@@ -252,14 +244,11 @@ function counts_in(raw_output: string | undefined = 'null'): ReadonlyMap<string,
 	return counts
 }
 
-// The safe entry point, and the only one exported: eslint's output can be empty or truncated, and
-// `JSON.parse` throws on both.
-function parse_counts(raw_output: string | undefined): ReadonlyMap<string, number> {
-	try {
-		return counts_in(raw_output)
-	} catch {
-		return new Map<string, number>()
-	}
+// eslint's output can be empty or truncated, and neither is JSON — both read as no counts at all.
+function parse_counts(raw_output: string | undefined = 'null'): ReadonlyMap<string, number> {
+	const results = json_value.parse_with(raw_output, results_schema)
+
+	return results === undefined ? new Map<string, number>() : counts_from(results)
 }
 
 // **Only regular files are passed to eslint, and this is not tidiness.** One argument eslint cannot
@@ -284,7 +273,7 @@ function lintable_paths(file_paths: ReadonlyArray<string>): ReadonlyArray<string
 // One eslint run per *distinct counting method*, rather than one per path. The cost of this report is
 // a process start, so the number of paths is the one thing that must not multiply it — and the number
 // of distinct `max-lines` option sets in one project is one, in every configuration that does not
-// deliberately count two groups of files differently (joshuafolkken/kit#1454).
+// deliberately count two groups of files differently.
 // The keys are sorted before they are written out, so two config blocks that state the same options in
 // a different order are one group rather than two. Unsorted, a purely cosmetic difference would split
 // the probe in two and cost a second eslint process for nothing.
@@ -387,7 +376,9 @@ const line_budget = {
 	advice,
 	budget_of,
 	budgets_for,
+	counts_from,
 	describe,
+	grouped,
 	is_lintable_path,
 	near_limit_percent,
 	near_limit_threshold,
@@ -395,6 +386,7 @@ const line_budget = {
 	probe_arguments,
 	probe_command,
 	probe_rule,
+	probe_rules,
 	NEAR_LIMIT_FRACTION,
 }
 

package/scripts/lines/line-targets.ts

@@ -1,7 +1,8 @@
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn } from '#scripts/git/git-spawn'
 
-// The no-argument half of joshuafolkken/kit#1809. `josh lines <path>` answers for a file someone
+// The no-argument half of `josh lines`. `josh lines <path>` answers for a file someone
 // already named; a file near the limit that nobody has named yet is invisible until the gate reports
 // it. This enumerates the repository's own lint-target files so the no-argument scan can report every
 // one of them near the limit at once, before the first edit rather than after it.
@@ -51,13 +52,16 @@ function split_names(output: string): ReadonlyArray<string> {
 
 // The names resolve against the repository `root`, never the process cwd: `--full-name` prints them
 // relative to the root wherever the command runs, so resolving against cwd would double the prefix
-// and drop every file when the command is invoked from a subdirectory.
+// and drop every file when the command is invoked from a subdirectory. `--cached` still lists a file
+// deleted from the working tree but not yet staged, so a path no longer on disk is dropped — every
+// consumer reads or lints the file, and a deletion in flight would otherwise fail them.
 async function lint_target_files(root: string): Promise<ReadonlyArray<string>> {
 	const output = await git_spawn.read([...LS_FILES_FLAGS, WHOLE_TREE_PATHSPEC])
 
 	return split_names(output)
 		.filter((name) => is_lint_target(name))
 		.map((name) => path.resolve(root, name))
+		.filter((file_path) => existsSync(file_path))
 }
 
 const line_targets = {

package/scripts/lines/lines-command.ts

@@ -5,7 +5,7 @@ import { git_command } from '#scripts/git/git-command'
 import { line_budget, type FileBudget, type LineBudget } from './line-budget'
 import { line_targets } from './line-targets'
 
-// `josh lines` — the ask-before-writing half of joshuafolkken/kit#1425. `pnpm josh lint` reports the
+// `josh lines` — ask before writing. `pnpm josh lint` reports the
 // file line limit only once it has been broken, and by then the writing is finished and the splitting
 // that follows is rework. This answers the same question before the first edit: how many code lines
 // each target file already has, and how many are left.
@@ -33,7 +33,7 @@ const NONE_NEAR = 'no files near the limit'
 // at all. It deliberately does not name eslint, because the last of those is not eslint's doing.
 const NOT_A_FILE = 'not counted: not a regular file'
 const NOT_COUNTED = 'not counted: no line count for this path'
-// The third reason, and the one that replaced a wrong number (joshuafolkken/kit#1454). This project's
+// The third reason, and the one that replaced a wrong number. This project's
 // eslint enforces no `max-lines` here, so there is nothing to report a budget against — and the
 // alternative to saying so is quoting kit's limit for someone else's project, which is the defect. It
 // names no cause because there are several: the rule is turned off for this path, no configuration
@@ -63,7 +63,7 @@ function row(relative_path: string, entry: FileBudget): string {
 // The threshold is printed with the rows rather than left implicit: a reader who sees "near the limit"
 // on one file and nothing on the next needs the boundary to know which side a third one is on.
 //
-// **It is read off the budgets rather than from a limit of this command's own** (joshuafolkken/kit#1454).
+// **It is read off the budgets rather than from a limit of this command's own**.
 // Each file's limit is whatever that project's eslint enforces for it, so there is a line count to
 // print here only where every counted file agrees on one; where they do not — or where none was
 // resolved — the boundary is stated as the share it has always been, and each row carries its own

package/scripts/lint/cspell-cached.ts

@@ -6,7 +6,7 @@ import { lane_cache_run } from '#scripts/lane/lane-cache-run'
 import { buffered_process, FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 
 const ARGV_START = 2
-// `--no-progress` turns off cspell's per-file `N/1607 <path> cached` line (joshuafolkken/kit#2296).
+// `--no-progress` turns off cspell's per-file `N/1607 <path> cached` line.
 // Those lines ran to 1,607 of them — the whole output past the 8,000-character tool cap — so a gate
 // that failed on one unknown word buried the failure under progress and a run could read only the
 // first of several failures. The summary and the issue lines it prints are untouched; only the

package/scripts/lint/cycle-recheck.ts

@@ -0,0 +1,122 @@
+import { FAIL_EXIT_CODE, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+import type { ESLint } from 'eslint'
+
+// `import/no-cycle` reads other files, and the lint cache keys a verdict on the linted file's own
+// content. So once a cycle is closed by editing one side of it, the untouched side keeps its cached
+// `Dependency cycle detected` until its own content changes (joshuafolkken/kit#3641). The opposite
+// error cannot happen: a new cycle always contains the file that gained the import, and that file is
+// re-linted.
+//
+// A lint run therefore re-reads a cached red that names the rule: the files reported for it are
+// linted once more without the cache, and their fresh results replace the cached ones. A run that
+// reports no cycle never reaches this, so the green path costs what it did.
+//
+// That holds for a run narrowed to one change's files as much as for the whole tree: the change can
+// hold both sides of a cycle, and the side a later edit leaves alone keeps its cached report.
+//
+// The cached run is asked again through the Node API rather than read off the first run's report:
+// that report is the stylish text, and taking a file out of it means re-deriving its problem
+// counts. The second asking is answered from the cache the first one just wrote.
+const NO_CYCLE_RULE = 'import/no-cycle'
+const FORMATTER = 'stylish'
+const UNCACHED_SUFFIX = '.uncached'
+
+interface Linters {
+	cached: ESLint
+	fresh: ESLint
+}
+
+interface CycleRecheckOptions {
+	cache_file: string
+	// What the run linted — the whole tree, or one change's files — so the cached run is asked the
+	// question it was asked the first time.
+	patterns: ReadonlyArray<string>
+	// What the fixture test varies: the directory linted and the configuration it is linted with.
+	eslint_options?: ESLint.Options
+}
+
+// The exit code is eslint's "finished and reported problems", not any failure: a run that could not
+// finish — a configuration that does not load, a rule that threw — exits 2 and may name the rule
+// too, and asking it again throws the same error here, ahead of both buffered reports.
+function is_cycle_reported(result: BufferedProcessResult): boolean {
+	return result.exit_code === FAIL_EXIT_CODE && result.output.includes(NO_CYCLE_RULE)
+}
+
+function has_cycle_message(result: ESLint.LintResult): boolean {
+	return result.messages.some((message) => message.ruleId === NO_CYCLE_RULE)
+}
+
+function cached_options(options: CycleRecheckOptions): ESLint.Options {
+	return {
+		...options.eslint_options,
+		cache: true,
+		cacheStrategy: 'content',
+		cacheLocation: options.cache_file,
+	}
+}
+
+// A linter that runs without a cache deletes the cache file it would have used, and that defaults to
+// the very file the lint run keeps. So the uncached linter is pointed at a sibling path nothing
+// ever writes: the re-reading must not cost the next run its whole cache.
+function fresh_options(options: CycleRecheckOptions): ESLint.Options {
+	return {
+		...options.eslint_options,
+		cache: false,
+		cacheLocation: `${options.cache_file}${UNCACHED_SUFFIX}`,
+	}
+}
+
+// `eslint` is loaded here, only past the cycle report: it is an optional peer a basic-profile
+// consumer may not have, and this module is imported by the entry of every `josh lint`, which has to
+// reach its skip notice there.
+async function create_linters(options: CycleRecheckOptions): Promise<Linters> {
+	const eslint = await import('eslint')
+
+	return {
+		cached: new eslint.ESLint(cached_options(options)),
+		fresh: new eslint.ESLint(fresh_options(options)),
+	}
+}
+
+async function lint_fresh(
+	linter: ESLint,
+	cached: ReadonlyArray<ESLint.LintResult>,
+): Promise<Map<string, ESLint.LintResult>> {
+	const suspects = cached.filter((result) => has_cycle_message(result))
+	if (suspects.length === 0) return new Map()
+	const fresh = await linter.lintFiles(suspects.map((result) => result.filePath))
+
+	return new Map(fresh.map((result) => [result.filePath, result]))
+}
+
+async function report(
+	linter: ESLint,
+	results: Array<ESLint.LintResult>,
+): Promise<Pick<BufferedProcessResult, 'output' | 'exit_code'>> {
+	const formatter = await linter.loadFormatter(FORMATTER)
+	const is_failed = results.some((result) => result.errorCount > 0)
+
+	return { output: await formatter.format(results), exit_code: is_failed ? FAIL_EXIT_CODE : 0 }
+}
+
+async function verify(
+	result: BufferedProcessResult,
+	options: CycleRecheckOptions,
+): Promise<BufferedProcessResult> {
+	if (!is_cycle_reported(result)) return result
+	const started_at = performance.now()
+	const linters = await create_linters(options)
+	const cached = await linters.cached.lintFiles([...options.patterns])
+	const fresh = await lint_fresh(linters.fresh, cached)
+	const verified = await report(
+		linters.fresh,
+		cached.map((entry) => fresh.get(entry.filePath) ?? entry),
+	)
+
+	return { ...verified, elapsed_ms: result.elapsed_ms + performance.now() - started_at }
+}
+
+const cycle_recheck = { verify }
+
+export type { CycleRecheckOptions }
+export { cycle_recheck, NO_CYCLE_RULE }

package/scripts/lint/format.ts

@@ -19,8 +19,7 @@ async function run_step(args: ReadonlyArray<string>, directory: string): Promise
 
 // prettier first, deliberately: `eslint --fix` exits 1 whenever a non-autofixable error remains, so
 // putting it first would mean one unused variable anywhere in the tree stops prettier from running.
-// A basic project without Prettier or ESLint is skipped with the same reason `josh lint` prints
-// (joshuafolkken/kit#2693, joshuafolkken/kit#2606).
+// A basic project without Prettier or ESLint is skipped with the same reason `josh lint` prints.
 async function run_unless_skipped(
 	check: string,
 	reason: string | undefined,