src/github/prune.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts. Imported by src/github.ts, src/maintenance-branches.ts.

Source

1import type { RepoEnv as Env } from "../env";
2import { encodePath, getDefaultBranch, ghFetch, invalidateRepoReads, resolveRepo } from "./client";
3
4// PRUNE MERGED BRANCHES (job_8779278b8e91, Dustin 2026-10-07). capsid_close_pr action delete_branch with merged:true
5// finds the branches whose work has landed and, only with confirm:true, deletes them. A branch
6// is pruned only when its LATEST pull request in this repo merged AND the branch tip is the
7// commit that pull request merged from, so a commit pushed after the merge is never lost.
8// Anything uncertain is kept: no pull request, one that is open or was closed unmerged, a
9// reopened branch, or a list this call could not read in full.
10//
11// Reads are live (ghFetch), not the cached reads the other tools use, because a stale list
12// is how a branch with new work gets deleted. A confirmed call re-reads each branch's tip
13// immediately before deleting it.
14
15const PAGE_SIZE = 100;
16const PAGE_CAP = 10;
17// A confirmed call deletes at most this many, and says how many are left, so one call's
18// subrequests stay bounded however many branches are stale. The seat repeats until none remain.
19const DELETE_CAP = 40;
20const KEPT_LISTED = 200;
21const NEVER_PRUNED = new Set(["screenshots", "results", "gh-pages"]);
22const NEVER_PRUNED_PREFIXES = ["release/"];
23
24interface BranchRow {
25  name: string;
26  commit: { sha: string };
27  protected?: boolean;
28}
29
30interface PullRow {
31  number: number;
32  state: string;
33  merged_at: string | null;
34  head: { ref: string; sha: string; repo: { full_name: string } | null };
35  body?: string | null;
36}
37
38export interface PruneKept {
39  branch: string;
40  reason: string;
41}
42
43export interface PruneCandidate {
44  branch: string;
45  sha: string;
46  // The merged pull request, or null for a branch the daily pass deletes for its age alone
47  // (src/maintenance-branches.ts).
48  pr: number | null;
49}
50
51// Screenshot branches (job_9dbaf2ecfd2c): a pull request's images live on a branch of their
52// own, named shots/... or ...-shots, that no pull request has as its head. One is kept while
53// an open pull request's description names it or its tip, and is an orphan after that.
54const SHOTS_BRANCH = /^shots\/|-shots$/;
55
56/** The open pull request whose description shows a screenshot branch's images, or null. */
57function shotsInUse(branch: { name: string; sha: string }, open: ReadonlyArray<{ number: number; body?: string | null }>): number | null {
58  if (!SHOTS_BRANCH.test(branch.name)) return null;
59  const used = open.find((pr) => (pr.body ?? "").includes(branch.name) || (pr.body ?? "").includes(branch.sha));
60  return used ? used.number : null;
61}
62
63// orphan: kept only because the rule cannot prove its work landed (no pull request, one
64// closed without merging, or commits after the merge), so its age is what says whether it
65// is still wanted. A branch kept for what it is (default, protected, by name) or for an open pull request is not an orphan.
66type PruneVerdict = { prune: true; pr: number } | { prune: false; reason: string; orphan: boolean };
67
68/** Whether a branch may be pruned, from the facts about it. Pure, so every rule is tested
69 *  without GitHub. `latest` is the branch's newest pull request in this repo, or undefined. */
70export function pruneVerdict(
71  branch: { name: string; sha: string; protected: boolean },
72  defaultBranch: string,
73  latest: { number: number; state: string; merged: boolean; headSha: string } | undefined,
74  listsComplete: boolean
75): PruneVerdict {
76  if (branch.name === defaultBranch) return { prune: false, reason: "default branch", orphan: false };
77  if (branch.protected) return { prune: false, reason: "protected branch", orphan: false };
78  if (NEVER_PRUNED.has(branch.name) || NEVER_PRUNED_PREFIXES.some((p) => branch.name.startsWith(p))) {
79    return { prune: false, reason: "kept by name (release, screenshots, results, gh-pages)", orphan: false };
80  }
81  if (!latest) {
82    return { prune: false, reason: listsComplete ? "no pull request" : "no pull request found in the part of the list that was read", orphan: true };
83  }
84  if (latest.state === "open") return { prune: false, reason: `open pull request #${latest.number}`, orphan: false };
85  if (!latest.merged) return { prune: false, reason: `pull request #${latest.number} was closed without merging`, orphan: true };
86  if (latest.headSha !== branch.sha) return { prune: false, reason: `commits after pull request #${latest.number} merged`, orphan: true };
87  // A list not read whole may hide a newer open pull request on the same head, so a
88  // delete waits until it can be read whole (Grok audit 2026-10-21, CA-17).
89  if (!listsComplete) return { prune: false, reason: `pull request #${latest.number} merged, but the pull request list was not read whole`, orphan: false };
90  return { prune: true, pr: latest.number };
91}
92
93async function paged<T>(env: Env, owner: string, repo: string, path: string): Promise<{ rows: T[]; complete: boolean }> {
94  const rows: T[] = [];
95  for (let page = 1; page <= PAGE_CAP; page++) {
96    const sep = path.includes("?") ? "&" : "?";
97    const resp = await ghFetch(env, owner, repo, `${path}${sep}per_page=${PAGE_SIZE}&page=${page}`);
98    if (!resp.ok) throw new Error(`delete_branch merged: reading ${path} failed (${resp.status}): ${(await resp.text()).slice(0, 200)}`);
99    const batch = (await resp.json()) as T[];
100    rows.push(...batch);
101    if (batch.length < PAGE_SIZE) return { rows, complete: true };
102  }
103  return { rows, complete: false };
104}
105
106/** What the prune rule makes of a repo's branches: the ones it would delete, and every other
107 *  with the reason it is kept. The tool's preview and the daily maintenance pass
108 *  (src/maintenance-branches.ts) both read it, so the rule is spelled once. */
109export interface PrunePlan {
110  owner: string;
111  name: string;
112  repo: string;
113  defaultBranch: string;
114  branchesRead: number;
115  listsComplete: boolean;
116  /** Whether the open pull request list was read in full, so "no open pull request" is known. */
117  openComplete: boolean;
118  prune: PruneCandidate[];
119  kept: PruneKeptRow[];
120}
121
122/** A kept branch with its tip, and whether nothing but its age says it is still wanted:
123 *  no pull request, one closed without merging, or commits after the merge. */
124interface PruneKeptRow extends PruneKept {
125  sha: string;
126  orphan: boolean;
127}
128
129export async function readPrunePlan(env: Env, namespace: string, keep: string[] = [], repoSelector?: string): Promise<PrunePlan> {
130  const { owner, repo, full } = await resolveRepo(env, namespace, repoSelector);
131  const base = `/repos/${owner}/${repo}`;
132  const defaultBranch = await getDefaultBranch(env, owner, repo);
133
134  const branches = await paged<BranchRow>(env, owner, repo, `${base}/branches`);
135  const open = await paged<PullRow>(env, owner, repo, `${base}/pulls?state=open`);
136  const closed = await paged<PullRow>(env, owner, repo, `${base}/pulls?state=closed&sort=updated&direction=desc`);
137  const listsComplete = branches.complete && open.complete && closed.complete;
138
139  // The newest pull request per head branch, from this repo only: a fork's pull request can
140  // carry a head branch of the same name.
141  const latest = new Map<string, { number: number; state: string; merged: boolean; headSha: string }>();
142  for (const pr of [...open.rows, ...closed.rows]) {
143    if (pr.head.repo?.full_name?.toLowerCase() !== full.toLowerCase()) continue;
144    const seen = latest.get(pr.head.ref);
145    if (!seen || pr.number > seen.number) {
146      latest.set(pr.head.ref, { number: pr.number, state: pr.state, merged: pr.merged_at !== null, headSha: pr.head.sha });
147    }
148  }
149
150  const prune: PruneCandidate[] = [];
151  const kept: PruneKeptRow[] = [];
152  // Names the caller said to leave alone, whatever their pull request says.
153  const keepNames = new Set(keep);
154  for (const b of branches.rows) {
155    if (keepNames.has(b.name)) {
156      kept.push({ branch: b.name, reason: "kept by request (keep)", sha: b.commit.sha, orphan: false });
157      continue;
158    }
159    const verdict = pruneVerdict({ name: b.name, sha: b.commit.sha, protected: b.protected === true }, defaultBranch, latest.get(b.name), listsComplete);
160    const shotsFor = !verdict.prune && verdict.orphan ? shotsInUse({ name: b.name, sha: b.commit.sha }, open.rows) : null;
161    if (shotsFor !== null) {
162      kept.push({ branch: b.name, reason: `screenshots for open pull request #${shotsFor}`, sha: b.commit.sha, orphan: false });
163      continue;
164    }
165    if (verdict.prune) prune.push({ branch: b.name, sha: b.commit.sha, pr: verdict.pr });
166    else kept.push({ branch: b.name, reason: verdict.reason, sha: b.commit.sha, orphan: verdict.orphan });
167  }
168  return { owner, name: repo, repo: full, defaultBranch, branchesRead: branches.rows.length, listsComplete, openComplete: open.complete, prune, kept };
169}
170
171/** Delete up to `cap` of the plan's candidates. Each tip is re-read immediately before its
172 *  delete, and a branch that moved since the plan was read is skipped, not deleted.
173 *  `onDeleted` runs after each delete and before the next, so a caller's record of one
174 *  delete is written before another happens; if it throws, nothing more is deleted. */
175export async function deletePruneCandidates(env: Env, plan: PrunePlan, cap: number, onDeleted?: (c: PruneCandidate) => Promise<void>) {
176  const { owner, name: repo } = plan;
177  const base = `/repos/${owner}/${repo}`;
178  const deleted: PruneCandidate[] = [];
179  const skipped: PruneKept[] = [];
180  const batch = plan.prune.slice(0, cap);
181  for (const c of batch) {
182    // The tip as it is now. A branch that moved since the list was read has new work.
183    let tip: string | undefined;
184    try {
185      const ref = await ghFetch(env, owner, repo, `${base}/git/ref/heads/${encodePath(c.branch)}`);
186      if (ref.ok) tip = ((await ref.json()) as { object?: { sha?: string } }).object?.sha;
187    } catch {
188      tip = undefined;
189    }
190    if (tip === undefined) {
191      skipped.push({ branch: c.branch, reason: "could not re-read the branch tip, so it was not deleted" });
192      continue;
193    }
194    if (tip !== c.sha) {
195      skipped.push({ branch: c.branch, reason: "the branch moved since the preview, so it was not deleted" });
196      continue;
197    }
198    const resp = await ghFetch(env, owner, repo, `${base}/git/refs/heads/${encodePath(c.branch)}`, { method: "DELETE" });
199    if (resp.ok || resp.status === 404 || resp.status === 422) {
200      if (resp.ok) {
201        deleted.push(c);
202        await onDeleted?.(c);
203      } else skipped.push({ branch: c.branch, reason: `already gone (${resp.status})` });
204    } else {
205      skipped.push({ branch: c.branch, reason: `GitHub refused the delete (${resp.status})` });
206    }
207  }
208  if (batch.length > 0) await invalidateRepoReads(env, owner, repo);
209  return { deleted, skipped, remaining: plan.prune.length - batch.length };
210}
211
212export async function pruneMergedBranches(env: Env, namespace: string, opts: { confirm?: boolean; keep?: string[] } = {}, repoSelector?: string) {
213  const plan = await readPrunePlan(env, namespace, opts.keep, repoSelector);
214  const kept = plan.kept.map(({ branch, reason }) => ({ branch, reason }));
215  const result = {
216    repo: plan.repo,
217    mode: opts.confirm ? ("delete" as const) : ("preview" as const),
218    branches_read: plan.branchesRead,
219    lists_complete: plan.listsComplete,
220    would_prune: plan.prune.length,
221    kept_count: kept.length,
222    kept: kept.slice(0, KEPT_LISTED),
223    kept_truncated: kept.length > KEPT_LISTED,
224    prune: plan.prune,
225    deleted: [] as string[],
226    skipped: [] as PruneKept[],
227    remaining: 0,
228  };
229  if (!opts.confirm) return result;
230
231  const done = await deletePruneCandidates(env, plan, DELETE_CAP);
232  result.deleted = done.deleted.map((c) => c.branch);
233  result.skipped = done.skipped;
234  result.remaining = done.remaining;
235  return result;
236}