src/auto-merge-policy.ts

Functions

Imports

It imports src/env.ts, src/roster.ts, src/scope.ts, src/signed-docs.ts. Imported by src/approval-executor.ts, src/auto-merge-tick.ts, src/complete-ci.ts, src/maintenance-prs.ts, src/merge-class.ts, src/merge-safety.ts, src/model-routing.ts, src/ops-feed.ts, src/policy-sign.ts, src/status.ts, src/whats-next.ts.

Source

1import type { Env } from "./env";
2import { onRoster } from "./roster";
3import { isMoneyPath } from "./scope";
4import { POLICY_ID_ITEM, policyField, readSignedPolicy } from "./signed-docs";
5
6// What the Worker may merge without a human, and where that list lives. The document
7// is capsid/policy/auto-merge.md, signed with the same key and envelope as a task
8// document, because it decides whether this Worker may write to a default branch that
9// deploys on push. An unsigned or edited policy merges nothing.
10//
11// The document names the checks and the code enforces them. A policy document parsed
12// into predicates would be a configuration language, and a change to it would be a
13// code change nobody reviewed as one. So the document carries the version, whether the
14// policy is enabled and which namespaces it covers, and it names every check by id,
15// every refused path pattern and every required CI step. The code holds the same three
16// lists. test/auto-merge.test.ts asserts the two agree in both directions, and
17// loadMergePolicy refuses at run time as well, because the test proves the pair in the
18// repo while the document lives in the database.
19//
20// One list lives only in the document: the PR author allowlist. The code has no copy
21// to compare it with, so it is a value the signature governs, and a document without
22// one does not load.
23export const AUTO_MERGE_POLICY_PATH = "policy/auto-merge.md";
24
25// Every check, in the order evaluated. Each one refuses on its own. The three path
26// checks run first because they are the never list: a change to one of those paths is
27// not merged without a human, whatever the rest of the PR looks like.
28//
29// Job ids are public, in commit subjects and PR bodies, so judging only the job a PR
30// body names would let any open PR that named a finished job merge on green CI.
31// The PR itself is judged too: head_in_base_repo refuses a fork head, job_handed_on
32// refuses a job that is not blocked or done, and pr_recorded_for_job refuses a PR the
33// holder never recorded against that job.
34//
35// pr_author_allowed refuses a PR whose GitHub author login is not on the allowlist the
36// signed document carries. The list is in the document and not here, so changing who
37// may author an unattended merge is a signed act.
38//
39// Version 7 (job_e68de044f8a4; Dustin, 2026-10-10, plan step 2) drops author_is_driver,
40// which required the job to have been claimed by a minted driver agent. Cloud sessions
41// sign in as the admin login and complete a job without a claim, naming its pull request
42// (src/jobs-seat.ts completeUnclaimed), so nothing they opened could merge. Who may open
43// an unattended merge stays pr_author_allowed's question, and pr_recorded_for_job still
44// requires the pull request to be recorded against the job by whoever completed it. The
45// same version adds size_within_cap: a pull request over AUTO_MERGE_SIZE_CAP changed lines
46// waits for a person's approval.
47export const POLICY_CHECKS = [
48  "paths_not_refused",
49  "paths_not_money",
50  "no_migration_workflow_lockfile",
51  "paths_allowed_for_namespace",
52  "head_in_base_repo",
53  "body_names_job",
54  "pr_author_allowed",
55  "job_handed_on",
56  "pr_recorded_for_job",
57  "base_is_default_branch",
58  "size_within_cap",
59  "ci_green",
60] as const;
61
62export type PolicyCheck = (typeof POLICY_CHECKS)[number];
63
64// The most changed lines (additions plus deletions, as GitHub counts them) a pull request
65// may carry and still merge with no human. Over it, the merge class is approve: one tap,
66// with the reason "over the size cap". Ona caps its auto-approval at 1,000 lines, and
67// Intercom's agent refuses large pull requests; a big diff is where a review earns its time.
68export const AUTO_MERGE_SIZE_CAP = 1000;
69
70/** Whether a pull request's changed lines are over the size cap. Uncounted is not over it;
71 *  the policy refuses an uncounted pull request on its own. */
72export const overSizeCap = (facts: Pick<PrFacts, "changedLines">): boolean => facts.changedLines !== null && facts.changedLines > AUTO_MERGE_SIZE_CAP;
73
74/** The reason a pull request over the cap carries, in the merge class and the decline. */
75export const sizeCapReason = (facts: Pick<PrFacts, "changedLines">): string =>
76  `over the size cap: ${facts.changedLines} changed lines, more than ${AUTO_MERGE_SIZE_CAP}`;
77
78// The paths auto-merge refuses, separate from PROTECTED_PATH_PATTERNS (what needs the
79// can_touch_protected flag, src/protected-paths.ts). Tests, src/, docs, CLAUDE.md and .claude/ merge on green; these do
80// not, because each changes what judges a change or what ships beside it. Matched
81// case-insensitively against the repo-relative path; the document lists each source.
82export const AUTO_MERGE_REFUSED_PATHS: Array<{ pattern: RegExp; why: string }> = [
83  { pattern: /^src\/gate-policy\.ts$/i, why: "the gate policy source" },
84  { pattern: /^src\/auto-merge(-(policy|tick))?\.ts$/i, why: "the auto-merge source, which holds this list" },
85  { pattern: /^src\/policy-sign\.ts$/i, why: "the policy signer" },
86  { pattern: /^src\/protected-paths\.ts$/i, why: "the protected path list" },
87  // The sources the checks read their answers from, not only the ones that run them.
88  // Each is a two-step route otherwise: a green driver PR weakens the source and
89  // merges on its own, and the next PR passes the check it weakened.
90  { pattern: /^src\/scope\.ts$/i, why: "isMoneyPath, which is the whole of the paths_not_money check" },
91  { pattern: /^src\/signed-docs\.ts$/i, why: "verifySignedBody, which is how loadMergePolicy decides the stored policy is signed" },
92  { pattern: /^src\/auth\.ts$/i, why: "the HMAC and the constant-time comparison that verifier delegates to" },
93  { pattern: /^src\/encoding\.ts$/i, why: "the hex encoding of the signature that verifier compares" },
94  { pattern: /^src\/github\/client\.ts$/i, why: "the reader that supplies the changed paths and the CI facts every check judges" },
95  // dustinedwards-info's judge files. The list stays one list rather than one per
96  // namespace: every pattern is a refusal, so a namespace inheriting another's pattern
97  // can only refuse more, and a list split per namespace would be a second place to
98  // forget a pattern.
99  { pattern: /^\.github\/workflows\//i, why: "any workflow, which is what CI runs" },
100  { pattern: /^scripts\/check-[^/]*\.mjs$/i, why: "a check script, which is what the Gates step runs" },
101  { pattern: /^scripts\/lib\//i, why: "the library those check scripts read their rules from" },
102  { pattern: /(^|\/)\.aislop\//i, why: "the slop checker's word lists and allowances" },
103  { pattern: /(^|\/)workers\//i, why: "a worker that ships beside the site" },
104  { pattern: /(^|\/)package-lock\.json$/i, why: "the lockfile CI installs from" },
105  { pattern: /(^|\/)migrations\//i, why: "a migration, which runs against the live database" },
106  { pattern: /(^|\/)wrangler\.(jsonc?|toml)(\.example)?$/i, why: "deployment configuration" },
107  { pattern: /(^|\/)\.dev\.vars/i, why: "a secrets file" },
108  { pattern: /(^|\/)\.env($|\.)/i, why: "a secrets file" },
109  { pattern: /^package\.json$/i, why: "the npm scripts CI runs as the checks" },
110  { pattern: /(^|\/)tsconfig[^/]*\.json$/i, why: "what the typechecks check" },
111  { pattern: /(^|\/)vitest\.config\.[cm]?[jt]s$/i, why: "the integration suite's configuration" },
112  { pattern: /^scripts\/test-budget\.mjs$/i, why: "the runner behind npm test" },
113  { pattern: /^scripts\/verify-live\.mjs$/i, why: "the live gate, whose rollback is the backstop for an unattended merge" },
114  // Install, build and deploy glue. A namespace with no allowed-path limit merged these
115  // on green, though each runs in CI or ships (Grok audit 2026-10, U2). Lockfiles are
116  // no_migration_workflow_lockfile's, below.
117  { pattern: /(^|\/)scripts\//i, why: "a script CI, a build or a deploy runs" },
118  { pattern: /(^|\/)\.github\//i, why: "CI configuration beyond the workflows" },
119  { pattern: /(^|\/)package\.json$/i, why: "a nested package manifest, whose scripts and dependencies an install runs" },
120  { pattern: /(^|\/)(pnpm-workspace\.yaml|\.pnpmfile\.cjs|\.yarnrc[^/]*)$/i, why: "install configuration or a hook that runs during install" },
121  { pattern: /(^|\/)\.npmrc$/i, why: "npm registry and install-script policy" },
122  { pattern: /(^|\/)Dockerfile[^/]*$/i, why: "the image a build runs in" },
123  { pattern: /(^|\/)Makefile$/i, why: "build glue CI executes" },
124  { pattern: /(^|\/)\.husky\//i, why: "a git hook CI may run" },
125  { pattern: /(^|\/)\.gitmodules$/i, why: "submodules the checkout would fetch and run" },
126  // pr_recorded_for_job trusts result_ref and job_outcome_prs because only the job's
127  // holder writes them. These two sources are what writes them, so a green PR that
128  // loosened either could record any PR against any job. The job transitions are
129  // src/jobs.ts and the jobs-* modules it re-exports; jobs-schema.ts writes nothing.
130  { pattern: /^src\/jobs(-(claim|holder|seat|mirror|transition))?\.ts$/i, why: "the job transitions that write result_ref, which pr_recorded_for_job reads" },
131  { pattern: /^src\/outcome-prs\.ts$/i, why: "the writer of job_outcome_prs, which pr_recorded_for_job reads" },
132];
133
134function refusedPathHits(paths: string[]): Array<{ path: string; why: string }> {
135  const hits: Array<{ path: string; why: string }> = [];
136  for (const path of paths) {
137    const rule = AUTO_MERGE_REFUSED_PATHS.find(({ pattern }) => pattern.test(path));
138    if (rule) hits.push({ path, why: rule.why });
139  }
140  return hits;
141}
142
143// The paths a namespace's pull requests may touch at all, for a namespace that carries
144// a limit. Every changed path must match one of its patterns; a namespace with no entry
145// here has no limit beyond the refused paths. capsid carries one (Dustin, D6 of
146// 2026-10-03, policy version 6): a capsid merge deploys the control plane, so only
147// docs outside docs/policy/ and the Portal's stylesheets merge unattended there, and
148// tests, the Portal's scripts and every other path wait for the seat. This is the one
149// path list that admits rather than refuses, so it is per namespace: inheriting another
150// namespace's allow list would widen, not narrow. Matched case-insensitively, like the
151// refused paths, so docs/Policy/ is still docs/policy/.
152export const AUTO_MERGE_ALLOWED_PATHS: Record<string, Array<{ pattern: RegExp; why: string }>> = {
153  capsid: [
154    { pattern: /^docs\/(?!policy\/).+$/i, why: "a document under docs/, except the policy sources in docs/policy/" },
155    { pattern: /^dashboard\/.+\.css$/i, why: "a Portal stylesheet" },
156  ],
157};
158
159/** The allowed-path rule for a namespace, or null when it has no limit. */
160function allowedPathsFor(namespace: string): Array<{ pattern: RegExp; why: string }> | null {
161  return Object.hasOwn(AUTO_MERGE_ALLOWED_PATHS, namespace) ? AUTO_MERGE_ALLOWED_PATHS[namespace] : null;
162}
163
164/** Every allowed-path pattern as the document writes it, under its namespace's heading. */
165export const namespacedAllowedPaths = (): string[] =>
166  Object.entries(AUTO_MERGE_ALLOWED_PATHS).flatMap(([ns, rows]) => rows.map((r) => `${ns} / ${r.pattern.source}`));
167
168// The CI steps a green PR must have run, per namespace. A repo's CI runs its suites as
169// steps of one job, so check-run names cannot show that any of them ran. ci_green reads
170// the steps of the newest run of each named workflow on the head sha, and every step
171// named for that namespace must have concluded success. A skipped step is not a pass.
172//
173// Per namespace because the step names belong to the repo, not to this policy.
174// Checking one repo's step names against another repo's workflow would refuse every
175// pull request there. A namespace with no list here merges nothing, which is the same
176// refusal for a namespace whose CI nobody has written down.
177export interface RequiredStep {
178  workflow: string;
179  job: string;
180  step: string;
181}
182
183const ciStep = (job: string) => (step: string): RequiredStep => ({ workflow: ".github/workflows/ci.yml", job, step });
184
185export const AUTO_MERGE_REQUIRED_CI: Record<string, RequiredStep[]> = {
186  // One typecheck step runs all four configs.
187  capsid: [
188    "Typecheck src, tests, integration tests and the copied scorer script",
189    "Lint dead exports and doc drift",
190    "Tests",
191    "Integration tests",
192  ].map(ciStep("checks")),
193  // Every named step of both jobs of dustinedwards-info's ci.yml, read off main on
194  // 2026-10-18. Install and the build steps are named alongside the ones that judge, so
195  // a reordered workflow that drops one refuses rather than merging on a run that
196  // skipped it. The Admin MCP job's command steps carry no name, so GitHub reports them
197  // as "Run <command>", and those are the names below.
198  dustinedwards: [
199    ...["Install", "Migrations, stack and content build, local sync", "Lint", "Gates", "Build"].map(ciStep("Gates, clean checkout")),
200    ...[
201      "Install",
202      "Bootstrap wrangler.jsonc from the example",
203      "Run npm run typecheck",
204      "Run npm run check:wrapper",
205      "Run npm run check:wrapper:plant",
206      "Run npm test",
207      "Run npm run build",
208    ].map(ciStep("Admin MCP, clean checkout")),
209  ],
210  // Every step of Carrel's two jobs, read off its ci.yml on main on 2026-10-07. Carrel's
211  // steps that run a command carry no name, so GitHub names them "Run <command>"; that
212  // is the name the jobs API reports, and a script rename in package.json that changes
213  // the command text refuses until this list is updated. Both jobs judge: `check` runs
214  // the types, tests and accessibility scan, `gates` the conformance suite and the plants.
215  carrel: [
216    ...[
217      "Run npm ci",
218      "Run npm run typecheck",
219      "Run npm test",
220      "Run npm run check:postinstall",
221      "Run npm run check:mcp-roles",
222      "Install Chromium for the accessibility scan",
223      "Run npm run check:a11y",
224    ].map(ciStep("check")),
225    ...["Run npm ci", "Run npm run check:conformance", "Run npm run check:plants"].map(ciStep("gates")),
226  ],
227  // Every blocking step of Capsomer's `check` job, read off its ci.yml on main on
228  // 2026-10-07. The steps its own file marks warn-only (forced-colours screenshots, size,
229  // token check, the site summary and the artifact upload) are left out: they run with
230  // continue-on-error or always(), so a pass proves nothing about the change. The
231  // `results` job runs on a push to main only and is skipped on a pull request. The
232  // separate No bloat workflow is warn-only by its own ruling and is not required.
233  capsomer: [
234    "Install",
235    "Palette, scales, unit tests, types",
236    "Every family's contrast pairs, both themes (blocking, rule 18)",
237    "Build the behaviour modules and wrappers",
238    "Build the site and every states page",
239    "Install Chromium",
240    "Keyboard and accessibility tests, both themes",
241  ].map(ciStep("check")),
242};
243
244/** The steps that namespace's pull requests must have run, or null when none are written down. */
245export function requiredCiFor(namespace: string): RequiredStep[] | null {
246  const rows = Object.hasOwn(AUTO_MERGE_REQUIRED_CI, namespace) ? AUTO_MERGE_REQUIRED_CI[namespace] : undefined;
247  return rows && rows.length > 0 ? rows : null;
248}
249
250export const requiredCiLabel = (r: RequiredStep): string => `${r.workflow} / ${r.job} / ${r.step}`;
251
252/** Every required step as the document writes it, under its namespace's heading. */
253export const namespacedCiLabels = (): string[] =>
254  Object.entries(AUTO_MERGE_REQUIRED_CI).flatMap(([ns, rows]) => rows.map((r) => `${ns} / ${requiredCiLabel(r)}`));
255
256export interface MergePolicy {
257  version: string;
258  enabled: boolean;
259  namespaces: string[];
260  checks: string[];
261  refusedPaths: string[];
262  // Each entry is `<namespace> / <pattern>`, from the `## Allowed paths, <namespace>`
263  // heading it was written under, compared with the code's list like the steps are.
264  allowedPaths: string[];
265  // GitHub logins whose PRs may merge without a human, from the document only.
266  authors: string[];
267  // The merge units promoted to auto (docs/design/design-merge-pipeline.md section 7,
268  // PR 10), each `<namespace> / <path class>`, from the `## Auto units` section. Like the
269  // author allowlist, the list lives only in the signed document; the code holds only the
270  // path classes a unit may name (PROMOTABLE_PATH_CLASSES).
271  units: string[];
272  // Each entry is `<namespace> / <workflow> / <job> / <step>`, built from the heading
273  // the step was written under. One flat list keeps the load-time agreement check a
274  // single comparison in both directions, so a namespace section missing from the
275  // document is caught by the same line that catches a missing step.
276  requiredCi: string[];
277}
278
279// Check ids are read with POLICY_ID_ITEM. Paths, steps and authors carry a leading
280// word so they are not read as check ids.
281const PATH_ITEM = /^- path `([^`]+)`/;
282const STEP_ITEM = /^- step `([^`]+)`/;
283const AUTHOR_ITEM = /^- author `([^`]+)`/;
284const ALLOW_ITEM = /^- allow `([^`]+)`/;
285const UNIT_ITEM = /^- unit `([^`]+)`/;
286const UNITS_HEADING = /^##\s+Auto units\s*$/i;
287
288// The path classes a unit may promote: every class src/merge-class.ts holds except
289// money (typed forever, design section 8), migration and workflow (each a step outside a
290// merge, class seat). test/auto-merge-units.test.ts holds this to merge-class's list.
291export const PROMOTABLE_PATH_CLASSES: readonly string[] = ["docs", "dashboard-css", "tests", "dashboard-code", "deps-own", "src-routine", "deps-other", "src-worth"];
292// The heading a required step is filed under: `## Required CI, <namespace>`. A step
293// written before any such heading is a refusal rather than a step belonging to
294// whichever namespace came first.
295const CI_HEADING = /^##\s+Required CI,\s*([a-z0-9-]+)\s*$/i;
296// The heading an allowed path is filed under: `## Allowed paths, <namespace>`. Same rule:
297// an allowed path under no such heading is a refusal, never a limit on some namespace.
298const ALLOW_HEADING = /^##\s+Allowed paths,\s*([a-z0-9-]+)\s*$/i;
299
300/** Parse the policy body below its frontmatter. Returns the policy or a refusal. */
301export function parseMergePolicy(body: string): { policy: MergePolicy } | { error: string } {
302  const version = policyField(body, "version");
303  if (!version) {
304    return { error: "the policy document names no version. A merge audited against an unnamed policy cannot be traced to what it allowed." };
305  }
306  const enabled = policyField(body, "enabled");
307  if (enabled === null) return { error: "the policy document does not say whether it is enabled." };
308  const namespaces = (policyField(body, "namespaces") ?? "")
309    .split(",")
310    .map((n) => n.trim())
311    .filter(Boolean);
312  if (namespaces.length === 0) return { error: "the policy document covers no namespaces, so it authorises nothing." };
313  const unknown = namespaces.filter((n) => !onRoster(n));
314  if (unknown.length > 0) {
315    return {
316      error: `the policy names ${unknown.join(", ")}, which is not on the roster. A policy cannot widen the set of repos this Worker reaches.`,
317    };
318  }
319  const checks: string[] = [];
320  const refusedPaths: string[] = [];
321  const authors: string[] = [];
322  const requiredCi: string[] = [];
323  const allowedPaths: string[] = [];
324  const units: string[] = [];
325  let ciNamespace: string | null = null;
326  let allowNamespace: string | null = null;
327  let inUnits = false;
328  for (const line of body.split("\n")) {
329    const trimmed = line.trim();
330    // Any heading closes the section, so a step under `## What a merge means` is not
331    // filed under the last namespace that appeared above it.
332    if (trimmed.startsWith("##")) {
333      const heading = CI_HEADING.exec(trimmed);
334      ciNamespace = heading ? heading[1] : null;
335      const allowHeading = ALLOW_HEADING.exec(trimmed);
336      allowNamespace = allowHeading ? allowHeading[1] : null;
337      inUnits = UNITS_HEADING.test(trimmed);
338      continue;
339    }
340    const unitItem = UNIT_ITEM.exec(trimmed);
341    if (unitItem) {
342      // A unit is a widening, so every way it can be malformed refuses the whole document.
343      if (!inUnits) return { error: `the policy lists unit '${unitItem[1]}' outside the ## Auto units section, so whether it is promoted is unstated.` };
344      const m = /^([a-z0-9-]+)\s*\/\s*([a-z-]+)$/.exec(unitItem[1]!.trim());
345      if (!m) return { error: `the policy's unit '${unitItem[1]}' is not '<namespace> / <path class>'.` };
346      const [, ns, cls] = m;
347      if (!PROMOTABLE_PATH_CLASSES.includes(cls!)) {
348        return { error: `the policy's unit '${unitItem[1]}' names path class '${cls}', which is ${cls === "money" || cls === "migration" || cls === "workflow" ? "never promoted to auto" : "not a path class this Worker knows"}. Refusing the whole document rather than guessing what it widens.` };
349      }
350      if (!namespaces.includes(ns!)) return { error: `the policy's unit '${unitItem[1]}' names ${ns}, which the policy does not cover.` };
351      const unit = `${ns} / ${cls}`;
352      if (units.includes(unit)) return { error: `the policy lists unit '${unit}' twice.` };
353      units.push(unit);
354      continue;
355    }
356    const check = POLICY_ID_ITEM.exec(trimmed);
357    if (check) checks.push(check[1]);
358    const path = PATH_ITEM.exec(trimmed);
359    if (path) refusedPaths.push(path[1]);
360    const author = AUTHOR_ITEM.exec(trimmed);
361    if (author) authors.push(author[1]);
362    const step = STEP_ITEM.exec(trimmed);
363    if (step) {
364      if (!ciNamespace) {
365        return { error: `the policy lists required CI step '${step[1]}' under no namespace heading, so which repo's CI it describes is unstated.` };
366      }
367      requiredCi.push(`${ciNamespace} / ${step[1]}`);
368    }
369    const allow = ALLOW_ITEM.exec(trimmed);
370    if (allow) {
371      if (!allowNamespace) {
372        return { error: `the policy lists allowed path '${allow[1]}' under no namespace heading, so which namespace it limits is unstated.` };
373      }
374      allowedPaths.push(`${allowNamespace} / ${allow[1]}`);
375    }
376  }
377  // Fails closed: a document with no author allowlist loads nothing.
378  if (authors.length === 0) {
379    return { error: "the policy document names no PR author, so it authorises no pull request. Refusing rather than merging with no author allowlist." };
380  }
381  return { policy: { version, enabled: enabled.toLowerCase() === "true", namespaces, checks, refusedPaths, allowedPaths, authors, requiredCi, units } };
382}
383
384// Both directions: what the document lists and the code does not, and the reverse.
385function listDisagreement(what: string, documented: string[], enforced: string[]): string | null {
386  const unenforced = documented.filter((d) => !enforced.includes(d));
387  const undocumented = enforced.filter((e) => !documented.includes(e));
388  if (unenforced.length === 0 && undocumented.length === 0) return null;
389  const parts: string[] = [];
390  if (undocumented.length > 0) parts.push(`does not list ${undocumented.join(", ")}, which this Worker enforces`);
391  if (unenforced.length > 0) parts.push(`lists ${unenforced.join(", ")}, which this Worker does not enforce`);
392  return `the policy document's ${what} ${parts.join(", and ")}. Refusing rather than merging against a policy that disagrees with the code.`;
393}
394
395/** Read and verify the policy. A missing, unsigned or tampered document merges nothing. */
396export async function loadMergePolicy(env: Env): Promise<{ policy: MergePolicy } | { error: string }> {
397  const read = await readSignedPolicy(env, AUTO_MERGE_POLICY_PATH, "merge policy", "nothing is auto-merged");
398  if ("error" in read) return read;
399  return checkMergePolicyBody(read.body);
400}
401
402/** Every check loadMergePolicy makes of a body once its signature is verified: it parses,
403 *  and it says no less, and nothing different, than the code enforces. The one place a body
404 *  is judged loadable, so a body signed from the repo (sign_policy_from_repo) is held to
405 *  what the loader will hold it to. */
406export function checkMergePolicyBody(body: string): { policy: MergePolicy } | { error: string } {
407  const parsed = parseMergePolicy(body);
408  if ("error" in parsed) return parsed;
409  const missing = POLICY_CHECKS.filter((c) => !parsed.policy.checks.includes(c));
410  if (missing.length > 0) {
411    return {
412      error: `the policy document does not name ${missing.join(", ")}, which this Worker enforces. Refusing rather than merging against a policy that describes less than the code does.`,
413    };
414  }
415  const paths = listDisagreement(
416    "refused paths",
417    parsed.policy.refusedPaths,
418    AUTO_MERGE_REFUSED_PATHS.map((p) => p.pattern.source)
419  );
420  if (paths) return { error: paths };
421  // Both directions here too: a limit the document drops would widen a namespace the
422  // signer meant to hold narrow, and one it adds would be a limit nothing enforces.
423  const allowed = listDisagreement("allowed paths", parsed.policy.allowedPaths, namespacedAllowedPaths());
424  if (allowed) return { error: allowed };
425  const steps = listDisagreement("required CI steps", parsed.policy.requiredCi, namespacedCiLabels());
426  if (steps) return { error: steps };
427  // A namespace the policy covers with no required CI steps merges nothing. Without
428  // this, ci_green's step check would have nothing to compare and would pass on any run
429  // that reported at all, so a widening here would be quiet rather than fail closed.
430  const uncovered = parsed.policy.namespaces.filter((n) => requiredCiFor(n) === null);
431  if (uncovered.length > 0) {
432    return {
433      error: `the policy covers ${uncovered.join(", ")}, for which this Worker holds no required CI steps. A green run there would prove nothing, so it is refused rather than merged.`,
434    };
435  }
436  return parsed;
437}
438
439export interface PrFacts {
440  number: number;
441  repo: string;
442  namespace: string;
443  baseRef: string;
444  defaultBranch: string;
445  headSha: string;
446  body: string;
447  changedPaths: string[];
448  // Why the changed-file list is incomplete, or null. An incomplete list refuses.
449  filesProblem: string | null;
450  // Additions plus deletions across the changed files, as GitHub counts them, or null
451  // when a file came back without its counts, which size_within_cap refuses.
452  changedLines: number | null;
453  // The existing tests the pull request changes (src/github/pr-files.ts). No policy check
454  // reads it: the class and the tick do, and hold such a pull request for Dustin.
455  existingTestEdits: string[];
456  // null when no check run has reported, which is NOT green.
457  ciConclusion: string | null;
458  ciNote: string;
459  // The steps of the newest run of each workflow on the head sha, and why they could
460  // not be read, or null.
461  ciSteps: Array<{ workflow: string; job: string; step: string; conclusion: string | null }>;
462  ciStepsProblem: string | null;
463  // The owner/name of the repo the PR's head branch lives on, as GitHub reports it, or
464  // null when GitHub reports none (a fork that was deleted).
465  headRepo: string | null;
466  // The login of the GitHub account that opened the PR (pr.user.login), or null when
467  // GitHub reports none.
468  prAuthor: string | null;
469  // Resolved from the job id in the PR body. jobClaimedBy is who held or completed the
470  // job, for the audit row; no check reads it.
471  jobId: string | null;
472  jobClaimedBy: string | null;
473  jobStatus: string | null;
474  // Every pull request URL the job's holder recorded: result_ref and the
475  // job_outcome_prs rows, all written by the transitions that complete or block a job
476  // (src/jobs-holder.ts) or seeded from what they wrote.
477  jobPrUrls: string[];
478}
479
480export type PolicyVerdict =
481  | { merge: true; passed: PolicyCheck[] }
482  | { merge: false; failed: PolicyCheck; why: string; passed: PolicyCheck[] };
483
484// The job id a driver puts in a PR body, matched anywhere in it.
485const JOB_ID_IN_BODY = /\bjob_[0-9a-f]{12}\b/;
486
487export function jobIdFromBody(body: string): string | null {
488  return JOB_ID_IN_BODY.exec(body ?? "")?.[0] ?? null;
489}
490
491// The statuses in which a job has handed its PR on. A session opens the PR and then
492// completes (done) or stops at a gate (blocked). A queued, claimed, failed or
493// superseded job has not handed anything on, so its id in a PR body proves nothing,
494// and a job id no row in this namespace carries has no status at all.
495const HANDED_ON_STATUSES = ["blocked", "done"];
496
497// A PR URL as the job records hold it, compared case-insensitively. The match ends at
498// the PR number, so pull/23 never matches pull/234.
499const PR_URL = /https:\/\/github\.com\/[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+\/pull\/\d+/g;
500
501function normalizedPrUrls(text: string | null): string[] {
502  return [...(text ?? "").matchAll(PR_URL)].map((m) => m[0].toLowerCase());
503}
504
505// Named separately from the refused list because their consequence is not local: a
506// migration runs against the live database, a workflow is what measures the code, and
507// a lockfile decides what gets installed and executed. The refused list also covers
508// some of these; this is the second statement for them, so removing a pattern from
509// one list does not quietly open the other.
510const MIGRATION_WORKFLOW_LOCKFILE: Array<{ pattern: RegExp; why: string }> = [
511  { pattern: /(^|\/)migrations\//i, why: "a migration, which runs against the live database" },
512  { pattern: /(^|\/)\.github\/workflows\//i, why: "a workflow, which is what measures the code" },
513  {
514    pattern: /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|deno\.lock)$/i,
515    why: "a lockfile, which decides what gets installed and executed",
516  },
517];
518
519/**
520 * The whole policy, as a pure function of facts and the signed document's author
521 * allowlist. Every check refuses on its own.
522 */
523export function evaluatePolicy(
524  facts: PrFacts,
525  allowedAuthors: string[],
526  // The promoted unit this PR falls in, when the signed policy lists its namespace and
527  // path class under ## Auto units (the tick computes the path class). It widens only
528  // paths_allowed_for_namespace: never a refused path, money, a migration or a workflow.
529  promoted: { unit: string } | null = null
530): PolicyVerdict {
531  const passed: PolicyCheck[] = [];
532  const no = (failed: PolicyCheck, why: string): PolicyVerdict => ({ merge: false, failed, why, passed: [...passed] });
533
534  // A path list that was not read whole is not judged on the part that loaded: a
535  // refused path on page two would merge that way.
536  if (facts.filesProblem) {
537    return no("paths_not_refused", `the changed-file list is incomplete (${facts.filesProblem}), so this PR is not evaluated.`);
538  }
539  const refused = refusedPathHits(facts.changedPaths);
540  if (refused.length > 0) {
541    return no("paths_not_refused", `the change touches ${refused.length} path(s) auto-merge refuses: ${refused.map((h) => `${h.path} (${h.why})`).join("; ")}.`);
542  }
543  passed.push("paths_not_refused");
544
545  const money = facts.changedPaths.filter((p) => isMoneyPath(p));
546  if (money.length > 0) {
547    return no("paths_not_money", `the change touches a billing or payment surface: ${money.join(", ")}.`);
548  }
549  passed.push("paths_not_money");
550
551  for (const path of facts.changedPaths) {
552    for (const { pattern, why } of MIGRATION_WORKFLOW_LOCKFILE) {
553      if (pattern.test(path)) return no("no_migration_workflow_lockfile", `${path} is ${why}.`);
554    }
555  }
556  passed.push("no_migration_workflow_lockfile");
557
558  // A namespace with a limit merges only a change whose every path is inside it. A PR
559  // that changes no file shows nothing inside the limit, so it waits for the seat too.
560  const allowedRules = allowedPathsFor(facts.namespace);
561  if (allowedRules) {
562    if (facts.changedPaths.length === 0) {
563      return no("paths_allowed_for_namespace", `the PR changes no file, and ${facts.namespace} merges unattended only a change inside its allowed paths.`);
564    }
565    const outside = facts.changedPaths.filter((p) => !allowedRules.some(({ pattern }) => pattern.test(p)));
566    if (outside.length > 0 && !promoted) {
567      return no(
568        "paths_allowed_for_namespace",
569        `${facts.namespace} merges unattended only ${allowedRules.map((r) => r.why).join(" or ")}, and the change also touches ${outside.join(", ")}.`
570      );
571    }
572  }
573  passed.push("paths_allowed_for_namespace");
574
575  // A fork's head is code nobody holding a credential here pushed. GitHub reports no
576  // head repo when the fork was deleted, which is refused the same way.
577  if (!facts.headRepo || facts.headRepo.toLowerCase() !== facts.repo.toLowerCase()) {
578    return no("head_in_base_repo", `the PR's head is on ${facts.headRepo ?? "no repo GitHub reports"}, not on ${facts.repo}. A fork's PR waits for the seat.`);
579  }
580  passed.push("head_in_base_repo");
581
582  if (!facts.jobId) {
583    return no("body_names_job", "the PR body names no job id, so there is no request this change can be traced back to.");
584  }
585  passed.push("body_names_job");
586
587  // Case-insensitive, as GitHub treats logins. An empty allowlist matches nobody.
588  const author = facts.prAuthor?.toLowerCase() ?? null;
589  if (!author || !allowedAuthors.some((a) => a.toLowerCase() === author)) {
590    return no(
591      "pr_author_allowed",
592      `the PR was opened by ${facts.prAuthor ?? "no account GitHub reports"}, which is not on the policy's author allowlist (${allowedAuthors.join(", ") || "empty"}).`
593    );
594  }
595  passed.push("pr_author_allowed");
596
597  if (!facts.jobStatus || !HANDED_ON_STATUSES.includes(facts.jobStatus)) {
598    return no("job_handed_on", `${facts.jobId} is ${facts.jobStatus ?? "in no status"}, not blocked or done, so it has not handed a PR on.`);
599  }
600  passed.push("job_handed_on");
601
602  // The PR itself must be recorded against the job, or anyone could name a finished
603  // job in a PR body.
604  const url = `https://github.com/${facts.repo}/pull/${facts.number}`.toLowerCase();
605  if (!facts.jobPrUrls.some((recorded) => normalizedPrUrls(recorded).includes(url))) {
606    return no(
607      "pr_recorded_for_job",
608      `${facts.jobId}'s holder never recorded this PR against it (neither its result_ref nor its outcome PRs name ${url}), so it is not shown to be that job's work.`
609    );
610  }
611  passed.push("pr_recorded_for_job");
612
613  if (facts.baseRef !== facts.defaultBranch) {
614    return no("base_is_default_branch", `the PR targets '${facts.baseRef}', not the default branch '${facts.defaultBranch}'.`);
615  }
616  passed.push("base_is_default_branch");
617
618  if (facts.changedLines === null) {
619    return no("size_within_cap", "GitHub reported no line counts for at least one changed file, so the size cap cannot be judged. A person approves it.");
620  }
621  if (overSizeCap(facts)) return no("size_within_cap", `${sizeCapReason(facts)}. A person approves it.`);
622  passed.push("size_within_cap");
623
624  const ci = ciGreenOn(facts);
625  if (ci.state !== "green") return no("ci_green", ci.why);
626  passed.push("ci_green");
627
628  return { merge: true, passed };
629}
630
631/** The ci_green check on the facts' head sha, with the same required steps the policy
632 *  reads, shared by the policy and the approval executor (docs/design/design-merge-pipeline.md
633 *  section 4: "through the same function and the same required steps as the policy").
634 *  green: every check and every required step succeeded. wait: CI has not finished, or its
635 *  steps could not be read. red: CI failed, or a required step did not run to success.
636 *  never: no required steps are written down for the namespace, so no run shows anything. */
637export function ciGreenOn(facts: Pick<PrFacts, "headSha" | "ciConclusion" | "ciNote" | "ciStepsProblem" | "ciSteps" | "namespace">): { state: "green" | "wait" | "red" | "never"; why: string } {
638  const sha = facts.headSha.slice(0, 7);
639  if (facts.ciConclusion === null || facts.ciConclusion === "pending") return { state: "wait", why: `CI on ${sha} is ${facts.ciConclusion ?? "not reported"}: ${facts.ciNote}` };
640  if (facts.ciConclusion !== "success") return { state: "red", why: `CI on ${sha} is ${facts.ciConclusion}: ${facts.ciNote}` };
641  if (facts.ciStepsProblem) {
642    return { state: "wait", why: `the CI steps on ${sha} could not be read (${facts.ciStepsProblem}), so the required suites are not shown to have run.` };
643  }
644  const required = requiredCiFor(facts.namespace);
645  if (!required) {
646    return { state: "never", why: `no required CI steps are written down for namespace '${facts.namespace}', so a green run there shows nothing. It waits for the seat.` };
647  }
648  const notRun = required.filter(
649    (r) => !facts.ciSteps.some((s) => s.workflow === r.workflow && s.job === r.job && s.step === r.step && s.conclusion === "success")
650  );
651  if (notRun.length > 0) return { state: "red", why: `CI on ${sha} did not run ${notRun.map(requiredCiLabel).join(", ")} to success.` };
652  return { state: "green", why: `CI on ${sha} is green, with every required step` };
653}
654
655// Every completed check run must have concluded success, skipped or neutral, and at
656// least one must have reported. A PR with no checks is not green: its workflow never
657// started, which cannot be told apart from a workflow that was removed.
658export function ciVerdict(
659  runs: Array<{ name: string; status: string; conclusion: string | null }>
660): { conclusion: string | null; note: string } {
661  if (runs.length === 0) return { conclusion: null, note: "no check run has reported on this commit" };
662  const pending = runs.filter((r) => r.status !== "completed");
663  if (pending.length > 0) {
664    return { conclusion: "pending", note: `${pending.length} check(s) still running: ${pending.map((r) => r.name).join(", ")}` };
665  }
666  const bad = runs.filter((r) => !["success", "skipped", "neutral"].includes(r.conclusion ?? ""));
667  if (bad.length > 0) {
668    return { conclusion: "failure", note: `${bad.map((r) => `${r.name}=${r.conclusion ?? "null"}`).join(", ")}` };
669  }
670  return { conclusion: "success", note: `${runs.length} check(s) green` };
671}