@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/run/board/run-board-render-foot.ts

@@ -0,0 +1,59 @@
+import type { BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import { run_board_layout } from './run-board-layout'
+import type { Link } from './run-board-link'
+import type { BoardNote } from './run-board-notes'
+import { run_board_render_drawn } from './run-board-render-drawn'
+import { run_board_render_icon } from './run-board-render-icon'
+import { run_board_render_legend } from './run-board-render-legend'
+import { run_board_render_thanks } from './run-board-render-thanks'
+import { run_board_render_waits } from './run-board-render-waits'
+import type { Thanks } from './run-board-thanks-csv'
+
+// The lines around a frame's rows that no row draws — pure: the command a stopped run resumes from
+// under the header, and the reviewers thanked, the stray waits and the legend at the foot.
+
+const { STATE_ICONS, WORDS } = run_board_labels
+const GAP = '  '
+
+// The command that resumes a stopped run's session, under the header where the person looks first.
+function resume_lines(resume: string | undefined): Array<string> {
+	if (resume === undefined) return []
+
+	return ['', `${STATE_ICONS.human} ${WORDS.resume}${GAP}claude --resume ${resume}`]
+}
+
+// No legend is drawn before a plan is read, nor where the frame draws nothing it would name.
+function legend_of(header: BoardHeader, notes: ReadonlyArray<BoardNote>): Array<string> {
+	const { layout } = header
+
+	if (layout === undefined) return []
+
+	const rows = run_board_layout.drawn_rows(layout)
+	const leads = new Set(rows.map((row) => run_board_render_icon.state_icon(row)))
+	const drawn = run_board_render_drawn.drawn_of(header, rows, leads)
+
+	return run_board_render_legend.legend_of(rows, drawn, notes)
+}
+
+// The waits no lane row owns, right before the legend (joshuafolkken/kit#4052), and the legend.
+function legend_lines(header: BoardHeader, notes: ReadonlyArray<BoardNote>): Array<string> {
+	const lines = [...run_board_render_waits.stray_lines(header), ...legend_of(header, notes)]
+
+	return lines.length === 0 ? [] : ['', ...lines]
+}
+
+// Names with no link where no terminal opens one: a frame with no `link` draws them plain.
+function thanks_part(
+	thanks: Thanks | undefined,
+	link: Link | undefined,
+	columns: number | undefined,
+): Array<string> {
+	const linked = link ?? ((text: string): string => text)
+
+	return run_board_render_thanks.thanks_lines(thanks ?? [], linked, columns)
+}
+
+const run_board_render_foot = { legend_lines, resume_lines, thanks_part }
+
+export { run_board_render_foot }

package/scripts/run/board/run-board-render-found.ts

@@ -0,0 +1,157 @@
+import { run_event_overrun, type OverrunNote } from '#scripts/run/event/run-event-overrun'
+import type { Found } from './run-board-found'
+import type { BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+import { run_board_render_title } from './run-board-render-title'
+import type { ItemState } from './run-board-status'
+
+// A done row's end after its time (joshuafolkken/kit#4772, joshuafolkken/kit#4818). A merged row says
+// its lane's net minutes — `?′` where there are none — the numbers of the Issues its child filed, then
+// what its overrun investigation came to and the numbers it filed (joshuafolkken/kit#4880), each group
+// two spaces apart: `⏭` and why it was skipped, or 🔍, the lane's longest stage and the numbers it filed
+// (`🔍 implement 51′ · 4983`), `↪N` for each open
+// Issue it appended causes to (joshuafolkken/kit#4858), `∅` and why it did not, `∅ ↻N` for a
+// recurrence commented on, or 💥 for an investigation that failed. While the investigation runs, the spinner stands for 🔍.
+// A row its merge left no note on was never asked. A done row that did not merge, and a merged row
+// while the investigation switch is off, says only what was filed during it.
+
+const { OVERRUN_MARK } = run_board_labels
+const DONE_STATES: ReadonlySet<ItemState> = new Set(['merged', 'done'])
+const SEPARATOR = ', '
+const GROUP_SEPARATOR = '  '
+const LONGEST_SEPARATOR = ' · '
+const MINUTES_WIDTH = 3
+const MINUTE_MARK = '′'
+const UNKNOWN_MINUTES = '?'
+const SKIP_MARK = '⏭'
+const NONE_MARK = '∅'
+const RECURRED_MARK = '↻'
+const FOLDED_MARK = '↪'
+const FAILED_TEXT = `${OVERRUN_MARK} 💥`
+const NO_RECORD = 'no record'
+// The investigator writes its reason in about 15 characters; the row keeps no more.
+const REASON_LIMIT = 16
+
+function found_of(row: BoardRow, header: BoardHeader): Found | undefined {
+	if (!DONE_STATES.has(row.state)) return undefined
+
+	return header.found?.get(row.number)
+}
+
+function links_of(references: ReadonlyArray<string>, header: BoardHeader): string {
+	return references.map((reference) => header.link(reference)).join(SEPARATOR)
+}
+
+// Every filing, the child's and the investigation's alike: a row that did not merge has no outcome
+// to tell them apart by.
+function numbers_of(found: Found | undefined, header: BoardHeader): string {
+	return links_of([...(found?.filed ?? []), ...(found?.overrun_filed ?? [])], header)
+}
+
+function minutes_text(found: Found | undefined): string {
+	const minutes = found?.minutes === undefined ? UNKNOWN_MINUTES : String(found.minutes)
+
+	return `${minutes.padStart(MINUTES_WIDTH)}${MINUTE_MARK}`
+}
+
+// An investigation that filed nothing: the recurrence it commented on, a link with no `#` and its mark
+// outside it (joshuafolkken/kit#4956), else why it did not.
+function none_text(result: string, header: BoardHeader): string {
+	const recurred = run_event_overrun.recurred_of(result)
+
+	if (recurred !== undefined) return `${NONE_MARK} ${RECURRED_MARK}${header.link(String(recurred))}`
+
+	const why = run_board_render_title.title_of(run_event_overrun.reason_of(result), REASON_LIMIT)
+
+	return `${NONE_MARK} ${why}`
+}
+
+// The open Issues the investigation appended its causes to, each a link with no `#`.
+function folded_text(issues: ReadonlyArray<number>, header: BoardHeader): string {
+	const links = issues.map((issue) => `${FOLDED_MARK}${header.link(String(issue))}`)
+
+	return `${OVERRUN_MARK} ${links.join(SEPARATOR)}`
+}
+
+// The result decides, not whether anything was filed: an event written before the overrun mark reads
+// as the child's.
+function ended_text(result: string, header: BoardHeader): string {
+	const folded = run_event_overrun.folded_of(result)
+
+	if (folded.length > 0) return folded_text(folded, header)
+	if (result.startsWith(run_event_overrun.FILED_RESULT)) return OVERRUN_MARK
+
+	return `${OVERRUN_MARK} ${none_text(result, header)}`
+}
+
+// A started session still running turns the spinner, one gone without its end note failed, and one
+// whose start token was never read stands still while its pid lives.
+function started_text(found: Found, header: BoardHeader): string {
+	if (found.is_investigating === false) return FAILED_TEXT
+	if (found.is_investigating === undefined) return OVERRUN_MARK
+
+	return header.spinner ?? OVERRUN_MARK
+}
+
+// A lane at or under the threshold says nothing past its minutes.
+function outcome_text(found: Found, note: OverrunNote, header: BoardHeader): string {
+	if (note.kind === 'within') return ''
+	if (note.kind === 'skipped') return `${SKIP_MARK} ${note.reason}`
+	if (note.kind === 'ended') return ended_text(note.result, header)
+
+	return note.kind === 'started' ? started_text(found, header) : FAILED_TEXT
+}
+
+function joined(parts: ReadonlyArray<string>, separator: string): string {
+	return parts.filter((part) => part !== '').join(separator)
+}
+
+// The lane's longest stage its start note carried (joshuafolkken/kit#4995), else nothing.
+function longest_text(found: Found | undefined): string {
+	const longest = found?.longest
+
+	return longest === undefined ? '' : `${longest.name} ${String(longest.minutes)}${MINUTE_MARK}`
+}
+
+// What the investigation came to, its lane's longest stage, then the Issues it filed.
+function investigation_text(found: Found | undefined, header: BoardHeader): string {
+	const outcome =
+		found?.overrun === undefined
+			? `${SKIP_MARK} ${NO_RECORD}`
+			: outcome_text(found, found.overrun, header)
+
+	const filed = links_of(found?.overrun_filed ?? [], header)
+
+	return joined([outcome, joined([longest_text(found), filed], LONGEST_SEPARATOR)], ' ')
+}
+
+// The minutes, the child's own filings, then the investigation, each group apart by two spaces. While
+// the investigation switch is off, every merged row says only what was filed, whatever its note
+// (joshuafolkken/kit#5132, joshuafolkken/kit#5194).
+function merged_text(row: BoardRow, header: BoardHeader): string {
+	const found = found_of(row, header)
+
+	if (!header.is_investigation_on) return numbers_of(found, header)
+
+	const own = links_of(found?.filed ?? [], header)
+
+	return joined([minutes_text(found), own, investigation_text(found, header)], GROUP_SEPARATOR)
+}
+
+// Empty for an unmerged done row with nothing filed, for every row not done, and on a board that read
+// no stream.
+function found_text(row: BoardRow, header: BoardHeader): string {
+	if (row.state === 'merged' && header.found !== undefined) return merged_text(row, header)
+
+	return numbers_of(found_of(row, header), header)
+}
+
+// The row draws 🔍, which the legend names.
+function is_still(row: BoardRow, header: BoardHeader): boolean {
+	return row.state === 'merged' && found_text(row, header).includes(OVERRUN_MARK)
+}
+
+const run_board_render_found = { found_text, is_still }
+
+export { run_board_render_found }

package/scripts/run/board/run-board-render-icon.ts

@@ -0,0 +1,35 @@
+import { run_board_earlier } from './run-board-earlier'
+import { run_board_labels } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+
+// The icon a `run:board` row leads with: its state's, or its phase's while it runs. A held lane keeps
+// it, 🚧 standing in the progress column before it (joshuafolkken/kit#4292).
+
+const { PHASE_ICONS, STATE_ICONS } = run_board_labels
+const { EARLIER_ICON } = run_board_earlier
+
+// A row that says what it waits on leads with that wait's icon in place of its state's
+// (joshuafolkken/kit#4288).
+function state_lead(row: BoardRow): string {
+	return row.reason?.icon ?? STATE_ICONS[row.state]
+}
+
+// A running row leads with the icon of the phase it is in now — the last its track reached — and
+// with 🔄 while it has reached none yet; an earlier run's running lane leads with 🧳 in its place.
+function running_lead(row: BoardRow): string {
+	const current = row.status?.track?.at(-1)
+
+	return current === undefined ? state_lead(row) : PHASE_ICONS[current]
+}
+
+function state_icon(row: BoardRow): string {
+	if (row.state !== 'running') return state_lead(row)
+
+	return row.is_earlier === true ? EARLIER_ICON : running_lead(row)
+}
+
+const run_board_render_icon = {
+	state_icon,
+}
+
+export { run_board_render_icon }

package/scripts/run/board/run-board-render-lanes.ts

@@ -0,0 +1,145 @@
+import { run_board_earlier } from './run-board-earlier'
+import { run_board_fit, type PlanLine, type PlanSection } from './run-board-fit'
+import type { BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+import { run_board_render_lead } from './run-board-render-lead'
+import { run_board_render_section, type RuleColumn } from './run-board-render-section'
+import type { LaneUsages, UsageFigure, UsageScale } from './run-board-usage'
+import { run_board_usage_text, type CellLimits } from './run-board-usage-text'
+
+// The run's own rows' CPU, MEM and CMPRS cells, right after each row's lead and before its number,
+// under a rule whose labels stand over them and over the run's time: `── 🧵 lanes ── ⏰ ── 💪 CPU ─
+// 🧠 MEM ─ 🤏 CMPRS ───`. The cells start at `USAGE_START`, as the processes rows' do, so the two
+// sections' figures stand in one column (joshuafolkken/kit#4292). A running row draws its lane's
+// figures; every other row blanks of the same width, so every number and title after them starts in
+// one column. Drawn with gauges on a terminal and as figures alone anywhere else.
+
+const { HEADER_ICONS } = run_board_labels
+const { cell_widths, cells_of, lane_limits } = run_board_usage_text
+const { columns_rule } = run_board_render_section
+const { ELAPSED_START, USAGE_START } = run_board_render_lead
+const { width_of } = run_board_fit
+const GAUGE = 5
+const CELL_GAP = ' '
+// What a column needs past its label so the next label still has a rule before it: ` ─`.
+const LABEL_TAIL = 2
+// Icons Unicode draws as emoji by default, which `string-width` counts two columns wide as a
+// terminal draws them: 🛤 and 🗜, text symbols drawn as emoji, overlapped the blank after them.
+const LANES_LABEL = `${run_board_labels.LANES_ICON} lanes`
+const COLUMN_LABELS = [`${HEADER_ICONS.cpu} CPU`, `${HEADER_ICONS.memory} MEM`, '🤏 CMPRS']
+
+// What one frame's lane cells are drawn with.
+interface LaneCells {
+	usages: LaneUsages
+	scale: UsageScale
+	// Where each live row's gauges are full — its share of the header's yellow thresholds, counted once a
+	// frame.
+	limits: CellLimits
+	gauge: number
+	// The widest row number of the section, so the kind icon and title after it start in one column.
+	number_width: number
+}
+
+// The gauge drawn after each figure — none where the frame is not drawn on a terminal, which draws no
+// spinner.
+function gauge_of(header: BoardHeader): number {
+	return header.spinner === undefined ? 0 : GAUGE
+}
+
+// Each column's width: its cell's, widened where its label is wider.
+function column_widths(gauge: number): Array<number> {
+	return cell_widths(gauge).map((width, index) =>
+		Math.max(width, width_of(COLUMN_LABELS[index] ?? '') + LABEL_TAIL),
+	)
+}
+
+// A figure's cells, each right-aligned in its column — full at `limits` where a lane row passes its
+// share, at the whole machine where not.
+function column_cells(
+	figure: UsageFigure | undefined,
+	scale: UsageScale,
+	gauge: number,
+	limits?: CellLimits,
+): string {
+	const widths = column_widths(gauge)
+	const cells = cells_of(figure, scale, gauge, limits).map(
+		(cell, index) => `${' '.repeat(Math.max(0, (widths[index] ?? 0) - width_of(cell)))}${cell}`,
+	)
+
+	return cells.join(CELL_GAP)
+}
+
+// `undefined` where the frame read no usage, which draws no cells.
+function lane_cells_of(header: BoardHeader, rows: ReadonlyArray<BoardRow>): LaneCells | undefined {
+	const { usages } = header
+
+	if (usages === undefined) return undefined
+
+	const running = rows.filter((row) => run_board_earlier.is_live(row)).length
+
+	return {
+		usages: usages.lanes,
+		scale: usages.scale,
+		limits: lane_limits(running),
+		gauge: gauge_of(header),
+		number_width: Math.max(0, ...rows.map((row) => String(row.number).length)),
+	}
+}
+
+// A row's number as linked — where cells are drawn, after them and padded to the section's widest.
+function number_text(
+	row: BoardRow,
+	cells: LaneCells | undefined,
+	link: (text: string) => string,
+): string {
+	const number = String(row.number)
+
+	if (cells === undefined) return link(number)
+
+	const figure = run_board_earlier.is_live(row) ? cells.usages.get(row.number) : undefined
+	const drawn = column_cells(figure, cells.scale, cells.gauge, cells.limits)
+
+	return `${drawn} ${link(number)}${' '.repeat(cells.number_width - number.length)}`
+}
+
+// Each column's label, placed at the column its cells start at, the first at `first`.
+function label_columns(first: number, gauge: number): Array<RuleColumn> {
+	let start = first
+
+	return column_widths(gauge).map((width, index) => {
+		const column = { label: COLUMN_LABELS[index] ?? '', start }
+
+		start += width + CELL_GAP.length
+
+		return column
+	})
+}
+
+// The run's own rows under the lanes rule, ⏰ over the run's time and the usage labels over their
+// cells where they are drawn.
+function lanes_section(
+	lines: ReadonlyArray<PlanLine>,
+	cells: LaneCells | undefined,
+): Array<PlanSection> {
+	if (lines.length === 0) return []
+
+	const elapsed = { label: HEADER_ICONS.elapsed, start: ELAPSED_START }
+	const usage = cells === undefined ? [] : label_columns(USAGE_START, cells.gauge)
+	const rule = columns_rule(LANES_LABEL, [elapsed, ...usage])
+
+	return [{ head: ['', rule], lines, label: LANES_LABEL, key: 'lanes' }]
+}
+
+const run_board_render_lanes = {
+	COLUMN_LABELS,
+	LANES_LABEL,
+	column_cells,
+	label_columns,
+	lane_cells_of,
+	lanes_section,
+	number_text,
+}
+
+export { run_board_render_lanes }
+export type { LaneCells }

package/scripts/run/board/run-board-render-lead.ts

@@ -0,0 +1,89 @@
+import { run_board_earlier } from './run-board-earlier'
+import { run_board_fresh } from './run-board-fresh'
+import type { BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import type { BoardRow } from './run-board-layout'
+import { run_board_render_icon } from './run-board-render-icon'
+import { run_board_render_tail } from './run-board-render-tail'
+import { run_board_render_time } from './run-board-render-time'
+import { run_board_render_waits } from './run-board-render-waits'
+
+// What a lane row draws before its usage cells (joshuafolkken/kit#4292): the progress column — the
+// spinner while it runs, 🚧 while its lane is held, blanks where it stopped — the phase's icon, how
+// long it has stood at the phase and how long it has run, each time eight columns right-aligned. A held
+// lane draws why and how long it is held in the run's time's place, so every column after it stays put.
+
+const { BUDGET_ICON, held_of, held_time } = run_board_render_waits
+const { phase_time } = run_board_render_tail
+const { state_icon } = run_board_render_icon
+const { time_of } = run_board_render_time
+const { WAIT_ICONS } = run_board_labels
+// The widest span a time column draws: `1°14′58″`.
+const TIME_WIDTH = 8
+const LANE_INDENT = '  '
+// The progress column: an emoji two columns wide, or the spinner and a blank.
+const PROGRESS_WIDTH = 2
+const PROGRESS_BLANK = ' '.repeat(PROGRESS_WIDTH)
+const ICON_WIDTH = 2
+const SPACE = 1
+// The column the run's time starts at, which the rule's ⏰ stands over.
+const ELAPSED_START =
+	LANE_INDENT.length + PROGRESS_WIDTH + SPACE + ICON_WIDTH + SPACE + TIME_WIDTH + SPACE
+// The column a lane row's usage cells start at, after the lead and one blank; the processes rows' too.
+const USAGE_START = ELAPSED_START + TIME_WIDTH + SPACE
+
+// A running row's part that changed at `at_ms`, emphasized while fresh (`run-board-fresh.ts`) — its
+// start and its phase; a settled row's are long past.
+function running_fresh(
+	row: BoardRow,
+	text: string,
+	at_ms: number | undefined,
+	header: BoardHeader,
+): string {
+	return run_board_earlier.is_live(row) ? run_board_fresh.since(text, at_ms, header) : text
+}
+
+function progress_of(row: BoardRow, header: BoardHeader): string {
+	if (held_of(row, header) !== undefined) return BUDGET_ICON
+	if (row.state !== 'running' || header.spinner === undefined) return PROGRESS_BLANK
+
+	return `${header.spinner} `
+}
+
+// How long the row has run, or why and how long its lane is held while it is.
+function whole_of(row: BoardRow, header: BoardHeader): string {
+	const held = held_of(row, header)
+
+	if (held !== undefined) return held_time(held, TIME_WIDTH)
+
+	const time = time_of(row, header.now_ms) ?? ''
+	const fresh = running_fresh(row, time, row.status?.started_ms, header)
+
+	return run_board_fresh.padded(time, TIME_WIDTH, fresh)
+}
+
+// A lane row's indent: 🧍 on a `run:solo` row (joshuafolkken/kit#4625), as wide as the blanks it
+// replaces, so every column after it stays put.
+function indent_of(row: BoardRow): string {
+	return row.is_solo === true ? WAIT_ICONS.solo : LANE_INDENT
+}
+
+// A lane row's lead after its indent, ending where its usage cells start less one blank.
+function lead_of(row: BoardRow, header: BoardHeader): string {
+	const icon = running_fresh(row, state_icon(row), row.status?.phase_ms, header)
+	const phase = phase_time(row, header, TIME_WIDTH)
+
+	return [progress_of(row, header), icon, phase, whole_of(row, header)].join(' ')
+}
+
+const run_board_render_lead = {
+	ELAPSED_START,
+	LANE_INDENT,
+	TIME_WIDTH,
+	USAGE_START,
+	indent_of,
+	lead_of,
+	running_fresh,
+}
+
+export { run_board_render_lead }