@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -0,0 +1,299 @@
+import { WriteStream } from 'node:tty'
+import { styleText } from 'node:util'
+import type { FiledKind } from '#scripts/run/event/run-event-filed'
+import cli_spinners from 'cli-spinners'
+import type { BoardNote } from './run-board-notes'
+import type { Phase } from './run-board-phase'
+import type { ItemState } from './run-board-status'
+
+// The words and the clock `run:board` draws with. A moment on the board is a local `HH:MM:SS` clock;
+// how long something has run is a short `MM:SS`, so a person reads the board against the clock on
+// their own screen.
+
+const CLOCK_WIDTH = 2
+const CLOCK_PAD = '0'
+const MS_PER_SECOND = 1000
+const SECONDS_PER_MINUTE = 60
+const MINUTES_PER_HOUR = 60
+const MS_PER_MINUTE = MS_PER_SECOND * SECONDS_PER_MINUTE
+// Every gauge is this wide — the plan, the machine and a row's phase.
+const BAR_WIDTH = 10
+// A centered square done and a thin line left: the shapes alone tell the two apart where no color is
+// drawn, and a terminal dims the line so the gauge does not read heavy. The square, not a full block,
+// leaves a gap between stacked bars at line height 1.
+const BAR_DONE = '■'
+const BAR_LEFT = '─'
+const BAR_DONE_COLOR: TextColor = 'cyan'
+const BAR_LEFT_COLOR: TextColor = 'dim'
+// The spinner a running run and a running row turn, at the package's own interval.
+const SPINNER_FRAMES = cli_spinners.dots.frames
+const SPINNER_INTERVAL_MS = cli_spinners.dots.interval
+// The color depth from which a terminal draws a 24-bit color, and the escapes that draw one.
+const RGB_COLOR_DEPTH = 24
+const ESC = '\u{1B}'
+const DEFAULT_FOREGROUND = `${ESC}[39m`
+
+// The words the board draws, English whatever the session language: one set of words reads the same
+// on every board. The board draws most of what it says as a symbol; the words left are the ones a
+// symbol cannot carry, and the legend that names the symbols.
+const WORDS = {
+	no_run: 'no run',
+	plan: 'plan',
+	merged: 'merged',
+	parked: 'parked',
+	done: 'done',
+	in_progress: 'running',
+	stopped: 'stopped',
+	waiting: 'waiting',
+	decision: 'decision',
+	waits: 'waits on',
+	investigate: 'investigate',
+	implement: 'implement',
+	ship: 'ship',
+	review: 'review',
+	gate: 'gate',
+	sync: 'sync',
+	commit: 'commit',
+	round_two: 'round-2',
+	followup: 'followup',
+	report: 'report',
+	failed: 'failed',
+	idle_until: 'wait ends',
+	idle_left: 'left',
+	idle_end_idle: 'ends and reports if nothing new',
+	idle_end_run: 'ends at the whole-run cut-off and reports',
+	next_check: 'next check',
+	notes: 'findings and decisions',
+	more: 'more',
+	filed: 'filed',
+	breaking: 'breaking',
+	feature: 'feature',
+	fix: 'fix',
+	park: 'park',
+	note: 'note',
+	found_during: ' (found during {n})',
+	// The session a stopped run waits in, and what closing the board leaves.
+	resume: 'stopped — resume with',
+	keeps_running: 'Closing this screen leaves the run going · reopen with `pnpm josh backlogrun`',
+} as const
+
+type Words = typeof WORDS
+
+type TextColor = Parameters<typeof styleText>[0]
+
+// A color that does not depend on the terminal's palette: `rgb` as the
+// `38;2;R;G;B` escape takes it, drawn where the output has 24-bit color, and `named` — the palette's own
+// — where it does not.
+interface Shade {
+	rgb: string
+	named: TextColor
+}
+
+type Paint = TextColor | Shade
+
+// Every row icon is an emoji a terminal draws two columns wide by default (Emoji_Presentation), so the
+// number after it lines up whichever state a row is in: 🅿 and ☑ are text symbols a terminal such as
+// VSCode's draws one column wide, which would shift a parked or finished row.
+const STATE_ICONS: Readonly<Record<ItemState, string>> = {
+	running: '🔄',
+	merged: '✅',
+	parked: '💤',
+	done: '🏁',
+	waiting: '⏳',
+	human: '🙋',
+	stopped: '🛑',
+}
+
+// The blocking edge, chosen on the same rule: ⛓ is a text symbol.
+const WAITS_ICON = '🔗'
+
+// A running row's phases as icons, chosen on the same rule; the row draws every phase it has passed,
+// so the rightmost icon is what it is doing now. Each of `josh ship`'s stages has its own; ⚓ rather
+// than 🔁, which reads as a retry.
+const PHASE_ICONS: Readonly<Record<Phase, string>> = {
+	investigate: '🔍',
+	plan: '📝',
+	implement: '🔨',
+	ship: '🚢',
+	review: '👀',
+	gate: '🚦',
+	sync: '🔀',
+	commit: '📦',
+	round_two: '🔂',
+	followup: '⚓',
+	report: '📣',
+	failed: '💥',
+}
+
+// The legend's word for each phase — the header's own `plan` where the phase shares one.
+const PHASE_WORDS: Readonly<Record<Phase, keyof Words>> = {
+	investigate: 'investigate',
+	plan: 'plan',
+	implement: 'implement',
+	ship: 'ship',
+	review: 'review',
+	gate: 'gate',
+	sync: 'sync',
+	commit: 'commit',
+	round_two: 'round_two',
+	followup: 'followup',
+	report: 'report',
+	failed: 'failed',
+}
+
+// The findings section's rule and each note kind's lead, chosen on the same rule and apart from every
+// phase and state icon, so the legend names them and a row needs no word. 🆕 is a filed issue whose
+// kind is none of `FILED_KIND_ICONS`.
+const NOTES_ICON = '📌'
+const NOTE_ICONS: Readonly<Record<BoardNote['kind'], string>> = {
+	filed: '🆕',
+	park: STATE_ICONS.parked,
+	note: '💬',
+}
+// A filed issue's line leads with its kind in place of 🆕: inside the 📌 section a line is already
+// read as a filing, so 🆕 beside the kind would only widen it. 🧨 rather than 💥, which a failed ship
+// draws.
+const FILED_KIND_ICONS: Readonly<Record<FiledKind, string>> = {
+	'breaking-change': '🧨',
+	bug: '🐛',
+	enhancement: '✨',
+}
+// A row leads its title with its kind's icon (joshuafolkken/kit#3577), and one with no kind with as many
+// blank columns, so every title starts in one column. The legend names a kind by its release category.
+const KIND_BLANK = '  '
+const KIND_WORDS: Readonly<Record<FiledKind, keyof Words>> = {
+	'breaking-change': 'breaking',
+	enhancement: 'feature',
+	bug: 'fix',
+}
+
+// The header's gauges and marks. ⚡ rather than 🔥: a fire beside a gauge drawn green reads as an
+// alarm.
+const HEADER_ICONS = {
+	cpu: '⚡',
+	memory: '🧠',
+	swap: '💾',
+	ended: '🔚',
+	loading: '⏳',
+} as const
+
+// **The machine gauges' three colors, decided here alone**: Activity Monitor's green, yellow and red
+// in the system's dark-mode values. A palette's `green` draws blue and its `red` orange in a VSCode
+// terminal, so the normal gauge would read as the cyan plan bar and the busy one as yellow.
+const GAUGE_SHADES = {
+	normal: { rgb: '48;209;88', named: 'green' },
+	yellow: { rgb: '255;214;10', named: 'yellow' },
+	red: { rgb: '255;69;58', named: 'red' },
+} as const satisfies Readonly<Record<string, Shade>>
+
+function two_digits(value: number): string {
+	return String(value).padStart(CLOCK_WIDTH, CLOCK_PAD)
+}
+
+// The local wall-clock `HH:MM:SS` of a moment.
+function clock_of(ms: number): string {
+	const date = new Date(ms)
+
+	return [date.getHours(), date.getMinutes(), date.getSeconds()]
+		.map((value) => two_digits(value))
+		.join(':')
+}
+
+// The local wall-clock `HH:MM` of a moment, for one a person reads to the minute — when a run ended, or
+// when a finding was filed.
+function minute_of(ms: number): string {
+	const date = new Date(ms)
+
+	return [date.getHours(), date.getMinutes()].map((value) => two_digits(value)).join(':')
+}
+
+// How long something has run, as `MM:SS` whose minutes never carry into hours (`61:05`), so the header
+// and every row read one short column; a negative span reads as zero.
+function elapsed_of(ms: number): string {
+	const seconds = Math.floor(Math.max(0, ms) / MS_PER_SECOND)
+	const minutes = Math.floor(seconds / SECONDS_PER_MINUTE)
+
+	return `${two_digits(minutes)}:${two_digits(seconds % SECONDS_PER_MINUTE)}`
+}
+
+// How long is left, as `7h38m`; a deadline already passed reads as zero.
+function left_of(ms: number): string {
+	const minutes = Math.floor(Math.max(0, ms) / MS_PER_MINUTE)
+	const hours = Math.floor(minutes / MINUTES_PER_HOUR)
+
+	return `${String(hours)}h${two_digits(minutes % MINUTES_PER_HOUR)}m`
+}
+
+function is_shade(color: Paint): color is Shade {
+	return typeof color === 'object' && 'rgb' in color
+}
+
+// A shade in 24-bit color where stdout draws it, else its palette color. Whether stdout draws color at
+// all is `styleText`'s answer alone, so a shade draws no escape where its palette color would not.
+function shaded(shade: Shade, text: string): string {
+	const named = styleText(shade.named, text)
+
+	if (named === text || WriteStream.prototype.getColorDepth() < RGB_COLOR_DEPTH) return named
+
+	return `${ESC}[38;2;${shade.rgb}m${text}${DEFAULT_FOREGROUND}`
+}
+
+// A part of a gauge in its color; an empty part, or no color, draws no escape. `styleText` drops the
+// escape itself where stdout draws no color (a pipe, `NO_COLOR`), so a gauge never disagrees with the
+// rest of the board about it.
+function painted(color: Paint | undefined, text: string): string {
+	if (color === undefined || text === '') return text
+
+	return is_shade(color) ? shaded(color, text) : styleText(color, text)
+}
+
+// **The one progress bar the board draws** — the header's plan, the machine and every running row's
+// phase: `done` of `total` filled in proportion across `width` cells, the done part in `color`
+// (`undefined` leaves it the terminal's own).
+function bar_of(
+	done: number,
+	total: number,
+	width: number = BAR_WIDTH,
+	color: Paint | undefined = BAR_DONE_COLOR,
+): string {
+	const filled = total === 0 ? 0 : Math.round((Math.min(done, total) / total) * width)
+
+	return (
+		painted(color, BAR_DONE.repeat(filled)) +
+		painted(BAR_LEFT_COLOR, BAR_LEFT.repeat(width - filled))
+	)
+}
+
+// The spinner's frame at a moment, from the clock rather than a count of redraws, so the frame a redraw
+// draws needs no state carried between redraws.
+function spinner_of(now_ms: number): string {
+	const step = Math.floor(Math.max(0, now_ms) / SPINNER_INTERVAL_MS)
+
+	return SPINNER_FRAMES[step % SPINNER_FRAMES.length] ?? ''
+}
+
+const run_board_labels = {
+	FILED_KIND_ICONS,
+	GAUGE_SHADES,
+	HEADER_ICONS,
+	KIND_BLANK,
+	KIND_WORDS,
+	NOTES_ICON,
+	NOTE_ICONS,
+	PHASE_ICONS,
+	PHASE_WORDS,
+	SPINNER_INTERVAL_MS,
+	STATE_ICONS,
+	WAITS_ICON,
+	WORDS,
+	bar_of,
+	clock_of,
+	elapsed_of,
+	left_of,
+	minute_of,
+	painted,
+	spinner_of,
+}
+
+export { run_board_labels }
+export type { Paint, TextColor, Words }

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

