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

A wave page lists its pulls newest first, each with one distilled sentence #14099

Merged opened this

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

Merged

scout/forge:scout/14078-a-wave-page-lists-its-pulls-newest-first → main 7 commits fork 3 threads · 3 unresolved

  • Merged. scout/14078-a-wave-page-lists-its-pulls-newest-first was merged into main as 31ec7ec.

Review

Sign in to review this change.
7 files changed +127 −2
docs/features/README.md +1
@@ -553,3 +553,4 @@ Read with the guide page [When something is wrong](../guide-when-wrong.md).
553553 - [Who liked a post](likers.md)
554554 - [The price of a forge, first on /pricing](pricing-price-line.md)
555555 - [A claimed forge tells a stranger whose it is](claimed-forge-door.md)
556 - [One sentence for each pull on a wave](wave-pull-sentence.md)
docs/features/wave-pull-sentence.md added +8
@@ -0,0 +1,8 @@
1 # One sentence for each pull on a wave
2
3 Open a wave, e.g. `/trevato/forge/waves/<version>`, and under each pull's title read one sentence: the first non-empty line of the pull's description, and nothing when the description is empty (the title above already says it).
4
5 - The sentence is plain text, escaped on the page, and cut at 160 characters with an ellipsis.
6 - The terminal's wave screen (`waves` in the terminal, then open a wave) shows the same sentence on the line under each pull.
7
8 Both doors take it from `distill` in `src/story/wave_pulls.ts`, so they agree.
src/story/wave_pulls.ts +22 −2
@@ -22,9 +22,29 @@ export interface CarriedPull {
2222 /** Username of whoever landed it; null when unmerged or unrecorded. */
2323 mergedBy: string | null;
2424 state: "open" | "closed";
25 /**
26 * The first line of the description; absent when there is none (the title says it). Plain text:
27 * escape it.
28 */
29 sentence?: string;
30 }
31
32 /** Longest sentence shown; a longer first line is cut with an ellipsis. */
33 export const SENTENCE_CAP = 160;
34
outdated

distill returns the title when there is no body, so every consumer prints the title twice (row title plus sentence; terminal too). Return undefined for the fallback case, or have callers skip a sentence equal to the title.

35 /**
36 * The one sentence a pull's description opens with; undefined when it has none, so the title is not
37 * said twice.
38 */
39 export function distill(body: string): string | undefined {
40 const first = body.split(/\r?\n/).map((l) => l.replace(/[\u0000-\u001f\u007f]/g, " ").trim()).find((l) => l !== "");
41 if (first === undefined) return undefined;
42 const s = first;

Non-blocking: const s = first; is a redundant alias. Use first directly. The IIFE spread in carriedPulls could be a plain const sentence = distill(...) and a conditional spread.

43 return s.length <= SENTENCE_CAP ? s : `${s.slice(0, SENTENCE_CAP - 1).trimEnd()}…`;
2544 }
2645
2746 interface Row {
47 body: string;
2848 repo_id: string;
2949 number: number;
3050 title: string;
@@ -53,7 +73,7 @@ export function carriedPulls(
5373 if (visible.length === 0) return [];
5474 const rows = db
5575 .query<Row, string[]>(
56 `SELECT issue.repo_id, issue.number, issue.title, issue.state, pull.merged_at, user.username AS merged_by
76 `SELECT issue.repo_id, issue.number, issue.title, issue.body, issue.state, pull.merged_at, user.username AS merged_by
5777 FROM issue JOIN pull ON pull.issue_id = issue.id LEFT JOIN user ON user.id = pull.merged_by
5878 WHERE issue.kind = 'pull' AND (${visible
5979 .map(() => "(issue.repo_id = ? AND issue.number = ?)")
@@ -64,7 +84,7 @@ export function carriedPulls(
6484 return visible.flatMap(({ ref, repo }) => {
6585 const r = byKey.get(`${repo.id}#${ref.number}`);
6686 return r
67 ? [{ owner: ref.owner, name: ref.name, number: ref.number, title: r.title, mergedAt: r.merged_at, mergedBy: r.merged_by, state: r.state }]
87 ? [{ owner: ref.owner, name: ref.name, number: ref.number, title: r.title, mergedAt: r.merged_at, mergedBy: r.merged_by, state: r.state, ...((s => (s === undefined ? {} : { sentence: s }))(distill(r.body ?? ""))) }]
6888 : [];
6989 });
7090 }
src/tui/screens/waves.ts +1
@@ -98,6 +98,7 @@ export function waveLines(
9898 ? [" No pulls to show here."]
9999 : pulls.flatMap((p, i) => [
100100 `${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 ...(p.sentence === undefined ? [] : [` ${plain(p.sentence)}`]),
101102 ` ${plain(pullPath(p))}`,
102103 ])),
103104 ];
src/web/pages/waves.ts +3
@@ -224,6 +224,9 @@ export async function wavePage(ctx: Ctx): Promise<Response> {
224224 href: `${pullPath(p)}${fromWave(repo.ownerName, repo.name, entry.ok ? entry.wave.version : "")}`,
225225 title: html`#${p.number} ${p.title}`,
226226 meta: html`${p.mergedAt === null ? p.state : `merged ${p.mergedBy === null ? "" : `by ${p.mergedBy} `}${p.mergedAt.slice(0, 10)}`}`,
outdated

Principles 1 and 7: the sentence is the content of the row, but it is packed into meta with a " · " separator ahead of the state and date. On a phone it wraps into one long muted line. Give it its own line (a second row line or a dl row). When the sentence equals the title (empty description), do not render it, so nothing is said twice.

227 // Its own line (a fact row), so the state and date stay scannable; none when the pull has no
228 // description.
229 ...(p.sentence === undefined ? {} : { facts: [{ label: "Says", value: html`<span data-pull-sentence>${p.sentence}</span>` }] }),
227230 state: p.mergedAt === null ? p.state : ("merged" as const),
228231 });
229232 /** Each pull is said once: those a change's fold holds are not listed again below. */
test/tui-waves.test.ts +11
@@ -17,6 +17,8 @@ import { openIssue } from "../src/actions/issues.ts";
1717 import { getIssueById, setIssueState } from "../src/core/issues.ts";
1818 import { writeWave, type Wave } from "../src/story/wave.ts";
1919 import { createForgeApp } from "../src/tui/forge.ts";
20 import type { CarriedPull } from "../src/story/wave_pulls.ts";
21 import type { WaveEntry } from "../src/story/waves.ts";
2022 import { waveLines, wavesScreen } from "../src/tui/screens/waves.ts";
2123 import type { RepoSource } from "../src/view/source.ts";
2224 import { local } from "../src/tui/screens/where.ts";
@@ -392,3 +394,12 @@ describe("a wave's pulls in the terminal", () => {
392394 expect(lines.join("\n")).toContain("merged by ada 2026-01-02");
393395 });
394396 });
397
398 test("each pull's sentence is shown under it, as on the page", () => {
399 const entry: WaveEntry = { ok: true, file: "waves/0.1.0.md", wave: { version: "0.1.0", date: "2026-03-05", headline: "h", highlights: [], pulls: [] } };
400 const pull: CarriedPull = { owner: "a", name: "r", number: 3, title: "T", mergedAt: null, mergedBy: null, state: "open", sentence: "First line of the body" };
401 const lines = waveLines(entry, [pull]);
402 const i = lines.indexOf(" First line of the body");
403 expect(i).toBeGreaterThan(0);
404 expect(lines[i - 1]).toContain("#3 T");
405 });
test/wave-page-pulls.test.ts added +81
@@ -0,0 +1,81 @@
1 /**
2 * A wave page lists its pulls newest first, each with the first line of its description, escaped.
3 */
4 import { afterAll, beforeAll, expect, test } from "bun:test";
5 import { mkdtempSync, rmSync } from "node:fs";
6 import { tmpdir } from "node:os";
7 import { join } from "node:path";
8 import { openPull } from "../src/actions/pulls.ts";
9 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
10 import { createApp, type App } from "../src/app.ts";
11 import { createUser } from "../src/core/users.ts";
12 import { serve, type Servers } from "../src/http/server.ts";
13 import { distill } from "../src/story/wave_pulls.ts";
14 import { quietLogs } from "./helpers/globals.ts";
15 import { waveNaming } from "./helpers/wave-pulls.ts";
16
17 quietLogs();
18
19 let root = "";
20 let app: App;
21 let servers: Servers;
22 let html = "";
23
24 const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
25 if (!r.ok) throw new Error(JSON.stringify(r.error));
26 return r.value;
27 };
28
29 beforeAll(async () => {
30 root = mkdtempSync(join(tmpdir(), "forge-wave-page-pulls-"));
31 app = createApp({ dataDir: root, port: 0 });
32 servers = await serve(app);
33 const u = must(await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }));
34 const repo = must(await createRepo(app, u, { name: "pub", visibility: "public" }));
35 must(await commitToBranch(app, u, repo, { message: "init", files: [{ path: "README.md", content: "hi\n" }] }));
36 const specs: [string, string, string][] = [
37 ["Older", "\n\nOld sentence\nsecond line", "2026-03-01T10:00:00.000Z"],
38 ["Newer", "Says <script>alert(1)</script> & more\nrest", "2026-03-09T10:00:00.000Z"],
39 ["No description title", "", "2026-03-05T10:00:00.000Z"],
40 ];
41 const refs: { owner: string; name: string; number: number }[] = [];
42 for (const [title, body, at] of specs) {
43 const branch = `b-${title.replace(/\W/g, "")}`;
44 must(await commitToBranch(app, u, repo, { branch, message: title, files: [{ path: `${branch}.txt`, content: "x" }] }));
45 const p = must(await openPull(app, u, repo, { title, body, baseBranch: "main", headBranch: branch }));
46 app.db.query("UPDATE pull SET merged_at = ? WHERE issue_id = ?").run(at, p.id);
47 refs.push({ owner: "alice", name: "pub", number: p.number });
48 }
49 must(await commitToBranch(app, u, repo, { message: "wave", files: [{ path: "waves/0.1.0.md", content: waveNaming("0.1.0", refs) }] }));
50 html = await (await fetch(`${servers.url}/alice/pub/waves/0.1.0`)).text();
51 }, 60_000);
52 afterAll(() => {
53 servers.stop();
54 app.close();
55 rmSync(root, { recursive: true, force: true });
56 });
57
58 test("pulls are listed newest first", () => {
59 const order = ["Says &lt;script&gt;", "No description title", "Old sentence"].map((s) => html.indexOf(s, html.indexOf("data-pull-sentence")));
60 expect(order.every((i) => i > 0)).toBe(true);
61 expect(order).toEqual([...order].sort((a, b) => a - b));
62 });
63
64 test("each pull shows the first line of its description, escaped", () => {
65 expect(html).toContain("Old sentence");
66 expect(html).not.toContain("second line");
67 expect(html).toContain("Says &lt;script&gt;alert(1)&lt;/script&gt; &amp; more");
68 expect(html).not.toContain("<script>alert(1)");
69 });
70
71 test("a pull with no description shows no sentence: the title is not said twice", () => {
72 expect(html).not.toContain("<span data-pull-sentence>No description title</span>");
73 expect(html.split("No description title").length - 1).toBe(1);
74 });
75
76 test("distill skips blank lines, cleans control characters and caps the length", () => {
77 expect(distill("\n \nfirst\nsecond")).toBe("first");
78 expect(distill(" \n")).toBeUndefined();
79 expect(distill("a\u0007b")).toBe("a b");
80 expect(distill("x".repeat(500))!.length).toBeLessThanOrEqual(160);
81 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs