@arjunkhera/atlas 0.4.35 → 0.4.36

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.35",
+  "version": "0.4.36",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/lib/gate.mjs

@@ -252,7 +252,7 @@ export const gateRunTitle = (pr, sha) => `gate #${pr} at ${sha}`;
 // The audit reads a merged pull request. GitHub then lists no pull request
 // on its runs, so with `audit` the two pull request pins are left out; the
 // file, the event, the head and the title still hold.
-export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [], audit = false }) {
+export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [], audit = false, baseChanged = () => '' }) {
   if (!run) return 'no workflow run';
   if (!homes.get(name)?.has(run.path)) return `from ${run.path ?? 'no file'}, not a base file that defines the check`;
   const event = name === GATE_CHECK ? 'pull_request_target' : 'pull_request';
@@ -272,6 +272,12 @@ export function refusal(run, { name, pr, sha, baseRef, homes, sides = () => [],
   const side = sides();
   if (side === null) return 'no head branch to check for side pull requests';
   if (side.length) return `the head branch also had #${side[0].number} into ${side[0].base?.ref ?? 'another branch'}`;
+  // A pull request can change its base. A run made while it pointed at a side
+  // branch used that branch's file, and the lists above no longer show it. So
+  // a run made before the last base change does not count (item 490bd791).
+  const changed = baseChanged();
+  if (changed === null) return `no events of #${pr} to check for a base change`;
+  if (changed && !(String(run.created_at ?? '') > changed)) return `made before the base of #${pr} last changed (${changed})`;
   return null;
 }
 
@@ -291,6 +297,77 @@ export function jobRefusal(job, check, run) {
   return null;
 }
 
+// Every event of one pull request, oldest first, or null when GitHub gives
+// none or more pages than `pages`. The newest event sits on the last page.
+function eventsOf(gh, repo, pr, pages = 10) {
+  const all = [];
+  for (let page = 1; page <= pages; page += 1) {
+    const got = gh('GET', `repos/${repo}/issues/${pr}/events?per_page=100&page=${page}`);
+    if (!Array.isArray(got)) return null;
+    all.push(...got);
+    if (got.length < 100) return all;
+  }
+  return null;
+}
+
+// The merge lock (item a638ce35). Two pull requests, each READY on the same
+// main tip, can merge seconds apart and turn the main branch red together
+// (atlas#214 and atlas#215). So a READY takes a lock: the label MERGE_LABEL
+// on its pull request. A lock lives LOCK_MS from its label event, a minute
+// longer than a READY file, or until its pull request closes. A label makes
+// no ref and starts no workflow. Times come from GitHub, not the local clock.
+export const MERGE_LABEL = 'atlas-merging';
+export const LOCK_MS = 11 * 60 * 1000;
+
+// The newest event that put the label on or took it off, or null. GitHub
+// lists the events oldest first.
+const labelEvents = (events) => events
+  .filter((each) => (each?.event === 'labeled' || each?.event === 'unlabeled') && each.label?.name === MERGE_LABEL);
+const lastLabelEvent = (events) => labelEvents(events).at(-1) ?? null;
+
+// `lock.on` says whether the pull request carries the label now.
+export function dropLock(gh, repo, pull, lock) {
+  if (!lock.on) return;
+  gh('DELETE', `repos/${repo}/issues/${pull.number}/labels/${MERGE_LABEL}`);
+  lock.on = false;
+}
+
+// Take the lock for `pull`. Returns null when it holds the lock, or why not;
+// the caller then takes the label off. Each caller puts its label on first,
+// then reads the others. Of two live labels, the older one wins, and the
+// lower number breaks a tie. So of two ready calls in the same seconds,
+// exactly one keeps its label.
+export function takeLock(gh, repo, pull, lock) {
+  // GitHub can show its events late, and an old label event would make this
+  // lock look older. Events only grow, so the label events are counted first:
+  // the read after must hold each new one, and the newest must put it on.
+  const before = eventsOf(gh, repo, pull.number);
+  if (!before) return { why: `GitHub gave no events of #${pull.number}` };
+  const made = lock.on ? 2 : 1;
+  // A new label event restarts the lock, so an old label comes off first.
+  dropLock(gh, repo, pull, lock);
+  gh('POST', `repos/${repo}/issues/${pull.number}/labels`, { labels: [MERGE_LABEL] });
+  lock.on = true;
+  const mine = eventsOf(gh, repo, pull.number);
+  const last = mine && lastLabelEvent(mine);
+  if (!mine || labelEvents(mine).length < labelEvents(before).length + made || last?.event !== 'labeled') return { why: `GitHub does not show the new label event on #${pull.number} yet` };
+  const at = String(last.created_at ?? '');
+  const held = gh('GET', `repos/${repo}/issues?labels=${MERGE_LABEL}&state=open&per_page=100`);
+  if (!Array.isArray(held)) return { why: 'GitHub gave no list of locked pull requests' };
+  for (const other of held) {
+    if (!other?.pull_request || Number(other.number) === Number(pull.number)) continue;
+    const events = eventsOf(gh, repo, other.number);
+    const theirs = events && lastLabelEvent(events);
+    if (!theirs) return { why: `GitHub shows no label event on #${other.number}`, pr: other.number };
+    // The list can be late too: a label already taken off holds no lock.
+    if (theirs.event !== 'labeled') continue;
+    const since = String(theirs.created_at ?? '');
+    if (Date.parse(at) - Date.parse(since) >= LOCK_MS) continue;
+    if (since < at || (since === at && Number(other.number) < Number(pull.number))) return { why: `#${other.number} holds the merge lock since ${since}`, pr: other.number };
+  }
+  return null;
+}
+
 // Every pull request, open or closed, from the head branch into another
 // branch. Read once, and only when a gate run needs it.
 function sidesOf(gh, repo, head, baseRef) {
@@ -304,6 +381,18 @@ function sidesOf(gh, repo, head, baseRef) {
   };
 }
 
+// The time of the last base change of one pull request, '' for none, or
+// null when GitHub gives no events. Read once, when the first run needs it.
+function baseChangedOf(gh, repo, pr) {
+  let changedAt;
+  return () => {
+    if (changedAt !== undefined) return changedAt;
+    const events = eventsOf(gh, repo, pr);
+    if (!events) return (changedAt = null);
+    return (changedAt = events.filter((each) => each?.event === 'base_ref_changed').map((each) => String(each.created_at ?? '')).sort().pop() ?? '');
+  };
+}
+
 // The workflow run of each check suite, read once.
 function suiteRuns(gh, repo) {
   const suites = new Map();
@@ -337,13 +426,14 @@ export function gateCopyRefusals(gh, repo, pull) {
 export function pinnedRuns(gh, repo, { pr, sha, baseRef, head, checks, homesRef = baseRef, audit = false }) {
   const homes = homesAt(gh, repo, homesRef, checks);
   const sides = sidesOf(gh, repo, head, baseRef);
+  const baseChanged = audit ? () => '' : baseChangedOf(gh, repo, pr);
   const runOf = suiteRuns(gh, repo);
   const kept = [];
   const refused = [];
   for (const check of checkRuns(gh, repo, sha)) {
     if (!checks.includes(check.name) || check.app?.id !== ACTIONS_APP_ID) continue;
     const run = runOf(check.check_suite?.id);
-    const why = refusal(run, { name: check.name, pr, sha, baseRef, homes, sides, audit })
+    const why = refusal(run, { name: check.name, pr, sha, baseRef, homes, sides, audit, baseChanged })
       ?? jobRefusal(check.id === undefined ? null : gh('GET', `repos/${repo}/actions/jobs/${check.id}`), check, run);
     if (why) refused.push({ name: check.name, why }); else kept.push(check);
   }
@@ -374,6 +464,20 @@ export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   const pull = gh('GET', `repos/${repo}/pulls/${pr}`);
   if (answer && typeof pull?.head?.sha === 'string') answer.sha = pull.head.sha;
   if (pull?.state !== 'open') { line(`atlas gate ready: pull request #${pr} is ${pull?.merged ? 'merged' : pull?.state ?? 'not found'}. NOT READY.`); return 1; }
+  // Any answer but READY, an error too, takes the merge label off.
+  const lock = { on: (pull.labels ?? []).some((each) => each?.name === MERGE_LABEL) };
+  let code;
+  try {
+    code = readyOpen({ repo, pr, pull, lock }, line, gh);
+    return code;
+  } finally {
+    if (code !== 0) {
+      try { dropLock(gh, repo, pull, lock); } catch (error) { if (code !== undefined) throw error; }
+    }
+  }
+}
+
+function readyOpen({ repo, pr, pull, lock }, line, gh) {
   const sha = pull.head.sha;
   let checks;
   try { checks = checksAt(gh, repo, pull.base.ref); } catch (error) {
@@ -395,7 +499,19 @@ export function readyCommand({ repo, pr, answer }, line, gh = ghApi) {
   if (!(behind >= 0)) throw new GateError(`GitHub gave no compare of ${pull.base.ref} and ${sha.slice(0, 7)}.`);
   line(`  ${behind === 0 ? '✓' : '✗'} ${(behind === 0 ? 'current' : 'behind').padEnd(8)} ${behind === 0 ? `the head holds every commit of ${pull.base.ref}` : `${pull.base.ref} has ${behind} commit(s) that the head does not hold`}`);
   const green = rows.every((row) => row.state === 'green');
-  if (green && behind === 0) { line('READY: every required check is green, on top of the current main branch. Merge with a merge commit, at this head.'); return 0; }
+  if (green && behind === 0) {
+    const held = takeLock(gh, repo, pull, lock);
+    if (held) {
+      line(`  ✗ locked   ${held.why}`);
+      line(held.pr
+        ? `NOT READY: do not merge. Wait for #${held.pr} to merge or for its lock to end (${LOCK_MS / 60000} min). Then merge ${pull.base.ref} in if it moved, and run ready again.`
+        : 'NOT READY: do not merge. The merge lock could not be read; run ready again.');
+      return 1;
+    }
+    line(`  ✓ lock     this pull request holds the merge lock (label ${MERGE_LABEL}) for ${LOCK_MS / 60000} min`);
+    line('READY: every required check is green, on top of the current main branch. Merge with a merge commit, at this head.');
+    return 0;
+  }
   line(behind > 0
     ? `NOT READY: do not merge. Merge ${pull.base.ref} in, wait for green, then run ready again.`
     : 'NOT READY: do not merge. Wait for a pending check; fix a red or missing one.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.35",
+  "version": "0.4.36",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",