src/approval-executor.ts

Functions

Imports

It imports src/auto-merge-policy.ts, src/doc-statements.ts, src/env.ts, src/github/refs.ts, src/merge-class.ts, src/time.ts. Imported by src/auto-merge-tick.ts, src/merge-safety.ts, src/trends.ts.

Source

1import { ciGreenOn, type PrFacts } from "./auto-merge-policy";
2import type { Env } from "./env";
3import { HeadMovedError, managePr } from "./github/refs";
4import { systemAudit } from "./doc-statements";
5import type { Classification } from "./merge-class";
6import { DAY_MS } from "./time";
7
8// THE EXECUTOR (docs/design/design-merge-pipeline.md section 4, PR 4; Dustin's DECIDE of
9// 2026-10-09: approvals void on a new push, red CI or 7 days). The auto-merge tick
10// (src/auto-merge-tick.ts) calls it for a pull request the signed policy did not merge and
11// that holds an open approval (src/pr-approvals.ts). In order:
12//   1. the head is not the approved sha: void, "new push";
13//   2. the approval is older than 7 days: expire;
14//   3. CI on that sha, by the policy's own ci_green test (ciGreenOn): not finished waits,
15//      red voids, "CI red", and a namespace with no required steps refuses;
16//   4. a head off the base repo, a base that is not the default branch, or a money path
17//      approved without its typed confirmation refuses;
18//   5. otherwise managePr merge pinned to the approved sha: a 409 voids, "head moved", and
19//      success moves the row to merged with the merge sha.
20// It is the only thing that merges an approved pull request. Every state move is
21// `UPDATE ... WHERE id = ? AND status = 'approved' RETURNING id`
22// (path mutation invariant, test/path-mutation.test.ts), in one batch with its audit row, written as SYSTEM_ACTOR (src/doc-statements.ts) like the tick's own rows.
23
24const APPROVAL_DAYS = 7;
25
26export interface OpenApproval {
27  id: number;
28  pr: number;
29  head_sha: string;
30  class: string;
31  approved_by: string;
32  surface: string;
33  batch_id: string | null;
34  approved_at: string;
35}
36
37/** The open approvals on one repo, by pull request number. */
38export async function readOpenApprovals(db: D1Database, repo: string): Promise<Map<number, OpenApproval>> {
39  const { results } = await db
40    .prepare(
41      `SELECT id, pr, head_sha, class, approved_by, surface, batch_id, approved_at FROM pr_approvals
42       WHERE repo = ?1 AND status = 'approved'`
43    )
44    .bind(repo)
45    .all<OpenApproval>();
46  return new Map((results ?? []).map((r) => [r.pr, r]));
47}
48
49export type ExecutorResult =
50  | { done: "merged"; merge_sha: string | null; why: string }
51  | { done: "voided" | "expired" | "refused"; why: string }
52  | { done: "waiting"; why: string };
53
54const AUDIT: Record<"voided" | "expired" | "refused" | "merged", string> = {
55  voided: "pr-approval-voided",
56  expired: "pr-approval-expired",
57  refused: "pr-approval-refused",
58  merged: "approved-merged",
59};
60
61/** One state move and its audit row, in one batch. False when the row had already moved. */
62async function close(
63  env: Env,
64  namespace: string,
65  approval: OpenApproval,
66  facts: Pick<PrFacts, "repo" | "number" | "headSha">,
67  status: "voided" | "expired" | "refused" | "merged",
68  reason: string,
69  now: Date,
70  mergeSha: string | null = null
71): Promise<boolean> {
72  const at = now.toISOString();
73  const [moved] = await env.DB.batch([
74    env.DB.prepare(`UPDATE pr_approvals SET status = ?2, closed_at = ?3, close_reason = ?4, merge_sha = ?5 WHERE id = ?1 AND status = 'approved' RETURNING id`).bind(
75      approval.id,
76      status,
77      at,
78      reason,
79      mergeSha
80    ),
81    systemAudit(env.DB, AUDIT[status], namespace, {
82      repo: facts.repo,
83      pr: facts.number,
84      approved_sha: approval.head_sha,
85      head_sha: facts.headSha,
86      class: approval.class,
87      approved_by: approval.approved_by,
88      surface: approval.surface,
89      batch_id: approval.batch_id,
90      reason,
91      ...(mergeSha ? { merge_sha: mergeSha } : {}),
92      at,
93    }),
94  ]);
95  return (moved?.results?.length ?? 0) > 0;
96}
97
98/** Acts on one open approval of a pull request the policy left open. */
99export async function executeApproval(
100  env: Env,
101  namespace: string,
102  facts: PrFacts,
103  classified: Classification | null,
104  approval: OpenApproval,
105  now: Date
106): Promise<ExecutorResult> {
107  const end = async (done: "voided" | "expired" | "refused", why: string): Promise<ExecutorResult> => {
108    await close(env, namespace, approval, facts, done, why, now);
109    return { done, why };
110  };
111  if (facts.headSha !== approval.head_sha) {
112    return end("voided", `new push: approved at ${approval.head_sha.slice(0, 7)}, the head is ${facts.headSha.slice(0, 7)} now`);
113  }
114  if (now.getTime() - Date.parse(approval.approved_at) > APPROVAL_DAYS * DAY_MS) {
115    return end("expired", `approved ${APPROVAL_DAYS} days ago or more without merging`);
116  }
117  const ci = ciGreenOn(facts);
118  if (ci.state === "wait") return { done: "waiting", why: ci.why };
119  if (ci.state === "red") return end("voided", `CI red: ${ci.why}`);
120  if (ci.state === "never") return end("refused", ci.why);
121  if (facts.headRepo === null || facts.headRepo.toLowerCase() !== facts.repo.toLowerCase()) {
122    return end("refused", "head_in_base_repo: the head is not on the base repo");
123  }
124  if (facts.baseRef !== facts.defaultBranch) {
125    return end("refused", `base_is_default_branch: the base is ${facts.baseRef}, not ${facts.defaultBranch}`);
126  }
127  // A money path is approved only by typing (design section 8). The class is read again
128  // from this tick's files, so a pull request that became one since is not merged on an
129  // approval that never typed it.
130  if (classified?.class === "typed" && approval.surface !== "typed") {
131    return end("refused", "a money path, approved without its typed confirmation");
132  }
133  let mergeSha: string | null;
134  try {
135    // merge_method "merge", as the tick's own merges, so the approved sha stays in history;
136    // pinned to it, so a push since this read gets a 409 and nothing merges.
137    const result = (await managePr(env, namespace, facts.number, "merge", "merge", undefined, undefined, approval.head_sha)) as { sha?: string };
138    mergeSha = result.sha ?? null;
139  } catch (err) {
140    if (!(err instanceof HeadMovedError)) throw err;
141    return end("voided", `head moved: GitHub refused the merge pinned to ${approval.head_sha.slice(0, 7)}`);
142  }
143  const why = `merged on the approval of ${approval.approved_by} (${approval.surface}) at ${approval.head_sha.slice(0, 7)}`;
144  await close(env, namespace, approval, facts, "merged", why, now, mergeSha);
145  return { done: "merged", merge_sha: mergeSha, why };
146}
147
148// The reason on the approved-merged audit row closeAsAutoMerged writes. The same merge
149// also has its auto-merged row, so src/trends.ts reads this to count the merge once.
150export const AUTO_MERGED_APPROVAL_REASON = "the signed policy merged it on its own";
151
152/** A pull request the policy merged on its own: its open approval is closed as merged. */
153export async function closeAsAutoMerged(env: Env, namespace: string, facts: PrFacts, approval: OpenApproval, mergeSha: string | null, now: Date): Promise<void> {
154  await close(env, namespace, approval, facts, "merged", AUTO_MERGED_APPROVAL_REASON, now, mergeSha);
155}
156
157/** Every approval older than 7 days, on any pull request, open or not: expired. The tick
158 *  sees only open pull requests, so one closed or merged by hand would otherwise stay open. */
159export async function expireStaleApprovals(env: Env, now: Date): Promise<number> {
160  const at = now.toISOString();
161  const { results } = await env.DB.prepare(
162    `UPDATE pr_approvals SET status = 'expired', closed_at = ?1, close_reason = ?2 WHERE status = 'approved' AND approved_at < ?3 RETURNING id, repo, pr, head_sha`
163  )
164    .bind(at, `approved ${APPROVAL_DAYS} days ago or more without merging`, new Date(now.getTime() - APPROVAL_DAYS * DAY_MS).toISOString())
165    .all<{ id: number; repo: string; pr: number; head_sha: string }>();
166  const rows = results ?? [];
167  if (rows.length) {
168    await env.DB.batch(rows.map((r) => systemAudit(env.DB, "pr-approval-expired", null, { repo: r.repo, pr: r.pr, approved_sha: r.head_sha, reason: "7 days", at })));
169  }
170  return rows.length;
171}