@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/exports/unused-members-cli.ts

@@ -1,58 +1,13 @@
 #!/usr/bin/env tsx
-import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { project_checks } from '#scripts/gate/project-checks'
-import { NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
-import type { NamespaceMember } from './namespace-members'
+import { unused_members_check } from './unused-members-check'
 
-const CHECK = 'exports'
-const FAIL_EXIT_CODE = 1
-// A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
-// `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
-//
-// **Not a skip notice**. `SKIP_MARKER` means "a check passed without running",
-// and the gate withholds its green record on it — so a consumer, where this notice prints on every
-// run, never got a green record. Out of scope by design is not unverified, so the marker stays out.
-const CONSUMER_NOTICE = `josh ${CHECK}: checks only the kit repository itself — ${NOTHING_TO_CHECK_MARKER} in a consumer project.`
-
-function format_member(root: string, member: NamespaceMember): string {
-	return `${path.relative(root, member.file)}:${String(member.line)}  ${member.namespace}.${member.member}`
-}
-
-function report(root: string, members: ReadonlyArray<NamespaceMember>): string {
-	if (members.length === 0) return `josh ${CHECK}: no unused namespace member`
-
-	return [
-		`josh ${CHECK}: ${String(members.length)} namespace member(s) nothing reads — remove each from its namespace object (and the declaration, if nothing in its file uses it either):`,
-		...members.map((member) => `  ${format_member(root, member)}`),
-	].join('\n')
-}
-
-async function run_unused_members(root: string): Promise<number> {
-	if (doctor_consumer.is_kit_consumer(root)) {
-		console.info(CONSUMER_NOTICE)
-
-		return 0
-	}
-
-	// Loaded only past the skip: the scanner pulls in `typescript`, an optional peer a basic-profile
-	// consumer may not have, and this check runs in every consumer's gate. For the same reason the
-	// scanner is left out of the published package (`package.json` `files`); only this entry ships.
-	const { unused_members } = await import('./unused-members')
-	const members = unused_members.find_unused_members(root)
-	const output = report(root, members)
-
-	if (members.length === 0) console.info(output)
-	else console.error(output)
-
-	return members.length === 0 ? 0 : FAIL_EXIT_CODE
-}
+// The `josh exports:unused` entry point: the whole-program scan the gate runs. `josh lint:related`
+// imports the check itself, narrowed to the changed files.
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run_unused_members(project_checks.project_root(process.cwd()))
+	process.exitCode = await unused_members_check.run_unused_members(
+		project_checks.project_root(process.cwd()),
+	)
 }
-
-const unused_members_cli = { run_unused_members, CONSUMER_NOTICE }
-
-export { unused_members_cli }

package/scripts/followup/followup-checks-event.ts

@@ -35,16 +35,21 @@ function coderabbit_state_of(check: RollupCheck | undefined): CodeRabbitState {
 	return is_coderabbit_rate_limited(check) ? 'rate-limited' : 'done'
 }
 
+// CodeRabbit's state on one poll — the reading `run:board` draws and `followup` times
+// (`followup-coderabbit-wait.ts`).
+function coderabbit_of(snapshot: PrStateSnapshot): CodeRabbitState {
+	return coderabbit_state_of(snapshot.rollup.find((check) => is_coderabbit_check(check.name)))
+}
+
 function summary_of(snapshot: PrStateSnapshot, pr: number): PrChecks {
 	const ci = snapshot.rollup.filter((check) => !is_coderabbit_check(check.name))
-	const coderabbit = snapshot.rollup.find((check) => is_coderabbit_check(check.name))
 
 	return {
 		pr,
 		pass: count_of(ci, CHECK_STATUS_PASS),
 		pending: count_of(ci, CHECK_STATUS_PENDING),
 		fail: count_of(ci, CHECK_STATUS_FAIL),
-		coderabbit: coderabbit_state_of(coderabbit),
+		coderabbit: coderabbit_of(snapshot),
 	}
 }
 
@@ -77,6 +82,6 @@ function observer_of(issue: string | undefined, pr_url: string | undefined): Sna
 	}
 }
 
-const followup_checks_event = { observer_of, summary_of }
+const followup_checks_event = { coderabbit_of, observer_of, summary_of }
 
 export { followup_checks_event }

package/scripts/followup/followup-ci-path.ts

@@ -0,0 +1,67 @@
+import type { SnapshotObserver } from '#scripts/gh/git-pr-checks'
+import { is_coderabbit_check } from '#scripts/gh/git-pr-checks-eval'
+import { CHECK_STATUS_PENDING, type PrStateSnapshot } from '#scripts/gh/git-pr-checks-parse'
+
+// Which check `followup`'s CI wait waited on last (joshuafolkken/kit#5295). The `ci-wait` row alone
+// says how long the wait was, not which job held it, so the next job to shorten could not be chosen.
+//
+// **A check is timed when it is seen pending and then settled**: its time is the interval from the
+// wait's first poll to the first poll that saw it settled. A check already settled at the first poll
+// held nothing up and is not recorded. CodeRabbit is left out — its wait is `coderabbit-wait`'s
+// (`followup-coderabbit-wait.ts`), so it is never counted twice. The clock is `performance.now()`'s
+// for the reason `git-followup-stages.ts` states.
+
+// Mutable for the reason `StageLog` is: the observer adds to it as the wait polls.
+interface CiPath {
+	start_ms?: number
+	pending: Set<string>
+	check_ms: Record<string, number>
+}
+
+// The `ci-wait` row's critical-path fields, both absent where no check was seen to settle.
+interface CiPathRecord {
+	last_check?: string
+	check_ms?: Record<string, number>
+}
+
+function new_path(): CiPath {
+	return { pending: new Set(), check_ms: {} }
+}
+
+function settle(path: CiPath, name: string, elapsed_ms: number): void {
+	if (path.pending.delete(name)) path.check_ms[name] = elapsed_ms
+}
+
+function observe(path: CiPath, snapshot: PrStateSnapshot, now_ms: number): void {
+	path.start_ms ??= now_ms
+	const elapsed_ms = now_ms - path.start_ms
+	const checks = snapshot.rollup.filter((check) => !is_coderabbit_check(check.name))
+
+	for (const check of checks) {
+		if (check.status === CHECK_STATUS_PENDING) path.pending.add(check.name)
+		else settle(path, check.name, elapsed_ms)
+	}
+}
+
+// **Only the first check wait is timed**: the `ci-wait` row is that wait's lap, and the wait the merge
+// goes back to when the head moved (#4036) times checks the row does not cover.
+function observer_of(path: CiPath): SnapshotObserver {
+	const is_first_wait = path.start_ms === undefined
+
+	return async function time_checks(snapshot: PrStateSnapshot): Promise<void> {
+		if (is_first_wait) observe(path, snapshot, performance.now())
+	}
+}
+
+function record_of(path: CiPath): CiPathRecord {
+	const [last] = Object.entries(path.check_ms).toSorted((left, right) => right[1] - left[1])
+
+	if (last === undefined) return {}
+
+	return { last_check: last[0], check_ms: { ...path.check_ms } }
+}
+
+const followup_ci_path = { new_path, observe, observer_of, record_of }
+
+export type { CiPath, CiPathRecord }
+export { followup_ci_path }

package/scripts/followup/followup-coderabbit-retrigger.ts

@@ -0,0 +1,261 @@
+// cspell:words coderabbit coderabbitai
+import { is_coderabbit_author, is_coderabbit_rate_limit } from '#scripts/gh/git-ai-review-scan'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { SnapshotObserver } from '#scripts/gh/git-pr-checks'
+import { parse_pr_state_snapshot } from '#scripts/gh/git-pr-checks-parse'
+import { ai_review_pull_comment_schema } from '#scripts/git/git-schemas'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { poll } from '#scripts/lib/poll'
+import type { CodeRabbitState } from '#scripts/run/event/run-event-checks'
+import { followup_checks_event } from './followup-checks-event'
+import { followup_coderabbit_wait, type CodeRabbitWait } from './followup-coderabbit-wait'
+
+// A rate-limited CodeRabbit, retriggered once by `followup` itself (joshuafolkken/kit#5289): read the
+// window off CodeRabbit's own notice, wait it out, post `@coderabbitai review`, and wait for the check
+// again. **Once per pull request** — a retrigger comment older than the latest notice means the one
+// attempt was spent, and a second rate limit is the person's call (bypassing it is Tier C); one newer
+// than it, whoever posted it, is a review still to come and is waited for, not posted again. The pull
+// request, not the ledger, answers "already retriggered", so a re-run `followup` reads the same answer.
+
+const RETRIGGER_BODY = '@coderabbitai review'
+// `Please wait **12 minutes and 34 seconds** before requesting another review.` — the clause between
+// `wait` and `before`, read as `<number> <unit>` token pairs.
+const WAIT_OPENER = /please wait/iu
+const WAIT_CLOSER = /before/iu
+const TOKEN = /\d+|[a-z]+/giu
+const DIGITS = /^\d+$/u
+const SECOND_MS = 1000
+const SECONDS_PER_MINUTE = 60
+const MINUTES_PER_HOUR = 60
+const MINUTE_MS = SECONDS_PER_MINUTE * SECOND_MS
+const UNIT_MS: Readonly<Record<string, number>> = {
+	h: MINUTES_PER_HOUR * MINUTE_MS,
+	m: MINUTE_MS,
+	s: SECOND_MS,
+}
+// Past the window's end, so the retrigger does not land on its last second.
+const MARGIN_SECONDS = 15
+const MARGIN_MS = MARGIN_SECONDS * SECOND_MS
+// The longest window `followup` waits out; a longer one is left to the person (`followup.md`).
+const WINDOW_CAP_MINUTES = 30
+const WINDOW_CAP_MS = WINDOW_CAP_MINUTES * MINUTE_MS
+// The wait for the retriggered review: twenty minutes, polled every thirty seconds.
+const REVIEW_WAIT_ATTEMPTS = 40
+const REVIEW_WAIT_INTERVAL_SECONDS = 30
+const REVIEW_WAIT_INTERVAL_MS = REVIEW_WAIT_INTERVAL_SECONDS * SECOND_MS
+const NO_TIME = 0
+const FIRST = 0
+const NEXT = 1
+const RATE_LIMITED: CodeRabbitState = 'rate-limited'
+const TIER_C = 'bypassing it is Tier C — explicit user instruction only'
+const BY_HAND = `wait it out, post \`${RETRIGGER_BODY}\` and rerun followup; ${TIER_C}`
+const AGAIN_NOTE = `CodeRabbit rate-limited again after the one \`${RETRIGGER_BODY}\` (kit#5289): ${TIER_C}`
+const UNREADABLE_NOTE = `CodeRabbit rate-limited with no window readable from its comments (kit#5289): no retrigger posted — ${BY_HAND}`
+const UNFINISHED_NOTE = `CodeRabbit still reviewing after \`${RETRIGGER_BODY}\` (kit#5289): the merge goes ahead without it`
+
+interface PullComment {
+	body?: string | undefined
+	author?: { login?: string | undefined } | undefined
+	updatedAt?: string | undefined
+}
+
+type Decision =
+	{ kind: 'retrigger'; wait_ms: number } | { kind: 'await' } | { kind: 'stop'; note: string }
+
+interface Retrigger {
+	is_retriggered: boolean
+	notes: Array<string>
+}
+
+interface Settled<T> {
+	snapshot: T
+	is_retriggered: boolean
+	notes: Array<string>
+}
+
+function wait_clause_of(body: string): string {
+	const after_opener = body.split(WAIT_OPENER)[NEXT] ?? ''
+
+	return after_opener.split(WAIT_CLOSER)[FIRST] ?? ''
+}
+
+// The time one token stands for: a number times the unit the next token starts with.
+function token_ms(tokens: ReadonlyArray<string>, index: number): number {
+	const token = tokens[index] ?? ''
+	if (!DIGITS.test(token)) return NO_TIME
+	const unit = (tokens[index + NEXT] ?? '').charAt(FIRST).toLowerCase()
+
+	return Number(token) * (UNIT_MS[unit] ?? NO_TIME)
+}
+
+// The wait CodeRabbit's notice states, or `undefined` for a comment that states none.
+function parse_wait_ms(body: string): number | undefined {
+	if (!is_coderabbit_rate_limit(body)) return undefined
+	const tokens = wait_clause_of(body).match(TOKEN) ?? []
+	const wait_ms = tokens.reduce((sum, _token, index) => sum + token_ms(tokens, index), NO_TIME)
+
+	return wait_ms === NO_TIME ? undefined : wait_ms
+}
+
+function is_notice(comment: PullComment): boolean {
+	return (
+		is_coderabbit_author(comment.author?.login ?? '') &&
+		is_coderabbit_rate_limit(comment.body ?? '')
+	)
+}
+
+function is_retrigger(comment: PullComment): boolean {
+	return comment.body?.trim() === RETRIGGER_BODY
+}
+
+function written_ms(comment: PullComment): number {
+	return Date.parse(comment.updatedAt ?? '')
+}
+
+// The latest time among the comments `is_match` picks; one with no readable time counts as none.
+function latest_ms(
+	comments: ReadonlyArray<PullComment>,
+	is_match: (comment: PullComment) => boolean,
+): number | undefined {
+	const times = comments
+		.filter((comment) => is_match(comment))
+		.map((comment) => written_ms(comment))
+		.filter((ms) => !Number.isNaN(ms))
+
+	return times.length === 0 ? undefined : Math.max(...times)
+}
+
+// The latest end any CodeRabbit notice states — the window counts from when the notice was written.
+function window_end_ms(comments: ReadonlyArray<PullComment>): number | undefined {
+	const ends = comments
+		.filter((comment) => is_notice(comment))
+		.map((comment) => written_ms(comment) + (parse_wait_ms(comment.body ?? '') ?? NaN))
+		.filter((ms) => !Number.isNaN(ms))
+
+	return ends.length === 0 ? undefined : Math.max(...ends)
+}
+
+// A retrigger written after the latest notice is still to be answered; one before it was answered
+// with another rate limit. Either time unreadable reads as the second.
+function decide_after_retrigger(comments: ReadonlyArray<PullComment>): Decision {
+	const retrigger_ms = latest_ms(comments, is_retrigger) ?? NO_TIME
+	const notice_ms = latest_ms(comments, is_notice) ?? retrigger_ms
+
+	return retrigger_ms > notice_ms ? { kind: 'await' } : { kind: 'stop', note: AGAIN_NOTE }
+}
+
+function too_long_note(wait_ms: number): string {
+	const minutes = String(Math.ceil(wait_ms / MINUTE_MS))
+
+	return `CodeRabbit rate-limited for ${minutes} more minutes, over followup's ${String(WINDOW_CAP_MINUTES)} minute wait (kit#5289): no retrigger posted — ${BY_HAND}`
+}
+
+function decide(comments: ReadonlyArray<PullComment>, now_ms: number): Decision {
+	if (comments.some((comment) => is_retrigger(comment))) return decide_after_retrigger(comments)
+	const end_ms = window_end_ms(comments)
+	if (end_ms === undefined) return { kind: 'stop', note: UNREADABLE_NOTE }
+	const wait_ms = Math.max(NO_TIME, end_ms - now_ms) + MARGIN_MS
+
+	return wait_ms > WINDOW_CAP_MS
+		? { kind: 'stop', note: too_long_note(wait_ms) }
+		: { kind: 'retrigger', wait_ms }
+}
+
+async function read_comments(branch_name: string): Promise<Array<PullComment>> {
+	const raw = await git_gh_command.pr_get_comments(branch_name)
+
+	return parse_json_array_or_undefined(raw ?? '', ai_review_pull_comment_schema) ?? []
+}
+
+async function read_state(
+	branch_name: string,
+	observe: SnapshotObserver,
+): Promise<CodeRabbitState> {
+	const checks = await git_gh_command.pr_get_checks_snapshot(branch_name)
+	const snapshot = parse_pr_state_snapshot(checks.snapshot_json)
+
+	await observe(snapshot)
+
+	return followup_checks_event.coderabbit_of(snapshot)
+}
+
+// **A rate limit read before the review started is the old one**, so only one read after another
+// state is the second rate limit; a check that never moves off it is read as one at the budget's end.
+// One observer for the whole wait, so its polls are timed against one another.
+async function wait_for_review(branch_name: string, wait: CodeRabbitWait): Promise<Array<string>> {
+	const observe = followup_coderabbit_wait.observer_of(wait)
+	let is_started = false
+	let state: CodeRabbitState = RATE_LIMITED
+	const is_settled = await poll.poll_until(
+		async () => {
+			state = await read_state(branch_name, observe)
+			is_started ||= state !== RATE_LIMITED
+
+			return is_started && state !== 'running'
+		},
+		{ attempts: REVIEW_WAIT_ATTEMPTS, interval_ms: REVIEW_WAIT_INTERVAL_MS, sleeper: poll.sleep },
+	)
+	if (state === RATE_LIMITED) return [AGAIN_NOTE]
+
+	return is_settled ? [] : [UNFINISHED_NOTE]
+}
+
+async function retrigger(
+	branch_name: string,
+	wait: CodeRabbitWait,
+	wait_ms: number,
+): Promise<Retrigger> {
+	const seconds = String(Math.ceil(wait_ms / SECOND_MS))
+
+	console.info(`⏳ CodeRabbit rate-limited — waiting ${seconds}s, then \`${RETRIGGER_BODY}\``)
+	await poll.sleep(wait_ms)
+	await git_gh_command.pr_comment(branch_name, RETRIGGER_BODY)
+	await lane_ledger_write.record_stage({
+		stage: lane_ledger_write.CODERABBIT_RETRIGGER_STAGE,
+		elapsed_ms: wait_ms,
+	})
+
+	return { is_retriggered: true, notes: await wait_for_review(branch_name, wait) }
+}
+
+// Runs only when the check wait last saw CodeRabbit rate-limited; anything else is untouched.
+async function run(branch_name: string, wait: CodeRabbitWait): Promise<Retrigger> {
+	if (wait.last?.state !== RATE_LIMITED) return { is_retriggered: false, notes: [] }
+	const decision = decide(await read_comments(branch_name), Date.now())
+	if (decision.kind === 'stop') return { is_retriggered: false, notes: [decision.note] }
+
+	if (decision.kind === 'await') {
+		return { is_retriggered: true, notes: await wait_for_review(branch_name, wait) }
+	}
+
+	return await retrigger(branch_name, wait, decision.wait_ms)
+}
+
+// The checks after a retriggered review are read again, so the merge and the skip notes read the
+// snapshot that review left, not the rate-limited one.
+async function settle<T>(
+	snapshot: T,
+	wait_for_green: () => Promise<T>,
+	branch_name: string,
+	wait: CodeRabbitWait,
+): Promise<Settled<T>> {
+	const { is_retriggered, notes } = await run(branch_name, wait)
+	if (!is_retriggered) return { snapshot, is_retriggered, notes }
+
+	return { snapshot: await wait_for_green(), is_retriggered, notes }
+}
+
+const followup_coderabbit_retrigger = {
+	AGAIN_NOTE,
+	RETRIGGER_BODY,
+	UNFINISHED_NOTE,
+	UNREADABLE_NOTE,
+	decide,
+	parse_wait_ms,
+	run,
+	settle,
+}
+
+export type { PullComment, Retrigger, Settled }
+export { followup_coderabbit_retrigger }

package/scripts/followup/followup-coderabbit-wait.ts

@@ -0,0 +1,85 @@
+import type { SnapshotObserver } from '#scripts/gh/git-pr-checks'
+import type { PrStateSnapshot } from '#scripts/gh/git-pr-checks-parse'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import type { CodeRabbitState } from '#scripts/run/event/run-event-checks'
+import { followup_checks_event } from './followup-checks-event'
+
+// How long `followup`'s check waits spent with CodeRabbit still running or rate-limited
+// (joshuafolkken/kit#4574). CodeRabbit does not gate the merge, so the wait never names it; without
+// this, a followup that sat for half an hour beside a rate-limited CodeRabbit leaves nothing in the
+// lane ledger but a long `ci-wait`.
+//
+// **The time between two polls is the state the earlier poll saw** — the observer sees snapshots, not
+// transitions, so the clock is read at each one and the interval since the last is charged to the
+// state that held over it. The clock is `performance.now()`'s, monotonic for the reason
+// `git-followup-stages.ts` states.
+
+const NO_TIME = 0
+const RATE_LIMITED: CodeRabbitState = 'rate-limited'
+const WAITING_STATES: ReadonlySet<CodeRabbitState> = new Set(['running', RATE_LIMITED])
+
+interface Poll {
+	state: CodeRabbitState
+	at_ms: number
+}
+
+// Mutable for the reason `StageLog` is: the observer adds to it as the wait polls.
+interface CodeRabbitWait {
+	wait_ms: number
+	rate_limited_ms: number
+	last?: Poll
+}
+
+function new_wait(): CodeRabbitWait {
+	return { wait_ms: NO_TIME, rate_limited_ms: NO_TIME }
+}
+
+function charge(wait: CodeRabbitWait, last: Poll, now_ms: number): void {
+	const elapsed_ms = now_ms - last.at_ms
+
+	if (WAITING_STATES.has(last.state)) wait.wait_ms += elapsed_ms
+	if (last.state === RATE_LIMITED) wait.rate_limited_ms += elapsed_ms
+}
+
+function observe(wait: CodeRabbitWait, snapshot: PrStateSnapshot, now_ms: number): void {
+	if (wait.last !== undefined) charge(wait, wait.last, now_ms)
+
+	wait.last = { state: followup_checks_event.coderabbit_of(snapshot), at_ms: now_ms }
+}
+
+// **Each check wait is timed from its own first poll**: the time between two waits — the comment scans,
+// the merge that found the head moved — is not CodeRabbit's, whatever the earlier wait last saw.
+function observer_of(wait: CodeRabbitWait): SnapshotObserver {
+	delete wait.last
+
+	return async function time_snapshot(snapshot: PrStateSnapshot): Promise<void> {
+		observe(wait, snapshot, performance.now())
+	}
+}
+
+// Every observer on every poll, started in order — the board's event line and the wait's timers.
+function all(...observers: ReadonlyArray<SnapshotObserver>): SnapshotObserver {
+	return async function observe_all(snapshot: PrStateSnapshot): Promise<void> {
+		await Promise.all(
+			observers.map(async (observer) => {
+				await observer(snapshot)
+			}),
+		)
+	}
+}
+
+async function record_part(stage: string, elapsed_ms: number): Promise<void> {
+	if (elapsed_ms > NO_TIME) await lane_ledger_write.record_stage({ stage, elapsed_ms })
+}
+
+// **A run that never saw CodeRabbit waiting records nothing**, so a row's run count is how many
+// followups CodeRabbit held up, and its median is over those.
+async function record(wait: CodeRabbitWait): Promise<void> {
+	await record_part(lane_ledger_write.CODERABBIT_WAIT_STAGE, wait.wait_ms)
+	await record_part(lane_ledger_write.CODERABBIT_RATE_LIMIT_STAGE, wait.rate_limited_ms)
+}
+
+const followup_coderabbit_wait = { all, new_wait, observe, observer_of, record }
+
+export type { CodeRabbitWait }
+export { followup_coderabbit_wait }

