Public: anyone can read this; the crew can change it.
A weekly maintenance duty lists source files that no test imports #14146
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/14125-a-weekly-maintenance-duty-lists-source-f → main 7 commits fork
6 files
changed +150
−4
docs/features/maintenance.md +9
| @@ -120,6 +120,15 @@ open at a time: while it is open no second is filed, and closing it while the ch | ||
| 120 | 120 | next day file a fresh one. The duty never comments on or closes an issue. It shows as the `red-apps` row |
| 121 | 121 | on `/maintenance`. Test: `test/maintain-red-apps.test.ts`. |
| 122 | 122 | |
| 123 | ## Untested sources (#14125) | |
| 124 | ||
| 125 | The `untested-sources` duty runs weekly and reads the forge's own checkout: each `.ts` file under `src/` | |
| 126 | that no file under `test/` imports by path, minus `ENTRY_POINTS` (one array, a reason each). It files one | |
| 127 | finding with the first ten names and the count of the rest, never one per file, and none when the list is | |
| 128 | empty. Matching is by import path in the text, so a dynamic import built at run time is missed; every | |
| 129 | finding says so in its footer. It shows as the `untested-sources` row on `/maintenance`. Test: | |
| 130 | `test/maint-untested.test.ts`. | |
| 131 | ||
| 123 | 132 | ## Chapter stall (#14057) |
| 124 | 133 | |
| 125 | 134 | The `chapter-stall` duty runs once a day. For each repository with an open chapter it lists the chapter's |
src/maintain/duties/untested_sources.ts added +75
| @@ -0,0 +1,75 @@ | ||
| 1 | /** | |
| 2 | * Untested sources (#14125): each `.ts` file under `src/` that no file under `test/` imports by | |
| 3 | * path, so the crew has small, safe work (a characterization test) to pick up. It reads the | |
| 4 | * forge's own checkout, never the database, and files one finding naming the first ten, not one | |
| 5 | * per file; an empty list files nothing. Entry points, which a test cannot import because | |
| 6 | * something else runs them, are listed in `ENTRY_POINTS` with a reason each. | |
| 7 | */ | |
| 8 | ||
| 9 | import { readFileSync } from "node:fs"; | |
| 10 | import { dirname, join, normalize } from "node:path"; | |
| 11 | import type { Duty } from "../duty.ts"; | |
| 12 | ||
| 13 | /** Files a test never imports by design: each is started by the runtime or a script, with why. */ | |
| 14 | export const ENTRY_POINTS: readonly { readonly path: string; readonly reason: string }[] = [ | |
| 15 | { path: "src/main.ts", reason: "the process entry forge.json runs; tests boot the app through createApp" }, | |
| 16 | ]; | |
| 17 | ||
| 18 | /** How many names the finding carries. */ | |
| 19 | export const SHOWN = 10; | |
| 20 | ||
| 21 | /** The caveat every finding ends with: matching is by path string. */ | |
| 22 | export const FOOTER = | |
| 23 | "Matching is by import path in the text of each test file: a dynamic import whose path is built at run time, or a file reached only through another source file, is not seen, so a name here may still be tested."; | |
| 24 | ||
| 25 | const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*|\bmodule\s*\(\s*)["']([^"'\n]+)["']/g; | |
| 26 | ||
| 27 | const files = (root: string, pattern: string): string[] => [...new Bun.Glob(pattern).scanSync({ cwd: root })].sort(); | |
| 28 | ||
| 29 | /** | |
| 30 | * The `src/` paths one test file's relative imports name, with and without an index or extension. | |
| 31 | */ | |
| 32 | function importedBy(root: string, testFile: string): string[] { | |
| 33 | const text = readFileSync(join(root, testFile), "utf8"); | |
| 34 | const out: string[] = []; | |
| 35 | for (const m of text.matchAll(SPECIFIER)) { | |
| 36 | const spec = m[1]!; | |
| 37 | if (!spec.startsWith(".")) continue; | |
| 38 | const path = normalize(join(dirname(testFile), spec)).replaceAll("\\", "/"); | |
| 39 | out.push(path, `${path}.ts`, `${path}/index.ts`); | |
| 40 | } | |
| 41 | return out; | |
| 42 | } | |
| 43 | ||
| 44 | /** Source files under `src/` that no test imports by path, minus the entry points; sorted. */ | |
| 45 | export function untestedSources(root: string, entries: readonly { readonly path: string }[] = ENTRY_POINTS): string[] { | |
| 46 | const seen = new Set<string>(); | |
| 47 | for (const t of files(root, "test/**/*.ts")) for (const p of importedBy(root, t)) seen.add(p); | |
| 48 | const skip = new Set(entries.map((e) => e.path)); | |
| 49 | return files(root, "src/**/*.ts").filter((f) => !f.endsWith(".d.ts") && !skip.has(f) && !seen.has(f)); | |
| 50 | } | |
| 51 | ||
| 52 | /** The finding's one sentence: the count, the first ten names, how many more, and the footer. */ | |
| 53 | export function summaryOf(list: readonly string[]): string { | |
| 54 | const more = list.length > SHOWN ? `; and ${list.length - SHOWN} more` : ""; | |
| 55 | return `${list.length} source file${list.length === 1 ? "" : "s"} under src/ no test imports by path: ${list.slice(0, SHOWN).join(", ")}${more}. ${FOOTER}`; | |
| 56 | } | |
| 57 | ||
| 58 | /** The duty over a checkout at `root`: a test points it at a fixture tree. */ | |
| 59 | export function untestedDuty(root: string, entries: readonly { readonly path: string }[] = ENTRY_POINTS): Duty { | |
| 60 | return { | |
| 61 | name: "untested-sources", | |
| 62 | intervalMs: 7 * 24 * 3_600_000, | |
| 63 | budget: { runsPerDay: 2, dollarsPerDay: 1, reason: "weekly; the rest is room for a catch-up, and it spends no money" }, | |
| 64 | run({ now }) { | |
| 65 | const list = untestedSources(root, entries); | |
| 66 | if (list.length === 0) return { findings: [], actions: [] }; | |
| 67 | return { | |
| 68 | findings: [{ summary: summaryOf(list), probe: { kind: "measurement", what: "source files under src/ that no test under test/ imports by path", number: list.length, at: now.toISOString() } }], | |
| 69 | actions: [], | |
| 70 | }; | |
| 71 | }, | |
| 72 | }; | |
| 73 | } | |
| 74 | ||
| 75 | export const duty: Duty = untestedDuty(new URL("../../..", import.meta.url).pathname); |
src/maintain/registry.ts +2 −1
| @@ -17,10 +17,11 @@ import { duty as waitSplit } from "./duties/wait_split.ts"; | ||
| 17 | 17 | import { duty as deadDocPaths } from "./duties/dead_doc_paths.ts"; |
| 18 | 18 | import { duty as redApps } from "./duties/red_apps.ts"; |
| 19 | 19 | import { duty as flakyTests } from "./duties/flaky_tests.ts"; |
| 20 | import { duty as untestedSources } from "./duties/untested_sources.ts"; | |
| 20 | 21 | import { duty as chapterStall } from "./duties/chapter_stall.ts"; |
| 21 | 22 | import { dutyIdle } from "./duties/duty_idle.ts"; |
| 22 | 23 | |
| 23 | const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches, previewDirs, staleIssues, waitSplit, flakyTests, redApps, chapterStall, deadDocPaths]; | |
| 24 | const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches, previewDirs, staleIssues, waitSplit, flakyTests, redApps, chapterStall, deadDocPaths, untestedSources]; | |
| 24 | 25 | |
| 25 | 26 | /** The duties plus the one that watches them for silence. */ |
| 26 | 27 | export const duties: readonly Duty[] = [...others, dutyIdle(others)]; |
src/perf/page_budget.ts +2 −2
| @@ -44,9 +44,9 @@ export const PAGE_BUDGETS: readonly PageBudget[] = [ | ||
| 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 | 46 | // still show. Four more duties (flaky-tests #13937, red apps #13938, chapter stall #14057, |
| 47 | // dead-doc-paths #13977) each | |
| 47 | // dead-doc-paths #13977, untested-sources #14125) each | |
| 48 | 48 | // read their own state. One query reads every dismissal (#13967). |
| 49 | { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 72 }, | |
| 49 | { page: "maintenance", pattern: "/maintenance", medianMs: 50, statements: 75 }, | |
| 50 | 50 | // A stranger's way to a forge (#11410): walked signed out. `/claim` is |
| 51 | 51 | // measured on a spawned forge with a live link, as the child's owner sees it. |
| 52 | 52 | { page: "pricing", pattern: "/pricing", medianMs: 50, statements: 10, signedOut: true }, |
test/maint-untested.test.ts added +61
| @@ -0,0 +1,61 @@ | ||
| 1 | /** Untested sources (#14125): the duty on a tiny fixture tree. */ | |
| 2 | import { afterAll, expect, test } from "bun:test"; | |
| 3 | import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { dirname, join } from "node:path"; | |
| 6 | import { rulesWorld } from "./helpers/rules-app.ts"; | |
| 7 | import { duties } from "../src/maintain/registry.ts"; | |
| 8 | import { FOOTER, SHOWN, untestedDuty, untestedSources } from "../src/maintain/duties/untested_sources.ts"; | |
| 9 | ||
| 10 | const dirs: string[] = []; | |
| 11 | function tree(files: Record<string, string>): string { | |
| 12 | const root = mkdtempSync(join(tmpdir(), "forge-untested-")); | |
| 13 | dirs.push(root); | |
| 14 | for (const [p, text] of Object.entries(files)) { | |
| 15 | mkdirSync(dirname(join(root, p)), { recursive: true }); | |
| 16 | writeFileSync(join(root, p), text); | |
| 17 | } | |
| 18 | return root; | |
| 19 | } | |
| 20 | afterAll(() => dirs.forEach((d) => rmSync(d, { recursive: true, force: true }))); | |
| 21 | const w = rulesWorld(); | |
| 22 | const NOW = new Date("2026-11-16T00:00:00Z"); | |
| 23 | const run = async (root: string, entries: readonly { path: string }[] = []) => await untestedDuty(root, entries).run({ db: w.app.db, bus: w.app.bus, app: w.app, now: NOW }); | |
| 24 | ||
| 25 | test("a source no test imports is listed; imported, entry-point and declaration files are not", () => { | |
| 26 | const root = tree({ | |
| 27 | "src/a.ts": "export const a = 1;", | |
| 28 | "src/b.ts": "export const b = 1;", | |
| 29 | "src/sub/index.ts": "export const s = 1;", | |
| 30 | "src/c.ts": "export const c = 1;", | |
| 31 | "src/dyn.ts": "export const d = 1;", | |
| 32 | "src/main.ts": "", | |
| 33 | "src/types.d.ts": "", | |
| 34 | "test/a.test.ts": 'import { a } from "../src/a.ts";\nimport "../src/sub";\nconst x = await import("../src/c.ts");', | |
| 35 | }); | |
| 36 | expect(untestedSources(root, [{ path: "src/main.ts" }])).toEqual(["src/b.ts", "src/dyn.ts"]); | |
| 37 | }); | |
| 38 | ||
| 39 | test("one finding carries the first ten names, the rest counted, and the footer", async () => { | |
| 40 | const files: Record<string, string> = { "test/x.test.ts": "" }; | |
| 41 | for (let i = 0; i < 13; i++) files[`src/m${String(i).padStart(2, "0")}.ts`] = ""; | |
| 42 | const out = await run(tree(files)); | |
| 43 | expect(out.findings).toHaveLength(1); | |
| 44 | const f = out.findings[0]!; | |
| 45 | expect(f.probe!.number).toBe(13); | |
| 46 | expect(SHOWN).toBe(10); | |
| 47 | expect(f.summary).toContain("13 source files"); | |
| 48 | expect(f.summary).toContain("m09.ts"); | |
| 49 | expect(f.summary).not.toContain("m10.ts"); | |
| 50 | expect(f.summary).toContain("and 3 more"); | |
| 51 | expect(f.summary).toContain(FOOTER); | |
| 52 | }); | |
| 53 | ||
| 54 | test("an empty list files nothing", async () => { | |
| 55 | const root = tree({ "src/a.ts": "", "test/a.test.ts": 'import "../src/a.ts";' }); | |
| 56 | expect(await run(root)).toEqual({ findings: [], actions: [] }); | |
| 57 | }); | |
| 58 | ||
| 59 | test("it is registered", () => { | |
| 60 | expect(duties.map((d) => d.name)).toContain("untested-sources"); | |
| 61 | }); |
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: 72 }, // main's 72 already had a statement to spare, which the one dismissal query (#13967) takes; +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 | |
| 59 | "/maintenance": { statements: 75 }, // +3: untested-sources (#14125) reads its own state and runs, and the dismissal query (#13967) is one more; +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