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

A wave's page lists each landed pull with its title, who merged it and when, in the order they landed #13574

Merged opened this

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

Merged

mason/forge:mason/13488-a-wave-s-page-lists-each-landed-pull-wit → main 10 commits fork 5 threads · 5 unresolved

  • Merged. mason/13488-a-wave-s-page-lists-each-landed-pull-wit was merged into main as 792fde2.

Review

Sign in to review this change.
11 files changed +117 −16
docs/features/README.md +1
@@ -167,6 +167,7 @@ Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
167167 - [How many of a wave's changes are live and waiting to ship](wave-landing.md)
168168 - [How close a wave is to done](wave-landed.md)
169169 - [What a repository with no waves says and offers](wave-empty.md)
170 - [Reading a wave's pulls, newest landed first, with who merged each](wave-pulls-order.md)
170171 - [What became of the first ask](ask-status.md)
171172 - [When a setting or a permission stands in the way](blocked-by.md)
172173 - [The map's growth line](map-growth.md)
docs/features/wave-pulls-order.md added +8
@@ -0,0 +1,8 @@
1 # A wave's pulls, newest landed first
2
3 Open a wave, e.g. `/trevato/forge/waves/<version>`, and read its **Pulls** newest landed first. Each landed pull says who merged it: `merged by ada 2026-01-02`.
4
5 - Pulls not yet landed follow, in the order the wave names them.
6 - The terminal's wave screen shows the same order and the same `merged by` words; the API carries `mergedBy` on each pull.
outdated

Stale: the pager was removed, so no wave pages by link now. Delete this bullet.

7
8 Both doors order with `inLandingOrder` in `src/story/wave_pulls.ts`, so they agree.
src/contract/openapi/routes/getApiV1ReposOwnerNameWavesVersion.ts +1 −1
@@ -1,3 +1,3 @@
11 import { REPO, type Route } from "../shared.ts";
22
3 export const route: Route = { method: "get", path: `${REPO}/waves/{version}`, summary: "Takes no query parameters. Read one wave as { version, date, headline, highlights, pulls: [{ number, title, url }] }; number is null when the line names no pull; a private repository needs a token", auth: false, role: "anonymous", reply: { version: "string", date: "string", headline: "string", highlights: "array", pulls: "array" }, refusals: { not_found: "404: no such repository, or it is not readable, or no such wave" } };
3 export const route: Route = { method: "get", path: `${REPO}/waves/{version}`, summary: "Takes no query parameters. Read one wave as { version, date, headline, highlights, pulls: [{ number, title, url, state, merged_at, merged_by }] } in the order they landed, newest first, those not landed after; merged_by is the username of whoever landed the pull, null when unmerged or unrecorded; a private repository needs a token", auth: false, role: "anonymous", reply: { version: "string", date: "string", headline: "string", highlights: "array", pulls: "array" }, refusals: { not_found: "404: no such repository, or it is not readable, or no such wave" } };
src/http/api.ts +3 −2
@@ -302,7 +302,7 @@ import { readRunLog, subscribeRunLog } from "../runs/log.ts";
302302 import { blobForRender, commitLog, listRefs, listTree, refTip } from "../git/read.ts";
303303 import { repoDir } from "../git/repos.ts";
304304 import { holds, weakEtag } from "./etag.ts";
305 import { carriedPulls, pullPath } from "../story/wave_pulls.ts";
305 import { carriedPulls, inLandingOrder, pullPath } from "../story/wave_pulls.ts";
306306 import { waitingKeys } from "../release/landings.ts";
307307 import { shippedOf } from "../story/wave_moved.ts";
308308 import { pullRefs, readWave, readWaves, waveSize } from "../story/waves.ts";
@@ -2376,7 +2376,7 @@ export function apiRoutes(router: Router<Handler>): void {
23762376 const w = entry.wave;
23772377 // The page's gate on each pull: one the viewer cannot read is not named.
23782378 const pulls = timePhase(ctx.request, "pulls", () =>
2379 carriedPulls(ctx.app.db, pullRefs(w), ctx.auth.user),
2379 inLandingOrder(carriedPulls(ctx.app.db, pullRefs(w), ctx.auth.user)),
23802380 );
23812381 return timePhase(ctx.request, "render", () =>
23822382 json({
@@ -2390,6 +2390,7 @@ export function apiRoutes(router: Router<Handler>): void {
23902390 url: `${ctx.url.origin}${pullPath(p)}`,
23912391 state: p.mergedAt === null ? p.state : "merged",
23922392 merged_at: p.mergedAt,
2393 merged_by: p.mergedBy,
23932394 })),
23942395 }),
23952396 );
src/story/wave_pulls.ts +27 −4
@@ -19,6 +19,8 @@ export interface CarriedPull {
1919 number: number;
2020 title: string;
2121 mergedAt: string | null;
22 /** Username of whoever landed it; null when unmerged or unrecorded. */
23 mergedBy: string | null;
2224 state: "open" | "closed";
2325 }
2426
@@ -27,6 +29,7 @@ interface Row {
2729 number: number;
2830 title: string;
2931 merged_at: string | null;
32 merged_by: string | null;
3033 state: "open" | "closed";
3134 }
3235
@@ -50,8 +53,8 @@ export function carriedPulls(
5053 if (visible.length === 0) return [];
5154 const rows = db
5255 .query<Row, string[]>(
53 `SELECT issue.repo_id, issue.number, issue.title, issue.state, pull.merged_at
54 FROM issue JOIN pull ON pull.issue_id = issue.id
56 `SELECT issue.repo_id, issue.number, issue.title, issue.state, pull.merged_at, user.username AS merged_by
57 FROM issue JOIN pull ON pull.issue_id = issue.id LEFT JOIN user ON user.id = pull.merged_by
5558 WHERE issue.kind = 'pull' AND (${visible
5659 .map(() => "(issue.repo_id = ? AND issue.number = ?)")
5760 .join(" OR ")})`,
@@ -61,12 +64,32 @@ export function carriedPulls(
6164 return visible.flatMap(({ ref, repo }) => {
6265 const r = byKey.get(`${repo.id}#${ref.number}`);
6366 return r
64 ? [{ owner: ref.owner, name: ref.name, number: ref.number, title: r.title, mergedAt: r.merged_at, state: r.state }]
67 ? [{ owner: ref.owner, name: ref.name, number: ref.number, title: r.title, mergedAt: r.merged_at, mergedBy: r.merged_by, state: r.state }]
6568 : [];
6669 });
6770 }
6871
69 /** Where the pull lives on this forge: the local path, never the host the wave file was written with. */
72 /**
73 * Landed pulls newest first, then those not landed, each group in the order the wave names them.
74 */
75 export function inLandingOrder(pulls: readonly CarriedPull[]): CarriedPull[] {
76 return pulls
77 .map((p, i) => ({ p, i }))
78 .sort((a, b) => {
79 const x = a.p.mergedAt;
80 const y = b.p.mergedAt;
81 if (x !== null && y !== null) return x === y ? b.p.number - a.p.number : x < y ? 1 : -1;
82 if (x !== null) return -1;
83 if (y !== null) return 1;
84 return a.i - b.i;
85 })
86 .map((e) => e.p);
87 }
88

inLandingOrder has no unit test of its own: the equal-time tie-break by higher number, and unmerged pulls keeping wave order, are untested. The new test only checks two merged pulls. Medium.

89 /**
90 * Where the pull lives on this forge: the local path, never the host the wave file was written
91 * with.
92 */
7093 export const pullPath = (p: Pick<CarriedPull, "owner" | "name" | "number">): string =>
7194 `/${encodeURIComponent(p.owner)}/${encodeURIComponent(p.name)}/pulls/${p.number}`;
7295
src/tui/screens/waves.ts +3 −3
@@ -14,7 +14,7 @@ import { movedWithPulls, shippedOf, shippedWords, waveProgress, type MovedMilest
1414 import { milestonePath, planNow } from "../../story/wave_plan.ts";
1515 import { repoBase } from "../../web/chrome.ts";
1616 import { waitingKeys } from "../../release/landings.ts";
17 import { carriedPulls, pullPath, type CarriedPull } from "../../story/wave_pulls.ts";
17 import { carriedPulls, inLandingOrder, pullPath, type CarriedPull } from "../../story/wave_pulls.ts";
1818 import { pullRefs, readWave, readWaves, sizeWords, waveLine, waveSize, type WaveEntry } from "../../story/waves.ts";
1919 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, landedSentence, waveSentence } from "../../story/words.ts";
2020 import type { RepoSource } from "../../view/source.ts";
@@ -97,7 +97,7 @@ export function waveLines(
9797 ...(pulls.length === 0
9898 ? [" No pulls to show here."]
9999 : pulls.flatMap((p, i) => [
100 `${picked === i ? "> " : " "}#${p.number} ${plain(p.title)} ${p.mergedAt === null ? p.state : `merged ${p.mergedAt.slice(0, 10)}`}`,
100 `${picked === i ? "> " : " "}#${p.number} ${plain(p.title)} ${p.mergedAt === null ? p.state : `merged ${p.mergedBy === null ? "" : `by ${plain(p.mergedBy)} `}${p.mergedAt.slice(0, 10)}`}`,
101101 ` ${plain(pullPath(p))}`,
102102 ])),
103103 ];
@@ -192,7 +192,7 @@ export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen {
192192 : entry;
193193 if (!one) return;
194194 // The page's gate on each pull: one the viewer cannot read is not named.
195 const pulls = one.ok ? carriedPulls(f.db, pullRefs(one.wave), f.user) : [];
195 const pulls = one.ok ? inLandingOrder(carriedPulls(f.db, pullRefs(one.wave), f.user)) : [];
196196 // Same list as the page, from the same function, with the same gate.
197197 const moved = one.ok
198198 ? movedWithPulls({
src/web/pages/waves.ts +3 −3
@@ -17,7 +17,7 @@ import { repoDir } from "../../git/repos.ts";
1717 import type { Ctx } from "../../http/context.ts";
1818 import { VERSION, type Wave } from "../../story/wave.ts";
1919 import { movedWithPulls, type MovedMilestone, shippedOf, shippedWords, waveProgress, widestMoved } from "../../story/wave_moved.ts";
20 import { carriedPulls, pullPath } from "../../story/wave_pulls.ts";
20 import { carriedPulls, inLandingOrder, pullPath } from "../../story/wave_pulls.ts";
2121 import { fromWave, pullRefs, readWave, readWaves, sizeWords, waveSize } from "../../story/waves.ts";
2222 import { FIRST_WAVE_BUTTON, FIRST_WAVE_TELL, NO_WAVES, landedSentence, waveSentence } from "../../story/words.ts";
2323 import { loadRepo, notFoundPage, repoBase, scopeHeader } from "../chrome.ts";
@@ -200,7 +200,7 @@ export async function wavePage(ctx: Ctx): Promise<Response> {
200200 if (!entry) return notFoundPage(ctx);
201201 const carried = entry.ok
202202 ? timePhase(ctx.request, "pulls", () =>
203 carriedPulls(ctx.app.db, pullRefs(entry.wave), ctx.auth.user),
203 inLandingOrder(carriedPulls(ctx.app.db, pullRefs(entry.wave), ctx.auth.user)),
204204 )
205205 : [];
206206 const moved = entry.ok
@@ -223,7 +223,7 @@ export async function wavePage(ctx: Ctx): Promise<Response> {
223223 row({
224224 href: `${pullPath(p)}${fromWave(repo.ownerName, repo.name, entry.ok ? entry.wave.version : "")}`,
225225 title: html`#${p.number} ${p.title}`,
226 meta: html`${p.mergedAt === null ? p.state : `merged ${p.mergedAt.slice(0, 10)}`}`,
226 meta: html`${p.mergedAt === null ? p.state : `merged ${p.mergedBy === null ? "" : `by ${p.mergedBy} `}${p.mergedAt.slice(0, 10)}`}`,
227227 state: p.mergedAt === null ? p.state : ("merged" as const),
228228 });
229229 /** Each pull is said once: those a change's fold holds are not listed again below. */
test/tui-waves.test.ts +10 −2
@@ -266,7 +266,7 @@ describe("waves in the terminal", () => {
266266
267267 test("a wave opens with the same sentence as the page, under the headline", () => {
268268 const entry = { ok: true as const, file: "1.0.0.md", wave: { version: "1.0.0", date: "2026-01-01", headline: "Head", highlights: [], pulls: [] } };
269 const lines = waveLines(entry, [{ owner: "o", name: "r", number: 1, title: "Add \u001b[2Jsearch", mergedAt: "2026-01-01", state: "closed" }]);
269 const lines = waveLines(entry, [{ owner: "o", name: "r", number: 1, title: "Add \u001b[2Jsearch", mergedAt: "2026-01-01", mergedBy: null, state: "closed" }]);
270270 expect(lines[0]).toBe("Head");
271271 expect(lines[1]).toBe("This wave landed Add [2Jsearch.");
272272 expect(waveLines(entry, [])[1]).toBe("No pull in this wave has landed yet.");
@@ -294,7 +294,7 @@ describe("waves in the terminal", () => {
294294 pulls: [],
295295 },
296296 },
297 [{ owner: "o", name: "r", number: 1, title: "P\u001b[2J", mergedAt: null, state: "open" }],
297 [{ owner: "o", name: "r", number: 1, title: "P\u001b[2J", mergedAt: null, mergedBy: null, state: "open" }],
298298 );
299299 expect(lines.join("\n")).not.toMatch(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/);
300300 });
@@ -384,3 +384,11 @@ describe("waves in the terminal", () => {
384384 expect(h.text).not.toContain("no waves/ directory");
385385 });
386386 });
387
388 describe("a wave's pulls in the terminal", () => {
389 test("say who landed each, as the page does", () => {
390 const entry = { ok: true as const, file: "1.0.0.md", wave: { version: "1.0.0", date: "2026-01-01", headline: "Head", highlights: [], pulls: [] } };
391 const lines = waveLines(entry, [{ owner: "o", name: "r", number: 2, title: "T", mergedAt: "2026-01-02", mergedBy: "ada", state: "closed" }]);
392 expect(lines.join("\n")).toContain("merged by ada 2026-01-02");
393 });
394 });
test/wave-landed.test.ts +1 −1
@@ -21,7 +21,7 @@ import { mergedPull, waveNaming } from "./helpers/wave-pulls.ts";
2121
2222 quietLogs();
2323
24 const pull = (n: number, mergedAt: string | null): CarriedPull => ({ owner: "o", name: "r", number: n, title: `P${n}`, mergedAt, state: mergedAt ? "closed" : "open" });
24 const pull = (n: number, mergedAt: string | null): CarriedPull => ({ owner: "o", name: "r", number: n, title: `P${n}`, mergedAt, mergedBy: null, state: mergedAt ? "closed" : "open" });
2525
2626 test("the sentence for 0, partial and complete waves", () => {
2727 expect(landedSentence([])).toBe(WAVE_NO_CHANGES);
test/wave-landing-order.test.ts added +38
@@ -0,0 +1,38 @@
1 /**
2 * The order a wave lists its pulls in: newest landed first, ties by higher number, unlanded last.
3 */
4 import { expect, test } from "bun:test";
5 import { inLandingOrder, type CarriedPull } from "../src/story/wave_pulls.ts";
6
7 const pull = (number: number, mergedAt: string | null): CarriedPull => ({
8 owner: "a",
9 name: "r",
10 number,
11 title: `t${number}`,
12 mergedAt,
13 mergedBy: mergedAt === null ? null : "mason",
14 state: mergedAt === null ? "open" : "closed",
15 });
16
17 const numbers = (ps: CarriedPull[]) => ps.map((p) => p.number);
18
19 test("the later landing comes first", () => {
20 const out = inLandingOrder([pull(1, "2026-01-01T00:00:00Z"), pull(2, "2026-02-01T00:00:00Z")]);
21 expect(numbers(out)).toEqual([2, 1]);
22 });
23
24 test("pulls landing at the same instant: the higher number first", () => {
25 const t = "2026-01-01T00:00:00Z";
26 expect(numbers(inLandingOrder([pull(3, t), pull(9, t), pull(5, t)]))).toEqual([9, 5, 3]);
27 });
28
29 test("unlanded pulls follow the landed, in the order the wave names them", () => {
30 const out = inLandingOrder([pull(7, null), pull(1, "2026-01-01T00:00:00Z"), pull(4, null), pull(2, "2026-03-01T00:00:00Z")]);
31 expect(numbers(out)).toEqual([2, 1, 7, 4]);
32 });
33
34 test("the input is left as it was", () => {
35 const input = [pull(1, null), pull(2, "2026-01-01T00:00:00Z")];
36 inLandingOrder(input);
37 expect(numbers(input)).toEqual([1, 2]);
38 });
test/wave-pulls.test.ts +22
@@ -103,6 +103,7 @@ test("rows give #N title · merged date, link to the pull, and leave out the uns
103103 expect(body).not.toContain("<b>thing");
104104 expect(body).toContain("Fix the other");
105105 expect(body).toContain("merged 2026-03-04");
106 expect(body).not.toContain("merged by");
106107 expect(body).toMatch(/href="\/alice\/pub\/pulls\/\d+(?:\?from=[^"]*)?"[^>]*class="row"|class="row"[^>]*href="\/alice\/pub\/pulls\/\d+(?:\?from=[^"]*)?"/);
107108 expect(body).not.toContain("Secret work");
108109 expect(body).not.toContain("/alice/priv/pulls/");
@@ -194,3 +195,24 @@ test("the page opens with one escaped sentence of what landed, and says when not
194195 const none = await (await fetch(`${servers.url}/alice/pub/waves/0.2.0`, { headers: { cookie: bobCookie } })).text();
195196 expect(none).toContain("No pull in this wave has landed yet.");
196197 });
198
199 test("pulls are listed newest landed first, with who merged them, in page and API", async () => {
200 const repo = app.db.query<{ id: string }, []>("SELECT id FROM repo WHERE name = 'pub'").get()!;
201 const nums = (t: string) =>
202 app.db.query<{ number: number }, [string, string]>("SELECT number FROM issue WHERE repo_id = ? AND title = ?").get(repo.id, t)!.number;
203 const a = nums("Add the <b>thing</b>");
204 const b = nums("Fix the other");
205 app.db.query("UPDATE pull SET merged_at = '2026-03-01T10:00:00.000Z', merged_by = ? WHERE issue_id = (SELECT id FROM issue WHERE repo_id = ? AND number = ?)").run(bob.id, repo.id, a);
206 app.db.query("UPDATE pull SET merged_at = '2026-03-09T10:00:00.000Z', merged_by = ? WHERE issue_id = (SELECT id FROM issue WHERE repo_id = ? AND number = ?)").run(alice.id, repo.id, b);
207 const html = await (await fetch(`${servers.url}/alice/pub/waves/0.1.0`)).text();
208 expect(html.indexOf("Fix the other")).toBeLessThan(html.indexOf("Add the &lt;b&gt;thing"));
209 expect(html).toContain("merged by alice 2026-03-09");
210 expect(html).toContain("merged by bob 2026-03-01");
211 const api = (await (await fetch(`${servers.url}/api/v1/repos/alice/pub/waves/0.1.0`)).json()) as {
212 pulls: { number: number; merged_by: string | null; state: string }[];
213 };
214 expect(api.pulls.map((p) => p.number).slice(0, 2)).toEqual([b, a]);
215 expect(api.pulls[0]!.merged_by).toBe("alice");
216 expect(api.pulls[1]!.merged_by).toBe("bob");
217 expect(api.pulls.at(-1)!.state).toBe("closed");
218 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs