src/review.ts

Functions

Imports

It imports src/agents-schema.ts, src/env.ts, src/github/client.ts, src/github/pr-files.ts. Imported by src/jobs-holder.ts.

Source

1// A job posted with review_required does not reach the seat until a reviewer has
2// given a verdict on its pull request.
3//
4// The verdict is a comment, not a GitHub review, because the reviewer agent holds only
5// can_comment_pr; accepting a GitHub review would need a wider scope. The envelope is
6// strict, `REVIEW:` at the start and one of three words at the end, so no verdict is
7// guessed out of free prose.
8
9import type { Env } from "./env";
10import { ghFetch, parsePrUrl, resolveRepo, type PrUrl } from "./github/client";
11import { readAllPages } from "./github/pr-files";
12import { parseScopes } from "./agents-schema";
13
14const REVIEW_PREFIX = "REVIEW:";
15
16export const VERDICTS = ["APPROVE", "CHANGES", "BLOCK"] as const;
17type Verdict = (typeof VERDICTS)[number];
18
19export interface ReviewComment {
20  // GitHub's issue-comment id. The gate counts a verdict only when Capsid posted this
21  // id for an actor holding can_comment_pr (see reviewerCommentIds). A comment with no
22  // id is never eligible.
23  id?: number;
24  // The author login, recorded for the audit row. Not the check: every comment Capsid
25  // posts has the same App author.
26  user: string;
27  body: string;
28  created_at: string;
29}
30
31export interface Review {
32  verdict: Verdict;
33  by: string;
34  at: string;
35  // The comment with its envelope stripped.
36  said: string;
37}
38
39/** The verdict a single comment carries, or null when it is not a review. Both the
40 *  prefix and the closing verdict word are required. */
41export function verdictOf(comment: ReviewComment): Review | null {
42  const body = comment.body?.trim() ?? "";
43  if (!body.toUpperCase().startsWith(REVIEW_PREFIX)) return null;
44  const rest = body.slice(REVIEW_PREFIX.length).trim();
45  // The last word, allowing trailing punctuation and formatting ("CHANGES.", "**BLOCK**").
46  const tail = rest.replace(/[\s*_`.!]+$/u, "");
47  const match = /([A-Za-z]+)$/u.exec(tail);
48  if (!match) return null;
49  const word = match[1].toUpperCase();
50  if (!(VERDICTS as readonly string[]).includes(word)) return null;
51  return {
52    verdict: word as Verdict,
53    by: comment.user,
54    at: comment.created_at,
55    said: tail.slice(0, tail.length - match[1].length).replace(/[\s*_`,:-]+$/u, "").trim(),
56  };
57}
58
59/** The review that decides: the newest verdict, by created_at rather than array
60 *  position, because GitHub's ordering is not promised. */
61export function decidingReview(comments: readonly ReviewComment[]): Review | null {
62  let best: Review | null = null;
63  let bestAt = Number.NEGATIVE_INFINITY;
64  for (const comment of comments) {
65    const review = verdictOf(comment);
66    if (!review) continue;
67    const at = Date.parse(review.at);
68    // An unparseable timestamp counts only when nothing else does.
69    const rank = Number.isNaN(at) ? Number.NEGATIVE_INFINITY : at;
70    if (best === null || rank >= bestAt) {
71      best = review;
72      bestAt = rank;
73    }
74  }
75  return best;
76}
77
78export type ReviewOutcome =
79  // No review yet. The job stays where it is.
80  | { kind: "waiting"; reason: string }
81  // The seat may have it.
82  | { kind: "proceed"; review: Review }
83  // Back to the driver, and it costs a correction.
84  | { kind: "rework"; review: Review }
85  // Stopped for the seat, with the reviewer's objection as the reason.
86  | { kind: "halt"; review: Review };
87
88/** What a job with review_required does when its driver tries to hand it on. Pure,
89 *  so every branch is tested without GitHub. */
90export function outcomeOf(review: Review | null): ReviewOutcome {
91  if (!review) {
92    return {
93      kind: "waiting",
94      reason:
95        `no review yet. This job was posted with review_required, so it waits for a comment on its pull request ` +
96        `starting with '${REVIEW_PREFIX}' and ending with ${VERDICTS.join(", ")}. An APPROVE must also quote the pull request's head sha.`,
97    };
98  }
99  switch (review.verdict) {
100    case "APPROVE":
101      return { kind: "proceed", review };
102    case "CHANGES":
103      return { kind: "rework", review };
104    case "BLOCK":
105      return { kind: "halt", review };
106  }
107}
108
109// The issue comments endpoint lists oldest first and has no direction parameter, so
110// the newest review is on the last page and every page is read.
111const COMMENT_MAX_PAGES = 30;
112
113/** Every comment on a pull request. Issue comments, not review comments, because
114 *  capsid_open_pr action `comment` posts there. Throws when the list cannot be read
115 *  whole, which the caller treats as an unread review rather than an approval. */
116export async function readReviewComments(
117  env: Env,
118  pr: PrUrl
119): Promise<ReviewComment[]> {
120  const read = await readAllPages(
121    env, pr.owner, pr.repo, `/repos/${pr.owner}/${pr.repo}/issues/${pr.number}/comments`,
122    (page) => page as Array<{ id?: number; user?: { login?: string }; body?: string; created_at?: string }>, COMMENT_MAX_PAGES
123  );
124  if (read.problem) throw new Error(`reading review comments failed: ${read.problem}`);
125  return read.items.map((r) => ({
126    id: typeof r.id === "number" ? r.id : undefined,
127    user: r.user?.login ?? "(unknown)",
128    body: r.body ?? "",
129    created_at: r.created_at ?? "",
130  }));
131}
132
133/** The pull request's current head sha, read so an APPROVE counts only for the code it
134 *  names. Throws on a GitHub failure, which the caller treats as an unread review
135 *  rather than an approval. */
136async function readHeadSha(env: Env, pr: PrUrl): Promise<string> {
137  const resp = await ghFetch(env, pr.owner, pr.repo, `/repos/${pr.owner}/${pr.repo}/pulls/${pr.number}`);
138  if (!resp.ok) throw new Error(`reading the pull request failed (${resp.status}): ${(await resp.text()).slice(0, 200)}`);
139  const sha = ((await resp.json()) as { head?: { sha?: string } }).head?.sha ?? "";
140  if (!/^[0-9a-f]{40}$/i.test(sha)) throw new Error(`the pull request reported no head commit`);
141  return sha;
142}
143
144// The shortest sha prefix a review may quote, as `git log --oneline` prints.
145const MIN_QUOTED_SHA = 7;
146
147/** Whether a review's text quotes `head`: some standalone run of 7 to 40 hex
148 *  characters in it is a prefix of the head sha (case-insensitive). */
149function quotesSha(text: string, head: string): boolean {
150  const want = head.toLowerCase();
151  for (const token of text.match(new RegExp(`\\b[0-9a-f]{${MIN_QUOTED_SHA},40}\\b`, "gi")) ?? []) {
152    if (want.startsWith(token.toLowerCase())) return true;
153  }
154  return false;
155}
156
157// Owner and repo compare case-insensitively because GitHub resolves them that way.
158function samePr(a: PrUrl, b: PrUrl): boolean {
159  return a.number === b.number && `${a.owner}/${a.repo}`.toLowerCase() === `${b.owner}/${b.repo}`.toLowerCase();
160}
161
162// How far back the eligibility scan reads, in audit rows for one namespace.
163const REVIEWER_AUDIT_SCAN = 500;
164
165/** The issue-comment ids Capsid posted for an actor allowed to review, in a namespace.
166 *
167 *  The identity half of the gate, read from audit_log rather than off the comment:
168 *  `capsid_open_pr` action `comment` posts through the App installation, so every comment
169 *  Capsid writes has the same author login and the login cannot separate a reviewer's
170 *  verdict from a driver's. What does separate them is who asked Capsid to post it,
171 *  which the audit row records beside the comment_id.
172 *
173 *  A verdict counts when Capsid posted it and the actor that asked held
174 *  can_comment_pr. A driver with local `gh` can still write `REVIEW: ... APPROVE` on
175 *  the pull request, but it is not a review, because nothing in this set names it; with
176 *  newest-wins it would otherwise also overwrite a real CHANGES.
177 *
178 *  A non-agent actor (the admin session or the legacy operator key) has unrestricted
179 *  scopes and counts: a human reviewing by hand is a case this gate exists to allow. */
180async function reviewerCommentIds(db: D1Database, namespace: string): Promise<Set<number>> {
181  const rows = await db
182    .prepare(
183      `SELECT a.actor AS actor, a.params AS params, COALESCE(g.scopes, x.scopes) AS scopes
184         FROM audit_log a
185         LEFT JOIN agents g ON g.name = substr(a.actor, 7)
186         LEFT JOIN agents_archive x ON x.name = substr(a.actor, 7)
187        WHERE a.action = 'manage_pr' AND a.namespace = ?1 AND a.params LIKE '%"comment_id":%'
188        ORDER BY a.id DESC
189        LIMIT ?2`
190    )
191    .bind(namespace, REVIEWER_AUDIT_SCAN)
192    .all<{ actor: string; params: string; scopes: string | null }>();
193  const ids = new Set<number>();
194  for (const row of rows.results ?? []) {
195    if (row.actor?.startsWith("agent:")) {
196      // An agent with no row in either table fails closed. An archived one is judged
197      // on the scopes it held, as it was before it moved (src/agents-archive.ts).
198      if (!row.scopes || !parseScopes(row.scopes).flags.can_comment_pr) continue;
199    }
200    let commentId: unknown;
201    try {
202      commentId = (JSON.parse(row.params) as { comment_id?: unknown }).comment_id;
203    } catch {
204      continue;
205    }
206    if (typeof commentId === "number") ids.add(commentId);
207  }
208  return ids;
209}
210
211/** The gate, end to end: what the review says about this job's pull request. A job
212 *  with no pull request proceeds unless requirePullRequest is set. */
213export type GateOutcome = ReviewOutcome & {
214  // The pull request the gate read, so the caller can bind the job to it.
215  pr?: string;
216};
217
218export async function reviewGate(
219  env: Env,
220  // The stored result_ref. On a claimed job only the gate writes it, so a pull request
221  // URL there is the job's own, bound the first time the gate read one.
222  job: { namespace: string; review_required: number; result_ref: string | null },
223  opts: {
224    // Set on `complete` only; see reviewRefusal in src/jobs.ts for why.
225    requirePullRequest?: boolean;
226    // The references this call names: its result_ref, then a complete's evidence.prs.
227    candidateRefs?: readonly (string | null | undefined)[];
228  } = {}
229): Promise<GateOutcome | null> {
230  if (!job.review_required) return null;
231  let named: PrUrl | null = null;
232  for (const ref of opts.candidateRefs ?? []) {
233    named = parsePrUrl(ref);
234    if (named) break;
235  }
236  // Bound to the job's own pull request: once the gate has read one, a call naming a
237  // different one is refused, so a CHANGES cannot be escaped with an older approval.
238  const bound = parsePrUrl(job.result_ref);
239  if (bound && named && !samePr(bound, named)) {
240    return {
241      kind: "waiting",
242      reason:
243        `bound to ${job.result_ref}, the pull request its review gate first read, and this call names ` +
244        `https://github.com/${named.owner}/${named.repo}/pull/${named.number}. A review of a different pull request does not review this job's work.`,
245    };
246  }
247  const pr = bound ?? named;
248  if (!pr) {
249    if (!opts.requirePullRequest) return null;
250    return {
251      kind: "waiting",
252      reason:
253        `posted with review_required and names no pull request. Pass the pull request URL as result_ref, or in evidence.prs, ` +
254        `so that a reviewer has something to read. A job that must be reviewed cannot be handed on with a document key, ` +
255        `because that would let the driver decide whether the review applied.`,
256    };
257  }
258  // Resolved through the namespace mapping, the authorization boundary, as prFacts does.
259  let target: PrUrl;
260  let url: string;
261  try {
262    const resolved = await resolveRepo(env, job.namespace, `${pr.owner}/${pr.repo}`);
263    target = { owner: resolved.owner, repo: resolved.repo, number: pr.number };
264    url = `https://github.com/${resolved.full}/pull/${pr.number}`;
265  } catch (err) {
266    return {
267      kind: "waiting",
268      reason:
269        `naming a pull request the review gate may not read: ${err instanceof Error ? err.message : String(err)} ` +
270        `Name a pull request in a repo that namespace ${job.namespace} maps.`,
271    };
272  }
273  const comments = await readReviewComments(env, target);
274  const eligible = await reviewerCommentIds(env.DB, job.namespace);
275  const review = decidingReview(comments.filter((c) => c.id !== undefined && eligible.has(c.id)));
276  // An APPROVE counts only when it quotes the current head sha, so a push after the
277  // review needs a fresh one. A sha, not a committer date, which the committer sets.
278  // CHANGES and BLOCK need no sha.
279  if (review?.verdict === "APPROVE") {
280    const head = await readHeadSha(env, target);
281    if (!quotesSha(review.said, head)) {
282      return {
283        kind: "waiting",
284        reason:
285          `approved without quoting the current head of ${url}, which is ${head}. An APPROVE counts only when its ` +
286          `${REVIEW_PREFIX} comment quotes the head sha it reviewed (at least ${MIN_QUOTED_SHA} hex characters), so this needs a fresh review.`,
287        pr: url,
288      };
289    }
290  }
291  return { ...outcomeOf(review), pr: url };
292}