@joshuafolkken/kit 1.1240.0 → 1.1370.0

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

@@ -0,0 +1,66 @@
+import type { CarryRead } from '#scripts/run/carry/run-carry'
+import type { EndedRun } from '#scripts/run/carry/run-carry-ended'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+
+// Which run `run:board` draws: the running one while its carry record is here,
+// else the one `run:carry --end` last ended, kept on screen until the next run begins. Both ends of the
+// span come from a record — the carry's start, the ended run's start and end — never from the screen.
+
+// One run to draw. `ended_ms` is set only for a run that has ended.
+interface BoardSpan {
+	invocation: string
+	started_ms: number
+	ended_ms: number | undefined
+}
+
+const { moment_of } = run_event_scope
+
+function ended_span(ended: EndedRun | undefined): BoardSpan | undefined {
+	if (ended === undefined) return undefined
+
+	const started_ms = moment_of(ended.started_at)
+	const ended_ms = moment_of(ended.ended_at)
+
+	if (started_ms === undefined || ended_ms === undefined) return undefined
+
+	return { invocation: ended.invocation, started_ms, ended_ms }
+}
+
+// The running run wins over the ended one, so a run that begins replaces the finished board at once.
+// An expired carry is still the running run's budget spent, not a run that ended, so it draws nothing.
+function span_of(read: CarryRead, ended: EndedRun | undefined): BoardSpan | undefined {
+	if (read.kind !== 'carried') return read.kind === 'none' ? ended_span(ended) : undefined
+
+	const started_ms = moment_of(read.carry.started_at)
+
+	if (started_ms === undefined) return undefined
+
+	return { invocation: read.carry.invocation, started_ms, ended_ms: undefined }
+}
+
+// The session a person resumes a stopped run from: only while the ended run is
+// the one drawn, and only when it stopped rather than finished. A run that begins hides it at once.
+function resume_of(read: CarryRead, ended: EndedRun | undefined): string | undefined {
+	if (read.kind !== 'none' || ended?.stopped === undefined) return undefined
+
+	return ended.session
+}
+
+function is_within(event: RunEvent, span: BoardSpan): boolean {
+	const at = moment_of(event.at)
+
+	if (at === undefined || at < span.started_ms) return false
+
+	return span.ended_ms === undefined || at <= span.ended_ms
+}
+
+// The events inside the span: a later run's events never land on an ended run's board.
+function events_of(events: ReadonlyArray<RunEvent>, span: BoardSpan): ReadonlyArray<RunEvent> {
+	return events.filter((event) => is_within(event, span))
+}
+
+const run_board_span = { events_of, resume_of, span_of }
+
+export { run_board_span }
+export type { BoardSpan }

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

@@ -0,0 +1,115 @@
+import { stripVTControlCharacters } from 'node:util'
+import { run_progress } from '#scripts/run/progress/run-progress'
+import string_width from 'string-width'
+import { run_board_fit, type TerminalSize } from './run-board-fit'
+import { run_board_labels } from './run-board-labels'
+import type { BoardPorts } from './run-board-state'
+
+// The spinners of a live `run:board` frame turned between redraws. The frame
+// is redrawn once a second, on the second, and between redraws only the spinners' own cells are written
+// at the package's interval: a cursor move and one character each, with no read, layout or render. The
+// renderer draws a placeholder where a spinner goes, and each placeholder's place on screen — its row
+// after the lines above it wrap, its column by display width — is recorded as the frame is written. A
+// row the frame was cut to the terminal's rows without is not on screen, so it records nothing.
+
+// A private-use character one column wide, as a spinner frame is, so the frame is fitted the same.
+const SPOT = '\u{E000}'
+const REDRAW_MS = run_progress.MS_PER_SECOND
+const CSI = '\u{1B}['
+const RESET = `${CSI}0m`
+// eslint-disable-next-line no-control-regex -- the color escapes a spot keeps are control characters
+const SGR = /\u{1B}\[[\d;]*m/gu
+const { SPINNER_INTERVAL_MS, spinner_of } = run_board_labels
+
+// Where one spinner is on screen, 1-based, and the colors in effect where it is drawn.
+interface Spot {
+	row: number
+	column: number
+	style: string
+}
+
+interface Spun {
+	lines: Array<string>
+	spots: Array<Spot>
+}
+
+type SpinPorts = Pick<BoardPorts, 'now' | 'sleep' | 'write'>
+
+// The spot of the placeholder at `index` in a line that starts `row` rows down the screen.
+function spot_at(line: string, index: number, row: number, columns: number): Spot {
+	const before = line.slice(0, index)
+	const width = string_width(stripVTControlCharacters(before))
+	const style = (before.match(SGR) ?? []).join('')
+
+	return { row: row + Math.floor(width / columns), column: (width % columns) + 1, style }
+}
+
+function line_spots(line: string, row: number, columns: number): Array<Spot> {
+	return [...line.matchAll(new RegExp(SPOT, 'gu'))].map((match) =>
+		spot_at(line, match.index, row, columns),
+	)
+}
+
+// The frame with each placeholder drawn as `frame`, and every placeholder's spot that is on screen.
+function spun(lines: ReadonlyArray<string>, frame: string, size?: TerminalSize): Spun {
+	const columns = Math.max(1, size?.columns ?? Infinity)
+	const rows = size?.rows ?? Infinity
+	let row = 1
+	const spots = lines.flatMap((line) => {
+		const found = line_spots(line, row, columns)
+
+		row += run_board_fit.height_of(line, columns)
+
+		return found
+	})
+
+	return {
+		lines: lines.map((line) => line.split(SPOT).join(frame)),
+		spots: spots.filter((spot) => spot.row <= rows),
+	}
+}
+
+// One spinner frame at every spot: the cursor moved there, the spot's colors, the frame, then a reset.
+function spin_bytes(spots: ReadonlyArray<Spot>, frame: string): string {
+	return spots
+		.map((spot) => `${CSI}${String(spot.row)};${String(spot.column)}H${spot.style}${frame}${RESET}`)
+		.join('')
+}
+
+// The next moment the spinner turns, but never past `until_ms`.
+function next_turn(now_ms: number, until_ms: number): number {
+	return Math.min(now_ms - (now_ms % SPINNER_INTERVAL_MS) + SPINNER_INTERVAL_MS, until_ms)
+}
+
+async function turn_until(
+	spots: ReadonlyArray<Spot>,
+	ports: SpinPorts,
+	until_ms: number,
+): Promise<void> {
+	for (let now = ports.now(); now < until_ms; now = ports.now()) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each turn waits for the spinner's next frame
+		await ports.sleep(next_turn(now, until_ms) - now)
+		const at_ms = ports.now()
+
+		if (at_ms < until_ms) ports.write(spin_bytes(spots, spinner_of(at_ms)))
+	}
+}
+
+// Waits for the next second, turning the spinners until then; a frame with none just waits.
+async function spin_to_second(spots: ReadonlyArray<Spot>, ports: SpinPorts): Promise<void> {
+	const now_ms = ports.now()
+	const second_ms = now_ms - (now_ms % REDRAW_MS) + REDRAW_MS
+
+	if (spots.length === 0) {
+		await ports.sleep(second_ms - now_ms)
+
+		return
+	}
+
+	await turn_until(spots, ports, second_ms)
+}
+
+const run_board_spin = { REDRAW_MS, SPOT, spin_bytes, spin_to_second, spun }
+
+export { run_board_spin }
+export type { Spot, Spun }

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

