Public: anyone can read this; the crew can change it.

The map says in one line what changed in a day, a week or a month: issues opened, landed, pillars finished #12777

Merged opened this

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

Merged

mason/forge:mason/12756-the-map-says-in-one-line-what-changed-in → main 10 commits fork 2 threads · 2 unresolved

  • Merged. mason/12756-the-map-says-in-one-line-what-changed-in was merged into main as 6362852.

Review

Sign in to review this change.
12 files changed +313 −20
docs/MCP.md +1 −1
@@ -142,7 +142,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`;
142142 | `limits` | — | Every limit the owner can hit | 1101 |
143143 | `maintenance` | `status`, `prepare`, `resume`, `pause-duty`, `resume-duty` | Prepare the forge for a power-off, check the drain, or end maintenance (admin) | 308 |
144144 | `make_it_yours` | — | Fork an app you can see: code and history, following the original | 337 |
145 | `map` | — | An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first | 465 |
145 | `map` | — | An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first | 521 |
146146 | `merge` | `land` | Land a pull, as its page's Merge button does; a person's only | 362 |
147147 | `migrate` | — | Bring a repo in by public `url` (`name`, `crew`), history and all | 269 |
148148 | `milestones` | — | How far each ask is | 439 |
docs/design/areas/map.md +4
@@ -35,3 +35,7 @@ issue on the page's one background, no frame and no badge. A row says its word (
3535 stands in front of it (`waits for N`) and what it holds up; a pillar row says its counts as muted text. `.map-canvas` has
3636 no border: the drawing sits on the page. The First button, its same-origin POST form and the 390px single column are
3737 unchanged. No new class.
38
39 ## The growth line (#12756)
40
41 `.map-growth` is the one line above the drawing: what changed in the span (`?since=day|week|month`), the counts as words, the other spans as links. `.map-card.map-new` marks a card created in the span, with `.map-new-dot`, a dot in the text colour (the accent is for interaction alone) in its corner: a heavier dashed edge and a dot, and "(new)" in its label, so the mark never rests on colour alone.
docs/features/README.md +1
@@ -137,6 +137,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
137137 - [Walking a wave](wave-walk.md)
138138 - [What became of the first ask](ask-status.md)
139139 - [When a setting or a permission stands in the way](blocked-by.md)
140 - [The map's growth line](map-growth.md)
140141 - [Your team](team.md)
141142
142143 ### Ship and undo
docs/features/map-growth.md added +12
@@ -0,0 +1,12 @@
1 # The map's growth line
2
3 One line says what changed in a span: `this week: 38 issues opened, 31 landed, 2 pillars finished`. Every door says the same words (`mapGrowthWords`, `src/core/growth.ts`).
4
5 - **Page.** `/OWNER/REPO/map` shows it above the drawing; `?since=day|week|month` picks the span (week when absent, junk falls back to the week). Cards created in the span carry a dashed heavier edge and a dot.
6 - **API.** `GET /api/v1/repos/OWNER/REPO/map?since=month` adds `growth: { since, opened, landed, pillarsFinished, words }`; an unknown `since` is a 422.
7 - **MCP.** The `map` tool takes `since` and answers the same `growth` field; an unknown value is an error.
8 - **Terminal.** The roadmap screen (open a repository, then Roadmap) prints the line at the top; `d`, `w`, `m` pick day, week, month.
9
10 Counts leave out sealed issues the reader may not see. A pillar counts as finished only when a person who writes the repository opened the closed umbrella (`umbrellaWriters`, the check `pillarsOf` uses), so a stranger's `P9 x: y` adds nothing.
11
12 Design notes for the page are in `docs/design/areas/map.md`.
src/core/growth.ts +59
@@ -9,6 +9,8 @@
99 */
1010
1111 import type { Database } from "bun:sqlite";
12 import { umbrellaWriters } from "./pillars.ts";
13 import type { Repo } from "./repos.ts";
1214 import type { sealedScope } from "./sealed.ts";
1315
1416 /** What `sealedScope` answered for the viewer. */
@@ -222,3 +224,60 @@ export function oldest(db: Database, repoId: string, scope: Scope = {}): { pull:
222224 };
223225 return { pull: one("pull", false), issue: one("issue", true) };
224226 }
227
228 /** The spans the map's growth line counts over (#12756); `week` is what an absent `since` means. */
229 export const SINCE = ["day", "week", "month"] as const;
230 export type Since = (typeof SINCE)[number];
231 const SINCE_DAYS: Readonly<Record<Since, number>> = { day: 1, week: 7, month: 30 };
232 const SINCE_WORDS: Readonly<Record<Since, string>> = { day: "today", week: "this week", month: "this month" };
233
234 /** `since` as asked: absent is the week, a known word is itself, anything else is undefined. */
235 export function parseSince(raw: string | null | undefined): Since | undefined {
236 if (raw === null || raw === undefined) return "week";
237 return (SINCE as readonly string[]).includes(raw) ? (raw as Since) : undefined;
238 }
239
240 export interface MapGrowth {
241 readonly since: Since;
242 /** The start of the span, an ISO instant: cards created at or after it are the span's. */
243 readonly from: string;
244 readonly opened: number;
245 readonly landed: number;
246 readonly pillarsFinished: number;
247 /** "this week: 38 issues opened, 31 landed, 2 pillars finished": one wording everywhere. */
248 readonly words: string;
249 }
250
251 /** The sentence over the counts. */
252 export function mapGrowthWords(since: Since, c: Pick<MapGrowth, "opened" | "landed" | "pillarsFinished">): string {
253 return `${SINCE_WORDS[since]}: ${plural(c.opened, "issue", "issues")} opened, ${c.landed} landed, ${plural(c.pillarsFinished, "pillar", "pillars")} finished`;
254 }
255
256 /**
257 * What changed in the span, for the line above the map. Opened and landed are `weekLine`'s own
258 * counts (one read of the repository's rows, so /next and the map agree); a pillar finished is a
259 * closed umbrella (`P0 Trust: …`) in the same span, counted only when a person who writes the
260 * repository opened it, as `pillarsOf` reads them: a title anyone can type makes no pillar.
261 */
262 export function mapGrowth(db: Database, repo: Repo, since: Since, now: Date, scope: Scope = {}): MapGrowth {
263 const days = SINCE_DAYS[since];
264 const line = weekLine(db, repo, days, now, scope);
265 const from = `${windowDays(now, days)[0]}T00:00:00.000Z`;
266 const [all, mine] = visibleArgs(scope);
267 const writers = umbrellaWriters(db, repo, "closed");
268 const pillars = writers.length === 0 ? null : db
outdated

Spoofable: any title shaped like P9 x: y counts as a pillar. Use pillarsOf's writer check and test a spoof.

269 .query<{ c: number }, (string | number)[]>(
270 `SELECT COUNT(*) AS c FROM issue i
271 WHERE i.repo_id = ?1 AND i.kind = 'issue' AND i.closed_at IS NOT NULL AND i.closed_at >= ?2
272 AND i.origin_author IS NULL AND i.title GLOB 'P[0-9]* *:*' ${visible(3, 4)}
273 AND i.author_id IN (${writers.map((_, k) => `?${k + 5}`).join(",")})`,
274 )
275 .get(repo.id, from, all, mine, ...writers);
276 const counts = { opened: line.opened, landed: line.closed, pillarsFinished: pillars?.c ?? 0 };
277 return { since, from, ...counts, words: mapGrowthWords(since, counts) };
278 }
279
280 /** The `growth` field of the map's answer: the counts and their words, minus the instant. */
281 export function growthField(g: MapGrowth): { since: Since; opened: number; landed: number; pillarsFinished: number; words: string } {
282 return { since: g.since, opened: g.opened, landed: g.landed, pillarsFinished: g.pillarsFinished, words: g.words };
283 }
src/core/pillars.ts +19 −10
@@ -56,24 +56,33 @@ export const LATER_TITLED = /^later/i;
5656 const MAX = 64;
5757
5858 /** An open issue, written here by a person, that is titled like an umbrella or the gate. */
59 const TITLED = `issue.repo_id = ?1 AND issue.kind = 'issue' AND issue.state = 'open'
59 const titled = (state: "open" | "closed"): string => `issue.repo_id = ?1 AND issue.kind = 'issue' AND issue.state = '${state}'
6060 AND issue.origin_author IS NULL
6161 AND (issue.title GLOB 'P[0-9]*' OR issue.title LIKE 'Later%')`;
62 const TITLED = titled("open");
63
64 /**
65 * The people who write the repository among those who opened an issue in `state` titled like an
66 * umbrella: the one check that makes a title count (`pillarsOf`, and the map's finished pillars).
67 */
68 export function umbrellaWriters(db: Database, repo: Repo, state: "open" | "closed" = "open"): string[] {
69 return db
70 .query<{ id: string }, [string]>(
71 `SELECT DISTINCT issue.author_id AS id
72 FROM issue JOIN user ON user.id = issue.author_id
73 WHERE ${titled(state)} AND user.kind = 'user' AND user.is_agent = 0`,
74 )
75 .all(repo.id)
76 .map((row) => row.id)
77 .filter((id) => canWrite(db, repo, getUserById(db, id)));
78 }
6279
6380 /** The pillars, the Later gate and the Later umbrella of one repository. */
6481 export function pillarsOf(db: Database, repo: Repo): Pillars {
6582 // Who among the people that opened such an issue writes the repository.
6683 // Asked per author, not per issue, and before the cap: however many
6784 // issues a stranger opens, none of them takes a real umbrella's place.
68 const writers = db
69 .query<{ id: string }, [string]>(
70 `SELECT DISTINCT issue.author_id AS id
71 FROM issue JOIN user ON user.id = issue.author_id
72 WHERE ${TITLED} AND user.kind = 'user' AND user.is_agent = 0`,
73 )
74 .all(repo.id)
75 .map((row) => row.id)
76 .filter((id) => canWrite(db, repo, getUserById(db, id)));
85 const writers = umbrellaWriters(db, repo);
7786 if (writers.length === 0)
7887 return { pillars: [], gate: undefined, later: undefined };
7988 const ids = db
src/http/api.ts +5 −1
@@ -255,6 +255,7 @@ import {
255255 import { forReader } from "../crew/handover.ts";
256256 import { globalMapJson } from "../web/pages/global-map.ts";
257257 import { withoutDone } from "../web/pages/map.ts";
258 import { growthField, mapGrowth, parseSince } from "../core/growth.ts";
258259 import { roadmapOf } from "../web/roadmap.ts";
259260 import { snapshotMap } from "../web/map_snapshot.ts";
260261 const MAP_PHASES = ["graph", "marks", "pillars", "asktolive", "held", "render"] as const;
@@ -2493,11 +2494,14 @@ export function apiRoutes(router: Router<Handler>): void {
24932494 if (!repo) return notFound();
24942495 const { request } = ctx;
24952496 notePhase(request, "session", takeSessionTime(request));
2497 const since = parseSince(ctx.url.searchParams.get("since"));
2498 if (since === undefined) return apiError("invalid_since", 422, "since is day, week or month");
24962499 const scope = sealedScope(ctx.app.db, repo, ctx.auth.user);
24972500 // Built by the map's worker, so the thread serves everything else meanwhile; a snapshot of this write clock answers at once.
24982501 const got = await snapshotMap(ctx.app, { repoId: repo.id, scope, now: new Date() });
24992502 if (got === undefined) return notFound();
2500 const { value } = got;
2503 // The growth line is read here, not in the snapshot: it moves with the clock, not with writes.
2504 const value = { ...got.value, growth: growthField(mapGrowth(ctx.app.db, repo, since, new Date(), scope)) };
25012505 // A snapshot skips the phases; they are still named, as hits at no cost.
25022506 if (got.hit) for (const name of MAP_PHASES) notePhase(request, name, 0, true);
25032507 else for (const [name, ms] of got.phases) notePhase(request, name, ms);
src/http/mcp/tools/map.ts +7 −3
@@ -7,6 +7,7 @@ import { listActiveRuns } from "../../../core/runs.ts";
77 import { spaceOf } from "../../../web/space_read.ts";
88 import { roadmapOf } from "../../../web/roadmap.ts";
99 import { mapJson, marksFor, withoutDone } from "../../../web/pages/map.ts";
10 import { growthField, mapGrowth, parseSince } from "../../../core/growth.ts";
1011 import { putIssueFirst } from "../../../actions/first.ts";
1112 import { cappedSpace } from "../map_space.ts";
1213 import { bad, good, type Tool, APP_ARG, planRepo, isAnswer, issueArg } from "../shared.ts";
@@ -15,12 +16,12 @@ const VIEWS = ["plan", "space"];
1516
1617 export const tool: Tool = {
1718 name: "map",
18 doc: "an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`, `done` to list closed issues too; `roadmap` for the pillars in order with ETAs; `first: <number>` puts that ready issue first, for writers: a reader is forbidden, a closed or blocked issue invalid); `view: \"space\"` for the space page's facts; draws the `ui://forge/map` card",
19 doc: "an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`, `done` to list closed issues too; `since` day|week|month sets the span of `growth`, the counts of what changed; `roadmap` for the pillars in order with ETAs; `first: <number>` puts that ready issue first, for writers: a reader is forbidden, a closed or blocked issue invalid); `view: \"space\"` for the space page's facts; draws the `ui://forge/map` card",
1920 description:
2021 "An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first.",
2122 inputSchema: {
2223 type: "object",
23 properties: { app: APP_ARG, done: { type: "boolean" }, roadmap: { type: "boolean" }, first: { type: "integer", minimum: 1 }, view: { type: "string", enum: VIEWS } },
24 properties: { app: APP_ARG, done: { type: "boolean" }, roadmap: { type: "boolean" }, since: { type: "string", enum: ["day", "week", "month"] }, first: { type: "integer", minimum: 1 }, view: { type: "string", enum: VIEWS } },
2425 required: ["app"],
2526 },
2627 writes: true,
@@ -43,6 +44,8 @@ export const tool: Tool = {
4344 const road = roadmapOf(ctx.app.db, repo, user);
4445 return road === undefined ? bad("no_pillars", "this app names no pillars") : good({ ...road });
4546 }
47 const since = parseSince(typeof args["since"] === "string" ? args["since"] : null);
48 if (since === undefined) return bad("invalid_since", "since is day, week or month");
4649 const scope = sealedScope(ctx.app.db, repo, user);
4750 const graph = repoGraph(ctx.app.db, repo.id, { ...scope });
4851 const pillars = pillarView(ctx.app.db, repo);
@@ -59,6 +62,7 @@ export const tool: Tool = {
5962 askToLiveFor(ctx.app, repo, pillars, user),
6063 mapHeldFor(ctx.app, repo, graph, scope),
6164 );
62 return good(args.done === true ? map : withoutDone(map));
65 const growth = growthField(mapGrowth(ctx.app.db, repo, since, new Date(), scope));
66 return good({ ...(args.done === true ? map : withoutDone(map)), growth });
6367 },
6468 };
src/tui/screens/roadmap.ts +22 −2
@@ -5,7 +5,11 @@
55 * gets Needs you.
66 */
77
8 import type { Database } from "bun:sqlite";
9 import type { User } from "../../core/users.ts";
10 import { mapGrowth, type Since } from "../../core/growth.ts";
811 import type { Repo } from "../../core/repos.ts";
12 import { sealedScope } from "../../core/sealed.ts";
913 import { paceSentence, roadmapOf, type Roadmap, type RoadmapIssue } from "../../web/roadmap.ts";
1014 import type { Ctx, Screen } from "../app/app.ts";
1115 import { binding } from "../app/keys.ts";
@@ -46,16 +50,27 @@ export function roadmapLines(road: Roadmap, width = 80): string[] {
4650 return out;
4751 }
4852
53 /** The map's growth line for this viewer (sealed issues left out), the page's own words. */
54 export const growthLine = (db: Database, user: User | undefined, repo: Repo, since: Since = "week", now = new Date()): string =>
55 mapGrowth(db, repo, since, now, sealedScope(db, repo, user)).words;
56
57 const SPANS: Readonly<Record<string, Since>> = { d: "day", w: "week", m: "month" };
58
4959 export function roadmapScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
5060 const scroll = new Scroll();
61 let since: Since = "week";
5162 let lines: string[] = [];
5263 return {
5364 title: `Roadmap · ${repo.ownerName}/${repo.name}`,
54 keys: [binding(["j", "k"], "scroll"), binding(["esc"], "back")],
65 keys: [binding(["j", "k"], "scroll"), binding(["d", "w", "m"], "day, week, month"), binding(["esc"], "back")],
5566 render(area, s) {
5667 const c = ctx.theme.c;
5768 const road = roadmapOf(f.app.db, repo, f.user);
58 lines = road === undefined ? ["This repository names no pillars."] : roadmapLines(road, area.w - 4);
69 lines = [
70 ...wrap(growthLine(f.db, f.user, repo, since), area.w - 4),
71 "",
72 ...(road === undefined ? ["This repository names no pillars."] : roadmapLines(road, area.w - 4)),
73 ];
5974 const from = scroll.window(area.h, lines.length);
6075 for (let i = 0; i < area.h; i++) {
6176 const line = lines[from + i];
@@ -67,6 +82,11 @@ export function roadmapScreen(f: Session, ctx: Ctx, repo: Repo): Screen {
6782 ctx.pop();
6883 return true;
6984 }
85 const span = SPANS[e.key];
86 if (span !== undefined && !e.ctrl && !e.alt) {
87 since = span;
88 return true;
89 }
7090 return scroll.key(e, lines.length);
7191 },
7292 };
src/web/pages/map.ts +26 −2
@@ -24,6 +24,7 @@ import { mayDirectCrew } from "../../crew/direct.ts";
2424 import { faceAt } from "../pixel.ts";
2525 import type { MapHold } from "../../crew/held.ts";
2626 import { sealedScope } from "../../core/sealed.ts";
27 import { SINCE, mapGrowth, parseSince, type MapGrowth } from "../../core/growth.ts";
2728 import type { Database } from "bun:sqlite";
2829 import {
2930 blockedOn,
@@ -643,6 +644,8 @@ export interface Emphasis {
643644 /** The path's own edges, blocker to blocked, as `routeKey`s. */
644645 readonly chain: Set<string>;
645646 readonly marks: Marks;
647 /** The cards created in the map's growth span (#12756): drawn with `map-new`. */
648 readonly added?: ReadonlySet<string>;
646649 }
647650
648651 /** What to emphasise, from the ready list, the critical path and the marks. */
@@ -650,6 +653,7 @@ export function emphasisFor(
650653 ready: readonly Ranked[],
651654 path: readonly Issue[],
652655 marks: Marks,
656 added?: ReadonlySet<string>,
653657 ): Emphasis {
654658 const chain = new Set<string>();
655659 for (let i = 0; i + 1 < path.length; i++)
@@ -659,6 +663,7 @@ export function emphasisFor(
659663 critical: new Set(path.map((i) => i.id)),
660664 chain,
661665 marks,
666 ...(added === undefined ? {} : { added }),
662667 };
663668 }
664669
@@ -723,6 +728,7 @@ function node(
723728 data-crit="${emphasis.critical.has(n.issue.id) ? "1" : "0"}"
724729 ${run ? html`data-run="${run}"` : null}
725730 href="${issueHref(base, n.issue.number)}"
731 ${emphasis.added?.has(n.issue.id) ? html`aria-description="new in this span"` : null}
726732 aria-label="${number} ${n.issue.title} — ${word}${word === "held" ? ` by ${emphasis.marks.onHold.get(n.issue.id)}` : word === "deferred" ? `: ${emphasis.marks.deferred.get(n.issue.id)}` : emphasis.marks.why.has(n.issue.id) ? `: ${emphasis.marks.why.get(n.issue.id)}` : ""}"
727733 >
728734 ${word === "working"
@@ -736,7 +742,7 @@ function node(
736742 />`
737743 : null}
738744 <rect
739 class="map-card"
745 class="map-card${emphasis.added?.has(n.issue.id) ? " map-new" : ""}"
740746 x="${px}"
741747 y="${py}"
742748 width="${W}"
@@ -748,6 +754,7 @@ function node(
748754 ? null
749755 : html`<tspan x="${left}" dy="16">${second}</tspan>`}
750756 </text>
757 ${emphasis.added?.has(n.issue.id) ? html`<circle class="map-new-dot" cx="${px + W - 9}" cy="${py + 9}" r="4" />` : null}
751758 <text class="map-meta" x="${left}" y="${bottom}">${number}</text>
752759 ${face !== null
753760 ? html`<g class="map-who">
@@ -1158,6 +1165,9 @@ export const mapCss = /* css */ `
11581165 .map-node[data-state="waiting"] .map-card { stroke: color-mix(in srgb, var(--merged) 55%, var(--border)); }
11591166 .map-node[data-state="parked"] .map-card { fill: color-mix(in srgb, var(--attn) 7%, var(--card)); stroke: color-mix(in srgb, var(--attn) 45%, var(--border)); }
11601167 .map-node[data-state="done"] .map-card { fill: none; stroke: var(--border); }

Principle 5: accent is for interaction alone; this dot is not interactive. Use --fg/--muted.

1168 .map-card.map-new { stroke-width: 2; stroke-dasharray: 2 2; }
1169 .map-new-dot { fill: var(--fg); }
1170 .map-growth { margin: 0 0 var(--gap, 12px); }
11611171 .map-node:hover .map-card { stroke: var(--border-strong); }
11621172 .map-node[data-state="working"]:hover .map-card { stroke: var(--accent); }
11631173 .map-node:focus-visible .map-card { stroke: var(--accent); stroke-width: 2; }
@@ -1422,6 +1432,16 @@ export function lastLooked(
14221432 return { since: p, cookie: `${p ?? ""}~${c}` };
14231433 }
14241434
1435 /** The ids of the cards created in the span: the ones drawn with the new mark. */
1436 function addedIn(graph: Graph, g: MapGrowth): Set<string> {
1437 return new Set(graph.issues.filter((i) => i.createdAt >= g.from).map((i) => i.id));
1438 }
1439
1440 /** The one line above the drawing: the counts, as words, and the other spans as links. */
1441 function growthLine(g: MapGrowth, href: (w: string) => string): Html {
1442 return html`<p class="map-growth" data-map-growth>${g.words} · ${SINCE.map((w, i) => html`${i === 0 ? null : " "}${w === g.since ? html`<b>${w}</b>` : html`<a href="${href(w)}">${w}</a>`}`)}</p>`;
1443 }
1444
14251445 /** GET /:owner/:name/map (`?done=1` draws the closed issues too; `?view=graph` is the drawing) */
14261446 export async function mapPage(ctx: Ctx): Promise<Response> {
14271447 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
@@ -1443,6 +1463,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> {
14431463 });
14441464 if (road !== undefined) {
14451465 const base = repoBase(repo);
1466 const growth = mapGrowth(ctx.app.db, repo, parseSince(ctx.url.searchParams.get("since")) ?? "week", new Date(), sealedScope(ctx.app.db, repo, ctx.auth.user));
14461467 const response = page({
14471468 ctx,
14481469 title: `Roadmap · ${repo.name}`,
@@ -1453,6 +1474,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> {
14531474 <h1>Roadmap</h1>
14541475 <p class="muted small"><a href="${base}/map?view=graph">The graph</a> · <a href="${base}/space">The space</a></p>
14551476 </div>
1477 ${growthLine(growth, (w) => `${base}/map?since=${w}`)}
14561478 <div
14571479 class="rm"
14581480 id="roadmap-live"
@@ -1473,6 +1495,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> {
14731495 }
14741496 }
14751497 const db = ctx.app.db;
1498 const growth = mapGrowth(db, repo, parseSince(ctx.url.searchParams.get("since")) ?? "week", new Date(), sealedScope(db, repo, ctx.auth.user));
14761499 const studio = studioRecord(ctx, repo) !== undefined;
14771500 const showDone = ctx.url.searchParams.get("done") === "1";
14781501 // The read, one Server-Timing phase per step (#8381); `render` is the page's own.
@@ -1512,6 +1535,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> {
15121535 <span class="spacer"></span>
15131536 <a href="${repoBase(repo)}/space">Space</a><a href="${repoBase(repo)}/milestones">Milestones</a><a href="${repoBase(repo)}/next">Next up</a>
15141537 </div>
1538 ${growthLine(growth, (w) => `${repoBase(repo)}/map?${showDone ? "done=1" : "view=graph"}&since=${w}`)}
15151539 ${disclosure("? How to read this", html`<div class="prose break" id="map-help">
15161540 <p>What waits for what. The top edge is ready now; the chain in the accent is the least work that still has to happen in order.</p>
15171541 <p>The first list is what nothing stands in front of; when it is empty, everything open waits for something. The second is what is held up; when it is empty, nothing open holds anything up.</p>
@@ -1523,7 +1547,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> {
15231547 data-live-repo="${repo.ownerName}/${repo.name}"
15241548 >
15251549 <div class="map-main">
1526 ${drawMap(repo, shown, placed, emphasisFor(ready, critical, marks), {
1550 ${drawMap(repo, shown, placed, emphasisFor(ready, critical, marks, addedIn(graph, growth)), {
15271551 id: "map-canvas",
15281552 cap: 1,
15291553 issueHref: tellHref,
test/map-growth.test.ts added +131
@@ -0,0 +1,131 @@
1 /** The map's one line of growth (#12756): page, API and MCP say the same words. */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { openIssue } from "../src/actions/issues.ts";
8 import { createRepo } from "../src/actions/repos.ts";
9 import { mapGrowth, mapGrowthWords, parseSince, weekLine } from "../src/core/growth.ts";
10 import { createSession } from "../src/core/sessions.ts";
11 import { createToken } from "../src/core/tokens.ts";
12 import { createUser, type User } from "../src/core/users.ts";
13 import type { Repo } from "../src/core/repos.ts";
14 import { expectWork } from "./helpers/work.ts";
15 import { statements } from "./helpers/statements.ts";
16 import { serve, type Servers } from "../src/http/server.ts";
17
18 let dir: string;
19 let app: App;
20 let servers: Servers;
21 let cookie: string;
22 let token: string;
23 let alice: User;
24 let repo: Repo;
25
26 const DAY = 86_400_000;
27 const ago = (days: number): string => new Date(Date.now() - days * DAY).toISOString();
28
29 beforeAll(async () => {
30 dir = await mkdtemp(join(tmpdir(), "forge-map-growth-"));
31 app = createApp({ dataDir: dir, port: 0 });
32 servers = await serve(app);
33 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
34 if (!made.ok) throw new Error(made.error);
35 alice = made.value;
36 cookie = `forge_session=${createSession(app.db, alice.id).token}`;
37 token = createToken(app.db, alice.id, "rw", "rw").token;
38 const r = await createRepo(app, alice, { name: "g", visibility: "public" });
39 if (!r.ok) throw new Error(JSON.stringify(r.error));
40 repo = r.value;
41 for (const t of ["Old one", "Fresh one", "Fresh two", "P0 Trust: be safe"]) if (!openIssue(app, alice, repo, { title: t }).ok) throw new Error("issue");
42 // "Old one" opened and closed twenty days ago; the umbrella closed three days ago.
43 app.db.run("UPDATE issue SET created_at = ?1, closed_at = ?1, state = 'closed' WHERE repo_id = ?2 AND title = 'Old one'", [ago(20), repo.id]);
44 app.db.run("UPDATE issue SET closed_at = ?1, state = 'closed' WHERE repo_id = ?2 AND title LIKE 'P0 %'", [ago(3), repo.id]);
45 app.db.run("UPDATE issue SET created_at = ?1 WHERE repo_id = ?2 AND title LIKE 'P0 %'", [ago(25), repo.id]);
46 });
47
48 afterAll(async () => {
49 await servers.stop();
50 app.close();
51 await rm(dir, { recursive: true, force: true });
52 });
53
54 const WEEK = "this week: 2 issues opened, 1 landed, 1 pillar finished";
55
56 test("the words count what the span holds, from weekLine's own numbers", () => {
57 expect(parseSince(null)).toBe("week");
58 expect(parseSince("junk")).toBeUndefined();
59 const week = mapGrowth(app.db, repo, "week", new Date());
60 expect(week.words).toBe(WEEK);
61 expect(week.opened).toBe(weekLine(app.db, repo, 7, new Date()).opened);
62 expect(mapGrowth(app.db, repo, "day", new Date()).pillarsFinished).toBe(0);
63 expect(mapGrowth(app.db, repo, "month", new Date()).words).toBe("this month: 4 issues opened, 2 landed, 1 pillar finished");
64 expect(mapGrowthWords("day", { opened: 1, landed: 0, pillarsFinished: 2 })).toBe("today: 1 issue opened, 0 landed, 2 pillars finished");
65 });
66
67 test("the page says it above the drawing and marks the new cards by class", async () => {
68 const res = await fetch(`${servers.url}/alice/g/map?view=graph`, { headers: { cookie } });
69 const page = await res.text();
70 expect(res.status).toBe(200);
71 expect(page).toContain(`data-map-growth>this week: 2 issues opened, `);
72 expect(page.indexOf("data-map-growth")).toBeLessThan(page.indexOf('id="map-canvas"'));
73 expect((page.match(/class="map-card map-new"/g) ?? []).length).toBe(2);
74 expect(page).toContain("map-new-dot");
75 const month = await (await fetch(`${servers.url}/alice/g/map?view=graph&since=month`, { headers: { cookie } })).text();
76 expect(month).toContain("this month: 4 issues opened");
77 // Junk falls back to the week.
78 const junk = await fetch(`${servers.url}/alice/g/map?view=graph&since=forever`, { headers: { cookie } });
79 expect(junk.status).toBe(200);
80 expect(await junk.text()).toContain("data-map-growth>this week:");
81 });
82
83 test("the API carries growth with the same words; junk is a 422", async () => {
84 const get = (q: string) => fetch(`${servers.url}/api/v1/repos/alice/g/map${q}`, { headers: { authorization: `Bearer ${token}` } });
85 const body: any = await (await get("")).json();
86 expect(body.growth.words).toStartWith("this week: 2 issues opened");
87 expect(body.growth.since).toBe("week");
88 const month: any = await (await get("?since=month")).json();
89 expect(month.growth.words).toBe("this month: 4 issues opened, 2 landed, 1 pillar finished");
90 expect(month.growth.pillarsFinished).toBe(1);
91 const bad = await get("?since=junk");
92 expect(bad.status).toBe(422);
93 });
94
95 test("the map tool carries the same growth field", async () => {
96 const call = async (args: unknown) => {
97 const res = await fetch(`${servers.url}/mcp`, {
98 method: "POST",
99 headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` },
100 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "map", arguments: args } }),
101 });
102 const b: any = await res.json();
103 const text: string = b.result.content[0].text;
104 return b.result.isError === true ? { error: true, value: text } : { error: false, value: JSON.parse(text) };
105 };
106 const ok = await call({ app: "alice/g", since: "month" });
107 expect(ok.value.growth.words).toBe("this month: 4 issues opened, 2 landed, 1 pillar finished");
108 expect((await call({ app: "alice/g" })).value.growth.since).toBe("week");
109 expect((await call({ app: "alice/g", since: "junk" })).error).toBe(true);
110 });
111
112 test("a stranger's title shaped like an umbrella is no pillar finished", async () => {
113 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "mallory", email: "[email protected]", password: "a-good-passphrase" });
114 if (!made.ok) throw new Error(made.error);
115 const spoof = openIssue(app, made.value, repo, { title: "P9 Fake: please count me" });
116 if (!spoof.ok) throw new Error("spoof");
117 app.db.run("UPDATE issue SET closed_at = ?1, state = 'closed' WHERE repo_id = ?2 AND title LIKE 'P9 %'", [ago(1), repo.id]);
118 expect(mapGrowth(app.db, repo, "week", new Date()).pillarsFinished).toBe(1);
119 expect(mapGrowth(app.db, repo, "month", new Date()).pillarsFinished).toBe(1);
120 });
121
122 test("the growth read stays inside the map's page budget on a large repository", async () => {
123 const stmt = app.db.prepare("INSERT INTO issue (id, repo_id, number, kind, title, body, state, author_id, created_at, updated_at) SELECT ?1, ?2, ?3, 'issue', 'bulk', '', 'open', ?4, ?5, ?5");
124 app.db.transaction(() => {
125 for (let k = 0; k < 3000; k++) stmt.run(`bulk-${k}`, repo.id, 1000 + k, alice.id, ago(k % 20));
126 })();
127 // Counted work, not a clock: the read's statements do not grow with the repository.
128 const small = await statements(app.db, () => void mapGrowth(app.db, repo, "month", new Date()));
129 expectWork(small, { max: 12 });
130 app.db.run("DELETE FROM issue WHERE id LIKE 'bulk-%'");
131 });
test/roadmap-tui.test.ts +26 −1
@@ -11,7 +11,8 @@ import { setHold } from "../src/core/holds.ts";
1111 import { createIssue } from "../src/core/issues.ts";
1212 import { createUser, type User } from "../src/core/users.ts";
1313 import { createForgeApp } from "../src/tui/forge.ts";
14 import { roadmapLines } from "../src/tui/screens/roadmap.ts";
14 import { mapGrowth } from "../src/core/growth.ts";
15 import { growthLine, roadmapLines } from "../src/tui/screens/roadmap.ts";
1516 import type { TuiIdentity } from "../src/tui/session.ts";
1617 import { headlessTerminal } from "../src/tui/term/terminal.ts";
1718 import { roadmapOf } from "../src/web/roadmap.ts";
@@ -33,6 +34,8 @@ describe("roadmap in the terminal", () => {
3334 app.start();
3435 const key = (k: string) => app.dispatch({ type: "key", key: k, ctrl: false, alt: false, shift: false });
3536 return {
37 app,
38 key,
3639 text: () => app.screen.toText(),
3740 async open(spec: string) {
3841 await settleApp(app);
@@ -97,6 +100,28 @@ describe("roadmap in the terminal", () => {
97100 t.stop();
98101 });
99102
103 test("the growth line is the page's words, and d/w/m pick the span", async () => {
104 const t = boot(ada);
105 await t.open("ada/road");
106 expect(t.text()).toContain("this week: 2 issues opened, 0 landed, 0 pillars finished");
107 t.key("m");
108 await settleApp(t.app);
109 expect(t.text()).toContain("this month: 2 issues opened");
110 const repo = getRepo(forge.db, "ada", "road")!;
111 expect(growthLine(forge.db, ada, repo)).toBe(mapGrowth(forge.db, repo, "week", new Date()).words);
112 t.stop();
113 });
114
115 test("the sealed issues a reader may not see are not counted in the line", () => {
116 const repo = getRepo(forge.db, "ada", "road")!;
117 const sealed = createIssue(forge.db, { repoId: repo.id, authorId: ada.id, title: "Sealed hole", body: "" });
118 if (!sealed.ok) throw new Error(sealed.error);
119 forge.db.run("UPDATE issue SET sealed = 1 WHERE id = ?1", [sealed.value.id]);
120 expect(growthLine(forge.db, ada, repo, "day")).toContain("3 issues opened");
121 expect(growthLine(forge.db, eve, repo, "day")).toContain("2 issues opened");
122 forge.db.run("DELETE FROM issue WHERE id = ?1", [sealed.value.id]);
123 });
124
100125 test("lines come from the model", () => {
101126 const repo = getRepo(forge.db, "ada", "road")!;
102127 const lines = roadmapLines(roadmapOf(forge.db, repo, ada)!, 80);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs