Public: anyone can read this; the crew can change it.
A duty lists docs that name a file path that no longer exists #13988
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13977-a-duty-lists-docs-that-name-a-file-path → main 9 commits fork 2 threads · 2 unresolved
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). | ||
| 460 | 460 | - [](backup-growth.md) |
| 461 | 461 | - [](backup-age.md) |
| 462 | 462 | - [](disk-free.md) |
| 463 | - [](dead-doc-paths.md) | |
| 463 | 464 | - [](backup-refs.md) |
| 464 | 465 | - [](forge-origin.md) |
| 465 | 466 | - [](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 | }, | |
| 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"; | ||
| 14 | 14 | import { duty as diskFree } from "./duties/disk_free.ts"; |
| 15 | 15 | import { duty as staleIssues } from "./duties/stale_issues.ts"; |
| 16 | 16 | import { duty as waitSplit } from "./duties/wait_split.ts"; |
| 17 | import { duty as deadDocPaths } from "./duties/dead_doc_paths.ts"; | |
| 17 | 18 | import { duty as redApps } from "./duties/red_apps.ts"; |
| 18 | 19 | import { duty as flakyTests } from "./duties/flaky_tests.ts"; |
| 19 | 20 | import { duty as chapterStall } from "./duties/chapter_stall.ts"; |
| 20 | 21 | import { dutyIdle } from "./duties/duty_idle.ts"; |
| 21 | 22 | |
| 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]; | |
| 23 | 24 | |
| 24 | 25 | /** The duties plus the one that watches them for silence. */ |
| 25 | 26 | 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[] = [ | ||
| 43 | 43 | // The admin board of duties (#13388): walked as the admin, stored rows only. Statements: measured |
| 44 | 44 | // warm (53, with main's duties) plus nine: each of the eight duties reads its own state and |
| 45 | 45 | // 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 | |
| 47 | 48 | // read their own state. |
| 48 | { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 68 }, | |
| 49 | { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 72 }, | |
| 49 | 50 | // A stranger's way to a forge (#11410): walked signed out. `/claim` is |
| 50 | 51 | // measured on a spawned forge with a live link, as the child's owner sees it. |
| 51 | 52 | { 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 }> = { | ||
| 56 | 56 | "/api/v1/asks": { statements: 61 }, // +1: the stopped apps someone asked for, one read of the viewer's archived repositories (#12277) |
| 57 | 57 | "/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 |
| 58 | 58 | "/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 | |
| 60 | 60 | }; |
| 61 | 61 | |
| 62 | 62 | /** Patterns with no fixture today: lower this as fixtures are added, never raise it silently. */ |
new above
offline
No docs/features/dead-doc-paths.md for this duty. Add one, with its README row.