Public: anyone can read this; the crew can change it.
/maintenance shows one row per finding, not one per day #14631
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14577-maintenance-shows-one-row-per-finding-no → main 5 commits fork 3 threads · 3 unresolved
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 | /** | |
| 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"; | ||
| 2 | 2 | |
| 3 | 3 | // The admin board of duties (#13388): walked as the admin, stored rows only. Each duty reads its |
| 4 | 4 | // 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 @@ | ||
| 8 | 8 | */ |
| 9 | 9 | |
| 10 | 10 | import { filedText } from "../../maintenance/filed.ts"; |
| 11 | import { findingLines } from "../../maintenance/findings.ts"; | |
| 11 | 12 | import { duties, quietLine, splitDuties } from "../../maintenance/duties.ts"; |
| 12 | 13 | import { ABOUT_TO_STOP_ROWS, prepare, resumeNow, status } from "../../maintenance/service.ts"; |
| 13 | 14 | import { probeStandby, withStandby, type Standby } from "../../maintenance/standby.ts"; |
| @@ -50,7 +51,7 @@ export function maintenanceLines(f: Session, standby?: Standby): string[] { | ||
| 50 | 51 | ...loud.flatMap((d) => wrap(filedText(f.app.db, d, f.user), INNER)), |
| 51 | 52 | ...(quiet.length === 0 ? [] : wrap(`${quietLine(quiet.length, loud.length === 0)}: ${quiet.map((d) => d.name).join(", ")}`, INNER)), |
| 52 | 53 | ]; |
| 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))]; | |
| 54 | 55 | } |
| 55 | 56 | |
| 56 | 57 | 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"; | ||
| 8 | 8 | import { dutyStates, switchDuty } from "../../maintain/pause.ts"; |
| 9 | 9 | import { DISMISS_DAYS, REASON_MAX, dismiss, dismissals, dismissalWords } from "../../maintain/dismiss.ts"; |
| 10 | 10 | import { duties, quietLine, splitDuties } from "../../maintenance/duties.ts"; |
| 11 | import { findingRows, seenWords } from "../../maintenance/findings.ts"; | |
| 11 | 12 | import { NOTHING_FILED, filedPieces } from "../../maintenance/filed.ts"; |
| 12 | 13 | import { statusWithStandby } from "../../maintenance/standby.ts"; |
| 13 | 14 | import { ABOUT_TO_STOP_ROWS, prepare, resumeNow, status } from "../../maintenance/service.ts"; |
| @@ -23,6 +24,7 @@ import { PREVIEW_DAYS, PREVIEW_WORDS, previewDirs, previewLine, removePreviewDir | ||
| 23 | 24 | import { MERGED_DAYS, MERGED_WORDS, deleteMerged, lineOf, mergedBranches, type MergedBranch } from "../../maintain/duties/merged_branches.ts"; |
| 24 | 25 | import { writePauseFold } from "./maintenance_pause.ts"; |
| 25 | 26 | import { budgetRows } from "./maintenance_budgets.ts"; |
| 27 | import { statusRow } from "./security.ts"; | |
| 26 | 28 | |
| 27 | 29 | function admin(ctx: Ctx): Response | undefined { |
| 28 | 30 | if (!ctx.auth.user) return signInFirst(ctx); |
| @@ -39,6 +41,19 @@ const fold = (id: string, title: string, count: string, open: boolean, body: Htm | ||
| 39 | 41 | |
| 40 | 42 | const plural = (n: number, one: string, many: string): string => `${String(n)} ${n === 1 ? one : many}`; |
| 41 | 43 | |
| 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 |
||
| 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 | ||
| 42 | 57 | /** A loud duty's row: what it found with each issue or pull it filed linked, or "nothing filed". */ |
| 43 | 58 | function foundWords(ctx: Ctx, d: { detail: string; found: string; lastRun: string }): Html { |
| 44 | 59 | if (d.lastRun === "never" || d.found === "not finished") return html`${d.detail}`; |
| @@ -102,6 +117,7 @@ export async function maintenancePage(ctx: Ctx): Promise<Response> { | ||
| 102 | 117 | <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" })} |
| 103 | 118 | </form>`}`)} |
| 104 | 119 | ${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)} | |
| 105 | 121 | ${writePauseFold(ctx.app.db)} |
| 106 | 122 | ${stale > 0 |
| 107 | 123 | ? 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 | ||
| 70 | 70 | const render = Number(/render;dur=([\d.]+)/.exec(timing)![1]); |
| 71 | 71 | expect(render).toBeLessThan(BUDGET_MS); |
| 72 | 72 | }); |
| 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 }> = { | ||
| 59 | 59 | "/api/v1/asks": { statements: 61 }, // +1: the stopped apps someone asked for, one read of the viewer's archived repositories (#12277) |
| 60 | 60 | "/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 |
| 61 | 61 | "/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 | |
| 63 | 63 | "/api/v1/maintenance/duties": { statements: 66 }, // the same duties as JSON; slow-tests (#13966) and stale-branches (#14141) each add 3 |
| 64 | 64 | }; |
| 65 | 65 |
new above
offline
Both doors: no src/tui screen and no docs/features/<name>.md for this read. Add both.