Public: anyone can read this; the crew can change it.
A wave's page says how many changes it holds and how far the next milestone is, in one line #13170
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13136-a-wave-s-page-says-how-many-changes-it-h → main 6 commits fork 2 threads · 2 unresolved
7 files
changed +184
−9
docs/features/README.md +1
| @@ -140,6 +140,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md). | ||
| 140 | 140 | - [](crew-week.md) |
| 141 | 141 | - [](week-pace.md) |
| 142 | 142 | - [](wave-walk.md) |
| 143 | - [](wave-standing.md) | |
| 143 | 144 | - [](ask-status.md) |
| 144 | 145 | - [](blocked-by.md) |
| 145 | 146 | - [](map-growth.md) |
docs/features/wave-standing.md added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | # The wave-standing line | |
| 2 | ||
| 3 | A wave's page and the terminal's wave screen say, in the trail under the headline, how many changes the wave holds and how far the nearest open milestone is: `3 changes · milestone Ship it is 2 away`. | |
| 4 | ||
| 5 | - **Changes** are the wave's pulls that have merged and that the reader may see. A pull the reader cannot read is not counted, as in the size words beside it. | |
| 6 | - **The nearest milestone** is the open, not deferred milestone of the repository with the fewest issues left. When two are equally far, the lowest number wins. A milestone with more done than total counts as 0 away. | |
| 7 | - With no open milestone the line says only the changes; nothing is invented. | |
| 8 | - A reader who may not open the repository sees no milestone. | |
| 9 | ||
| 10 | Both doors build the line with `standingLine` in `src/web/pages/milestones_near.ts`, so they say the same words. |
src/tui/screens/waves.ts +24 −6
| @@ -7,6 +7,7 @@ | ||
| 7 | 7 | |
| 8 | 8 | import { cutWaveFor, planCutFor } from "../../actions/cut_wave.ts"; |
| 9 | 9 | import { canRead, getRepo } from "../../core/repos.ts"; |
| 10 | import { nearMilestones, standingLine } from "../../web/pages/milestones_near.ts"; | |
| 10 | 11 | import { VERSION } from "../../story/wave.ts"; |
| 11 | 12 | import { movedWithPulls, waveProgress, type MovedMilestone } from "../../story/wave_moved.ts"; |
| 12 | 13 | import { milestonePath, planNow } from "../../story/wave_plan.ts"; |
| @@ -26,7 +27,10 @@ import { ListState, Scroll, confirmScreen, drawList, drawLines, hitList, plural, | ||
| 26 | 27 | import { pullScreen } from "./pull.ts"; |
| 27 | 28 | import { local, localRepo, sourceName, whereRows, whereStrip } from "./where.ts"; |
| 28 | 29 | |
| 29 | /** One line per wave, as the screen draws it, sized as the page sizes it: `sizeOf` counts the pulls this viewer can see. */ | |
| 30 | /** | |
| 31 | * One line per wave, as the screen draws it, sized as the page sizes it: `sizeOf` counts the pulls | |
| 32 | * this viewer can see. | |
| 33 | */ | |
| 30 | 34 | export function waveRows(entries: WaveEntry[], sizeOf: (e: WaveEntry & { ok: true }) => { pulls: number; apps: number }) { |
| 31 | 35 | return entries.map((e) => |
| 32 | 36 | e.ok |
| @@ -47,13 +51,18 @@ const plain = (s: string): string => | ||
| 47 | 51 | /** A moved milestone with the path that opens it. */ |
| 48 | 52 | export type MovedLine = MovedMilestone & { path: string; pulls?: number[] }; |
| 49 | 53 | |
| 50 | /** One wave as lines of plain text: headline, version and date, highlights with why, then the pulls the viewer may see. */ | |
| 54 | /** | |
| 55 | * One wave as lines of plain text: headline, version and date, highlights with why, then the pulls | |
| 56 | * the viewer may see. | |
| 57 | */ | |
| 51 | 58 | export function waveLines( |
| 52 | 59 | entry: WaveEntry, |
| 53 | 60 | pulls: CarriedPull[], |
| 54 | 61 | moved: MovedLine[] = [], |
| 55 | 62 | /** Which pull the cursor is on, marked with `>`; none when null. */ |
| 56 | 63 | picked: number | null = null, |
| 64 | /** The standing line, as the page's trail says it; none when empty. */ | |
| 65 | standing = "", | |
| 57 | 66 | ): string[] { |
| 58 | 67 | if (!entry.ok) return [plain(entry.file), "", `Not a wave: ${plain(entry.reason)}`]; |
| 59 | 68 | const w = entry.wave; |
| @@ -61,7 +70,7 @@ export function waveLines( | ||
| 61 | 70 | plain(w.headline), |
| 62 | 71 | plain(waveSentence(pulls.filter((p) => p.mergedAt !== null).map((p) => p.title))), |
| 63 | 72 | // Sized over `pulls`, the ones this viewer may see, as the page's header is. |
| 64 | `${plain(w.version)} ${plain(w.date)} ${sizeWords(waveSize(pulls))}`, | |
| 73 | `${plain(w.version)} ${plain(w.date)} ${sizeWords(waveSize(pulls))}${standing === "" ? "" : ` ${plain(standing)}`}`, | |
| 65 | 74 | ...(moved.length === 0 ? [] : [plain(waveProgress(moved))]), |
| 66 | 75 | "", |
| 67 | 76 | "Highlights", |
| @@ -98,16 +107,18 @@ function waveScreen( | ||
| 98 | 107 | pulls: CarriedPull[], |
| 99 | 108 | moved: MovedLine[], |
| 100 | 109 | src: RepoSource, |
| 110 | standing = "", | |
| 101 | 111 | ): Screen { |
| 102 | 112 | const scroll = new Scroll(); |
| 103 | 113 | let picked = 0; |
| 104 | 114 | /** Where the wave's pulls start in the text, so the pick is scrolled into view. */ |
| 105 | const linesFor = (): string[] => waveLines(entry, pulls, moved, pulls.length === 0 ? null : picked); | |
| 115 | const linesFor = (): string[] => waveLines(entry, pulls, moved, pulls.length === 0 ? null : picked, standing); | |
| 106 | 116 | const open = (): void => { |
| 107 | 117 | const p = pulls[picked]; |
| 108 | 118 | if (p === undefined) return; |
| 109 | 119 | const here = localRepo(src); |
| 110 | // The pull's own repository, read again through the gate: a wave may name pulls of other repositories. | |
| 120 | // The pull's own repository, read again through the gate: a wave may name pulls of other | |
| 121 | // repositories. | |
| 111 | 122 | const repo = |
| 112 | 123 | here !== undefined && here.ownerName === p.owner && here.name === p.name |
| 113 | 124 | ? here |
| @@ -187,7 +198,14 @@ export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen { | ||
| 187 | 198 | plan: () => planNow(f.db, repo, new Date()), |
| 188 | 199 | }).map((m) => ({ ...m, path: milestonePath(repoBase(repo), m.number) })) |
| 189 | 200 | : []; |
| 190 | ctx.push(waveScreen(f, ctx, one, pulls, moved, src)); | |
| 201 | // The page's line, from the same function, over the same gated pulls and plan. | |
| 202 | const standing = one.ok | |
| 203 | ? standingLine( | |
| 204 | pulls.filter((p) => p.mergedAt !== null).length, | |
| 205 | nearMilestones(f.app, `${repo.ownerName}/${repo.name}`, f.user)?.near ?? [], | |
| 206 | ) | |
| 207 | : ""; | |
| 208 | ctx.push(waveScreen(f, ctx, one, pulls, moved, src, standing)); | |
| 191 | 209 | }); |
| 192 | 210 | }; |
| 193 | 211 |
src/web/pages/milestones_near.ts +32 −1
| @@ -13,7 +13,10 @@ import { planFor } from "./milestones.ts"; | ||
| 13 | 13 | /** One open milestone's line: its number, name and how far it is. */ |
| 14 | 14 | export type Near = { number: number; name: string; done: number; total: number }; |
| 15 | 15 | |
| 16 | /** The open milestones of `slug` ("owner/name"), for `user` (undefined is a guest), with the repository read for them. */ | |
| 16 | /** | |
| 17 | * The open milestones of `slug` ("owner/name"), for `user` (undefined is a guest), with the | |
| 18 | * repository read for them. | |
| 19 | */ | |
| 17 | 20 | export function nearMilestones(app: App, slug: string | undefined, user: User | undefined): { repo: Repo; near: Near[] } | undefined { |
| 18 | 21 | const [owner = "", name = ""] = (slug ?? "").split("/"); |
| 19 | 22 | if (owner === "" || name === "") return undefined; |
| @@ -27,3 +30,31 @@ export function nearMilestones(app: App, slug: string | undefined, user: User | | ||
| 27 | 30 | |
| 28 | 31 | /** One line of words for a milestone, as the trail says it. */ |
| 29 | 32 | export const nearWords = (m: Near): string => `${m.done} of ${m.total} done`; |
| 33 | ||
| 34 | /** Issues a milestone has left; more done than total leaves none. */ | |
| 35 | const remaining = (m: Near): number => Math.max(0, m.total - m.done); | |
| 36 | ||
| 37 | /** The open milestone with the fewest issues left (the lowest number on a tie), or none. */ | |
| 38 | export function closestMilestone(near: readonly Near[]): Near | undefined { | |
| 39 | let best: Near | undefined; | |
| 40 | let bestLeft = 0; | |
| 41 | for (const m of near) { | |
| 42 | const left = remaining(m); | |
| 43 | if (best === undefined || left < bestLeft || (left === bestLeft && m.number < best.number)) { | |
| 44 | best = m; | |
| 45 | bestLeft = left; | |
| 46 | } | |
| 47 | } | |
| 48 | return best; | |
| 49 | } | |
| 50 | ||
| 51 | /** | |
| 52 | * A wave's standing line: `3 changes · milestone Ship it is 2 away`. With no | |
| 53 | * open milestone it says only the changes; nothing is invented. Markup is left | |
| 54 | * for the page to escape. | |
| 55 | */ | |
| 56 | export function standingLine(changes: number, near: readonly Near[]): string { | |
| 57 | const head = `${changes} ${changes === 1 ? "change" : "changes"}`; | |
| 58 | const m = closestMilestone(near); | |
| 59 | return m === undefined ? head : `${head} · milestone ${m.name} is ${remaining(m)} away`; | |
| 60 | } |
src/web/pages/waves.ts +13 −2
| @@ -24,6 +24,7 @@ import { page } from "../layout.ts"; | ||
| 24 | 24 | import { btn, empty, listCard, row } from "../ui.ts"; |
| 25 | 25 | import { localScope } from "../scope.ts"; |
| 26 | 26 | import { milestoneHref, planFor } from "./milestones.ts"; |
| 27 | import { nearMilestones, standingLine } from "./milestones_near.ts"; | |
| 27 | 28 | |
| 28 | 29 | /** |
| 29 | 30 | * A wave's headline is the writer's words, so a row lets it wrap (a long word |
| @@ -37,7 +38,10 @@ export const WAVES_CSS = `[data-waves] { overflow-wrap: anywhere; } | ||
| 37 | 38 | const WHAT_A_WAVE = |
| 38 | 39 | "A wave is a release note in waves/<version>.md that names its highlights and the pulls merged since the last one."; |
| 39 | 40 | |
| 40 | /** One wave on the list: its headline, the first highlight's why as the one sentence under it, and version, date and pull count as a muted trail. */ | |
| 41 | /** | |
| 42 | * One wave on the list: its headline, the first highlight's why as the one sentence under it, and | |
| 43 | * version, date and pull count as a muted trail. | |
| 44 | */ | |
| 41 | 45 | export function waveRow(w: Wave, href: string, size: { pulls: number; apps: number }) { |
| 42 | 46 | const why = w.highlights[0]?.why; |
| 43 | 47 | return row({ |
| @@ -224,11 +228,18 @@ export async function wavePage(ctx: Ctx): Promise<Response> { | ||
| 224 | 228 | const folded = new Set(moved.flatMap((m) => m.pulls)); |
| 225 | 229 | const unfolded = carried.filter((p) => !(p.owner === repo.ownerName && p.name === repo.name && folded.has(p.number))); |
| 226 | 230 | const line = waveProgress(moved); |
| 231 | // The stored plan, read through the same cache the milestones page uses. | |
| 232 | const standing = entry.ok | |
| 233 | ? standingLine( | |
| 234 | carried.filter((p) => p.mergedAt !== null).length, | |
| 235 | nearMilestones(ctx.app, `${repo.ownerName}/${repo.name}`, ctx.auth.user)?.near ?? [], | |
| 236 | ) | |
| 237 | : ""; | |
| 227 | 238 | |
| 228 | 239 | const content = entry.ok |
| 229 | 240 | ? html`<h1>${entry.wave.headline}</h1> |
| 230 | 241 | <p data-wave-sentence>${waveSentence(carried.filter((p) => p.mergedAt !== null).map((p) => p.title))}</p> |
outdated
Principle 1: the muted line leads above the h1. Move it under the headline, with the trail. Also the terminal wave screen must show the same line. |
||
| 231 | <p class="muted">${entry.wave.version} · ${entry.wave.date} · <span data-wave-size>${sizeWords(waveSize(carried))}</span></p> | |
| 242 | <p class="muted">${entry.wave.version} · ${entry.wave.date} · <span data-wave-size>${sizeWords(waveSize(carried))}</span> · <span data-wave-standing>${standing}</span></p> | |
| 232 | 243 | ${line === "" |
| 233 | 244 | ? "" |
| 234 | 245 | : html`<p class="muted" data-wave-progress>${line}</p>`} |
test/tui-waves.test.ts +9
| @@ -272,6 +272,15 @@ describe("waves in the terminal", () => { | ||
| 272 | 272 | expect(waveLines(entry, [])[1]).toBe("No pull in this wave has landed yet."); |
| 273 | 273 | }); |
| 274 | 274 | |
| 275 | test("the trail carries the page's standing line, after the size", () => { | |
| 276 | const entry = { ok: true as const, file: "1.0.0.md", wave: { version: "1.0.0", date: "2026-01-01", headline: "Head", highlights: [], pulls: [] } }; | |
| 277 | const trail = (standing?: string) => waveLines(entry, [], [], null, standing)[2]!; | |
| 278 | expect(trail("2 changes · milestone Ship is 1 away")).toEndWith(" 2 changes · milestone Ship is 1 away"); | |
| 279 | expect(trail("x\u001b[2Jy")).not.toContain("\u001b"); | |
| 280 | expect(trail()).toBe(trail("")); | |
| 281 | expect(trail()).not.toContain("milestone"); | |
| 282 | }); | |
| 283 | ||
| 275 | 284 | test("wave text carries no escape or control characters", () => { |
| 276 | 285 | const lines = waveLines( |
| 277 | 286 | { |
test/wave-standing.test.ts added +95
| @@ -0,0 +1,95 @@ | ||
| 1 | /** | |
| 2 | * A wave's page opens with one line: how many changes it holds and how far the nearest | |
| 3 | * milestone is (#13136). | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { commitToBranch, createRepo } from "../src/actions/repos.ts"; | |
| 10 | import { createApp, type App } from "../src/app.ts"; | |
| 11 | import { getRepo } from "../src/core/repos.ts"; | |
| 12 | import { createUser } from "../src/core/users.ts"; | |
| 13 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 14 | import { closestMilestone, standingLine } from "../src/web/pages/milestones_near.ts"; | |
| 15 | import { mergedPull, waveNaming } from "./helpers/wave-pulls.ts"; | |
| 16 | ||
| 17 | test("the line counts changes and names the nearest milestone", () => { | |
| 18 | const near = [ | |
| 19 | { number: 5, name: "Far", done: 1, total: 9 }, | |
| 20 | { number: 6, name: "Close", done: 3, total: 4 }, | |
| 21 | ]; | |
| 22 | expect(standingLine(3, near)).toBe("3 changes · milestone Close is 1 away"); | |
| 23 | expect(standingLine(1, near)).toBe("1 change · milestone Close is 1 away"); | |
| 24 | }); | |
| 25 | test("the closest milestone: a tie goes to the lowest number, and done past total is 0 away", () => { | |
| 26 | const tie = [ | |
| 27 | { number: 9, name: "Nine", done: 1, total: 3 }, | |
| 28 | { number: 4, name: "Four", done: 2, total: 4 }, | |
| 29 | { number: 7, name: "Seven", done: 0, total: 2 }, | |
| 30 | ]; | |
| 31 | expect(closestMilestone(tie)?.name).toBe("Four"); | |
| 32 | const over = [ | |
| 33 | { number: 2, name: "Two", done: 1, total: 2 }, | |
| 34 | { number: 3, name: "Over", done: 5, total: 3 }, | |
| 35 | ]; | |
| 36 | expect(closestMilestone(over)?.name).toBe("Over"); | |
| 37 | expect(standingLine(2, over)).toBe("2 changes · milestone Over is 0 away"); | |
| 38 | expect(closestMilestone([])).toBeUndefined(); | |
| 39 | }); | |
| 40 | test("with no open milestone nothing is invented", () => { | |
| 41 | expect(standingLine(2, [])).toBe("2 changes"); | |
| 42 | }); | |
| 43 | ||
| 44 | let dir: string; | |
| 45 | let app: App; | |
| 46 | let servers: Servers; | |
| 47 | const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => { | |
| 48 | if (!r.ok) throw new Error(JSON.stringify(r.error)); | |
| 49 | return r.value; | |
| 50 | }; | |
| 51 | const page = async () => await (await fetch(`${servers.url}/alice/pub/waves/0.1.0`)).text(); | |
| 52 | ||
| 53 | beforeAll(async () => { | |
| 54 | dir = await mkdtemp(join(tmpdir(), "forge-wave-standing-")); | |
| 55 | app = createApp({ dataDir: dir, port: 0 }); | |
| 56 | servers = await serve(app); | |
| 57 | const alice = must(await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true })); | |
| 58 | const repo = must(await createRepo(app, alice, { name: "pub", visibility: "public" })); | |
| 59 | must(await commitToBranch(app, alice, repo, { message: "init", files: [{ path: "README.md", content: "hi\n" }] })); | |
| 60 | const n = await mergedPull(app, alice, repo, "Shown work"); | |
| 61 | must(await commitToBranch(app, alice, repo, { message: "wave", files: [{ path: "waves/0.1.0.md", content: waveNaming("0.1.0", [{ owner: "alice", name: "pub", number: n }]) }] })); | |
| 62 | }, 60_000); | |
| 63 | afterAll(async () => { | |
| 64 | servers.stop(); | |
| 65 | app.close(); | |
| 66 | await rm(dir, { recursive: true, force: true }); | |
| 67 | }); | |
| 68 | ||
| 69 | test("with no milestone open the first HTML says only the changes", async () => { | |
| 70 | const body = await page(); | |
| 71 | expect(body).toContain("<span data-wave-standing>1 change</span>"); | |
| 72 | expect(body).not.toContain("is 0 away"); | |
| 73 | }); | |
| 74 | ||
| 75 | test("with a milestone open the first HTML says how far it is", async () => { | |
| 76 | const repoId = getRepo(app.db, "alice", "pub")!.id; | |
| 77 | const author = app.db.query("SELECT id FROM user LIMIT 1").get() as { id: string }; | |
| 78 | const at = new Date(Date.now() - 3_600_000).toISOString(); | |
| 79 | let k = 100; | |
| 80 | const add = (title: string, state: string) => { | |
| 81 | const id = `m${++k}`; | |
| 82 | app.db.run( | |
| 83 | "INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state, created_at, updated_at, closed_at) VALUES (?1, ?2, ?3, 'issue', ?4, '', ?5, ?6, ?7, ?7, ?8)", | |
| 84 | [id, repoId, k, title, author.id, state, at, state === "open" ? null : at], | |
| 85 | ); | |
| 86 | return id; | |
| 87 | }; | |
| 88 | const umbrella = add("Ship <it>", "open"); | |
| 89 | app.db.run("INSERT INTO issue_dependency (issue_id, blocked_by_id) VALUES (?1, ?2)", [umbrella, add("done one", "closed")]); | |
| 90 | app.db.run("INSERT INTO issue_dependency (issue_id, blocked_by_id) VALUES (?1, ?2)", [umbrella, add("open one", "open")]); | |
| 91 | const body = await page(); | |
| 92 | expect(body).toContain("1 change · milestone Ship <it> is 1 away"); | |
| 93 | // Headline first: the line sits in the trail below it. | |
| 94 | expect(body.indexOf("<h1>")).toBeLessThan(body.indexOf("data-wave-standing")); | |
| 95 | }); |
new above
offline
Compute remaining once per milestone; the repeated Math.max is hard to read. Add a test for the tie and for done>total.