package/scripts/followup/followup-failed-tests.ts

@@ -0,0 +1,160 @@
+import path from 'node:path'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import {
+	observation_record,
+	REFUSED_VERDICT,
+	type ObservationEntry,
+} from '#scripts/observations/observation-record'
+import { review_comment_round } from '#scripts/review/review-comment-round'
+import { vitest_failure_summary } from '#scripts/test/vitest-failure-summary'
+
+// A CI job that ended `failure` because a unit test went red can still owe nothing to the change: a test
+// the diff never touched fails under runner load (joshuafolkken/kit#5152, a frame-budget test on a busy
+// runner). `followup` reruns such a job once, as it does a stalled one (`followup-job-rerun.ts`), and
+// these are the readings that decide it: the failed tests a job's log names, and whether any of them
+// belongs to the change.
+//
+// **A test belongs to the change when its own file or its subject module moved** — `foo.claim.test.ts`
+// tests `foo.claim.ts` and `foo.ts`. A test reaching a moved module only through an import is missed,
+// and costs one rerun: the second red still stops `followup`, since a rerun attempt is never rerun.
+
+// GitHub Actions stamps every log line `<ISO timestamp> `, which vitest's ` FAIL  ` line does not begin with.
+const LOG_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\S+Z /u
+const TEST_SUFFIX = /\.test(?<extension>\.[^./]+)$/u
+const SEGMENT_SEPARATOR = '.'
+const OBSERVATION_SLUG = 'followup-unrelated-test-rerun'
+const OBSERVATION_DEPTH = 'd1'
+const NAME_SEPARATOR = '; '
+const UNNAMED_ISSUE =
+	'Did not record the failed tests outside the change: the branch names no issue to post them on.'
+
+const RERUN_VERDICT = 'rerun'
+const KEPT_VERDICT = 'kept'
+const UNNAMED_VERDICT = 'unnamed'
+
+type TestVerdict = typeof RERUN_VERDICT | typeof KEPT_VERDICT | typeof UNNAMED_VERDICT
+
+interface FailedTests {
+	files: ReadonlyArray<string>
+	names: ReadonlyArray<string>
+}
+
+interface UnrelatedFailure {
+	job: string
+	tests: FailedTests
+}
+
+// The failed tests vitest named in a job's log — empty when the job failed on anything but a test.
+function read_failed_tests(log: string): FailedTests {
+	const lines = log.split('\n').map((line) => line.replace(LOG_TIMESTAMP, ''))
+	const names = vitest_failure_summary.failed_tests(lines.join('\n'))
+
+	return { files: vitest_failure_summary.failed_files(names), names }
+}
+
+// The test file itself, then the module each leading run of its name's segments names.
+function subjects_of(test_file: string): ReadonlyArray<string> {
+	const extension = TEST_SUFFIX.exec(test_file)?.groups?.['extension']
+
+	if (extension === undefined) return [test_file]
+
+	const directory = path.posix.dirname(test_file)
+	const segments = path.posix.basename(test_file, `.test${extension}`).split(SEGMENT_SEPARATOR)
+	const modules = segments.map((_, index) =>
+		path.posix.join(
+			directory,
+			`${segments.slice(0, index + 1).join(SEGMENT_SEPARATOR)}${extension}`,
+		),
+	)
+
+	return [test_file, ...modules]
+}
+
+function is_in_change(test_file: string, changed: ReadonlySet<string>): boolean {
+	return subjects_of(test_file).some((subject) => changed.has(subject))
+}
+
+// **`rerun` only when the log named a failed test and none of them belongs to the change**, `kept`
+// when one does. A job red with no test named — a lint, a build, a job gathering others' results — is
+// `unnamed`: rerun only as one waiting on a job red on tests outside the change (`followup-job-needs.ts`).
+function verdict_of(tests: FailedTests, changed: ReadonlySet<string>): TestVerdict {
+	if (tests.files.length === 0) return UNNAMED_VERDICT
+
+	return tests.files.every((file) => !is_in_change(file, changed)) ? RERUN_VERDICT : KEPT_VERDICT
+}
+
+// The ledger line a rerun leaves, so a test that keeps failing beside unrelated changes is counted
+// rather than retried into silence. A ledger line's fields are split on ` | `, so the `|<project>|`
+// prefix a workspace test name carries is rewritten.
+function observation_of(failures: ReadonlyArray<UnrelatedFailure>): ObservationEntry {
+	const files = new Set(failures.flatMap(({ tests }) => tests.files))
+	const names = new Set(failures.flatMap(({ tests }) => tests.names))
+	const listed = [...names].map((name) => name.replaceAll('|', '/'))
+	const jobs = failures.map(({ job }) => job)
+
+	return {
+		slug: OBSERVATION_SLUG,
+		depth: OBSERVATION_DEPTH,
+		where: [...files].join(', '),
+		what: `followup reran ${jobs.join(', ')}; failed outside the change: ${listed.join(NAME_SEPARATOR)}`,
+	}
+}
+
+// **The line is posted on the issue, never appended to the tree** (joshuafolkken/kit#5197): the rerun
+// happens during the CI wait, after `prepare_merge` committed the ledger, so an appended line would
+// either be lost with the lane or need a push of its own that restarts CI. `review-comment-round.ts`
+// carries it into the ledger once the issue closes; the count is still read off this tree's ledger.
+async function post(entry: ObservationEntry, issue: number): Promise<string> {
+	const assessment = await observation_record.assess({
+		entry,
+		checkout: observation_ledger_home.ledger_root(),
+		now: new Date(),
+	})
+
+	if (assessment.verdict === REFUSED_VERDICT) return `${REFUSED_VERDICT}: ${assessment.reason}`
+
+	await git_gh_issue_write.issue_comment(
+		String(issue),
+		review_comment_round.observation_body_of([assessment.line]),
+	)
+
+	return assessment.verdict
+}
+
+// A post that fails is reported and does not stop the step it describes; a branch naming no issue has
+// nowhere to post.
+async function record_entry(entry: ObservationEntry, issue: number | undefined): Promise<void> {
+	if (issue === undefined) {
+		console.info(`⚠️ ${UNNAMED_ISSUE}`)
+
+		return
+	}
+
+	try {
+		console.info(`📝 Recorded the ${entry.slug} observation: ${await post(entry, issue)}`)
+	} catch (error) {
+		console.info(`⚠️ Could not record the ${entry.slug} observation: ${String(error)}`)
+	}
+}
+
+async function record(
+	failures: ReadonlyArray<UnrelatedFailure>,
+	issue: number | undefined,
+): Promise<void> {
+	if (failures.length === 0) return
+
+	await record_entry(observation_of(failures), issue)
+}
+
+const followup_failed_tests = {
+	observation_of,
+	read_failed_tests,
+	record,
+	record_entry,
+	subjects_of,
+	verdict_of,
+}
+
+export type { FailedTests, TestVerdict, UnrelatedFailure }
+export { followup_failed_tests, KEPT_VERDICT, OBSERVATION_SLUG, RERUN_VERDICT, UNNAMED_VERDICT }