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

Closed opened this
Closed without merging

scout/forge:scout/6121-a-repository-s-map-draws-what-is-open-an → main 5 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
9 files changed +154 −36
README.md +3 −3
@@ -1735,9 +1735,9 @@ read leaves the card as it was.
17351735 Two of them carry a figure beside the words:
17361736
17371737 - **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
17411741 open count, the critical path's length and ends, and the next issue a free
17421742 hand would take; along the foot `ready · working · blocked · waiting · done`.
17431743 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.
3131
3232 ## The map
3333
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
3637 level below everything it is blocked by, so the top edge is what is ready
3738 now. Within a level, cards are ordered to keep the curves short and
3839 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.
2424 - `.map-edge-crit` — an edge on the critical path, in the accent.
2525 - `.map-edge-done` — an edge with a closed issue at either end, faded.
2626 - `.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 @@
99 */
1010
1111 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";
1313 import { cachedLayout } from "../map_cache.ts";
1414 import type { CardInput } from "./card.ts";
1515 import type { GraphEdge, GraphFigure, GraphNode } from "./graph.ts";
@@ -110,13 +110,8 @@ export function mapInput(title: string, graph: Graph, marks: Marks): CardInput {
110110 const words = new Map(graph.issues.map((i) => [i.id, wordFor(i, readySet, marks)]));
111111 const open = graph.issues.filter((i) => i.state === "open").length;
112112 // 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));
114113 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),
120115 words,
121116 path.map((i) => i.id),
122117 );
src/web/pages/map.ts +46 −20
@@ -930,6 +930,23 @@ export function countWords(words: readonly Word[]): Record<Word, number> {
930930 return out;
931931 }
932932
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 {

This doc comment is right, but docs/PLANNING.md:34 still 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.

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
933950 function countsLine(counts: Record<Word, number>): Html {
934951 const always = new Set<Word>(["ready", "working", "blocked", "done"]);
935952 const tone: Partial<Record<Word, string>> = {
@@ -1111,6 +1128,8 @@ export const mapCss = /* css */ `
11111128 .map-wrap { display: grid; grid-template-columns: minmax(0, 1fr) 272px; gap: 24px; align-items: start; margin-top: 4px; }
11121129 @media (max-width: 860px) { .map-wrap { grid-template-columns: 1fr; } }
11131130 .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; } }
11141133
11151134 /* ---- the canvas ---- */
11161135 .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> {
13561375 if (!repo) return notFoundPage(ctx);
13571376 const db = ctx.app.db;
13581377 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),
13771383 });
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 });
13781398 const rendering = performance.now();
13791399 const body = html`${repoHeader(ctx, repo, "map")}
13801400 <div class="page-head mt">
@@ -1392,13 +1412,19 @@ export async function mapPage(ctx: Ctx): Promise<Response> {
13921412 data-live-repo="${repo.ownerName}/${repo.name}"
13931413 >
13941414 <div class="map-main">
1395 ${drawMap(repo, graph, placed, emphasisFor(ready, critical, marks), {
1415 ${drawMap(repo, drawn, placed, emphasisFor(ready, critical, marks), {
13961416 id: "map-canvas",
13971417 cap: 1,
13981418 issueHref: tellHref,
13991419 ...(studio ? { empty: studioEmpty(repoBase(repo)) } : {}),
14001420 })}
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 withDone set, the done badge is a plain span, so ?done=1 has no way back. ${repoBase(repo)}/map as the href in that case would let the badge toggle the view.

1424 ? null
1425 : html`<a class="map-done-link" href="${repoBase(repo)}/map${withDone ? "" : "?done=1"}"
1426 >${withDone ? "Open only" : "Show done"}</a
1427 >`}`}
14021428 </div>
14031429 <aside class="stack">
14041430 ${pillars === undefined
test/map-page-timing.test.ts +1 −1
@@ -52,6 +52,6 @@ test("GET /:owner/:name/map names its phases", async () => {
5252 expect(res.status).toBe(200);
5353 expect(body).toContain("<h1>Map</h1>");
5454 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"])
5656 expect(parts.find((p) => p.startsWith(`${name};`))).toMatch(/^[a-z]+;dur=\d+\.\d$/);
5757 });
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", () => {
334334 test("a card says its word, who is on it, and wears a ring while the crew works", async () => {
335335 const cookie = await signIn("alice");
336336 const page = await (
337 await fetch(`${base}/alice/engine/map`, { headers: { cookie } })
337 await fetch(`${base}/alice/engine/map?done=1`, { headers: { cookie } })
338338 ).text();
339339 const card = (title: string) =>
340340 page.match(
@@ -369,7 +369,7 @@ describe("the map, per app and across the forge", () => {
369369 /data-state="blocked"[^>]*>blocked <b>1<\/b><\/span>/,
370370 );
371371 expect(page).toMatch(
372 /data-state="done"[^>]*>done <b>1<\/b><\/span>/,
372 /data-state="done"[^>]*>done <b>1<\/b><\/(span|a)>/,
373373 );
374374 expect(page).toMatch(
375375 /data-state="waiting"[^>]*>waiting <b>1<\/b><\/span>/,
test/og-designs.test.ts +2 −1
@@ -93,7 +93,8 @@ describe("the map's thumbnail", () => {
9393 expect(card.lines).toEqual(["5 open issues", "Critical path: 3 issues, #1 → #5", "Next: #6 Issue 6"]);
9494 const fig = card.figure;
9595 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.
9798 expect(fig.nodes.length).toBe(4);
9899 expect(fig.levels).toBe(3);
99100 expect(fig.nodes.filter((n) => n.critical).length).toBe(3);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs