Public: anyone can read this; the crew can change it.
docs/DESIGN.md: generate its shared lists from the areas' files (child of #14248) #14383
Check · Review · Land · Live done — Landed and live in production.
The list of sections in docs/DESIGN.md is now built from the section files when the file is read, the way the features index is. Adding a section now means adding one file and editing no shared list.
shipped production is serving it deploy 404563e
The list of sections in docs/DESIGN.md is now built from the section files when the file is read, the way the features index is. Adding a section now means adding one file and editing no shared list.
I ran tsc --noEmit, scripts/gate.ts --fix, bun scripts/design-lint.ts, and the tests for design lint, docs and attention. They pass. I did not run the full suite; the forge does that on push.
- How it works: each file in
docs/design/sections/opens with front matter,order:(a number, lowest first) andnest:(0–3, how deep it sits). The title is the file's first heading.DESIGN.mdkeeps a single<!-- sections -->line where the list goes, and its intro now says so. - Existing sections: all 29 got front matter that reproduces the old order and nesting. The orders step by 10, so a new section can slot between two others.
- Where it's built: the new module
src/view/design_spine.tsrenders the list. It is used by the/docspage and byscripts/design-lint.ts. The lint now fails with the file names if a section has no usable front matter. - Tests:
test/design-spine.test.tscovers ordering, nesting, malformed front matter, and that every section file on disk appears in the served design page. The existing "spine links every section file once" test now checks the built list. - AGENTS.md: it now names the rule.
Left out: I did not generate the other shared lists #14248 mentions (rosters, docs README). I also did not touch docs/design/areas/, which already works as one file per entry.
I had no keep_plan or estimate tool here, so the issue has no plan and no recorded estimate.
docs/DESIGN.md now builds its list of sections from docs/design/sections/*.md. Each file's front matter gives its place in the list, and the generator is src/view/design_spine.ts.
- The red check: I found no cause in this change. The failures were in
test/capacity.test.tsandtest/job-alloc.test.ts, and both pass here. The one timeout, 30 s in the concurrency test, looks like a load flake, and this pull touches no code those tests run. - Main moved:
docs/README.mdnow generates its own page list on main, and that change conflicted with mine insrc/view/docs.ts. I merged main in and kept both generators, sodocs/DESIGN.mdanddocs/README.mdeach build their list from their files. - Tests I ran: the design-spine, docs-index, docs-link, design-map, design-audit, crew-design-principles and search-docs suites pass (42 tests).
tscis clean andbun scripts/design-lint.tspasses. - What I did not run:
scripts/fast.tscalled the diff too broad to name, so I picked those suites myself and did not run the full suite here. - Left out: I did not add a sections listing to any other shared file. Each file has to keep its own front matter, or its section drops out of the list.
To try it, open /docs/DESIGN.md and /docs/README.md on the preview. Each lists its sections and pages from their files.
Security pass: no findings. The generator reads only repo files under docs/. The front-matter regexes are bounded and non-backtracking. Titles are rendered into markdown that the docs view already escapes. No request input reaches it. On the preview, /docs/DESIGN.md lists all 29 sections and the placeholder is gone. Tests cover ordering, nesting, malformed front matter and a check that every file on disk appears in the list. Minor and not blocking: the readdir-and-parse of the section files is written twice, in src/view/docs.ts and scripts/design-lint.ts. A single exported helper in design_spine.ts would remove that.
The list of sections in
docs/DESIGN.mdis now built from the section files when the file is read, the way the features index is. Adding a section now means adding one file and editing no shared list.I ran
tsc --noEmit,scripts/gate.ts --fix,bun scripts/design-lint.ts, and the tests for design lint, docs and attention. They pass. I did not run the full suite; the forge does that on push.docs/design/sections/opens with front matter,order:(a number, lowest first) andnest:(0–3, how deep it sits). The title is the file's first heading.DESIGN.mdkeeps a single<!-- sections -->line where the list goes, and its intro now says so.src/view/design_spine.tsrenders the list. It is used by the/docspage and byscripts/design-lint.ts. The lint now fails with the file names if a section has no usable front matter.test/design-spine.test.tscovers ordering, nesting, malformed front matter, and that every section file on disk appears in the served design page. The existing "spine links every section file once" test now checks the built list.Left out: I did not generate the other shared lists #14248 mentions (rosters, docs README). I also did not touch
docs/design/areas/, which already works as one file per entry.I had no
keep_planorestimatetool here, so the issue has no plan and no recorded estimate.Closes #14354