@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/run/ship/run-ship-stop-cause.ts

@@ -0,0 +1,135 @@
+import { api_auth } from '#scripts/agent/api-auth'
+import { NO_CHECKS_MESSAGE } from '#scripts/gh/git-pr-checks-watch'
+import type { StopRecord } from '#scripts/lane/lane-ledger'
+import { run_ship_review, type StopFinding } from './run-ship-review'
+import { run_ship_stage, type Stage } from './run-ship-stage'
+
+// Why a `josh ship` stage stopped, beside the stage it stopped at: a review that found something, a
+// merge git could not finish, a check that went red, or the infrastructure — a rate limit, a check list
+// GitHub did not return, a network blip — that a re-run clears (joshuafolkken/kit#3998).
+//
+// **Only a stage whose output is the tooling's own is read for infrastructure**: a gate's or a review's
+// output carries test titles and findings, which may name a rate limit without being one, and their
+// stops are the quality gate's own verdict — never retried, never relabelled.
+//
+// **A review round names its own cause**: the step of the round that stopped tags its result — a red
+// join or scoped pair `check`, a reviewer that did not finish `infra`, a refused attestation `attest` —
+// so only a stop on a recorded finding counts as one (joshuafolkken/kit#4431). An untagged review stop
+// stays a finding.
+
+const CAUSE = {
+	FINDING: 'finding',
+	INFRA: 'infra',
+	CONFLICT: 'conflict',
+	CHECK: 'check',
+	AUTH: 'auth',
+	ATTEST: 'attest',
+} as const
+
+type Cause = (typeof CAUSE)[keyof typeof CAUSE]
+
+const { STAGE } = run_ship_stage
+const REVIEW_STAGES: ReadonlySet<Stage> = new Set([STAGE.REVIEW, STAGE.ROUND_TWO])
+const INFRA_STAGES: ReadonlySet<Stage> = new Set([
+	STAGE.SYNC,
+	STAGE.COMMIT,
+	STAGE.FOLLOWUP,
+	STAGE.REPORT,
+])
+const INFRA_PATTERNS: ReadonlyArray<RegExp> = [
+	/rate limit/iu,
+	new RegExp(NO_CHECKS_MESSAGE, 'u'),
+	/\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND)\b/u,
+	/socket hang up/iu,
+	/could not resolve host/iu,
+	/\bHTTP 50[234]\b/u,
+]
+
+function is_infra(output: string): boolean {
+	return INFRA_PATTERNS.some((pattern) => pattern.test(output))
+}
+
+// A reviewer that could not authenticate is no finding: the review steps put `AUTH_FAILURE_NOTE` at the
+// head of a stop line (`isolated reviewer failed: <note>` or `<note>`), and only there is it read — a
+// finding that quotes the note mid-line stays a finding (joshuafolkken/kit#4216).
+const AUTH_LINE = new RegExp(
+	`^(?:isolated reviewer failed: (?:the broker answered a failure: )?)?${api_auth.AUTH_FAILURE_NOTE}`,
+	'mu',
+)
+
+function is_review(stage: Stage): boolean {
+	return REVIEW_STAGES.has(stage)
+}
+
+function review_cause(output: string, tagged: Cause = CAUSE.FINDING): Cause {
+	return AUTH_LINE.test(output) ? CAUSE.AUTH : tagged
+}
+
+// What a stopped stage handed back: its output, the paths a stopped merge left unmerged, the kinds
+// of the preconditions a stopped preflight found unmet, and the cause a review round tagged its stop with.
+interface StoppedOutput {
+	body: string
+	// The standard output alone, read for the infrastructure in place of the body when present.
+	out?: string
+	conflicts?: ReadonlyArray<string>
+	preconditions?: ReadonlyArray<string>
+	cause?: Cause
+}
+
+const NO_OUTPUT: StoppedOutput = { body: '' }
+
+// A failed stage's body also carries its stderr, where a poll warns of a transient rate limit it then
+// recovered from — so the infrastructure is read on the standard output alone wherever the stage kept it.
+function infra_text({ body, out = body }: StoppedOutput): string {
+	return out
+}
+
+function cause_of(stage: Stage, failed: StoppedOutput): Cause {
+	const { body, conflicts, cause } = failed
+	const reason = run_ship_stage.stop_reason(stage, conflicts)
+
+	if (reason === run_ship_stage.CONFLICT) return CAUSE.CONFLICT
+	if (is_review(stage)) return review_cause(body, cause)
+
+	return INFRA_STAGES.has(stage) && is_infra(infra_text(failed)) ? CAUSE.INFRA : CAUSE.CHECK
+}
+
+// Whether a finding decided the stop — false on any other stop, and on a review stop no finding decided
+// (a red gate at the join, a reviewer that never answered).
+function is_finding_stop(stage: Stage, cause: Cause): boolean {
+	return is_review(stage) && cause === CAUSE.FINDING
+}
+
+// The kind of every blocking finding a review stop's output lists.
+function findings_of(stage: Stage, cause: Cause, body: string): ReadonlyArray<string> {
+	return is_finding_stop(stage, cause) ? run_ship_review.blocking_kinds(body) : []
+}
+
+// Each finding that decided a review stop, whole, for the durable stop log (joshuafolkken/kit#4519).
+function details_of(stage: Stage, failed: StoppedOutput = NO_OUTPUT): ReadonlyArray<StopFinding> {
+	if (!is_finding_stop(stage, cause_of(stage, failed))) return []
+
+	return run_ship_review.blocking_details(failed.body)
+}
+
+// The lane ledger's record of one stop — the stage, its cause and, for a preflight, which
+// preconditions were unmet, so `lane:stats` counts the one worth meeting before a ship
+// (joshuafolkken/kit#4166); for a review, which kinds of finding stopped it (joshuafolkken/kit#4426).
+function record_of(issue: number, stage: Stage, failed: StoppedOutput = NO_OUTPUT): StopRecord {
+	const { body, conflicts, preconditions } = failed
+	const cause = cause_of(stage, failed)
+	const findings = findings_of(stage, cause, body)
+
+	return {
+		issue,
+		reason: run_ship_stage.stop_reason(stage, conflicts),
+		cause,
+		...(preconditions !== undefined && { preconditions: [...preconditions] }),
+		...(findings.length > 0 && { findings: [...findings] }),
+	}
+}
+
+const run_ship_stop_cause = { CAUSE, cause_of, details_of, is_review, record_of }
+
+export type { Cause }
+export { run_ship_stop_cause }

