src/merge-class.ts

Functions

Imports

It imports src/auto-merge-policy.ts, src/model-routing.ts, src/scope.ts. Imported by src/approval-executor.ts, src/auto-merge-tick.ts, src/complete-ci.ts, src/github/pr-files.ts, src/inbox.ts.

Source

1import { AUTO_MERGE_REFUSED_PATHS, overSizeCap, sizeCapReason, type PrFacts, type PolicyVerdict } from "./auto-merge-policy";
2import { worthReviewer } from "./model-routing";
3import { isMoneyPath } from "./scope";
4
5// THE MERGE CLASSES (docs/design/design-merge-pipeline.md section 2; Dustin ruled DECIDE 2
6// on 2026-10-09). Every open pull request on a covered repo gets exactly one class, with
7// its reasons, computed each tick by this pure function. REPORT-ONLY for now (the design's
8// PR 2): the class rides on the awaiting-seat set and the inbox, and nothing acts on it.
9// The approval record (PR 3) and the executor (PR 4) are what will.
10//
11//   auto     passes every check of the signed policy: the tick merges it
12//   approve  fails only on rules a person may waive: one tap, batchable
13//   typed    any money path: a typed confirmation, never batched, never automatic
14//   seat     needs a step outside a merge: a migration, a workflow, a fork head, a base
15//            that is not the default branch, a file list that could not be read
16//   wait     CI has not finished, or the PR is a draft: nobody acts yet
17//
18// Money is decided before anything else, so no other rule can move a money PR out of
19// typed (design section 8, "the permanent exception").
20
21const MERGE_CLASSES = ["auto", "approve", "typed", "seat", "wait"] as const;
22export type MergeClass = (typeof MERGE_CLASSES)[number];
23
24// The path classes, least risky first: a PR's path class is the riskiest of its files'.
25export const PATH_CLASSES = ["docs", "dashboard-css", "tests", "dashboard-code", "deps-own", "src-routine", "deps-other", "src-worth", "workflow", "migration", "money"] as const;
26export type PathClass = (typeof PATH_CLASSES)[number];
27
28export interface Classification {
29  class: MergeClass;
30  path_class: PathClass | null;
31  reasons: string[];
32}
33
34export const TEST_FILE = /(^|\/)(test|tests|test-integration|e2e|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$/i;
35const DEPS_FILE = /(^|\/)(package\.json|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?)$/i;
36const DOC_FILE = /\.(md|mdx|txt|png|jpe?g|gif|svg|webp)$/i;
37
38/** One file's path class. */
39export function pathClassOf(path: string): PathClass {
40  if (isMoneyPath(path)) return "money";
41  if (/(^|\/)migrations\/[^/]+\.sql$/i.test(path)) return "migration";
42  if (/^\.github\/workflows\//i.test(path)) return "workflow";
43  // Which dependency changed is in the diff, not the path, so a manifest or lockfile is
44  // judged as another's package until the diff is read (deps-own, job_3b09752450c1).
45  // Before the refused list, which names lockfiles for a different reason.
46  if (DEPS_FILE.test(path)) return "deps-other";
47  if (AUTO_MERGE_REFUSED_PATHS.some(({ pattern }) => pattern.test(path))) return "src-worth";
48  if (TEST_FILE.test(path)) return "tests";
49  if (/^dashboard\/.*\.css$/i.test(path)) return "dashboard-css";
50  if (/^dashboard\//i.test(path)) return "dashboard-code";
51  if (/^docs\//i.test(path) || DOC_FILE.test(path)) return "docs";
52  return worthReviewer([{ filename: path }]).level === "worth" ? "src-worth" : "src-routine";
53}
54
55/** The riskiest path class among `paths`, or null for none. */
56export function pathClassOfAll(paths: readonly string[]): PathClass | null {
57  let worst = -1;
58  for (const p of paths) worst = Math.max(worst, PATH_CLASSES.indexOf(pathClassOf(p)));
59  return worst < 0 ? null : PATH_CLASSES[worst];
60}
61
62/** The reason a pull request that changes an existing test waits for Dustin. */
63export function existingTestReason(edits: readonly string[]): string {
64  return `changes an existing test: ${edits.slice(0, 3).join(", ")}${edits.length > 3 ? `, and ${edits.length - 3} more` : ""}`;
65}
66
67/** The class of one pull request, from the facts the tick read and the policy's verdict. */
68export function mergeClass(facts: PrFacts, verdict: PolicyVerdict, draft = false): Classification {
69  const paths = facts.changedPaths;
70  const path_class = facts.filesProblem ? null : pathClassOfAll(paths);
71  const money = paths.filter(isMoneyPath);
72  if (money.length) return { class: "typed", path_class, reasons: [`${money.slice(0, 3).join(", ")} ${money.length === 1 ? "is a money path" : "are money paths"}: typed confirmation only`] };
73  if (draft) return { class: "wait", path_class, reasons: ["the PR is a draft"] };
74  if (facts.ciConclusion === null || facts.ciConclusion === "pending") return { class: "wait", path_class, reasons: [`CI has not finished: ${facts.ciNote}`] };
75  // A changed existing test is never merged unattended, whatever the policy and the
76  // promoted units say: a test edited to pass is how a regression gets past CI. It is
77  // approve, one tap, and it holds with every unit promoted (src/auto-merge-tick.ts).
78  const testEdit = facts.existingTestEdits.length ? existingTestReason(facts.existingTestEdits) : null;
79  if (verdict.merge && testEdit) return { class: "approve", path_class, reasons: [testEdit] };
80  if (verdict.merge) return { class: "auto", path_class, reasons: ["passes every check of the signed policy"] };
81  const seat: string[] = [];
82  if (facts.filesProblem) seat.push(`the changed files could not be read whole: ${facts.filesProblem}`);
83  const byClass = (c: PathClass) => paths.filter((p) => pathClassOf(p) === c);
84  if (byClass("migration").length) seat.push(`a migration (${byClass("migration")[0]}) is applied by the seat`);
85  if (byClass("workflow").length) seat.push(`a workflow (${byClass("workflow")[0]}) needs the App's workflows permission to merge`);
86  if (facts.headRepo === null || facts.headRepo.toLowerCase() !== facts.repo.toLowerCase()) seat.push("the head is not on the base repo");
87  if (facts.baseRef !== facts.defaultBranch) seat.push(`the base is ${facts.baseRef}, not the default branch ${facts.defaultBranch}`);
88  if (seat.length) return { class: "seat", path_class, reasons: seat };
89  // Over the size cap is its own reason, named first whichever check the policy stopped
90  // at, so a big pull request reads as one a person approves for its size.
91  const reasons = testEdit ? [testEdit] : [];
92  if (overSizeCap(facts)) reasons.push(sizeCapReason(facts));
93  if (verdict.failed !== "size_within_cap") reasons.push(`the policy stops at ${verdict.failed}: ${verdict.why}`);
94  if (facts.ciConclusion !== "success") reasons.push(`CI is ${facts.ciConclusion}: an approval waits for green`);
95  return { class: "approve", path_class, reasons };
96}