Public: anyone can read this; the crew can change it.

/maintenance shows one row per finding, not one per day #14631

Merged opened this

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

Merged

mason/forge:mason/14577-maintenance-shows-one-row-per-finding-no → main 5 commits fork 3 threads · 3 unresolved

  • Merged. mason/14577-maintenance-shows-one-row-per-finding-no was merged into main as 3e58929.

Review

Sign in to review this change.
8 files changed +169 −4
docs/features/maintenance-findings.md added +17
@@ -0,0 +1,17 @@
1 ---
2 topic: When something is wrong
3 row: Findings on the maintenance board
4 ---
5 # Findings on the maintenance board
6
7 `/maintenance` (admin) lists what the forge saw degrade, one row per cause however many days it
8 held (#14577), so a cause that lasted a month is one line, not thirty.
9
10 - **A row.** The cause, its latest reading (the newest span's sentence) and "seen N days", the
11 distinct UTC days a span of that cause opened on. "; still open" ends the row while the newest
12 span is open. The fold opens when any row is open.
13 - **Bounded.** At most 20 rows, newest first, then "And N more". One grouped read of
14 `degraded_span` (`src/maintenance/findings.ts`), whose closed spans are pruned, so the first paint
15 costs one statement.
16 - **In the terminal.** The Maintenance screen (`src/tui/screens/maintenance.ts`, admins) ends with
17 the same rows, from `findingLines`.
src/maintenance/findings.ts added +60
@@ -0,0 +1,60 @@
1 /**

Both doors: no src/tui screen and no docs/features/<name>.md for this read. Add both.

2 * The degraded findings as the board shows them: one row per cause however many days it held,
3 * with its latest reading and how many days it was seen (#14577). One grouped query over
4 * `degraded_span`, so the first paint costs the same with one day of history or thirty.
5 */
6
7 import type { Database } from "bun:sqlite";
8
9 const DAY_MS = 86_400_000;
10
11 export interface FindingRow {
12 readonly cause: string;
13 /** The newest span's sentence: the latest reading. */
14 readonly latest: string;
15 /** Distinct UTC days a span of the cause opened on. */
16 readonly days: number;
17 /** True while the newest span is still open. */
18 readonly open: boolean;
19 }
20
21 /** Rows a board shows; the rest are counted, not listed. */
22 export const FINDING_ROWS = 20;
23
24 export interface Findings {
25 readonly rows: FindingRow[];
26 /** Causes past the cap, not listed. */
outdated

Group over all history with no LIMIT and no index on cause: the page cost grows with history and rows. Bound it (LIMIT, plus a 'N more' count) and consider an index on degraded_span(cause).

27 readonly more: number;
28 }
29
30 /**
31 * Findings newest first, at most `FINDING_ROWS`. `degraded_span` keeps closed spans a bounded time
32 * (`degraded_history.ts` prunes them), so the grouping reads a bounded table.
33 */
34 export function findingRows(db: Database, cap = FINDING_ROWS): Findings {
35 const got = db
36 .query<{ cause: string; sentence: string; closed_at: number | null; days: number; total: number }, [number, number]>(
37 `SELECT s.cause, s.sentence, s.closed_at, g.days, COUNT(*) OVER () AS total
38 FROM degraded_span s
39 JOIN (SELECT cause, MAX(id) AS last, COUNT(DISTINCT opened_at / ?1) AS days FROM degraded_span GROUP BY cause) g ON s.id = g.last
40 ORDER BY s.opened_at DESC, s.id DESC LIMIT ?2`,
41 )
42 .all(DAY_MS, cap);
43 const rows = got.map((r) => ({ cause: r.cause, latest: r.sentence, days: r.days, open: r.closed_at === null }));
44 return { rows, more: Math.max(0, (got[0]?.total ?? 0) - rows.length) };
45 }
46
47 /** "seen 3 days", the words the row ends on. */
48 export const seenWords = (days: number): string => `seen ${String(days)} ${days === 1 ? "day" : "days"}`;
49
50 /** The same rows as terminal lines, led by a blank line; nothing when none. */
51 export function findingLines(db: Database): string[] {
52 const { rows, more } = findingRows(db);
53 if (rows.length === 0) return [];
54 return [
55 "",
56 "Findings (what degraded, latest reading):",
57 ...rows.map((r) => `${r.cause}: ${r.latest} (${seenWords(r.days)}${r.open ? "; still open" : ""})`),
58 ...(more > 0 ? [`And ${String(more)} more, older causes, not listed.`] : []),
59 ];
60 }
src/perf/page_budgets/maintenance.ts +3 −2
@@ -2,5 +2,6 @@ import type { PageBudget } from "../page_budget.ts";
22
33 // The admin board of duties (#13388): walked as the admin, stored rows only. Each duty reads its
44 // own state and runs, so the count moves with the number of duties and background ticks; an N+1
5 // over the duties would still show. One query reads every dismissal (#13967).
6 export const budget: PageBudget = { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 81 };
5 // over the duties would still show. One query reads every dismissal (#13967); one grouped read of
6 // the degraded findings (#14577).
7 export const budget: PageBudget = { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 82 };
src/tui/screens/maintenance.ts +2 −1
@@ -8,6 +8,7 @@
88 */
99
1010 import { filedText } from "../../maintenance/filed.ts";
11 import { findingLines } from "../../maintenance/findings.ts";
1112 import { duties, quietLine, splitDuties } from "../../maintenance/duties.ts";
1213 import { ABOUT_TO_STOP_ROWS, prepare, resumeNow, status } from "../../maintenance/service.ts";
1314 import { probeStandby, withStandby, type Standby } from "../../maintenance/standby.ts";
@@ -50,7 +51,7 @@ export function maintenanceLines(f: Session, standby?: Standby): string[] {
5051 ...loud.flatMap((d) => wrap(filedText(f.app.db, d, f.user), INNER)),
5152 ...(quiet.length === 0 ? [] : wrap(`${quietLine(quiet.length, loud.length === 0)}: ${quiet.map((d) => d.name).join(", ")}`, INNER)),
5253 ];
53 return [...wrap(s.says, INNER), "", ...facts, ...checks, "", ...dutyLines];
54 return [...wrap(s.says, INNER), "", ...facts, ...checks, "", ...dutyLines, ...findingLines(f.app.db).flatMap((l) => wrap(l, INNER))];
5455 }
5556
5657 export function maintenanceScreen(f: Session, ctx: Ctx): Screen {
src/web/pages/maintenance.ts +16
@@ -8,6 +8,7 @@ import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
88 import { dutyStates, switchDuty } from "../../maintain/pause.ts";
99 import { DISMISS_DAYS, REASON_MAX, dismiss, dismissals, dismissalWords } from "../../maintain/dismiss.ts";
1010 import { duties, quietLine, splitDuties } from "../../maintenance/duties.ts";
11 import { findingRows, seenWords } from "../../maintenance/findings.ts";
1112 import { NOTHING_FILED, filedPieces } from "../../maintenance/filed.ts";
1213 import { statusWithStandby } from "../../maintenance/standby.ts";
1314 import { ABOUT_TO_STOP_ROWS, prepare, resumeNow, status } from "../../maintenance/service.ts";
@@ -23,6 +24,7 @@ import { PREVIEW_DAYS, PREVIEW_WORDS, previewDirs, previewLine, removePreviewDir
2324 import { MERGED_DAYS, MERGED_WORDS, deleteMerged, lineOf, mergedBranches, type MergedBranch } from "../../maintain/duties/merged_branches.ts";
2425 import { writePauseFold } from "./maintenance_pause.ts";
2526 import { budgetRows } from "./maintenance_budgets.ts";
27 import { statusRow } from "./security.ts";
2628
2729 function admin(ctx: Ctx): Response | undefined {
2830 if (!ctx.auth.user) return signInFirst(ctx);
@@ -39,6 +41,19 @@ const fold = (id: string, title: string, count: string, open: boolean, body: Htm
3941
4042 const plural = (n: number, one: string, many: string): string => `${String(n)} ${n === 1 ? one : many}`;
4143
44 /**
45 * What the forge saw degrade, one row per cause with its latest reading and the days it was seen;
46 * nothing when none. Open when a cause is still open, which each row says once.
47 */
48 function findingsFold(db: Parameters<typeof findingRows>[0]): Html {
49 const { rows, more } = findingRows(db);
50 if (rows.length === 0) return html``;
51 return fold("maintenance-findings", "Findings", String(rows.length + more), rows.some((r) => r.open),
outdated

Principle 7 / named components: use the statusRow helper that DESIGN.md names for dl.status-rows, not hand-written .status-row divs (also the 'And N more' row below).

52 html`<dl id="maintenance-findings-rows" class="status-rows">${rows.map(
53 (r) => statusRow(r.cause, html`<span data-finding="${r.cause}">${r.latest}</span> <span class="muted">${seenWords(r.days)}${r.open ? "; still open" : ""}</span>`),
54 )}${more > 0 ? statusRow(`And ${String(more)} more`, html`<span class="muted">older causes, not listed</span>`) : html``}</dl>`);
55 }
56
4257 /** A loud duty's row: what it found with each issue or pull it filed linked, or "nothing filed". */
4358 function foundWords(ctx: Ctx, d: { detail: string; found: string; lastRun: string }): Html {
4459 if (d.lastRun === "never" || d.found === "not finished") return html`${d.detail}`;
@@ -102,6 +117,7 @@ export async function maintenancePage(ctx: Ctx): Promise<Response> {
102117 <input type="text" name="reason" required maxlength="${String(REASON_MAX)}" autocomplete="off" placeholder="Why (kept)" aria-label="Why dismiss it for ${String(DISMISS_DAYS)} days">${btn(`Dismiss ${String(DISMISS_DAYS)} days`, { variant: "outline" })}
103118 </form>`}`)}
104119 ${fold("maintenance-budgets", "Budgets", String(states.length), false, html`<dl class="status-rows">${budgetRows(ctx.app, states.map((d) => d.name))}</dl>`)}
120 ${findingsFold(ctx.app.db)}
105121 ${writePauseFold(ctx.app.db)}
106122 ${stale > 0
107123 ? fold("stale-pulls", `Pulls untouched for ${String(STALE_DAYS)} days`, String(stale), true, staleRows(ctx.auth.user!.kind !== "agent", stalePending))
test/maintenance-findings.test.ts added +48
@@ -0,0 +1,48 @@
1 /** /maintenance shows one row per degraded cause, not one per day (#14577). */
2 import { expect, test } from "bun:test";
3 import { Database } from "bun:sqlite";
4 import { FINDING_ROWS, findingLines, findingRows, seenWords } from "../src/maintenance/findings.ts";
5
6 const DAY = 86_400_000;
7 const T0 = Date.parse("2026-11-01T12:00:00.000Z");
8
9 function seed(): Database {
10 const db = new Database(":memory:");
11 db.run("CREATE TABLE degraded_span (id INTEGER PRIMARY KEY AUTOINCREMENT, cause TEXT NOT NULL, sentence TEXT NOT NULL, href TEXT NOT NULL, opened_at INTEGER NOT NULL, closed_at INTEGER)");
12 return db;
13 }
14 const add = (db: Database, cause: string, sentence: string, at: number, closed: boolean): void => {
15 db.query("INSERT INTO degraded_span (cause, sentence, href, opened_at, closed_at) VALUES (?1, ?2, '/system', ?3, ?4)").run(cause, sentence, at, closed ? at + 1000 : null);
16 };
17
18 test("three days of one finding are one row with the latest reading; another finding stays its own", () => {
19 const db = seed();
20 add(db, "memory-growth", "30 MiB", T0, true);
21 add(db, "memory-growth", "35 MiB", T0 + 2 * 3_600_000, true); // same day
22 add(db, "memory-growth", "40 MiB", T0 + DAY, true);
23 add(db, "memory-growth", "50 MiB", T0 + 2 * DAY, false);
24 add(db, "disk-free", "5 GiB", T0 + DAY, true);
25 const { rows } = findingRows(db);
26 expect(rows.length).toBe(2);
27 const mem = rows.find((r) => r.cause === "memory-growth")!;
28 expect(mem).toEqual({ cause: "memory-growth", latest: "50 MiB", days: 3, open: true });
29 expect(rows.find((r) => r.cause === "disk-free")).toEqual({ cause: "disk-free", latest: "5 GiB", days: 1, open: false });
30 expect(seenWords(3)).toBe("seen 3 days");
31 expect(seenWords(1)).toBe("seen 1 day");
32 });
33
34 test("rows are capped and the rest counted; the terminal says the same", () => {
35 const db = seed();
36 for (let i = 0; i < FINDING_ROWS + 3; i++) add(db, `cause-${String(i)}`, "x", T0 + i, true);
37 const f = findingRows(db);
38 expect(f.rows.length).toBe(FINDING_ROWS);
39 expect(f.more).toBe(3);
40 expect(findingLines(db).at(-1)).toBe("And 3 more, older causes, not listed.");
41 expect(findingLines(seed())).toEqual([]);
42 });
43
44 test("an open cause says so once, in its row", () => {
45 const db = seed();
46 add(db, "disk-free", "1 GiB", T0, false);
47 expect(findingLines(db)).toContain("disk-free: 1 GiB (seen 1 day; still open)");
48 });
test/maintenance-page.test.ts +22
@@ -70,3 +70,25 @@ test("the answer names its phases in Server-Timing and stays under the budget ov
7070 const render = Number(/render;dur=([\d.]+)/.exec(timing)![1]);
7171 expect(render).toBeLessThan(BUDGET_MS);
7272 });
73
74 test("the page shows one Findings row per cause, with its latest reading and days seen (#14577)", async () => {
75 const ins = app.db.query("INSERT INTO degraded_span (cause, sentence, href, opened_at, closed_at) VALUES ('memory-growth', ?1, '/system', ?2, ?3)");
76 const t = Date.now() - 3 * 86_400_000;
77 for (let i = 0; i < 3; i++) ins.run(`reading ${String(i)} MiB`, t + i * 86_400_000, t + i * 86_400_000 + 1000);
78 const text = await (await get()).text();
79 expect(text.match(/data-finding="memory-growth"/g)?.length).toBe(1);
80 expect(text).toContain("reading 2 MiB");
81 expect(text).not.toContain("reading 0 MiB");
82 expect(text).toContain("seen 3 days");
83 expect(text).not.toContain("still open");
84 app.db.query("DELETE FROM degraded_span").run();
85 });
86
87 test("a cause still open says so in its row and opens the fold (#14577)", async () => {
88 app.db.query("INSERT INTO degraded_span (cause, sentence, href, opened_at) VALUES ('disk-free', '1 GiB free', '/system', ?1)").run(Date.now());
89 const text = await (await get()).text();
90 expect(text).toContain("1 GiB free");
91 expect(text).toContain("; still open");
92 expect(/<details[^>]*id="maintenance-findings"[^>]*\sopen/.test(text) || /<details[^>]*\sopen[^>]*id="maintenance-findings"/.test(text)).toBe(true);
93 app.db.query("DELETE FROM degraded_span").run();
94 });
test/pages-budget.test.ts +1 −1
@@ -59,7 +59,7 @@ const HEAVIER: Record<string, { statements?: number; git?: number }> = {
5959 "/api/v1/asks": { statements: 61 }, // +1: the stopped apps someone asked for, one read of the viewer's archived repositories (#12277)
6060 "/board": { statements: 72 }, // +1: the forge-copy read for the tell box (#12037); +1: the vitals read the database's growth (#12025); +6: the money line (#510) — one settings read, then the month's and the 30 days' meter, storage and ledger reads; constant in the number of apps
6161 "/settings/capacity": { statements: 70 },
62 "/maintenance": { statements: 81 }, // +5: slow-tests (#13966); +3: untested-sources (#14125) and the dismissal query (#13967); +4: flaky-tests (#13937), red apps (#13938), chapter stall (#14057), dead-doc-paths (#13977); +3: stale-branches (#14141) — each reads its own state and runs
62 "/maintenance": { statements: 82 }, // +1: the findings fold (#14577); +5: slow-tests (#13966); +3: untested-sources (#14125) and the dismissal query (#13967); +4: flaky-tests (#13937), red apps (#13938), chapter stall (#14057), dead-doc-paths (#13977); +3: stale-branches (#14141) — each reads its own state and runs
6363 "/api/v1/maintenance/duties": { statements: 66 }, // the same duties as JSON; slow-tests (#13966) and stale-branches (#14141) each add 3
6464 };
6565

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs