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
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/12756-the-map-says-in-one-line-what-changed-in → main 10 commits fork 2 threads · 2 unresolved
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`; | ||
| 142 | 142 | | `limits` | — | Every limit the owner can hit | 1101 | |
| 143 | 143 | | `maintenance` | `status`, `prepare`, `resume`, `pause-duty`, `resume-duty` | Prepare the forge for a power-off, check the drain, or end maintenance (admin) | 308 | |
| 144 | 144 | | `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 | | |
| 146 | 146 | | `merge` | `land` | Land a pull, as its page's Merge button does; a person's only | 362 | |
| 147 | 147 | | `migrate` | — | Bring a repo in by public `url` (`name`, `crew`), history and all | 269 | |
| 148 | 148 | | `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 ( | ||
| 35 | 35 | 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 |
| 36 | 36 | no border: the drawing sits on the page. The First button, its same-origin POST form and the 390px single column are |
| 37 | 37 | 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). | ||
| 137 | 137 | - [](wave-walk.md) |
| 138 | 138 | - [](ask-status.md) |
| 139 | 139 | - [](blocked-by.md) |
| 140 | - [](map-growth.md) | |
| 140 | 141 | - [](team.md) |
| 141 | 142 | |
| 142 | 143 | ### 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 @@ | ||
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | 11 | import type { Database } from "bun:sqlite"; |
| 12 | import { umbrellaWriters } from "./pillars.ts"; | |
| 13 | import type { Repo } from "./repos.ts"; | |
| 12 | 14 | import type { sealedScope } from "./sealed.ts"; |
| 13 | 15 | |
| 14 | 16 | /** What `sealedScope` answered for the viewer. */ |
| @@ -222,3 +224,60 @@ export function oldest(db: Database, repoId: string, scope: Scope = {}): { pull: | ||
| 222 | 224 | }; |
| 223 | 225 | return { pull: one("pull", false), issue: one("issue", true) }; |
| 224 | 226 | } |
| 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 | |
| 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; | ||
| 56 | 56 | const MAX = 64; |
| 57 | 57 | |
| 58 | 58 | /** 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}' | |
| 60 | 60 | AND issue.origin_author IS NULL |
| 61 | 61 | 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 | } | |
| 62 | 79 | |
| 63 | 80 | /** The pillars, the Later gate and the Later umbrella of one repository. */ |
| 64 | 81 | export function pillarsOf(db: Database, repo: Repo): Pillars { |
| 65 | 82 | // Who among the people that opened such an issue writes the repository. |
| 66 | 83 | // Asked per author, not per issue, and before the cap: however many |
| 67 | 84 | // 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); | |
| 77 | 86 | if (writers.length === 0) |
| 78 | 87 | return { pillars: [], gate: undefined, later: undefined }; |
| 79 | 88 | const ids = db |
src/http/api.ts +5 −1
| @@ -255,6 +255,7 @@ import { | ||
| 255 | 255 | import { forReader } from "../crew/handover.ts"; |
| 256 | 256 | import { globalMapJson } from "../web/pages/global-map.ts"; |
| 257 | 257 | import { withoutDone } from "../web/pages/map.ts"; |
| 258 | import { growthField, mapGrowth, parseSince } from "../core/growth.ts"; | |
| 258 | 259 | import { roadmapOf } from "../web/roadmap.ts"; |
| 259 | 260 | import { snapshotMap } from "../web/map_snapshot.ts"; |
| 260 | 261 | const MAP_PHASES = ["graph", "marks", "pillars", "asktolive", "held", "render"] as const; |
| @@ -2493,11 +2494,14 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 2493 | 2494 | if (!repo) return notFound(); |
| 2494 | 2495 | const { request } = ctx; |
| 2495 | 2496 | 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"); | |
| 2496 | 2499 | const scope = sealedScope(ctx.app.db, repo, ctx.auth.user); |
| 2497 | 2500 | // Built by the map's worker, so the thread serves everything else meanwhile; a snapshot of this write clock answers at once. |
| 2498 | 2501 | const got = await snapshotMap(ctx.app, { repoId: repo.id, scope, now: new Date() }); |
| 2499 | 2502 | 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)) }; | |
| 2501 | 2505 | // A snapshot skips the phases; they are still named, as hits at no cost. |
| 2502 | 2506 | if (got.hit) for (const name of MAP_PHASES) notePhase(request, name, 0, true); |
| 2503 | 2507 | 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"; | ||
| 7 | 7 | import { spaceOf } from "../../../web/space_read.ts"; |
| 8 | 8 | import { roadmapOf } from "../../../web/roadmap.ts"; |
| 9 | 9 | import { mapJson, marksFor, withoutDone } from "../../../web/pages/map.ts"; |
| 10 | import { growthField, mapGrowth, parseSince } from "../../../core/growth.ts"; | |
| 10 | 11 | import { putIssueFirst } from "../../../actions/first.ts"; |
| 11 | 12 | import { cappedSpace } from "../map_space.ts"; |
| 12 | 13 | import { bad, good, type Tool, APP_ARG, planRepo, isAnswer, issueArg } from "../shared.ts"; |
| @@ -15,12 +16,12 @@ const VIEWS = ["plan", "space"]; | ||
| 15 | 16 | |
| 16 | 17 | export const tool: Tool = { |
| 17 | 18 | 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", | |
| 19 | 20 | description: |
| 20 | 21 | "An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first.", |
| 21 | 22 | inputSchema: { |
| 22 | 23 | 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 } }, | |
| 24 | 25 | required: ["app"], |
| 25 | 26 | }, |
| 26 | 27 | writes: true, |
| @@ -43,6 +44,8 @@ export const tool: Tool = { | ||
| 43 | 44 | const road = roadmapOf(ctx.app.db, repo, user); |
| 44 | 45 | return road === undefined ? bad("no_pillars", "this app names no pillars") : good({ ...road }); |
| 45 | 46 | } |
| 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"); | |
| 46 | 49 | const scope = sealedScope(ctx.app.db, repo, user); |
| 47 | 50 | const graph = repoGraph(ctx.app.db, repo.id, { ...scope }); |
| 48 | 51 | const pillars = pillarView(ctx.app.db, repo); |
| @@ -59,6 +62,7 @@ export const tool: Tool = { | ||
| 59 | 62 | askToLiveFor(ctx.app, repo, pillars, user), |
| 60 | 63 | mapHeldFor(ctx.app, repo, graph, scope), |
| 61 | 64 | ); |
| 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 }); | |
| 63 | 67 | }, |
| 64 | 68 | }; |
src/tui/screens/roadmap.ts +22 −2
| @@ -5,7 +5,11 @@ | ||
| 5 | 5 | * gets Needs you. |
| 6 | 6 | */ |
| 7 | 7 | |
| 8 | import type { Database } from "bun:sqlite"; | |
| 9 | import type { User } from "../../core/users.ts"; | |
| 10 | import { mapGrowth, type Since } from "../../core/growth.ts"; | |
| 8 | 11 | import type { Repo } from "../../core/repos.ts"; |
| 12 | import { sealedScope } from "../../core/sealed.ts"; | |
| 9 | 13 | import { paceSentence, roadmapOf, type Roadmap, type RoadmapIssue } from "../../web/roadmap.ts"; |
| 10 | 14 | import type { Ctx, Screen } from "../app/app.ts"; |
| 11 | 15 | import { binding } from "../app/keys.ts"; |
| @@ -46,16 +50,27 @@ export function roadmapLines(road: Roadmap, width = 80): string[] { | ||
| 46 | 50 | return out; |
| 47 | 51 | } |
| 48 | 52 | |
| 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 | ||
| 49 | 59 | export function roadmapScreen(f: Session, ctx: Ctx, repo: Repo): Screen { |
| 50 | 60 | const scroll = new Scroll(); |
| 61 | let since: Since = "week"; | |
| 51 | 62 | let lines: string[] = []; |
| 52 | 63 | return { |
| 53 | 64 | 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")], | |
| 55 | 66 | render(area, s) { |
| 56 | 67 | const c = ctx.theme.c; |
| 57 | 68 | 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 | ]; | |
| 59 | 74 | const from = scroll.window(area.h, lines.length); |
| 60 | 75 | for (let i = 0; i < area.h; i++) { |
| 61 | 76 | const line = lines[from + i]; |
| @@ -67,6 +82,11 @@ export function roadmapScreen(f: Session, ctx: Ctx, repo: Repo): Screen { | ||
| 67 | 82 | ctx.pop(); |
| 68 | 83 | return true; |
| 69 | 84 | } |
| 85 | const span = SPANS[e.key]; | |
| 86 | if (span !== undefined && !e.ctrl && !e.alt) { | |
| 87 | since = span; | |
| 88 | return true; | |
| 89 | } | |
| 70 | 90 | return scroll.key(e, lines.length); |
| 71 | 91 | }, |
| 72 | 92 | }; |
src/web/pages/map.ts +26 −2
| @@ -24,6 +24,7 @@ import { mayDirectCrew } from "../../crew/direct.ts"; | ||
| 24 | 24 | import { faceAt } from "../pixel.ts"; |
| 25 | 25 | import type { MapHold } from "../../crew/held.ts"; |
| 26 | 26 | import { sealedScope } from "../../core/sealed.ts"; |
| 27 | import { SINCE, mapGrowth, parseSince, type MapGrowth } from "../../core/growth.ts"; | |
| 27 | 28 | import type { Database } from "bun:sqlite"; |
| 28 | 29 | import { |
| 29 | 30 | blockedOn, |
| @@ -643,6 +644,8 @@ export interface Emphasis { | ||
| 643 | 644 | /** The path's own edges, blocker to blocked, as `routeKey`s. */ |
| 644 | 645 | readonly chain: Set<string>; |
| 645 | 646 | readonly marks: Marks; |
| 647 | /** The cards created in the map's growth span (#12756): drawn with `map-new`. */ | |
| 648 | readonly added?: ReadonlySet<string>; | |
| 646 | 649 | } |
| 647 | 650 | |
| 648 | 651 | /** What to emphasise, from the ready list, the critical path and the marks. */ |
| @@ -650,6 +653,7 @@ export function emphasisFor( | ||
| 650 | 653 | ready: readonly Ranked[], |
| 651 | 654 | path: readonly Issue[], |
| 652 | 655 | marks: Marks, |
| 656 | added?: ReadonlySet<string>, | |
| 653 | 657 | ): Emphasis { |
| 654 | 658 | const chain = new Set<string>(); |
| 655 | 659 | for (let i = 0; i + 1 < path.length; i++) |
| @@ -659,6 +663,7 @@ export function emphasisFor( | ||
| 659 | 663 | critical: new Set(path.map((i) => i.id)), |
| 660 | 664 | chain, |
| 661 | 665 | marks, |
| 666 | ...(added === undefined ? {} : { added }), | |
| 662 | 667 | }; |
| 663 | 668 | } |
| 664 | 669 | |
| @@ -723,6 +728,7 @@ function node( | ||
| 723 | 728 | data-crit="${emphasis.critical.has(n.issue.id) ? "1" : "0"}" |
| 724 | 729 | ${run ? html`data-run="${run}"` : null} |
| 725 | 730 | href="${issueHref(base, n.issue.number)}" |
| 731 | ${emphasis.added?.has(n.issue.id) ? html`aria-description="new in this span"` : null} | |
| 726 | 732 | 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)}` : ""}" |
| 727 | 733 | > |
| 728 | 734 | ${word === "working" |
| @@ -736,7 +742,7 @@ function node( | ||
| 736 | 742 | />` |
| 737 | 743 | : null} |
| 738 | 744 | <rect |
| 739 | class="map-card" | |
| 745 | class="map-card${emphasis.added?.has(n.issue.id) ? " map-new" : ""}" | |
| 740 | 746 | x="${px}" |
| 741 | 747 | y="${py}" |
| 742 | 748 | width="${W}" |
| @@ -748,6 +754,7 @@ function node( | ||
| 748 | 754 | ? null |
| 749 | 755 | : html`<tspan x="${left}" dy="16">${second}</tspan>`} |
| 750 | 756 | </text> |
| 757 | ${emphasis.added?.has(n.issue.id) ? html`<circle class="map-new-dot" cx="${px + W - 9}" cy="${py + 9}" r="4" />` : null} | |
| 751 | 758 | <text class="map-meta" x="${left}" y="${bottom}">${number}</text> |
| 752 | 759 | ${face !== null |
| 753 | 760 | ? html`<g class="map-who"> |
| @@ -1158,6 +1165,9 @@ export const mapCss = /* css */ ` | ||
| 1158 | 1165 | .map-node[data-state="waiting"] .map-card { stroke: color-mix(in srgb, var(--merged) 55%, var(--border)); } |
| 1159 | 1166 | .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)); } |
| 1160 | 1167 | .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); } | |
| 1161 | 1171 | .map-node:hover .map-card { stroke: var(--border-strong); } |
| 1162 | 1172 | .map-node[data-state="working"]:hover .map-card { stroke: var(--accent); } |
| 1163 | 1173 | .map-node:focus-visible .map-card { stroke: var(--accent); stroke-width: 2; } |
| @@ -1422,6 +1432,16 @@ export function lastLooked( | ||
| 1422 | 1432 | return { since: p, cookie: `${p ?? ""}~${c}` }; |
| 1423 | 1433 | } |
| 1424 | 1434 | |
| 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 | ||
| 1425 | 1445 | /** GET /:owner/:name/map (`?done=1` draws the closed issues too; `?view=graph` is the drawing) */ |
| 1426 | 1446 | export async function mapPage(ctx: Ctx): Promise<Response> { |
| 1427 | 1447 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| @@ -1443,6 +1463,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> { | ||
| 1443 | 1463 | }); |
| 1444 | 1464 | if (road !== undefined) { |
| 1445 | 1465 | 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)); | |
| 1446 | 1467 | const response = page({ |
| 1447 | 1468 | ctx, |
| 1448 | 1469 | title: `Roadmap · ${repo.name}`, |
| @@ -1453,6 +1474,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> { | ||
| 1453 | 1474 | <h1>Roadmap</h1> |
| 1454 | 1475 | <p class="muted small"><a href="${base}/map?view=graph">The graph</a> · <a href="${base}/space">The space</a></p> |
| 1455 | 1476 | </div> |
| 1477 | ${growthLine(growth, (w) => `${base}/map?since=${w}`)} | |
| 1456 | 1478 | <div |
| 1457 | 1479 | class="rm" |
| 1458 | 1480 | id="roadmap-live" |
| @@ -1473,6 +1495,7 @@ export async function mapPage(ctx: Ctx): Promise<Response> { | ||
| 1473 | 1495 | } |
| 1474 | 1496 | } |
| 1475 | 1497 | 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)); | |
| 1476 | 1499 | const studio = studioRecord(ctx, repo) !== undefined; |
| 1477 | 1500 | const showDone = ctx.url.searchParams.get("done") === "1"; |
| 1478 | 1501 | // 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> { | ||
| 1512 | 1535 | <span class="spacer"></span> |
| 1513 | 1536 | <a href="${repoBase(repo)}/space">Space</a><a href="${repoBase(repo)}/milestones">Milestones</a><a href="${repoBase(repo)}/next">Next up</a> |
| 1514 | 1537 | </div> |
| 1538 | ${growthLine(growth, (w) => `${repoBase(repo)}/map?${showDone ? "done=1" : "view=graph"}&since=${w}`)} | |
| 1515 | 1539 | ${disclosure("? How to read this", html`<div class="prose break" id="map-help"> |
| 1516 | 1540 | <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> |
| 1517 | 1541 | <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> { | ||
| 1523 | 1547 | data-live-repo="${repo.ownerName}/${repo.name}" |
| 1524 | 1548 | > |
| 1525 | 1549 | <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)), { | |
| 1527 | 1551 | id: "map-canvas", |
| 1528 | 1552 | cap: 1, |
| 1529 | 1553 | 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"; | ||
| 11 | 11 | import { createIssue } from "../src/core/issues.ts"; |
| 12 | 12 | import { createUser, type User } from "../src/core/users.ts"; |
| 13 | 13 | 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"; | |
| 15 | 16 | import type { TuiIdentity } from "../src/tui/session.ts"; |
| 16 | 17 | import { headlessTerminal } from "../src/tui/term/terminal.ts"; |
| 17 | 18 | import { roadmapOf } from "../src/web/roadmap.ts"; |
| @@ -33,6 +34,8 @@ describe("roadmap in the terminal", () => { | ||
| 33 | 34 | app.start(); |
| 34 | 35 | const key = (k: string) => app.dispatch({ type: "key", key: k, ctrl: false, alt: false, shift: false }); |
| 35 | 36 | return { |
| 37 | app, | |
| 38 | key, | |
| 36 | 39 | text: () => app.screen.toText(), |
| 37 | 40 | async open(spec: string) { |
| 38 | 41 | await settleApp(app); |
| @@ -97,6 +100,28 @@ describe("roadmap in the terminal", () => { | ||
| 97 | 100 | t.stop(); |
| 98 | 101 | }); |
| 99 | 102 | |
| 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 | ||
| 100 | 125 | test("lines come from the model", () => { |
| 101 | 126 | const repo = getRepo(forge.db, "ada", "road")!; |
| 102 | 127 | const lines = roadmapLines(roadmapOf(forge.db, repo, ada)!, 80); |
new above
offline
Spoofable: any title shaped like
P9 x: ycounts as a pillar. Use pillarsOf's writer check and test a spoof.