@arjunkhera/atlas 0.4.34 → 0.4.36

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.34",
+  "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.34",
+  "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",

package/work/lib/numbers.mjs

@@ -35,11 +35,18 @@ export const SECOND_CHECK = 'passes-after';
 // package.json or a runner config changes for many reasons, so it is not.
 const TEST_GROUPS = Object.freeze(['unit-test', 'check-block', 'scenario-words', 'test-helper', 'kit-manifest']);
 // The GitHub counts and the tracker counts of one row.
-export const GITHUB_COUNTS = Object.freeze(['merges', 'not_on_green', 'reverts', 'unchecked_test_changes', 'signed_acts']);
+export const GITHUB_COUNTS = Object.freeze(['merges', 'not_on_green', 'reverts', 'unchecked_test_changes', 'signed_acts', 'audit_unsigned_merges']);
 export const GRAPH_COUNTS = Object.freeze(['reopens', 'step_ins', 'owner_messages', 'platform_messages']);
-// Line 2: the count that waits on an item not built yet. It is named, never
-// shown as zero.
-export const WAITING = Object.freeze({ audit_unsigned_merges: 'waits on R14 line 3, the unsigned-merge finding of the audit job' });
+// Line 2: the counts that wait on an item not built yet. Each is named, never
+// shown as zero. None waits now: R14 line 3 shipped the unsigned-merge finding.
+export const WAITING = Object.freeze({});
+// Line 2: the audit job (R14 line 3) opens one issue for each merge that the
+// gate sent to the owner with no signed act. GitHub Actions writes it, with
+// the label atlas-job and this title.
+export const AUDIT_LABEL = 'atlas-job';
+const AUDIT_TITLE = /^atlas-job: gate-audit owner-unsigned:([0-9a-f]{40})$/;
+const AUDIT_AUTHOR = 'github-actions[bot]';
+const MAX_ISSUE_PAGES = 10;
 
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 const dayOf = (value) => String(value ?? '').slice(0, 10);
@@ -108,6 +115,26 @@ async function readAllFiles(repo, number, readGitHub) {
   throw new Error(`pull request ${number} changed more than ${MAX_FILE_PAGES * PAGE} files`);
 }
 
