@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/followup/git-pr-followup.ts

@@ -13,6 +13,8 @@ import {
 	type TelegramTaskType,
 } from '#scripts/notify/telegram-notify'
 import { followup_checks_event } from './followup-checks-event'
+import { followup_ci_path } from './followup-ci-path'
+import { followup_coderabbit_retrigger, type Settled } from './followup-coderabbit-retrigger'
 import { followup_coderabbit_wait } from './followup-coderabbit-wait'
 import { git_followup_merged } from './git-followup-merged'
 import { git_followup_pending } from './git-followup-pending'
@@ -123,6 +125,13 @@ interface RunContext {
 	context: TelegramContext
 }
 
+type CompletionSend = () => Promise<void>
+
+interface PreparedNotify {
+	is_recorded: boolean
+	send: CompletionSend
+}
+
 // **The four reads in front of the check wait are issued together**. Not one
 // of them is a wait on anything: the `closes #N` check reads the pull request body, and the
 // notification needs the repository name, the issue title and the pull request URL — four requests
@@ -165,31 +174,33 @@ async function read_run_context(input: {
 // The pending count replaces the project version line: children no longer
 // bump, so the local `package.json` names the previous release rather than what this run ships.
 // A count that could not be read contributes no line at all, rather than a zero nobody measured.
-async function notify_completion(
+//
+// **The body is read here, the send is returned** (#5080): the send goes out beside the merge, but the
+// pending count is read off `origin`'s default branch, and a fetch that landed after the merge would
+// count this pull request under a line that says it is not counted.
+async function completion_sender(
 	context: TelegramContext,
 	skip_notes: ReadonlyArray<string>,
 	is_merge_pending: boolean,
-): Promise<void> {
+): Promise<CompletionSend> {
 	const pending_line = await git_followup_pending.pending_release_line({ is_merge_pending })
 	const lines = pending_line === undefined ? skip_notes : [pending_line, ...skip_notes]
-	const body = lines.join('\n')
+	const input = build_telegram_input({ task_type: 'completion', context, body: lines.join('\n') })
 
-	// **The tolerant send**: this runs on the way to the merge, so a Telegram
-	// gateway timeout must not leave a reviewed, green pull request unmerged. The failure is reported
-	// under `❗` and the run carries on.
+	// **The tolerant send**: this runs beside the merge, so a Telegram gateway timeout must not leave a
+	// reviewed, green pull request unmerged. The failure is reported under `❗` and the run carries on.
 	//
 	// **No recovery line**, deliberately, in the same sense `git_followup_cleanup`'s epic-close step
 	// has none: a completion notification is never re-sent by hand — `pnpm josh notify --task-type
 	// completion` is prohibited because it populates no PR link — and re-running `followup` after the
 	// merge is not a re-send either. Naming either would send the reader somewhere useless.
-	await telegram_notify.send_or_report(
-		build_telegram_input({
-			task_type: 'completion',
-			context,
-			body,
-		}),
-		undefined,
-	)
+	return async function send_completion(): Promise<void> {
+		await telegram_notify.send_or_report(input, undefined)
+	}
+}
+
+async function send_nothing(): Promise<void> {
+	// A completion already on record is not sent again.
 }
 
 // The two comment scans, marked separately from the check wait because they answer a different
@@ -248,14 +259,38 @@ function wait_for_green_of(
 		return await run_checks({
 			branch_name: input.branch_name,
 			is_skip_watch: input.is_skip_watch,
-			observe: followup_coderabbit_wait.both(
+			observe: followup_coderabbit_wait.all(
 				followup_checks_event.observer_of(issue_number, context.pr_url),
 				followup_coderabbit_wait.observer_of(log.coderabbit),
+				followup_ci_path.observer_of(log.ci_path),
 			),
 		})
 	}
 }
 
+// **The `checks-wait` lap ends at the first green**, so the `ci-wait` row holds the checks alone; a
+// rate-limited CodeRabbit retriggered after it is a lap of its own (joshuafolkken/kit#5289).
+async function wait_for_review_green(
+	input: FollowupInput,
+	context: TelegramContext,
+	issue_number: string | undefined,
+	log: StageLog,
+): Promise<Settled<PrStateSnapshot>> {
+	const wait_for_green = wait_for_green_of(input, context, issue_number, log)
+	const checked = await wait_for_green()
+
+	lap(log, STAGE.checks_wait)
+	const settled = await followup_coderabbit_retrigger.settle(
+		checked,
+		wait_for_green,
+		input.branch_name,
+		log.coderabbit,
+	)
+	if (settled.is_retriggered) lap(log, STAGE.coderabbit_retrigger)
+
+	return settled
+}
+
 async function run_review_checks(
 	input: FollowupInput,
 	context: TelegramContext,
@@ -264,13 +299,12 @@ async function run_review_checks(
 ): Promise<ReviewChecks> {
 	if (input.is_merged === true) return { notes: [], managed: [] }
 
+	git_followup_stages.hold_issue(log, issue_number)
 	const managed = await git_pr_managed_config.handle_managed_config_changes({
 		should_merge: input.should_merge,
 	})
-	const snapshot = await wait_for_green_of(input, context, issue_number, log)()
-
-	lap(log, STAGE.checks_wait)
-	const check_notes = read_coderabbit_skip_notes(snapshot)
+	const { snapshot, notes } = await wait_for_review_green(input, context, issue_number, log)
+	const check_notes = [...notes, ...read_coderabbit_skip_notes(snapshot)]
 
 	log_skip_notes(check_notes)
 	const scan_notes = await run_comment_scans(input, context, log)
@@ -280,22 +314,23 @@ async function run_review_checks(
 
 // **A tail re-run after a merge does not report twice**: where the issue
 // already carries this pull request's completion report, the Telegram is skipped here and the comment
-// in the wrapup. Answers whether it was recorded, so the wrapup skips on the same read.
-async function notify_unless_recorded(
+// in the wrapup. Answers whether it was recorded, so the wrapup skips on the same read, and the send
+// the wrapup issues beside the merge.
+async function prepare_notify(
 	input: FollowupInput,
 	issue_number: string | undefined,
 	context: TelegramContext,
 	checks: { notes: Array<string> },
-): Promise<boolean> {
+): Promise<PreparedNotify> {
 	const is_recorded = await git_followup_merged.is_completion_recorded({
 		merged_at: input.is_merged === true ? input.merged_at : undefined,
 		issue_number,
 		pr_url: context.pr_url,
 	})
 
-	if (!is_recorded) await notify_completion(context, checks.notes, input.should_merge)
+	if (is_recorded) return { is_recorded, send: send_nothing }
 
-	return is_recorded
+	return { is_recorded, send: await completion_sender(context, checks.notes, input.should_merge) }
 }
 
 // **Answers with the issue number the run actually used**, which is the one
@@ -308,9 +343,8 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 
 	lap(log, STAGE.closes_and_context)
 	const checks = await run_review_checks(input, context, log, issue_number)
-	const is_completion_recorded = await notify_unless_recorded(input, issue_number, context, checks)
+	const notify = await prepare_notify(input, issue_number, context, checks)
 
-	lap(log, STAGE.telegram)
 	await git_pr_followup_wrapup.run_wrapup(
 		{
 			branch_name: input.branch_name,
@@ -321,7 +355,8 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 			should_merge: input.should_merge,
 			managed_notes: checks.managed,
 			is_merged: input.is_merged,
-			is_completion_recorded,
+			is_completion_recorded: notify.is_recorded,
+			send_completion: notify.send,
 			checked: checks.snapshot,
 			wait_for_green: wait_for_green_of(input, context, issue_number, log),
 		},

package/scripts/fresh-machine/fresh-machine-script.ts

@@ -1,3 +1,4 @@
+import { shell_quote } from '#scripts/lib/shell-quote'
 import type { Scenario } from './fresh-machine-spec'
 
 // The script one container runs. Every command is printed before it runs and its exit status after,
@@ -8,28 +9,23 @@ const SEED_MOUNT = '/seed'
 const PACK_MOUNT = '/pack'
 const COPY_SEED = `cp -R ${SEED_MOUNT}/. .`
 const PROBES_HEADING = '# probes — recorded, never failing the run'
-const ESCAPED_QUOTE = String.raw`'\''`
 const PREAMBLE = [
 	String.raw`step() { printf '\n$ %s\n' "$1"; eval "$1"; local code=$?; printf '[exit %s]\n' "$code"; return "$code"; }`,
 	'mkdir -p "$HOME/$RUN_NAME" && cd "$HOME/$RUN_NAME" || exit 1',
 ]
 
-function quote(command: string): string {
-	const escaped = command.split("'").join(ESCAPED_QUOTE)
-
-	return `'${escaped}'`
-}
+const { single_quoted } = shell_quote
 
 function required(command: string): string {
-	return `step ${quote(command)} || exit $?`
+	return `step ${single_quoted(command)} || exit $?`
 }
 
 function probe_lines(probes: ReadonlyArray<string>): Array<string> {
 	if (probes.length === 0) return []
 
 	return [
-		String.raw`printf '\n%s\n' ${quote(PROBES_HEADING)}`,
-		...probes.map((probe) => `step ${quote(probe)}`),
+		String.raw`printf '\n%s\n' ${single_quoted(PROBES_HEADING)}`,
+		...probes.map((probe) => `step ${single_quoted(probe)}`),
 	]
 }
 

package/scripts/fresh-machine/specs/kit-test-backlogrun-python.json

@@ -27,8 +27,8 @@
 		"tail -n 40 \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\" | cut -c1-400",
 		"grep -c 'requires approval' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
 		"grep -c 'run:carry --begin' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
-		"tail -n 40 /tmp/josh-lane-dispatch-*.log | cut -c1-400",
-		"cat /tmp/josh-lane-dispatch-*.log | grep -c 'requires approval'",
+		"tail -n 40 \"$(git rev-parse --path-format=absolute --git-common-dir)\"/josh/run-state/josh-lane-dispatch-*.log | cut -c1-400",
+		"cat \"$(git rev-parse --path-format=absolute --git-common-dir)\"/josh/run-state/josh-lane-dispatch-*.log | grep -c 'requires approval'",
 		"gh pr list --state all"
 	]
 }

package/scripts/fresh-machine/specs/kit-test-backlogrun.json

@@ -24,8 +24,8 @@
 	"probes": [
 		"tail -n 40 \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\" | cut -c1-400",
 		"grep -c 'requires approval' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
-		"tail -n 40 /tmp/josh-lane-dispatch-*.log | cut -c1-400",
-		"cat /tmp/josh-lane-dispatch-*.log | grep -c 'requires approval'",
+		"tail -n 40 \"$(git rev-parse --path-format=absolute --git-common-dir)\"/josh/run-state/josh-lane-dispatch-*.log | cut -c1-400",
+		"cat \"$(git rev-parse --path-format=absolute --git-common-dir)\"/josh/run-state/josh-lane-dispatch-*.log | grep -c 'requires approval'",
 		"gh pr list --state all"
 	]
 }

package/scripts/gate/busy-average.ts

@@ -52,7 +52,39 @@ function averaged(
 	return { ...reading, busy_cores: ledger_cores + total / samples.length }
 }
 
-const busy_average = { AVERAGE_WINDOW_MS, averaged, with_reading }
+// **A wait that does not ease the load gains nothing by going on** (joshuafolkken/kit#4982). On a
+// saturated machine the load never falls, and a claim that waits out the cap only starts at minimum
+// width two minutes late. A wait keeps the lowest mean busy count it has read and when it last fell; a
+// fall under a whole core is noise, not easing.
+const EASE_CORES = 1
 
-export type { BusySample }
+interface LoadEase {
+	level: number
+	eased_at: number
+}
+
+// `ease` once the mean `busy_cores` read at `now` is added. An unread machine changes nothing, so a wait
+// that cannot read the load is never judged unrelieved.
+function with_ease(
+	ease: LoadEase | undefined,
+	busy_cores: number | undefined,
+	now: number,
+): LoadEase | undefined {
+	if (busy_cores === undefined) return ease
+
+	if (ease === undefined || busy_cores <= ease.level - EASE_CORES) {
+		return { level: busy_cores, eased_at: now }
+	}
+
+	return ease
+}
+
+// Whether the load has not eased for `window_ms` of the wait.
+function is_unrelieved(ease: LoadEase | undefined, now: number, window_ms: number): boolean {
+	return ease !== undefined && now - ease.eased_at >= window_ms
+}
+
+const busy_average = { AVERAGE_WINDOW_MS, averaged, is_unrelieved, with_ease, with_reading }
+
+export type { BusySample, LoadEase }
 export { busy_average }

package/scripts/gate/check-related-pinned.ts

@@ -0,0 +1,43 @@
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { run_review_pinned_accepted } from '#scripts/run/review/run-review-pinned-accepted'
+import { run_review_pinned_join } from '#scripts/run/review/run-review-pinned-join'
+import { test_pinned_logic } from '#scripts/test/test-pinned-logic'
+import type { PinnedSummary } from '#scripts/test/test-pinned-record'
+
+// **`check:related` prints the `josh test:pinned` verdict it finds already reached on this tree**
+// (joshuafolkken/kit#4971): read only by the ship's pre-detach, it stopped the first `josh ship` on
+// unpinned places, and the ship ran its preflight and pre-detach again once the reason was added.
+// **A check this run started is waited on** (joshuafolkken/kit#4987): one still probing when the four
+// checks ended printed nothing, and the ship stopped on it again. One it did not start is read as it
+// stands, and one on another tree prints nothing here.
+
+const SHIP_HINT =
+	'Pin each unpinned place above with a test that turns red without it, or give the first ship its reason: `pnpm josh ship "<title> #<N>" --review … --unpinned-ok "<reason>"`.'
+// The wait's bound keeps the four checks plus it under a foreground Bash call's 600-second cap, so the
+// verdict line is never cut off; a check past it is left running for the ship's pre-detach.
+const WAIT_MS = 240_000
+
+async function reached(root: string, is_started: boolean): Promise<PinnedSummary | undefined> {
+	if (is_started) return await run_review_pinned_join.settled_on_tree(root, WAIT_MS)
+
+	return await run_review_pinned_join.finished_on_tree(root)
+}
+
+// The unpinned places the ship's pre-detach would stop on, with the `--unpinned-ok` form;
+// `undefined` when no answer is reached on this tree or it stops nothing.
+async function notice(
+	root: string = PROJECT_ROOT,
+	is_started = false,
+): Promise<string | undefined> {
+	const summary = await reached(root, is_started)
+	if (summary === undefined) return undefined
+	const verdict = await run_review_pinned_accepted.judge(summary, undefined)
+
+	if (verdict.kind !== 'stop') return undefined
+
+	return test_pinned_logic.report_text(summary, `${SHIP_HINT}\n`).trimEnd()
+}
+
+const check_related_pinned = { SHIP_HINT, WAIT_MS, notice }
+
+export { check_related_pinned }

package/scripts/gate/check-related-reuse.ts

@@ -0,0 +1,64 @@
+import type { CheckResult } from './check-related'
+import { check_reuse, type CheckRecords } from './check-reuse'
+import { gate_labels } from './gate-labels'
+import type { GateStepResult } from './gate-report'
+import { gate_tree, type GateTree } from './gate-tree'
+import { scoped_green } from './scoped-green'
+
+// **`check:related` runs only the checks whose green record no longer holds** (joshuafolkken/kit#5156):
+// a re-run after fixing one failure ran the three that had passed over again, minutes of a hub-file
+// `test:related` among them. No record is new here. `lint:related` and `test:related` write their own
+// scoped records (`scoped-green.ts`); the type check and cspell read and write the gate's per-check
+// records under the gate's labels (`check-reuse.ts`), so a green from either end serves the other. A
+// failed check writes no record, so it runs again.
+
+const GATE_LABELS: ReadonlyMap<string, string> = new Map([
+	[gate_labels.TYPE_CHECK_TARGET, gate_labels.TYPE_CHECK_LABEL],
+	[gate_labels.SPELL_CHECK_TARGET, gate_labels.SPELL_CHECK_LABEL],
+])
+
+const UNREAD_TREE: GateTree = { files: {}, base: undefined }
+
+function gate_label(command: string): string {
+	return GATE_LABELS.get(command) ?? ''
+}
+
+// The commands of `commands` whose green record still describes `tree`.
+async function reusable(
+	commands: ReadonlyArray<string>,
+	tree: GateTree,
+	records: CheckRecords = check_reuse.DEFAULT_RECORDS,
+): Promise<ReadonlySet<string>> {
+	const scoped = new Set(scoped_green.green_scripts(tree.files, tree.base))
+	const gate = await check_reuse.reusable_checks([...GATE_LABELS.values()], tree, records)
+
+	return new Set(commands.filter((command) => scoped.has(command) || gate.has(gate_label(command))))
+}
+
+function gate_results(results: ReadonlyArray<CheckResult>): Array<GateStepResult> {
+	return results
+		.filter((result) => GATE_LABELS.has(result.command))
+		.map((result) => ({ ...result, label: gate_label(result.command), elapsed_ms: 0 }))
+}
+
+// Records the green type check and cspell against `tree`, the tree read before they started.
+async function record(
+	results: ReadonlyArray<CheckResult>,
+	tree: GateTree,
+	records: CheckRecords = check_reuse.DEFAULT_RECORDS,
+): Promise<void> {
+	await check_reuse.record_green_checks(gate_results(results), tree, records)
+}
+
+// A tree git could not read is one with no answer, so nothing is reused and every check runs.
+async function read_tree(): Promise<GateTree> {
+	try {
+		return await gate_tree.read_gate_tree()
+	} catch {
+		return UNREAD_TREE
+	}
+}
+
+const check_related_reuse = { UNREAD_TREE, read_tree, record, reusable }
+
+export { check_related_reuse }

package/scripts/gate/check-related-section.ts

@@ -0,0 +1,57 @@
+// **Each check prints only its last lines; its whole output is in the log** (joshuafolkken/kit#5204).
+// A `test:related` over hundreds of files printed past 140 KB, past the tool result's size limit, and
+// the run typed the same `check:related` again behind a `grep` only to read the verdict. The end of a
+// section is where a check's own verdict and its failures land, so a passed check keeps its last 5
+// lines and a failed one its last 40; `--full` prints the whole output as before.
+
+const PASSED_TAIL_LINES = 5
+const FAILED_TAIL_LINES = 40
+const FULL_FLAG = '--full'
+
+interface CheckResult {
+	command: string
+	exit_code: number
+	output: string
+}
+
+function result_status(result: CheckResult): string {
+	return result.exit_code === 0 ? 'passed' : `failed (${String(result.exit_code)})`
+}
+
+function tail_lines(result: CheckResult): ReadonlyArray<string> {
+	const lines = result.output.trimEnd().split('\n')
+	const count = result.exit_code === 0 ? PASSED_TAIL_LINES : FAILED_TAIL_LINES
+	const dropped = lines.length - count
+
+	if (dropped <= 0) return lines
+
+	return [`… ${String(dropped)} earlier line(s) in the log`, ...lines.slice(-count)]
+}
+
+function section_body(result: CheckResult, is_full: boolean): string {
+	if (is_full) return result.output.endsWith('\n') ? result.output : `${result.output}\n`
+
+	return `${tail_lines(result).join('\n')}\n`
+}
+
+function format_section(result: CheckResult, is_full = false): string {
+	const header = `\n=== ${result.command}: ${result_status(result)} ===\n`
+
+	if (result.output.length === 0) return header
+
+	return `${header}${section_body(result, is_full)}`
+}
+
+function is_full_requested(arguments_: ReadonlyArray<string>): boolean {
+	return arguments_.includes(FULL_FLAG)
+}
+
+const check_related_section = {
+	FAILED_TAIL_LINES,
+	format_section,
+	is_full_requested,
+	result_status,
+}
+
+export type { CheckResult }
+export { check_related_section }

package/scripts/gate/check-related-unplanned.ts

@@ -0,0 +1,34 @@
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { error_text } from '#scripts/lib/error-message'
+import { run_ship_planned, type Unplanned } from '#scripts/run/ship/run-ship-planned'
+
+// **`check:related` prints the ship's `unplanned` answer ahead of the ship** (joshuafolkken/kit#5203):
+// asked only by the ship's preflight, a lane learned of a code file its `lane:plan` record never listed
+// after the review and its fixes, and spent the re-plan and a second ship on it. The judgment is the
+// preflight's own (`run-ship-planned.ts`); this run never stops on it — the preflight still does. Each
+// notice printed is recorded, so `lane:stats` tells a preflight `unplanned` stop that came after one apart.
+
+// A git read that fails here prints nothing rather than the run's verdict lost — the preflight still
+// asks it, and reports an unreadable read as its own precondition.
+async function read_unplanned(): Promise<Unplanned | undefined> {
+	try {
+		return await run_ship_planned.unplanned()
+	} catch (error) {
+		error_text.trace_swallowed('check_related_unplanned.notice', error)
+
+		return undefined
+	}
+}
+
+async function notice(): Promise<string | undefined> {
+	const found = await read_unplanned()
+
+	if (found === undefined) return undefined
+	await lane_ledger_write.record_unplanned_notice({ issue: found.issue, files: [...found.files] })
+
+	return found.text
+}
+
+const check_related_unplanned = { notice }
+
+export { check_related_unplanned }