package/scripts/run/ship/run-ship-stop-text.ts

@@ -1,15 +1,20 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
 
 // The text a `josh ship` supervisor records when a stage stops, written and read in one place so the
-// retrospective's per-stage count never drifts from the writer.
-const STOP_PATTERN = /^#\d+ (\S+) failed — /u
+// retrospective's per-stage count never drifts from the writer. The cause rides in parentheses after
+// `failed` (`run-ship-stop-cause.ts`); a text written before it had one reads back with none.
+const STOP_PATTERN = /^#\d+ (?<reason>\S+) failed(?: \((?<cause>\S+)\))? — /u
 
-function format(issue: string, reason: string): string {
-	return `${issue_cite.plain(issue)} ${reason} failed — pnpm josh ship --log ${issue}`
+function format(issue: string, reason: string, cause: string): string {
+	return `${issue_cite.plain(issue)} ${reason} failed (${cause}) — pnpm josh ship --log ${issue}`
 }
 
 function reason_of(text: string): string | undefined {
-	return STOP_PATTERN.exec(text)?.[1]
+	return STOP_PATTERN.exec(text)?.groups?.['reason']
 }
 
-export const run_ship_stop_text = { format, reason_of }
+function cause_of(text: string): string | undefined {
+	return STOP_PATTERN.exec(text)?.groups?.['cause']
+}
+
+export const run_ship_stop_text = { format, reason_of, cause_of }

package/scripts/run/ship/run-ship-sync.ts

@@ -6,6 +6,7 @@ import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
 import { run_ship_overlap } from './run-ship-overlap'
 import { run_ship_scoped } from './run-ship-scoped'
+import type { Cause } from './run-ship-stop-cause'
 
 // `josh ship` keeps the branch current with the default branch itself: a default branch that moves
 // while the pull request opens and CI runs would otherwise stop the followup as `interrupted`, though
@@ -29,10 +30,14 @@ const MERGED_PREFIX = 'merged '
 
 // A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
 // `is_skipped` marks a stage that found nothing to do — a review round with nothing to review, a gate
-// that reused a green record — so its few seconds are not timed as a run of it.
+// that reused a green record — so its few seconds are not timed as a run of it. `preconditions` names
+// the kinds of the preconditions a stopped preflight found unmet (`run-ship-preflight.ts`). `cause` is the
+// one a stopped review round tagged its stop with (`run-ship-stop-cause.ts`).
 interface StepResult extends JoshResult {
 	is_skipped?: boolean
 	conflicts?: ReadonlyArray<string>
+	preconditions?: ReadonlyArray<string>
+	cause?: Cause
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
@@ -117,21 +122,53 @@ async function merge_again(title: string, failed: JoshResult): Promise<StepResul
 	return await push_merged(title)
 }
 
-async function followup_stage(
+// Whether the ship waits on the merge alone, for its stage record (`run_ship_stage.mark_merge_waiting`).
+type WaitMark = (is_merge_waiting: boolean) => void
+
+function ignore_wait(): void {
+	// A ship with no stage record has no lane place to free.
+}
+
+// The wait is marked only while `josh followup` runs: the merge again and its gate run unmarked, so a
+// lane gating here still holds its place (joshuafolkken/kit#4466).
+async function marked_followup(
 	title: string,
 	notify: ReadonlyArray<string>,
-	retries = 0,
+	mark: WaitMark,
+): Promise<JoshResult> {
+	mark(true)
+
+	try {
+		return await josh(['followup', title, ...notify])
+	} finally {
+		mark(false)
+	}
+}
+
+async function followup_attempt(
+	title: string,
+	notify: ReadonlyArray<string>,
+	mark: WaitMark,
+	retries: number,
 ): Promise<StepResult> {
-	const result = await josh(['followup', title, ...notify])
+	const result = await marked_followup(title, notify, mark)
 
 	if (result.code === SUCCESS_EXIT_CODE || retries >= MAX_MERGE_RETRIES) return result
 
 	const stop = await merge_again(title, result)
 
-	return stop ?? (await followup_stage(title, notify, retries + 1))
+	return stop ?? (await followup_attempt(title, notify, mark, retries + 1))
+}
+
+async function followup_stage(
+	title: string,
+	notify: ReadonlyArray<string>,
+	mark: WaitMark = ignore_wait,
+): Promise<StepResult> {
+	return await followup_attempt(title, notify, mark, 0)
 }
 
 const run_ship_sync = { CONFLICT_NOTE, MAX_MERGE_RETRIES, followup_stage, sync_stage }
 
-export type { StepResult }
+export type { StepResult, WaitMark }
 export { run_ship_sync }

package/scripts/run/ship/run-ship.ts

@@ -10,6 +10,9 @@
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
 import { run_section, type Section } from '#scripts/run/run-section'
+import { run_tail } from '#scripts/run/run-tail'
+import type { Cause } from './run-ship-stop-cause'
+import type { StepResult } from './run-ship-sync'
 
 const PREFLIGHT_HEADER = '=== preflight ==='
 const PRE_DETACH_HEADER = '=== pre-detach checks ==='
@@ -26,14 +29,38 @@ const STOPPED_PREFIX = 'stopped at: '
 const SKIPPED_BODY = 'skipped — already done'
 
 type ShipSection = Section & {
+	// The stage's standard output alone, the text an infrastructure stop is read on.
+	out?: string
 	// The paths a stopped merge left unmerged, handed to the stop prompt.
 	conflicts?: ReadonlyArray<string>
+	// The kinds of the preconditions a stopped preflight found unmet, recorded with the stop.
+	preconditions?: ReadonlyArray<string>
+	// The cause a stopped review round tagged its stop with, recorded with the stop.
+	cause?: Cause
+}
+
+// A stage's result under its header, carrying the conflicts, the preconditions and the cause only where
+// it has them.
+function section_of(header: string, result: StepResult): ShipSection {
+	const { conflicts, preconditions, cause } = result
+
+	return {
+		header,
+		body: run_tail.section_body(result.out, result.err, result.code),
+		code: result.code,
+		out: result.out,
+		...(conflicts !== undefined && { conflicts }),
+		...(preconditions !== undefined && { preconditions }),
+		...(cause !== undefined && { cause }),
+	}
 }
 
 // The step that stopped the ship, or `undefined` when every executed step was green. Because the
-// composite breaks at the first failure, this is the last section whenever one exists.
+// composite breaks at the first failure, this is the last section whenever one exists. The pre-detach
+// report runs on past a red check and prints the preflight refusal last (joshuafolkken/kit#4478), so
+// the last failed section is the one named.
 function failed_section(sections: ReadonlyArray<ShipSection>): ShipSection | undefined {
-	return sections.find((section) => section.code !== run_section.SUCCESS_EXIT_CODE)
+	return sections.findLast((section) => section.code !== run_section.SUCCESS_EXIT_CODE)
 }
 
 // The executed steps under their headers, closed with the name of the step that stopped the run so the
@@ -64,6 +91,7 @@ const run_ship = {
 	exit_code: run_section.exit_code_of,
 	failed_section,
 	format_report,
+	section_of,
 }
 
 export type { ShipSection }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { backlog_drive_restore } from '#scripts/backlog/backlog-drive-restore'
 import { issue_merged } from '#scripts/issue/issue-merged'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
@@ -49,6 +47,4 @@ async function sweep(): Promise<void> {
 
 const run_tidy_cli = { sweep }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await sweep()
-
 export { run_tidy_cli }

package/scripts/run/tidy/run-tidy-lanes.ts

@@ -3,6 +3,7 @@ import { git_stash } from '#scripts/git/stash/git-stash'
 import { session_cite } from '#scripts/issue/session-cite'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_residents } from '#scripts/lane/lane-residents'
 import { error_text } from '#scripts/lib/error-message'
 import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_tidy, type Outcome, type Verdict } from './run-tidy'
@@ -72,6 +73,8 @@ async function lane_verdict(lane: LaneInfo, hold_path: string): Promise<Verdict>
 async function close(issue: string, hold_path: string): Promise<Verdict> {
 	const outcome = await lane_close.close_lane(issue)
 
+	lane_residents.report(outcome.residents, session_cite.issue(issue))
+
 	if (outcome.kind !== CLOSED_KIND) return run_tidy.keep(INCOMPLETE_REASON)
 
 	run_hold.release_hold(hold_path)

package/scripts/run/tidy/run-tidy-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_tidy_cli } from './run-tidy-cli'
+
+// The `josh run:tidy` entry, kept apart from `run-tidy-cli.ts` because `run:hold` imports that one: a
+// bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186). The sweep takes no arguments and never sets an exit code.
+if (process.argv[1] === fileURLToPath(import.meta.url)) await run_tidy_cli.sweep()