+// Line 2: the merge commits that the audit job reported as unsigned, from
+// its issues opened since the start of the period. Only an issue that GitHub
+// Actions opened counts, so a person cannot add one by hand. A closed issue
+// still counts: the merge happened. More than MAX_ISSUE_PAGES pages is
+// refused, never cut.
+export async function readUnsignedMerges(repo, readGitHub, sinceAt) {
+  const shas = new Set();
+  const since = new Date(sinceAt).toISOString();
+  for (let page = 1; page <= MAX_ISSUE_PAGES; page += 1) {
+    const rows = await readGitHub(`repos/${repo}/issues?labels=${AUDIT_LABEL}&state=all&since=${since}&per_page=${PAGE}&page=${page}`);
+    if (!Array.isArray(rows)) throw new Error('the audit issues are not a list');
+    for (const row of rows) {
+      const match = AUDIT_TITLE.exec(String(row?.title ?? ''));
+      if (match && row?.user?.login === AUDIT_AUTHOR && !row.pull_request) shas.add(match[1].toLowerCase());
+    }
+    if (rows.length < PAGE) return shas;
+  }
+  throw new Error(`more than ${MAX_ISSUE_PAGES * PAGE} audit issues`);
+}
+
 // Line 2: the comment texts of one pull request, every page. More than
 // MAX_COMMENT_PAGES pages is refused, never cut.
 export async function readAllComments(repo, number, readGitHub) {
@@ -222,6 +249,7 @@ export async function readMerges({ repo, defaultBranch, period, readGitHub }) {
     const text = await textAt('atlas.yaml', sha);
     return text === null ? [] : deliveryFacts(text).required;
   };
+  const unsigned = await readUnsignedMerges(repo, readGitHub, period.start);
   return pool(merges.map((pull) => async () => {
     const head = pull.head?.sha, merge = pull.merge_commit_sha;
     if (!/^[0-9a-f]{40}$/i.test(String(head)) || !/^[0-9a-f]{40}$/i.test(String(merge))) throw new Error(`GitHub names no head or merge commit for pull request ${pull.number}`);
@@ -245,6 +273,7 @@ export async function readMerges({ repo, defaultBranch, period, readGitHub }) {
     const signed = keys.length ? signedActOf({ repo, pull, texts: await readAllComments(repo, pull.number, readGitHub), keys }) : null;
     return {
       repo, number: pull.number, url: pull.html_url ?? `https://github.com/${repo}/pull/${pull.number}`, title: oneLine(pull.title ?? '', 200), merged_at: pull.merged_at,
+      audit_unsigned: unsigned.has(String(merge).toLowerCase()),
       not_on_green: notOnGreenReasons({ required, runs, mergedAt: pull.merged_at }), revert: isRevert(pull),
       changed_tests: tests, signed, unchecked: tests.length > 0 && !signed && !secondCheckPassed(runs, pull.merged_at),
     };
@@ -320,6 +349,7 @@ export async function readNumbers({ product, repos, items, marks, period, readGi
       if (merge.revert) events.push(['reverts', merge.merged_at]);
       if (merge.unchecked) events.push(['unchecked_test_changes', merge.merged_at]);
       if (merge.signed) events.push(['signed_acts', merge.merged_at]);
+      if (merge.audit_unsigned) events.push(['audit_unsigned_merges', merge.merged_at]);
     }
     for (const mark of reopens) if (itemRepos.get(mark.fields.item).includes(repo.id)) events.push(['reopens', mark.fields.marked_at]);
     for (const pair of pairs) {
@@ -341,6 +371,7 @@ export async function readNumbers({ product, repos, items, marks, period, readGi
       not_on_green: refused ? null : merges.filter((merge) => merge.not_on_green.length).map((merge) => ({ pr: merge.url, merged_at: merge.merged_at, reasons: merge.not_on_green })),
       reverts: refused ? null : merges.filter((merge) => merge.revert).map((merge) => ({ pr: merge.url, title: merge.title })),
       unchecked_test_changes: refused ? null : merges.filter((merge) => merge.unchecked).map((merge) => ({ pr: merge.url, tests: merge.changed_tests })),
+      audit_unsigned_merges: refused ? null : merges.filter((merge) => merge.audit_unsigned).map((merge) => ({ pr: merge.url, merged_at: merge.merged_at })),
       signed_acts: refused ? null : merges.filter((merge) => merge.signed).map((merge) => ({ pr: merge.url, signed_at: merge.signed.signed_at, key: merge.signed.key })),
     });
   }

package/work/lib/roundup.mjs

@@ -266,7 +266,7 @@ function render(view) {
 }
 
 // Part 6. A refused count reads "refused", never 0.
-const COLUMNS = [['merges', 'merges'], ['not_on_green', 'not on green'], ['reverts', 'reverts'], ['unchecked_test_changes', 'unchecked test changes'], ['signed_acts', 'signed acts'], ['reopens', 'reopens'], ['step_ins', 'step-ins'], ['owner_messages', 'owner messages'], ['platform_messages', 'platform messages']];
+const COLUMNS = [['merges', 'merges'], ['not_on_green', 'not on green'], ['reverts', 'reverts'], ['unchecked_test_changes', 'unchecked test changes'], ['signed_acts', 'signed acts'], ['audit_unsigned_merges', 'unsigned merges'], ['reopens', 'reopens'], ['step_ins', 'step-ins'], ['owner_messages', 'owner messages'], ['platform_messages', 'platform messages']];
 const countsLine = (row) => COLUMNS.map(([key, word]) => `${row[key] === null ? 'refused' : row[key]} ${word}`).join(' · ');
 function renderNumbers(numbers, more) {
   const out = [`6. The numbers, ${numbers.from} to ${numbers.to} (UTC)`];
@@ -284,7 +284,7 @@ function renderNumbers(numbers, more) {
   out.push(`   input to live: ${numbers.delivered.length} delivered ${numbers.delivered.length === 1 ? 'item' : 'items'}${median === null ? '' : `, median ${median} days`}`);
   for (const row of numbers.delivered.slice(0, SHOWN)) out.push(listLine(row.title, `${row.item.slice(0, 8)} · ${row.days ?? '?'} days · live ${dayOf(row.live_at)}`, '     '));
   out.push(...more(numbers.delivered));
-  out.push(`   owner acts: unsigned merges ${numbers.owner_acts.audit_unsigned_merges}`);
+  for (const [count, wait] of Object.entries(numbers.owner_acts ?? {})) out.push(`   ${count.replace(/_/g, ' ')}: ${wait}`);
   if (numbers.not_counted_sessions) out.push(`   ${numbers.not_counted_sessions} sessions ran with the hooks off, so their messages were not counted`);
   return out.join('\n');
 }

package/work/mcp.mjs

@@ -227,6 +227,9 @@ export const GITHUB_READS = Object.freeze([
   // and the owner key file at the first parent of the merge.
   new RegExp(`^repos/${REPO}/issues/\\d{1,9}/comments\\?per_page=\\d{1,3}&page=\\d{1,3}$`),
   new RegExp(`^repos/${REPO}/contents/atlas/owner-signers\\?ref=${SHA}$`),
+  // Roadmap R16 line 2: the audit issues of the period, for the merges that
+  // the audit job reported as unsigned.
+  new RegExp(`^repos/${REPO}/issues\\?labels=atlas-job&state=all&since=\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z&per_page=\\d{1,3}&page=\\d{1,3}$`),
 ]);
 export function githubReader() {
   return async (path) => {