Public: anyone can read this; the crew can change it.
A wave page lists its pulls newest first, each with one distilled sentence #14099
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14078-a-wave-page-lists-its-pulls-newest-first → main 7 commits fork 3 threads · 3 unresolved
docs/features/README.md +1
| @@ -553,3 +553,4 @@ Read with the guide page [When something is wrong](../guide-when-wrong.md). | ||
| 553 | 553 | - [](likers.md) |
| 554 | 554 | - [](pricing-price-line.md) |
| 555 | 555 | - [](claimed-forge-door.md) |
| 556 | - [](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 { | ||
| 22 | 22 | /** Username of whoever landed it; null when unmerged or unrecorded. */ |
| 23 | 23 | mergedBy: string | null; |
| 24 | 24 | 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 | ||
| 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: |
||
| 43 | return s.length <= SENTENCE_CAP ? s : `${s.slice(0, SENTENCE_CAP - 1).trimEnd()}…`; | |
| 25 | 44 | } |
| 26 | 45 | |
| 27 | 46 | interface Row { |
| 47 | body: string; | |
| 28 | 48 | repo_id: string; |
| 29 | 49 | number: number; |
| 30 | 50 | title: string; |
| @@ -53,7 +73,7 @@ export function carriedPulls( | ||
| 53 | 73 | if (visible.length === 0) return []; |
| 54 | 74 | const rows = db |
| 55 | 75 | .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 | |
| 57 | 77 | FROM issue JOIN pull ON pull.issue_id = issue.id LEFT JOIN user ON user.id = pull.merged_by |
| 58 | 78 | WHERE issue.kind = 'pull' AND (${visible |
| 59 | 79 | .map(() => "(issue.repo_id = ? AND issue.number = ?)") |
| @@ -64,7 +84,7 @@ export function carriedPulls( | ||
| 64 | 84 | return visible.flatMap(({ ref, repo }) => { |
| 65 | 85 | const r = byKey.get(`${repo.id}#${ref.number}`); |
| 66 | 86 | 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 ?? ""))) }] | |
| 68 | 88 | : []; |
| 69 | 89 | }); |
| 70 | 90 | } |
src/tui/screens/waves.ts +1
| @@ -98,6 +98,7 @@ export function waveLines( | ||
| 98 | 98 | ? [" No pulls to show here."] |
| 99 | 99 | : pulls.flatMap((p, i) => [ |
| 100 | 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 | ...(p.sentence === undefined ? [] : [` ${plain(p.sentence)}`]), | |
| 101 | 102 | ` ${plain(pullPath(p))}`, |
| 102 | 103 | ])), |
| 103 | 104 | ]; |
src/web/pages/waves.ts +3
| @@ -224,6 +224,9 @@ export async function wavePage(ctx: Ctx): Promise<Response> { | ||
| 224 | 224 | href: `${pullPath(p)}${fromWave(repo.ownerName, repo.name, entry.ok ? entry.wave.version : "")}`, |
| 225 | 225 | title: html`#${p.number} ${p.title}`, |
| 226 | 226 | 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>` }] }), | |
| 227 | 230 | state: p.mergedAt === null ? p.state : ("merged" as const), |
| 228 | 231 | }); |
| 229 | 232 | /** 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"; | ||
| 17 | 17 | import { getIssueById, setIssueState } from "../src/core/issues.ts"; |
| 18 | 18 | import { writeWave, type Wave } from "../src/story/wave.ts"; |
| 19 | 19 | 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"; | |
| 20 | 22 | import { waveLines, wavesScreen } from "../src/tui/screens/waves.ts"; |
| 21 | 23 | import type { RepoSource } from "../src/view/source.ts"; |
| 22 | 24 | import { local } from "../src/tui/screens/where.ts"; |
| @@ -392,3 +394,12 @@ describe("a wave's pulls in the terminal", () => { | ||
| 392 | 394 | expect(lines.join("\n")).toContain("merged by ada 2026-01-02"); |
| 393 | 395 | }); |
| 394 | 396 | }); |
| 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 <script>", "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 <script>alert(1)</script> & 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 | }); |
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.