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

I added a dead-doc-paths maintenance duty. It runs daily, only reads files, and spends no money. It is registered in src/maintain/registry.ts.

Notes

shipped production is serving it deploy 4adf612

opened this

I added a dead-doc-paths maintenance duty. It runs daily, only reads files, and spends no money. It is registered in src/maintain/registry.ts.

It scans docs/.md and docs/features/.md for src/… and test/… paths that end in a file extension and aren't in the tree. Each dead path is reported once per doc, with the doc and line of its first mention, and the finding's probe gives the count. Globs (src/a/*.ts), placeholders (src/<name>/x.ts) and longer paths like docs/src/z.ts are ignored.

The duty makes one finding per run, so it shows on /maintenance through the same run board as the other duties. The finding lists up to four doc:line path entries followed by "…". I did not open /maintenance in a browser. I did run deadDocPaths() on the real tree, and it finds 36 dead paths today (for example src/source.ts in docs/ADAPTERS.md). The first run will therefore file a finding right away.

test/maintain-dead-doc-paths.test.ts uses a fixture tree with one live and one dead path, plus a glob, a placeholder and a longer path, and finds exactly the dead one. It also checks that the finding carries a probe and that a tree with no dead paths gives no finding. A third test checks the duty is registered. The new test, test/maintain.test.ts and test/maintain-week-line.test.ts pass, and tsc and the gate are clean (the gate rewrapped comments in two files, committed).

Left out:

  • Scan reach: subdirectories other than docs/features/ aren't scanned, and neither is AGENTS.md or the README.
  • Feature note: there is no docs/features note for the duty, which would need a row in the hot docs/features/README.md. That file is only read.
  • Full list: /maintenance shows the first four entries. The full list is available from deadDocPaths().

Closes #13977

Show 1 earlier items

7 earlier comments · 1 event
commented

The failing check is fixed and pushed. I removed both as never casts from test/maintain-dead-doc-paths.test.ts. The test now builds a real duty context from rulesWorld() and awaits the duty's result.

bun scripts/gate.ts now exits 0 on the committed state. The --fix run I made just before committing still printed the two cast complaints, so the gate was probably reading the old commit. Plain tsc is clean and the 3 tests in that file pass.

I didn't re-run the other maintain tests or the forge's full check. The forge will run the check against this push.

commented

Merged main into the branch and pushed. The only conflict was in src/maintain/registry.ts, where main added the flaky-tests duty next to my dead-doc-paths one. I kept both imports and both entries in the duties list.

The gate rewrapped comments in one file, and I committed that along with the merge. tsc is clean. The tests for dead doc paths, maintain.test.ts and the week line pass (30 tests). I did not run the full suite; the forge's check does that on this push.

commented

I restored src/spawn/host.ts to its state on main, so this pull no longer touches it. The gate failed on that file because the pull had rewrapped the comment above roomLocks, which it did not write.

After the restore, bun scripts/gate.ts prints nothing and the diff against main shows no change to that file. I did not re-run tsc or the tests, since nothing else changed. The fix is pushed as a38709c36, so the forge's check will run again on the new push.

commented

The pull adds a maintenance duty, dead-doc-paths. Once a day it reads docs/.md and docs/features/.md and reports each src/ or test/ path a doc names that is no longer in the tree. Each report gives the doc and line, and the duty only reads files and spends no money.

  • Page budget: the duty is one more entry in the registry, and it added two SQL statements to /maintenance, from 63 to 65. I raised the budget to 66 in src/perf/page_budget.ts and test/pages-budget.test.ts, the same way the previous duty's change did. This fixes the two budget failures from the last check.
  • Stranger-pull test: "a slice is read against the guard as the whole pull is" passes when run alone and nothing in this diff touches it, so I left it as flaky. I did not reproduce the failure, so if it recurs on this push it is not caused by this change.
  • Earlier gate failure: src/spawn/host.ts is restored to main, so the pull no longer touches it.

The two budget test files and the duty's test all pass (13 tests), and the gate and tsc are clean. I did not run the full suite, since the forge runs it on push.

To try it, open /maintenance as an admin. The duty only produces a finding when a doc names a path that is missing.

I left out glob, placeholder and {a,b} paths. A path in a doc that is not a plain src/… or test/… file name is skipped rather than guessed at.

commented

I merged main into the branch and pushed it. I ran the maintenance and page-budget tests plus tsc and the gate; I did not run the whole suite. The forge's check runs on this push.

All three conflicts came from main adding the red-apps duty alongside this pull's dead-doc-paths duty.

  • src/maintain/registry.ts: both duties are registered. The list now ends flakyTests, redApps, deadDocPaths.
  • /maintenance statement budget: this is in src/perf/page_budget.ts and test/pages-budget.test.ts. With all three duties the page measures 68 statements, so I set the limit to 69. It was 66 here and 65 on main. The comments name all three duties.

Results after the merge:

  • test/pages-budget.test.ts passes (4 of 4).
  • The maintenance tests I ran pass (137).
  • bun x tsc --noEmit is clean.
  • bun scripts/gate.ts --fix rewrapped comments in one file, and that change went into the merge commit.
  • scripts/fast.ts exited 2 because the diff is too broad to name test files, so I picked the maintenance and page-budget tests myself.

The merge commit also swept in test/statement.test.ts, which showed as modified in the working tree. I did not look at what changed in it.

commented

I restored test/statement.test.ts to its main version and pushed. The earlier merge had swept in a comment rewrap there that this pull didn't write, and the gate's "the diff is the change" rule refused it.

Locally, bun scripts/gate.ts now passes with no output, bun x tsc --noEmit is clean, and test/pages-budget.test.ts passes (4 of 4). I didn't run any other tests, and the forge's check on this push hasn't reported yet.

The pull otherwise carries the dead-doc-paths duty, registered after main's red-apps duty. Together they set the /maintenance statement limit to 69, from 68 measured.

Changes requested — before the latest push

The duty itself is sound: read-only, bounded, globs and placeholders skipped, and the fixture test finds exactly the dead path. Two things must change before it lands.

  1. (first) test/pages-budget.test.ts raises the /:owner/:name/next statement budget from 66 to 69. This pull adds a duty and does not touch that page, and the comment above HEAVIER says to lower these and never raise them. Revert that line to 66. If the page really measures higher on main, that belongs in its own pull.
  2. The checklist asks for the how-to in docs/features/<name>.md. There is none (the pull says it left it out to avoid touching docs/features/README.md). Add docs/features/dead-doc-paths.md with the README row. Also say in the doc how the terminal shows it: if the terminal's maintenance screen reads the same run board, state that and add a test showing the finding reaches it. If it does not, wire it.

Smaller: the finding lists only 4 entries, so on today's 36 dead paths a person cannot reach the rest from /maintenance. Consider listing one finding per doc, or a longer list.

commented

I've addressed both requested changes and the smaller note, and pushed. tsc, the gate and the dead-doc-paths, pages-budget and maintain tests pass locally; I haven't run any other tests, and the forge's check on this push hasn't reported yet.

  • /next budget: it is back to 66. My merge-fix sed had rewritten every statements: 66 in the file, and I hadn't noticed it also changed /next. /maintenance stays at 69, which is the one budget this pull should move: it measured 68 with this duty alongside the flaky-tests and red-apps duties.
  • How-to: docs/features/dead-doc-paths.md is added, with its row in docs/features/README.md after the disk-free row.
  • Terminal: the terminal's "Maintenance duty runs" screen reads the same run records as /maintenance (latest in src/maintain/runs.ts). The doc says so. The screen shows a run as a row with its finding count, not the finding text, so I did not add new wiring. The new test runs the duty through startMaintain and checks that the row appears on the terminal screen with a count of 2.
  • One finding per doc: each doc with dead paths now gets its own finding, listing every dead path with its line, so nothing is cut off. Each finding carries its own count as the probe. The finding text is visible on /maintenance and in GET /api/v1/maintenance/runs, not on the terminal screen.

The new test also caught a bug of mine. The duty's dollarsPerDay was 0, and the runner treats 0 spent against a cap of 0 as over budget, so the duty never actually ran. It is now 1, like the other duties that spend nothing.

commented

I merged main into the branch and pushed. The gate and tsc are clean, and the pages-budget and dead-doc-paths tests pass (8). I didn't run the rest of the suite, so the forge's check on this push is the full run.

All three conflicts came from main adding the chapter-stall duty next to this pull's dead-doc-paths duty:

  • src/maintain/registry.ts: the duty list now ends …, redApps, chapterStall, deadDocPaths.
  • /maintenance budget (src/perf/page_budget.ts, test/pages-budget.test.ts): the page measures 71 statements with four new duties, so the limit is 72, up from 68 on main. The comments name all four duties. The other budgets are unchanged from main.
  • Terminal test: the gate now refuses as never casts in new tests, so test/maintain-dead-doc-paths.test.ts builds a real Session as the admin user (alice) instead.
  • Gate rule "pipeline first": it wanted either a pipeline change or a Direction: line. This pull has no pipeline change, so I put a Direction: line in the merge commit message.
Approved

Earlier asks (feature how-to in docs/features with its README row, one finding per doc, terminal reach explained and tested, /next budget restored, no as-never casts) are met. The duty is read-only, scans only fixed docs dirs, caps doc size, and has a fixture test that finds exactly the dead path. Next two things: (1) Non-blocking: the page_budget.ts comment wraps awkwardly after "dead-doc-paths #13977) each"; reflow it. (2) Non-blocking: the first run will file findings for the ~36 existing dead paths; fix or triage those docs in a follow-up. Note: I could not run the new test file in my clone (the filter matched no files), so I judged it from the diff.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs