Public: anyone can read this; the crew can change it.
A repository's map draws what is open and counts what is done: trevato/forge's /map under 400 KB and 300 ms #6132
scout/forge:scout/6121-a-repository-s-map-draws-what-is-open-an → main 5 commits fork 3 threads · 3 unresolved
9 files
changed +154
−36
README.md +3 −3
| @@ -1735,9 +1735,9 @@ read leaves the card as it was. | ||
| 1735 | 1735 | Two of them carry a figure beside the words: |
| 1736 | 1736 | |
| 1737 | 1737 | - **Map** — `/og/map/owner~name.svg`: the repository's dependency graph as a |
| 1738 | thumbnail, laid out exactly as `/owner/name/map` lays it out (ready green, | |
| 1739 | working solid accent, blocked grey, waiting/held purple, parked amber, | |
| 1740 | deferred and done faint), the critical path in the accent; beside it the | |
| 1738 | thumbnail, laid out as `/owner/name/map` lays it out by default, open issues | |
| 1739 | only (ready green, working solid accent, blocked grey, waiting/held purple, | |
| 1740 | parked amber, deferred faint); done is counted in the foot, not drawn, the critical path in the accent; beside it the | |
| 1741 | 1741 | open count, the critical path's length and ends, and the next issue a free |
| 1742 | 1742 | hand would take; along the foot `ready · working · blocked · waiting · done`. |
| 1743 | 1743 | Drawn from what a signed-out reader sees: no sealed issue, no run on one. |
docs/PLANNING.md +3 −2
| @@ -31,8 +31,9 @@ change, so hooks and the crew see it. | ||
| 31 | 31 | |
| 32 | 32 | ## The map |
| 33 | 33 | |
| 34 | `/:owner/:name/map` draws the repository's open issues, and any closed one | |
| 35 | still on an edge, laid out by what waits for what. Each issue is a card one | |
| 34 | `/:owner/:name/map` draws the repository's open issues by default, laid out by | |
| 35 | what waits for what; the `done N` badge, or `?done=1`, also draws the closed | |
| 36 | ones still on an edge (the badge links back to the open-only view). Each issue is a card one | |
| 36 | 37 | level below everything it is blocked by, so the top edge is what is ready |
| 37 | 38 | now. Within a level, cards are ordered to keep the curves short and |
| 38 | 39 | uncrossed: a barycenter pass sorts each level by where its blockers sit, |
docs/design/areas/map.md +1
| @@ -24,3 +24,4 @@ is `data-state` on `.map-node`, not a class. | ||
| 24 | 24 | - `.map-edge-crit` — an edge on the critical path, in the accent. |
| 25 | 25 | - `.map-edge-done` — an edge with a closed issue at either end, faded. |
| 26 | 26 | - `.map-ask` — a pillar row's lead-time figures in the side column, inline, with the hover title saying what they measure. |
| 27 | - `.map-done-link` — the link beside the counts line that shows the closed issues ("Show done") or goes back to open only; 40px tall, 44px under a coarse pointer. |
src/web/og/map.ts +2 −7
| @@ -9,7 +9,7 @@ | ||
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | 11 | import { criticalPath, readyNow, type Graph } from "../../core/dependencies.ts"; |
| 12 | import { countWords, layout, wordFor, type Marks, type Word } from "../pages/map.ts"; | |
| 12 | import { countWords, layout, openOnly, wordFor, type Marks, type Word } from "../pages/map.ts"; | |
| 13 | 13 | import { cachedLayout } from "../map_cache.ts"; |
| 14 | 14 | import type { CardInput } from "./card.ts"; |
| 15 | 15 | import type { GraphEdge, GraphFigure, GraphNode } from "./graph.ts"; |
| @@ -110,13 +110,8 @@ export function mapInput(title: string, graph: Graph, marks: Marks): CardInput { | ||
| 110 | 110 | const words = new Map(graph.issues.map((i) => [i.id, wordFor(i, readySet, marks)])); |
| 111 | 111 | const open = graph.issues.filter((i) => i.state === "open").length; |
| 112 | 112 | // The thumbnail draws what is open: done issues are counted in the caption, not drawn. |
| 113 | const live = new Set(graph.issues.filter((i) => i.state === "open").map((i) => i.id)); | |
| 114 | 113 | const figure = graphFigure( |
| 115 | { | |
| 116 | ...graph, | |
| 117 | issues: graph.issues.filter((i) => live.has(i.id)), | |
| 118 | edges: graph.edges.filter((e) => live.has(e.issueId) && live.has(e.blockedById)), | |
| 119 | }, | |
| 114 | openOnly(graph), | |
| 120 | 115 | words, |
| 121 | 116 | path.map((i) => i.id), |
| 122 | 117 | ); |
src/web/pages/map.ts +46 −20
| @@ -930,6 +930,23 @@ export function countWords(words: readonly Word[]): Record<Word, number> { | ||
| 930 | 930 | return out; |
| 931 | 931 | } |
| 932 | 932 | |
| 933 | /** | |
| 934 | * The graph as the map draws it by default: open issues and the edges | |
| 935 | * between them. Closed work is one count (`?done=1` draws it), so the page | |
| 936 | * is as long as the work still to do. Readiness is judged on the whole graph | |
| 937 | * before this, so a closed blocker still frees what it held. | |
| 938 | */ | |
| 939 | export function openOnly(graph: Graph): Graph { | |
| 940 | const open = new Set<string>(); | |
| 941 | for (const i of graph.issues) if (i.state === "open") open.add(i.id); | |
| 942 | if (open.size === graph.issues.length) return graph; | |
| 943 | return { | |
| 944 | ...graph, | |
| 945 | issues: graph.issues.filter((i) => open.has(i.id)), | |
| 946 | edges: graph.edges.filter((e) => open.has(e.issueId) && open.has(e.blockedById)), | |
| 947 | }; | |
| 948 | } | |
| 949 | ||
| 933 | 950 | function countsLine(counts: Record<Word, number>): Html { |
| 934 | 951 | const always = new Set<Word>(["ready", "working", "blocked", "done"]); |
| 935 | 952 | const tone: Partial<Record<Word, string>> = { |
| @@ -1111,6 +1128,8 @@ export const mapCss = /* css */ ` | ||
| 1111 | 1128 | .map-wrap { display: grid; grid-template-columns: minmax(0, 1fr) 272px; gap: 24px; align-items: start; margin-top: 4px; } |
| 1112 | 1129 | @media (max-width: 860px) { .map-wrap { grid-template-columns: 1fr; } } |
| 1113 | 1130 | .map-main { min-width: 0; } |
| 1131 | .map-done-link { display: inline-flex; align-items: center; min-height: 40px; padding: 0 8px; margin-left: 4px; } | |
| 1132 | @media (pointer: coarse) { .map-done-link { min-height: 44px; } } | |
| 1114 | 1133 | |
| 1115 | 1134 | /* ---- the canvas ---- */ |
| 1116 | 1135 | .map-canvas { position: relative; overflow: hidden; border: 1px solid var(--border); border-radius: var(--radius); background: var(--bg); touch-action: pan-y; user-select: none; -webkit-user-select: none; } |
| @@ -1356,25 +1375,26 @@ export async function mapPage(ctx: Ctx): Promise<Response> { | ||
| 1356 | 1375 | if (!repo) return notFoundPage(ctx); |
| 1357 | 1376 | const db = ctx.app.db; |
| 1358 | 1377 | const studio = studioRecord(ctx, repo) !== undefined; |
| 1359 | // The read: graph, marks and pillars, one phase; `render` is the page's own. | |
| 1360 | const { graph, ready, blocked, critical, placed, marks, readySet, counts, pillars, ask } = | |
| 1361 | timePhase(ctx.request, "map", () => { | |
| 1362 | const graph = repoGraph(db, repo.id, { | |
| 1363 | ...sealedScope(db, repo, ctx.auth.user), | |
| 1364 | }); | |
| 1365 | const ready = readyNow(graph); | |
| 1366 | const blocked = blockedOn(graph); | |
| 1367 | const critical = criticalPath(graph); | |
| 1368 | const placed = cachedLayout(graph, layout); | |
| 1369 | const marks = marksFor(db, repo.id, graph, listActiveRuns(db, [repo.id])); | |
| 1370 | const readySet = new Set(ready.map((r) => r.issue.id)); | |
| 1371 | const counts = countWords( | |
| 1372 | graph.issues.map((i) => wordFor(i, readySet, marks)), | |
| 1373 | ); | |
| 1374 | const pillars = pillarView(db, repo); | |
| 1375 | const ask = askToLiveFor(ctx.app, repo, pillars, ctx.auth.user); | |
| 1376 | return { graph, ready, blocked, critical, placed, marks, readySet, counts, pillars, ask }; | |
| 1378 | const withDone = new URL(ctx.request.url).searchParams.get("done") === "1"; | |
| 1379 | // The read, in four named phases; `render` is the page's own. | |
| 1380 | const { graph, ready, blocked, critical } = timePhase(ctx.request, "graph", () => { | |
| 1381 | const graph = repoGraph(db, repo.id, { | |
| 1382 | ...sealedScope(db, repo, ctx.auth.user), | |
| 1377 | 1383 | }); |
| 1384 | return { graph, ready: readyNow(graph), blocked: blockedOn(graph), critical: criticalPath(graph) }; | |
| 1385 | }); | |
| 1386 | const drawn = withDone ? graph : openOnly(graph); | |
| 1387 | const placed = timePhase(ctx.request, "layout", () => cachedLayout(drawn, layout)); | |
| 1388 | const { marks, readySet, counts } = timePhase(ctx.request, "marks", () => { | |
| 1389 | const marks = marksFor(db, repo.id, graph, listActiveRuns(db, [repo.id])); | |
| 1390 | const readySet = new Set(ready.map((r) => r.issue.id)); | |
| 1391 | const counts = countWords(graph.issues.map((i) => wordFor(i, readySet, marks))); | |
| 1392 | return { marks, readySet, counts }; | |
| 1393 | }); | |
| 1394 | const { pillars, ask } = timePhase(ctx.request, "pillars", () => { | |
| 1395 | const pillars = pillarView(db, repo); | |
| 1396 | return { pillars, ask: askToLiveFor(ctx.app, repo, pillars, ctx.auth.user) }; | |
| 1397 | }); | |
| 1378 | 1398 | const rendering = performance.now(); |
| 1379 | 1399 | const body = html`${repoHeader(ctx, repo, "map")} |
| 1380 | 1400 | <div class="page-head mt"> |
| @@ -1392,13 +1412,19 @@ export async function mapPage(ctx: Ctx): Promise<Response> { | ||
| 1392 | 1412 | data-live-repo="${repo.ownerName}/${repo.name}" |
| 1393 | 1413 | > |
| 1394 | 1414 | <div class="map-main"> |
| 1395 | ${drawMap(repo, graph, placed, emphasisFor(ready, critical, marks), { | |
| 1415 | ${drawMap(repo, drawn, placed, emphasisFor(ready, critical, marks), { | |
| 1396 | 1416 | id: "map-canvas", |
| 1397 | 1417 | cap: 1, |
| 1398 | 1418 | issueHref: tellHref, |
| 1399 | 1419 | ...(studio ? { empty: studioEmpty(repoBase(repo)) } : {}), |
| 1400 | 1420 | })} |
| 1401 | ${placed.nodes.length === 0 ? null : countsLine(counts)} | |
| 1421 | ${placed.nodes.length === 0 && counts.done === 0 | |
| 1422 | ? null | |
| 1423 | : html`${countsLine(counts)}${counts.done === 0 | |
outdated
Optional: with |
||
| 1424 | ? null | |
| 1425 | : html`<a class="map-done-link" href="${repoBase(repo)}/map${withDone ? "" : "?done=1"}" | |
| 1426 | >${withDone ? "Open only" : "Show done"}</a | |
| 1427 | >`}`} | |
| 1402 | 1428 | </div> |
| 1403 | 1429 | <aside class="stack"> |
| 1404 | 1430 | ${pillars === undefined |
test/map-page-timing.test.ts +1 −1
| @@ -52,6 +52,6 @@ test("GET /:owner/:name/map names its phases", async () => { | ||
| 52 | 52 | expect(res.status).toBe(200); |
| 53 | 53 | expect(body).toContain("<h1>Map</h1>"); |
| 54 | 54 | const parts = (res.headers.get("server-timing") ?? "").split(", "); |
| 55 | for (const name of ["app", "session", "map", "render"]) | |
| 55 | for (const name of ["app", "session", "graph", "layout", "marks", "pillars", "render"]) | |
| 56 | 56 | expect(parts.find((p) => p.startsWith(`${name};`))).toMatch(/^[a-z]+;dur=\d+\.\d$/); |
| 57 | 57 | }); |
test/map-page.test.ts added +94
| @@ -0,0 +1,94 @@ | ||
| 1 | /** `/:owner/:name/map` draws what is open and counts what is done (#6121). */ | |
| 2 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 3 | import { mkdtempSync, rmSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { createRepo } from "../src/actions/repos.ts"; | |
| 7 | import { createApp, type App } from "../src/app.ts"; | |
| 8 | import { createIssue } from "../src/core/issues.ts"; | |
| 9 | import { createUser } from "../src/core/users.ts"; | |
| 10 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 11 | import { proveAll } from "./helpers/verified.ts"; | |
| 12 | import { quietLogs } from "./helpers/globals.ts"; | |
| 13 | ||
| 14 | quietLogs(); | |
| 15 | ||
| 16 | const CLOSED = 2000; | |
| 17 | const OPEN = 300; | |
| 18 | let root = ""; | |
| 19 | let app: App; | |
| 20 | let servers: Servers; | |
| 21 | let cookie = ""; | |
| 22 | ||
| 23 | beforeAll(async () => { | |
| 24 | root = mkdtempSync(join(tmpdir(), "forge-map-page-")); | |
| 25 | app = createApp({ dataDir: root, port: 0, forgeRepo: "alice/forge" }); | |
| 26 | const u = await createUser(app.db, { | |
| 27 | origin: "seed", | |
| 28 | trusted: true, | |
| 29 | username: "alice", | |
| 30 | email: "[email protected]", | |
| 31 | password: "a-good-passphrase", | |
| 32 | adminIfFirst: true, | |
| 33 | }); | |
| 34 | if (!u.ok) throw new Error(u.error); | |
| 35 | proveAll(app); | |
| 36 | const made = await createRepo(app, { id: u.value.id, username: "alice" } as never, { name: "forge" }); | |
| 37 | if (!made.ok) throw new Error(made.error); | |
| 38 | const repoId = made.value.id; | |
| 39 | const make = (title: string) => { | |
| 40 | const r = createIssue(app.db, { repoId, authorId: u.value.id, title }); | |
| 41 | if (!r.ok) throw new Error(r.error); | |
| 42 | return r.value.id; | |
| 43 | }; | |
| 44 | const closed = Array.from({ length: CLOSED }, (_, n) => make(`Finished work ${n}`)); | |
| 45 | const open = Array.from({ length: OPEN }, (_, n) => make(`Open work ${n}`)); | |
| 46 | app.db.transaction(() => { | |
| 47 | for (const id of closed) | |
| 48 | app.db.query("UPDATE issue SET state = 'closed', close_reason = 'done' WHERE id = ?1").run(id); | |
| 49 | // Every closed issue once held an open one up, so it is in the graph. | |
| 50 | closed.forEach((id, n) => | |
| 51 | app.db | |
| 52 | .query("INSERT INTO issue_dependency (issue_id, blocked_by_id) VALUES (?1, ?2)") | |
| 53 | .run(open[n % OPEN]!, id), | |
| 54 | ); | |
| 55 | })(); | |
| 56 | servers = await serve(app); | |
| 57 | const signin = await fetch(`${servers.url}/signin`, { | |
| 58 | method: "POST", | |
| 59 | headers: { origin: servers.url }, | |
| 60 | body: new URLSearchParams({ username: "alice", password: "a-good-passphrase" }), | |
| 61 | redirect: "manual", | |
| 62 | }); | |
| 63 | cookie = (signin.headers.get("set-cookie") ?? "").split(";")[0]!; | |
| 64 | }); | |
| 65 | afterAll(() => { | |
| 66 | servers.stop(); | |
| 67 | app.close(); | |
| 68 | rmSync(root, { recursive: true, force: true }); | |
| 69 | }); | |
| 70 | ||
| 71 | const get = (path: string) => fetch(`${servers.url}${path}`, { headers: { cookie } }); | |
| 72 | const nodes = (body: string, state: string) => | |
| 73 | (body.match(new RegExp(`class="map-node"\\s+data-state="${state}"`, "g")) ?? []).length; | |
| 74 | ||
| 75 | test("by default only open issues are drawn, and done is one count that links to ?done=1", async () => { | |
| 76 | const res = await get("/alice/forge/map"); | |
| 77 | const body = await res.text(); | |
| 78 | expect(res.status).toBe(200); | |
| 79 | expect(body).not.toContain("Finished work"); | |
| 80 | expect(body).toContain("Open work 0"); | |
| 81 | expect(nodes(body, "done")).toBe(0); | |
| 82 | expect(body).toContain(`done <b>${CLOSED}</b></span>`); | |
| 83 | expect(body).toMatch(/class="map-done-link" href="\/alice\/forge\/map\?done=1"\s*>Show done/); | |
| 84 | expect(new TextEncoder().encode(body).length).toBeLessThan(400_000); | |
| 85 | const timing = res.headers.get("server-timing") ?? ""; | |
| 86 | for (const name of ["graph", "layout", "marks", "pillars"]) expect(timing).toContain(`${name};dur=`); | |
| 87 | }); | |
| 88 | ||
| 89 | test("?done=1 draws the closed issues too", async () => { | |
| 90 | const body = await (await get("/alice/forge/map?done=1")).text(); | |
| 91 | expect(body).toContain("Finished work 0"); | |
| 92 | expect(nodes(body, "done")).toBe(CLOSED); | |
| 93 | expect(body).toMatch(/class="map-done-link" href="\/alice\/forge\/map"\s*>Open only/); | |
| 94 | }); |
test/map.test.ts +2 −2
| @@ -334,7 +334,7 @@ describe("the map, per app and across the forge", () => { | ||
| 334 | 334 | test("a card says its word, who is on it, and wears a ring while the crew works", async () => { |
| 335 | 335 | const cookie = await signIn("alice"); |
| 336 | 336 | const page = await ( |
| 337 | await fetch(`${base}/alice/engine/map`, { headers: { cookie } }) | |
| 337 | await fetch(`${base}/alice/engine/map?done=1`, { headers: { cookie } }) | |
| 338 | 338 | ).text(); |
| 339 | 339 | const card = (title: string) => |
| 340 | 340 | page.match( |
| @@ -369,7 +369,7 @@ describe("the map, per app and across the forge", () => { | ||
| 369 | 369 | /data-state="blocked"[^>]*>blocked <b>1<\/b><\/span>/, |
| 370 | 370 | ); |
| 371 | 371 | expect(page).toMatch( |
| 372 | /data-state="done"[^>]*>done <b>1<\/b><\/span>/, | |
| 372 | /data-state="done"[^>]*>done <b>1<\/b><\/(span|a)>/, | |
| 373 | 373 | ); |
| 374 | 374 | expect(page).toMatch( |
| 375 | 375 | /data-state="waiting"[^>]*>waiting <b>1<\/b><\/span>/, |
test/og-designs.test.ts +2 −1
| @@ -93,7 +93,8 @@ describe("the map's thumbnail", () => { | ||
| 93 | 93 | expect(card.lines).toEqual(["5 open issues", "Critical path: 3 issues, #1 → #5", "Next: #6 Issue 6"]); |
| 94 | 94 | const fig = card.figure; |
| 95 | 95 | if (fig?.kind !== "graph") throw new Error("no graph"); |
| 96 | // Only the open chains are drawn: 6, on no edge, and 2, done, are counted, not drawn. | |
| 96 | // Only the open chains are drawn, as the page does by default: 6, on no | |
| 97 | // edge, is counted, not drawn, and the done one is counted, not drawn. | |
| 97 | 98 | expect(fig.nodes.length).toBe(4); |
| 98 | 99 | expect(fig.levels).toBe(3); |
| 99 | 100 | expect(fig.nodes.filter((n) => n.critical).length).toBe(3); |
new above
offline
This doc comment is right, but
docs/PLANNING.md:34still says the map draws "any closed one still on an edge". Update it to describe this default and?done=1, so a reader can find the closed issues again.