Public: anyone can read this; the crew can change it.
A wave's page says how close it is to done: closed of total changes in one sentence and one bar, server-rendered #13450
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13425-a-wave-s-page-says-how-close-it-is-to-do → main 7 commits fork 3 threads · 3 unresolved
7 files
changed +139
−4
docs/features/README.md +1
| @@ -161,6 +161,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md). | ||
| 161 | 161 | - [](wave-walk.md) |
| 162 | 162 | - [](wave-standing.md) |
| 163 | 163 | - [](wave-landing.md) |
| 164 | - [](wave-landed.md) | |
| 164 | 165 | - [](wave-empty.md) |
| 165 | 166 | - [](ask-status.md) |
| 166 | 167 | - [](blocked-by.md) |
docs/features/wave-landed.md added +11
| @@ -0,0 +1,11 @@ | ||
| 1 | # How close a wave is to done | |
| 2 | ||
| 3 | A wave's page, the MCP wave tool and the terminal's wave screen say how many of the wave's changes landed, in one sentence: `2 of 5 changes landed.` The sentence sits on the version line; the page adds one bar under that line. | |
| 4 | ||
| 5 | - **Landed** counts the wave's pulls that merged; the total is every pull of the wave the reader may see. A pull the reader cannot read is in neither number. | |
| 6 | - A wave with no visible change says `This wave has no changes yet.` and draws no bar. | |
| 7 | - One change reads `1 of 1 change landed.` | |
| 8 | ||
| 9 | Try it: open `/trevato/forge/waves/<version>`, or the waves screen in the terminal, and read the sentence on the version line under the headline. | |
| 10 | ||
| 11 | All doors build the sentence with `landedSentence` in `src/story/words.ts`, so they say the same words. |
src/http/mcp/tools/waves.ts +3
| @@ -2,6 +2,8 @@ import { pullRefs, readWave, readWaves } from "../../../story/waves.ts"; | ||
| 2 | 2 | import { VERSION as WAVE_VERSION } from "../../../story/wave.ts"; |
| 3 | 3 | import { repoDir } from "../../../git/repos.ts"; |
| 4 | 4 | import { movedForViewer, waveProgress } from "../../../story/wave_moved.ts"; |
| 5 | import { carriedPulls } from "../../../story/wave_pulls.ts"; | |
| 6 | import { landedSentence } from "../../../story/words.ts"; | |
| 5 | 7 | import { planNow } from "../../../story/wave_plan.ts"; |
| 6 | 8 | import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"; |
| 7 | 9 | |
| @@ -47,6 +49,7 @@ export const tool: Tool = { | ||
| 47 | 49 | version: w.version, |
| 48 | 50 | date: w.date, |
| 49 | 51 | headline: w.headline, |
| 52 | landed: landedSentence(carriedPulls(ctx.app.db, pullRefs(w), user)), | |
| 50 | 53 | ...(progress === "" ? {} : { progress }), |
| 51 | 54 | highlights: w.highlights, |
| 52 | 55 | pulls: w.pulls.flatMap((p) => { |
src/story/words.ts +16
| @@ -60,3 +60,19 @@ export function waveSentence(titles: readonly string[], cap = WAVE_SENTENCE_CAP) | ||
| 60 | 60 | const room = cap - lead.length - 1; |
| 61 | 61 | return `${lead}${text.length > room ? `${text.slice(0, room - 1).trimEnd()}…` : text}.`; |
| 62 | 62 | } |
| 63 | ||
| 64 | /** Said when a wave carries no change the viewer can see. */ | |
| 65 | export const WAVE_NO_CHANGES = "This wave has no changes yet."; | |
| 66 | ||
| 67 | /** | |
| 68 | * How close a wave is to done, in one sentence: "2 of 5 changes landed." Every door says it alike. | |
| 69 | */ | |
| 70 | export function waveLanded(landed: number, total: number): string { | |
| 71 | if (total <= 0) return WAVE_NO_CHANGES; | |
| 72 | return `${landed} of ${total} ${total === 1 ? "change" : "changes"} landed.`; | |
| 73 | } | |
| 74 | ||
| 75 | /** How close a wave is to done, said from the pulls the viewer may see: merged ones landed. */ | |
| 76 | export function landedSentence(pulls: readonly { mergedAt: string | null }[]): string { | |
| 77 | return waveLanded(pulls.filter((p) => p.mergedAt !== null).length, pulls.length); | |
| 78 | } |
src/tui/screens/waves.ts +2 −2
| @@ -16,7 +16,7 @@ import { repoBase } from "../../web/chrome.ts"; | ||
| 16 | 16 | import { waitingKeys } from "../../release/landings.ts"; |
| 17 | 17 | import { carriedPulls, pullPath, type CarriedPull } from "../../story/wave_pulls.ts"; |
| 18 | 18 | import { pullRefs, readWave, readWaves, sizeWords, waveLine, waveSize, type WaveEntry } from "../../story/waves.ts"; |
| 19 | import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, waveSentence } from "../../story/words.ts"; | |
| 19 | import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, landedSentence, waveSentence } from "../../story/words.ts"; | |
| 20 | 20 | import type { RepoSource } from "../../view/source.ts"; |
| 21 | 21 | import type { Ctx, Screen } from "../app/app.ts"; |
| 22 | 22 | import { binding } from "../app/keys.ts"; |
| @@ -73,7 +73,7 @@ export function waveLines( | ||
| 73 | 73 | plain(w.headline), |
| 74 | 74 | plain(waveSentence(pulls.filter((p) => p.mergedAt !== null).map((p) => p.title))), |
| 75 | 75 | // Sized over `pulls`, the ones this viewer may see, as the page's header is. |
| 76 | `${plain(w.version)} ${plain(w.date)} ${sizeWords(waveSize(pulls))}${standing === "" ? "" : ` ${plain(standing)}`}`, | |
| 76 | `${plain(w.version)} ${plain(w.date)} ${sizeWords(waveSize(pulls))} ${landedSentence(pulls)}${standing === "" ? "" : ` ${plain(standing)}`}`, | |
| 77 | 77 | ...(moved.length === 0 ? [] : [plain(waveProgress(moved))]), |
| 78 | 78 | "", |
| 79 | 79 | "Highlights", |
src/web/pages/waves.ts +7 −2
| @@ -19,7 +19,7 @@ import { VERSION, type Wave } from "../../story/wave.ts"; | ||
| 19 | 19 | import { movedWithPulls, type MovedMilestone, shippedOf, shippedWords, waveProgress, widestMoved } from "../../story/wave_moved.ts"; |
| 20 | 20 | import { carriedPulls, pullPath } from "../../story/wave_pulls.ts"; |
| 21 | 21 | import { fromWave, pullRefs, readWave, readWaves, sizeWords, waveSize } from "../../story/waves.ts"; |
| 22 | import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, waveSentence } from "../../story/words.ts"; | |
| 22 | import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, landedSentence, waveSentence } from "../../story/words.ts"; | |
| 23 | 23 | import { loadRepo, notFoundPage, repoBase, scopeHeader } from "../chrome.ts"; |
| 24 | 24 | import { escapeHtml, html, type Html } from "../html.ts"; |
| 25 | 25 | import { page } from "../layout.ts"; |
| @@ -237,10 +237,15 @@ export async function wavePage(ctx: Ctx): Promise<Response> { | ||
| 237 | 237 | ) |
| 238 | 238 | : ""; |
| 239 | 239 | |
| 240 | /** | |
| 241 | * The bar under the version line, named differently from the sentence beside it; none when empty. | |
| 242 | */ | |
| 243 | const landed = carried.length === 0 ? "" : progress(carried.filter((p) => p.mergedAt !== null).length, carried.length, "Share landed"); | |
| 240 | 244 | const content = entry.ok |
| 241 | 245 | ? html`<h1>${entry.wave.headline}</h1> |
| 242 | 246 | <p data-wave-sentence>${waveSentence(carried.filter((p) => p.mergedAt !== null).map((p) => p.title))}</p> |
| 243 | <p class="muted">${entry.wave.version} · ${entry.wave.date} · <span data-wave-size>${sizeWords(waveSize(carried))}</span> · <span data-wave-standing>${standing}</span></p> | |
| 247 | <p class="muted">${entry.wave.version} · ${entry.wave.date} · <span data-wave-size>${sizeWords(waveSize(carried))}</span> · <span data-wave-landed>${landedSentence(carried)}</span> · <span data-wave-standing>${standing}</span></p> | |
| 248 | ${landed} | |
| 244 | 249 | ${waveProgressRow(moved)} |
outdated
Principle 1: the sentence and the bar's label are the same words, so the page says it twice. Also three sentence lines now stack above the version line. Keep one. |
||
| 245 | 250 | <h2>Highlights</h2> |
| 246 | 251 | <ul> |
test/wave-landed.test.ts added +99
| @@ -0,0 +1,99 @@ | ||
| 1 | /** | |
| 2 | * A wave says how close it is to done: one sentence on the line under the headline, one bar | |
| 3 | * (#13425). | |
| 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 { createSession } from "../src/core/sessions.ts"; | |
| 12 | import { createToken } from "../src/core/tokens.ts"; | |
| 13 | import { createUser } from "../src/core/users.ts"; | |
| 14 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 15 | import { landedSentence, WAVE_NO_CHANGES } from "../src/story/words.ts"; | |
| 16 | import type { CarriedPull } from "../src/story/wave_pulls.ts"; | |
| 17 | import type { WaveEntry } from "../src/story/waves.ts"; | |
| 18 | import { waveLines } from "../src/tui/screens/waves.ts"; | |
| 19 | import { quietLogs } from "./helpers/globals.ts"; | |
| 20 | import { mergedPull, waveNaming } from "./helpers/wave-pulls.ts"; | |
| 21 | ||
| 22 | quietLogs(); | |
outdated
No test for the web page (sentence, bar value/max, no bar when empty) or the MCP |
||
| 23 | ||
| 24 | const pull = (n: number, mergedAt: string | null): CarriedPull => ({ owner: "o", name: "r", number: n, title: `P${n}`, mergedAt, state: mergedAt ? "closed" : "open" }); | |
| 25 | ||
| 26 | test("the sentence for 0, partial and complete waves", () => { | |
| 27 | expect(landedSentence([])).toBe(WAVE_NO_CHANGES); | |
| 28 | expect(landedSentence([pull(1, "2026-01-01"), pull(2, null), pull(3, null)])).toBe("1 of 3 changes landed."); | |
| 29 | expect(landedSentence([pull(1, "2026-01-01")])).toBe("1 of 1 change landed."); | |
| 30 | expect(landedSentence([pull(1, "x"), pull(2, "y")])).toBe("2 of 2 changes landed."); | |
| 31 | }); | |
| 32 | ||
| 33 | test("the terminal wave screen carries the same sentence, on the version line", () => { | |
| 34 | const entry: WaveEntry = { ok: true, file: "1.0.0.md", wave: { version: "1.0.0", date: "2026-01-01", headline: "H", highlights: [], pulls: [] } }; | |
| 35 | expect(waveLines(entry, [pull(1, "x"), pull(2, null)])[2]).toContain("1 of 2 changes landed."); | |
| 36 | expect(waveLines(entry, [])[2]).toContain(WAVE_NO_CHANGES); | |
| 37 | }); | |
| 38 | ||
| 39 | let dataDir = ""; | |
| 40 | let app: App; | |
| 41 | let servers: Servers; | |
| 42 | let cookie = ""; | |
| 43 | let token = ""; | |
| 44 | ||
| 45 | beforeAll(async () => { | |
| 46 | dataDir = await mkdtemp(join(tmpdir(), "forge-wave-landed-")); | |
| 47 | app = createApp({ dataDir, port: 0 }); | |
| 48 | servers = await serve(app); | |
| 49 | const u = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 50 | if (!u.ok) throw new Error(String(u.error)); | |
| 51 | cookie = `forge_session=${createSession(app.db, u.value.id).token}; forge_mode=dev`; | |
| 52 | token = createToken(app.db, u.value.id, "ro", "ro").token; | |
| 53 | const made = await createRepo(app, u.value, { name: "plan", visibility: "public" }); | |
| 54 | if (!made.ok) throw new Error(String(made.error)); | |
| 55 | const repo = made.value; | |
| 56 | const init = await commitToBranch(app, u.value, repo, { message: "init", files: [{ path: "README.md", content: "hi\n" }] }); | |
| 57 | if (!init.ok) throw new Error(JSON.stringify(init.error)); | |
| 58 | const one = await mergedPull(app, u.value, repo, "Done work"); | |
| 59 | const two = await mergedPull(app, u.value, repo, "More work"); | |
| 60 | app.db.query("UPDATE pull SET merged_at = NULL WHERE issue_id = (SELECT id FROM issue WHERE repo_id = ? AND number = ?)").run(repo.id, two); | |
| 61 | const ref = (number: number) => ({ owner: "alice", name: "plan", number }); | |
| 62 | const c = await commitToBranch(app, u.value, repo, { | |
| 63 | message: "waves", | |
| 64 | files: [ | |
| 65 | { path: "waves/0.1.0.md", content: waveNaming("0.1.0", [ref(one), ref(two)]) }, | |
| 66 | { path: "waves/0.2.0.md", content: waveNaming("0.2.0", []) }, | |
| 67 | ], | |
| 68 | }); | |
| 69 | if (!c.ok) throw new Error(JSON.stringify(c.error)); | |
| 70 | }, 60_000); | |
| 71 | ||
| 72 | afterAll(async () => { | |
| 73 | servers?.stop(); | |
| 74 | app?.close(); | |
| 75 | await rm(dataDir, { recursive: true, force: true }); | |
| 76 | }); | |
| 77 | ||
| 78 | test("the wave page says N of M once and draws one bar with that value and max", async () => { | |
| 79 | const text = await (await fetch(`${servers.url}/alice/plan/waves/0.1.0`, { headers: { cookie } })).text(); | |
| 80 | expect(text).toContain("<span data-wave-landed>1 of 2 changes landed.</span>"); | |
| 81 | expect(text.split("1 of 2 changes landed.").length).toBe(2); | |
| 82 | expect(text).toMatch(/<progress\s+max="2"\s+value="1"/); | |
| 83 | }); | |
| 84 | ||
| 85 | test("a wave with no changes says so and draws no bar", async () => { | |
| 86 | const text = await (await fetch(`${servers.url}/alice/plan/waves/0.2.0`, { headers: { cookie } })).text(); | |
| 87 | expect(text).toContain(`<span data-wave-landed>${WAVE_NO_CHANGES}</span>`); | |
| 88 | expect(text).not.toContain("<progress"); | |
| 89 | }); | |
| 90 | ||
| 91 | test("the MCP wave answer carries landed", async () => { | |
| 92 | const res = await fetch(`${servers.url}/mcp`, { | |
| 93 | method: "POST", | |
| 94 | headers: { "content-type": "application/json", accept: "application/json, text/event-stream", authorization: `Bearer ${token}` }, | |
| 95 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "waves", arguments: { repo: "alice/plan", version: "0.1.0" } } }), | |
| 96 | }); | |
| 97 | const body = (await res.json()) as any; | |
| 98 | expect(JSON.parse(body.result.content[0].text).wave.landed).toBe("1 of 2 changes landed."); | |
| 99 | }); |
new above
offline
Hard-to-read IIFE; add a helper in words.ts taking the pulls. Also box 3 names the changelog, not this screen.