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

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/14649-home-shows-median-ship-time-from-the-cre → main 11 commits fork 5 threads · 5 unresolved

  • Merged. torque/14649-home-shows-median-ship-time-from-the-cre was merged into main as a9e6899.

Review

Sign in to review this change.
23 files changed +809 −7
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
4343 - `.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.
4444 - `.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.
4545 - `.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.
4647 - `.fg-reading` — the line a region shows before the first reading.
docs/design/attention-budget.json +5 −5
@@ -1,16 +1,16 @@
11 {
22 "home": {
33 "390": {
4 "words": 297,
5 "blocks": 50,
4 "words": 324,
5 "blocks": 54,
66 "colours": 7
77 },
88 "1280": {
9 "words": 297,
10 "blocks": 50,
9 "words": 324,
10 "blocks": 54,
1111 "colours": 7
1212 },
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)."
1414 },
1515 "repository": {
1616 "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";
100100 export { route as getApiV1FleetOps } from "./getApiV1FleetOps.ts";
101101 export { route as getApiV1FleetOpsId } from "./getApiV1FleetOpsId.ts";
102102 export { route as getApiV1FleetRows } from "./getApiV1FleetRows.ts";
103 export { route as getApiV1FlowShipTime } from "./getApiV1FlowShipTime.ts";
103104 export { route as getApiV1Forge } from "./getApiV1Forge.ts";
104105 export { route as getApiV1ForgeEconomics } from "./getApiV1ForgeEconomics.ts";
105106 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 @@
1313 import type { Database } from "bun:sqlite";
1414 import { median } from "./pipeline.ts";
1515 import type { Kpis } from "./kpis.ts";
16 import { readShipTime, type ShipTime } from "./ship_time.ts";
1617
1718 /** Days the daily series cover, today last. */
1819 export const SERIES_DAYS = 14;
@@ -29,6 +30,8 @@ export interface Figures {
2930 readonly spend: { readonly todayUsd: number; readonly ceilingUsd: number | null; readonly days: readonly number[]; readonly totalUsd: number };
3031 /** How long a finished check took: the median over 24 h and per UTC day (null for a day with none). */
3132 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;
3235 readonly bugs: { readonly open: number; readonly overdue: number } | null;
3336 readonly backup: { readonly at: string | null; readonly state: "green" | "red" | "unknown" | null; readonly note: string };
3437 }
@@ -88,6 +91,7 @@ export function readFigures(db: Database, now: Date, kpis: Kpis): Figures {
8891 shipped: { days: shipped, total: shipped.reduce((a, b) => a + b, 0) },
8992 spend: { todayUsd: kpis.spend.todayUsd, ceilingUsd: kpis.spend.ceilingUsd, days: spend, totalUsd: spend.reduce((a, b) => a + b, 0) },
9093 checks: { medianMs: kpis.medianCheckMs, days: keys.map((k) => median(took.get(k) ?? [])) },
94 ship: readShipTime(db, now),
9195 bugs: kpis.bugs === undefined ? null : { open: kpis.bugs.open, overdue: kpis.bugs.overdue },
9296 backup: { at: kpis.backupAt, state: backupState, note: kpis.backup?.note ?? "" },
9397 };
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);

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.

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";
382382 import { forgeRoutes } from "./api/forges.ts";
383383 import { packRoutes } from "./api/packs.ts";
384384 import { forgeViewRoutes } from "./api/forge_view.ts";
385 import { shipTimeRoutes } from "./api/ship_time.ts";
385386 import { billingRoutes } from "./api/billing.ts";
386387 import { codesRoutes } from "./api/codes.ts";
387388 import { economicsRoutes } from "./api/economics.ts";
@@ -3857,6 +3858,7 @@ export function apiRoutes(router: Router<Handler>, isPage: (path: string) => boo
38573858 forgeRoutes(router);
38583859 packRoutes(router);
38593860 forgeViewRoutes(router);
3861 shipTimeRoutes(router);
38603862 economicsRoutes(router);
38613863 billingRoutes(router);
38623864 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 {
120120 import { readVitals, vitalsLine } from "../../flow/vitals.ts";
121121 import { readKpis } from "../../flow/kpis.ts";
122122 import { kpiLines } from "../../flow/kpi_words.ts";
123 import { shipTimeLines } from "./ship_time.ts";
123124 import { BOOTED } from "../../release/gate.ts";
124125 import { running } from "../../kernel/version.ts";
125126 import { deciderLine, deciderScreen } from "./decider.ts";
@@ -514,6 +515,7 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen {
514515 ...idleLines(f.app, now),
515516 ...weekBlock(f.app, now),
516517 ...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),
517519 vitalsLine(readVitals(f.db, now)),
518520 ...firedAlarms(f.db, now, { ceilingUsd: forgeCeiling(f.app.config), dataDir: f.app.config.dataDir }).map((a) => a.says),
519521 ...(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 {
2323 import type { Figures } from "../../flow/figures.ts";
2424 import type { LanePicture } from "../../flow/lanes.ts";
2525 import { html, raw, type Html } from "../html.ts";
26 import { shipSection } from "./home_ship.ts";
2627
2728 /** The events that change a figure; they change by the minute, so these are few. */
2829 export const FIGURES_LIVE =
@@ -260,6 +261,7 @@ export function figuresGrid(picture: LanePicture, now: number): Html {
260261 data-live-src="/live/figures"
261262 >
262263 <div class="fg-grid">${cards(f, now).map(card)}</div>
264 ${shipSection(f.ship)}
263265 </div>`;
264266 }
265267
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); }
244244 .lane[data-reading] { padding-bottom: 64px; }
245245 /* A table: its header row and one row, each 44px (.tb-pick), and the gap. */
246246 .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
248248 + 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: --accent is for interaction alone. These bars are data, not controls. Use --fg or --muted-fg for them.

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; }
250262
251263 /* ---- the box that tells the crew, kept to one row on a desk ---- */
252264 .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", () => {
6363 shipped: { days: [0, 3, 8, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 2], total: 14 },
6464 spend: { todayUsd: 39, ceilingUsd: 50, days: Array.from({ length: 14 }, () => 20), totalUsd: 280 },
6565 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: [] },
6667 bugs: { open: 3, overdue: 1 },
6768 backup: { at: null, state: null, note: "" },
6869 } as const;
@@ -123,6 +124,8 @@ describe("the figures come from the picture", () => {
123124 const html = await (await fetch(`${servers.url}/`, { headers: { cookie: owner } })).text();
124125 expect(html).toContain('id="hf-figures"');
125126 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:");
126129 expect(html).not.toContain("Safe off the machine");
127130 const body = await fetch(`${servers.url}/live/figures`, { headers: { cookie: owner } });
128131 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", () => {
201201 ["app-templates", "App templates", "the repositories New app offers; mark or unmark one"],
202202 ["devices", "Devices", "LAN printers: model, state, supplies; declare or remove one"],
203203 ["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"],
204205 ["edge-only-accounts", "Edge-only accounts", "who would be locked out if the platform edge sign-in went off"],
205206 ["way-back-links", "Way-back links", "a link that signs in an account the edge made, once the edge is gone"],
206207 ["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",
313314 ["can", "What I can do", "your role and what it allows here"],
314315 ["bugs", "Bugs", "open bugs and the bug clock"],
315316 ["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"],
316318 ["maintenance-runs", "Maintenance duty runs", "what each duty found, did and probed"],
317319 ["traffic-sources", "Traffic sources", "where people come from and where they go, for the forge"],
318320 ["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

entry.offered.length checks the function's arity, not that it admits only admins. It would pass for a function that always returns true. Call entry.offered with an admin session and a non-admin one and assert true and false.

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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs