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
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/13488-a-wave-s-page-lists-each-landed-pull-wit → main 10 commits fork 5 threads · 5 unresolved
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). | ||
| 167 | 167 | - [](wave-landing.md) |
| 168 | 168 | - [](wave-landed.md) |
| 169 | 169 | - [](wave-empty.md) |
| 170 | - [](wave-pulls-order.md) | |
| 170 | 171 | - [](ask-status.md) |
| 171 | 172 | - [](blocked-by.md) |
| 172 | 173 | - [](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. | |
| 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 @@ | ||
| 1 | 1 | import { REPO, type Route } from "../shared.ts"; |
| 2 | 2 | |
| 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"; | ||
| 302 | 302 | import { blobForRender, commitLog, listRefs, listTree, refTip } from "../git/read.ts"; |
| 303 | 303 | import { repoDir } from "../git/repos.ts"; |
| 304 | 304 | 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"; | |
| 306 | 306 | import { waitingKeys } from "../release/landings.ts"; |
| 307 | 307 | import { shippedOf } from "../story/wave_moved.ts"; |
| 308 | 308 | import { pullRefs, readWave, readWaves, waveSize } from "../story/waves.ts"; |
| @@ -2376,7 +2376,7 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 2376 | 2376 | const w = entry.wave; |
| 2377 | 2377 | // The page's gate on each pull: one the viewer cannot read is not named. |
| 2378 | 2378 | 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)), | |
| 2380 | 2380 | ); |
| 2381 | 2381 | return timePhase(ctx.request, "render", () => |
| 2382 | 2382 | json({ |
| @@ -2390,6 +2390,7 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 2390 | 2390 | url: `${ctx.url.origin}${pullPath(p)}`, |
| 2391 | 2391 | state: p.mergedAt === null ? p.state : "merged", |
| 2392 | 2392 | merged_at: p.mergedAt, |
| 2393 | merged_by: p.mergedBy, | |
| 2393 | 2394 | })), |
| 2394 | 2395 | }), |
| 2395 | 2396 | ); |
src/story/wave_pulls.ts +27 −4
| @@ -19,6 +19,8 @@ export interface CarriedPull { | ||
| 19 | 19 | number: number; |
| 20 | 20 | title: string; |
| 21 | 21 | mergedAt: string | null; |
| 22 | /** Username of whoever landed it; null when unmerged or unrecorded. */ | |
| 23 | mergedBy: string | null; | |
| 22 | 24 | state: "open" | "closed"; |
| 23 | 25 | } |
| 24 | 26 | |
| @@ -27,6 +29,7 @@ interface Row { | ||
| 27 | 29 | number: number; |
| 28 | 30 | title: string; |
| 29 | 31 | merged_at: string | null; |
| 32 | merged_by: string | null; | |
| 30 | 33 | state: "open" | "closed"; |
| 31 | 34 | } |
| 32 | 35 | |
| @@ -50,8 +53,8 @@ export function carriedPulls( | ||
| 50 | 53 | if (visible.length === 0) return []; |
| 51 | 54 | const rows = db |
| 52 | 55 | .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 | |
| 55 | 58 | WHERE issue.kind = 'pull' AND (${visible |
| 56 | 59 | .map(() => "(issue.repo_id = ? AND issue.number = ?)") |
| 57 | 60 | .join(" OR ")})`, |
| @@ -61,12 +64,32 @@ export function carriedPulls( | ||
| 61 | 64 | return visible.flatMap(({ ref, repo }) => { |
| 62 | 65 | const r = byKey.get(`${repo.id}#${ref.number}`); |
| 63 | 66 | 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 }] | |
| 65 | 68 | : []; |
| 66 | 69 | }); |
| 67 | 70 | } |
| 68 | 71 | |
| 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 | ||
|
||
| 89 | /** | |
| 90 | * Where the pull lives on this forge: the local path, never the host the wave file was written | |
| 91 | * with. | |
| 92 | */ | |
| 70 | 93 | export const pullPath = (p: Pick<CarriedPull, "owner" | "name" | "number">): string => |
| 71 | 94 | `/${encodeURIComponent(p.owner)}/${encodeURIComponent(p.name)}/pulls/${p.number}`; |
| 72 | 95 |
src/tui/screens/waves.ts +3 −3
| @@ -14,7 +14,7 @@ import { movedWithPulls, shippedOf, shippedWords, waveProgress, type MovedMilest | ||
| 14 | 14 | import { milestonePath, planNow } from "../../story/wave_plan.ts"; |
| 15 | 15 | import { repoBase } from "../../web/chrome.ts"; |
| 16 | 16 | 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"; | |
| 18 | 18 | import { pullRefs, readWave, readWaves, sizeWords, waveLine, waveSize, type WaveEntry } from "../../story/waves.ts"; |
| 19 | 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"; |
| @@ -97,7 +97,7 @@ export function waveLines( | ||
| 97 | 97 | ...(pulls.length === 0 |
| 98 | 98 | ? [" No pulls to show here."] |
| 99 | 99 | : 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)}`}`, | |
| 101 | 101 | ` ${plain(pullPath(p))}`, |
| 102 | 102 | ])), |
| 103 | 103 | ]; |
| @@ -192,7 +192,7 @@ export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen { | ||
| 192 | 192 | : entry; |
| 193 | 193 | if (!one) return; |
| 194 | 194 | // 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)) : []; | |
| 196 | 196 | // Same list as the page, from the same function, with the same gate. |
| 197 | 197 | const moved = one.ok |
| 198 | 198 | ? movedWithPulls({ |
src/web/pages/waves.ts +3 −3
| @@ -17,7 +17,7 @@ import { repoDir } from "../../git/repos.ts"; | ||
| 17 | 17 | import type { Ctx } from "../../http/context.ts"; |
| 18 | 18 | import { VERSION, type Wave } from "../../story/wave.ts"; |
| 19 | 19 | 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"; | |
| 21 | 21 | import { fromWave, pullRefs, readWave, readWaves, sizeWords, waveSize } from "../../story/waves.ts"; |
| 22 | 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"; |
| @@ -200,7 +200,7 @@ export async function wavePage(ctx: Ctx): Promise<Response> { | ||
| 200 | 200 | if (!entry) return notFoundPage(ctx); |
| 201 | 201 | const carried = entry.ok |
| 202 | 202 | ? 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)), | |
| 204 | 204 | ) |
| 205 | 205 | : []; |
| 206 | 206 | const moved = entry.ok |
| @@ -223,7 +223,7 @@ export async function wavePage(ctx: Ctx): Promise<Response> { | ||
| 223 | 223 | row({ |
| 224 | 224 | href: `${pullPath(p)}${fromWave(repo.ownerName, repo.name, entry.ok ? entry.wave.version : "")}`, |
| 225 | 225 | 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)}`}`, | |
| 227 | 227 | state: p.mergedAt === null ? p.state : ("merged" as const), |
| 228 | 228 | }); |
| 229 | 229 | /** 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", () => { | ||
| 266 | 266 | |
| 267 | 267 | test("a wave opens with the same sentence as the page, under the headline", () => { |
| 268 | 268 | 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" }]); | |
| 270 | 270 | expect(lines[0]).toBe("Head"); |
| 271 | 271 | expect(lines[1]).toBe("This wave landed Add [2Jsearch."); |
| 272 | 272 | expect(waveLines(entry, [])[1]).toBe("No pull in this wave has landed yet."); |
| @@ -294,7 +294,7 @@ describe("waves in the terminal", () => { | ||
| 294 | 294 | pulls: [], |
| 295 | 295 | }, |
| 296 | 296 | }, |
| 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" }], | |
| 298 | 298 | ); |
| 299 | 299 | expect(lines.join("\n")).not.toMatch(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/); |
| 300 | 300 | }); |
| @@ -384,3 +384,11 @@ describe("waves in the terminal", () => { | ||
| 384 | 384 | expect(h.text).not.toContain("no waves/ directory"); |
| 385 | 385 | }); |
| 386 | 386 | }); |
| 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"; | ||
| 21 | 21 | |
| 22 | 22 | quietLogs(); |
| 23 | 23 | |
| 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" }); | |
| 25 | 25 | |
| 26 | 26 | test("the sentence for 0, partial and complete waves", () => { |
| 27 | 27 | 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 | ||
| 103 | 103 | expect(body).not.toContain("<b>thing"); |
| 104 | 104 | expect(body).toContain("Fix the other"); |
| 105 | 105 | expect(body).toContain("merged 2026-03-04"); |
| 106 | expect(body).not.toContain("merged by"); | |
| 106 | 107 | expect(body).toMatch(/href="\/alice\/pub\/pulls\/\d+(?:\?from=[^"]*)?"[^>]*class="row"|class="row"[^>]*href="\/alice\/pub\/pulls\/\d+(?:\?from=[^"]*)?"/); |
| 107 | 108 | expect(body).not.toContain("Secret work"); |
| 108 | 109 | 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 | ||
| 194 | 195 | const none = await (await fetch(`${servers.url}/alice/pub/waves/0.2.0`, { headers: { cookie: bobCookie } })).text(); |
| 195 | 196 | expect(none).toContain("No pull in this wave has landed yet."); |
| 196 | 197 | }); |
| 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 <b>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 | }); |
new above
offline
Stale: the pager was removed, so no wave pages by link now. Delete this bullet.