@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/scripts/review/review-comment-round.ts

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs'
+import { gh_author_association } from '#scripts/gh/gh-author-association'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { parse_json, parse_json_array_safe } from '#scripts/git/parse-json-array'
+import { session_cite } from '#scripts/issue/session-cite'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { z } from 'zod'
+import { review_finding_ledger } from './review-finding-ledger'
+
+// A review round recorded after its pull request opened (`josh review:record --comment`), and how its
+// lines reach the ledger's readers (joshuafolkken/kit#3811). The round is posted on the issue because
+// a ledger line written then would be pushed onto the open pull request and restart its CI — and so
+// nothing that reads the ledger (`review:findings`, the retrospective) ever saw it.
+//
+// **The next run that records a round carries it.** Once an issue is closed no round is added to it,
+// so `review:record` copies each closed issue's comment rounds not yet carried into
+// `<issue>-comment-rounds.md` in the ledger, and the lines ride that run's own commit: the ledger stays
+// the one place a reader looks, and no push restarts any CI. **The file is the carried mark** — an
+// issue whose file exists is never read again, and two lanes carrying one issue write the same file,
+// so their pull requests merge to the same lines.
+
+const COMMENT_HEADING_MARK = '### '
+const COMMENT_TITLE = 'Review round recorded after the pull request opened'
+const COMMENT_HEADING = `${COMMENT_HEADING_MARK}${COMMENT_TITLE}`
+const COMMENT_NOTE =
+	'Kept here rather than in the observation ledger: a line appended after the commit would be pushed onto the open pull request and restart its CI.'
+const CODE_FENCE = '```'
+const CARRIED_SUFFIX = '-comment-rounds'
+// One page of the newest closed issues: an issue leaves the search's interest once carried, so the
+// ones still to carry are the recently closed.
+const PER_PAGE = '100'
+const UNNAMED_REPOSITORY = 'Could not name this repository from `git remote`.'
+const UNREAD_SEARCH = 'Could not read the search for closed issues with a comment round.'
+const UNREAD_COMMENTS = 'Could not read the comments of'
+
+const search_item_schema = z.object({ number: z.number() })
+const search_schema = z.object({ items: z.array(search_item_schema) })
+const comment_schema = z.object({
+	body: z.string().nullish(),
+	author_association: z.string().nullish(),
+})
+
+type IssueComment = z.infer<typeof comment_schema>
+
+function body_of(lines: ReadonlyArray<string>): string {
+	return [COMMENT_HEADING, '', COMMENT_NOTE, '', CODE_FENCE, ...lines, CODE_FENCE].join('\n')
+}
+
+// The ledger lines of every comment round among one issue's comments, oldest first; any other
+// comment, one that only quotes the heading among them, carries none — nor does one whose author
+// cannot write to the repository: anyone can comment on a public issue, and the carried lines ride
+// the run's commit unreviewed.
+function lines_of(comments: ReadonlyArray<IssueComment>): Array<string> {
+	return comments
+		.filter((comment) => gh_author_association.is_trusted(comment.author_association))
+		.map((comment) => comment.body ?? '')
+		.filter((body) => body.startsWith(COMMENT_HEADING))
+		.flatMap((body) => body.split('\n'))
+		.filter((line) => review_finding_ledger.is_finding_line(line))
+}
+
+function search_path(repo: string): string {
+	const query = `repo:${repo} is:issue is:closed in:comments "${COMMENT_TITLE}"`
+	const parameters = new URLSearchParams({ q: query, sort: 'updated', per_page: PER_PAGE })
+
+	return `search/issues?${parameters.toString()}`
+}
+
+// The closed issues whose comments name a comment round; a repository that cannot be named or a
+// search that cannot be read throws, so the run says so rather than carrying nothing in silence.
+async function closed_issues(): Promise<ReadonlyArray<number>> {
+	const repo = session_cite.session_repo()
+
+	if (repo === undefined) throw new Error(UNNAMED_REPOSITORY)
+
+	const raw = await git_gh_exec.exec_gh_api({ path: search_path(repo) })
+	const page = parse_json.parse_json_object_or_undefined(raw, search_schema)
+
+	if (page === undefined) throw new Error(UNREAD_SEARCH)
+
+	return page.items.map((item) => item.number)
+}
+
+function carried_path(issue: number, root: string): string {
+	return observation_ledger_home.file_path(`${String(issue)}${CARRIED_SUFFIX}`, root)
+}
+
+// An issue whose comments could not be read writes no file, so the next run reads it again, and
+// throws so this one says so.
+async function carry_issue(issue: number, root: string): Promise<number> {
+	const raw = await git_gh_issue_read.issue_list_comments(String(issue))
+
+	if (raw === undefined) throw new Error(`${UNREAD_COMMENTS} ${session_cite.issue(issue)}`)
+
+	const lines = lines_of(parse_json_array_safe(raw, comment_schema))
+
+	await observation_ledger_home.append(carried_path(issue, root), lines)
+
+	return lines.length
+}
+
+// Copies every closed issue's comment rounds not yet in the ledger, and answers how many lines.
+async function carry(root: string): Promise<number> {
+	const issues = await closed_issues()
+	const pending = issues.filter((issue) => !existsSync(carried_path(issue, root)))
+	const counts = await Promise.all(pending.map(async (issue) => await carry_issue(issue, root)))
+
+	return counts.reduce((total, count) => total + count, 0)
+}
+
+const review_comment_round = { body_of, carried_path, carry, lines_of }
+
+export { review_comment_round }

package/scripts/review/review-record-cli.ts

@@ -4,6 +4,7 @@ import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { review_comment_round } from './review-comment-round'
 import { review_finding_ledger, type Finding } from './review-finding-ledger'
 import { review_record, type RecordVerdict } from './review-record'
 
@@ -16,7 +17,8 @@ import { review_record, type RecordVerdict } from './review-record'
 // **`--comment` records a round that ran after the pull request opened**: the same lines go to the
 // issue as a comment and nothing is appended. A line written to the tree then has no commit of the
 // run's left to ride, so `pnpm josh followup` would push it onto the open pull request and its CI
-// would start over.
+// would start over. The next round recorded to the ledger carries it there once the issue is closed
+// (`review-comment-round.ts`).
 //
 // `josh review:record --check --issue <N>` is the read half `pnpm josh followup` runs before it
 // merges: `ok` / `not-required` exit zero, `missing` exits non-zero so the
@@ -31,10 +33,10 @@ const CHECK_USAGE = 'Usage: josh review:record --check --issue <N>'
 const RECORDED_LINE = 'Recorded: the review round for this issue is in the ledger.'
 const NOT_REQUIRED_LINE =
 	'No review-finding ledger is kept in this checkout, so there is nothing to check.'
-const COMMENT_HEADING = '### Review round recorded after the pull request opened'
-const COMMENT_NOTE =
-	'Kept here rather than in the observation ledger: a line appended after the commit would be pushed onto the open pull request and restart its CI.'
-const CODE_FENCE = '```'
+const CARRIED_LINE =
+	'review-finding line(s) recorded on closed issues after their pull requests opened into the ledger.'
+const CARRY_FAILED_LINE =
+	'Could not carry the closed issues’ comment rounds into the ledger; the next round retries:'
 const OPTIONS = {
 	issue: { type: 'string' },
 	check: { type: 'boolean' },
@@ -161,15 +163,14 @@ async function run_check(issue: string | undefined, root: string): Promise<numbe
 	return FAILURE_EXIT_CODE
 }
 
-function comment_body(lines: ReadonlyArray<string>): string {
-	return [COMMENT_HEADING, '', COMMENT_NOTE, '', CODE_FENCE, ...lines, CODE_FENCE].join('\n')
-}
-
 // **A comment that could not be posted fails the record**: it is the round's only copy, so a
 // swallowed refusal would read as a recorded round that exists nowhere.
 async function post_comment(issue: number, lines: ReadonlyArray<string>): Promise<number> {
 	try {
-		const url = await git_gh_issue_write.issue_comment(String(issue), comment_body(lines))
+		const url = await git_gh_issue_write.issue_comment(
+			String(issue),
+			review_comment_round.body_of(lines),
+		)
 
 		console.info(`Recorded ${String(lines.length)} review-finding line(s) in ${url.trim()}.`)
 
@@ -181,8 +182,35 @@ async function post_comment(issue: number, lines: ReadonlyArray<string>): Promis
 	}
 }
 
+// The closed issues' comment rounds ride this round's commit (`review-comment-round.ts`). **A carry
+// that fails never fails the record**: this round is recorded, and the comment rounds wait for the
+// next run's.
+async function carry_comment_rounds(root: string): Promise<void> {
+	try {
+		const count = await review_comment_round.carry(root)
+
+		if (count > 0) console.info(`Carried ${String(count)} ${CARRIED_LINE}`)
+	} catch (error) {
+		console.warn(`${CARRY_FAILED_LINE} ${error instanceof Error ? error.message : String(error)}`)
+	}
+}
+
 // The round lands in its own issue's file, so two lanes recording at once
 // write two files, and their pull requests never conflict on the ledger.
+async function append_round(
+	issue: number,
+	lines: ReadonlyArray<string>,
+	root: string,
+): Promise<number> {
+	const ledger_path = observation_ledger_home.issue_path(issue, root)
+
+	await observation_ledger_home.append(ledger_path, lines)
+	console.info(confirmation(lines.length, ledger_path))
+	await carry_comment_rounds(root)
+
+	return 0
+}
+
 async function run_record(parsed: Parsed, now: Date, root: string): Promise<number> {
 	const request = to_request(parsed)
 
@@ -196,12 +224,7 @@ async function run_record(parsed: Parsed, now: Date, root: string): Promise<numb
 
 	if (parsed.comment) return await post_comment(request.issue, lines)
 
-	const ledger_path = observation_ledger_home.issue_path(request.issue, root)
-
-	await observation_ledger_home.append(ledger_path, lines)
-	console.info(confirmation(lines.length, ledger_path))
-
-	return 0
+	return await append_round(request.issue, lines, root)
 }
 
 // **The default is the work tree the command runs in, a lane's inside a lane**.
