@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/lane/openai-lane-supervisor-owner.ts

@@ -3,11 +3,12 @@ import { linkSync, statSync, unlinkSync } from 'node:fs'
 import { process_identity } from '#scripts/josh/process-identity'
 import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
 
 // The supervisor's owner and state stamps — who holds a lane, and which child it last launched —
-// split out of `openai-lane-supervisor.ts` when it reached its line limit (joshuafolkken/kit#3264).
+// split out of `openai-lane-supervisor.ts` when it reached its line limit.
 // `openai_lane_supervisor` re-exports each public one under the name it always had, so the move
 // changed no call site and no suite that spies on `openai_lane_supervisor`.
 
@@ -41,14 +42,7 @@ function state_path(lane_directory: string): string {
 }
 
 function parsed_stamp<T>(target: string, schema: z.ZodType<T>): T | undefined {
-	try {
-		const value: unknown = JSON.parse(stamp_file.read_stamp_text(target) ?? '')
-		const parsed = schema.safeParse(value)
-
-		return parsed.success ? parsed.data : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(stamp_file.read_stamp_text(target) ?? '', schema)
 }
 
 function read(lane_directory: string): SupervisorOwner | undefined {

package/scripts/lane/openai-review-broker.ts

@@ -7,6 +7,7 @@ import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
+import { json_value } from '#scripts/lib/json-value'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review } from '#scripts/run/ship/run-ship-review'
 import { z } from 'zod'
@@ -60,10 +61,7 @@ function response_path(directory: string, issue: string): string | undefined {
 
 function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
 	try {
-		const content: unknown = JSON.parse(readFileSync(target, 'utf8'))
-		const parsed = schema.safeParse(content)
-
-		return parsed.success ? parsed.data : undefined
+		return json_value.parse_with(readFileSync(target, 'utf8'), schema)
 	} catch {
 		return undefined
 	}

package/scripts/lib/ancestor-directories.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 
-// One parent-directory walk, in one place (joshuafolkken/kit#3260). Five modules had each written
+// One parent-directory walk, in one place. Five modules had each written
 // their own — the josh package-root lookup, the gate's project root, the effective-upstream version
 // read, the local-bin shim search and the progress-interval read — and they had drifted to three
 // different stop conditions. The walk stops at the filesystem root (where `dirname` answers itself)

package/scripts/lib/bounded-pool.ts

@@ -5,7 +5,7 @@
 // and `epic-bundle-referenced.ts` each read one issue per reference and must not turn a rate limit
 // into a wrong answer. The reads were written as waves — slice, `Promise.all`, next slice — which
 // idles the whole batch behind its slowest member, so the three were neither the same code nor the
-// same behavior (joshuafolkken/kit#1144).
+// same behavior.
 //
 // A worker pool instead: `limit` consumers pull from one queue, so a slot is refilled the moment its
 // task ends rather than when its neighbors do.
@@ -32,7 +32,7 @@ interface Pool<Item, Result> {
 // so the clamp passes it straight through and `Array.from({ length: NaN })` builds no consumer at all
 // — an empty result for a non-empty input, which is precisely what the paragraph above promises
 // cannot happen. A caller reading that promise is entitled not to validate first, so it is closed
-// here (joshuafolkken/kit#1144). A fractional limit is floored for the same reason: `Array.from`
+// here. A fractional limit is floored for the same reason: `Array.from`
 // truncates it silently, and a width that is not the number asked for should be a decision rather
 // than a side effect.
 function pool_width(limit: number, total: number): number {

package/scripts/lib/buffered-process.ts

@@ -7,8 +7,7 @@ import { SUITE_TIMEOUT_MS } from './timeouts'
 // need the same three things: the output buffered until the child finishes (concurrent writers
 // otherwise interleave into an unreadable transcript), a non-zero exit reported rather than thrown
 // (so one failing check does not abort its siblings), and a bound on how long a child may hang.
-// They had the same code twice, which is how a fix to one of them missed the other
-// (joshuafolkken/kit#914).
+// They had the same code twice, which is how a fix to one of them missed the other.
 
 const PNPM = 'pnpm'
 const FORCE_COLOR = '1'
@@ -21,13 +20,12 @@ interface BufferedProcessResult {
 	exit_code: number | undefined
 	// How long the child ran, in milliseconds. Measured here rather than at each call site because
 	// this function owns the child's lifetime — a caller timing it from outside would have to repeat
-	// the same two readings, and every fan-out caller would repeat them once per branch
-	// (joshuafolkken/kit#1248).
+	// the same two readings, and every fan-out caller would repeat them once per branch.
 	elapsed_ms: number
 }
 
-// The two things a caller outside the fan-out needs to vary, and the only two
-// (joshuafolkken/kit#1554). `lane:open` runs its install in the work tree it just created rather
+// The two things a caller outside the fan-out needs to vary, and the only two.
+// `lane:open` runs its install in the work tree it just created rather
 // than in the directory `josh` was typed in, and bounds it well under the fan-out's half hour
 // because an install that never answers has to end the command rather than hold a parallel run
 // open. Everything else — the buffering, the non-throwing exit, and the color policy that respects

package/scripts/lib/cli-flags.ts

@@ -1,9 +1,19 @@
 import { parseArgs, type ParseArgsConfig, type ParseArgsOptionsConfig } from 'node:util'
 
 // Argument reading for the commands under `scripts/`.
-//
+
+const HELP_FLAGS: ReadonlySet<string> = new Set(['--help', '-h'])
+
+// The usage line `refuse_unknown_flags` ends with, for a command that prints it on its own help
+// request (`josh release --help`).
+function usage_line(known_flags: ReadonlyArray<string>, command: string): string {
+	if (known_flags.length === 0) return `Usage: josh ${command}`
+
+	return `Usage: josh ${command} [${known_flags.join('] [')}]`
+}
+
 // Reject anything not on the list rather than ignoring it: a misspelled `--dryrun` that fell through
-// would run the real write path. `josh propagate` and `josh adopt` both write into working trees, so
+// would run the real write path. `josh propagate`, `josh adopt` and `josh release` all write, so
 // the refusal is single-sourced here rather than described once per command (`CLAUDE.md` → "No
 // clones").
 function refuse_unknown_flags(
@@ -13,15 +23,36 @@ function refuse_unknown_flags(
 ): string | undefined {
 	const unknown = argv.filter((argument) => !known_flags.includes(argument))
 	if (unknown.length === 0) return undefined
-	const usage = `Usage: josh ${command} [${known_flags.join('] [')}]`
 
-	return `Unknown argument(s): ${unknown.join(' ')}\n${usage}`
+	return `Unknown argument(s): ${unknown.join(' ')}\n${usage_line(known_flags, command)}`
+}
+
+// The argument gate of a command that publishes (`josh release`, `josh release:github`): a help
+// request prints the usage and exits 0, an unknown argument is refused with exit 1, both before any side effect. `undefined` means the
+// arguments are all known and the command may run.
+function answer_help_or_unknown(
+	argv: ReadonlyArray<string>,
+	known_flags: ReadonlyArray<string>,
+	command: string,
+): number | undefined {
+	if (argv.some((argument) => HELP_FLAGS.has(argument))) {
+		console.info(usage_line(known_flags, command))
+
+		return 0
+	}
+
+	const refusal = refuse_unknown_flags(argv, known_flags, command)
+	if (refusal === undefined) return undefined
+
+	console.error(refusal)
+
+	return 1
 }
 
 // `parseArgs`, answering `undefined` where it would throw — an unknown flag, a missing option value,
 // or a positional the config does not allow. Each caller turns that into its usage line and a failure
 // exit rather than a stack trace, on commands whose output a workflow reads; eleven of them had begun
-// to carry a copy of the same try/catch each (joshuafolkken/kit#2902), and this is the one copy.
+// to carry a copy of the same try/catch each, and this is the one copy.
 function parse_or_undefined<T extends ParseArgsConfig>(
 	config: T,
 ): ReturnType<typeof parseArgs<T>> | undefined {
@@ -34,7 +65,7 @@ function parse_or_undefined<T extends ParseArgsConfig>(
 
 // The two shapes every command reads `argv` in: flags alone, or flags beside positionals. Both are
 // strict, so an unknown flag is `undefined` rather than a silently ignored typo; the commands had each
-// carried a one-line wrapper spelling these out (joshuafolkken/kit#3072).
+// carried a one-line wrapper spelling these out.
 type FlagsOnly<T extends ParseArgsOptionsConfig> = ReturnType<
 	typeof parseArgs<{ args: Array<string>; options: T }>
 >
@@ -123,7 +154,9 @@ function attach_values(
 
 const cli_flags = {
 	attach_values,
+	usage_line,
 	refuse_unknown_flags,
+	answer_help_or_unknown,
 	parse_or_undefined,
 	values_of,
 	arguments_of,

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,
 }