@@ -0,0 +1,222 @@
+import { backlog_plan, type PlanContext } from '#scripts/backlog/backlog-plan'
+import type { WavePlan } from '#scripts/backlog/backlog-waves'
+import type { EpicChild } from '#scripts/epic/epic-graph'
+import type { IssueReference } from '#scripts/epic/epic-reference'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import type { FiledKind } from '#scripts/run/event/run-event-filed'
+import { run_board_kind } from './run-board-kind'
+import type { ItemState, ItemStatus } from './run-board-status'
+
+// The plan with each issue's status laid over it — pure, so the order the board
+// draws is tested apart from the screen. **The order is the plan's**: the waves are `backlog_waves.build`'s,
+// the same play-forward `backlog:plan --waves` prints, so a merge, a park or a new arrival that changes the
+// plan changes the board with it. The plan leaves out what a run already holds or has closed, so those
+// rows come from the stream instead, in the leading active section.
+//
+// **An epic and its children are a tree; every other dependency is not.** A child an opted-in epic
+// tracks is drawn under its epic; a `blocked_by` edge is a DAG, so it stays a waiting-on note at the end of the row.
+
+interface BoardPlan {
+	waves: WavePlan
+	// Which opted-in epic tracks which child (`Plan.tracked`).
+	tracked: ReadonlyMap<number, number>
+	context: PlanContext
+	// Each issue's label names as the open listing read them, so a running row is drawn as its labels
+	// say it stopped.
+	labels: ReadonlyMap<number, ReadonlyArray<string>>
+}
+
+interface BoardRow {
+	number: number
+	title: string | undefined
+	// The release category its labels place it in (joshuafolkken/kit#3577), none for an Other Change.
+	kind: FiledKind | undefined
+	state: ItemState
+	status: ItemStatus | undefined
+	// The standing blockers this row still waits on, as the plan names them.
+	waits: ReadonlyArray<string>
+}
+
+type WaveEntry =
+	| { kind: 'row'; row: BoardRow }
+	| { kind: 'epic'; epic: number; title: string | undefined; rows: Array<BoardRow> }
+
+interface BoardLayout {
+	active: ReadonlyArray<BoardRow>
+	waves: ReadonlyArray<ReadonlyArray<WaveEntry>>
+	people: ReadonlyArray<BoardRow>
+	unreached: ReadonlyArray<BoardRow>
+}
+
+// What an active row is named and classified by — each issue's title and labels.
+interface RowRead {
+	titles: ReadonlyMap<number, string>
+	labels: ReadonlyMap<number, ReadonlyArray<string>>
+}
+
+interface Overlay {
+	plan: BoardPlan
+	statuses: ReadonlyMap<number, ItemStatus>
+}
+
+const SETTLED_STATES: ReadonlySet<ItemState> = new Set(['merged', 'parked', 'done'])
+
+function is_settled(state: ItemState): boolean {
+	return SETTLED_STATES.has(state)
+}
+
+// A blocker the plan still names, unless the stream has already seen it merge — the plan was read up
+// to two minutes ago, and a merge since then is no longer worth waiting on.
+function is_waiting_on(edge: IssueReference, overlay: Overlay): boolean {
+	const { context } = overlay.plan
+	const is_merged =
+		edge.repo === context.repo && overlay.statuses.get(edge.number)?.state === 'merged'
+
+	return !is_merged && backlog_plan.is_standing(edge, context)
+}
+
+function reference_of(edge: IssueReference, repo: string): string {
+	return edge.repo === repo ? String(edge.number) : issue_cite.plain(edge.number, edge.repo)
+}
+
+function plan_row(child: EpicChild, state: ItemState, overlay: Overlay): BoardRow {
+	const { context } = overlay.plan
+	const waits = child.blocked_by
+		.filter((edge) => is_waiting_on(edge, overlay))
+		.map((edge) => reference_of(edge, context.repo))
+
+	return {
+		number: child.number,
+		title: context.titles.get(child.number),
+		kind: run_board_kind.kind_of(child.labels),
+		state,
+		status: undefined,
+		waits,
+	}
+}
+
+function started_of(row: BoardRow): number {
+	return row.status?.started_ms ?? Infinity
+}
+
+// Every child the run has touched, in the order each started.
+function active_rows(statuses: ReadonlyMap<number, ItemStatus>, read: RowRead): Array<BoardRow> {
+	const rows = [...statuses].map(([number, status]) => ({
+		number,
+		title: read.titles.get(number),
+		kind: run_board_kind.kind_of(read.labels.get(number)),
+		state: status.state,
+		status,
+		waits: [],
+	}))
+
+	return rows.toSorted((left, right) => started_of(left) - started_of(right))
+}
+
+// The epic row carries its own title, read from the same open listing as its children's — an opted-in
+// epic is an open issue.
+function place_in_epic(
+	entries: Array<WaveEntry>,
+	epic: number,
+	overlay: Overlay,
+	row: BoardRow,
+): void {
+	const group = entries.find((entry) => entry.kind === 'epic' && entry.epic === epic)
+	const title = overlay.plan.context.titles.get(epic)
+
+	if (group?.kind === 'epic') group.rows.push(row)
+	else entries.push({ kind: 'epic', epic, title, rows: [row] })
+}
+
+function is_untouched(child: EpicChild, overlay: Overlay): boolean {
+	return !overlay.statuses.has(child.number)
+}
+
+function is_human(child: EpicChild): boolean {
+	return has_label_name(child.labels, NEEDS_DECISION_LABEL)
+}
+
+// A wave row waits, unless it waits on a person's decision — the one wait the board marks.
+function wave_state(child: EpicChild): ItemState {
+	return is_human(child) ? 'human' : 'waiting'
+}
+
+// One wave, its rows in the plan's order, an epic's children gathered under the epic where the first
+// of them falls.
+function wave_entries(wave: ReadonlyArray<EpicChild>, overlay: Overlay): Array<WaveEntry> {
+	const entries: Array<WaveEntry> = []
+
+	for (const child of wave) {
+		const row = plan_row(child, wave_state(child), overlay)
+		const epic = overlay.plan.tracked.get(child.number)
+
+		if (epic === undefined) entries.push({ kind: 'row', row })
+		else place_in_epic(entries, epic, overlay, row)
+	}
+
+	return entries
+}
+
+function unreached_rows(overlay: Overlay, is_people: boolean): Array<BoardRow> {
+	const state: ItemState = is_people ? 'human' : 'waiting'
+
+	return overlay.plan.waves.unreached
+		.filter((child) => is_untouched(child, overlay) && is_human(child) === is_people)
+		.map((child) => plan_row(child, state, overlay))
+}
+
+function layout_of(plan: BoardPlan, statuses: ReadonlyMap<number, ItemStatus>): BoardLayout {
+	const overlay = { plan, statuses }
+	const waves = plan.waves.waves.map((wave) =>
+		wave_entries(
+			wave.filter((child) => is_untouched(child, overlay)),
+			overlay,
+		),
+	)
+
+	return {
+		active: active_rows(statuses, { titles: plan.context.titles, labels: plan.labels }),
+		waves: waves.filter((wave) => wave.length > 0),
+		people: unreached_rows(overlay, true),
+		unreached: unreached_rows(overlay, false),
+	}
+}
+
+const EMPTY_LAYOUT: BoardLayout = { active: [], waves: [], people: [], unreached: [] }
+
+// The run's own children before the plan is read: the stream and the lanes are local and read at
+// once, so the rows, their states and how long each has run are drawn while GitHub answers; the titles
+// and every issue the run has not touched wait for the plan.
+function local_layout_of(statuses: ReadonlyMap<number, ItemStatus>): BoardLayout {
+	return {
+		...EMPTY_LAYOUT,
+		active: active_rows(statuses, { titles: new Map(), labels: new Map() }),
+	}
+}
+
+// Every issue the plan holds, wave or unreached — the run's scope a lane is checked against.
+function numbers_of(plan: BoardPlan): ReadonlySet<number> {
+	return new Set([...plan.waves.waves.flat(), ...plan.waves.unreached].map((child) => child.number))
+}
+
+// Every row the layout draws, an epic's children among them — what the header counts and the legend reads.
+function rows_of(layout: BoardLayout): Array<BoardRow> {
+	const waves = layout.waves
+		.flat()
+		.flatMap((entry) => (entry.kind === 'row' ? [entry.row] : entry.rows))
+
+	return [...layout.active, ...waves, ...layout.people, ...layout.unreached]
+}
+
+const run_board_layout = {
+	EMPTY_LAYOUT,
+	is_settled,
+	layout_of,
+	local_layout_of,
+	numbers_of,
+	rows_of,
+}
+
+export { run_board_layout }
+export type { BoardLayout, BoardPlan, BoardRow, WaveEntry }

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

@@ -0,0 +1,31 @@
+// The issue numbers on `run:board` open their GitHub issue: each is wrapped in
+// an OSC 8 terminal hyperlink, so VSCode's terminal opens it on Cmd+click while the visible text stays
+// the number. A reference is drawn the way the plan names it — `3450` for this repository's issue,
+// `owner/repo#12` for one elsewhere — and links to the repository it names.
+//
+// The columns are padded on the text before it is linked: the escape draws nothing, but `padEnd`
+// counts it. Whether a terminal gets the escape at all is the `link` port's answer.
+
+const GITHUB_URL_PREFIX = 'https://github.com/'
+const QUALIFIED = /^(?<repo>[^#]+)#(?<number>\d+)$/u
+
+type Link = (text: string, url: string) => string
+
+// `owner/repo#12` names its own repository; a bare number names `repo`'s.
+function issue_url(reference: string, repo: string): string {
+	const { repo: target = repo, number = reference } = QUALIFIED.exec(reference)?.groups ?? {}
+
+	return `${GITHUB_URL_PREFIX}${target}/issues/${number}`
+}
+
+// A board with no plan read yet knows no repository, so its references stay plain text.
+function linker(repo: string | undefined, link: Link): (reference: string) => string {
+	if (repo === undefined) return (reference) => reference
+
+	return (reference) => link(reference, issue_url(reference, repo))
+}
+
+const run_board_link = { issue_url, linker }
+
+export { run_board_link }
+export type { Link }