[WRONG BRANCH] promote dev onto main for v2.34.0

.github/scripts/closed-pr-branch-cleanup.cjs

@@ -0,0 +1,226 @@
+"use strict";
+
+/**
+ * Deletion planning for branches left behind by closed-without-merge pull
+ * requests.
+ *
+ * GitHub's repository-level `delete_branch_on_merge` only fires on merge, so a
+ * PR that is closed unmerged leaves its head branch in the repository forever.
+ * This module decides which of those branches may be deleted; the workflow
+ * performs the deletion.
+ *
+ * Kept as a pure module so the safety rules can be unit-tested without Actions
+ * and without a live repository.
+ */
+
+/** Branches that may never be deleted regardless of pull-request state. */
+const PROTECTED_BRANCHES = Object.freeze(["main", "dev", "preview", "gh-pages"]);
+
+/** Default grace period before a closed PR's head branch becomes eligible. */
+const DEFAULT_GRACE_DAYS = 14;
+
+function normalizeBranchName(value) {
+  return String(value || "").trim();
+}
+
+/**
+ * A commit id, lowercased for comparison.
+ *
+ * The REST and GraphQL APIs are not consistent about case, and a full 40-character
+ * sha compared case-sensitively against an abbreviated or upper-case one silently
+ * reads as "different" - which here would mean "keep", so the failure direction is
+ * safe, but it would make the guard useless rather than protective. Anything that
+ * is not a plausible hex object id becomes null, i.e. unknown.
+ */
+function normalizeOid(value) {
+  const text = String(value || "").trim().toLowerCase();
+  return /^[0-9a-f]{7,64}$/.test(text) ? text : null;
+}
+
+function isProtectedBranch(name) {
+  return PROTECTED_BRANCHES.includes(normalizeBranchName(name));
+}
+
+function toTimestamp(value) {
+  if (!value) return null;
+  const ms = Date.parse(String(value));
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Reasons a candidate branch is kept. Exported so the workflow can log a
+ * stable, greppable verdict per branch instead of a free-form sentence.
+ */
+const KEEP_REASONS = Object.freeze({
+  PROTECTED: "protected-branch",
+  MERGED: "pull-request-merged",
+  OPEN: "open-pull-request",
+  BASE_OF_OPEN: "base-of-open-pull-request",
+  CROSS_REPOSITORY: "cross-repository-head",
+  MISSING_CLOSED_AT: "missing-closed-at",
+  WITHIN_GRACE: "within-grace-period",
+  MOVED_SINCE_CLOSE: "branch-moved-since-close",
+  UNKNOWN_HEAD_SHA: "unknown-head-sha",
+});
+
+/**
+ * Plan deletions for head branches of closed-unmerged pull requests.
+ *
+ * Every rule here is a safety rule, and each one exists because the opposite
+ * behavior destroys work that is still referenced:
+ *
+ * - A branch is a candidate only when *every* pull request that ever used it as
+ *   a head is closed and unmerged. One open or merged PR on the same branch
+ *   keeps it, because reopening a PR whose head branch is gone cannot restore
+ *   the commits.
+ * - A branch that is the base of an open pull request is kept. Deleting it
+ *   closes the stacked child PR that targets it.
+ * - Cross-repository (fork) heads are never touched: they live in the
+ *   contributor's repository and this token has no business there.
+ * - A grace period after `closed_at` leaves room to reopen a PR that was
+ *   closed by mistake.
+ * - The branch must still POINT AT a commit one of those closed pull requests
+ *   had as its head. Matching by NAME alone deletes reused work: `codex/`-style
+ *   names get picked up again all the time, and a branch recreated for new work
+ *   inherits the closed history of every PR that ever used that name. The tip
+ *   moved, so the branch is not the closed PR's branch any more - it only shares
+ *   its label.
+ * - A branch whose current tip cannot be determined is kept. An unknown tip is
+ *   not evidence of an abandoned branch, and this job's mistakes are not
+ *   recoverable.
+ *
+ * @param {object} input
+ * @param {Array<object>} input.pullRequests Pull requests with
+ *   `headRefName`, `headRefOid`, `baseRefName`, `state`, `merged`, `closedAt`,
+ *   and `isCrossRepository`.
+ * @param {Array<string|{name: string, oid?: string}>} input.branches Branches
+ *   that currently exist. A bare string carries no tip, which is treated as an
+ *   unknown tip and kept.
+ * @param {number} [input.now] Current time in milliseconds.
+ * @param {number} [input.graceDays] Days to wait after `closedAt`.
+ * @returns {{ deletions: Array<{branch: string, pullRequests: number[]}>,
+ *   keeps: Array<{branch: string, reason: string}> }}
+ */
+function planClosedPrBranchDeletions({
+  pullRequests = [],
+  branches = [],
+  now = Date.now(),
+  graceDays = DEFAULT_GRACE_DAYS,
+}) {
+  // Accepts both shapes so an older caller passing bare names still works - it
+  // just gets the conservative answer, because a name without a tip cannot be
+  // proven safe to delete.
+  /** @type {Map<string, string|null>} */
+  const existing = new Map();
+  for (const entry of branches) {
+    const name = normalizeBranchName(typeof entry === "string" ? entry : entry && entry.name);
+    if (!name) continue;
+    const oid = typeof entry === "string" ? null : normalizeOid(entry && entry.oid);
+    existing.set(name, oid);
+  }
+  const graceMs = Math.max(0, Number(graceDays) || 0) * 24 * 60 * 60 * 1000;
+
+  /** @type {Map<string, object[]>} */
+  const byHead = new Map();
+  const openBases = new Set();
+
+  for (const pr of pullRequests) {
+    const head = normalizeBranchName(pr && pr.headRefName);
+    if (head) {
+      const list = byHead.get(head) || [];
+      list.push(pr);
+      byHead.set(head, list);
+    }
+    const isOpen = String(pr && pr.state).toUpperCase() === "OPEN";
+    if (isOpen) {
+      const base = normalizeBranchName(pr && pr.baseRefName);
+      if (base) openBases.add(base);
+    }
+  }
+
+  const deletions = [];
+  const keeps = [];
+
+  for (const branch of [...existing.keys()].sort()) {
+    if (isProtectedBranch(branch)) {
+      keeps.push({ branch, reason: KEEP_REASONS.PROTECTED });
+      continue;
+    }
+
+    const related = byHead.get(branch) || [];
+    if (related.length === 0) continue; // No PR ever used it; out of scope.
+
+    if (related.some((pr) => pr && pr.isCrossRepository === true)) {
+      keeps.push({ branch, reason: KEEP_REASONS.CROSS_REPOSITORY });
+      continue;
+    }
+    if (related.some((pr) => pr && pr.merged === true)) {
+      keeps.push({ branch, reason: KEEP_REASONS.MERGED });
+      continue;
+    }
+    if (related.some((pr) => String(pr && pr.state).toUpperCase() === "OPEN")) {
+      keeps.push({ branch, reason: KEEP_REASONS.OPEN });
+      continue;
+    }
+    if (openBases.has(branch)) {
+      keeps.push({ branch, reason: KEEP_REASONS.BASE_OF_OPEN });
+      continue;
+    }
+
+    const closedTimestamps = related.map((pr) => toTimestamp(pr && pr.closedAt));
+    if (closedTimestamps.some((ts) => ts === null)) {
+      keeps.push({ branch, reason: KEEP_REASONS.MISSING_CLOSED_AT });
+      continue;
+    }
+    const newestClosedAt = Math.max(...closedTimestamps);
+    if (now - newestClosedAt < graceMs) {
+      keeps.push({ branch, reason: KEEP_REASONS.WITHIN_GRACE });
+      continue;
+    }
+
+    // The tip check, last because it is the most expensive claim to satisfy and
+    // the cheaper rules above have already excluded most branches.
+    //
+    // A closed PR's head branch is only THIS branch if the branch still points at
+    // a commit that PR had as its head. Without this, a name reused for new work
+    // is deleted on the strength of an unrelated PR that happened to share the
+    // label months earlier - and a deleted branch whose commits were never pushed
+    // anywhere else is gone.
+    const currentOid = existing.get(branch) || null;
+    if (!currentOid) {
+      keeps.push({ branch, reason: KEEP_REASONS.UNKNOWN_HEAD_SHA });
+      continue;
+    }
+    const closedOids = new Set(
+      related.map((pr) => normalizeOid(pr && pr.headRefOid)).filter(Boolean),
+    );
+    // An empty set means the API gave us no head SHA for any of them, which is the
+    // unknown case again rather than a licence to delete.
+    if (closedOids.size === 0) {
+      keeps.push({ branch, reason: KEEP_REASONS.UNKNOWN_HEAD_SHA });
+      continue;
+    }
+    if (!closedOids.has(currentOid)) {
+      keeps.push({ branch, reason: KEEP_REASONS.MOVED_SINCE_CLOSE });
+      continue;
+    }
+
+    deletions.push({
+      branch,
+      pullRequests: related
+        .map((pr) => Number(pr && pr.number))
+        .filter((n) => Number.isFinite(n))
+        .sort((a, b) => a - b),
+    });
+  }
+
+  return { deletions, keeps };
+}
+
+module.exports = {
+  DEFAULT_GRACE_DAYS,
+  KEEP_REASONS,
+  PROTECTED_BRANCHES,
+  isProtectedBranch,
+  planClosedPrBranchDeletions,
+};

.github/scripts/closed-pr-branch-cleanup.test.cjs

@@ -0,0 +1,165 @@
+"use strict";
+
+const { describe, it } = require("node:test");
+const assert = require("node:assert/strict");
+const {
+  DEFAULT_GRACE_DAYS,
+  KEEP_REASONS,
+  isProtectedBranch,
+  planClosedPrBranchDeletions,
+} = require("./closed-pr-branch-cleanup.cjs");
+
+const NOW = Date.parse("2026-08-26T00:00:00Z");
+const DAY = 24 * 60 * 60 * 1000;
+const longAgo = new Date(NOW - 60 * DAY).toISOString();
+
+function closedPr(overrides) {
+  return {
+    number: 1,
+    state: "CLOSED",
+    merged: false,
+    isCrossRepository: false,
+    headRefName: "codex/example",
+    baseRefName: "dev",
+    closedAt: longAgo,
+    ...overrides,
+  };
+}
+
+function keepReason(result, branch) {
+  const hit = result.keeps.find((entry) => entry.branch === branch);
+  return hit ? hit.reason : null;
+}
+
+function deletedBranches(result) {
+  return result.deletions.map((entry) => entry.branch);
+}
+
+describe("isProtectedBranch", () => {
+  it("protects the integration, release, and prerelease lines", () => {
+    for (const name of ["main", "dev", "preview", "gh-pages"]) {
+      assert.equal(isProtectedBranch(name), true, name);
+    }
+    assert.equal(isProtectedBranch("codex/dev"), false);
+  });
+});
+
+describe("planClosedPrBranchDeletions", () => {
+  it("deletes a branch whose only pull request closed unmerged past the grace period", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [closedPr({ number: 42, headRefName: "codex/stale" })],
+      branches: ["codex/stale", "dev"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), ["codex/stale"]);
+    assert.deepEqual(result.deletions[0].pullRequests, [42]);
+  });
+
+  it("keeps a branch that any merged pull request used as a head", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [
+        closedPr({ number: 10, headRefName: "codex/reused" }),
+        closedPr({ number: 11, headRefName: "codex/reused", state: "MERGED", merged: true }),
+      ],
+      branches: ["codex/reused"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+    assert.equal(keepReason(result, "codex/reused"), KEEP_REASONS.MERGED);
+  });
+
+  it("keeps a branch that still has an open pull request", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [
+        closedPr({ number: 20, headRefName: "codex/active" }),
+        closedPr({ number: 21, headRefName: "codex/active", state: "OPEN", closedAt: null }),
+      ],
+      branches: ["codex/active"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+    assert.equal(keepReason(result, "codex/active"), KEEP_REASONS.OPEN);
+  });
+
+  it("keeps a closed stack parent while an open child still targets it", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [
+        closedPr({ number: 30, headRefName: "codex/stack-1" }),
+        closedPr({
+          number: 31,
+          state: "OPEN",
+          closedAt: null,
+          headRefName: "codex/stack-2",
+          baseRefName: "codex/stack-1",
+        }),
+      ],
+      branches: ["codex/stack-1", "codex/stack-2"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+    assert.equal(keepReason(result, "codex/stack-1"), KEEP_REASONS.BASE_OF_OPEN);
+  });
+
+  it("never touches a fork head branch", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [
+        closedPr({ number: 40, headRefName: "patch-1", isCrossRepository: true }),
+      ],
+      branches: ["patch-1"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+    assert.equal(keepReason(result, "patch-1"), KEEP_REASONS.CROSS_REPOSITORY);
+  });
+
+  it("waits out the grace period so a mistaken close can be reopened", () => {
+    const recent = new Date(NOW - 3 * DAY).toISOString();
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [closedPr({ number: 50, headRefName: "codex/recent", closedAt: recent })],
+      branches: ["codex/recent"],
+      now: NOW,
+      graceDays: DEFAULT_GRACE_DAYS,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+    assert.equal(keepReason(result, "codex/recent"), KEEP_REASONS.WITHIN_GRACE);
+  });
+
+  it("keeps a branch when a closed pull request has no closed_at timestamp", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [closedPr({ number: 60, headRefName: "codex/unknown", closedAt: null })],
+      branches: ["codex/unknown"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+    assert.equal(keepReason(result, "codex/unknown"), KEEP_REASONS.MISSING_CLOSED_AT);
+  });
+
+  it("refuses to delete a protected branch even if a closed pull request used it", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [closedPr({ number: 70, headRefName: "dev" })],
+      branches: ["dev", "main", "preview"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+    assert.equal(keepReason(result, "dev"), KEEP_REASONS.PROTECTED);
+  });
+
+  it("ignores branches that no pull request ever used", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [closedPr({ number: 80, headRefName: "codex/known" })],
+      branches: ["codex/known", "codex/never-a-pr"],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), ["codex/known"]);
+    assert.equal(keepReason(result, "codex/never-a-pr"), null);
+  });
+
+  it("only plans deletions for branches that still exist", () => {
+    const result = planClosedPrBranchDeletions({
+      pullRequests: [closedPr({ number: 90, headRefName: "codex/already-gone" })],
+      branches: [],
+      now: NOW,
+    });
+    assert.deepEqual(deletedBranches(result), []);
+  });
+});