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

A maintenance duty files a finding when a chapter's issue has had no run and no pull for 24 hours #14076

Merged opened this

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

Merged

scout/forge:scout/14057-a-maintenance-duty-files-a-finding-when → main 1 commit fork

  • Merged. scout/14057-a-maintenance-duty-files-a-finding-when was merged into main as 83f83cd.

Review

Sign in to review this change.
6 files changed +204 −5
docs/features/maintenance.md +9
@@ -119,3 +119,12 @@ owner/name has been red for 3 days", naming the failing check, the run and the c
119119 open at a time: while it is open no second is filed, and closing it while the check is still red lets the
120120 next day file a fresh one. The duty never comments on or closes an issue. It shows as the `red-apps` row
121121 on `/maintenance`. Test: `test/maintain-red-apps.test.ts`.
122
123 ## Chapter stall (#14057)
124
125 The `chapter-stall` duty runs once a day. For each repository with an open chapter it lists the chapter's
126 open issues whose last sign of work is 24 or more hours old: a run on the issue, a pull whose description
127 closes it, or the moment it entered the open chapter (or the chapter was opened). Each gets one defect
128 issue, labelled `bug`, in its repository, titled "#N in chapter X has had no run and no pull for 24 hours";
129 while one is open no second is filed. Draft and closed chapters, and repositories with no chapter, are left
130 alone. Shows as the `chapter-stall` row on `/maintenance`. Test: `test/maintenance-chapter-stall.test.ts`.
src/maintain/duties/chapter_stall.ts added +103
@@ -0,0 +1,103 @@
1 /**
2 * Chapter stall (#14057): an open issue in a repository's open chapter whose last sign of work is
3 * 24 or more hours old files one defect issue in that repository. A sign of work is a run on the
4 * issue, a pull whose description closes it, or the moment it entered the open chapter (so a fresh
5 * chapter, or a fresh addition, is not stalled). A repository with no open chapter is left alone.
6 * The report is keyed on the issue number in its title (`fileIssueOnce`): while one is open no
7 * second is filed, and one issue per stall is the only thing the duty writes. Reads the chapter
8 * items once per repository, runs by `issue_id`, pulls once per repository.
9 */
10
11 import type { Database } from "bun:sqlite";
12 import { fileIssueOnce } from "../../checks/flake.ts";
13 import { closesFromBody } from "../../core/pulls.ts";
14 import { createLabel, getLabel } from "../../core/issues.ts";
15 import { LABEL_COLORS } from "../../hunt/finding.ts";
16 import type { Duty } from "../duty.ts";
17
18 export const STALL_HOURS = 24;
19 const HOUR_MS = 3_600_000;
20
21 export interface Stalled {
22 readonly repoId: string;
23 readonly owner: string;
24 readonly name: string;
25 readonly chapter: string;
26 readonly number: number;
27 readonly title: string;
28 readonly lastSign: string;
29 readonly hours: number;
30 }
31
32 export const titleOf = (chapter: string, number: number): string => `#${number} in chapter ${chapter} has had no run and no pull for ${STALL_HOURS} hours`;
33
34 /** Stalled issues of every open chapter at `now`, by repository then issue number. */
35 export function stalledIssues(db: Database, now: Date, hours = STALL_HOURS): Stalled[] {
36 const cutoff = new Date(now.getTime() - hours * HOUR_MS).toISOString();
37 const chapters = db
38 .query<{ id: string; repo_id: string; name: string; opened_at: string | null; created_at: string; owner: string; repo: string }, []>(
39 `SELECT c.id, c.repo_id, c.name, c.opened_at, c.created_at, u.username AS owner, repo.name AS repo
40 FROM chapter c JOIN repo ON repo.id = c.repo_id JOIN user u ON u.id = repo.owner_id
41 WHERE c.state = 'open' ORDER BY c.repo_id`,
42 )
43 .all();
44 const out: Stalled[] = [];
45 for (const c of chapters) {
46 const items = db
47 .query<{ id: string; number: number; title: string; at: string }, [string]>(
48 `SELECT i.id, i.number, i.title, ci.at FROM chapter_item ci JOIN issue i ON i.id = ci.issue_id
49 WHERE ci.chapter_id = ?1 AND i.state = 'open' AND i.kind = 'issue' ORDER BY i.number`,
50 )
51 .all(c.id);
52 if (items.length === 0) continue;
53 const pulls = db
54 .query<{ body: string | null; created_at: string }, [string]>("SELECT body, created_at FROM issue WHERE repo_id = ?1 AND kind = 'pull'")
55 .all(c.repo_id);
56 const pullAt = new Map<number, string>();
57 for (const p of pulls)
58 for (const n of closesFromBody(p.body ?? "")) if ((pullAt.get(n) ?? "") < p.created_at) pullAt.set(n, p.created_at);
59 for (const it of items) {
60 const run = db.query<{ at: string | null }, [string]>("SELECT MAX(created_at) AS at FROM run WHERE issue_id = ?1").get(it.id)?.at ?? "";
61 const last = [it.at, c.opened_at ?? c.created_at, run, pullAt.get(it.number) ?? ""].reduce((a, b) => (a > b ? a : b));
62 if (last >= cutoff) continue;
63 out.push({ repoId: c.repo_id, owner: c.owner, name: c.repo, chapter: c.name, number: it.number, title: it.title, lastSign: last, hours: Math.floor((now.getTime() - Date.parse(last)) / HOUR_MS) });
64 }
65 }
66 return out;
67 }
68
69 const oneLine = (s: string): string => s.replace(/\s+/g, " ").replace(/[<>`]/g, "").trim().slice(0, 120);
70
71 export function bodyOf(s: Stalled): string {
72 return (
73 `_Filed by the chapter stall duty from the run and pull tables, not written by a person._\n\n` +
74 `#${s.number} ${oneLine(s.title)} is in the open chapter ${oneLine(s.chapter)} of ${s.owner}/${s.name}. Its last sign of work was at ${s.lastSign} (${s.hours} hours ago): no run on it and no pull for it since.\n\n` +
75 `Start it, split it, or take it out of the chapter. One issue stays open at a time; close it while the stall lasts and the next day files a fresh one.`
76 );
77 }
78
79 export const duty: Duty = {
80 name: "chapter-stall",
81 intervalMs: 24 * HOUR_MS,
82 budget: { runsPerDay: 3, dollarsPerDay: 1, reason: "once a day; the rest is room for a catch-up, and it spends no money" },
83 run({ db, bus, now, app }) {
84 if (app === undefined) return { findings: [], actions: [] };
85 const findings = [];
86 const actions: string[] = [];
87 for (const s of stalledIssues(db, now)) {
88 const repo = db.query<{ id: string; owner_id: string }, [string]>("SELECT id, owner_id FROM repo WHERE id = ?1").get(s.repoId);
89 if (repo === null) continue;
90 const label = getLabel(db, s.repoId, "bug") ?? (() => {
91 const made = createLabel(db, s.repoId, "bug", LABEL_COLORS.bug ?? "ededed");
92 return made.ok ? made.value : undefined;
93 })();
94 const filed = fileIssueOnce(db, bus, { id: repo.id, ownerId: repo.owner_id }, { title: titleOf(s.chapter, s.number), body: bodyOf(s), ...(label ? { labelId: label.id } : {}) });
95 findings.push({
96 summary: `#${s.number} in chapter ${s.chapter} of ${s.owner}/${s.name} has had no run and no pull for ${s.hours} hours`,
97 probe: { kind: "measurement" as const, what: `hours #${s.number} of ${s.owner}/${s.name} has stood without a run or pull`, number: s.hours, at: now.toISOString() },
98 });
99 if (filed.opened) actions.push(`filed #${filed.number} on ${s.owner}/${s.name}`);
100 }
101 return { findings, actions };
102 },
103 };
src/maintain/registry.ts +2 −1
@@ -16,9 +16,10 @@ import { duty as staleIssues } from "./duties/stale_issues.ts";
1616 import { duty as waitSplit } from "./duties/wait_split.ts";
1717 import { duty as redApps } from "./duties/red_apps.ts";
1818 import { duty as flakyTests } from "./duties/flaky_tests.ts";
19 import { duty as chapterStall } from "./duties/chapter_stall.ts";
1920 import { dutyIdle } from "./duties/duty_idle.ts";
2021
21 const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches, previewDirs, staleIssues, waitSplit, flakyTests, redApps];
22 const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches, previewDirs, staleIssues, waitSplit, flakyTests, redApps, chapterStall];
2223
2324 /** The duties plus the one that watches them for silence. */
2425 export const duties: readonly Duty[] = [...others, dutyIdle(others)];
src/perf/page_budget.ts +4 −3
@@ -34,7 +34,7 @@ export const PAGE_BUDGETS: readonly PageBudget[] = [
3434 { page: "map", pattern: "/map", medianMs: 50, statements: 21 },
3535 { page: "an app page", pattern: "/:owner/:name", medianMs: 50, statements: 49 },
3636 { page: "changelog", pattern: "/changelog", medianMs: 50, statements: 20 },
37 { page: "next up", pattern: "/:owner/:name/next", medianMs: 50, statements: 65 },
37 { page: "next up", pattern: "/:owner/:name/next", medianMs: 50, statements: 68 },
3838 // The space (#12770), which the owner opens to watch growth: the page and the
3939 // `space.json` it reads are two requests, so each has its own row.
4040 // Statement limits: measured warm (15 and 6) plus two, the margin the map row keeps.
@@ -43,8 +43,9 @@ export const PAGE_BUDGETS: readonly PageBudget[] = [
4343 // The admin board of duties (#13388): walked as the admin, stored rows only. Statements: measured
4444 // warm (53, with main's duties) plus nine: each of the eight duties reads its own state and
4545 // runs, so the count moves with duty state and background ticks; an N+1 over the duties would
46 // still show. Two more duties (flaky-tests #13937, red apps #13938) each read their own state.
47 { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 65 },
46 // still show. Three more duties (flaky-tests #13937, red apps #13938, chapter stall #14057) each
47 // read their own state.
48 { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 68 },
4849 // A stranger's way to a forge (#11410): walked signed out. `/claim` is
4950 // measured on a spawned forge with a live link, as the child's owner sees it.
5051 { page: "pricing", pattern: "/pricing", medianMs: 50, statements: 10, signedOut: true },
test/maintenance-chapter-stall.test.ts added +85
@@ -0,0 +1,85 @@
1 /**
2 * Chapter stall (#14057): an issue in the open chapter with no run and no pull for 24 hours files
3 * one defect; none when no chapter is open; never twice. Time is the `now` passed in.
4 */
5 import { expect, test } from "bun:test";
6 import { rulesWorld } from "./helpers/rules-app.ts";
7 import { duty, stalledIssues } from "../src/maintain/duties/chapter_stall.ts";
8 import { duties } from "../src/maintain/registry.ts";
9 import { createIssue } from "../src/core/issues.ts";
10 import { id } from "../src/kernel/id.ts";
11
12 const w = rulesWorld();
13 const NOW = new Date("2026-11-16T12:00:00Z");
14 const ago = (h: number): string => new Date(NOW.getTime() - h * 3_600_000).toISOString();
15 const run = async (now = NOW) => await duty.run({ db: w.app.db, bus: w.app.bus, app: w.app, now });
16 const reports = () => w.app.db.query<{ title: string; body: string }, [string]>("SELECT title, body FROM issue WHERE repo_id = ?1 AND state = 'open' AND title LIKE '%no run and no pull%'").all(w.repoId);
17
18 function issue(title: string, body = ""): { id: string; number: number } {
19 const r = createIssue(w.app.db, { repoId: w.repoId, authorId: w.ownerId, title, body });
20 if (!r.ok) throw new Error(r.error);
21 return r.value;
22 }
23 function chapter(state: "open" | "draft", openedHoursAgo: number): string {
24 const cid = id();
25 w.app.db.query("INSERT INTO chapter (id, repo_id, name, state, position, created_at, opened_at) VALUES (?1, ?2, ?3, ?4, 0, ?5, ?5)").run(cid, w.repoId, `ch-${cid.slice(-6)}`, state, ago(openedHoursAgo));
26 return cid;
27 }
28 const put = (cid: string, issueId: string, hours: number) => w.app.db.query("INSERT INTO chapter_item (issue_id, chapter_id, at) VALUES (?1, ?2, ?3)").run(issueId, cid, ago(hours));
29
30 test("no chapter open: nothing, even with an idle issue", async () => {
31 issue("idle with no chapter");
32 expect(await run()).toEqual({ findings: [], actions: [] });
33 });
34
35 let cid = "";
36 let idle = { id: "", number: 0 };
37 let busy = { id: "", number: 0 };
38 let fresh = { id: "", number: 0 };
39
40 test("a draft chapter is not stalled; an open one lists its idle issue only", async () => {
41 const draft = chapter("draft", 100);
42 put(draft, issue("in a draft").id, 100);
43 expect((await run()).findings).toEqual([]);
44 cid = chapter("open", 72);
45 idle = issue("the idle one");
46 busy = issue("the busy one");
47 fresh = issue("added an hour ago");
48 put(cid, idle.id, 72);
49 put(cid, busy.id, 72);
50 put(cid, fresh.id, 1);
51 w.app.db.query("INSERT INTO run (id, repo_id, kind, issue_id, created_at) VALUES (?1, ?2, 'agent', ?3, ?4)").run(id(), w.repoId, busy.id, ago(2));
52 const s = stalledIssues(w.app.db, NOW);
53 expect(s.map((x) => x.number)).toEqual([idle.number]);
54 expect(s[0]!.hours).toBe(72);
55 });
56
57 test("one finding and one defect per stalled issue, never a second while open", async () => {
58 const out = await run();
59 expect(out.findings).toHaveLength(1);
60 expect(out.actions).toHaveLength(1);
61 expect(reports()).toHaveLength(1);
62 expect(reports()[0]!.body).toContain(`#${idle.number}`);
63 const again = await run();
64 expect(again.findings).toHaveLength(1);
65 expect(again.actions).toEqual([]);
66 expect(reports()).toHaveLength(1);
67 });
68
69 test("a pull that closes the issue ends the stall; time passing brings it back", async () => {
70 issue("a pull for it", `Closes #${busy.number}, closes #${idle.number}`);
71 w.app.db.query("UPDATE issue SET created_at = ?1 WHERE title = 'a pull for it'").run(ago(3));
72 w.app.db.query("UPDATE issue SET kind = 'pull' WHERE title = 'a pull for it'").run();
73 expect(stalledIssues(w.app.db, NOW)).toEqual([]);
74 const later = new Date(NOW.getTime() + 30 * 3_600_000);
75 expect(stalledIssues(w.app.db, later).map((x) => x.number).sort()).toEqual([busy.number, idle.number, fresh.number].sort());
76 });
77
78 test("a closed issue is not stalled", () => {
79 w.app.db.query("UPDATE issue SET state = 'closed' WHERE id = ?1").run(idle.id);
80 expect(stalledIssues(w.app.db, new Date(NOW.getTime() + 30 * 3_600_000)).map((x) => x.number)).toEqual([busy.number, fresh.number].sort());
81 });
82
83 test("the duty is in the registry", () => {
84 expect(duties.map((d) => d.name)).toContain("chapter-stall");
85 });
test/pages-budget.test.ts +1 −1
@@ -56,7 +56,7 @@ const HEAVIER: Record<string, { statements?: number; git?: number }> = {
5656 "/api/v1/asks": { statements: 61 }, // +1: the stopped apps someone asked for, one read of the viewer's archived repositories (#12277)
5757 "/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
5858 "/settings/capacity": { statements: 70 },
59 "/maintenance": { statements: 65 }, // +2: the flaky-tests (#13937) and red apps (#13938) duties each read their own state and run
59 "/maintenance": { statements: 68 }, // +3: the flaky-tests (#13937), red apps (#13938) and chapter stall (#14057) duties each read their own state and run
6060 };
6161
6262 /** Patterns with no fixture today: lower this as fixtures are added, never raise it silently. */

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs