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

A review is guided: a pull carries steps that take the reviewer, person or agent, into the preview at the place to test #13701

Merged opened this in answer to

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

Merged

torque/forge:torque/13653-a-review-is-guided-a-pull-carries-steps → main 14 commits fork 4 threads · 4 unresolved

  • Merged. torque/13653-a-review-is-guided-a-pull-carries-steps was merged into main as cf7835c.

Review

Sign in to review this change.
20 files changed +973 −7
src/actions/review_steps.ts added +147
@@ -0,0 +1,147 @@
1 /**
2 * A guided review's two writes (#13653): a writer sets a pull's script, and whoever walked it sends
3 * its answers back as ONE comment on the pull, each answer tied to its step. The same words serve
4 * the page, the API and the terminal.
5 */
6
7 import type { App } from "../app.ts";
8 import { canRead, canWrite, type Repo } from "../core/repos.ts";
9 import type { Pull } from "../core/pulls.ts";
10 import type { User } from "../core/users.ts";
11 import { addCommentThrough } from "./issues.ts";
12 import { err, ok, type Result } from "../kernel/result.ts";
13 import {
14 parseSteps,
15 saveSteps,
16 stepPath,
17 stepsOf,
18 type ReviewStep,
19 type StepsError,
20 } from "../core/review_steps.ts";
21 import type { AccessError } from "./access.ts";
22 import { previewEnv } from "../apps/data.ts";
23 import { openEnvUrl } from "./apps.ts";
24
25 export type StepsSetError = AccessError | StepsError | "not_open";
26
27 /** Set a pull's review script: a writer's, on an open pull. */
28 export function setReviewSteps(
29 app: App,
30 actor: User | undefined,
31 repo: Repo,
32 pull: Pull,
33 raw: unknown,
34 ): Result<ReviewStep[], StepsSetError> {
35 if (pull.repoId !== repo.id || !canRead(app.db, repo, actor)) return err("not_found");
36 if (!actor) return err("unauthorized");
37 if (!canWrite(app.db, repo, actor)) return err("forbidden");
38 if (pull.state !== "open" || pull.mergedAt !== null) return err("not_open");
39 const steps = parseSteps(raw);
40 if (!steps.ok) return steps;
41 saveSteps(app.db, pull.id, actor.username, steps.value);
42 app.bus.append({
43 kind: "pull.review_steps",
44 repoId: repo.id,
45 actorId: actor.id,
46 payload: { number: pull.number, steps: steps.value.length },
47 });
48 return ok(steps.value);
49 }
50
51 export type Verdict = "works" | "broken" | "skipped";
52 export interface StepAnswer {
53 readonly verdict: Verdict;
54 readonly note: string;
55 }
56
57 const NOTE_MAX = 500;
58 const VERDICTS: readonly Verdict[] = ["works", "broken", "skipped"];
59
60 /**
61 * The answers a form or query carries, `v<n>` (works, broken or skipped) and `n<n>` (a note), for
62 * a script of `count` steps. A missing answer is skipped; an unknown word is refused.
63 */
64 export function readAnswers(count: number, get: (key: string) => string | null): StepAnswer[] | undefined {
65 const out: StepAnswer[] = [];
66 for (let i = 1; i <= count; i++) {
67 const v = (get(`v${i}`) ?? "skipped") as Verdict;
68 if (!VERDICTS.includes(v)) return undefined;
69 // eslint-disable-next-line no-control-regex
70 const note = (get(`n${i}`) ?? "").replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, " ").trim();
71 out.push({ verdict: v, note: [...note].slice(0, NOTE_MAX).join("") });
72 }
73 return out;
74 }
75
76 const WORD: Readonly<Record<Verdict, string>> = {
77 works: "works",
78 broken: "does not work",
79 skipped: "not tried",
80 };
81
82 /**
83 * Words a writer chose, set into a comment under the reviewer's name as plain text: every markdown
84 * and HTML character is escaped, so a script cannot dress itself as the reviewer's own formatting.
85 */
86 export function plain(text: string): string {
87 return text.replace(/[\\`*_{}\[\]()<>#|~&@:]/g, "\\$&");
88 }
89
90 /** The one comment: a count line, then each step with its address, the check and the answer. */
91 export function answersComment(
92 base: string,
93 number: number,
94 steps: readonly ReviewStep[],
95 answers: readonly StepAnswer[],
96 ): string {
97 const count = (v: Verdict) => answers.filter((a) => a.verdict === v).length;
98 const lines = [
99 `Guided review: ${count("works")} of ${steps.length} steps work, ${count("broken")} do not, ${count("skipped")} not tried.`,
100 "",
101 ];
102 steps.forEach((s, i) => {
103 const a = answers[i] ?? { verdict: "skipped" as const, note: "" };
104 lines.push(`${i + 1}. [Step ${i + 1}](${stepPath(base, number, i + 1)}) — ${WORD[a.verdict]}. Expected: ${plain(s.expect)}`);
105 if (s.ask !== undefined) lines.push(` Asked: ${plain(s.ask)}`);
106 if (a.note !== "") lines.push(` Note: ${plain(a.note.replace(/\n/g, " "))}`);
107 });
108 return lines.join("\n");
109 }
110
111 /** Send a walked script's answers back to the pull as one comment. */
112 export async function sendReviewAnswers(
113 app: App,
114 actor: User | undefined,
115 repo: Repo,
116 pull: Pull,
117 answers: readonly StepAnswer[],
118 ): Promise<Result<{ steps: number }, "no_steps" | "not_found" | "unauthorized" | "refused">> {
119 if (!canRead(app.db, repo, actor)) return err("not_found");
120 if (!actor) return err("unauthorized");
121 const steps = stepsOf(app.db, pull);
122 if (steps.length === 0 || answers.length !== steps.length) return err("no_steps");
123 const body = answersComment(`/${repo.ownerName}/${repo.name}`, pull.number, steps, answers);
124 const added = await addCommentThrough(app, actor, repo, pull, body);
125 return added.ok ? ok({ steps: steps.length }) : err("refused");
126 }
127
128 /**
129 * A pull's steps as an agent or a person reads them: each with its number, its words, the
130 * absolute address of its page in the preview (null when the viewer may not open it) and the
131 * forge's own deep link, `/<owner>/<name>/pulls/<n>/review/<step>`.
132 */
133 export function reviewSteps(app: App, actor: User | undefined, repo: Repo, pull: Pull) {
134 const base = `/${repo.ownerName}/${repo.name}`;
135 return stepsOf(app.db, pull).map((s, i) => {
136 const link = openEnvUrl(app, actor, repo, previewEnv(pull.number), s.go);
137 return {
138 step: i + 1,
139 go: s.go,
140 look: s.look,
141 expect: s.expect,
142 ask: s.ask ?? null,
143 url: link.ok ? link.value : null,
144 link: stepPath(base, pull.number, i + 1),
145 };
146 });
147 }
src/apps/proxy.ts +14 −4
@@ -74,6 +74,8 @@ import { currentLoopLag, forgeWaited, LAG_WINDOW_MS } from "../perf/loop_worst.t
7474 import { HOOK_MAX_BYTES, HOOK_PREFIX, hookPath, readCapped } from "./hook_relay.ts";
7575 import { liveOf } from "../perf/live.ts";
7676 import { heldBy, noteRelayWait, stallTiming } from "./relay_wait.ts";
77 import { stepsOf } from "../core/review_steps.ts";
78 import { TOUR_ASSET_PATH, tourResponse } from "./tour.ts";
7779 import { cspNonce, htmlAnswer, readPage, rewritable, TOOLBAR_ASSET_PATH, TOOLBAR_ASSET_PREFIX, toolbarResponse, withToolbar, type PillWhere } from "./toolbar.ts";
7880 import { COMMENT_ASSET_PATH, commentResponse } from "./toolbar_comment.ts";
7981
@@ -612,6 +614,11 @@ export function pillWhere(
612614 if (!reads || !mayView(db, repo, pull, user)) return where;
613615 where.title = pull.title;
614616 if (row !== undefined && row.headBranch !== "") where.branch = row.headBranch;
617 // A pull that carries a review script offers the guided review on its open preview (#13653).
618 if (row !== undefined && row.state === "open" && row.mergedAt === null) {
619 const steps = stepsOf(db, row);
620 if (steps.length > 0) where.tour = { repo: `${repo.ownerName}/${repo.name}`, pull: row.number, steps };
621 }
615622 const head = getPull(db, target.app.repoId, where.pull);
616623 if (head !== undefined && head.headOid !== "") where.check = pillCheck(db, pull.id, head.headOid);
617624 // How current the preview is: the row's head against the commit it runs. A
@@ -1085,14 +1092,17 @@ export async function proxyApp(
10851092 // only the exact hashed paths are them; any other /__forge/toolbar… path is the forge's 404,
10861093 // never the app's.
10871094 if (url.pathname.startsWith(TOOLBAR_ASSET_PREFIX) && !target.nested) {
1095 const reads = request.method === "GET" || request.method === "HEAD";
10881096 return securityFloor(
1089 request.method !== "GET" && request.method !== "HEAD"
1097 !reads
10901098 ? notFound()
10911099 : url.pathname === TOOLBAR_ASSET_PATH
10921100 ? toolbarResponse(request)
1093 : url.pathname === COMMENT_ASSET_PATH
1094 ? commentResponse(request)
1095 : notFound(),
1101 : url.pathname === TOUR_ASSET_PATH
1102 ? tourResponse(request)
1103 : url.pathname === COMMENT_ASSET_PATH
1104 ? commentResponse(request)
1105 : notFound(),
10961106 );
10971107 }
10981108 // A grant with this forge's own token is answered here. On a nested
src/apps/toolbar.ts +15 −1
@@ -16,6 +16,8 @@
1616
1717 import { staticResponse } from "../web/asset.ts";
1818 import { sha256 } from "../kernel/hash.ts";
19 import { TOUR_ASSET_PATH } from "./tour.ts";
20 import type { ReviewStep } from "../core/review_steps.ts";
1921 import { CHECK_WORDS, type PillCheck } from "./pill_check.ts";
2022 import { NOTE_EMPTY, NOTE_FAILED, NOTE_OFFLINE, NOTE_WAIT } from "./note_words.ts";
2123 import { COMMENT_ASSET_PATH } from "./toolbar_comment.ts";
@@ -727,6 +729,8 @@ export type PillWhere = {
727729 * record.
728730 */
729731 serving?: { oid: string; at: string; change?: string };
732 /** The pull carries a review script: its preview adds the guided review (`apps/tour.ts`). */
733 tour?: TourWhere;
730734 };
731735
732736 /** `text` safe inside a double-quoted HTML attribute. */
@@ -739,6 +743,15 @@ export function escapeAttr(text: string): string {
739743 .replace(/'/g, "&#39;");
740744 }
741745
746 /** What the guided review needs: where its answers go and the steps to walk. */
747 export type TourWhere = { repo: string; pull: number; steps: readonly ReviewStep[] };
748
749 /** The guided review's script tag (`apps/tour.ts`): the steps as escaped data attributes. */
750 export function tourTag(forgeUrl: string, tour: TourWhere, nonce?: string): string {
751 const admitted = nonce === undefined ? "" : ` nonce="${escapeAttr(nonce)}"`;
752 return `<script src="${TOUR_ASSET_PATH}"${admitted} data-forge="${escapeAttr(new URL(forgeUrl).origin)}" data-repo="${escapeAttr(tour.repo)}" data-pull="${tour.pull}" data-steps="${escapeAttr(JSON.stringify(tour.steps))}" defer></script>`;
753 }
754
742755 /**
743756 * The nonce a response's own Content-Security-Policy admits scripts by: from
744757 * `script-src`, or `default-src` when a policy has no `script-src`. Only a
@@ -791,7 +804,8 @@ export function toolbarTag(
791804 const token = proof === undefined ? "" : ` data-proof="${escapeAttr(proof)}"`;
792805 const forge = ` data-forge="${escapeAttr(new URL(forgeUrl).origin)}"`;
793806 const admitted = nonce === undefined ? "" : ` nonce="${escapeAttr(nonce)}"`;
794 return `<script src="${TOOLBAR_ASSET_PATH}"${admitted}${forge}${data}${token} defer></script>`;
807 const tour = where?.tour === undefined ? "" : tourTag(forgeUrl, where.tour, nonce);
808 return `<script src="${TOOLBAR_ASSET_PATH}"${admitted}${forge}${data}${token} defer></script>${tour}`;
795809 }
796810
797811 /**
src/apps/tour.ts added +148
@@ -0,0 +1,148 @@
1 /**
2 * The guided review's client (#13653): one small script the app proxy adds to a pull's preview
3 * pages when the pull carries a review script. Like the pill it is a file on the preview's own
4 * host, content-addressed and immutable, styles itself through the CSSOM (never a `style`
5 * attribute or element) and lives in a closed shadow root. It does nothing until a person opens
6 * the preview from "Review this" (`#forge-review=<step>` in the address) and does nothing on
7 * production: the tag is written only for a pull's preview.
8 *
9 * It walks the steps (`core/review_steps.ts`): loads the step's page, highlights the step's
10 * region and dims the rest, and shows its sentence and question in a card. Each answer is kept in
11 * sessionStorage; at the end the answers go to the forge as a link to its own page, which shows
12 * them and sends them as ONE comment (a mutation the forge checks itself, never from here).
13 */
14
15 import { staticResponse } from "../web/asset.ts";
16 import { sha256 } from "../kernel/hash.ts";
17
18 const tourSource = `(function () {
19 if (window.__forgeTour) return;
20 window.__forgeTour = true;
21 var me = document.currentScript, d = (me && me.dataset) || {}, steps = [], fo = "";
22 try { steps = JSON.parse(d.steps || "[]"); fo = new URL(d.forge || "").origin; } catch (e) {}
23 if (!Array.isArray(steps) || !steps.length || !fo || !/^[\\w.-]+\\/[\\w.-]+$/.test(d.repo || "") || !/^\\d{1,9}$/.test(d.pull || "")) return;
24 var KEY = "forge-review:" + d.pull;
25 var at = /^#forge-review=(\\d{1,2})$/.exec(location.hash);
26 var saved = null;
27 try { saved = JSON.parse(sessionStorage.getItem(KEY) || "null"); } catch (e) {}
28 // Only a person who opened the preview from the pull starts it; a reload resumes it.
29 if (!at && !saved) return;
30 var n = at ? +at[1] : saved.n;
31 if (!(n >= 1 && n <= steps.length + 1)) return;
32 var answers = saved && Array.isArray(saved.a) ? saved.a : [];
33 function keep() { try { sessionStorage.setItem(KEY, JSON.stringify({ n: n, a: answers })); } catch (e) {} }
34 function leave() { try { sessionStorage.removeItem(KEY); } catch (e) {} if (location.hash) history.replaceState(null, "", location.pathname + location.search); host.remove(); }
35 function go(to) {
36 n = to; keep();
37 var s = steps[n - 1];
38 if (s && s.go !== location.pathname + location.search) { location.href = s.go + "#forge-review=" + n; return; }
39 history.replaceState(null, "", location.pathname + location.search + "#forge-review=" + n);
40 draw();
41 }
42 var host = document.createElement("div");
43 host.id = "forge-tour";
44 host.style.cssText = "all:initial;position:fixed;z-index:2147483646;left:0;top:0";
45 var root = host.attachShadow({ mode: "closed" });
46 var mark = document.createElement("div");
47 mark.style.cssText = "position:fixed;pointer-events:none;border-radius:6px;outline:3px solid #8ab4ff;box-shadow:0 0 0 100vmax rgba(13,17,23,.6);display:none";
48 var card = document.createElement("div");
49 card.setAttribute("role", "dialog");
50 card.setAttribute("aria-label", "Guided review");
51 card.tabIndex = -1;
52 card.style.cssText = "position:fixed;left:8px;right:8px;bottom:8px;max-width:420px;box-sizing:border-box;font:14px/1.4 system-ui,sans-serif;color:#fff;background:#1f2328;border-radius:12px;padding:12px;box-shadow:0 2px 8px rgba(0,0,0,.5);display:flex;flex-direction:column;gap:8px;outline:none";
53 root.appendChild(mark);
54 root.appendChild(card);
55 function el(tag, text, css) {
56 var e = document.createElement(tag);
57 if (text) e.textContent = text;
58 if (css) e.style.cssText = css;
59 return e;
60 }
61 var BTN = "all:unset;box-sizing:border-box;cursor:pointer;min-height:44px;padding:0 14px;line-height:44px;text-align:center;border-radius:8px;font-weight:600;color:#fff;";
62 function button(text, bg, fn) {
63 var b = el("button", text, BTN + "background:" + bg);
64 b.type = "button";
65 b.addEventListener("click", fn);
66 b.addEventListener("focus", function () { b.style.outline = "2px solid #8ab4ff"; });
67 b.addEventListener("blur", function () { b.style.outline = ""; });
68 return b;
69 }
70 var target = null;
71 function place() {
72 if (!target || !target.isConnected) { mark.style.display = "none"; return; }
73 var r = target.getBoundingClientRect();
74 mark.style.cssText += ";display:block;left:" + (r.left - 4) + "px;top:" + (r.top - 4) + "px;width:" + (r.width + 8) + "px;height:" + (r.height + 8) + "px";
75 }
76 var queued = false;
77 function soon() { if (queued) return; queued = true; requestAnimationFrame(function () { queued = false; place(); }); }
78 window.addEventListener("scroll", soon, true);
79 window.addEventListener("resize", soon);
80 function answer(v, note) {
81 answers[n - 1] = { v: v, n: note };
82 if (n < steps.length) go(n + 1); else { keep(); n = steps.length + 1; draw(); }
83 }
84 function draw() {
85 card.textContent = "";
86 if (n > steps.length) return finish();
87 var s = steps[n - 1];
88 target = null;
89 try { target = document.querySelector(s.look); } catch (e) {}
90 if (target && target.scrollIntoView) target.scrollIntoView({ block: "center" });
91 place();
92 card.appendChild(el("div", "Step " + n + " of " + steps.length, "font-weight:600;opacity:.85"));
93 card.appendChild(el("div", s.expect));
94 if (s.ask) card.appendChild(el("div", s.ask, "font-weight:600"));
95 if (!target) card.appendChild(el("div", "This page has nothing at " + s.look + ". Say so in your note.", "opacity:.85"));
96 var note = el("textarea", "", "box-sizing:border-box;width:100%;font:16px/1.3 system-ui,sans-serif;padding:8px;border-radius:8px;border:1px solid #57606a;background:#0d1117;color:#fff;resize:vertical");
97 note.maxLength = 200; note.rows = 2;
98 note.setAttribute("aria-label", "A note on this step");
99 note.value = (answers[n - 1] && answers[n - 1].n) || "";
100 card.appendChild(note);
101 var row = el("div", "", "display:flex;gap:8px;flex-wrap:wrap");
102 row.appendChild(button("Works", "#238636", function () { answer("works", note.value); }));
103 row.appendChild(button("Does not work", "#b62324", function () { answer("broken", note.value); }));
104 row.appendChild(button("Skip", "#444c56", function () { answer("skipped", note.value); }));
105 card.appendChild(row);
106 var nav = el("div", "", "display:flex;gap:8px");
107 if (n > 1) nav.appendChild(button("Back", "#444c56", function () { go(n - 1); }));
108 nav.appendChild(button("Leave", "#444c56", leave));
109 card.appendChild(nav);
110 card.focus();
111 }
112 function finish() {
113 target = null; place();
114 var q = [];
115 steps.forEach(function (s, i) {
116 var a = answers[i] || { v: "skipped", n: "" };
117 q.push("v" + (i + 1) + "=" + a.v);
118 if (a.n) q.push("n" + (i + 1) + "=" + encodeURIComponent(a.n));
119 });
120 card.appendChild(el("div", "That was the last step.", "font-weight:600"));
121 card.appendChild(el("div", "The forge shows your answers and sends them to the pull as one comment."));
122 var send = el("a", "Review and send", BTN + "background:#238636;display:block");
123 send.href = fo + "/" + d.repo + "/pulls/" + d.pull + "/review-answers?" + q.join("&");
124 send.rel = "noopener";
125 card.appendChild(send);
126 card.appendChild(button("Back", "#444c56", function () { go(steps.length); }));
127 card.appendChild(button("Leave", "#444c56", leave));
128 card.focus();
129 }
130 card.addEventListener("keydown", function (e) { if (e.key === "Escape") leave(); });
131 document.documentElement.appendChild(host);
132 go(n);
133 })();
134 `;
135
136 /** What is served: the source without its whole-line comments. */
137 export const tourJs = tourSource.replace(/^[ \t]*\/\/[^\n]*\n/gm, "");
138
139 const hash = sha256(tourJs);
140 const name = `toolbar-tour-${hash.slice(0, 16)}`;
141
142 /** The path the script is served from on an app's own host, content-addressed. */
143 export const TOUR_ASSET_PATH = `/__forge/${name}.js`;
144
145 /** The forge's answer for the script: immutable, because its name is its hash. */
146 export function tourResponse(request: Request): Response {
147 return staticResponse(request, tourJs, "text/javascript; charset=utf-8", `"${hash}"`);
148 }
src/contract/openapi/routes/getApiV1ReposOwnerNamePullsNumberReview.ts added +9
@@ -0,0 +1,9 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "get",
5 path: `${REPO}/pulls/{number}/review`,
6 summary: "A pull's guided review: { items: [{ step, go, look, expect, ask, url, link }] }, each with the absolute address of its page in the preview and the forge's deep link; empty when the pull has no script",
7 auth: false,
8 role: "anonymous",
9 };
src/contract/openapi/routes/index.ts +2
@@ -189,6 +189,7 @@ export { route as getApiV1ReposOwnerNamePulls } from "./getApiV1ReposOwnerNamePu
189189 export { route as getApiV1ReposOwnerNamePullsNumber } from "./getApiV1ReposOwnerNamePullsNumber.ts";
190190 export { route as getApiV1ReposOwnerNamePullsNumberChecks } from "./getApiV1ReposOwnerNamePullsNumberChecks.ts";
191191 export { route as getApiV1ReposOwnerNamePullsNumberLooks } from "./getApiV1ReposOwnerNamePullsNumberLooks.ts";
192 export { route as getApiV1ReposOwnerNamePullsNumberReview } from "./getApiV1ReposOwnerNamePullsNumberReview.ts";
192193 export { route as getApiV1ReposOwnerNamePullsNumberReviewStates } from "./getApiV1ReposOwnerNamePullsNumberReviewStates.ts";
193194 export { route as getApiV1ReposOwnerNamePullsNumberReviews } from "./getApiV1ReposOwnerNamePullsNumberReviews.ts";
194195 export { route as getApiV1ReposOwnerNamePullsNumberThreads } from "./getApiV1ReposOwnerNamePullsNumberThreads.ts";
@@ -463,6 +464,7 @@ export { route as putApiV1ReposOwnerNameMilestonesNumberWatch } from "./putApiV1
463464 export { route as putApiV1ReposOwnerNamePullsNumberAssignee } from "./putApiV1ReposOwnerNamePullsNumberAssignee.ts";
464465 export { route as putApiV1ReposOwnerNamePullsNumberHold } from "./putApiV1ReposOwnerNamePullsNumberHold.ts";
465466 export { route as putApiV1ReposOwnerNamePullsNumberLabels } from "./putApiV1ReposOwnerNamePullsNumberLabels.ts";
467 export { route as putApiV1ReposOwnerNamePullsNumberReview } from "./putApiV1ReposOwnerNamePullsNumberReview.ts";
466468 export { route as putApiV1ReposOwnerNameUpstream } from "./putApiV1ReposOwnerNameUpstream.ts";
467469 export { route as putApiV1SecretsScopeName } from "./putApiV1SecretsScopeName.ts";
468470 export { route as putApiV1UserNotify } from "./putApiV1UserNotify.ts";
src/contract/openapi/routes/putApiV1ReposOwnerNamePullsNumberReview.ts added +14
@@ -0,0 +1,14 @@
1 import { REPO, type Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "put",
5 path: `${REPO}/pulls/{number}/review`,
6 summary: "Set a pull's guided review: up to 12 steps { go, look, expect, ask? } replacing the ones it had (a writer's, rw scope); answers { items } as GET does",
7 auth: true,
8 role: "member",
9 body: { steps: "list of { go: path in the preview, look: CSS selector, expect: one sentence, ask?: a question }" },
10 refusals: {
11 invalid_steps: "a step is not acceptable, named in the message (422)",
12 not_open: "the pull is closed or merged (409)",
13 },
14 };
src/core/event_audience.ts +1
@@ -141,6 +141,7 @@ const READER_KINDS: ReadonlySet<string> = new Set([
141141 "account.model_added",
142142 "account.ceiling_set",
143143 "pull.reviewed",
144 "pull.review_steps",
144145 "pull.thread_resolved",
145146 "pull.run_granted",
146147 "pull.guest_approved",
src/core/migration-pins/20261115150000-pull-review-steps.pin added +1
@@ -0,0 +1,1 @@
1 696f408c0c69486c2503f07ec45514de3fd48dfbc4be5980da14ff335009936a
src/core/migrations/20261115150000-pull-review-steps.ts added +11
@@ -0,0 +1,11 @@
1 // A pull's review script (#13653): the ordered steps that take a reviewer into the preview at the
2 // place to test, as one JSON array validated by `core/review_steps.ts`. One row per pull that has
3 // one; no row is no script (the pull's own description may still carry one). Additive.
4 export default `
5 CREATE TABLE IF NOT EXISTS pull_review_steps (
6 issue_id TEXT PRIMARY KEY REFERENCES issue(id) ON DELETE CASCADE,
7 steps TEXT NOT NULL,
8 set_by TEXT NOT NULL,
9 set_at TEXT NOT NULL
10 );
11 `;
src/core/review_steps.ts added +158
@@ -0,0 +1,158 @@
1 /**
2 * A pull's review script (#13653): an ordered list of steps as plain data, each
3 * `{ go, look, expect, ask? }`. `go` is a path in the preview, `look` a CSS selector for the
4 * region to highlight, `expect` one sentence a reviewer can check, `ask` the question to answer.
5 * (`do` is part of the shape but not yet accepted: no scripted clicks in the first pull.)
6 *
7 * Every field is validated at the boundary: a path that stays on the preview's own host, a
8 * selector from a closed alphabet (it is only ever given to `querySelector`), sentences without
9 * control characters. The script is kept per pull, or read from a fenced `review` block in the
10 * pull's description, which is how a builder writes it as part of the pull.
11 */
12
13 import type { Database } from "bun:sqlite";
14 import { err, ok, type Result } from "../kernel/result.ts";
15
16 export interface ReviewStep {
17 readonly go: string;
18 readonly look: string;
19 readonly expect: string;
20 readonly ask?: string;
21 }
22
23 export type StepsError = "not_a_list" | "too_many" | "no_steps" | `step_${number}`;
24
25 /** The most steps a script may hold: three can be walked in a minute, twelve is a long review. */
26 export const STEPS_MAX = 12;
27 const GO_MAX = 200;
28 const LOOK_MAX = 120;
29 const SENTENCE_MAX = 200;
30 const KEYS = new Set(["go", "look", "expect", "ask"]);
31 // A selector's alphabet: names, ids, classes, attributes, combinators; never markup or escapes.
32 const LOOK = /^[A-Za-z0-9_\-#.\[\]=:"'>+~*,() ]+$/;
33 // eslint-disable-next-line no-control-regex
34 const CONTROL = /[\u0000-\u001f\u007f]/;
35
36 function sentence(v: unknown, max: number): string | undefined {
37 if (typeof v !== "string") return undefined;
38 const text = v.trim();
39 if (text === "" || [...text].length > max || CONTROL.test(text)) return undefined;
40 return text;
41 }
42
43 /** A path on the preview's own host: one slash, no scheme, no backslash, no fragment. */
44 export function cleanGo(v: unknown): string | undefined {
45 if (typeof v !== "string" || v.length > GO_MAX || v.length === 0) return undefined;
46 if (!v.startsWith("/") || v.startsWith("//") || v.includes("\\") || v.includes("#")) return undefined;
47 if (CONTROL.test(v) || /\s/.test(v)) return undefined;
48 return v;
49 }
50
51 function oneStep(raw: unknown): ReviewStep | undefined {
52 if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
53 const o = raw as Record<string, unknown>;
54 if (Object.keys(o).some((k) => !KEYS.has(k))) return undefined;
55 const go = cleanGo(o["go"]);
56 const look = sentence(o["look"], LOOK_MAX);
57 const expect = sentence(o["expect"], SENTENCE_MAX);
58 if (go === undefined || look === undefined || expect === undefined || !LOOK.test(look)) return undefined;
59 if (o["ask"] === undefined) return { go, look, expect };
60 const ask = sentence(o["ask"], SENTENCE_MAX);
61 return ask === undefined ? undefined : { go, look, expect, ask };
62 }
63
64 /** The steps a request or a block carries, or the first thing wrong with them. */
65 export function parseSteps(raw: unknown): Result<ReviewStep[], StepsError> {
66 if (!Array.isArray(raw)) return err("not_a_list");
67 if (raw.length === 0) return err("no_steps");
68 if (raw.length > STEPS_MAX) return err("too_many");
69 const out: ReviewStep[] = [];
70 for (let i = 0; i < raw.length; i++) {
71 const one = oneStep(raw[i]);
72 if (one === undefined) return err(`step_${i + 1}` as const);
73 out.push(one);
74 }
75 return ok(out);
76 }
77
78 /** The words for a refusal, for a person and an agent alike. */
79 export function stepsWords(error: StepsError): string {
80 if (error === "not_a_list") return "steps is a list of { go, look, expect, ask? }";
81 if (error === "no_steps") return "give at least one step";
82 if (error === "too_many") return `at most ${STEPS_MAX} steps`;
83 return `${error.replace("_", " ")} needs go (a path starting with /), look (a CSS selector) and expect (one sentence), and ask only if it has a question`;
84 }
85
86 /** The script a description carries in a fenced `review` block, if it holds a valid one. */
87 export function stepsInBody(body: string): ReviewStep[] | undefined {
88 const m = /^```review[ \t]*\r?\n([\s\S]*?)\r?\n```[ \t]*$/m.exec(body);
89 if (m === null || m[1]!.length > 20_000) return undefined;
90 try {
91 const parsed = parseSteps(JSON.parse(m[1]!));
92 return parsed.ok ? parsed.value : undefined;
93 } catch {
94 return undefined;
95 }
96 }
97
98 /**
99 * What a pull's script was last read as, per database: the kept row (null when none) and the
100 * description's block with the body it came from. Pages and the preview's proxy ask for it on
101 * every request, so a read costs no statement and no parse once made. `saveSteps` is the only
102 * writer of the row, so it keeps the entry; a new description body reads again. At most
103 * `CACHE_MAX` pulls, dropped whole past that, and gone on restart.
104 */
105 const CACHE_MAX = 2000;
106 interface Read {
107 kept: ReviewStep[] | null;
108 body: string;
109 block: ReviewStep[] | undefined;
110 }
111 const reads = new WeakMap<Database, Map<string, Read>>();
112
113 function readsOf(db: Database): Map<string, Read> {
114 let m = reads.get(db);
115 if (m === undefined) reads.set(db, (m = new Map()));
116 if (m.size >= CACHE_MAX) m.clear();
117 return m;
118 }
119
120 /** Keep a pull's script, replacing the one it had. */
121 export function saveSteps(db: Database, issueId: string, by: string, steps: readonly ReviewStep[]): void {
122 db.query(
123 `INSERT INTO pull_review_steps (issue_id, steps, set_by, set_at) VALUES (?, ?, ?, ?)
124 ON CONFLICT(issue_id) DO UPDATE SET steps = excluded.steps, set_by = excluded.set_by, set_at = excluded.set_at`,
125 ).run(issueId, JSON.stringify(steps), by, new Date().toISOString());
126 const known = readsOf(db).get(issueId);
127 if (known !== undefined) known.kept = [...steps];
128 }
129
130 function readKept(db: Database, id: string): ReviewStep[] | null {
131 const row = db.query<{ steps: string }, [string]>("SELECT steps FROM pull_review_steps WHERE issue_id = ?").get(id);
132 if (row === null) return null;
133 try {
134 const kept = parseSteps(JSON.parse(row.steps));
135 return kept.ok ? kept.value : null;
136 } catch {
137 return null; // A damaged row reads as none; the description may still have one.
138 }
139 }
140
141 /** A pull's script: the one kept for it, else the one its description carries, else none. */
142 export function stepsOf(db: Database, pull: { id: string; body: string }): ReviewStep[] {
143 const cache = readsOf(db);
144 let r = cache.get(pull.id);
145 if (r === undefined) {
146 r = { kept: readKept(db, pull.id), body: pull.body, block: stepsInBody(pull.body) };
147 cache.set(pull.id, r);
148 } else if (r.body !== pull.body) {
149 r.body = pull.body;
150 r.block = stepsInBody(pull.body);
151 }
152 return r.kept ?? r.block ?? [];
153 }
154
155 /** The path one step's deep link takes: `/<owner>/<name>/pulls/<n>/review/<step>`. */
156 export function stepPath(base: string, number: number, step: number): string {
157 return `${base}/pulls/${number}/review/${step}`;
158 }
src/http/api.ts +26
@@ -114,6 +114,8 @@ import {
114114 } from "../actions/pulls.ts";
115115 import { landSlice } from "../actions/pull_slices.ts";
116116 import { attachLook } from "../actions/attach_look.ts";
117 import { reviewSteps, setReviewSteps } from "../actions/review_steps.ts";
118 import { stepsWords } from "../core/review_steps.ts";
117119 import { lookUrl } from "../core/looks.ts";
118120 import { pullFit, pullLooks } from "../looks/readable.ts";
119121 import { holdPull, releasePull } from "../actions/holds.ts";
@@ -3157,6 +3159,30 @@ export function apiRoutes(router: Router<Handler>): void {
31573159 },
31583160 );
31593161
3162 // A pull's review script (#13653): the steps that take a reviewer, person or agent, into the
3163 // preview at the place to test, each with the absolute address of its page.
3164 router.add("GET", "/api/v1/repos/:owner/:name/pulls/:number/review", (ctx) => {
3165 const found = loadPull(ctx);
3166 if ("error" in found) return found.error;
3167 return json({ items: reviewSteps(ctx.app, ctx.auth.user, found.repo, found.pull) });
3168 });
3169
3170 // Set it: a writer's, on an open pull; the steps replace the ones it had.
3171 router.add("PUT", "/api/v1/repos/:owner/:name/pulls/:number/review", async (ctx) => {
3172 const denied = requireScope(ctx, "rw");
3173 if (denied) return denied;
3174 const found = loadPull(ctx);
3175 if ("error" in found) return found.error;
3176 const input = await body(ctx.request);
3177 const set = setReviewSteps(ctx.app, ctx.auth.user, found.repo, found.pull, input.steps);
3178 if (!set.ok) {
3179 const e = set.error;
3180 if (e === "unauthorized" || e === "forbidden" || e === "not_found") return respondAccess(e, 422);
3181 return json({ error: e === "not_open" ? e : "invalid_steps", message: e === "not_open" ? "the pull is not open" : stepsWords(e) }, e === "not_open" ? 409 : 422);
3182 }
3183 return json({ items: reviewSteps(ctx.app, ctx.auth.user, found.repo, found.pull) });
3184 });
3185
31603186 // Line-anchored review comments. The anchor is (path, side, line) in the
31613187 // pull's current diff; the server takes the content hash, so a client never
31623188 // handles one — and a later force-push marks the comment `outdated`.
src/http/server.ts +4
@@ -337,6 +337,7 @@ import { templatesPage } from "../web/pages/templates.ts";
337337 import { askedPage } from "../web/studio/asked_page.ts";
338338 import { notesOverrule, notesSave, notesView } from "../web/pages/notes.ts";
339339 import { reviewPage } from "../web/studio/review_page.ts";
340 import { reviewAnswersPage, reviewAnswersSend, reviewStepOpen } from "../web/studio/review_guide.ts";
340341 import { reviewAct } from "../web/studio/review_act.ts";
341342 import {
342343 asksBulkSubmit,
@@ -1491,6 +1492,9 @@ export function buildRouter(): Router<Handler> {
14911492 router.add("GET", "/:owner/:name/pulls/:number/checks-line", pullChecksFragment);
14921493 router.add("GET", "/:owner/:name/standing-line", standingFragment);
14931494 router.add("POST", "/:owner/:name/pulls/:number/comments", pullCommentSubmit);
1495 router.add("GET", "/:owner/:name/pulls/:number/review/:step", reviewStepOpen);
1496 router.add("GET", "/:owner/:name/pulls/:number/review-answers", reviewAnswersPage);
1497 router.add("POST", "/:owner/:name/pulls/:number/review-answers", reviewAnswersSend);
14941498 router.add("POST", "/:owner/:name/pulls/:number/review", pullReviewSubmit);
14951499 // The verdict on the change as a whole, and the threads it settles.
14961500 router.add(
src/web/pages/apps.ts +14 −1
@@ -12,6 +12,7 @@
1212 * 404 for everyone.
1313 */
1414
15 import { stepsOf } from "../../core/review_steps.ts";
1516 import { USERNAME_PATTERN } from "../username_pattern.ts";
1617 import { sshOn } from "../../settings/ssh.ts";
1718 import { runnerSettings } from "../../crew/runner_env.ts";
@@ -771,12 +772,17 @@ export function previewBlock(ctx: Ctx, repo: Repo, pull: Pull): Html {
771772 : pull.state === "closed"
772773 ? "The preview was removed when this closed. Reopen the pull request and it comes back."
773774 : "No preview yet — one starts when this pull request's head deploys.";
774 return previewSection(html`<p class="muted small">${why}</p>`, head);
775 const waiting = stepsOf(ctx.app.db, pull).length;
776 return previewSection(
777 html`<p class="muted small">${why}</p>${waiting === 0 || pull.state !== "open" ? null : html`<p class="muted small">This pull carries a guided review of ${waiting} ${waiting === 1 ? "step" : "steps"}; "Review this" appears here once the preview is up.</p>`}`,
778 head,
779 );
775780 }
776781 // A preview's terminal is a different login from production's — its own
777782 // command, shown only to a writer, same as the app page's.
778783 const writer = canWrite(ctx.app.db, repo, ctx.auth.user);
779784 const dataNote = previewDataNote(view.value.app.previewData, pull.createdAt);
785 const guide = stepsOf(ctx.app.db, pull).length;
780786 return previewSection(
781787 html`${envFacts(base, env)}
782788 ${dataNote === null ? null : html`<p class="muted small">${dataNote}</p>`}
@@ -797,6 +803,13 @@ export function previewBlock(ctx: Ctx, repo: Repo, pull: Pull): Html {
797803 variant: "outline",
798804 icon: "external",
799805 })}
806 ${guide === 0 || env.dormant !== undefined || pull.state !== "open"
807 ? null
808 : btn("Review this", {
809 href: `${base}/pulls/${pull.number}/review/1`,
810 size: "sm",
811 icon: "play",
812 })}
outdated

Principle 1 (and 8): this sentence repeats the button and the earlier waiting note. Say it once. Also add a test covering this button.

800813 </div>`,
801814 head,
802815 envTone(env),
src/web/studio/review_guide.ts added +90
@@ -0,0 +1,90 @@
1 /**
2 * A guided review's pages on the forge (#13653): a step's deep link, which opens the pull's
3 * preview at that step's place with the tour on, and the answers page, which shows what a reviewer
4 * walked and sends it back to the pull as ONE comment. The script itself is plain data on the pull
5 * (`core/review_steps.ts`); the tour is a script the preview's proxy adds (`apps/tour.ts`).
6 */
7
8 import { openEnvUrl } from "../../actions/apps.ts";
9 import { readAnswers, sendReviewAnswers } from "../../actions/review_steps.ts";
10 import { previewEnv } from "../../apps/data.ts";
11 import { stepPath, stepsOf } from "../../core/review_steps.ts";
12 import type { Ctx } from "../../http/context.ts";
13 import { notFoundPage, repoBase, signInFirst, signInHref } from "../chrome.ts";
14 import { field, readForm } from "../form.ts";
15 import { html, type Html } from "../html.ts";
16 import { flashTo, page } from "../layout.ts";
17 import { btn } from "../ui.ts";
18 import { pullContext } from "./change.ts";
19
20 /** GET /:owner/:name/pulls/:number/review/:step — open the preview at that step, tour on. */
21 export function reviewStepOpen(ctx: Ctx): Response {
outdated

Duplicate of stepPath in core/review_steps.ts; remove it and use that one.

22 const found = pullContext(ctx);
23 if (found instanceof Response) return found;
24 const { repo, pull } = found;
25 const steps = stepsOf(ctx.app.db, pull);
26 const raw = ctx.params["step"] ?? "";
27 const n = /^\d{1,2}$/.test(raw) ? Number(raw) : 0;
28 const step = steps[n - 1];
29 if (step === undefined) return notFoundPage(ctx);
30 const link = openEnvUrl(ctx.app, ctx.auth.user, repo, previewEnv(pull.number), step.go);
31 if (!link.ok) {
32 if (link.error === "unauthorized") return signInFirst(ctx);
33 return notFoundPage(ctx);
34 }
35 return new Response(null, {
36 status: 302,
37 headers: {
38 location: `${link.value}#forge-review=${n}`,
39 "cache-control": "no-store",
40 "referrer-policy": "no-referrer",
41 },
42 });
43 }
44
45 const WORD = { works: "Works", broken: "Does not work", skipped: "Not tried" } as const;
outdated

Medium: no-referrer-when-downgrade leaks the forge URL (and any grant in the redirect target) to the preview. Use no-referrer.

46
47 /** GET /:owner/:name/pulls/:number/review-answers — the walked answers, to read and send. */
48 export function reviewAnswersPage(ctx: Ctx): Response {
49 const found = pullContext(ctx);
50 if (found instanceof Response) return found;
51 const { repo, pull } = found;
52 const steps = stepsOf(ctx.app.db, pull);
53 const answers = readAnswers(steps.length, (k) => ctx.url.searchParams.get(k));
54 if (steps.length === 0 || answers === undefined) return notFoundPage(ctx);
55 const base = repoBase(repo);
56 const rows: Html[] = steps.map((s, i) => {
57 const a = answers[i]!;
58 return html`<li><strong>${WORD[a.verdict]}</strong> · <a href="${stepPath(base, pull.number, i + 1)}">Step ${i + 1}</a>: ${s.expect}${a.note === "" ? "" : html`<br><span class="muted">${a.note}</span>`}</li>`;
59 });
60 const hidden = answers.map((a, i) => html`<input type="hidden" name="v${i + 1}" value="${a.verdict}"><input type="hidden" name="n${i + 1}" value="${a.note}">`);
61 const body = html`<h1>Your review of #${pull.number}</h1>
62 <p class="muted">${pull.title}</p>
63 <ol>${rows}</ol>
64 ${ctx.auth.user === undefined
65 ? html`<p><a href="${signInHref(ctx)}">Sign in to send it</a></p>`
66 : html`<form method="post" action="${base}/pulls/${pull.number}/review-answers">${hidden}
67 <p class="muted small">Sent as one comment on the pull, each answer tied to its step.</p>
68 ${btn("Send as one comment", { icon: "check" })}</form>`}`;
69 return page({ ctx, title: `Your review of #${pull.number}`, body });
70 }
71
72 /** POST /:owner/:name/pulls/:number/review-answers — the one comment. */
73 export async function reviewAnswersSend(ctx: Ctx): Promise<Response> {
74 const found = pullContext(ctx);
75 if (found instanceof Response) return found;
76 if (!ctx.auth.user) return signInFirst(ctx);
77 const form = await readForm(ctx, "rw");
78 if (form instanceof Response) return form;
79 const { repo, pull } = found;
80 const dest = `${repoBase(repo)}/pulls/${pull.number}`;
81 const steps = stepsOf(ctx.app.db, pull);
82 const answers = readAnswers(steps.length, (k) => {
83 const v = field(form, k);
84 return v === "" ? null : v;
85 });
86 if (answers === undefined) return flashTo(ctx, dest, { tone: "danger", message: "Those answers could not be read." });
87 const sent = await sendReviewAnswers(ctx.app, ctx.auth.user, repo, pull, answers);
88 if (!sent.ok) return flashTo(ctx, dest, { tone: "danger", message: "The review could not be sent." });
89 return flashTo(ctx, `${dest}#conversation`, { message: "Review sent as one comment." });
90 }
test/no-polling.test.ts +1
@@ -328,6 +328,7 @@ const NOT_WALKED: Record<string, string> = {
328328 "/runs/:id": "the seed creates no run",
329329 "/signin/access/:token": "needs a one-time access link an admin minted",
330330 "/settings/features/:slug": "needs a feature slug",
331 "/:owner/:name/pulls/:number/review/:step": "needs a pull carrying review steps, which the seed has none of",
331332 "/settings/origins/:id/archived": ORIGIN,
332333 "/settings/origins/:id/mirror/:job": ORIGIN,
333334 "/settings/origins/:id/repos": ORIGIN,
test/open-routes-floor.test.ts +1 −1
@@ -41,7 +41,7 @@ const FILL: Readonly<Record<string, string>> = {
4141 ref: "main", branch: "main", oid: "0".repeat(40), sha: "0".repeat(40), commit: "0".repeat(40),
4242 // Not seeded: each still has to answer its not-found with the floor.
4343 team: "core", env: "prod", file: "README.md", label: "v1", chapter: "1", kind: "desktop", machine: "web",
44 op: "x", group: "a", version: "1", slug: "board", receipt: "r", token: "t", code: "c", spec: "16", stage: "build",
44 op: "x", step: "1", group: "a", version: "1", slug: "board", receipt: "r", token: "t", code: "c", spec: "16", stage: "build",
4545 };
4646
4747 /** Open GET routes that cannot be filled in from a seeded public repository, each with why. */
test/pages-budget.test.ts +3
@@ -74,6 +74,9 @@ const FIXTURE: Record<string, string> = {
7474 "/:owner/:name/issues/:number": "/alice/forge/issues/1",
7575 "/api/v1/repos/:owner/:name/issues/:number/estimates": "/api/v1/repos/alice/forge/issues/1/estimates",
7676 "/:owner/:name/pulls/:number": "/alice/forge/pulls/2",
77 "/:owner/:name/pulls/:number/review/:step": "/alice/forge/pulls/2/review/1",
78 "/:owner/:name/pulls/:number/review-answers": "/alice/forge/pulls/2/review-answers",
79 "/api/v1/repos/:owner/:name/pulls/:number/review": "/api/v1/repos/alice/forge/pulls/2/review",
7780 "/:owner/:name/display": "/alice/forge/display",
7881 "/api/v1/admin/machines/:machine/disks": "/api/v1/admin/machines/rack1/disks",
7982 "/claim/start/:token": "/claim/start/claim_fixture",
test/review-steps.test.ts added +313
@@ -0,0 +1,313 @@
1 /**
2 * A guided review (#13653): a pull carries steps; the API reads them; a step's deep
3 * link opens the preview with the tour on; the answers go back as ONE comment tied to the steps;
4 * and the preview's page gets the tour's tag only when the pull has a script.
5 */
6
7 import { afterAll, beforeAll, describe, expect, spyOn, 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 { openPull } from "../src/actions/pulls.ts";
12 import { commitToBranch, createRepo } from "../src/actions/repos.ts";
13 import { answersComment, readAnswers } from "../src/actions/review_steps.ts";
14 import { createApp, type App } from "../src/app.ts";
15 import { AppsRuntime, type EnvStatus } from "../src/apps/runtime.ts";
16 import { tourJs, tourResponse, TOUR_ASSET_PATH } from "../src/apps/tour.ts";
17 import { toolbarTag, tourTag } from "../src/apps/toolbar.ts";
18 import { createApp as insertApp, getAppByRepo } from "../src/core/apps.ts";
19 import { pillWhere, type AppTarget } from "../src/apps/proxy.ts";
20 import { listComments } from "../src/core/issues.ts";
21 import type { Pull } from "../src/core/pulls.ts";
22 import type { Repo } from "../src/core/repos.ts";
23 import { parseSteps, saveSteps, stepsInBody, stepsOf } from "../src/core/review_steps.ts";
24 import { createToken } from "../src/core/tokens.ts";
25 import { createUser, type User } from "../src/core/users.ts";
26 import { serve, type Servers } from "../src/http/server.ts";
27 import { quietLogs } from "./helpers/globals.ts";
28
29 quietLogs();
30
31 const STEPS = [
32 { go: "/", look: "main h1", expect: "The heading says Hello", ask: "Is it readable?" },
33 { go: "/about?x=1", look: "#team", expect: "The team list shows three people" },
34 { go: "/contact", look: "form.contact > button", expect: "Send is enabled" },
35 ];
36
37 describe("the shape of a review script", () => {
38 test("a good script reads and a bad one names its step", () => {
39 expect(parseSteps(STEPS).ok).toBe(true);
40 const bad = (step: object) => {
41 const r = parseSteps([STEPS[0], step]);
42 return r.ok ? "ok" : r.error;
43 };
44 expect(bad({ go: "https://evil.example/", look: "a", expect: "x" })).toBe("step_2");
45 expect(bad({ go: "//evil.example/", look: "a", expect: "x" })).toBe("step_2");
46 expect(bad({ go: "/a#frag", look: "a", expect: "x" })).toBe("step_2");
47 expect(bad({ go: "/a", look: "a<script>", expect: "x" })).toBe("step_2");
48 expect(bad({ go: "/a", look: "a\\3c", expect: "x" })).toBe("step_2");
49 expect(bad({ go: "/a", look: "a", expect: "x\ny" })).toBe("step_2");
50 expect(bad({ go: "/a", look: "a", expect: "x", do: "click" })).toBe("step_2");
51 expect(bad({ go: "/a", look: "a", expect: "" })).toBe("step_2");
52 const many = parseSteps(Array.from({ length: 13 }, () => STEPS[0]));
53 expect(many.ok ? "ok" : many.error).toBe("too_many");
54 expect(parseSteps([]).ok).toBe(false);
55 expect(parseSteps("x").ok).toBe(false);
56 });
57
58 test("a builder's fenced block in the description is the script", () => {
59 const body = `Did a thing.\n\n\`\`\`review\n${JSON.stringify(STEPS)}\n\`\`\`\n`;
60 expect(stepsInBody(body)).toEqual(STEPS);
61 expect(stepsInBody("```review\nnot json\n```")).toBeUndefined();
62 expect(stepsInBody("no block")).toBeUndefined();
63 });
64 });
65
66 describe("the answers", () => {
67 test("one comment, each answer tied to its step; the note is one line", () => {
68 const get = (k: string) => ({ v1: "works", v2: "broken", n2: "list\nhas two", v3: "skipped" })[k] ?? null;
69 const answers = readAnswers(3, get)!;
70 const text = answersComment("/a/b", 7, STEPS, answers);
71 expect(text).toContain("1 of 3 steps work, 1 do not, 1 not tried.");
72 expect(text).toContain("[Step 2](/a/b/pulls/7/review/2) — does not work. Expected: The team list shows three people");
73 expect(text).toContain("Note: list has two");
74 expect(text).toContain("Asked: Is it readable?");
75 });
76
77 test("an unknown verdict is refused", () => {
78 expect(readAnswers(1, (k) => (k === "v1" ? "great" : null))).toBeUndefined();
79 });
80 });
81
82 describe("the tour's tag", () => {
83 const tour = { repo: "a/b", pull: 3, steps: [{ go: "/", look: "h1", expect: 'say "hi" <b>' }] };
84 test("is written only with a script, escaped, and points at a content-addressed file", () => {
85 const where = { app: "b", env: "pull-3", pull: 3 };
86 expect(toolbarTag("https://forge.test", where)).not.toContain("toolbar-tour");
87 const tag = toolbarTag("https://forge.test", { ...where, tour });
88 expect(tag).toContain(`<script src="${TOUR_ASSET_PATH}"`);
89 expect(tag).not.toContain("<b>");
90 expect(tag).toContain("&lt;b&gt;");
91 expect(tourTag("https://forge.test/x", tour, "abc")).toContain('nonce="abc"');
92 });
93 test("is served immutable, by its hash", async () => {
94 const res = tourResponse(new Request(`http://x${TOUR_ASSET_PATH}`));
95 expect(await res.text()).toBe(tourJs);
96 expect(res.headers.get("cache-control")).toBe("public, max-age=31536000, immutable");
97 });
98 test("does nothing until opened from the pull and builds no markup from data", () => {
99 expect(tourJs).toContain("#forge-review=");
100 expect(tourJs).toContain("if (!at && !saved) return;");
101 expect(tourJs).not.toMatch(/innerHTML|eval\(|setAttribute\("style"|insertAdjacentHTML/);
102 });
103 });
104
105 describe("a pull with a script, over the API and the page", () => {
106 let dataDir: string;
107 let app: App;
108 let servers: Servers;
109 let runtime: AppsRuntime;
110 let alice: User;
111 let bob: User;
112 let repo: Repo;
113 let pull: Pull;
114 const tokens: Record<string, string> = {};
115 const url = (p: string) => `${servers.url}/api/v1/repos/alice/garden/pulls/${pull.number}/${p}`;
116 const send = (method: string, token: string | null, p: string, payload?: unknown) =>
117 fetch(url(p), {
118 method,
119 headers: { "content-type": "application/json", ...(token === null ? {} : { authorization: `Bearer ${token}` }) },
120 ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
121 });
122 const signIn = async (username: string): Promise<string> => {
123 const r = await fetch(`${servers.url}/signin`, {
124 method: "POST",
125 body: new URLSearchParams({ username, password: "a-good-passphrase" }),
126 redirect: "manual",
127 });
128 return (r.headers.get("set-cookie") ?? "").split(";")[0]!;
129 };
130
131 beforeAll(async () => {
132 dataDir = await mkdtemp(join(tmpdir(), "forge-review-steps-"));
133 app = createApp({ dataDir, port: 0, host: "forge.test" });
134 servers = await serve(app);
135 runtime = new AppsRuntime(app, { domain: "apps.test", scheme: "http", publicPort: servers.port, forgeUrl: servers.url, concurrency: 1 });
136 await runtime.start();
137 const person = async (username: string): Promise<User> => {
138 const made = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: "a-good-passphrase", adminIfFirst: username === "alice" });
139 if (!made.ok) throw new Error(made.error);
140 return made.value;
141 };
142 alice = await person("alice");
143 bob = await person("bob");
144 const made = await createRepo(app, alice, { name: "garden", visibility: "public" });
145 if (!made.ok) throw new Error(String(made.error));
146 repo = made.value;
147 await commitToBranch(app, alice, repo, { message: "seed", files: [{ path: "README.md", content: "# g\n" }] });
148 await commitToBranch(app, alice, repo, { branch: "one", base: "main", message: "one", files: [{ path: "one.md", content: "x\n" }] });
149 const opened = await openPull(app, alice, repo, { title: "Change one", body: "", baseBranch: "main", headBranch: "one" });
150 if (!opened.ok) throw new Error(String(opened.error));
151 pull = opened.value;
152 const inserted = insertApp(app.db, { repoId: repo.id, slug: "garden", access: "public" });
153 if (!inserted.ok) throw new Error(inserted.error);
154 tokens["alice"] = createToken(app.db, alice.id, "t", "rw").token;
155 tokens["aliceRo"] = createToken(app.db, alice.id, "t", "ro").token;
156 tokens["bob"] = createToken(app.db, bob.id, "t", "rw").token;
157 }, 120_000);
158
159 afterAll(async () => {
160 await runtime.stop();
161 servers.stop();
162 app.close();
163 await rm(dataDir, { recursive: true, force: true });
164 });
165
166 test("before any script there are no steps and no door to them", async () => {
167 const res = await send("GET", null, "review");
168 expect(((await res.json()) as any).items).toEqual([]);
169 expect((await fetch(`${servers.url}/alice/garden/pulls/${pull.number}/review/1`)).status).toBe(404);
170 });
171
172 test("only a writer with a read-write token sets it; a bad script is refused whole", async () => {
173 expect((await send("PUT", null, "review", { steps: STEPS })).status).toBe(401);
174 expect((await send("PUT", tokens["bob"]!, "review", { steps: STEPS })).status).toBe(403);
175 expect((await send("PUT", tokens["aliceRo"]!, "review", { steps: STEPS })).status).toBe(403);
176 const bad = await send("PUT", tokens["alice"]!, "review", { steps: [STEPS[0], { go: "http://x/", look: "a", expect: "b" }] });
177 expect(bad.status).toBe(422);
178 expect(((await bad.json()) as any).message).toContain("step 2");
179 expect(stepsOf(app.db, pull)).toEqual([]);
180 });
181
182 test("a set script is read back with each step's address, over the API", async () => {
183 const set = await send("PUT", tokens["alice"]!, "review", { steps: STEPS });
184 expect(set.status).toBe(200);
185 const got = (await (await send("GET", null, "review")).json()) as any;
186 expect(got.items.map((i: any) => i.step)).toEqual([1, 2, 3]);
187 expect(got.items[1].go).toBe("/about?x=1");
188 expect(got.items[1].link).toBe(`/alice/garden/pulls/${pull.number}/review/2`);
189 expect(got.items[0].ask).toBe("Is it readable?");
190 expect(got.items[1].ask).toBeNull();
191 expect(got.items[1].url).toContain("/about?x=1");
192 });
193
194 test("a step's deep link opens the preview at its path with the tour on", async () => {
195 const res = await fetch(`${servers.url}/alice/garden/pulls/${pull.number}/review/2`, { redirect: "manual" });
196 expect(res.status).toBe(302);
197 const to = res.headers.get("location")!;
198 expect(to).toContain(`garden--${pull.number}.`);
199 expect(to.endsWith("/about?x=1#forge-review=2")).toBe(true);
200 expect((await fetch(`${servers.url}/alice/garden/pulls/${pull.number}/review/4`)).status).toBe(404);
201 expect((await fetch(`${servers.url}/alice/garden/pulls/${pull.number}/review/x`)).status).toBe(404);
202 });
203
204 test("the preview's pill carries the tour for an open pull's preview, never for production", () => {
205 const record = getAppByRepo(app.db, repo.id)!;
206 const who = { id: alice.id, name: "alice", role: "user" } as const;
207 const preview = pillWhere(runtime, { app: record, env: `pull-${pull.number}` } as AppTarget, who);
208 expect(preview.tour?.repo).toBe("alice/garden");
209 expect(preview.tour?.steps).toHaveLength(3);
210 expect(pillWhere(runtime, { app: record, env: "production" } as AppTarget, who).tour).toBeUndefined();
211 });
212
213 test("the pull's page says it carries a guided review", async () => {
214 const html = await (await fetch(`${servers.url}/alice/garden/pulls/${pull.number}`)).text();
215 expect(html.includes("a guided review of 3 steps")).toBe(true);
216 expect(html.includes("once the preview is up")).toBe(true);
217 expect(html.includes(">Review this<")).toBe(false);
218 expect(html.split("guided review of 3").length).toBe(2);
219 });
220
221 test("with its preview up the pull offers 'Review this' once, and the waiting note is gone", async () => {
222 const spy = spyOn(AppsRuntime.prototype, "status").mockImplementation(
223 (): EnvStatus[] => [{ env: `pull-${pull.number}`, state: "running", commitOid: pull.headOid, url: "", port: 1 } as EnvStatus],
224 );
225 try {
226 const html = await (await fetch(`${servers.url}/alice/garden/pulls/${pull.number}`)).text();
227 expect(html.includes(`href="/alice/garden/pulls/${pull.number}/review/1"`)).toBe(true);
228 expect(html.includes("Review this")).toBe(true);
229 expect(html.includes("once the preview is up")).toBe(false);
230 expect(html.includes("guided review of")).toBe(false);
231 } finally {
232 spy.mockRestore();
233 }
234 });
235
236 test("the step's deep link refuses a referrer", async () => {
237 const r = await fetch(`${servers.url}/alice/garden/pulls/${pull.number}/review/1`, { redirect: "manual" });
238 if (r.status === 302) expect(r.headers.get("referrer-policy")).toBe("no-referrer");
239 });
240
241 test("the comment sets the writer's words as plain text, not markdown", () => {
242 const body = answersComment("/a/b", 1, [{ go: "/", look: "a", expect: "[x](https://evil.example) **bold** @bob", ask: "<b>hi</b>" }], [{ verdict: "works", note: "`code` *it*" }]);
243 expect(body).not.toContain("[x](");
244 expect(body).toContain("\\[x\\]\\(https\\:");
245 expect(body).toContain("\\*\\*bold\\*\\* \\@bob");
246 expect(body).toContain("\\<b\\>hi");
247 expect(body).toContain("\\`code\\` \\*it\\*");
248 });
249
250 test("a read costs no statement once made, and a set or a new description is seen", () => {
251 const counted = { n: 0 };
252 const real = app.db.query.bind(app.db);
253 const spy = spyOn(app.db, "query").mockImplementation((sql: string) => { counted.n++; return real(sql); });
254 try {
255 stepsOf(app.db, pull);
256 const before = counted.n;
257 for (let i = 0; i < 5; i++) stepsOf(app.db, pull);
258 expect(counted.n).toBe(before);
259 } finally {
260 spy.mockRestore();
261 }
262 const only = [STEPS[0]!];
263 saveSteps(app.db, pull.id, "alice", only);
264 expect(stepsOf(app.db, pull)).toEqual(only);
265 saveSteps(app.db, pull.id, "alice", STEPS);
266 expect(stepsOf(app.db, pull)).toEqual(STEPS);
267 });
268
269 test("the answers page shows what was walked, and one post makes one comment", async () => {
270 const q = "v1=works&v2=broken&n2=only%20two&v3=skipped";
271 const page = `${servers.url}/alice/garden/pulls/${pull.number}/review-answers`;
272 const shown = await (await fetch(`${page}?${q}`)).text();
273 expect(shown).toContain("only two");
274 expect(shown).toContain("Does not work");
275 expect((await fetch(`${page}?v1=great`)).status).toBe(404);
276
277 const cookie = await signIn("bob");
278 const before = listComments(app.db, pull.id, {}).length;
279 // A post from another origin is refused and writes nothing.
280 const cross = await fetch(page, {
281 method: "POST",
282 headers: { cookie, origin: "https://evil.example" },
283 body: new URLSearchParams({ v1: "works", v2: "works", v3: "works" }),
284 redirect: "manual",
285 });
286 expect(cross.status).toBeGreaterThanOrEqual(400);
287 expect(listComments(app.db, pull.id, {}).length).toBe(before);
288
289 const sent = await fetch(page, {
290 method: "POST",
291 headers: { cookie, origin: servers.url },
292 body: new URLSearchParams({ v1: "works", v2: "broken", n2: "only two", v3: "skipped" }),
293 redirect: "manual",
294 });
295 expect(sent.status).toBe(303);
296 const comments = listComments(app.db, pull.id, {});
297 expect(comments.length).toBe(before + 1);
298 const one = comments.at(-1)!;
299 expect(one.authorName).toBe("bob");
300 expect(one.body).toContain("1 of 3 steps work, 1 do not, 1 not tried.");
301 expect(one.body).toContain("Note: only two");
302 });
303
304 test("a stranger cannot send answers", async () => {
305 const r = await fetch(`${servers.url}/alice/garden/pulls/${pull.number}/review-answers`, {
306 method: "POST",
307 body: new URLSearchParams({ v1: "works" }),
308 redirect: "manual",
309 });
310 expect(r.status).toBeGreaterThanOrEqual(300);
311 expect(r.status).not.toBe(200);
312 });
313 });
test/security-floor-routes.test.ts +1
@@ -90,6 +90,7 @@ const UNSEEDED: Record<string, string> = {
9090 "/:owner/:name/builds/:label/shots/:file": SHOT,
9191 "/:owner/:name/looks/:env/:commit/:kind.png": LOOK,
9292 "/:owner/:name/milestones/:number/limb/:op": LIMB,
93 "/:owner/:name/pulls/:number/review/:step": "needs a pull with a review script, which the seed does not write (test/review-steps.test.ts covers it)",
9394 "/:owner/:name/variants/:group": VARIANT,
9495 "/:owner/:name/waves/:version": WAVE,
9596 "/api/v1/boards/:slug/panels/:id": BOARD,

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs