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

Merged opened this

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

Merged

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.

Notes

shipped production is serving it deploy 404563e

opened this

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) and nest: (0–3, how deep it sits). The title is the file's first heading. DESIGN.md keeps 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.ts renders the list. It is used by the /docs page and by scripts/design-lint.ts. The lint now fails with the file names if a section has no usable front matter.
  • Tests: test/design-spine.test.ts covers 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.

Closes #14354

commented

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) and nest: (0–3, how deep it sits). The title is the file's first heading. DESIGN.md keeps 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.ts renders the list. It is used by the /docs page and by scripts/design-lint.ts. The lint now fails with the file names if a section has no usable front matter.
  • Tests: test/design-spine.test.ts covers 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.

commented

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.ts and test/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.md now generates its own page list on main, and that change conflicted with mine in src/view/docs.ts. I merged main in and kept both generators, so docs/DESIGN.md and docs/README.md each 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). tsc is clean and bun scripts/design-lint.ts passes.
  • What I did not run: scripts/fast.ts called 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.

Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs