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

A duty lists docs that name a file path that no longer exists #13988

Merged opened this

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

Merged

scout/forge:scout/13977-a-duty-lists-docs-that-name-a-file-path → main 9 commits fork 2 threads · 2 unresolved

  • Merged. scout/13977-a-duty-lists-docs-that-name-a-file-path was merged into main as 1842857.

Review

Sign in to review this change.
7 files changed +165 −4
docs/features/README.md +1
@@ -460,6 +460,7 @@ Read with the guide page [Backups and moving](../guide-backups-moving.md).
460460 - [A nightly backup that doubles](backup-growth.md)
461461 - [A backup that stopped landing](backup-age.md)
462462 - [A data volume that is filling up](disk-free.md)
463 - [A doc that names a file that is gone](dead-doc-paths.md)
463464 - [A branch that cannot be backed up](backup-refs.md)
464465 - [A forge is an origin](forge-origin.md)
465466 - [A pull proposed to an origin, and its state coming back](origin-pull-state.md)
docs/features/dead-doc-paths.md added +19
@@ -0,0 +1,19 @@
1 # A doc that names a file that is gone
2
3 The `dead-doc-paths` maintenance duty (#13977) lists the `src/` and `test/` files that
4 `docs/*.md` and `docs/features/*.md` name and the tree no longer has, so a rename or a removal
5 does not leave a doc pointing at nothing.
6
7 - **What it reads.** Every `.md` directly under `docs/` and `docs/features/`, line by line.
8 A path counts when it starts `src/` or `test/` and ends in a file extension. Globs
9 (`src/*.ts`), placeholders (`src/<name>/x.ts`), directories and paths inside a longer path
10 (`docs/src/z.ts`) are skipped. Each path is checked once per doc, at its first line.
11 - **What it says.** One finding per doc that has any: the doc, then each dead path with its
12 line. A measurement probe carries that doc's count.
13 - **Read-only.** It opens files and checks they exist; it changes nothing and spends no money.
14 It runs once a day.
15 - **Where it shows.** On the maintenance board (`/maintenance`, admin) as the `dead-doc-paths`
16 row. The terminal's "Maintenance duty runs" screen reads the same run records
17 (`latest`, `src/maintain/runs.ts`), so the run shows there as a row with its finding count;
18 the finding text itself is on `/maintenance` and in `GET /api/v1/maintenance/runs`.
19 `test/maintain-dead-doc-paths.test.ts` shows a run reaching that screen.
src/maintain/duties/dead_doc_paths.ts added +77
@@ -0,0 +1,77 @@
1 /**
2 * Dead doc paths (#13977): docs/*.md and docs/features/*.md that name a src/ or test/ file which is
3 * no longer in the tree. The duty only reads: it opens the docs and checks each named path exists,
4 * and says which doc and line named it.
5 */
6
7 import { existsSync, readdirSync, readFileSync } from "node:fs";
8 import { join } from "node:path";
9 import type { Duty } from "../duty.ts";
10
11 export interface DeadPath {
12 /** The doc, relative to the root, e.g. `docs/GIT.md`. */
13 readonly doc: string;
14 readonly line: number;
15 readonly path: string;
16 }
17
18 /**
19 * A src/ or test/ path ending in a file extension, not part of a longer path, glob or placeholder.
20 */
21 const PATH = /(?<![\w./-])(?:src|test)\/[\w.-]+(?:\/[\w.-]+)*\.[A-Za-z0-9]+(?![\w*{<[/-])/g;
22 const MAX_DOC_BYTES = 1_000_000;
23
24 function docsIn(root: string, dir: string): string[] {
25 try {
26 return readdirSync(join(root, dir)).filter((n) => n.endsWith(".md")).sort().map((n) => `${dir}/${n}`);
27 } catch {
28 return [];
29 }
30 }
31
32 /** Every path the docs name that is missing under `root`, in doc then line order. */
33 export function deadDocPaths(root: string = process.cwd()): DeadPath[] {
34 const out: DeadPath[] = [];
35 for (const doc of [...docsIn(root, "docs"), ...docsIn(root, "docs/features")]) {
36 let text: string;
37 try {
38 text = readFileSync(join(root, doc), "utf8");
39 } catch {
40 continue;
41 }
42 if (text.length > MAX_DOC_BYTES) continue;
43 const seen = new Set<string>();
44 text.split("\n").forEach((lineText, i) => {
45 for (const m of lineText.matchAll(PATH)) {
46 const path = m[0];
47 if (seen.has(path) || existsSync(join(root, path))) continue;
48 seen.add(path);
49 out.push({ doc, line: i + 1, path });
50 }
51 });
52 }
53 return out;
54 }
55
56 export const makeDuty = (root?: string): Duty => ({
57 name: "dead-doc-paths",
58 intervalMs: 24 * 3_600_000,
59 budget: { runsPerDay: 3, dollarsPerDay: 1, reason: "once a day is enough for a doc to go stale; it reads files and spends no money" },
60 run({ now }) {
61 const dead = deadDocPaths(root);
62 if (dead.length === 0) return { findings: [], actions: [] };
63 // One finding per doc, every dead path in it with its line, so a person can reach them all.
64 const byDoc = new Map<string, DeadPath[]>();
65 for (const d of dead) byDoc.set(d.doc, [...(byDoc.get(d.doc) ?? []), d]);
66 const at = now.toISOString();
67 return {
68 findings: [...byDoc].map(([doc, paths]) => ({
69 summary: `${doc} names ${paths.length} path${paths.length === 1 ? "" : "s"} no longer in the tree: ${paths.map((d) => `${d.path} (line ${d.line})`).join("; ")}`,
70 probe: { kind: "measurement", what: `src/ and test/ paths named in ${doc} that are not in the tree`, number: paths.length, at },
71 })),
72 actions: [],
73 };
74 },
outdated

No docs/features/dead-doc-paths.md for this duty. Add one, with its README row.

75 });
76
77 export const duty: Duty = makeDuty();
src/maintain/registry.ts +2 −1
@@ -14,12 +14,13 @@ import { duty as previewDirs } from "./previews.ts";
1414 import { duty as diskFree } from "./duties/disk_free.ts";
1515 import { duty as staleIssues } from "./duties/stale_issues.ts";
1616 import { duty as waitSplit } from "./duties/wait_split.ts";
17 import { duty as deadDocPaths } from "./duties/dead_doc_paths.ts";
1718 import { duty as redApps } from "./duties/red_apps.ts";
1819 import { duty as flakyTests } from "./duties/flaky_tests.ts";
1920 import { duty as chapterStall } from "./duties/chapter_stall.ts";
2021 import { dutyIdle } from "./duties/duty_idle.ts";
2122
22 const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches, previewDirs, staleIssues, waitSplit, flakyTests, redApps, chapterStall];
23 const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches, previewDirs, staleIssues, waitSplit, flakyTests, redApps, chapterStall, deadDocPaths];
2324
2425 /** The duties plus the one that watches them for silence. */
2526 export const duties: readonly Duty[] = [...others, dutyIdle(others)];
src/perf/page_budget.ts +3 −2
@@ -43,9 +43,10 @@ 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. Three more duties (flaky-tests #13937, red apps #13938, chapter stall #14057) each
46 // still show. Four more duties (flaky-tests #13937, red apps #13938, chapter stall #14057,
47 // dead-doc-paths #13977) each
4748 // read their own state.
48 { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 68 },
49 { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 72 },
4950 // A stranger's way to a forge (#11410): walked signed out. `/claim` is
5051 // measured on a spawned forge with a live link, as the child's owner sees it.
5152 { page: "pricing", pattern: "/pricing", medianMs: 50, statements: 10, signedOut: true },
test/maintain-dead-doc-paths.test.ts added +62
@@ -0,0 +1,62 @@
1 /**
2 * Dead doc paths (#13977): a fixture doc names one live and one dead path; exactly the dead one is
3 * found.
4 */
5 import { expect, test } from "bun:test";
6 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
7 import { tmpdir } from "node:os";
8 import { join } from "node:path";
9 import { deadDocPaths, duty, makeDuty } from "../src/maintain/duties/dead_doc_paths.ts";
10 import { duties } from "../src/maintain/registry.ts";
11 import { getUserByName } from "../src/core/users.ts";
12 import { Session } from "../src/tui/session.ts";
13 import { rulesWorld } from "./helpers/rules-app.ts";
14
15 const w = rulesWorld();
16
17 const root = mkdtempSync(join(tmpdir(), "dead-doc-"));
18 mkdirSync(join(root, "docs", "features"), { recursive: true });
19 mkdirSync(join(root, "src", "a"), { recursive: true });
20 mkdirSync(join(root, "test"));
21 writeFileSync(join(root, "src", "a", "live.ts"), "");
22 writeFileSync(join(root, "test", "live.test.ts"), "");
23 writeFileSync(
24 join(root, "docs", "FIX.md"),
25 ["# Fixture", "Lives in `src/a/live.ts` and `test/live.test.ts`.", "Was in `src/a/gone.ts`, see also src/a/*.ts and src/<name>/x.ts and docs/src/z.ts."].join("\n"),
26 );
27 writeFileSync(join(root, "docs", "features", "F.md"), "nothing here\n");
28
29 test("exactly the dead path is found, with its doc and line", () => {
30 expect(deadDocPaths(root)).toEqual([{ doc: "docs/FIX.md", line: 3, path: "src/a/gone.ts" }]);
31 });
32
33 test("the duty makes one finding with a probe, and none when nothing is dead", async () => {
34 const ctx = { db: w.app.db, bus: w.app.bus, app: w.app, now: new Date("2026-11-16T00:00:00Z") };
35 const r = await makeDuty(root).run(ctx);
36 expect(r.findings).toHaveLength(1);
37 expect(r.findings[0]!.summary).toContain("docs/FIX.md names 1 path no longer in the tree: src/a/gone.ts (line 3)");
38 expect(r.findings[0]!.probe?.number).toBe(1);
39 expect(await makeDuty(mkdtempSync(join(tmpdir(), "dead-doc-empty-"))).run(ctx)).toEqual({ findings: [], actions: [] });
40 });
41
42 test("the duty is registered", () => {
43 expect(duties).toContain(duty);
44 });
45
46 test("one finding per doc, every dead path listed, and the terminal's run board counts them", async () => {
47 const r2 = mkdtempSync(join(tmpdir(), "dead-doc-two-"));
48 mkdirSync(join(r2, "docs"), { recursive: true });
49 writeFileSync(join(r2, "docs", "A.md"), "src/a1.ts src/a2.ts src/a3.ts src/a4.ts src/a5.ts\n");
50 writeFileSync(join(r2, "docs", "B.md"), "see test/b.test.ts\n");
51 const ctx = { db: w.app.db, bus: w.app.bus, app: w.app, now: new Date("2026-11-16T00:00:00Z") };
52 const res = await makeDuty(r2).run(ctx);
53 expect(res.findings).toHaveLength(2);
54 expect(res.findings[0]!.summary).toContain("src/a5.ts (line 1)");
55 const { startMaintain } = await import("../src/maintain/runner.ts");
56 const { runLines } = await import("../src/tui/screens/maintainruns.ts");
57 const m = startMaintain(w.app, { duties: [makeDuty(r2)], everyMs: 1e9 });
58 m.stop();
59 await m.tick();
60 const row = runLines(new Session(w.app, { sshUsername: "alice", remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user: getUserByName(w.app.db, "alice")! })).find((l) => l.startsWith("dead-doc-paths"));
61 expect(row).toMatch(/dead-doc-paths\s+\S+ \S+\s+2\s/);
62 });
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: 68 }, // +3: the flaky-tests (#13937), red apps (#13938) and chapter stall (#14057) duties each read their own state and run
59 "/maintenance": { statements: 72 }, // +4: the flaky-tests (#13937), red apps (#13938) and chapter stall (#14057) and dead-doc-paths (#13977) 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