Public: anyone can read this; the crew can change it.
Home shows median ship time: from the crew picking up an issue to the issue closing #14666
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14649-home-shows-median-ship-time-from-the-cre → main 11 commits fork 5 threads · 5 unresolved
docs/design/areas/home-flow.md +1
| @@ -43,4 +43,5 @@ One section under the lanes or the table (`web/pages/home_figures.ts`), an admin | ||
| 43 | 43 | - `.fg-body` — the figures' live region; holds one row of cards (172px, summed from the card's own rules) before they arrive, so nothing below moves. |
| 44 | 44 | - `.fg-card`, `.fg-label`, `.fg-value`, `.fg-n`, `.fg-unit`, `.fg-note` — a card: a name, the value with its unit, a note on two reserved lines so a row of cards is as tall as its tallest and nothing shifts. A card with a tone `attn` is the figure that is near or past a limit. |
| 45 | 45 | - `.fg-chart`, `.fg-svg`, `.fg-line`, `.fg-area`, `.fg-base`, `.fg-dot`, `.fg-axis` — the one chart: a line over a faint area in the accent, scaled from zero to the series' own peak, a day with no value breaking the line; its two ends named underneath (`14 days ago`, `today`); a card with no daily series keeps the same 32px, empty. |
| 46 | - `.fs`, `.fs-sum`, `.fs-svg`, `.fs-bar`, `.fs-count`, `.fs-base`, `.fs-h`, `.fs-slow`, `.fs-item`, `.fs-took`, `.fs-why`, `.fs-assume` — ship time under the cards (`web/pages/home_ship.ts`): a disclosure whose summary is the sentence (44px), a histogram drawn as SVG on the server in the muted foreground (seven fixed ranges, counts above the bars), the slowest tenth as a list of links with what the time went to, and the assumptions in a muted line. Closed by default; the live region reserves its row. | |
| 46 | 47 | - `.fg-reading` — the line a region shows before the first reading. |
docs/design/attention-budget.json +5 −5
| @@ -1,16 +1,16 @@ | ||
| 1 | 1 | { |
| 2 | 2 | "home": { |
| 3 | 3 | "390": { |
| 4 | "words": 297, | |
| 5 | "blocks": 50, | |
| 4 | "words": 324, | |
| 5 | "blocks": 54, | |
| 6 | 6 | "colours": 7 |
| 7 | 7 | }, |
| 8 | 8 | "1280": { |
| 9 | "words": 297, | |
| 10 | "blocks": 50, | |
| 9 | "words": 324, | |
| 10 | "blocks": 54, | |
| 11 | 11 | "colours": 7 |
| 12 | 12 | }, |
| 13 | "note": "Raised by 11 words and 1 block for the first-week line (To start: three links), shown to an admin in a forge's first week only (#13460)." | |
| 13 | "note": "Raised by 11 words and 1 block for the first-week line (To start: three links), shown to an admin in a forge's first week only (#13460); and by 27 words and 4 blocks for the Ship time card and its one-line disclosure (#14649)." | |
| 14 | 14 | }, |
| 15 | 15 | "repository": { |
| 16 | 16 | "390": { |
docs/features/ship-time.md added +13
| @@ -0,0 +1,13 @@ | ||
| 1 | --- | |
| 2 | topic: Ship and undo | |
| 3 | row: Ship time: how fast the forge ships an issue once the crew starts it: median, p90 and count over 7 days, with what the slowest tenth's time went to. | |
| 4 | --- | |
| 5 | # Ship time | |
| 6 | ||
| 7 | Home's figures (`src/web/pages/home_ship.ts`, admin) say it in one sentence: "Median ship time this week: 38 min (p90 3 h 10 min, 214 issues)." Open it for a histogram of ship times and, for the slowest tenth, what the time went to. The terminal says the same words on its dashboard (`src/tui/screens/dashboard.ts`) and in the palette's "Ship time" screen (`src/tui/screens/ship_time.ts`, admin), and `GET /api/v1/flow/ship-time` (admin; `?format=csv` for the histogram) returns the same reading, kept a minute. | |
| 8 | ||
| 9 | **Definition** (`src/flow/ship_time.ts`, one source for all three). From the start of the first crew run on an issue (`run.started_at`, kind agent) to the issue closing as done by a merged pull that says `Closes #N`. Time in the backlog before that run is not counted; issues closed as won't-do or duplicate, closed with no merged pull, or never run by the crew are left out. Over issues closed in the last 7 days. The median of an even count is the mean of the middle two; p90 is the nearest rank. | |
| 10 | ||
| 11 | **The slowest tenth** shows review (review runs, rounds of changes), checks (red checks, reworks), conflicts (conflicted pulls, resolve runs) and waiting (time queued or held by pace, valve or backoff). These are each work's own time and can overlap; work is what is left of the span. | |
| 12 | ||
| 13 | The issues are read through the `issue_closed_done` index (`test/ship-time.test.ts` shows the plan). |
src/contract/openapi/routes/getApiV1FlowShipTime.ts added +12
| @@ -0,0 +1,12 @@ | ||
| 1 | import type { Route } from "../shared.ts"; | |
| 2 | ||
| 3 | export const route: Route = { | |
| 4 | method: "get", | |
| 5 | path: "/api/v1/flow/ship-time", | |
| 6 | summary: "Median and slowest-tenth ship time since the crew started an issue (admin)", | |
| 7 | detail: | |
| 8 | "How fast the forge ships an issue once the crew starts it (a forge admin's, read scope): from the first crew run on an issue to its closing as done by a merged pull, over issues closed in the last 7 days; answers { sentence, days, count, medianMs, p90Ms, histogram, slowest } where slowest is the slowest tenth with the time each spent in review, checks, conflicts and waiting. ?format=csv answers the histogram as CSV", | |
| 9 | auth: true, | |
| 10 | role: "admin", | |
| 11 | refuses: [404], | |
| 12 | }; |
src/contract/openapi/routes/index.ts +1
| @@ -100,6 +100,7 @@ export { route as getApiV1FleetGraph } from "./getApiV1FleetGraph.ts"; | ||
| 100 | 100 | export { route as getApiV1FleetOps } from "./getApiV1FleetOps.ts"; |
| 101 | 101 | export { route as getApiV1FleetOpsId } from "./getApiV1FleetOpsId.ts"; |
| 102 | 102 | export { route as getApiV1FleetRows } from "./getApiV1FleetRows.ts"; |
| 103 | export { route as getApiV1FlowShipTime } from "./getApiV1FlowShipTime.ts"; | |
| 103 | 104 | export { route as getApiV1Forge } from "./getApiV1Forge.ts"; |
| 104 | 105 | export { route as getApiV1ForgeEconomics } from "./getApiV1ForgeEconomics.ts"; |
| 105 | 106 | export { route as getApiV1ForgeView } from "./getApiV1ForgeView.ts"; |
src/core/migration-pins/20261120120000-issue-closed-done.pin added +1
| @@ -0,0 +1,1 @@ | ||
| 1 | 0d995c8cfeb8ed72c70401b84b48726f30ccda7134f19085d7938b340273a2b5 |
src/core/migrations/20261120120000-issue-closed-done.ts added +7
| @@ -0,0 +1,7 @@ | ||
| 1 | // Home's ship time (#14649) reads the issues closed as done in the last 7 days. `closed_at` had no | |
| 2 | // index: the read would walk every issue of every repository. This one holds only the issues that | |
| 3 | // closed as done, in closing order, so the week is a range of it. Additive. | |
| 4 | export default ` | |
| 5 | CREATE INDEX IF NOT EXISTS issue_closed_done ON issue(closed_at) | |
| 6 | WHERE kind = 'issue' AND state = 'closed' AND close_reason = 'done'; | |
| 7 | `; |
src/flow/figures.ts +4
| @@ -13,6 +13,7 @@ | ||
| 13 | 13 | import type { Database } from "bun:sqlite"; |
| 14 | 14 | import { median } from "./pipeline.ts"; |
| 15 | 15 | import type { Kpis } from "./kpis.ts"; |
| 16 | import { readShipTime, type ShipTime } from "./ship_time.ts"; | |
| 16 | 17 | |
| 17 | 18 | /** Days the daily series cover, today last. */ |
| 18 | 19 | export const SERIES_DAYS = 14; |
| @@ -29,6 +30,8 @@ export interface Figures { | ||
| 29 | 30 | readonly spend: { readonly todayUsd: number; readonly ceilingUsd: number | null; readonly days: readonly number[]; readonly totalUsd: number }; |
| 30 | 31 | /** How long a finished check took: the median over 24 h and per UTC day (null for a day with none). */ |
| 31 | 32 | readonly checks: { readonly medianMs: number | null; readonly days: readonly (number | null)[] }; |
| 33 | /** From the crew's first run on an issue to its closing as done, over 7 days (`ship_time.ts`). */ | |
| 34 | readonly ship: ShipTime; | |
| 32 | 35 | readonly bugs: { readonly open: number; readonly overdue: number } | null; |
| 33 | 36 | readonly backup: { readonly at: string | null; readonly state: "green" | "red" | "unknown" | null; readonly note: string }; |
| 34 | 37 | } |
| @@ -88,6 +91,7 @@ export function readFigures(db: Database, now: Date, kpis: Kpis): Figures { | ||
| 88 | 91 | shipped: { days: shipped, total: shipped.reduce((a, b) => a + b, 0) }, |
| 89 | 92 | spend: { todayUsd: kpis.spend.todayUsd, ceilingUsd: kpis.spend.ceilingUsd, days: spend, totalUsd: spend.reduce((a, b) => a + b, 0) }, |
| 90 | 93 | checks: { medianMs: kpis.medianCheckMs, days: keys.map((k) => median(took.get(k) ?? [])) }, |
| 94 | ship: readShipTime(db, now), | |
| 91 | 95 | bugs: kpis.bugs === undefined ? null : { open: kpis.bugs.open, overdue: kpis.bugs.overdue }, |
| 92 | 96 | backup: { at: kpis.backupAt, state: backupState, note: kpis.backup?.note ?? "" }, |
| 93 | 97 | }; |
src/flow/ship_cache.ts added +20
| @@ -0,0 +1,20 @@ | ||
| 1 | /** | |
| 2 | * Ship time kept a minute (#14649) for the readers that are not the lanes' worker: the API and the | |
| 3 | * terminal. One answer per database, read again past 60 s; nothing is kept inside a transaction. | |
| 4 | */ | |
| 5 | ||
| 6 | import type { Database } from "bun:sqlite"; | |
| 7 | import { readShipTime, type ShipTime } from "./ship_time.ts"; | |
| 8 | ||
| 9 | export const SHIP_TTL_MS = 60_000; | |
| 10 | ||
| 11 | const kept = new WeakMap<Database, { at: number; value: ShipTime }>(); | |
| 12 | ||
| 13 | export function cachedShipTime(db: Database, now: Date = new Date()): ShipTime { | |
| 14 | if (db.inTransaction) return readShipTime(db, now); | |
| 15 | const k = kept.get(db); | |
| 16 | if (k !== undefined && now.getTime() - k.at >= 0 && now.getTime() - k.at < SHIP_TTL_MS) return k.value; | |
| 17 | const value = readShipTime(db, now); | |
| 18 | kept.set(db, { at: now.getTime(), value }); | |
| 19 | return value; | |
| 20 | } |
src/flow/ship_time.ts added +265
| @@ -0,0 +1,265 @@ | ||
| 1 | /** | |
| 2 | * Ship time (#14649): how fast the forge ships an issue once work starts. | |
| 3 | * | |
| 4 | * Definition. For an issue, from the start of the first crew run on it | |
| 5 | * (`run.started_at`, kind `agent`) to the issue closing as done (`closed_at`, `close_reason` | |
| 6 | * `done`) by a merged pull whose description says `Closes #N`. Time before the first crew run (the | |
| 7 | * backlog) is never counted; an issue closed as dropped, split or parked, closed with no merged | |
| 8 | * pull behind it, or never picked up by the crew is not counted at all. The figure is over the | |
| 9 | * issues that closed in the last 7 days, in every repository. | |
| 10 | * | |
| 11 | * Statistics. The median of an even count is the mean of the middle two (as `lead_time.ts`); p90 is | |
| 12 | * the nearest rank: the value at position ceil(0.9 n) of the sorted times. | |
| 13 | * | |
| 14 | * The slowest decile (ceil(n / 10) issues, the slowest first) is broken down by what the time went | |
| 15 | * to, read from the runs and reviews the forge already records on the issue and on the pulls that | |
| 16 | * close it. Each category is that work's own time, clipped to the span from the first crew run to | |
| 17 | * the close, so categories can overlap (a check runs beside a rework) and `workMs` is what is left | |
| 18 | * of the span after them, never negative: | |
| 19 | * - review: runs with reason `review` (started to finished), and `changes_requested` verdicts; | |
| 20 | * - check: failed checks and `check_failed` reworks (their own durations); | |
| 21 | * - conflict: runs with reason `conflict` or `resolve`, and the pulls they ran on; | |
| 22 | * - waiting: for each run, from the later of its creation and the first crew run to its start, | |
| 23 | * which is time queued or held (pace, valve, clone backoff) and not work. | |
| 24 | * | |
| 25 | * Plain data in, plain data out: one query for the issues, one for the merged pulls, and, for the | |
| 26 | * slow decile only, one per kind for their pulls, runs and reviews. Nothing here reads the clock. | |
| 27 | */ | |
| 28 | ||
| 29 | import type { Database } from "bun:sqlite"; | |
| 30 | import { closesFromBody } from "../core/pulls.ts"; | |
| 31 | ||
| 32 | const DAY_MS = 86_400_000; | |
| 33 | export const SHIP_DAYS = 7; | |
| 34 | /** Histogram bars; the edges are fixed so two readings compare. */ | |
| 35 | export const SHIP_EDGES_MS = [ | |
| 36 | 15 * 60_000, | |
| 37 | 30 * 60_000, | |
| 38 | 60 * 60_000, | |
| 39 | 2 * 3_600_000, | |
| 40 | 4 * 3_600_000, | |
| 41 | 8 * 3_600_000, | |
| 42 | 24 * 3_600_000, | |
| 43 | ] as const; | |
| 44 | ||
| 45 | export interface ShipBar { | |
| 46 | /** Inclusive lower edge in ms; the upper is the next bar's, null for the last (open) bar. */ | |
| 47 | readonly fromMs: number; | |
| 48 | readonly toMs: number | null; | |
| 49 | readonly count: number; | |
| 50 | } | |
| 51 | ||
| 52 | export interface SlowIssue { | |
| 53 | readonly path: string; | |
| 54 | readonly repo: string; | |
| 55 | readonly number: number; | |
| 56 | readonly title: string; | |
| 57 | readonly shipMs: number; | |
| 58 | readonly reviewMs: number; | |
| 59 | readonly reviewRuns: number; | |
| 60 | readonly changesRequested: number; | |
| 61 | readonly checkMs: number; | |
| 62 | readonly redChecks: number; | |
| 63 | readonly reworks: number; | |
| 64 | readonly conflictMs: number; | |
| 65 | readonly conflictRuns: number; | |
| 66 | readonly conflictedPulls: number; | |
| 67 | readonly waitingMs: number; | |
| 68 | readonly workMs: number; | |
| 69 | } | |
| 70 | ||
| 71 | export interface ShipTime { | |
| 72 | readonly days: number; | |
| 73 | readonly count: number; | |
| 74 | readonly medianMs: number | null; | |
| 75 | readonly p90Ms: number | null; | |
| 76 | readonly histogram: readonly ShipBar[]; | |
| 77 | /** The slowest decile, slowest first. */ | |
| 78 | readonly slowest: readonly SlowIssue[]; | |
| 79 | } | |
| 80 | ||
| 81 | /** Median of a sorted list; null for none. */ | |
| 82 | export function medianOf(sorted: readonly number[]): number | null { | |
| 83 | const n = sorted.length; | |
| 84 | if (n === 0) return null; | |
| 85 | return n % 2 ? sorted[n >> 1]! : (sorted[n / 2 - 1]! + sorted[n / 2]!) / 2; | |
| 86 | } | |
| 87 | ||
| 88 | /** Nearest-rank percentile (0 < p <= 1) of a sorted list; null for none. */ | |
| 89 | export function percentileOf(sorted: readonly number[], p: number): number | null { | |
| 90 | if (sorted.length === 0) return null; | |
| 91 | return sorted[Math.min(sorted.length, Math.max(1, Math.ceil(p * sorted.length))) - 1]!; | |
| 92 | } | |
| 93 | ||
| 94 | /** Ship times counted into the fixed bars. */ | |
| 95 | export function bars(times: readonly number[]): ShipBar[] { | |
| 96 | const out: ShipBar[] = [{ fromMs: 0, toMs: SHIP_EDGES_MS[0], count: 0 }]; | |
| 97 | SHIP_EDGES_MS.forEach((from, i) => out.push({ fromMs: from, toMs: SHIP_EDGES_MS[i + 1] ?? null, count: 0 })); | |
| 98 | const counts = out.map(() => 0); | |
| 99 | for (const t of times) { | |
| 100 | let at = out.length - 1; | |
| 101 | for (let i = 0; i < out.length; i++) { | |
| 102 | const to = out[i]!.toMs; | |
| 103 | if (to !== null && t < to) { | |
| 104 | at = i; | |
| 105 | break; | |
| 106 | } | |
| 107 | } | |
| 108 | counts[at]!++; | |
| 109 | } | |
| 110 | return out.map((b, i) => ({ ...b, count: counts[i]! })); | |
| 111 | } | |
| 112 | ||
| 113 | interface Closed { | |
| 114 | readonly id: string; | |
| 115 | readonly repo_id: string; | |
| 116 | readonly number: number; | |
| 117 | readonly title: string; | |
| 118 | readonly closed_at: string; | |
| 119 | readonly first_start: string | null; | |
| 120 | readonly owner: string; | |
| 121 | readonly name: string; | |
| 122 | } | |
| 123 | ||
| 124 | interface Pull { | |
| 125 | readonly id: string; | |
| 126 | readonly repo_id: string; | |
| 127 | readonly number: number; | |
| 128 | readonly body: string; | |
| 129 | readonly merged_at: string | null; | |
| 130 | } | |
| 131 | ||
| 132 | const ms = (iso: string | null): number => (iso === null ? NaN : Date.parse(iso)); | |
| 133 | ||
| 134 | /** The issues closed as done in the window that a merged pull closed, with their ship time. */ | |
| 135 | function shipped(db: Database, since: string, to: string): { issue: Closed; shipMs: number }[] { | |
| 136 | const issues = db | |
| 137 | .query<Closed, [string, string]>( | |
| 138 | `SELECT i.id, i.repo_id, i.number, i.title, i.closed_at, o.username AS owner, r.name, | |
| 139 | (SELECT MIN(x.started_at) FROM run x | |
| 140 | WHERE x.issue_id = i.id AND x.kind = 'agent' AND x.started_at IS NOT NULL) AS first_start | |
| 141 | FROM issue i INDEXED BY issue_closed_done | |
| 142 | JOIN repo r ON r.id = i.repo_id JOIN user o ON o.id = r.owner_id | |
| 143 | WHERE i.kind = 'issue' AND i.state = 'closed' AND i.close_reason = 'done' AND i.sealed = 0 | |
| 144 | AND i.closed_at >= ?1 AND i.closed_at <= ?2`, | |
| 145 | ) | |
| 146 | .all(since, to); | |
| 147 | if (issues.length === 0) return []; | |
| 148 | // The pull that closes an issue merges at or after the crew's first run and before the issue is | |
| 149 | // read as closed; a day of slack before the window covers a merge just ahead of it. | |
| 150 | const merged = db | |
| 151 | .query<Pull, [string]>( | |
| 152 | `SELECT q.id, q.repo_id, q.number, q.body, p.merged_at | |
| 153 | FROM pull p INDEXED BY pull_merged JOIN issue q ON q.id = p.issue_id | |
| 154 | WHERE p.merged_at >= ?1`, | |
| 155 | ) | |
| 156 | .all(new Date(Date.parse(since) - DAY_MS).toISOString()); | |
| 157 | const closers = new Map<string, number[]>(); | |
| 158 | for (const p of merged) { | |
| 159 | for (const n of closesFromBody(p.body ?? "")) { | |
| 160 | const key = `${p.repo_id}#${n}`; | |
| 161 | const at = ms(p.merged_at); | |
| 162 | const list = closers.get(key); | |
| 163 | if (list === undefined) closers.set(key, [at]); | |
| 164 | else list.push(at); | |
| 165 | } | |
| 166 | } | |
| 167 | const out: { issue: Closed; shipMs: number }[] = []; | |
| 168 | for (const issue of issues) { | |
| 169 | const start = ms(issue.first_start); | |
| 170 | const end = ms(issue.closed_at); | |
| 171 | if (Number.isNaN(start) || Number.isNaN(end)) continue; | |
| 172 | // A merged pull must stand behind the close, and not have landed before the crew began. | |
| 173 | if (!(closers.get(`${issue.repo_id}#${issue.number}`) ?? []).some((at) => at >= start)) continue; | |
| 174 | out.push({ issue, shipMs: Math.max(0, end - start) }); | |
| 175 | } | |
| 176 | return out; | |
| 177 | } | |
| 178 | ||
| 179 | const CHUNK = 200; | |
| 180 | ||
| 181 | /** What one slow issue's time went to. */ | |
| 182 | function breakdown(db: Database, issue: Closed, shipMs: number): SlowIssue { | |
| 183 | const start = ms(issue.first_start); | |
| 184 | const end = ms(issue.closed_at); | |
| 185 | const clip = (a: number, b: number): number => Math.max(0, Math.min(b, end) - Math.max(a, start)); | |
| 186 | // Every pull of this repository after the issue that says it closes it, merged or not. | |
| 187 | const pulls = db | |
| 188 | .query<Pull, [string, number, string]>( | |
| 189 | `SELECT id, repo_id, number, body, NULL AS merged_at FROM issue | |
| 190 | WHERE repo_id = ?1 AND kind = 'pull' AND number > ?2 AND created_at <= ?3 | |
| 191 | ORDER BY number DESC LIMIT 500`, | |
| 192 | ) | |
| 193 | .all(issue.repo_id, issue.number, issue.closed_at) | |
| 194 | .filter((p) => closesFromBody(p.body ?? "").includes(issue.number)); | |
| 195 | const ids = [issue.id, ...pulls.map((p) => p.id)]; | |
| 196 | const pullIds = new Set(pulls.map((p) => p.id)); | |
| 197 | let reviewMs = 0, reviewRuns = 0, checkMs = 0, redChecks = 0, reworks = 0; | |
| 198 | let conflictMs = 0, conflictRuns = 0, waitingMs = 0, changesRequested = 0; | |
| 199 | const conflicted = new Set<string>(); | |
| 200 | for (let i = 0; i < ids.length; i += CHUNK) { | |
| 201 | const part = ids.slice(i, i + CHUNK); | |
| 202 | const marks = part.map(() => "?").join(","); | |
| 203 | const runs = db | |
| 204 | .query<{ issue_id: string; kind: string; reason: string; state: string; created_at: string; started_at: string | null; finished_at: string | null }, string[]>( | |
| 205 | `SELECT issue_id, kind, reason, state, created_at, started_at, finished_at FROM run | |
| 206 | WHERE issue_id IN (${marks}) AND kind IN ('agent','check')`, | |
| 207 | ) | |
| 208 | .all(...part); | |
| 209 | for (const r of runs) { | |
| 210 | const began = ms(r.started_at); | |
| 211 | if (Number.isNaN(began)) continue; | |
| 212 | const own = clip(began, Number.isNaN(ms(r.finished_at)) ? end : ms(r.finished_at)); | |
| 213 | waitingMs += clip(ms(r.created_at), began); | |
| 214 | if (r.kind === "check") { | |
| 215 | if (r.state === "failed") (redChecks++, (checkMs += own)); | |
| 216 | } else if (r.reason === "review") (reviewRuns++, (reviewMs += own)); | |
| 217 | else if (r.reason === "check_failed") (reworks++, (checkMs += own)); | |
| 218 | else if (r.reason === "conflict" || r.reason === "resolve") { | |
| 219 | conflictRuns++; | |
| 220 | conflictMs += own; | |
| 221 | if (pullIds.has(r.issue_id)) conflicted.add(r.issue_id); | |
| 222 | } | |
| 223 | } | |
| 224 | changesRequested += | |
| 225 | db | |
| 226 | .query<{ n: number }, string[]>( | |
| 227 | `SELECT COUNT(*) AS n FROM review WHERE issue_id IN (${marks}) AND state = 'changes_requested'`, | |
| 228 | ) | |
| 229 | .get(...part)?.n ?? 0; | |
| 230 | } | |
| 231 | return { | |
| 232 | path: `/${encodeURIComponent(issue.owner)}/${encodeURIComponent(issue.name)}/issues/${issue.number}`, | |
| 233 | repo: `${issue.owner}/${issue.name}`, | |
| 234 | number: issue.number, | |
| 235 | title: issue.title, | |
| 236 | shipMs, | |
| 237 | reviewMs, | |
| 238 | reviewRuns, | |
| 239 | changesRequested, | |
| 240 | checkMs, | |
| 241 | redChecks, | |
| 242 | reworks, | |
| 243 | conflictMs, | |
| 244 | conflictRuns, | |
| 245 | conflictedPulls: conflicted.size, | |
| 246 | waitingMs, | |
| 247 | workMs: Math.max(0, shipMs - reviewMs - checkMs - conflictMs - waitingMs), | |
| 248 | }; | |
| 249 | } | |
| 250 | ||
| 251 | export function readShipTime(db: Database, now: Date): ShipTime { | |
| 252 | const to = now.toISOString(); | |
| 253 | const since = new Date(now.getTime() - SHIP_DAYS * DAY_MS).toISOString(); | |
| 254 | const rows = shipped(db, since, to); | |
| 255 | const times = rows.map((r) => r.shipMs).sort((a, b) => a - b); | |
| 256 | const slow = [...rows].sort((a, b) => b.shipMs - a.shipMs || a.issue.number - b.issue.number).slice(0, Math.ceil(rows.length / 10)); | |
| 257 | return { | |
| 258 | days: SHIP_DAYS, | |
| 259 | count: times.length, | |
| 260 | medianMs: medianOf(times), | |
| 261 | p90Ms: percentileOf(times, 0.9), | |
| 262 | histogram: bars(times), | |
| 263 | slowest: slow.map((r) => breakdown(db, r.issue, r.shipMs)), | |
| 264 | }; | |
| 265 | } |
src/flow/ship_words.ts added +50
| @@ -0,0 +1,50 @@ | ||
| 1 | /** | |
| 2 | * Ship time in the forge's own words (#14649), shared by home, the terminal and the API: plain data | |
| 3 | * in, plain strings out. | |
| 4 | */ | |
| 5 | ||
| 6 | import type { ShipTime, SlowIssue } from "./ship_time.ts"; | |
| 7 | ||
| 8 | /** A span as a person says it: `38 min`, `3 h 10 min`, `2 d 4 h`; under a minute, `under 1 min`. */ | |
| 9 | export function shipSpan(ms: number): string { | |
| 10 | const min = Math.round(ms / 60_000); | |
| 11 | if (min < 1) return "under 1 min"; | |
| 12 | if (min < 60) return `${min} min`; | |
| 13 | const h = Math.floor(min / 60); | |
| 14 | if (h < 24) return min % 60 === 0 ? `${h} h` : `${h} h ${min % 60} min`; | |
| 15 | const d = Math.floor(h / 24); | |
| 16 | return h % 24 === 0 ? `${d} d` : `${d} d ${h % 24} h`; | |
| 17 | } | |
| 18 | ||
| 19 | /** The sentence: "Median ship time this week: 38 min (p90 3 h 10 min, 214 issues)." */ | |
| 20 | export function shipSentence(s: Pick<ShipTime, "count" | "medianMs" | "p90Ms">): string { | |
| 21 | if (s.count === 0 || s.medianMs === null || s.p90Ms === null) | |
| 22 | return "Median ship time this week: no issue the crew started has shipped yet."; | |
| 23 | return `Median ship time this week: ${shipSpan(s.medianMs)} (p90 ${shipSpan(s.p90Ms)}, ${s.count} ${s.count === 1 ? "issue" : "issues"}).`; | |
| 24 | } | |
| 25 | ||
| 26 | /** The bar's range: `under 15 min`, `1 h to 2 h`, `1 d or more`. */ | |
| 27 | export function barWords(fromMs: number, toMs: number | null): string { | |
| 28 | if (fromMs === 0 && toMs !== null) return `under ${shipSpan(toMs)}`; | |
| 29 | if (toMs === null) return `${shipSpan(fromMs)} or more`; | |
| 30 | return `${shipSpan(fromMs)} to ${shipSpan(toMs)}`; | |
| 31 | } | |
| 32 | ||
| 33 | /** What a slow issue's time went to, one line: review, check, conflict and waiting named. */ | |
| 34 | export function slowLine(i: SlowIssue): string { | |
| 35 | const plural = (n: number, one: string, many: string): string => `${n} ${n === 1 ? one : many}`; | |
| 36 | return [ | |
| 37 | `review ${shipSpan(i.reviewMs)} (${plural(i.reviewRuns, "run", "runs")}, ${plural(i.changesRequested, "round of changes", "rounds of changes")})`, | |
| 38 | `checks ${shipSpan(i.checkMs)} (${plural(i.redChecks, "red check", "red checks")}, ${plural(i.reworks, "rework", "reworks")})`, | |
| 39 | `conflicts ${shipSpan(i.conflictMs)} (${plural(i.conflictedPulls, "conflicted pull", "conflicted pulls")}, ${plural(i.conflictRuns, "resolve run", "resolve runs")})`, | |
| 40 | `waiting ${shipSpan(i.waitingMs)} queued or held`, | |
| 41 | ].join(" · "); | |
| 42 | } | |
| 43 | ||
| 44 | /** The terminal's lines: the sentence, then the slowest few and what their time went to. */ | |
| 45 | export function shipLines(s: ShipTime, slowest = 3): string[] { | |
| 46 | return [ | |
| 47 | shipSentence(s), | |
| 48 | ...s.slowest.slice(0, slowest).map((i) => ` ${i.repo}#${i.number} ${shipSpan(i.shipMs)}: ${slowLine(i)}`), | |
| 49 | ]; | |
| 50 | } |
src/http/api.ts +2
| @@ -382,6 +382,7 @@ import { schedulesRoutes } from "./api/schedules.ts"; | ||
| 382 | 382 | import { forgeRoutes } from "./api/forges.ts"; |
| 383 | 383 | import { packRoutes } from "./api/packs.ts"; |
| 384 | 384 | import { forgeViewRoutes } from "./api/forge_view.ts"; |
| 385 | import { shipTimeRoutes } from "./api/ship_time.ts"; | |
| 385 | 386 | import { billingRoutes } from "./api/billing.ts"; |
| 386 | 387 | import { codesRoutes } from "./api/codes.ts"; |
| 387 | 388 | import { economicsRoutes } from "./api/economics.ts"; |
| @@ -3857,6 +3858,7 @@ export function apiRoutes(router: Router<Handler>, isPage: (path: string) => boo | ||
| 3857 | 3858 | forgeRoutes(router); |
| 3858 | 3859 | packRoutes(router); |
| 3859 | 3860 | forgeViewRoutes(router); |
| 3861 | shipTimeRoutes(router); | |
| 3860 | 3862 | economicsRoutes(router); |
| 3861 | 3863 | billingRoutes(router); |
| 3862 | 3864 | codesRoutes(router); |
src/http/api/ship_time.ts added +31
| @@ -0,0 +1,31 @@ | ||
| 1 | /** | |
| 2 | * GET /api/v1/flow/ship-time: how fast the forge ships an issue once the crew starts it (#14649), | |
| 3 | * the same `readShipTime` home and the terminal read, kept a minute. Forge-wide, so a forge admin's | |
| 4 | * alone; anyone else is told it is not there. `?format=csv` is the histogram as CSV. | |
| 5 | */ | |
| 6 | import { notePhase, takeSessionTime } from "../../core/route_timing.ts"; | |
| 7 | import { cachedShipTime } from "../../flow/ship_cache.ts"; | |
| 8 | import { shipSentence } from "../../flow/ship_words.ts"; | |
| 9 | import type { Handler } from "../context.ts"; | |
| 10 | import { notFound, requireScope } from "../respond.ts"; | |
| 11 | import type { Router } from "../router.ts"; | |
| 12 | ||
| 13 | export function shipTimeRoutes(router: Router<Handler>): void { | |
| 14 | router.add("GET", "/api/v1/flow/ship-time", (ctx) => { | |
| 15 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); | |
| 16 | if (ctx.auth.user?.isAdmin !== true) return notFound(); | |
| 17 | const denied = requireScope(ctx, "ro"); | |
| 18 | if (denied) return denied; | |
| 19 | const ship = cachedShipTime(ctx.app.db); | |
| 20 | const headers = { "cache-control": "private, max-age=60", vary: "authorization, cookie" }; | |
| 21 | if (new URL(ctx.request.url).searchParams.get("format") === "csv") { | |
| 22 | const rows = ship.histogram.map((b) => `${b.fromMs},${b.toMs ?? ""},${b.count}`); | |
| 23 | return new Response(["from_ms,to_ms,issues", ...rows].join("\n") + "\n", { | |
| 24 | headers: { "content-type": "text/csv; charset=utf-8", ...headers }, | |
| 25 | }); | |
| 26 | } | |
| 27 | return new Response(JSON.stringify({ sentence: shipSentence(ship), ...ship }), { | |
| 28 | headers: { "content-type": "application/json", ...headers }, | |
| 29 | }); | |
| 30 | }); | |
| 31 | } |
src/http/marks/api-v1-flow.json added +4
| @@ -0,0 +1,4 @@ | ||
| 1 | { | |
| 2 | "head": "/api/v1/flow", | |
| 3 | "mark": "admin" | |
| 4 | } |
src/tui/screens/dashboard.ts +2
| @@ -120,6 +120,7 @@ import { | ||
| 120 | 120 | import { readVitals, vitalsLine } from "../../flow/vitals.ts"; |
| 121 | 121 | import { readKpis } from "../../flow/kpis.ts"; |
| 122 | 122 | import { kpiLines } from "../../flow/kpi_words.ts"; |
| 123 | import { shipTimeLines } from "./ship_time.ts"; | |
| 123 | 124 | import { BOOTED } from "../../release/gate.ts"; |
| 124 | 125 | import { running } from "../../kernel/version.ts"; |
| 125 | 126 | import { deciderLine, deciderScreen } from "./decider.ts"; |
| @@ -514,6 +515,7 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen { | ||
| 514 | 515 | ...idleLines(f.app, now), |
| 515 | 516 | ...weekBlock(f.app, now), |
| 516 | 517 | ...kpiLines(readKpis(f.db, now, { ...kpiForge(f.app), idle: () => idleReason(f.app, now) }), commit === null ? null : { sha: commit, since: ago(BOOTED) }), |
| 518 | ...shipTimeLines(f.db, now), | |
| 517 | 519 | vitalsLine(readVitals(f.db, now)), |
| 518 | 520 | ...firedAlarms(f.db, now, { ceilingUsd: forgeCeiling(f.app.config), dataDir: f.app.config.dataDir }).map((a) => a.says), |
| 519 | 521 | ...(cleared === undefined ? [] : [cleared]), |
src/tui/screens/ship_time.ts added +54
| @@ -0,0 +1,54 @@ | ||
| 1 | /** | |
| 2 | * Ship time, from the palette (admins): the same reading as home's figure and | |
| 3 | * GET /api/v1/flow/ship-time (`cachedShipTime`), the sentence, then every slowest issue | |
| 4 | * and what its time went to. Read-only. | |
| 5 | */ | |
| 6 | ||
| 7 | import type { Database } from "bun:sqlite"; | |
| 8 | import { cachedShipTime } from "../../flow/ship_cache.ts"; | |
| 9 | import { shipLines } from "../../flow/ship_words.ts"; | |
| 10 | import type { Ctx, Screen } from "../app/app.ts"; | |
| 11 | import { binding } from "../app/keys.ts"; | |
| 12 | import type { Session } from "../session.ts"; | |
| 13 | import { style } from "../term/style.ts"; | |
| 14 | import { Scroll, drawLines, hitScroll } from "./common.ts"; | |
| 15 | import type { PaletteEntry } from "./entries.ts"; | |
| 16 | ||
| 17 | /** The lines the dashboard and this screen share: the sentence, then the slowest issues. */ | |
| 18 | export function shipTimeLines(db: Database, now: Date, slowest = 3): string[] { | |
| 19 | return shipLines(cachedShipTime(db, now), slowest); | |
| 20 | } | |
| 21 | ||
| 22 | export function shipTimeScreen(ctx: Ctx, lines: readonly string[]): Screen { | |
| 23 | const scroll = new Scroll(); | |
| 24 | return { | |
| 25 | title: "Ship time", | |
| 26 | keys: [binding(["j", "k"], "scroll"), binding(["esc", "q"], "back")], | |
| 27 | render(area, s) { | |
| 28 | const c = ctx.theme.c; | |
| 29 | const spans = lines.map((text) => [{ text, style: style(text.startsWith(" ") ? c.mutedFg : c.fg, c.bg) }]); | |
| 30 | drawLines(s, area, c, scroll, spans); | |
| 31 | hitScroll(ctx, area, scroll, lines.length); | |
| 32 | }, | |
| 33 | key(e) { | |
| 34 | if (scroll.key(e, lines.length)) return true; | |
| 35 | if (e.key === "esc" || e.key === "q") { | |
| 36 | ctx.pop(); | |
| 37 | return true; | |
| 38 | } | |
| 39 | return false; | |
| 40 | }, | |
| 41 | }; | |
| 42 | } | |
| 43 | ||
| 44 | export const entry: PaletteEntry = { | |
| 45 | rank: 185, | |
| 46 | id: "ship-time", | |
| 47 | title: "Ship time", | |
| 48 | hint: "median time from the crew's first run to done", | |
| 49 | after: ["refused-asks"], | |
| 50 | offered: (session: Session) => session.user?.isAdmin === true, | |
| 51 | run: (session, ctx) => { | |
| 52 | ctx.push(shipTimeScreen(ctx, shipTimeLines(session.db, new Date(), 10))); | |
| 53 | }, | |
| 54 | }; |
src/web/pages/home_figures.ts +2
| @@ -23,6 +23,7 @@ import { | ||
| 23 | 23 | import type { Figures } from "../../flow/figures.ts"; |
| 24 | 24 | import type { LanePicture } from "../../flow/lanes.ts"; |
| 25 | 25 | import { html, raw, type Html } from "../html.ts"; |
| 26 | import { shipSection } from "./home_ship.ts"; | |
| 26 | 27 | |
| 27 | 28 | /** The events that change a figure; they change by the minute, so these are few. */ |
| 28 | 29 | export const FIGURES_LIVE = |
| @@ -260,6 +261,7 @@ export function figuresGrid(picture: LanePicture, now: number): Html { | ||
| 260 | 261 | data-live-src="/live/figures" |
| 261 | 262 | > |
| 262 | 263 | <div class="fg-grid">${cards(f, now).map(card)}</div> |
| 264 | ${shipSection(f.ship)} | |
| 263 | 265 | </div>`; |
| 264 | 266 | } |
| 265 | 267 |
src/web/pages/home_flow_style.ts +14 −2
| @@ -244,9 +244,21 @@ a.fg-card:hover { border-color: var(--border-strong); color: var(--fg); } | ||
| 244 | 244 | .lane[data-reading] { padding-bottom: 64px; } |
| 245 | 245 | /* A table: its header row and one row, each 44px (.tb-pick), and the gap. */ |
| 246 | 246 | .tb-region[data-reading] { min-height: calc(44px + 8px + 44px); } |
| 247 | /* A figures card: border 2 + padding 24 + label 18 + gap 4 + value 28 + gap 4 | |
| 247 | /* A figures card (and the ship time disclosure under them, 12 + 44): border 2 + padding 24 + label 18 + gap 4 + value 28 + gap 4 | |
| 248 | 248 | + note 32 + gap 4 + chart (4 + 32) + gap 4 + axis 16 = 172px, one row. */ |
| 249 | .fg-body { min-height: 172px; } | |
| 249 | .fg-body { min-height: 228px; } | |
| 250 | /* Ship time (#14649), under the cards: the disclosure's summary is 44px, a gap of 12px above it. */ | |
| 251 | .fs { margin-top: 12px; } | |
| 252 | .fs-sum { min-height: 44px; display: flex; align-items: center; cursor: pointer; font-weight: 600; } | |
| 253 | .fs-svg { display: block; width: 100%; max-width: 480px; height: auto; aspect-ratio: 320 / 96; } | |
| 254 | .fs-bar { fill: var(--muted-fg); } | |
| 255 | .fs-count { font-size: var(--fs-min); fill: var(--muted-fg); font-variant-numeric: tabular-nums; } | |
| 256 | .fs-base { stroke: var(--border); stroke-width: 1; } | |
Principle 5: |
||
| 257 | .fs-h { margin: 12px 0 4px; font-size: var(--fs-min); font-weight: 400; color: var(--muted-fg); } | |
| 258 | .fs-slow { margin: 0; padding: 0; list-style: none; display: grid; gap: 8px; } | |
| 259 | .fs-item { display: flex; flex-direction: column; gap: 2px; min-width: 0; } | |
| 260 | .fs-took, .fs-why, .fs-assume { font-size: var(--fs-min); line-height: 16px; color: var(--muted-fg); } | |
| 261 | .fs-assume { margin: 12px 0 0; } | |
| 250 | 262 | |
| 251 | 263 | /* ---- the box that tells the crew, kept to one row on a desk ---- */ |
| 252 | 264 | .hf-tell { display: flex; flex-wrap: wrap; align-items: center; gap: 0 16px; } |
src/web/pages/home_ship.ts added +61
| @@ -0,0 +1,61 @@ | ||
| 1 | /** | |
| 2 | * Ship time under the figures (#14649): the sentence as the summary of one disclosure, and inside | |
| 3 | * it a histogram drawn as SVG on the server (no script, no chart library) and, for the slowest | |
| 4 | * decile, what each one's time went to, each linked to its issue. The data is `flow/ship_time.ts`, | |
| 5 | * the definition is in its header and shown here as the assumptions. | |
| 6 | */ | |
| 7 | ||
| 8 | import type { ShipTime } from "../../flow/ship_time.ts"; | |
| 9 | import { barWords, shipSentence, shipSpan, slowLine } from "../../flow/ship_words.ts"; | |
| 10 | import { html, type Html } from "../html.ts"; | |
| 11 | ||
| 12 | const W = 320; | |
| 13 | const H = 96; | |
| 14 | ||
| 15 | /** | |
| 16 | * The histogram: one bar per fixed range, scaled to the fullest, its count above and its range | |
| 17 | * named in the title. | |
| 18 | */ | |
| 19 | export function histogramSvg(s: ShipTime): Html { | |
| 20 | const top = Math.max(1, ...s.histogram.map((b) => b.count)); | |
| 21 | const slot = W / s.histogram.length; | |
| 22 | const bars = s.histogram.map((b, i) => { | |
| 23 | const h = Math.round((b.count / top) * (H - 20)); | |
| 24 | const x = (i * slot + 3).toFixed(1); | |
| 25 | return html`<g> | |
| 26 | <title>${barWords(b.fromMs, b.toMs)}: ${b.count}</title> | |
| 27 | <rect class="fs-bar" x="${x}" y="${H - 4 - h}" width="${(slot - 6).toFixed(1)}" height="${h}" /> | |
| 28 | <text class="fs-count" x="${(i * slot + slot / 2).toFixed(1)}" y="${H - 7 - h}" text-anchor="middle">${b.count}</text> | |
| 29 | </g>`; | |
| 30 | }); | |
| 31 | return html`<svg class="fs-svg" viewBox="0 0 ${W} ${H}" role="img" | |
| 32 | aria-label="Ship times of ${s.count} issues, in ${s.histogram.length} ranges from under ${shipSpan(s.histogram[0]!.toMs ?? 0)} to ${shipSpan(s.histogram[s.histogram.length - 1]!.fromMs)} or more"> | |
| 33 | <line class="fs-base" x1="0" y1="${H - 3.5}" x2="${W}" y2="${H - 3.5}" />${bars} | |
| 34 | </svg>`; | |
| 35 | } | |
| 36 | ||
| 37 | /** The disclosure: sentence, histogram, the slowest decile, and what is assumed. */ | |
| 38 | export function shipSection(s: ShipTime): Html { | |
| 39 | const slow = | |
| 40 | s.slowest.length === 0 | |
| 41 | ? null | |
| 42 | : html`<h4 class="fs-h">The slowest tenth, and what the time went to</h4> | |
| 43 | <ol class="fs-slow"> | |
| 44 | ${s.slowest.map( | |
| 45 | (i) => html`<li class="fs-item"> | |
| 46 | <a href="${i.path}">${i.repo}#${i.number} ${i.title}</a> | |
| 47 | <span class="fs-took">shipped in ${shipSpan(i.shipMs)}</span> | |
| 48 | <span class="fs-why">${slowLine(i)} · work ${shipSpan(i.workMs)}</span> | |
| 49 | </li>`, | |
| 50 | )} | |
| 51 | </ol>`; | |
| 52 | return html`<details class="fs" id="hf-ship"> | |
| 53 | <summary class="fs-sum">${shipSentence(s)}</summary> | |
| 54 | ${s.count === 0 ? null : histogramSvg(s)} | |
| 55 | ${slow} | |
| 56 | <p class="fs-assume"> | |
| 57 | First crew run to closing as done, last 7 days; the rest is in | |
| 58 | <a href="/docs/features/ship-time.md">the ship time doc</a>. | |
| 59 | </p> | |
| 60 | </details>`; | |
outdated
Principle 1 and 8: this paragraph explains the definition in long sentences, and docs/features/ship-time.md says it again. Cut it to one plain line and link the doc. |
||
| 61 | } |
test/home-figures.test.ts +3
| @@ -63,6 +63,7 @@ describe("a card says its unit", () => { | ||
| 63 | 63 | shipped: { days: [0, 3, 8, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 2], total: 14 }, |
| 64 | 64 | spend: { todayUsd: 39, ceilingUsd: 50, days: Array.from({ length: 14 }, () => 20), totalUsd: 280 }, |
| 65 | 65 | checks: { medianMs: 8 * 60_000, days: Array.from({ length: 14 }, (_, i) => (i === 3 ? null : 5 * 60_000)) }, |
| 66 | ship: { days: 7, count: 214, medianMs: 38 * 60_000, p90Ms: 190 * 60_000, histogram: [], slowest: [] }, | |
| 66 | 67 | bugs: { open: 3, overdue: 1 }, |
| 67 | 68 | backup: { at: null, state: null, note: "" }, |
| 68 | 69 | } as const; |
| @@ -123,6 +124,8 @@ describe("the figures come from the picture", () => { | ||
| 123 | 124 | const html = await (await fetch(`${servers.url}/`, { headers: { cookie: owner } })).text(); |
| 124 | 125 | expect(html).toContain('id="hf-figures"'); |
| 125 | 126 | expect(html.match(/class="fg-card/g)?.length).toBe(7); |
| 127 | expect(html).toContain('id="hf-ship"'); | |
| 128 | expect(html).toContain("Median ship time this week:"); | |
| 126 | 129 | expect(html).not.toContain("Safe off the machine"); |
| 127 | 130 | const body = await fetch(`${servers.url}/live/figures`, { headers: { cookie: owner } }); |
| 128 | 131 | expect(body.status).toBe(200); |
test/palette-roster.test.ts +2
| @@ -201,6 +201,7 @@ test("a site-admin person is offered the whole roster", () => { | ||
| 201 | 201 | ["app-templates", "App templates", "the repositories New app offers; mark or unmark one"], |
| 202 | 202 | ["devices", "Devices", "LAN printers: model, state, supplies; declare or remove one"], |
| 203 | 203 | ["payments", "Payments", "what was charged for the forges you claimed"], |
| 204 | ["ship-time", "Ship time", "median time from the crew's first run to done"], | |
| 204 | 205 | ["edge-only-accounts", "Edge-only accounts", "who would be locked out if the platform edge sign-in went off"], |
| 205 | 206 | ["way-back-links", "Way-back links", "a link that signs in an account the edge made, once the edge is gone"], |
| 206 | 207 | ["traffic-sources", "Traffic sources", "where people come from and where they go, for the forge"], |
| @@ -313,6 +314,7 @@ test("a site-admin agent is offered the roster without the person-only entries", | ||
| 313 | 314 | ["can", "What I can do", "your role and what it allows here"], |
| 314 | 315 | ["bugs", "Bugs", "open bugs and the bug clock"], |
| 315 | 316 | ["health-voice", "Health — spoken", "how the forge is, in two plain sentences"], |
| 317 | ["ship-time", "Ship time", "median time from the crew's first run to done"], | |
| 316 | 318 | ["maintenance-runs", "Maintenance duty runs", "what each duty found, did and probed"], |
| 317 | 319 | ["traffic-sources", "Traffic sources", "where people come from and where they go, for the forge"], |
| 318 | 320 | ["audit", "Who can do what", "each app's doors from its contract.json: yes, own or no"], |
test/ship-time-screen.test.ts added +25
| @@ -0,0 +1,25 @@ | ||
| 1 | import { afterAll, expect, test } from "bun:test"; | |
| 2 | import { mkdtempSync, rmSync } from "node:fs"; | |
| 3 | import { tmpdir } from "node:os"; | |
| 4 | import { join } from "node:path"; | |
| 5 | import type { Session } from "../src/tui/session.ts"; | |
| 6 | import { createApp } from "../src/app.ts"; | |
| 7 | import { readShipTime } from "../src/flow/ship_time.ts"; | |
| 8 | import { shipSentence } from "../src/flow/ship_words.ts"; | |
| 9 | import { entry, shipTimeLines } from "../src/tui/screens/ship_time.ts"; | |
| 10 | ||
| 11 | const root = mkdtempSync(join(tmpdir(), "forge-ship-screen-")); | |
| 12 | afterAll(() => rmSync(root, { recursive: true, force: true })); | |
| 13 | ||
| 14 | test("the terminal says the sentence the page and API say", () => { | |
| 15 | const app = createApp({ dataDir: root, port: 0 }); | |
| 16 | const now = new Date("2026-11-20T12:00:00.000Z"); | |
| 17 | expect(shipTimeLines(app.db, now)[0]).toBe(shipSentence(readShipTime(app.db, now))); | |
| 18 | }); | |
| 19 | ||
| 20 | test("the palette entry is its own, offered to admins only", () => { | |
| 21 | expect(entry.id).toBe("ship-time"); | |
outdated
|
||
| 22 | const as = (isAdmin: boolean) => ({ user: { isAdmin } }) as unknown as Session; | |
| 23 | expect(entry.offered(as(true))).toBe(true); | |
| 24 | expect(entry.offered(as(false))).toBe(false); | |
| 25 | }); |
test/ship-time.test.ts added +230
| @@ -0,0 +1,230 @@ | ||
| 1 | /** | |
| 2 | * Ship time (#14649): from the first crew run on an issue to its closing as done by a merged pull. | |
| 3 | */ | |
| 4 | import { afterAll, describe, expect, test } from "bun:test"; | |
| 5 | import { mkdtempSync, rmSync } from "node:fs"; | |
| 6 | import { tmpdir } from "node:os"; | |
| 7 | import { join } from "node:path"; | |
| 8 | import { createApp } from "../src/app.ts"; | |
| 9 | import { createRepo } from "../src/core/repos.ts"; | |
| 10 | import { createUser } from "../src/core/users.ts"; | |
| 11 | import { createSession } from "../src/core/sessions.ts"; | |
| 12 | import { id } from "../src/kernel/id.ts"; | |
| 13 | import { cachedShipTime } from "../src/flow/ship_cache.ts"; | |
| 14 | import { bars, medianOf, percentileOf, readShipTime } from "../src/flow/ship_time.ts"; | |
| 15 | import { shipSentence, shipSpan } from "../src/flow/ship_words.ts"; | |
| 16 | import { serve } from "../src/http/server.ts"; | |
| 17 | import { histogramSvg, shipSection } from "../src/web/pages/home_ship.ts"; | |
| 18 | ||
| 19 | const NOW = new Date("2026-11-20T12:00:00.000Z"); | |
| 20 | const at = (minutesAgo: number) => new Date(NOW.getTime() - minutesAgo * 60_000).toISOString(); | |
| 21 | const roots: string[] = []; | |
| 22 | afterAll(() => roots.forEach((r) => rmSync(r, { recursive: true, force: true }))); | |
| 23 | ||
| 24 | async function seed() { | |
| 25 | const root = mkdtempSync(join(tmpdir(), "forge-ship-")); | |
| 26 | roots.push(root); | |
| 27 | const app = createApp({ dataDir: root, port: 0 }); | |
| 28 | const u = await createUser(app.db, { username: "alice", email: "[email protected]", password: "a-good-passphrase", origin: "seed", trusted: true, adminIfFirst: true }); | |
| 29 | if (!u.ok) throw new Error(u.error); | |
| 30 | const r = await createRepo(app.db, app.reposRoot, { ownerId: u.value.id, name: "r", visibility: "public", description: "r" }); | |
| 31 | if (!r.ok) throw new Error(r.error); | |
| 32 | let n = 0; | |
| 33 | const q = (sql: string, ...a: (string | number | null)[]) => app.db.query(sql).run(...a); | |
| 34 | const row = (kind: "issue" | "pull", state: string, reason: string | null, created: number, closed: number | null, body = "") => { | |
| 35 | const rowId = id(); | |
| 36 | n++; | |
| 37 | q(`INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state, close_reason, created_at, closed_at) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11)`, | |
| 38 | rowId, r.value.id, n, kind, `${kind} ${n}`, body, u.value.id, state, reason, at(created), closed === null ? null : at(closed)); | |
| 39 | return { id: rowId, number: n }; | |
| 40 | }; | |
| 41 | const run = (issueId: string, kind: string, reason: string, state: string, created: number, started: number | null, finished: number | null) => | |
| 42 | q(`INSERT INTO run (id, repo_id, kind, issue_id, state, reason, created_at, started_at, finished_at) VALUES (?1,?2,?3,?4,?5,?6,?7,?8,?9)`, | |
| 43 | id(), r.value.id, kind, issueId, state, reason, at(created), started === null ? null : at(started), finished === null ? null : at(finished)); | |
| 44 | const merge = (pullId: string, minutesAgo: number) => | |
| 45 | q(`INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, head_repo_id, merged_at) VALUES (?1,'main',?2,'','',?3,?4)`, pullId, `b/${pullId}`, r.value.id, at(minutesAgo)); | |
| 46 | /** | |
| 47 | * An issue the crew started `ship` minutes before it closed `closedAgo` minutes ago, closed by a | |
| 48 | * merged pull. | |
| 49 | */ | |
| 50 | const shipped = (ship: number, closedAgo = 60) => { | |
| 51 | const issue = row("issue", "closed", "done", 5000, closedAgo); | |
| 52 | run(issue.id, "agent", "assigned", "ok", closedAgo + ship, closedAgo + ship, closedAgo + 1); | |
| 53 | const pull = row("pull", "closed", null, closedAgo + 5, closedAgo, `Closes #${issue.number}`); | |
| 54 | merge(pull.id, closedAgo + 1); | |
| 55 | return { issue, pull }; | |
| 56 | }; | |
| 57 | return { app, u: u.value, q, row, run, merge, shipped }; | |
| 58 | } | |
| 59 | ||
| 60 | describe("the definition", () => { | |
| 61 | test("backlog time before the first crew run is excluded", async () => { | |
| 62 | const s = await seed(); | |
| 63 | // Opened 5000 minutes ago, started 90 minutes before it closed: the ship time is 90, not 5000+. | |
| 64 | s.shipped(90); | |
| 65 | const t = readShipTime(s.app.db, NOW); | |
| 66 | expect(t.count).toBe(1); | |
| 67 | expect(t.medianMs).toBe(90 * 60_000); | |
| 68 | }); | |
| 69 | ||
| 70 | test("the first run counts, a later one does not move the start", async () => { | |
| 71 | const s = await seed(); | |
| 72 | const { issue } = s.shipped(120); | |
| 73 | s.run(issue.id, "agent", "feedback", "ok", 70, 65, 62); | |
| 74 | expect(readShipTime(s.app.db, NOW).medianMs).toBe(120 * 60_000); | |
| 75 | }); | |
| 76 | ||
| 77 | test("won't-do closes, closes with no merged pull and issues the crew never ran are excluded", async () => { | |
| 78 | const s = await seed(); | |
| 79 | s.shipped(30); | |
| 80 | const dropped = s.row("issue", "closed", "dropped", 5000, 60); | |
| 81 | s.run(dropped.id, "agent", "assigned", "ok", 200, 200, 100); | |
| 82 | const droppedPull = s.row("pull", "closed", null, 70, 60, `Closes #${dropped.number}`); | |
| 83 | s.merge(droppedPull.id, 61); | |
| 84 | const split = s.row("issue", "closed", "split", 5000, 60); | |
| 85 | s.run(split.id, "agent", "assigned", "ok", 200, 200, 100); | |
| 86 | const noPull = s.row("issue", "closed", "done", 5000, 60); | |
| 87 | s.run(noPull.id, "agent", "assigned", "ok", 300, 300, 100); | |
| 88 | const noRun = s.row("issue", "closed", "done", 5000, 60); | |
| 89 | const noRunPull = s.row("pull", "closed", null, 70, 60, `Closes #${noRun.number}`); | |
| 90 | s.merge(noRunPull.id, 61); | |
| 91 | const unmerged = s.row("issue", "closed", "done", 5000, 60); | |
| 92 | s.run(unmerged.id, "agent", "assigned", "ok", 300, 300, 100); | |
| 93 | s.row("pull", "closed", null, 70, 60, `Closes #${unmerged.number}`); | |
| 94 | const t = readShipTime(s.app.db, NOW); | |
| 95 | expect(t.count).toBe(1); | |
| 96 | expect(t.medianMs).toBe(30 * 60_000); | |
| 97 | }); | |
| 98 | ||
| 99 | test("only issues closed in the last 7 days count", async () => { | |
| 100 | const s = await seed(); | |
| 101 | s.shipped(30); | |
| 102 | s.shipped(30, 8 * 24 * 60); | |
| 103 | expect(readShipTime(s.app.db, NOW).count).toBe(1); | |
| 104 | }); | |
| 105 | ||
| 106 | test("nothing shipped is no figure, said plainly", async () => { | |
| 107 | const s = await seed(); | |
| 108 | const t = readShipTime(s.app.db, NOW); | |
| 109 | expect(t).toMatchObject({ count: 0, medianMs: null, p90Ms: null, slowest: [] }); | |
| 110 | expect(shipSentence(t)).toContain("no issue the crew started has shipped yet"); | |
| 111 | }); | |
| 112 | }); | |
| 113 | ||
| 114 | describe("median, p90, histogram and words, by hand", () => { | |
| 115 | test("median averages the middle two; p90 is the nearest rank", () => { | |
| 116 | expect(medianOf([10, 20, 30, 40])).toBe(25); | |
| 117 | expect(medianOf([10, 20, 30])).toBe(20); | |
| 118 | expect(percentileOf([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 0.9)).toBe(9); | |
| 119 | expect(percentileOf([5], 0.9)).toBe(5); | |
| 120 | expect(percentileOf([], 0.9)).toBeNull(); | |
| 121 | }); | |
| 122 | ||
| 123 | test("ten issues of 10, 20 … 100 minutes", async () => { | |
| 124 | const s = await seed(); | |
| 125 | for (let m = 10; m <= 100; m += 10) s.shipped(m); | |
| 126 | const t = readShipTime(s.app.db, NOW); | |
| 127 | expect(t.count).toBe(10); | |
| 128 | expect(t.medianMs).toBe(55 * 60_000); | |
| 129 | expect(t.p90Ms).toBe(90 * 60_000); | |
| 130 | expect(t.slowest.map((i) => i.shipMs)).toEqual([100 * 60_000]); | |
| 131 | // under 15 | 15-30 | 30-60 | 1-2 h | …: 10 / 20 / 30,40,50 / 60..100 (60, 70, 80, 90, 100). | |
| 132 | expect(t.histogram.map((b) => b.count)).toEqual([1, 1, 3, 5, 0, 0, 0, 0]); | |
| 133 | expect(shipSentence(t)).toBe("Median ship time this week: 55 min (p90 1 h 30 min, 10 issues)."); | |
| 134 | }); | |
| 135 | ||
| 136 | test("a span in words", () => { | |
| 137 | expect(shipSpan(38 * 60_000)).toBe("38 min"); | |
| 138 | expect(shipSpan(190 * 60_000)).toBe("3 h 10 min"); | |
| 139 | expect(shipSpan(26 * 3_600_000)).toBe("1 d 2 h"); | |
| 140 | expect(shipSpan(10_000)).toBe("under 1 min"); | |
| 141 | expect(bars([0, 899_999, 900_000, 99 * 86_400_000]).map((b) => b.count)).toEqual([2, 1, 0, 0, 0, 0, 0, 1]); | |
| 142 | }); | |
| 143 | }); | |
| 144 | ||
| 145 | describe("the slowest tenth, and what its time went to", () => { | |
| 146 | test("review, check, conflict and waiting time are named, and work is the rest", async () => { | |
| 147 | const s = await seed(); | |
| 148 | for (let m = 10; m <= 90; m += 10) s.shipped(m); | |
| 149 | const { issue, pull } = s.shipped(100); | |
| 150 | s.run(pull.id, "agent", "review", "ok", 40 + 60, 30 + 60, 22 + 60); // queued 10, ran 8 | |
| 151 | s.q(`INSERT INTO review (id, issue_id, author_id, state, body, created_at) VALUES (?1,?2,?3,'changes_requested','',?4)`, id(), pull.id, s.u.id, at(125)); | |
| 152 | s.run(pull.id, "check", "", "failed", 50 + 60, 50 + 60, 45 + 60); // a red check, 5 | |
| 153 | s.run(pull.id, "agent", "check_failed", "ok", 44 + 60, 44 + 60, 38 + 60); // a rework, 6 | |
| 154 | s.run(pull.id, "agent", "conflict", "ok", 20 + 60, 20 + 60, 16 + 60); // 4 | |
| 155 | const t = readShipTime(s.app.db, NOW); | |
| 156 | expect(t.slowest).toHaveLength(1); | |
| 157 | const i = t.slowest[0]!; | |
| 158 | expect(i.number).toBe(issue.number); | |
| 159 | expect(i.path).toBe(`/alice/r/issues/${issue.number}`); | |
| 160 | expect(i).toMatchObject({ | |
| 161 | shipMs: 100 * 60_000, | |
| 162 | reviewMs: 8 * 60_000, reviewRuns: 1, changesRequested: 1, | |
| 163 | checkMs: 11 * 60_000, redChecks: 1, reworks: 1, | |
| 164 | conflictMs: 4 * 60_000, conflictRuns: 1, conflictedPulls: 1, | |
| 165 | waitingMs: 10 * 60_000, | |
| 166 | workMs: (100 - 8 - 11 - 4 - 10) * 60_000, | |
| 167 | }); | |
| 168 | }); | |
| 169 | ||
| 170 | test("it draws as a histogram and a list that links each slow issue", async () => { | |
| 171 | const s = await seed(); | |
| 172 | for (let m = 10; m <= 100; m += 10) s.shipped(m); | |
| 173 | const t = readShipTime(s.app.db, NOW); | |
| 174 | expect(String(histogramSvg(t))).toContain("<rect"); | |
| 175 | const page = String(shipSection(t)); | |
| 176 | expect(page).toContain("Median ship time this week: 55 min (p90 1 h 30 min, 10 issues)."); | |
| 177 | expect(page).toContain('href="/alice/r/issues/'); | |
| 178 | expect(page).toMatch(/review .*checks .*conflicts .*waiting/); | |
| 179 | expect(page).toContain("First crew run to closing as done"); | |
| 180 | }); | |
| 181 | }); | |
| 182 | ||
| 183 | describe("one source, three doors", () => { | |
| 184 | test("the API and the kept reading say what the function says; only an admin reads it", async () => { | |
| 185 | const s = await seed(); | |
| 186 | s.shipped(40, 5); | |
| 187 | const servers = await serve(s.app); | |
| 188 | try { | |
| 189 | const base = `http://127.0.0.1:${servers.port}`; | |
| 190 | const cookie = `forge_session=${createSession(s.app.db, s.u.id).token}`; | |
| 191 | const res = await fetch(`${base}/api/v1/flow/ship-time`, { headers: { cookie } }); | |
| 192 | expect(res.status).toBe(200); | |
| 193 | const body = (await res.json()) as { sentence: string; count: number; medianMs: number }; | |
| 194 | expect(body.count).toBe(1); | |
| 195 | expect(body.sentence).toContain("40 min"); | |
| 196 | const csv = await (await fetch(`${base}/api/v1/flow/ship-time?format=csv`, { headers: { cookie } })).text(); | |
| 197 | expect(csv.split("\n")[0]).toBe("from_ms,to_ms,issues"); | |
| 198 | expect((await fetch(`${base}/api/v1/flow/ship-time`)).status).toBe(404); | |
| 199 | } finally { | |
| 200 | servers.stop(); | |
| 201 | } | |
| 202 | }); | |
| 203 | ||
| 204 | test("the kept reading is reused for a minute and read again after", async () => { | |
| 205 | const s = await seed(); | |
| 206 | s.shipped(40, 5); | |
| 207 | const first = cachedShipTime(s.app.db, new Date()); | |
| 208 | s.shipped(50, 5); | |
| 209 | expect(cachedShipTime(s.app.db, new Date(Date.now() + 1000))).toBe(first); | |
| 210 | expect(cachedShipTime(s.app.db, new Date(Date.now() + 61_000)).count).toBe(2); | |
| 211 | }); | |
| 212 | ||
| 213 | test("the issues are read through the index made for it, with no scan", async () => { | |
| 214 | const s = await seed(); | |
| 215 | const db = s.app.db; | |
| 216 | const sqls: string[] = []; | |
| 217 | const original = db.query.bind(db); | |
| 218 | (db as unknown as { query: unknown }).query = (sql: string) => (sqls.push(sql), original(sql)); | |
| 219 | readShipTime(db, NOW); | |
| 220 | (db as unknown as { query: unknown }).query = original; | |
| 221 | const plan = sqls | |
| 222 | .filter((sql) => /^\s*SELECT/i.test(sql) && sql.includes("issue_closed_done")) | |
| 223 | .flatMap((sql) => { | |
| 224 | const n = Math.max(0, ...[...sql.matchAll(/\?(\d+)/g)].map((m) => Number(m[1]))); | |
| 225 | return original(`EXPLAIN QUERY PLAN ${sql}`).all(...Array.from({ length: n }, () => "x")).map((r) => (r as { detail: string }).detail); | |
| 226 | }); | |
| 227 | expect(plan.join("\n")).toContain("issue_closed_done"); | |
| 228 | for (const line of plan) expect(line).not.toMatch(/^SCAN (?!.*USING (COVERING )?INDEX)/); | |
| 229 | }); | |
| 230 | }); |
Scope against the direction: the slowest-decile breakdown (per-issue run, pull and review queries, up to 500 pulls each) runs on every figures read, but the issue asked only for the median. Drop it from this pull, or open a separate one.