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

Merged opened this

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

Merged

scout/forge:scout/13136-a-wave-s-page-says-how-many-changes-it-h → main 6 commits fork 2 threads · 2 unresolved

  • Merged. scout/13136-a-wave-s-page-says-how-many-changes-it-h was merged into main as e6255ff.

Review

Sign in to review this change.
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).
140140 - [The week is one budget for the whole crew](crew-week.md)
141141 - [The week's pace](week-pace.md)
142142 - [Walking a wave](wave-walk.md)
143 - [The wave-standing line](wave-standing.md)
143144 - [What became of the first ask](ask-status.md)
144145 - [When a setting or a permission stands in the way](blocked-by.md)
145146 - [The map's growth line](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 @@
77
88 import { cutWaveFor, planCutFor } from "../../actions/cut_wave.ts";
99 import { canRead, getRepo } from "../../core/repos.ts";
10 import { nearMilestones, standingLine } from "../../web/pages/milestones_near.ts";
1011 import { VERSION } from "../../story/wave.ts";
1112 import { movedWithPulls, waveProgress, type MovedMilestone } from "../../story/wave_moved.ts";
1213 import { milestonePath, planNow } from "../../story/wave_plan.ts";
@@ -26,7 +27,10 @@ import { ListState, Scroll, confirmScreen, drawList, drawLines, hitList, plural,
2627 import { pullScreen } from "./pull.ts";
2728 import { local, localRepo, sourceName, whereRows, whereStrip } from "./where.ts";
2829
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 */
3034 export function waveRows(entries: WaveEntry[], sizeOf: (e: WaveEntry & { ok: true }) => { pulls: number; apps: number }) {
3135 return entries.map((e) =>
3236 e.ok
@@ -47,13 +51,18 @@ const plain = (s: string): string =>
4751 /** A moved milestone with the path that opens it. */
4852 export type MovedLine = MovedMilestone & { path: string; pulls?: number[] };
4953
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 */
5158 export function waveLines(
5259 entry: WaveEntry,
5360 pulls: CarriedPull[],
5461 moved: MovedLine[] = [],
5562 /** Which pull the cursor is on, marked with `>`; none when null. */
5663 picked: number | null = null,
64 /** The standing line, as the page's trail says it; none when empty. */
65 standing = "",
5766 ): string[] {
5867 if (!entry.ok) return [plain(entry.file), "", `Not a wave: ${plain(entry.reason)}`];
5968 const w = entry.wave;
@@ -61,7 +70,7 @@ export function waveLines(
6170 plain(w.headline),
6271 plain(waveSentence(pulls.filter((p) => p.mergedAt !== null).map((p) => p.title))),
6372 // 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)}`}`,
6574 ...(moved.length === 0 ? [] : [plain(waveProgress(moved))]),
6675 "",
6776 "Highlights",
@@ -98,16 +107,18 @@ function waveScreen(
98107 pulls: CarriedPull[],
99108 moved: MovedLine[],
100109 src: RepoSource,
110 standing = "",
101111 ): Screen {
102112 const scroll = new Scroll();
103113 let picked = 0;
104114 /** 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);
106116 const open = (): void => {
107117 const p = pulls[picked];
108118 if (p === undefined) return;
109119 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.
111122 const repo =
112123 here !== undefined && here.ownerName === p.owner && here.name === p.name
113124 ? here
@@ -187,7 +198,14 @@ export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen {
187198 plan: () => planNow(f.db, repo, new Date()),
188199 }).map((m) => ({ ...m, path: milestonePath(repoBase(repo), m.number) }))
189200 : [];
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));
191209 });
192210 };
193211
src/web/pages/milestones_near.ts +32 −1
@@ -13,7 +13,10 @@ import { planFor } from "./milestones.ts";
1313 /** One open milestone's line: its number, name and how far it is. */
1414 export type Near = { number: number; name: string; done: number; total: number };
1515
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 */
1720 export function nearMilestones(app: App, slug: string | undefined, user: User | undefined): { repo: Repo; near: Near[] } | undefined {
1821 const [owner = "", name = ""] = (slug ?? "").split("/");
1922 if (owner === "" || name === "") return undefined;
@@ -27,3 +30,31 @@ export function nearMilestones(app: App, slug: string | undefined, user: User |
2730
2831 /** One line of words for a milestone, as the trail says it. */
2932 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 {
outdated

Compute remaining once per milestone; the repeated Math.max is hard to read. Add a test for the tie and for done>total.

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";
2424 import { btn, empty, listCard, row } from "../ui.ts";
2525 import { localScope } from "../scope.ts";
2626 import { milestoneHref, planFor } from "./milestones.ts";
27 import { nearMilestones, standingLine } from "./milestones_near.ts";
2728
2829 /**
2930 * 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; }
3738 const WHAT_A_WAVE =
3839 "A wave is a release note in waves/<version>.md that names its highlights and the pulls merged since the last one.";
3940
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 */
4145 export function waveRow(w: Wave, href: string, size: { pulls: number; apps: number }) {
4246 const why = w.highlights[0]?.why;
4347 return row({
@@ -224,11 +228,18 @@ export async function wavePage(ctx: Ctx): Promise<Response> {
224228 const folded = new Set(moved.flatMap((m) => m.pulls));
225229 const unfolded = carried.filter((p) => !(p.owner === repo.ownerName && p.name === repo.name && folded.has(p.number)));
226230 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 : "";
227238
228239 const content = entry.ok
229240 ? html`<h1>${entry.wave.headline}</h1>
230241 <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>
232243 ${line === ""
233244 ? ""
234245 : html`<p class="muted" data-wave-progress>${line}</p>`}
test/tui-waves.test.ts +9
@@ -272,6 +272,15 @@ describe("waves in the terminal", () => {
272272 expect(waveLines(entry, [])[1]).toBe("No pull in this wave has landed yet.");
273273 });
274274
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
275284 test("wave text carries no escape or control characters", () => {
276285 const lines = waveLines(
277286 {
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 &lt;it&gt; 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs