Public: anyone can read this; the crew can change it.
docs/design/map.md says what /map shows that boards and the dependency list do not, and what to cut #2777
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/2768-docs-design-map-md-says-what-map-shows-t → main 1 commit fork 1 thread · 1 unresolved
2 files
changed +69
−0
docs/design/map.md added +31
| @@ -0,0 +1,31 @@ | ||
| 1 | # What /map shows (#2768) | |
| 2 | ||
| 3 | Part of #2695. A reading of `src/web/pages/map.ts`, section by section: does a | |
| 4 | board or an issue's dependency list already show it, and keep or cut. This | |
| 5 | document changes no code; each **cut** is a follow-up issue, not done here. | |
| 6 | ||
| 7 | An issue's dependency list shows one issue's direct edges. A board shows | |
| 8 | work by state, per app, with a "merged by pillar" line. Neither draws the | |
| 9 | whole graph or follows a chain more than one hop. | |
| 10 | ||
| 11 | ## Per-app map (`/:owner/:name/map`) | |
| 12 | ||
| 13 | - `Map canvas` — every open issue laid out by what it waits for (`drawMap`, id `map-canvas`). Neither board nor dependency list draws the transitive graph. **Keep**: it is the page. | |
| 14 | - `Counts line` — the words (ready, waiting, working…) counted under the canvas (`countsLine`). Boards count by state, not by wait. **Keep**, it is one line. | |
| 15 | - `Autonomy line` — spend and autonomy under the heading (`autonomyLine`). Spend already has its own page and the board header. **Cut**. | |
| 16 | - `By pillar` — each pillar's issues by word, with the ask to live (`pillarList`). Boards show only what merged per pillar in 7 days; milestones show how far each umbrella is. Open work per pillar is shown nowhere else. **Keep**. | |
| 17 | - `Ready now` — open issues nothing stands in front of, with how many each frees (`rankedList`). The dependency list shows one issue's blockers, not the ready set; the board's queue is by claim, not by wait. **Keep**. | |
| 18 | - `Blocked on` — issues that hold others up, most first. Only the map ranks by what a blocker holds up. **Keep**. | |
| 19 | - `Critical path` — the longest chain still to do, shown again as a list and as the accent on the canvas. The canvas already draws it. **Cut** the list, keep the accent. | |
| 20 | - `Two weeks` — open issues as a line over closed per day as bars (`chart`). Boards show flow as panels and `/flow` shows the same level and rate; nothing about it is about waiting. **Cut** (it belongs with `/flow`, folded into boards by #2693). | |
| 21 | ||
| 22 | ## Global map (`/map`) | |
| 23 | ||
| 24 | - `Lanes` — one lane per app you can see, each a small map (`laneHtml`). A board lists work by state across apps, not by wait. **Keep**. | |
| 25 | - `Spend bar` — each lane's autonomy spend (`spendBar`). Shown on spend and usage. **Cut**. | |
| 26 | ||
| 27 | ## Cutting | |
| 28 | ||
| 29 | Cutting `Autonomy line`, `Critical path` list, `Two weeks` and `Spend bar` | |
| 30 | leaves the canvas, counts, pillars, ready and blocked: what only the graph | |
| 31 | can say. |
test/design-map.test.ts added +38
| @@ -0,0 +1,38 @@ | ||
| 1 | /** | |
| 2 | * docs/design/map.md names every section of the map page, and each one is | |
| 3 | * still in the page source (#2768). Each entry is a backticked name leading a | |
| 4 | * bullet; this maps it to the text the page carries for it. | |
| 5 | */ | |
| 6 | import { expect, test } from "bun:test"; | |
| 7 | import { readFileSync } from "node:fs"; | |
| 8 | ||
| 9 | const doc = readFileSync("docs/design/map.md", "utf8"); | |
| 10 | const src = readFileSync("src/web/pages/map.ts", "utf8"); | |
| 11 | ||
| 12 | const MARKERS: Record<string, string> = { | |
| 13 | "Map canvas": 'id: "map-canvas"', | |
| 14 | "Counts line": "function countsLine", | |
| 15 | "Autonomy line": "function autonomyLine", | |
| 16 | "By pillar": "<h2>By pillar</h2>", | |
| 17 | "Ready now": '"Ready now"', | |
| 18 | "Blocked on": '"Blocked on"', | |
| 19 | "Critical path": "<h2>Critical path</h2>", | |
| 20 | "Two weeks": "<h2>Two weeks</h2>", | |
| 21 | Lanes: "function laneHtml", | |
| 22 | "Spend bar": "function spendBar", | |
| 23 | }; | |
| 24 | ||
| 25 | const named = [...doc.matchAll(/^- `([^`]+)` —/gm)].map((m) => m[1]!); | |
| 26 | ||
| 27 | test("the doc names every section it knows, and no other", () => { | |
| 28 | expect(named.sort()).toEqual(Object.keys(MARKERS).sort()); | |
| 29 | }); | |
| 30 | ||
| 31 | test("every section the doc names is in the page source", () => { | |
| 32 | for (const name of named) expect(src).toContain(MARKERS[name]!); | |
| 33 | }); | |
| 34 | ||
| 35 | test("every section says keep or cut", () => { | |
| 36 | for (const line of doc.split("\n").filter((l) => /^- `/.test(l))) | |
| 37 | expect(line).toMatch(/\*\*(Keep|Cut)\*\*/); | |
| 38 | }); |
new above
offline
The marker check only proves the page source still contains the string. It does not prove the section renders. Fine for a doc guard; if a cut lands, update MARKERS and the doc together.