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.
scout/forge:scout/14354-docs-design-md-generate-its-shared-lists → main 2 commits fork 1 thread · 1 unresolved
36 files
changed +240
−39
AGENTS.md +1 −1
| @@ -2,7 +2,7 @@ | ||
| 2 | 2 | |
| 3 | 3 | Read `CLAUDE.md` first: it is the rulebook for agents editing this repo. |
| 4 | 4 | |
| 5 | Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`). | |
| 5 | Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`). The section list of `docs/DESIGN.md` is built the same way: a section file under `docs/design/sections/` opens with `order:` and `nest:` front matter and its first heading is its title (#14354, `test/design-spine.test.ts`). | |
| 6 | 6 | |
| 7 | 7 | README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section. |
| 8 | 8 | A pull that adds a page (`src/web/pages/*.ts`) also adds a terminal screen under `src/tui/screens/` that another module imports (its palette entry) and a `docs/features/<name>.md`, or a commit line `No door: <why>`; a new `src/web/render/*.ts`, `src/web/studio/*.ts` or `src/actions/*.ts` is asked for the screen alone, and a new feature module under `src/` in a pull that edits an existing page is asked for both, and a pull that edits an existing page (or any shared `src/web/` file, #13376: a new feature module wired into it is asked for both) changes something under `src/tui/` and a `docs/features/*.md` too (#13196); an edited API route, MCP tool or `src/actions/*.ts` changes something under `src/tui/` too (#14040); a new `src/http/api/*.ts` or `src/http/mcp/tools/*.ts` is asked for the screen, and a new module wired into `src/http/server.ts` for both (#14320); `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628). |
docs/DESIGN.md +7 −33
| @@ -56,39 +56,13 @@ has a name for, that is the bug. | ||
| 56 | 56 | Read this once. It is short on purpose. |
| 57 | 57 | |
| 58 | 58 | Each section is its own file under `docs/design/sections/`, so a change to one |
| 59 | never conflicts with a change to another. This page is the spine: it orders | |
| 60 | them, and the design check (`bun scripts/design-lint.ts`) reads them in this | |
| 61 | order — a section file not listed here is not part of the contract. A new | |
| 62 | component class is named in `docs/design/areas/<area>.md`, not here. | |
| 59 | never conflicts with a change to another. The list below is built from them when | |
| 60 | read (#14354), never typed: a section opens with front matter, `order:` (a | |
| 61 | number; sections run lowest first, so leave gaps) and `nest:` (how deep it | |
| 62 | sits in the list), and its title is its first heading. The design check | |
| 63 | (`bun scripts/design-lint.ts`) reads them in that order. A new component class | |
| 64 | is named in `docs/design/areas/<area>.md`, not here. | |
| 63 | 65 | |
| 64 | 66 | --- |
| 65 | 67 | |
| 66 | - [](design/sections/1-principles.md) | |
| 67 | - [](design/sections/2-tokens.md) | |
| 68 | - [](design/sections/3-typography.md) | |
| 69 | - [](design/sections/4-space-radius-motion.md) | |
| 70 | - [](design/sections/5-components.md) | |
| 71 | - [](design/sections/5a-reading-from.md) | |
| 72 | - [](design/sections/5b-workflow-units.md) | |
| 73 | - [](design/sections/5c-apps-runs-crew.md) | |
| 74 | - [](design/sections/5d-page-local-classes.md) | |
| 75 | - [](design/sections/6-keyboard.md) | |
| 76 | - [](design/sections/6a-code-browser.md) | |
| 77 | - [](design/sections/6b-code-coloured.md) | |
| 78 | - [](design/sections/6c-editor.md) | |
| 79 | - [](design/sections/6-0-pointer.md) | |
| 80 | - [](design/sections/6-0a-dashboard-panes.md) | |
| 81 | - [](design/sections/6-0a-1-terminal-layout.md) | |
| 82 | - [](design/sections/6-0b-icons-appearance.md) | |
| 83 | - [](design/sections/6-0c-terminal-pictures.md) | |
| 84 | - [](design/sections/6a-counts-and-marks.md) | |
| 85 | - [](design/sections/6b-workspace.md) | |
| 86 | - [](design/sections/6c-editing-commit-dialog.md) | |
| 87 | - [](design/sections/6c-1-contributing.md) | |
| 88 | - [](design/sections/6d-forge-editor.md) | |
| 89 | - [](design/sections/6e-links.md) | |
| 90 | - [](design/sections/6e-1-reviews-merge-gate.md) | |
| 91 | - [](design/sections/6f-realtime.md) | |
| 92 | - [](design/sections/6g-terminal-apps-runs-crew.md) | |
| 93 | - [](design/sections/7-security-boundaries.md) | |
| 94 | - [](design/sections/8-checklist.md) | |
| 68 | <!-- sections --> |
docs/design/sections/1-principles.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 10 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 1. Principles |
| 2 | 6 | |
| 3 | 7 | 1. **Border-first, not shadow-first.** Elevation in a light theme is a hairline |
docs/design/sections/2-tokens.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 20 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 2. Tokens |
| 2 | 6 | |
| 3 | 7 | Palettes live in `src/design/themes.ts`; the stylesheet only ever reads |
docs/design/sections/3-typography.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 30 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 3. Typography |
| 2 | 6 | |
| 3 | 7 |
docs/design/sections/4-space-radius-motion.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 40 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 4. Space, radius, motion |
| 2 | 6 | |
| 3 | 7 | - **4px grid.** Every padding, margin and gap is divisible by 4; 6px is allowed |
docs/design/sections/5-components.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 50 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 5. The component vocabulary |
| 2 | 6 | |
| 3 | 7 | Implemented in `src/web/ui.ts` (pure) and `src/web/chrome.ts` (may read the |
docs/design/sections/5a-reading-from.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 60 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 5a. Saying where you are reading from |
| 2 | 6 | |
| 3 | 7 | Every repository page in the product carries the **where strip**, and it says |
docs/design/sections/5b-workflow-units.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 70 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 5b. The workflow units |
| 2 | 6 | |
| 3 | 7 | A unit is a whole intention with one button behind it, not a sequence of |
docs/design/sections/5c-apps-runs-crew.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 80 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 5c. Apps, runs and the crew |
| 2 | 6 | |
| 3 | 7 | `docs/APPS.md` is the contract; these are its units on a page, and the same |
docs/design/sections/5d-page-local-classes.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 90 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 5d. Page-local classes |
| 2 | 6 | |
| 3 | 7 | The close form on an issue's thread is no class at all: its reason select and |
docs/design/sections/6-0-pointer.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 140 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6·0. The pointer |
| 2 | 6 | |
| 3 | 7 | The terminal UI is keyboard-first and mouse-**complete**: everything you can |
docs/design/sections/6-0a-1-terminal-layout.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 160 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6·0a·1. Laid out for the terminal it is in |
| 2 | 6 | |
| 3 | 7 | Three numbers in `ui/layout.ts` decide every screen's shape, so every screen |
docs/design/sections/6-0a-dashboard-panes.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 150 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6·0a. The dashboard's panes |
| 2 | 6 | |
| 3 | 7 | `Repositories`, `Recent activity`, `On you`, `On your machine`, |
docs/design/sections/6-0b-icons-appearance.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 170 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6·0b. Icons, and the appearance picker |
| 2 | 6 | |
| 3 | 7 | Two vocabularies. **`plain`** is the safe set (§6a) — BMP, width 1, in every |
docs/design/sections/6-0c-terminal-pictures.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 180 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6·0c. Pictures in the terminal |
| 2 | 6 | |
| 3 | 7 | A tab whose path looks like an image and whose bytes git returned as binary is |
docs/design/sections/6-keyboard.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 100 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 6. Keyboard |
| 2 | 6 | |
| 3 | 7 | Driven entirely from the DOM: `data-shortcut="g i"` on a link, `data-nav` on a |
docs/design/sections/6a-code-browser.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 110 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6a. The code browser |
| 2 | 6 | |
| 3 | 7 | Tree and blob pages are one layout, not two: a `.code-layout` grid with the |
docs/design/sections/6a-counts-and-marks.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 190 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6a. Counts and marks on a row |
| 2 | 6 | |
| 3 | 7 | Three glyphs carry the at-a-glance numbers, all of them BMP, all width 1, all |
docs/design/sections/6b-code-coloured.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 120 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6b. Code, coloured |
| 2 | 6 | |
| 3 | 7 | One tokenizer, `src/web/highlight.ts`, serves the file browser, the diff |
docs/design/sections/6b-workspace.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 200 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6b. The workspace — one screen for a whole repository |
| 2 | 6 | |
| 3 | 7 | Opening a repository in the terminal opens a **workspace**, not a home page: |
docs/design/sections/6c-1-contributing.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 220 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6c·1. Contributing: fork at the origin, propose a change |
| 2 | 6 | |
| 3 | 7 | The workflow the origins layer exists for — _grab their repo, branch, edit, |
docs/design/sections/6c-editing-commit-dialog.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 210 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6c. Editing, and the commit dialog |
| 2 | 6 | |
| 3 | 7 | `e` turns the active tab into a modeless editor: arrows/Home/End/PgUp/PgDn and |
docs/design/sections/6c-editor.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 130 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6c. The editor |
| 2 | 6 | |
| 3 | 7 | `GET /:owner/:name/edit/:ref/*path` is a `<textarea>` in a `<form>`, and one |
docs/design/sections/6d-forge-editor.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 230 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6d. `$FORGE_EDITOR` — the operator's own editor, over a pty |
| 2 | 6 | |
| 3 | 7 | `E` suspends the UI and hands the terminal to `$FORGE_EDITOR` on a real pty. |
docs/design/sections/6e-1-reviews-merge-gate.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 250 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6e·1. Reviews, threads, and the merge gate |
| 2 | 6 | |
| 3 | 7 | A pull is judged in three places, and each says one thing. |
docs/design/sections/6e-links.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 240 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6e. Links that work |
| 2 | 6 | |
| 3 | 7 | The cell buffer has a sixth plane, `link`, holding a 1-based index into the |
docs/design/sections/6f-realtime.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 260 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6f. Realtime |
| 2 | 6 | |
| 3 | 7 | Dashboard, issue and pull lists, the repo home, and the issue and pull screens |
docs/design/sections/6g-terminal-apps-runs-crew.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 270 | |
| 3 | nest: 1 | |
| 4 | --- | |
| 1 | 5 | ### 6g. Apps, runs and the crew, where the terminal still shows them |
| 2 | 6 | |
| 3 | 7 | The terminal's half of §5c is deliberately small: running an app and |
docs/design/sections/7-security-boundaries.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 280 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 7. Two rules that are security boundaries |
| 2 | 6 | |
| 3 | 7 | **Label colors.** Inline `style=""` is blocked by the CSP — nonces apply to |
docs/design/sections/8-checklist.md +4
| @@ -1,3 +1,7 @@ | ||
| 1 | --- | |
| 2 | order: 290 | |
| 3 | nest: 0 | |
| 4 | --- | |
| 1 | 5 | ## 8. Checklist before you call a screen done |
| 2 | 6 | |
| 3 | 7 | 1. Every divider is exactly 1px. The only 2px things are the active-tab |
scripts/design-lint.ts +12 −2
| @@ -67,6 +67,7 @@ | ||
| 67 | 67 | |
| 68 | 68 | import { readdirSync, readFileSync, writeFileSync } from "node:fs"; |
| 69 | 69 | import { join, relative } from "node:path"; |
| 70 | import { parseSection, renderSpine, stripSection } from "../src/view/design_spine.ts"; | |
| 70 | 71 | import { dictateFindings } from "../src/design/dictate.ts"; |
| 71 | 72 | import { STRANGER_NEVER_SEES } from "../src/design/first_five_minutes.ts"; |
| 72 | 73 | import { contrastFindings } from "../src/design/contrast.ts"; |
| @@ -249,10 +250,19 @@ export function sectionLinks(spine: string): string[] { | ||
| 249 | 250 | return [...spine.matchAll(/\]\(design\/sections\/([a-z0-9-]+\.md)\)/g)].map((m) => m[1]!); |
| 250 | 251 | } |
| 251 | 252 | |
| 253 | /** The spine: DESIGN.md with its list of sections built from the section files (#14354). */ | |
| 254 | export function designSpine(root: string): string { | |
| 255 | const dir = join(root, SECTIONS); | |
| 256 | const sections = readdirSync(dir).filter((n) => n.endsWith(".md")).map((n) => ({ name: n, meta: parseSection(readFileSync(join(dir, n), "utf8")) })); | |
| 257 | const bad = sections.filter((s) => s.meta === undefined).map((s) => s.name); | |
| 258 | if (bad.length) throw new Error(`no usable front matter (order, a heading) in docs/design/sections: ${bad.join(", ")}`); | |
| 259 | return renderSpine(readFileSync(join(root, DESIGN), "utf8"), sections); | |
| 260 | } | |
| 261 | ||
| 252 | 262 | /** DESIGN.md as one text: the spine, then each section it links, in order (#5937). */ |
| 253 | 263 | export function designText(root: string): string { |
| 254 | const spine = readFileSync(join(root, DESIGN), "utf8"); | |
| 255 | return [spine, ...sectionLinks(spine).map((f) => readFileSync(join(root, SECTIONS, f), "utf8"))].join("\n"); | |
| 264 | const spine = designSpine(root); | |
| 265 | return [spine, ...sectionLinks(spine).map((f) => stripSection(readFileSync(join(root, SECTIONS, f), "utf8")))].join("\n"); | |
| 256 | 266 | } |
| 257 | 267 | |
| 258 | 268 | /** |
src/view/design_spine.ts added +62
| @@ -0,0 +1,62 @@ | ||
| 1 | /** | |
| 2 | * The list of sections in `docs/DESIGN.md` is built from the section files, never typed (#14354, | |
| 3 | * the way of the features index, #14248). A section file opens with front matter: | |
| 4 | * | |
| 5 | * --- | |
| 6 | * order: 140 (sections run lowest first; leave gaps so a new one fits between) | |
| 7 | * nest: 1 (optional: how deep it sits in the list, 0 by default) | |
| 8 | * --- | |
| 9 | * | |
| 10 | * and its title is its first `#` heading. DESIGN.md keeps one `<!-- sections -->` line where the | |
| 11 | * list goes. A pull that adds a section adds that one file and edits no shared list. Plain data in, | |
| 12 | * plain data out. | |
| 13 | */ | |
| 14 | ||
| 15 | export interface SectionMeta { | |
| 16 | readonly order: number; | |
| 17 | readonly nest: number; | |
| 18 | readonly title: string; | |
| 19 | } | |
| 20 | ||
| 21 | export interface Section { | |
| 22 | readonly name: string; | |
| 23 | readonly meta: SectionMeta | undefined; | |
| 24 | } | |
| 25 | ||
| 26 | const FRONT = /^---\n([\s\S]*?)\n---\n/; | |
| 27 | ||
| 28 | /** The text of a section without its front matter. */ | |
| 29 | export function stripSection(text: string): string { | |
| 30 | return text.replace(FRONT, ""); | |
| 31 | } | |
| 32 | ||
| 33 | /** The front matter and title of a section, or undefined when `order` or the heading is missing. */ | |
| 34 | export function parseSection(text: string): SectionMeta | undefined { | |
| 35 | const m = FRONT.exec(text); | |
| 36 | if (m === null) return undefined; | |
| 37 | const f = new Map<string, string>(); | |
| 38 | for (const line of (m[1] ?? "").split("\n")) { | |
| 39 | const at = line.indexOf(": "); | |
| 40 | if (at > 0) f.set(line.slice(0, at).trim(), line.slice(at + 2).trim()); | |
| 41 | } | |
| 42 | const o = f.get("order"); | |
| 43 | if (o === undefined || !/^\d{1,6}$/.test(o)) return undefined; | |
| 44 | const n = f.get("nest"); | |
| 45 | const nest = n !== undefined && /^[0-3]$/.test(n) ? Number(n) : 0; | |
| 46 | const h = /^#{1,6} (.+)$/m.exec(text.slice(m[0].length)); | |
| 47 | if (h === null) return undefined; | |
| 48 | return { order: Number(o), nest, title: (h[1] as string).trim() }; | |
| 49 | } | |
| 50 | ||
| 51 | /** The head with the list of sections put where its `<!-- sections -->` line is. */ | |
| 52 | export function renderSpine(head: string, sections: readonly Section[]): string { | |
| 53 | const list = sections | |
| 54 | .flatMap((s) => (s.meta === undefined ? [] : [{ s, m: s.meta }])) | |
| 55 | .sort((a, b) => a.m.order - b.m.order || a.s.name.localeCompare(b.s.name)) | |
| 56 | .map(({ s, m }) => `${" ".repeat(m.nest)}- [${m.title}](design/sections/${s.name})`) | |
| 57 | .join("\n"); | |
| 58 | return head | |
| 59 | .split("\n") | |
| 60 | .map((l) => (l.trim() === "<!-- sections -->" ? list : l)) | |
| 61 | .join("\n"); | |
| 62 | } |
src/view/docs.ts +6 −1
| @@ -7,6 +7,7 @@ | ||
| 7 | 7 | * for the life of the process. |
| 8 | 8 | */ |
| 9 | 9 | |
| 10 | import { parseSection, renderSpine } from "./design_spine.ts"; | |
| 10 | 11 | import { parseFront, renderFeatureIndex, stripFront } from "./feature_index.ts"; |
| 11 | 12 | import { docsPages, renderDocsIndex } from "./docs_index.ts"; |
| 12 | 13 | import { readdirSync, readFileSync } from "node:fs"; |
| @@ -51,10 +52,14 @@ export function docText(entry: DocEntry, ssh = false): string { | ||
| 51 | 52 | |
| 52 | 53 | /** |
| 53 | 54 | * A document as read: a note without its front matter, the features index built from the notes |
| 54 | * (#14248). | |
| 55 | * (#14248), the design file's list of sections from the section files (#14354). | |
| 55 | 56 | */ |
| 56 | 57 | function readDoc(name: string): string { |
| 57 | 58 | const text = readFileSync(join(DOCS, name), "utf8"); |
| 59 | if (name === "DESIGN.md") { | |
| 60 | const dir = join(DOCS, "design", "sections"); | |
| 61 | return renderSpine(text, readdirSync(dir).filter((n) => n.endsWith(".md")).map((n) => ({ name: n, meta: parseSection(readFileSync(join(dir, n), "utf8")) }))); | |
| 62 | } | |
| 58 | 63 | if (name === "README.md") return renderDocsIndex(text, docsPages(DOCS)); |
| 59 | 64 | if (name !== "features/README.md") return stripFront(text); |
| 60 | 65 | const notes = readdirSync(join(DOCS, "features")) |
test/design-lint.test.ts +2 −2
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | import { describe, expect, test } from "bun:test"; |
| 2 | 2 | import { readdirSync, readFileSync } from "node:fs"; |
| 3 | import { areaFiles, compareLayout, layoutCounts, layoutIn, scanLayout, classesIn, compare, compareQuiet, quiet, scanQuiet, scanCards, scanStranger, strangerWords, STRANGER_FILES, countFile, designText, documentedClasses, locate, loneSentenceCards, registeredClasses, overlay, overlayClassesIn, scanOverlay, scan, sectionLinks, webCss } from "../scripts/design-lint.ts"; | |
| 3 | import { areaFiles, compareLayout, layoutCounts, layoutIn, scanLayout, classesIn, compare, compareQuiet, quiet, scanQuiet, scanCards, scanStranger, strangerWords, STRANGER_FILES, countFile, designText, designSpine, documentedClasses, locate, loneSentenceCards, registeredClasses, overlay, overlayClassesIn, scanOverlay, scan, sectionLinks, webCss } from "../scripts/design-lint.ts"; | |
| 4 | 4 | |
| 5 | 5 | /** A DESIGN.md in miniature: the §5 table, a §5d register, and a §6 that names a class too. */ |
| 6 | 6 | const DESIGN = [ |
| @@ -173,7 +173,7 @@ describe("docs/DESIGN.md", () => { | ||
| 173 | 173 | }); |
| 174 | 174 | |
| 175 | 175 | test("the spine links every section file once, and each link is a file (#5937)", () => { |
| 176 | const linked = sectionLinks(readFileSync("docs/DESIGN.md", "utf8")); | |
| 176 | const linked = sectionLinks(designSpine(".")); | |
| 177 | 177 | expect(new Set(linked).size).toBe(linked.length); |
| 178 | 178 | expect([...linked].sort()).toEqual(readdirSync("docs/design/sections").filter((n) => n.endsWith(".md")).sort()); |
| 179 | 179 | }); |
test/design-spine.test.ts added +34
| @@ -0,0 +1,34 @@ | ||
| 1 | /** The design file's list of sections is built from the section files (#14354). */ | |
| 2 | import { expect, test } from "bun:test"; | |
| 3 | import { readdirSync, readFileSync } from "node:fs"; | |
| 4 | import { parseSection, renderSpine, stripSection } from "../src/view/design_spine.ts"; | |
| 5 | import { docEntry, docText } from "../src/view/docs.ts"; | |
| 6 | ||
| 7 | const sec = (order: number, nest: number, title: string) => `---\norder: ${order}\nnest: ${nest}\n---\n## ${title}\n`; | |
| 8 | ||
| 9 | test("sections run by order, nested by nest, titled by their heading", () => { | |
| 10 | const out = renderSpine("a\n<!-- sections -->\nb", [ | |
| 11 | { name: "b.md", meta: parseSection(sec(20, 1, "Two")) }, | |
| 12 | { name: "a.md", meta: parseSection(sec(10, 0, "One")) }, | |
| 13 | ]); | |
| 14 | expect(out).toBe("a\n- [One](design/sections/a.md)\n - [Two](design/sections/b.md)\nb"); | |
| 15 | }); | |
| 16 | ||
| 17 | test("front matter without an order or a heading is no section", () => { | |
| 18 | expect(parseSection("## T\n")).toBeUndefined(); | |
| 19 | expect(parseSection("---\norder: x\n---\n## T\n")).toBeUndefined(); | |
| 20 | expect(parseSection("---\norder: 1\n---\nno heading\n")).toBeUndefined(); | |
| 21 | expect(stripSection(sec(1, 0, "T"))).toBe("## T\n"); | |
| 22 | }); | |
| 23 | ||
| 24 | test("every section file in the repository is usable, so the list lacks none", () => { | |
| 25 | const dir = "docs/design/sections"; | |
| 26 | const names = readdirSync(dir).filter((n) => n.endsWith(".md")); | |
| 27 | expect(names.length).toBeGreaterThan(0); | |
| 28 | for (const n of names) expect(parseSection(readFileSync(`${dir}/${n}`, "utf8"))).toBeDefined(); | |
| 29 | const e = docEntry("DESIGN.md"); | |
| 30 | expect(e).toBeDefined(); | |
| 31 | const text = docText(e!); | |
| 32 | for (const n of names) expect(text).toContain(`(design/sections/${n})`); | |
| 33 | expect(text).not.toContain("<!-- sections -->"); | |
| 34 | }); |
new above
offline
Non-blocking: this duplicates the readdir-and-parse in designSpine() in scripts/design-lint.ts. Move one loader into design_spine.ts and call it from both.