Public: anyone can read this; the crew can change it.
/review: one quiet column where each item says what, why it needs you, the crew's recommendation and the evidence #4337
scout/forge:scout/3257-review-one-quiet-column-where-each-item → main 2 commits fork
5 files
changed +334
−2
docs/design/audit.md +2 −1
| @@ -33,7 +33,7 @@ their own vocabulary instead of composing the named one. | ||
| 33 | 33 | |
| 34 | 34 | ## Finding 2 — the pages, and what each is for |
| 35 | 35 | |
| 36 | There are 61 top-level pages, one entry each: every static `GET` route in `src/http/server.ts` | |
| 36 | There are 62 top-level pages, one entry each: every static `GET` route in `src/http/server.ts` | |
| 37 | 37 | that returns a page (`test/design-audit.test.ts` holds this list to the router, |
| 38 | 38 | both ways). Each entry reads `route` — module · what it is for · what |
| 39 | 39 | duplicates it · what breaks `docs/DESIGN.md`. "Breaks" counts colour literals |
| @@ -56,6 +56,7 @@ Machine routes are not pages and have no entry: `/audit.csv`, | ||
| 56 | 56 | - `/boards` — `pages/boards-view.ts` · saved queries as panels · `/board` · none seen. |
| 57 | 57 | - `/boards/data` — `pages/boards.ts` · the boards' query/data surface · `/board` · none seen. |
| 58 | 58 | - `/asks` — `studio/asks_page.ts` · what the crew is waiting on me for · `/` "needs me" list · colours 2. |
| 59 | - `/review` — `studio/review_page.ts` · the asks as one read-only column: what, why, the crew's recommendation, the evidence · `/asks` (same asks, with buttons) · none seen. | |
| 59 | 60 | - `/asked` — `studio/asked_page.ts` · what I answered, as a record · `/asks` · none seen. |
| 60 | 61 | - `/flow` — `pages/flow.ts` · the pipeline from ready issue to live deploy, and the bottleneck · `/system`, `/board`, `/` · none seen. A topbar button points here. |
| 61 | 62 | - `/map` — `pages/map.ts` (1,806 lines) · the dependency map of work across the forge · `/board`, issue dependency lists, `/:owner/:name/map` · colours 3, sizes 12: the largest private vocabulary. |
forge.json +1 −1
| @@ -3,7 +3,7 @@ | ||
| 3 | 3 | "api.anthropic.com" |
| 4 | 4 | ], |
| 5 | 5 | "app": { |
| 6 | "looks": ["/", "/forges", "/family", "/front", "/explore", "/board", "/boards", "/asked", "/search", "/new", "/audit", "/releases", "/apps", "/migrate", "/map", "/system", "/contribute", "/resilience", "/settings"], | |
| 6 | "looks": ["/", "/forges", "/family", "/front", "/explore", "/board", "/boards", "/asked", "/review", "/search", "/new", "/audit", "/releases", "/apps", "/migrate", "/map", "/system", "/contribute", "/resilience", "/settings"], | |
| 7 | 7 | "run": "bun run src/main.ts", |
| 8 | 8 | "install": "", |
| 9 | 9 | "health": "/healthz", |
src/http/server.ts +3
| @@ -265,6 +265,7 @@ import { | ||
| 265 | 265 | asksMute, |
| 266 | 266 | asksPage, |
| 267 | 267 | } from "../web/studio/asks_page.ts"; |
| 268 | import { reviewPage } from "../web/studio/review_page.ts"; | |
| 268 | 269 | import { homeArchive, homeArchived, homeArchiveUndo } from "../web/studio/home_archive.ts"; |
| 269 | 270 | import { liveFeedFragment } from "../web/studio/feed.ts"; |
| 270 | 271 | import { serviceWorker } from "../web/sw.ts"; |
| @@ -724,6 +725,8 @@ export function buildRouter(): Router<Handler> { | ||
| 724 | 725 | router.add("GET", "/board/returns", returnsPage); |
| 725 | 726 | // One screen for "is everything fine?": what asks the viewer (docs/STUDIO.md). |
| 726 | 727 | router.add("GET", "/asks", asksPage); |
| 728 | // The same asks as one read-only column, each with its why, advice and evidence. | |
| 729 | router.add("GET", "/review", reviewPage); | |
| 727 | 730 | router.add("POST", "/asks/bulk", asksBulkSubmit); |
| 728 | 731 | router.add("POST", "/asks/bulk/:id/undo", asksBulkUndo); |
| 729 | 732 | router.add("POST", "/asks/listen", asksListen); |
src/web/studio/review_page.ts added +171
| @@ -0,0 +1,171 @@ | ||
| 1 | /** | |
| 2 | * /review: one quiet column of what asks a person. Each ask is a card that | |
| 3 | * says what it is, why it needs a person, what the crew recommends and the | |
| 4 | * evidence (diff stat, check, preview, before and after), so nothing needs | |
| 5 | * a click to be judged. Read-only: acting from here is the next issue; the | |
| 6 | * asks themselves are `asks.ts`, read the way `/asks` reads them. | |
| 7 | */ | |
| 8 | ||
| 9 | import { notePhase, takeSessionTime } from "../../core/route_timing.ts"; | |
| 10 | import type { Ctx } from "../../http/context.ts"; | |
| 11 | import { repoDir } from "../../git/repos.ts"; | |
| 12 | import { diffBetween, type Pull } from "../../core/pulls.ts"; | |
| 13 | import { latestRunsForIssues, type Run } from "../../core/runs.ts"; | |
| 14 | import { recommendationsFor, type Recommendation } from "../../core/pull_wait.ts"; | |
| 15 | import { appsForRepos } from "../../core/apps.ts"; | |
| 16 | import { looksForApps, lookUrl } from "../../core/looks.ts"; | |
| 17 | import { listReposVisibleTo } from "../../core/repos.ts"; | |
| 18 | import { previewEnv } from "../../apps/data.ts"; | |
| 19 | import { repoBase, signInFirst } from "../chrome.ts"; | |
| 20 | import { html, type Html } from "../html.ts"; | |
| 21 | import { page } from "../layout.ts"; | |
| 22 | import { badge, card, time, type Tone } from "../ui.ts"; | |
| 23 | import { thumbLook } from "../pages/looks.ts"; | |
| 24 | import { decisionsFor, type Decision } from "./asks.ts"; | |
| 25 | import { changeHref } from "./nouns.ts"; | |
| 26 | ||
| 27 | /** How many asks the column shows; the rest are on `/asks`. */ | |
| 28 | const SHOWN = 50; | |
| 29 | ||
| 30 | interface Evidence { | |
| 31 | readonly stat?: { readonly files: number; readonly additions: number; readonly deletions: number }; | |
| 32 | readonly check?: Run; | |
| 33 | readonly before?: string; | |
| 34 | readonly after?: string; | |
| 35 | } | |
| 36 | ||
| 37 | const stamp = (d: Decision): string => d.pull?.updatedAt ?? d.issue?.updatedAt ?? ""; | |
| 38 | ||
| 39 | const titleOf = (d: Decision): string => | |
| 40 | d.pull?.title ?? d.issue?.title ?? d.proposal?.title ?? `${d.repo.name} is at its daily ceiling`; | |
| 41 | ||
| 42 | const hrefOf = (d: Decision): string => { | |
| 43 | const base = repoBase(d.repo); | |
| 44 | if (d.pull) return changeHref(base, d.pull.number); | |
| 45 | if (d.issue) return `${base}/issues/${d.issue.number}`; | |
| 46 | return base; | |
| 47 | }; | |
| 48 | ||
| 49 | const noun = (d: Decision): string => (d.pull ? "pull request" : d.issue ? "issue" : "repository"); | |
| 50 | ||
| 51 | const ADVICE: Record<Recommendation["verdict"], { word: string; tone: Tone }> = { | |
| 52 | merge: { word: "Merge", tone: "success" }, | |
| 53 | close: { word: "Close", tone: "danger" }, | |
| 54 | change: { word: "Change", tone: "attn" }, | |
| 55 | }; | |
| 56 | ||
| 57 | const CHECK_WORD: Record<string, string> = { | |
| 58 | ok: "check passed", | |
| 59 | failed: "check failed", | |
| 60 | running: "check running", | |
| 61 | queued: "check queued", | |
| 62 | cancelled: "check cancelled", | |
| 63 | }; | |
| 64 | ||
| 65 | /** The diff stat of each pull, read in parallel; a pull git cannot diff has no stat. */ | |
| 66 | async function stats(ctx: Ctx, decisions: readonly Decision[]): Promise<Map<string, NonNullable<Evidence["stat"]>>> { | |
| 67 | const out = new Map<string, NonNullable<Evidence["stat"]>>(); | |
| 68 | await Promise.all( | |
| 69 | decisions.map(async (d) => { | |
| 70 | const pull: Pull | undefined = d.pull; | |
| 71 | if (!pull) return; | |
| 72 | try { | |
| 73 | const got = await diffBetween(repoDir(ctx.app.reposRoot, d.repo.ownerName, d.repo.name), pull.baseOid, pull.headOid); | |
| 74 | if (!got.failed) | |
| 75 | out.set(pull.id, { files: got.diff.files.length, additions: got.diff.additions, deletions: got.diff.deletions }); | |
| 76 | } catch { | |
| 77 | // No stat is better than no page. | |
| 78 | } | |
| 79 | }), | |
| 80 | ); | |
| 81 | return out; | |
| 82 | } | |
| 83 | ||
| 84 | function evidenceFor(ctx: Ctx, decisions: readonly Decision[]): Map<string, Evidence> { | |
| 85 | const db = ctx.app.db; | |
| 86 | const pulls = decisions.flatMap((d) => (d.pull ? [d.pull] : [])); | |
| 87 | const checks = latestRunsForIssues(db, pulls.map((p) => p.id)); | |
| 88 | const records = appsForRepos(db, [...new Set(decisions.map((d) => d.repo.id))]); | |
| 89 | const looks = looksForApps(db, [...records.values()].map((r) => r.id)); | |
| 90 | const out = new Map<string, Evidence>(); | |
| 91 | for (const d of decisions) { | |
| 92 | if (!d.pull) continue; | |
| 93 | const record = records.get(d.repo.id); | |
| 94 | const at = (env: string): string | undefined => { | |
| 95 | if (record === undefined) return undefined; | |
| 96 | const look = thumbLook(ctx, d.repo, record, looks.filter((l) => l.appId === record.id && l.env === env)); | |
| 97 | return look && lookUrl(repoBase(d.repo), look); | |
| 98 | }; | |
| 99 | const after = d.picture ?? at(previewEnv(d.pull.number)); | |
| 100 | const before = after === undefined ? undefined : at("production"); | |
| 101 | const check = checks.get(d.pull.id); | |
| 102 | out.set(d.id, { | |
| 103 | ...(check === undefined ? {} : { check }), | |
| 104 | ...(after === undefined ? {} : { after }), | |
| 105 | ...(before === undefined ? {} : { before }), | |
| 106 | }); | |
| 107 | } | |
| 108 | return out; | |
| 109 | } | |
| 110 | ||
| 111 | function ask(d: Decision, ev: Evidence, rec: Recommendation | undefined): Html { | |
| 112 | const evidence: Html[] = []; | |
| 113 | if (ev.stat) evidence.push(html`<span>${ev.stat.files} ${ev.stat.files === 1 ? "file" : "files"}, +${ev.stat.additions} −${ev.stat.deletions}</span>`); | |
| 114 | if (ev.check) evidence.push(html`<span>${CHECK_WORD[ev.check.state] ?? ev.check.state}</span>`); | |
| 115 | if (d.preview) evidence.push(html`<a href="${d.preview}">preview</a>`); | |
| 116 | if (ev.before) evidence.push(html`<a href="${ev.before}">before</a>`); | |
| 117 | if (ev.after) evidence.push(html`<a href="${ev.after}">after</a>`); | |
| 118 | const created = d.pull?.createdAt ?? d.issue?.createdAt; | |
| 119 | return card( | |
| 120 | html`<div class="stack-tight"> | |
| 121 | <p class="muted small"> | |
| 122 | <a href="${repoBase(d.repo)}">${d.repo.ownerName}/${d.repo.name}</a> · ${noun(d)}${created ? html` · ${time(created)}` : null} | |
| 123 | </p> | |
| 124 | <p>${d.why ?? d.short}</p> | |
| 125 | ${rec | |
| 126 | ? html`<p>${badge(ADVICE[rec.verdict].word, { tone: ADVICE[rec.verdict].tone })} <span class="small">${rec.reason}</span></p>` | |
| 127 | : html`<p class="muted small">The crew has no recommendation.</p>`} | |
| 128 | ${evidence.length === 0 | |
| 129 | ? null | |
| 130 | : html`<p class="muted small">${evidence.map((e, i) => html`${i > 0 ? " · " : ""}${e}`)}</p>`} | |
| 131 | </div>`, | |
| 132 | { head: html`<h2><a href="${hrefOf(d)}">${titleOf(d)}</a></h2>`, attrs: html`data-ask="${d.id}"` }, | |
| 133 | ); | |
| 134 | } | |
| 135 | ||
| 136 | export async function reviewPage(ctx: Ctx): Promise<Response> { | |
| 137 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); | |
| 138 | const user = ctx.auth.user; | |
| 139 | if (!user) return signInFirst(ctx); | |
| 140 | const db = ctx.app.db; | |
| 141 | // "asks" is every read the column needs: the asks, their evidence, the diffs. | |
| 142 | const reading = performance.now(); | |
| 143 | const shown = decisionsFor(ctx, listReposVisibleTo(db, user, { limit: 200, withoutArchived: true })) | |
| 144 | .sort((a, b) => stamp(b).localeCompare(stamp(a))) | |
| 145 | .slice(0, SHOWN); | |
| 146 | const evidence = evidenceFor(ctx, shown); | |
| 147 | const advice = recommendationsFor( | |
| 148 | db, | |
| 149 | shown.flatMap((d) => (d.pull ? [d.pull.id] : d.issue ? [d.issue.id] : [])), | |
| 150 | ); | |
| 151 | const sizes = await stats(ctx, shown); | |
| 152 | notePhase(ctx.request, "asks", performance.now() - reading); | |
| 153 | const rendering = performance.now(); | |
| 154 | const response = page({ | |
| 155 | ctx, | |
| 156 | title: "Review", | |
| 157 | body: html`<main class="stack narrow"> | |
| 158 | <h1>Review</h1> | |
| 159 | ${shown.length === 0 | |
| 160 | ? html`<p class="muted">Nothing needs you.</p>` | |
| 161 | : shown.map((d) => { | |
| 162 | const ev = evidence.get(d.id) ?? {}; | |
| 163 | const stat = d.pull ? sizes.get(d.pull.id) : undefined; | |
| 164 | const id = d.pull?.id ?? d.issue?.id; | |
| 165 | return ask(d, stat ? { ...ev, stat } : ev, d.recommendation ?? (id ? advice.get(id) : undefined)); | |
| 166 | })} | |
| 167 | </main>`, | |
| 168 | }); | |
| 169 | notePhase(ctx.request, "render", performance.now() - rendering); | |
| 170 | return response; | |
| 171 | } |
test/review-page.test.ts added +157
| @@ -0,0 +1,157 @@ | ||
| 1 | /** | |
| 2 | * /review (#3257): the asks as one read-only column. A handed-over pull, a | |
| 3 | * stale pull and a parked issue are three rows, each with its why and the | |
| 4 | * crew's recommendation. | |
| 5 | */ | |
| 6 | ||
| 7 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 8 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 9 | import { tmpdir } from "node:os"; | |
| 10 | import { join } from "node:path"; | |
| 11 | import { createApp, type App } from "../src/app.ts"; | |
| 12 | import { addCrew, createAgentRow, setCrewRole } from "../src/core/agents.ts"; | |
| 13 | import { addComment } from "../src/core/issues.ts"; | |
| 14 | import { createRepo, type Repo } from "../src/core/repos.ts"; | |
| 15 | import { submitReview } from "../src/core/reviews.ts"; | |
| 16 | import { createUser, type User } from "../src/core/users.ts"; | |
| 17 | import { BREAKER_NOTE } from "../src/crew/breaker.ts"; | |
| 18 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 19 | import { id } from "../src/kernel/id.ts"; | |
| 20 | import { quietLogs } from "./helpers/globals.ts"; | |
| 21 | ||
| 22 | quietLogs(); | |
| 23 | ||
| 24 | const ZERO = "0".repeat(40); | |
| 25 | const hoursAgo = (h: number) => new Date(Date.now() - h * 3_600_000).toISOString(); | |
| 26 | ||
| 27 | describe("/review", () => { | |
| 28 | let dataDir = ""; | |
| 29 | let app: App; | |
| 30 | let servers: Servers; | |
| 31 | let owner: User; | |
| 32 | let builder: User; | |
| 33 | let reviewer: User; | |
| 34 | let repo: Repo; | |
| 35 | let cookie = ""; | |
| 36 | let seq = 0; | |
| 37 | ||
| 38 | const user = async (username: string, agent: boolean) => { | |
| 39 | const made = await createUser(app.db, { | |
| 40 | username, | |
| 41 | email: `${username}@forge.test`, | |
| 42 | ...(agent | |
| 43 | ? { agent: true, origin: "agent" as const } | |
| 44 | : { password: "a-good-passphrase", origin: "seed" as const, trusted: true, adminIfFirst: true }), | |
| 45 | }); | |
| 46 | if (!made.ok) throw new Error(`seed ${username}: ${made.error}`); | |
| 47 | if (agent) createAgentRow(app.db, { userId: made.value.id, brief: `${username}.` }); | |
| 48 | return made.value; | |
| 49 | }; | |
| 50 | ||
| 51 | const item = (kind: "pull" | "issue", author: User, title: string, age: number) => { | |
| 52 | const issueId = id(); | |
| 53 | const number = app.db | |
| 54 | .query<{ issue_seq: number }, [string]>( | |
| 55 | "UPDATE repo SET issue_seq = issue_seq + 1 WHERE id = ?1 RETURNING issue_seq", | |
| 56 | ) | |
| 57 | .get(repo.id)!.issue_seq; | |
| 58 | app.db | |
| 59 | .query( | |
| 60 | `INSERT INTO issue (id, repo_id, number, kind, title, body, author_id, state, created_at) | |
| 61 | VALUES (?1, ?2, ?3, ?4, ?5, '', ?6, 'open', ?7)`, | |
| 62 | ) | |
| 63 | .run(issueId, repo.id, number, kind, title, author.id, hoursAgo(age)); | |
| 64 | if (kind === "pull") | |
| 65 | app.db | |
| 66 | .query( | |
| 67 | `INSERT INTO pull (issue_id, base_branch, head_branch, base_oid, head_oid, head_repo_id) | |
| 68 | VALUES (?1, 'main', ?2, ?3, ?3, ?4)`, | |
| 69 | ) | |
| 70 | .run(issueId, `b/${++seq}`, ZERO, repo.id); | |
| 71 | return issueId; | |
| 72 | }; | |
| 73 | ||
| 74 | const advise = (issueId: string, verdict: string, reason: string) => | |
| 75 | addComment(app.db, { issueId, authorId: reviewer.id, body: `Recommendation: ${verdict} — ${reason}` }); | |
| 76 | ||
| 77 | const get = (headers: Record<string, string> = {}) => | |
| 78 | fetch(`${servers.url}/review`, { headers, redirect: "manual" }); | |
| 79 | ||
| 80 | beforeAll(async () => { | |
| 81 | dataDir = await mkdtemp(join(tmpdir(), "forge-review-page-")); | |
| 82 | app = createApp({ dataDir, port: 0 }); | |
| 83 | servers = await serve(app); | |
| 84 | owner = await user("alice", false); | |
| 85 | builder = await user("builder", true); | |
| 86 | reviewer = await user("reviewer", true); | |
| 87 | const made = await createRepo(app.db, app.reposRoot, { | |
| 88 | ownerId: owner.id, | |
| 89 | name: "rev", | |
| 90 | visibility: "public", | |
| 91 | description: "rev", | |
| 92 | }); | |
| 93 | if (!made.ok) throw new Error(`seed repo: ${made.error}`); | |
| 94 | repo = made.value; | |
| 95 | for (const agent of [builder, reviewer]) addCrew(app.db, repo.id, agent.id, owner.id); | |
| 96 | setCrewRole(app.db, repo.id, reviewer.id, "reviewer"); | |
| 97 | ||
| 98 | const handed = item("pull", builder, "Handed over pull", 3); | |
| 99 | for (let r = 0; r < 3; r++) | |
| 100 | submitReview(app.db, { | |
| 101 | issueId: handed, | |
| 102 | authorId: reviewer.id, | |
| 103 | state: "changes_requested", | |
| 104 | body: `Round ${r}.`, | |
| 105 | commitOid: ZERO, | |
| 106 | }); | |
| 107 | advise(handed, "close", "three rounds, still wrong"); | |
| 108 | const stale = item("pull", owner, "Stale pull", 30); | |
| 109 | advise(stale, "merge", "small and green"); | |
| 110 | const parked = item("issue", owner, "Parked issue", 5); | |
| 111 | advise(parked, "change", "narrow the scope"); | |
| 112 | addComment(app.db, { issueId: parked, authorId: builder.id, body: BREAKER_NOTE }); | |
| 113 | item("pull", builder, "Young crew pull", 2); | |
| 114 | ||
| 115 | const signin = await fetch(`${servers.url}/signin`, { | |
| 116 | method: "POST", | |
| 117 | body: new URLSearchParams({ username: "alice", password: "a-good-passphrase" }), | |
| 118 | redirect: "manual", | |
| 119 | }); | |
| 120 | cookie = (signin.headers.get("set-cookie") ?? "").split(";")[0]!; | |
| 121 | }, 30_000); | |
| 122 | ||
| 123 | afterAll(async () => { | |
| 124 | await servers.stop(); | |
| 125 | await rm(dataDir, { recursive: true, force: true }); | |
| 126 | }); | |
| 127 | ||
| 128 | test("a signed-out reader is sent to sign in", async () => { | |
| 129 | const res = await get(); | |
| 130 | expect(res.status).toBe(303); | |
| 131 | expect(res.headers.get("location")).toContain("/signin"); | |
| 132 | }); | |
| 133 | ||
| 134 | test("three rows, each with its why and the crew's recommendation", async () => { | |
| 135 | const res = await get({ cookie }); | |
| 136 | expect(res.status).toBe(200); | |
| 137 | const body = await res.text(); | |
| 138 | expect(body.match(/data-ask="/g)?.length).toBe(3); | |
| 139 | for (const title of ["Handed over pull", "Stale pull", "Parked issue"]) expect(body).toContain(title); | |
| 140 | expect(body).not.toContain("Young crew pull"); | |
| 141 | expect(body).toContain("three reviews asked for changes"); | |
| 142 | expect(body).toContain("three rounds, still wrong"); | |
| 143 | expect(body).toContain("small and green"); | |
| 144 | expect(body).toContain("narrow the scope"); | |
| 145 | expect(body).not.toContain("The crew has no recommendation"); | |
| 146 | expect(body).toContain("pull request"); | |
| 147 | expect(body).toContain("issue"); | |
| 148 | }); | |
| 149 | ||
| 150 | test("newest decision first, and Server-Timing names its phases", async () => { | |
| 151 | const res = await get({ cookie }); | |
| 152 | const body = await res.text(); | |
| 153 | expect(body.indexOf("Handed over pull")).toBeLessThan(body.indexOf("Stale pull")); | |
| 154 | const timing = res.headers.get("server-timing") ?? ""; | |
| 155 | for (const phase of ["session", "asks", "render"]) expect(timing).toContain(`${phase};dur=`); | |
| 156 | }); | |
| 157 | }); |
new above
offline