@@ -232,7 +255,6 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const review_record_cli = {
 	accepted_values,
 	build_lines,
-	comment_body,
 	parse_finding,
 	run,
 	usage_text,

package/scripts/rules/implementation-cut.ts

@@ -176,9 +176,9 @@ const IMPLEMENTATION_CUT_REASON =
 	'because the verdict was only ever read at session entry, where the context has not yet grown. The ' +
 	"verdict is `pnpm josh cost --cut`'s exactly — the same per-request billed-input statistic against the " +
 	'same threshold, never a second measurement. Issue `pnpm josh run:cut --impl <N> --handoff <path>` now and read the ' +
-	'verdict: on `cut`, **end the turn immediately** — in a lane the fresh process owns the run and ' +
-	'continues implementing, so it must not be waited for; outside a lane nothing is relaunched, so first ' +
-	'send the `confirmation` Telegram naming the resume command `fullrun #<N>` and keep the hold; on `not-a-lane`, `unready`, `busy`, `failed` or ' +
+	'verdict: on `cut`, read what the command printed. Where it relaunched a fresh process, **end the turn ' +
+	'immediately** — that process owns the run and continues implementing, so it must not be waited for, ' +
+	'and **no Telegram is owed**: a cut that resumes itself leaves a person nothing to act on. Where it printed that nothing was relaunched, do what it prints, then end the turn; on `not-a-lane`, `unready`, `busy`, `failed` or ' +
 	'`unknown`, this process carries the run on and the edit is simply the next call. Never relaunch a ' +
 	'second process after `busy`. This fired because the dispatch mark names this lane or the run hold ' +
 	'names this issue; a person working here carries no mark and holds no run, so sees no refusal, so there is no human-or-child judgement left to make. The ' +

package/scripts/rules/pre-gate-cut.ts

@@ -172,7 +172,7 @@ const PRE_GATE_CUT_REASON =
 	'176K of 204K output riding across that boundary, and joshuafolkken/kit#1864 measured the step ' +
 	'itself firing 0 times in 6 lane children while it was carried as prose. Issue ' +
 	'`pnpm josh run:cut <N>` now, and read the verdict: on `cut`, **end the turn immediately** — the ' +
-	'fresh process owns the run from there and must not be waited for; on `not-a-lane`, `unready`, ' +
+	'fresh process owns the run from there and must not be waited for, and **no Telegram is owed** for a cut that resumes itself; on `not-a-lane`, `unready`, ' +
 	'`busy`, `failed` or `unknown`, this process carries the run on and the gate is simply the next ' +
 	'call. Never relaunch a second process after `busy`. This fired because the dispatch mark names ' +
 	'this lane; a person working here carries no mark and sees no refusal, so there is no ' +

package/scripts/run/board/run-board-checks.ts

@@ -0,0 +1,42 @@
+import { run_event_checks, type PrChecks } from '#scripts/run/event/run-event-checks'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+
+// Each child's newest `pr-checks` line — its pull request's CI counts and CodeRabbit's state as
+// `josh followup` last polled them (joshuafolkken/kit#3770). Read from the stream alone, so a redraw
+// asks GitHub nothing.
+
+interface HeldChecks {
+	checks: PrChecks
+	at_ms: number
+}
+
+const { PR_CHECKS } = run_event_stream.EVENT_KIND
+
+function held_of(event: RunEvent): HeldChecks | undefined {
+	const checks = event.kind === PR_CHECKS ? run_event_checks.checks_of(event.text) : undefined
+
+	return checks === undefined ? undefined : { checks, at_ms: Date.parse(event.at) }
+}
+
+// The stream's bound reorders its lines, so the newest is the latest `at`, not the last line.
+function is_newer(held: HeldChecks, current: HeldChecks | undefined): boolean {
+	return current === undefined || held.at_ms >= current.at_ms
+}
+
+function newest_of(events: ReadonlyArray<RunEvent>): ReadonlyMap<number, PrChecks> {
+	const newest = new Map<number, HeldChecks>()
+
+	for (const event of events) {
+		const held = held_of(event)
+		const issue = Number(run_event_scope.issue_named(event))
+
+		if (held !== undefined && is_newer(held, newest.get(issue))) newest.set(issue, held)
+	}
+
+	return new Map([...newest].map(([issue, held]) => [issue, held.checks]))
+}
+
+const run_board_checks = { newest_of }
+
+export { run_board_checks }

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

@@ -15,6 +15,7 @@ import { run_board_read } from './run-board-read'
 import { run_board_screen, type Screen } from './run-board-screen'
 import { run_board_spin } from './run-board-spin'
 import type { BoardPorts } from './run-board-state'
+import { run_board_thanks_read } from './run-board-thanks-read'
 import { run_board_tick } from './run-board-tick'
 import { run_board_usage_read } from './run-board-usage-read'
 
@@ -52,6 +53,7 @@ const LIVE_PORTS: BoardPorts = {
 	read_machine: machine_capacity.read_sample,
 	read_usage: run_board_usage_read.usage_reader(),
 	read_closed: async (issues) => await run_board_closed.read_all(issues),
+	read_thanks: async () => await run_board_thanks_read.read_thanks(),
 	now: () => Date.now(),
 	write: (frame) => process.stdout.write(frame),
 	// No fallback: a terminal that opens no link, or a pipe, gets the bare number rather than a URL.

package/scripts/run/board/run-board-every.ts

@@ -15,7 +15,8 @@ interface ChatFrame {
 	local: LocalRead | undefined
 }
 
-// One frame in the chat's form, with every escape stripped because a chat shows them as text.
+// One frame in the chat's form, with every escape stripped because a chat shows them as text. The
+// reviewers are thanked on the terminal's board alone, so the chat reads no roster.
 async function chat_frame(ports: BoardPorts): Promise<ChatFrame> {
 	let text = ''
 	const chat_ports: BoardPorts = {
@@ -23,6 +24,7 @@ async function chat_frame(ports: BoardPorts): Promise<ChatFrame> {
 		is_tty: false,
 		size: undefined,
 		form: 'chat',
+		read_thanks: undefined,
 		write: (frame) => {
 			text += stripVTControlCharacters(frame)
 		},

package/scripts/run/board/run-board-fit.ts

@@ -5,14 +5,17 @@ import { run_board_labels } from './run-board-labels'
 // A live `run:board` frame kept within the terminal. A frame taller than the pane scrolls the
 // alternate screen as it is written, and the header — the lines that say whether the run moves and
 // how far it is — is what scrolls off. So the parts below it give way instead, least wanted first:
-// the footer, the legend, the finished rows, the notes, the rows not yet started, the parked rows
-// and, last, the running rows — what a person keeps the board open to see. Each stage stops once the
+// the footer, the legend, the oldest notes until three are left, the finished rows, the rest of the
+// notes, the reviewers thanked above the legend, the rows not yet started, the parked rows and, last,
+// the running rows — what a person keeps the board open to see. Each stage stops once the
 // frame fits, a cut row is counted on its section's `more N` line, and the order a row is drawn in
 // never changes. A line wider than the pane wraps, so every line is counted by the rows it takes on
 // screen, not as one.
 
 const { WORDS } = run_board_labels
 const INDENT = '  '
+// The newest notes kept until the finished rows are gone; the older ones give way before them.
+const NOTES_KEPT = 3
 
 interface TerminalSize {
 	rows: number
@@ -52,21 +55,24 @@ interface FrameParts {
 	above: ReadonlyArray<string>
 	plan: ReadonlyArray<PlanSection>
 	notes: NotesPart
+	// The reviewers thanked, drawn right above the legend; none where nobody is.
+	thanks?: ReadonlyArray<string> | undefined
 	legend: ReadonlyArray<string>
 	footer: ReadonlyArray<string>
 }
 
 // One thing that gives way: a part as a whole, one note (the oldest shown), or one issue row.
-type Yielder = 'footer' | 'legend' | 'note' | PlanLine
+type Yielder = 'thanks' | 'footer' | 'legend' | 'note' | PlanLine
 
 interface Cut {
+	thanks: boolean
 	footer: boolean
 	legend: boolean
 	notes: number
 	rows: ReadonlySet<PlanLine>
 }
 
-const NO_CUT: Cut = { footer: false, legend: false, notes: 0, rows: new Set() }
+const NO_CUT: Cut = { thanks: false, footer: false, legend: false, notes: 0, rows: new Set() }
 
 // The columns a line takes on screen: its color escapes take none, an emoji two.
 function width_of(line: string): number {
@@ -117,6 +123,7 @@ function compose(parts: FrameParts, cut: Cut): Array<string> {
 		...parts.above,
 		...plan_lines(parts.plan, cut.rows),
 		...notes_lines(parts.notes, cut.notes),
+		...(cut.thanks ? [] : (parts.thanks ?? [])),
 		...(cut.legend ? [] : parts.legend),
 		...(cut.footer ? [] : parts.footer),
 	]
@@ -154,12 +161,15 @@ function order_of(parts: FrameParts): Array<Yielder> {
 		.map((line, index) => ({ line, index }))
 		.filter((entry) => entry.line.row !== undefined)
 	const notes = parts.notes.lines.map((): Yielder => 'note')
+	const surplus = Math.max(0, notes.length - NOTES_KEPT)
 
 	return [
 		'footer',
 		'legend',
+		...notes.slice(0, surplus),
 		...yielding(rows, 'finished'),
-		...notes,
+		...notes.slice(surplus),
+		'thanks',
 		...yielding(rows, 'pending'),
 		...yielding(rows, 'parked'),
 		...yielding(rows, 'running'),
@@ -175,6 +185,7 @@ function cut_of(order: ReadonlyArray<Yielder>, count: number): Cut {
 	const gone = order.slice(0, count)
 
 	return {
+		thanks: gone.includes('thanks'),
 		footer: gone.includes('footer'),
 		legend: gone.includes('legend'),
 		notes: gone.filter((item) => item === 'note').length,

package/scripts/run/board/run-board-fresh.ts

@@ -0,0 +1,64 @@
+import { styleText } from 'node:util'
+import { run_progress } from '#scripts/run/progress/run-progress'
+
+// **The one place a freshly updated part of `run:board` is emphasized** — the header's `💓` and third
+// line, an issue row's phase, start and end (joshuafolkken/kit#3784). The emphasis fades in three
+// one-second stages, decided by the part's age alone, so no frame remembers the one before it. Only a
+// live screen draws it: a chat, a `--once` frame or a pipe gets the text as it is.
+
+type FreshStage = 'inverse' | 'bold-color' | 'bold' | 'none'
+
+type TextFormat = Parameters<typeof styleText>[0]
+
+// What decides whether a frame emphasizes at all: a screen frame with a spinner is a live terminal.
+interface FreshFrame {
+	now_ms: number
+	form: 'screen' | 'chat'
+	spinner: string | undefined
+}
+
+const STAGE_MS = run_progress.MS_PER_SECOND
+const FADING: ReadonlyArray<FreshStage> = ['inverse', 'bold-color', 'bold']
+const FORMATS: Readonly<Record<Exclude<FreshStage, 'none'>, TextFormat>> = {
+	inverse: 'inverse',
+	'bold-color': ['bold', 'cyan'],
+	bold: 'bold',
+}
+
+// The stage a part `age_ms` old is drawn in; an unknown or a future age is never emphasized.
+function stage_of(age_ms: number | undefined): FreshStage {
+	if (age_ms === undefined || age_ms < 0) return 'none'
+
+	return FADING[Math.floor(age_ms / STAGE_MS)] ?? 'none'
+}
+
+function paint(text: string, stage: FreshStage): string {
+	if (stage === 'none' || text === '') return text
+
+	return styleText(FORMATS[stage], text)
+}
+
+function is_live(frame: FreshFrame): boolean {
+	return frame.form === 'screen' && frame.spinner !== undefined
+}
+
+// `text` emphasized as a part `age_ms` old, where the frame is a live screen.
+function aged(text: string, age_ms: number | undefined, frame: FreshFrame): string {
+	return is_live(frame) ? paint(text, stage_of(age_ms)) : text
+}
+
+// `text` emphasized as a part that changed at `at_ms`.
+function since(text: string, at_ms: number | undefined, frame: FreshFrame): string {
+	return aged(text, at_ms === undefined ? undefined : frame.now_ms - at_ms, frame)
+}
+
+// `text` right-aligned to `width` with only the text emphasized, never the blanks before it, so the
+// column keeps its width and an inverse stage does not light up the padding.
+function padded(text: string, width: number, emphasized: string): string {
+	return `${' '.repeat(Math.max(0, width - text.length))}${emphasized}`
+}
+
+const run_board_fresh = { aged, padded, paint, since, stage_of }
+
+export { run_board_fresh }
+export type { FreshFrame, FreshStage }