@@ -0,0 +1,113 @@
+import type { NamedPlan } from '#scripts/backlog/backlog-plan'
+import type { MachineSample } from '#scripts/gate/machine-capacity'
+import type { ClosedAnswer, ClosedIssue } from './run-board-closed'
+import type { Fetch } from './run-board-fetch'
+import type { TerminalSize } from './run-board-fit'
+import type { BoardForm } from './run-board-header'
+import type { BoardPlan } from './run-board-layout'
+import type { Link } from './run-board-link'
+import type { MachineGauges, MachineMark } from './run-board-machine'
+import type { LocalRead } from './run-board-read'
+import type { Spot } from './run-board-spin'
+import type { LaneUsages, UsageMark } from './run-board-usage'
+
+// What a `run:board` redraw reads through and folds forward, shared by the
+// redraw (`run-board-tick.ts`) and its GitHub reads (`run-board-github.ts`).
+
+interface BoardPorts {
+	read_plan: (scope: NamedPlan) => Promise<BoardPlan | undefined>
+	// `undefined` when no run has started here.
+	read_local: () => Promise<LocalRead | undefined>
+	read_machine: () => Promise<MachineSample>
+	// Every process and its lane, the last reading's lanes reused (`run-board-usage-read.ts`).
+	read_usage: (before: UsageMark | undefined) => Promise<UsageMark | undefined>
+	// The issues that answered as closed, and whether every issue answered (`run-board-closed.ts`).
+	read_closed: (issues: ReadonlyArray<number>) => Promise<ClosedAnswer>
+	now: () => number
+	write: (frame: string) => void
+	// Wraps an issue number in a hyperlink where the terminal opens one, and leaves it plain elsewhere.
+	link: Link
+	// Whether stdout is a terminal — only a terminal gets the alternate screen and the spinner.
+	is_tty: boolean
+	// The terminal a live frame is kept within, read at every redraw so a resized pane is fitted on the
+	// next one; none where the frame is drawn whole — one frame, a pipe, a chat.
+	size?: (() => TerminalSize) | undefined
+	// The lines a live frame ends on, the first to give way to a short pane.
+	footer?: ReadonlyArray<string> | undefined
+	form: BoardForm
+	// Records that a progress report was just given, as `run:progress --mark` does, so the next scheduled
+	// one waits a full interval from here.
+	mark: () => Promise<void>
+	// Sends one chat frame off-screen, for `--every` alone.
+	push: (frame: string) => Promise<void>
+	// Runs `leave` however the process ends: a normal exit, Ctrl+C or SIGTERM.
+	on_exit: (leave: () => void) => void
+	sleep: (ms: number) => Promise<void>
+}
+
+// `background` launches the GitHub reads and draws without them; `settled` waits for them before
+// drawing.
+type Pace = 'background' | 'settled'
+
+interface BoardState {
+	// The last local read, drawn until the next is due; `undefined` when no run had started.
+	local: LocalRead | undefined
+	read_ms: number | undefined
+	// The start of the run the plan state was built for, so a run that begins draws nothing of the last.
+	run_started_ms: number | undefined
+	plan: BoardPlan | undefined
+	// The plan read in flight, `undefined` once it has been folded in.
+	plan_fetch: Fetch<BoardPlan | undefined> | undefined
+	attempted_ms: number | undefined
+	fetched_ms: number | undefined
+	failed_ms: number | undefined
+	baseline_total: number | undefined
+	// The run's children read closed, kept for the run: a closed issue's answer does not change.
+	closed: ReadonlyMap<number, ClosedIssue>
+	closed_fetch: Fetch<ClosedAnswer> | undefined
+	closed_attempted_ms: number | undefined
+	// The last ask every child answered, open or closed; a failed read leaves it where it was.
+	closed_answered_ms: number | undefined
+	// The last machine sample, which the next one is compared against, and the gauges drawn from them.
+	machine: MachineMark | undefined
+	gauges: MachineGauges | undefined
+	// The redraw the last sample was taken on, which the next sample is due a second after.
+	sampled_ms: number | undefined
+	// Where the last frame drew its spinners, turned between redraws.
+	spots: ReadonlyArray<Spot>
+	// The last process reading, which the next one is compared against, and each lane's usage drawn from
+	// them.
+	usage: UsageMark | undefined
+	usages: LaneUsages | undefined
+}
+
+const FRESH_STATE: BoardState = {
+	local: undefined,
+	read_ms: undefined,
+	run_started_ms: undefined,
+	plan: undefined,
+	plan_fetch: undefined,
+	attempted_ms: undefined,
+	fetched_ms: undefined,
+	failed_ms: undefined,
+	baseline_total: undefined,
+	closed: new Map(),
+	closed_fetch: undefined,
+	closed_attempted_ms: undefined,
+	closed_answered_ms: undefined,
+	machine: undefined,
+	gauges: undefined,
+	sampled_ms: undefined,
+	spots: [],
+	usage: undefined,
+	usages: undefined,
+}
+
+function is_due(last_ms: number | undefined, interval_ms: number, now_ms: number): boolean {
+	return last_ms === undefined || now_ms - last_ms >= interval_ms
+}
+
+const run_board_state = { FRESH_STATE, is_due }
+
+export { run_board_state }
+export type { BoardPorts, BoardState, Pace }

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

@@ -0,0 +1,279 @@
+import { backlog_idle, type IdleWindow } from '#scripts/backlog/backlog-idle'
+import {
+	has_label_name,
+	IN_PROGRESS_LABEL,
+	NEEDS_DECISION_LABEL,
+} from '#scripts/issue/issue-labels'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import type { ClosedIssue } from './run-board-closed'
+import { run_board_phase, type Phase } from './run-board-phase'
+
+// What each issue of a run is doing now, read from the run's own event stream and its open lanes.
+// Local reads only — no `gh` call — so `run:board` can redraw it every few seconds; the plan these
+// statuses are laid over is the slow GitHub half, and so is what a child that left the open listing
+// answers when read closed.
+
+type ItemState = 'running' | 'merged' | 'parked' | 'done' | 'waiting' | 'human' | 'stopped'
+
+interface ItemStatus {
+	state: ItemState
+	started_ms?: number | undefined
+	ended_ms?: number | undefined
+	// The seat-free lane label (`lane <N>`) of a running child, when it holds one — the running test reads
+	// it; the board does not draw it.
+	lane?: string | undefined
+	// Every phase the child passed while running, in order (`run-board-phase.ts`) — kept once it settles.
+	track?: ReadonlyArray<Phase> | undefined
+}
+
+// The run as a whole, read off the same stream.
+interface RunActivity {
+	last_event_ms: number | undefined
+	// The idle watch's window, when the newest one opened after the newest launch.
+	idle: IdleWindow | undefined
+	// The run's last position is a `stop` that names no child — the run itself ended.
+	is_stopped: boolean
+}
+
+const KIND = run_event_stream.EVENT_KIND
+const ENDING_STATES: Readonly<Partial<Record<string, ItemState>>> = {
+	[KIND.MERGE]: 'merged',
+	[KIND.PARK]: 'parked',
+	[KIND.SPLIT]: 'done',
+	[KIND.STOP]: 'done',
+}
+// A cut or a resume says the child is still running, on whatever phase it had reached.
+const CONTINUING_KINDS: ReadonlySet<string> = new Set([KIND.CUT, KIND.RESUME])
+
+function moment(event: RunEvent): number {
+	return Date.parse(event.at)
+}
+
+function launched(event: RunEvent): ItemStatus {
+	return { state: 'running', started_ms: moment(event), track: [run_board_phase.LAUNCHED_PHASE] }
+}
+
+// The status a child settles into: its start and the track it had reached, so a settled row still
+// draws how it got there.
+function settled_as(previous: ItemStatus | undefined, state: ItemState): ItemStatus {
+	const track = previous?.track
+
+	return { state, started_ms: previous?.started_ms, ...(track !== undefined && { track }) }
+}
+
+function ended(previous: ItemStatus | undefined, state: ItemState, event: RunEvent): ItemStatus {
+	return { ...settled_as(previous, state), ended_ms: moment(event) }
+}
+
+function continued(previous: ItemStatus | undefined): ItemStatus {
+	return { state: 'running', started_ms: previous?.started_ms, track: previous?.track }
+}
+
+// A stage line carrying its attempt redraws the track of any child launched on this stream — a settled
+// one too, since the line that survived a full stream is often the `report` after the merge — and
+// starts one for a running child whose launch has rolled off.
+function replayed(
+	previous: ItemStatus | undefined,
+	attempt: ReadonlyArray<Phase>,
+): ItemStatus | undefined {
+	if (previous === undefined) return previous
+	if (previous.track === undefined && previous.state !== 'running') return previous
+
+	return { ...previous, track: run_board_phase.replayed(previous.track ?? [], attempt) }
+}
+
+// A phase moves only a running child, so a three-word `report` stage after its merge — or a `plan`
+// event naming an issue no lane has launched — leaves the status as it was.
+function phased(previous: ItemStatus | undefined, event: RunEvent): ItemStatus | undefined {
+	const phase = run_board_phase.phase_of(event)
+
+	if (phase === undefined || previous?.state !== 'running') return previous
+
+	return { ...previous, track: run_board_phase.history_after(previous.track ?? [], phase) }
+}
+
+function advanced(previous: ItemStatus | undefined, event: RunEvent): ItemStatus | undefined {
+	const attempt = run_board_phase.attempt_of(event)
+
+	return attempt === undefined ? phased(previous, event) : replayed(previous, attempt)
+}
+
+// One event folded into the status of the child it names; an event the board does not track keeps it.
+function next_status(previous: ItemStatus | undefined, event: RunEvent): ItemStatus | undefined {
+	if (event.kind === KIND.CHILD_LAUNCH) return launched(event)
+
+	const ending = ENDING_STATES[event.kind]
+
+	if (ending !== undefined) return ended(previous, ending, event)
+
+	return CONTINUING_KINDS.has(event.kind) ? continued(previous) : advanced(previous, event)
+}
+
+function fold_events(events: ReadonlyArray<RunEvent>): Map<number, ItemStatus> {
+	const statuses = new Map<number, ItemStatus>()
+
+	for (const event of events) {
+		const issue = Number(run_event_scope.issue_named(event))
+		const status = next_status(statuses.get(issue), event)
+
+		if (status !== undefined && Number.isSafeInteger(issue)) statuses.set(issue, status)
+	}
+
+	return statuses
+}
+
+// A lane is this run's only when its issue is on the run's stream or in the run's plan, so a lane left
+// over from an earlier day is not drawn as this run's child.
+function is_running_lane(
+	issue: number,
+	status: ItemStatus | undefined,
+	in_run: ReadonlySet<number>,
+): boolean {
+	if (status === undefined) return in_run.has(issue)
+
+	return status.state === 'running'
+}
+
+// Every child the run has touched, with the lane each running child holds. A lane the stream never saw
+// launched — a run restored after the stream rolled — still reads as running while its issue is in the
+// run's plan (`in_run`).
+function statuses_of(
+	events: ReadonlyArray<RunEvent>,
+	lanes: ReadonlyArray<string>,
+	in_run: ReadonlySet<number>,
+): ReadonlyMap<number, ItemStatus> {
+	const statuses = fold_events(events)
+
+	for (const lane of lanes) {
+		const issue = Number(lane)
+		const status = statuses.get(issue)
+
+		if (is_running_lane(issue, status, in_run)) {
+			statuses.set(issue, { state: 'running', ...status, lane: `lane ${lane}` })
+		}
+	}
+
+	return statuses
+}
+
+// The open listing the plan was read with, and when it was read.
+interface OpenRead {
+	// `undefined` when the listing was cut short, so absence from it proves nothing.
+	open_numbers: ReadonlySet<number> | undefined
+	read_ms: number | undefined
+	// The children read closed from GitHub (`run-board-closed.ts`), by number.
+	closed: ReadonlyMap<number, ClosedIssue>
+	// Each listed issue's label names, by number; an issue the listing did not hold has none to read.
+	labels: ReadonlyMap<number, ReadonlyArray<string>>
+}
+
+function is_listed_closed(issue: number, read: OpenRead): boolean {
+	return read.open_numbers !== undefined && !read.open_numbers.has(issue)
+}
+
+// The listing was read after the child launched, so what it says about the child is this run's.
+function is_read_after_launch(status: ItemStatus, read: OpenRead): boolean {
+	return read.read_ms !== undefined && (status.started_ms ?? 0) <= read.read_ms
+}
+
+// A child launched before the listing was read and missing from it has closed since.
+function is_closed_running(issue: number, status: ItemStatus, read: OpenRead): boolean {
+	return is_listed_closed(issue, read) && is_read_after_launch(status, read)
+}
+
+// What a running child's labels say it is doing, `undefined` where they agree it is running: the child
+// applies `needs-decision` and drops `in-progress` itself when it stops, while the stream's park is
+// written by a parent that may no longer be there.
+function labelled_state(labels: ReadonlyArray<string> | undefined): ItemState | undefined {
+	if (labels === undefined) return undefined
+	if (has_label_name(labels, NEEDS_DECISION_LABEL)) return 'human'
+
+	return has_label_name(labels, IN_PROGRESS_LABEL) ? undefined : 'stopped'
+}
+
+function labelled(issue: number, status: ItemStatus, read: OpenRead): ItemStatus {
+	const state = is_read_after_launch(status, read)
+		? labelled_state(read.labels.get(issue))
+		: undefined
+
+	return state === undefined ? status : settled_as(status, state)
+}
+
+// A close dated before the launch is an earlier life of the issue, not how this run's child ended.
+function is_closed_before_launch(status: ItemStatus, closed: ClosedIssue): boolean {
+	if (closed.closed_ms === undefined || status.started_ms === undefined) return false
+
+	return closed.closed_ms < status.started_ms
+}
+
+// A running child read closed ends when GitHub says it closed, merged or not.
+function closed_status(
+	status: ItemStatus,
+	closed: ClosedIssue | undefined,
+): ItemStatus | undefined {
+	if (closed === undefined || is_closed_before_launch(status, closed)) return undefined
+
+	const state = closed.is_merged ? 'merged' : 'done'
+
+	return { ...settled_as(status, state), ended_ms: closed.closed_ms }
+}
+
+function settled(issue: number, status: ItemStatus, read: OpenRead): ItemStatus {
+	if (status.state !== 'running') return status
+
+	const from_closed = closed_status(status, read.closed.get(issue))
+
+	if (from_closed !== undefined) return from_closed
+
+	if (is_closed_running(issue, status, read)) return settled_as(status, 'done')
+
+	return labelled(issue, status, read)
+}
+
+// **The stream stays the source of truth; the listing only unsticks it.** A child whose merge never
+// reached the stream would read as running forever, so a running child the plan's open listing no
+// longer holds is drawn finished instead — merged and timed once GitHub was read for it, finished
+// without a time while that read has not answered. One the listing still holds is drawn as its labels
+// say, so a child that stopped with no parent to record it does not read as running.
+function settle_closed(
+	statuses: ReadonlyMap<number, ItemStatus>,
+	read: OpenRead,
+): ReadonlyMap<number, ItemStatus> {
+	return new Map([...statuses].map(([issue, status]) => [issue, settled(issue, status, read)]))
+}
+
+function newest_of(events: ReadonlyArray<RunEvent>, kind: string): RunEvent | undefined {
+	return events.findLast((event) => event.kind === kind)
+}
+
+function idle_of(events: ReadonlyArray<RunEvent>): IdleWindow | undefined {
+	const idle = newest_of(events, KIND.IDLE)
+	const launch = newest_of(events, KIND.CHILD_LAUNCH)
+
+	if (idle === undefined || (launch !== undefined && launch.pos > idle.pos)) return undefined
+
+	return backlog_idle.parse(idle.text)
+}
+
+function is_run_stop(event: RunEvent | undefined): boolean {
+	return event?.kind === KIND.STOP && run_event_scope.issue_named(event) === undefined
+}
+
+// `is_ended` is a run `run:carry --end` closed: its record says it stopped, whatever its last event
+// was.
+function activity_of(events: ReadonlyArray<RunEvent>, is_ended = false): RunActivity {
+	const last = events.at(-1)
+	const position = events.findLast((event) => !run_event_stream.TRACE_KINDS.has(event.kind))
+
+	return {
+		last_event_ms: last === undefined ? undefined : moment(last),
+		idle: idle_of(events),
+		is_stopped: is_ended || is_run_stop(position),
+	}
+}
+
+const run_board_status = { activity_of, settle_closed, statuses_of }
+
+export { run_board_status }
+export type { ItemState, ItemStatus, OpenRead, RunActivity }