src/pr-approvals.ts

Functions

Imports

It imports src/auto-merge-tick.ts, src/env.ts, src/github/client.ts, src/store-guards.ts. Imported by src/controls-perform.ts, src/controls-plan.ts.

Source

1import { AWAITING_SEAT_KEY, type AwaitingSeat } from "./auto-merge-tick";
2import type { Env } from "./env";
3import { ghFetch, resolveRepo } from "./github/client";
4import { auditStatement } from "./store-guards";
5
6// THE APPROVAL RECORD (docs/design/design-merge-pipeline.md section 3, PR 3; Dustin's
7// DECIDE of 2026-10-09). The `approve_pr` control (src/controls.ts) records that Dustin
8// approved one or more pull requests at the head sha he saw; it never merges. The
9// executor in the auto-merge tick (PR 4) merges an approved pull request once its CI is
10// green on that sha, and voids the approval on a new push, red CI or after 7 days.
11//
12// What may be approved is what the tick classed (src/merge-class.ts) into the
13// awaiting-seat set: `approve` (and `auto`, which the tick merges anyway). `typed`, any
14// money path, only alone and only with its number typed as confirm (design section 8:
15// never batched, never automatic). `seat` and `wait`, and a pull request the tick has not
16// classed, are refused. A batch holding one refused pull request is refused whole, so
17// nothing is half-approved.
18//
19// Every write is in one D1 batch: a void of the pull request's open approval, if any
20// (`UPDATE ... WHERE id = ? AND status = 'approved' RETURNING id`, path mutation
21// invariant, test/path-mutation.test.ts), the new row, and an audit row for each.
22
23const MAX_PRS = 20;
24const SHA = /^[0-9a-f]{7,40}$/;
25
26export interface ApprovalParams {
27  namespace?: string;
28  repo?: string;
29  prs?: string;
30  shas?: string;
31  confirm?: string;
32  reason?: string;
33  undo?: string;
34}
35
36interface OpenApproval {
37  id: number;
38  pr: number;
39  head_sha: string;
40}
41
42/** One pull request as the plan found it. */
43interface Target {
44  number: number;
45  head_sha: string;
46  class: string;
47  // The tick's path class for it (src/merge-class.ts), the unit promotion counts in
48  // (src/merge-units.ts). Null on an undo, which writes no row.
49  path_class: string | null;
50  open: OpenApproval | null;
51}
52
53export type ApprovalPlan =
54  | { ok: true; repo: string; namespace: string; undo: boolean; surface: "portal" | "chat" | "typed"; targets: Target[]; changes: string[]; audit: string[] }
55  | { ok: false; refusal: string };
56
57function numbers(raw: string | undefined): number[] | string {
58  const parts = (raw ?? "").split(/[\s,]+/).filter(Boolean);
59  if (!parts.length) return "approve_pr needs prs: the pull request numbers, comma-separated (\"312,315\").";
60  if (parts.length > MAX_PRS) return `approve_pr takes at most ${MAX_PRS} pull requests at once; got ${parts.length}.`;
61  const out: number[] = [];
62  for (const p of parts) {
63    if (!/^[1-9][0-9]{0,9}$/.test(p)) return `'${p}' is not a pull request number.`;
64    if (out.includes(Number(p))) return `#${p} is named twice.`;
65    out.push(Number(p));
66  }
67  return out;
68}
69
70async function awaitingSet(env: Env): Promise<AwaitingSeat[] | string> {
71  try {
72    const raw = await env.APP_KV.get(AWAITING_SEAT_KEY);
73    return raw ? (JSON.parse(raw) as AwaitingSeat[]) : [];
74  } catch (err) {
75    return `the awaiting-seat set could not be read (${err instanceof Error ? err.message : String(err)}), so no class is known and nothing is approved.`;
76  }
77}
78
79/** A pull request's head and state, read from GitHub now, never from a cache. */
80async function readHead(env: Env, owner: string, repo: string, number: number): Promise<{ sha: string; state: string; merged: boolean } | string> {
81  const resp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/pulls/${number}`);
82  if (!resp.ok) return `#${number} could not be read from GitHub (${resp.status}).`;
83  const pr = (await resp.json()) as { head?: { sha?: string }; state?: string; merged?: boolean };
84  if (!pr.head?.sha) return `#${number}: GitHub answered with no head sha.`;
85  return { sha: pr.head.sha, state: pr.state ?? "unknown", merged: pr.merged === true };
86}
87
88/** What approve_pr (or its Undo) will do, from the state now. Reads only. */
89export async function planApproval(env: Env, actor: string, p: ApprovalParams, surface: "portal" | "chat", click: string): Promise<ApprovalPlan> {
90  const refused = (refusal: string): ApprovalPlan => ({ ok: false, refusal });
91  const undo = p.undo === "true";
92  if (!p.namespace) return refused("approve_pr needs the namespace whose repo holds the pull requests.");
93  const nums = numbers(p.prs);
94  if (typeof nums === "string") return refused(nums);
95  let owner: string, name: string, full: string;
96  try {
97    ({ owner, repo: name, full } = await resolveRepo(env, p.namespace, p.repo));
98  } catch (err) {
99    return refused(err instanceof Error ? err.message : String(err));
100  }
101  const { results } = await env.DB.prepare(`SELECT id, pr, head_sha FROM pr_approvals WHERE repo = ?1 AND status = 'approved'`).bind(full).all<OpenApproval>();
102  const openBy = new Map((results ?? []).map((r) => [r.pr, r]));
103
104  if (undo) {
105    const missing = nums.filter((n) => !openBy.has(n));
106    if (missing.length) return refused(`${missing.map((n) => `#${n}`).join(", ")} ${missing.length === 1 ? "has" : "have"} no open approval to undo: it was merged, voided or never approved.`);
107    const targets = nums.map((n) => ({ number: n, head_sha: openBy.get(n)!.head_sha, class: "", path_class: null, open: openBy.get(n)! }));
108    return {
109      ok: true,
110      repo: full,
111      namespace: p.namespace,
112      undo: true,
113      surface,
114      targets,
115      changes: targets.map((t) => `${full}#${t.number}: the approval at ${t.head_sha.slice(0, 7)} -> voided, "undone". The executor will not merge it.`),
116      audit: [`pr-approval-voided by ${actor}`, click],
117    };
118  }
119
120  const shas = (p.shas ?? "").split(/[\s,]+/).filter(Boolean);
121  const awaiting = await awaitingSet(env);
122  if (typeof awaiting === "string") return refused(awaiting);
123  const heads = await Promise.all(nums.map((n) => readHead(env, owner, name, n)));
124  const problems: string[] = [];
125  const targets: Target[] = [];
126  nums.forEach((n, i) => {
127    const head = heads[i]!;
128    if (typeof head === "string") return void problems.push(head);
129    if (head.merged || head.state !== "open") return void problems.push(`#${n} is ${head.merged ? "merged" : head.state}, not open.`);
130    const seen = shas[i];
131    // The head Dustin saw, named by the caller: a push since then is a change nobody approved.
132    if (!seen) return void problems.push(`#${n} needs the head sha you reviewed (shas, in the order of prs). Its head is ${head.sha} now.`);
133    if (!SHA.test(seen) || !head.sha.startsWith(seen)) return void problems.push(`#${n}'s head is ${head.sha}, not ${seen}: something was pushed since you looked. Review it again.`);
134    const row = awaiting.find((a) => a.repo === full && a.number === n);
135    const cls = row?.class ?? null;
136    if (!row || !cls) return void problems.push(`#${n} has no class: the tick has not classed it into the awaiting-seat set yet, so nothing says what kind of approval it needs.`);
137    if (cls === "seat") return void problems.push(`#${n} is class seat (${(row.class_reasons ?? []).join("; ") || "a step outside a merge"}): it stays with the seat.`);
138    if (cls === "wait") return void problems.push(`#${n} is class wait (${(row.class_reasons ?? []).join("; ") || "CI or draft"}): nobody acts yet.`);
139    targets.push({ number: n, head_sha: head.sha, class: cls, path_class: row.path_class ?? null, open: openBy.get(n) ?? null });
140  });
141  if (problems.length) return refused(`${nums.length > 1 ? "Nothing in the batch was approved. " : ""}${problems.join(" ")}`);
142  const typed = targets.filter((t) => t.class === "typed");
143  if (typed.length && targets.length > 1) {
144    return refused(`${typed.map((t) => `#${t.number}`).join(", ")} touches a money path (class typed), which is never batched. Nothing in the batch was approved; approve it alone, with its number typed as confirm.`);
145  }
146  if (typed.length && p.confirm !== String(typed[0]!.number)) {
147    return refused(`#${typed[0]!.number} touches a money path (class typed): type its number as confirm to approve it.`);
148  }
149  const replaced = targets.filter((t) => t.open);
150  return {
151    ok: true,
152    repo: full,
153    namespace: p.namespace,
154    undo: false,
155    surface: typed.length ? "typed" : surface,
156    targets,
157    changes: [
158      ...targets.map((t) => `${full}#${t.number} (class ${t.class}): approved at ${t.head_sha.slice(0, 7)}. The executor merges it once CI is green on that sha; a new push, red CI or 7 days voids it.`),
159      ...replaced.map((t) => `${full}#${t.number}: the earlier approval at ${t.open!.head_sha.slice(0, 7)} -> voided, "replaced".`),
160      "Nothing is merged now: approve_pr never merges.",
161    ],
162    audit: [`pr-approved by ${actor}`, ...(replaced.length ? [`pr-approval-voided by ${actor}`] : []), click],
163  };
164}
165
166/** The writes of a plan, in one batch. Returns the result's one-line summary. */
167export async function performApproval(env: Env, actor: string, plan: Extract<ApprovalPlan, { ok: true }>, reason: string | null, now: Date): Promise<string> {
168  const at = now.toISOString();
169  const batchId = plan.targets.length > 1 ? crypto.randomUUID() : null;
170  const statements: D1PreparedStatement[] = [];
171  const voids = plan.undo ? plan.targets : plan.targets.filter((t) => t.open);
172  const voidAt: number[] = [];
173  for (const t of voids) {
174    voidAt.push(statements.length);
175    statements.push(
176      env.DB.prepare(`UPDATE pr_approvals SET status = 'voided', closed_at = ?2, close_reason = ?3 WHERE id = ?1 AND status = 'approved' RETURNING id`).bind(
177        t.open!.id,
178        at,
179        plan.undo ? "undone" : "replaced"
180      ),
181      auditStatement(env.DB, actor, "pr-approval-voided", plan.namespace, null, { repo: plan.repo, pr: t.number, head_sha: t.open!.head_sha, close_reason: plan.undo ? "undone" : "replaced" })
182    );
183  }
184  if (!plan.undo) {
185    for (const t of plan.targets) {
186      statements.push(
187        env.DB.prepare(
188          `INSERT INTO pr_approvals (repo, pr, head_sha, class, status, approved_by, surface, batch_id, reason, approved_at, namespace, path_class)
189           VALUES (?1, ?2, ?3, ?4, 'approved', ?5, ?6, ?7, ?8, ?9, ?10, ?11)`
190        ).bind(plan.repo, t.number, t.head_sha, t.class, actor, plan.surface, batchId, reason, at, plan.namespace, t.path_class),
191        auditStatement(env.DB, actor, "pr-approved", plan.namespace, null, { repo: plan.repo, pr: t.number, head_sha: t.head_sha, class: t.class, surface: plan.surface, batch_id: batchId })
192      );
193    }
194  }
195  const results = await env.DB.batch(statements);
196  // Each void must have moved its row: one that did not was merged, voided or replaced
197  // between the preview and now, and the batch's other rows are already written.
198  const moved = voidAt.filter((i) => (results[i]?.results?.length ?? 0) > 0).length;
199  const nums = plan.targets.map((t) => `#${t.number}`).join(", ");
200  if (plan.undo) return `Undid the approval of ${plan.repo} ${nums}${moved < voids.length ? ` (${voids.length - moved} had already ended)` : ""}.`;
201  return `Approved ${plan.repo} ${nums}. The executor merges ${plan.targets.length === 1 ? "it" : "each"} once CI is green on the approved sha.`;
202}