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

Parked opened this
Closed without merging

scout/forge:scout/3257-review-one-quiet-column-where-each-item → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +334 −2
docs/design/audit.md +2 −1
@@ -33,7 +33,7 @@ their own vocabulary instead of composing the named one.
3333
3434 ## Finding 2 — the pages, and what each is for
3535
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`
3737 that returns a page (`test/design-audit.test.ts` holds this list to the router,
3838 both ways). Each entry reads `route` — module · what it is for · what
3939 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`,
5656 - `/boards` — `pages/boards-view.ts` · saved queries as panels · `/board` · none seen.
5757 - `/boards/data` — `pages/boards.ts` · the boards' query/data surface · `/board` · none seen.
5858 - `/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.
5960 - `/asked` — `studio/asked_page.ts` · what I answered, as a record · `/asks` · none seen.
6061 - `/flow` — `pages/flow.ts` · the pipeline from ready issue to live deploy, and the bottleneck · `/system`, `/board`, `/` · none seen. A topbar button points here.
6162 - `/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 @@
33 "api.anthropic.com"
44 ],
55 "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"],
77 "run": "bun run src/main.ts",
88 "install": "",
99 "health": "/healthz",
src/http/server.ts +3
@@ -265,6 +265,7 @@ import {
265265 asksMute,
266266 asksPage,
267267 } from "../web/studio/asks_page.ts";
268 import { reviewPage } from "../web/studio/review_page.ts";
268269 import { homeArchive, homeArchived, homeArchiveUndo } from "../web/studio/home_archive.ts";
269270 import { liveFeedFragment } from "../web/studio/feed.ts";
270271 import { serviceWorker } from "../web/sw.ts";
@@ -724,6 +725,8 @@ export function buildRouter(): Router<Handler> {
724725 router.add("GET", "/board/returns", returnsPage);
725726 // One screen for "is everything fine?": what asks the viewer (docs/STUDIO.md).
726727 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);
727730 router.add("POST", "/asks/bulk", asksBulkSubmit);
728731 router.add("POST", "/asks/bulk/:id/undo", asksBulkUndo);
729732 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs