@joshuafolkken/kit 1.1370.0 → 1.1373.0

package/scripts/document/document-scan.ts

@@ -36,9 +36,10 @@ const BARE_ARROW_PATTERN = /→\s*(?:§\w+,\s*)?["「](?<heading>[^"「」]+)["
 // arrow — the link text already carries the file the reference names.
 const LINK_TARGET_PATTERN = /\]\([^)\s]*\)/gu
 
-// A relative markdown link target, with an optional `#anchor`. External `https://…` links carry no
-// `.md`, so the pattern never matches them.
-const LINK_PATTERN = /\]\(([\w./-]+\.md)(?:#[\w-]+)?\)/gu
+// A relative markdown link target, with an optional `#anchor` — a page, or the image a page shows
+// (`![alt](./docs/images/board.png)`). An external `https://…` link carries a colon the target class
+// leaves out, so the pattern never matches one.
+const LINK_PATTERN = /\]\(([\w./-]+\.(?:md|png|jpe?g|gif|svg|webp))(?:#[\w-]+)?\)/gu
 
 // Filenames that appear in the documents as illustrations of the reference form itself, never as real
 // targets — the doc-section explanation cites `` `path.md` → "Heading" `` and `` `X.md` → "Heading" ``.

package/scripts/josh/josh-commands-run.ts

@@ -125,7 +125,7 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Print the run’s next single action, computed from the event stream, carry record and issue state',
 		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network', 'files']],
+		reference: ['[<issue>]', 'automation', ['network', 'files']],
 	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */

package/scripts/lint/cross-file-recheck.ts

@@ -0,0 +1,155 @@
+import { FAIL_EXIT_CODE, type BufferedProcessResult } from '#scripts/lib/buffered-process'
+import type { ESLint } from 'eslint'
+
+// Some rules read other files, and the lint cache keys a verdict on the linted file's own content.
+// So once the other file is fixed, the untouched one keeps its cached error until its own content
+// changes. `import/no-cycle` did it first (joshuafolkken/kit#3641): a cycle closed by editing one
+// side stayed reported on the other. The type-aware rules do it too (joshuafolkken/kit#3667): a call
+// to a function its module did not export yet stays `no-unsafe-call` after the export is added.
+//
+// A red lint run therefore re-reads its cached report: the files reported for a rule that reads
+// other files are linted once more without the cache, and their fresh results replace the cached
+// ones. A green run never reaches this, so the green path costs what it did.
+//
+// Which rules those are is the rule's own statement, never a list kept here: a type-aware rule
+// declares `requiresTypeChecking`, and the `import` plugin's rules resolve the modules they name.
+// That plugin answers to two names: the base config registers it as `import`, and its own preset —
+// whose rules a hand-authored `.js` file keeps — as `import-x`.
+//
+// Only a stale red is re-read. A stale green — the other file broke, the untouched one still
+// answers clean — is not something a report can point at; the type check is what catches it.
+//
+// That holds for a run narrowed to one change's files as much as for the whole tree: the change can
+// hold both files, and the one 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 IMPORT_RULE_PATTERN = /^import(?:-x)?\//u
+const FORMATTER = 'stylish'
+const UNCACHED_SUFFIX = '.uncached'
+
+type RulesMeta = ESLint.LintResultData['rulesMeta']
+
+interface Linters {
+	cached: ESLint
+	fresh: ESLint
+}
+
+interface CrossFileRecheckOptions {
+	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 asking it again
+// throws the same error here, ahead of both buffered reports.
+function is_red(result: BufferedProcessResult): boolean {
+	return result.exit_code === FAIL_EXIT_CODE
+}
+
+// `requiresTypeChecking` is typescript-eslint's convention, which other type-aware plugins follow;
+// eslint's own type for a rule's docs does not name it.
+function is_type_aware(documentation: object | undefined): boolean {
+	if (documentation === undefined) return false
+
+	return 'requiresTypeChecking' in documentation && documentation.requiresTypeChecking === true
+}
+
+// A problem with no rule is the parser's, about the file itself.
+function reads_other_files(rule_id: string | null, rules_meta: RulesMeta): boolean {
+	if (rule_id === null) return false
+
+	return IMPORT_RULE_PATTERN.test(rule_id) || is_type_aware(rules_meta[rule_id]?.docs)
+}
+
+function suspects_of(linter: ESLint, cached: Array<ESLint.LintResult>): Array<string> {
+	const rules_meta = linter.getRulesMetaForResults(cached)
+
+	return cached
+		.filter((result) =>
+			result.messages.some((message) => reads_other_files(message.ruleId, rules_meta)),
+		)
+		.map((result) => result.filePath)
+}
+
+function cached_options(options: CrossFileRecheckOptions): 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: CrossFileRecheckOptions): ESLint.Options {
+	return {
+		...options.eslint_options,
+		cache: false,
+		cacheLocation: `${options.cache_file}${UNCACHED_SUFFIX}`,
+	}
+}
+
+// `eslint` is loaded here, only past a red 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: CrossFileRecheckOptions): 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,
+	suspects: Array<string>,
+): Promise<Map<string, ESLint.LintResult>> {
+	const fresh = await linter.lintFiles(suspects)
+
+	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 }
+}
+
+// A red about rules that read nothing else is handed back as the run reported it: its cached
+// verdicts are about the files they are keyed on.
+async function verify(
+	result: BufferedProcessResult,
+	options: CrossFileRecheckOptions,
+): Promise<BufferedProcessResult> {
+	if (!is_red(result)) return result
+	const started_at = performance.now()
+	const linters = await create_linters(options)
+	const cached = await linters.cached.lintFiles([...options.patterns])
+	const suspects = suspects_of(linters.cached, cached)
+	if (suspects.length === 0) return result
+	const fresh = await lint_fresh(linters.fresh, suspects)
+	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 cross_file_recheck = { verify }
+
+export type { CrossFileRecheckOptions }
+export { cross_file_recheck }

package/scripts/lint/lint-parallel.ts

@@ -8,7 +8,7 @@ import {
 	FAIL_EXIT_CODE,
 	type BufferedProcessResult,
 } from '#scripts/lib/buffered-process'
-import { cycle_recheck, type CycleRecheckOptions } from './cycle-recheck'
+import { cross_file_recheck, type CrossFileRecheckOptions } from './cross-file-recheck'
 
 const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
 // This — not the `lint:eslint` map entry — is the eslint invocation `josh gate` reaches, so the
@@ -17,16 +17,16 @@ const PRETTIER_ARGS = ['exec', 'prettier', '--check', '.'] as const
 // moves, with every test still green.
 const WHOLE_TREE = '.'
 const ESLINT_ARGS = ['exec', 'eslint', WHOLE_TREE, ...ESLINT_CACHE_FLAGS] as const
-const WHOLE_TREE_RECHECK: CycleRecheckOptions = {
+const WHOLE_TREE_RECHECK: CrossFileRecheckOptions = {
 	cache_file: ESLINT_CACHE_FILE,
 	patterns: [WHOLE_TREE],
 }
 
-// What one eslint run is made of: the child's arguments, and what re-reading a cached cycle report
-// (joshuafolkken/kit#3641) needs to ask the same question again — the cache file and the targets.
+// What one eslint run is made of: the child's arguments, and what re-reading a cached cross-file report
+// (`cross-file-recheck.ts`) needs to ask the same question again — the cache file and the targets.
 interface EslintRun {
 	args: ReadonlyArray<string>
-	recheck: CycleRecheckOptions
+	recheck: CrossFileRecheckOptions
 }
 
 // The finished report is re-read before it is returned, inside the lane's cache sharing, because
@@ -35,7 +35,7 @@ async function run_eslint(eslint: EslintRun): Promise<BufferedProcessResult> {
 	return await lane_cache_run.run(eslint.recheck.cache_file, async () => {
 		const result = await buffered_process.run_buffered_process(eslint.args)
 
-		return await cycle_recheck.verify(result, eslint.recheck)
+		return await cross_file_recheck.verify(result, eslint.recheck)
 	})
 }
 
@@ -80,12 +80,13 @@ function lint_exit_code(prettier: BufferedProcessResult, eslint: BufferedProcess
 // run would have skipped. The skip reasons answer nothing for a full
 // project, so the one path serves both profiles.
 //
-// A narrowed run re-reads a cached cycle report too (joshuafolkken/kit#3641): one change's files can
-// hold both sides of a cycle, and closing it by editing one leaves the other's cached report standing.
+// A narrowed run re-reads a cached cross-file report too (`cross-file-recheck.ts`): one change's
+// files can hold both the reported file and the one it reads, and fixing the second leaves the
+// first's cached report standing.
 async function run_lint_checks(
 	prettier_args: ReadonlyArray<string>,
 	eslint_args: ReadonlyArray<string>,
-	recheck: CycleRecheckOptions,
+	recheck: CrossFileRecheckOptions,
 ): Promise<number> {
 	const directory = process.cwd()
 	const [prettier, eslint] = await Promise.all([

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

@@ -9,7 +9,7 @@ import {
 	ESLINT_RELATED_CACHE_FILE,
 	ESLINT_RELATED_CACHE_FLAGS,
 } from '#scripts/josh/josh-command-types'
-import type { CycleRecheckOptions } from './cycle-recheck'
+import type { CrossFileRecheckOptions } from './cross-file-recheck'
 
 // `josh lint` reads the whole repository on every call, and an implementation loop calls it after
 // every few edits — re-reading files the change never touched.
@@ -113,9 +113,9 @@ function eslint_arguments(files: ReadonlyArray<string>): ReadonlyArray<string> {
 	return [...ESLINT_ARGS, ...files, ...ESLINT_RELATED_CACHE_FLAGS, ...ESLINT_SCOPED_FLAGS]
 }
 
-// What re-reading a cached cycle report (`cycle-recheck.ts`) needs to ask the narrowed run's question
+// What re-reading a cached cross-file report (`cross-file-recheck.ts`) needs to ask the narrowed run's question
 // again: the same targets, the same cache file, and the Node API's spelling of `--no-warn-ignored`.
-function cycle_recheck_options(files: ReadonlyArray<string>): CycleRecheckOptions {
+function cross_file_recheck_options(files: ReadonlyArray<string>): CrossFileRecheckOptions {
 	return {
 		cache_file: ESLINT_RELATED_CACHE_FILE,
 		patterns: files,
@@ -125,7 +125,7 @@ function cycle_recheck_options(files: ReadonlyArray<string>): CycleRecheckOption
 
 const lint_related_scope = {
 	COMMAND_LABEL,
-	cycle_recheck_options,
+	cross_file_recheck_options,
 	NOTHING_LINTABLE_REASON,
 	describe_scope,
 	eslint_arguments,

package/scripts/lint/lint-related.ts

@@ -36,7 +36,7 @@ async function lint_exit_code(scope: ChangedFileScope): Promise<number> {
 	return await lint_parallel.run_lint_checks(
 		lint_related_scope.prettier_arguments(scope.files),
 		lint_related_scope.eslint_arguments(scope.files),
-		lint_related_scope.cycle_recheck_options(scope.files),
+		lint_related_scope.cross_file_recheck_options(scope.files),
 	)
 }
 

package/scripts/rules/decision-oracle-batch.ts

@@ -106,7 +106,7 @@ const BATCH_ORACLES: ReadonlyArray<DecisionOracle> = [
 	{
 		name: 'run:step',
 		decision: 'The run’s next single action, computed from the event stream, carry and issue state',
-		args: ISSUE_N_ARG,
+		args: `[${ISSUE_N_ARG}]`,
 		// The non-command answers: `run:step` prints a runnable command for a phase with one to run, and
 		// one of these verdicts otherwise. A command line is not a vocabulary token, exactly as an issue
 		// number is not one for `backlog:next`.

package/scripts/run/run-headless.ts

@@ -123,6 +123,7 @@ async function is_backlog_parent(
 const run_headless = {
 	HEADLESS_ENV_KEY,
 	current_carry,
+	driven_here,
 	driving_carry,
 	environment,
 	is_backlog_parent,

package/scripts/run/run-step-cli.ts

@@ -13,9 +13,9 @@ import { run_headless } from './run-headless'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
 import { run_retrospective } from './run-retrospective'
-import { run_step, type StepInput } from './run-step'
+import { run_step, type ParentInput, type StepInput } from './run-step'
 
-// `josh run:step <N>` — print the run's next single action, computed from the event stream, the carry
+// `josh run:step [<N>]` — print the run's next single action, computed from the event stream, the carry
 // record and the issue state. It reads exactly those three, never the
 // conversation: the issue facts through `run:prep`'s own gather (so this and `run:next` never answer
 // from different reads), the newest event off the stream, and the carry record's kind. The reader runs
@@ -25,7 +25,8 @@ import { run_step, type StepInput } from './run-step'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const USAGE = 'Usage: josh run:step <issue-number>'
+const USAGE =
+	'Usage: josh run:step [<issue-number>] — without a number it answers for the `backlogrun` carry record this session drives'
 
 interface RunReads {
 	carry_kind: CarryRead['kind']
@@ -118,7 +119,54 @@ async function gather(issue_number: string): Promise<Gathered> {
 	return { input: step_input(parts, run_reads, is_lane_child), ship_problems: parts.ship_problems }
 }
 
+const UNREADABLE_CARRY: CarryRead = { kind: 'unreadable' }
+
+// The parent's own position — a run asked about with no issue. The last event is the run's newest in
+// scope, whichever issue it names: a parent is positioned by the whole batch, never by one child.
+function parent_reads(directory: string): Pick<ParentInput, 'carry_kind' | 'last_event'> & {
+	carry: CarryRead
+} {
+	const carry = run_carry.read_carry(run_carry.carry_path(directory))
+	const events = run_event_stream.read_events(run_event_stream.target_of(directory))
+	const last = run_event_scope.last_scoped_event(events, run_event_scope.scope_of(carry))
+
+	return { carry, carry_kind: carry.kind, last_event: last?.kind }
+}
+
+function parent_input(directory: string | undefined): ParentInput {
+	const { carry, ...position } =
+		directory === undefined
+			? { carry: UNREADABLE_CARRY, carry_kind: UNREADABLE_CARRY.kind, last_event: undefined }
+			: parent_reads(directory)
+
+	return {
+		...position,
+		is_driving: run_headless.driven_here(carry, lane_reap.own_ancestry) !== undefined,
+		is_handed_off: is_handed_off_here(carry),
+		is_at_cut_cap: carry.kind === 'carried' && run_headless.is_cut_capped(carry.carry),
+		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		is_retrospective_done: run_carry.retrospective_done_of(carry),
+		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
+		is_retrospective_enabled: run_retrospective.is_enabled(),
+	}
+}
+
+// `unknown` is the one answer with nothing to run — no record this session drives — so it exits non-zero
+// with the usage, exactly as a position missing its issue state does.
+async function run_parent(): Promise<number> {
+	const { line } = run_step.parent_action(parent_input(await run_carry.repository_directory()))
+
+	console.info(line)
+	if (line !== run_step.UNKNOWN) return SUCCESS_EXIT_CODE
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length === 0) return await run_parent()
+
 	const issue_number = run_prep_cli.parse_number(argv)
 
 	if (issue_number === undefined) {

package/scripts/run/run-step.ts

@@ -3,7 +3,7 @@ import { session_cite } from '#scripts/issue/session-cite'
 import type { CarryRead } from '#scripts/run/carry/run-carry'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
-import { run_retrospective } from './run-retrospective'
+import { run_retrospective, type RetrospectiveFacts } from './run-retrospective'
 
 // `josh run:step <N>` — the run's next single action, computed from three mechanical inputs and nothing
 // else, so the run's loop is not a state machine written in English that the reader rebuilds every
@@ -278,16 +278,19 @@ function closed_action(input: StepInput): StepAction {
 	}
 }
 
+// What the carry record alone says — the part an issue's position and the parent's own share.
+type CarryFacts = Pick<StepInput, 'carry_kind' | 'is_handed_off' | 'is_lane_child'>
+
 // **A cut hands the run on, so the session that took it stops** — otherwise it would go on answering
 // `wait` or the next offer after `run:carry --cut`, launching children in the same conversation. A
 // lane child never holds the carry record, so its own position is not decided here.
-function is_handed_off_parent(input: StepInput): boolean {
+function is_handed_off_parent(input: CarryFacts): boolean {
 	return input.is_handed_off && input.carry_kind === 'carried' && !input.is_lane_child
 }
 
 // The carry record's terminal answers: an unreadable record leaves the position unknowable, a handed-off
 // run is its successor's, and a spent budget is the person's call.
-function carry_terminal_action(input: StepInput): StepAction | undefined {
+function carry_terminal_action(input: CarryFacts): StepAction | undefined {
 	if (input.carry_kind === 'unreadable') return verdict(UNKNOWN)
 	if (is_handed_off_parent(input)) return verdict(STOP)
 	if (input.carry_kind === 'expired') return { kind: 'decide', line: EXPIRED_DECISION }
@@ -308,6 +311,47 @@ function terminal_action(input: StepInput): StepAction | undefined {
 	return undefined
 }
 
+// **A run with no issue still has a next action** — the `backlogrun` parent's own position, read off the
+// carry record alone. Without it a run that dispatched nothing — one begun on an empty backlog — has no
+// position to ask about, and "the backlog is empty, so the run is over" is decided in the conversation
+// instead of by the idle watch.
+interface ParentInput extends RetrospectiveFacts {
+	carry_kind: CarryRead['kind']
+	// Whether this session declared the live record and no cut has handed it off yet.
+	is_driving: boolean
+	is_handed_off: boolean
+	is_at_cut_cap: boolean
+	last_event: string | undefined
+}
+
+// The positions the end-of-run retrospective fires at, whoever asks.
+const RETROSPECTIVE_POSITIONS: ReadonlySet<string> = new Set([KIND.DRAIN, KIND.STOP])
+
+function is_retrospective_position(input: ParentInput): boolean {
+	return RETROSPECTIVE_POSITIONS.has(input.last_event ?? '') && run_retrospective.is_owed(input)
+}
+
+// **The loop belongs to the supervisor, so a driving parent's next action is the hand-off whatever the
+// plan held.** The supervisor starts no driver while a live owner holds the record, and only the driver
+// runs the idle watch. A record at the cut cap has no cut left to take, so its session carries on.
+function driving_action(input: ParentInput): StepAction {
+	if (is_retrospective_position(input)) return command(RETROSPECTIVE_COMMAND)
+
+	return input.is_at_cut_cap ? verdict(WAIT) : command(HAND_OFF_COMMAND)
+}
+
+// A lane child's position is its issue's, and a record this session does not drive — absent, or another
+// session's — is not its to hand off: both are `unknown`, never a guess at someone else's run.
+function parent_action(input: ParentInput): StepAction {
+	if (input.is_lane_child) return verdict(UNKNOWN)
+
+	const terminal = carry_terminal_action(input)
+
+	if (terminal !== undefined) return terminal
+
+	return input.is_driving ? driving_action(input) : verdict(UNKNOWN)
+}
+
 // The one entry point: the run's next action, from the three inputs and nothing else. A terminal answer
 // wins first; otherwise a run with nothing emitted yet is at its pre-implementation position, and a run
 // that has begun is placed by its newest event.
@@ -339,8 +383,9 @@ const run_step = {
 	VOCABULARY,
 	WAIT,
 	next_action,
+	parent_action,
 	pre_verdict,
 }
 
-export type { PreInput, PreVerdict, StepAction, StepInput }
+export type { ParentInput, PreInput, PreVerdict, StepAction, StepInput }
 export { run_step }

package/scripts/lint/cycle-recheck.ts

@@ -1,122 +0,0 @@
-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 }