forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/pr-bundle.js

@@ -86,12 +86,12 @@ async function gatherUnresolvedComments(adapter, { owner, repo, pr }) {
  * Predict merge conflicts. `detectConflicts` is optional on the adapter; when
  * absent or failing, report it as unsupported rather than throwing.
  */
-async function gatherConflicts(adapter, { baseRef, cwd }) {
+async function gatherConflicts(adapter, { baseRef, cwd, headRef }) {
   if (typeof adapter.detectConflicts !== 'function') {
     return { supported: false, reason: 'adapter has no detectConflicts capability' };
   }
   try {
-    return await adapter.detectConflicts({ baseRef, cwd });
+    return await adapter.detectConflicts({ baseRef, cwd, headRef });
   } catch (error) {
     return { supported: false, reason: error.message || 'conflict detection failed' };
   }
@@ -148,9 +148,9 @@ async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter })
   // silently yields a null required set. `pr` lets the adapter fall back to the
   // rollup `isRequired` set when branch protection is unreadable in CI.
   const requiredRaw = await adapter.readRequiredChecks({ owner, repo, base, pr });
-  const divergence = await adapter.readDivergence({ baseRef, cwd });
+  const divergence = await adapter.readDivergence({ baseRef, cwd, headRef: state.headSha });
   const comments = await gatherUnresolvedComments(adapter, { owner, repo, pr });
-  const conflicts = await gatherConflicts(adapter, { baseRef, cwd });
+  const conflicts = await gatherConflicts(adapter, { baseRef, cwd, headRef: state.headSha });
 
   const requiredSet = requiredRaw === undefined ? null : requiredRaw;
 
@@ -172,8 +172,7 @@ async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter })
       state: String(state.state || 'OPEN').toUpperCase(),
     },
     ci: buildCi(state.checks, requiredSet),
-    // Which source answered the required-checks read (`protection` | `rollup` |
-    // null) — `rollup` is the CI path where branch protection is unreadable.
+    // The authoritative required-check source (`protection` or null).
     requiredSource: adapter.lastRequiredSource || null,
     branch: {
       ahead: divergence.ahead || 0,

package/lib/pr-monitor/auto-actions.js

@@ -35,6 +35,17 @@ const INFRA_CONCLUSIONS = new Set(['CANCELLED', 'TIMED_OUT', 'STALE', 'STARTUP_F
 /** Conclusions that mean the code is genuinely broken — NEVER auto-rerun these. */
 const REAL_FAILURE_CONCLUSIONS = new Set(['FAILURE', 'ERROR', 'ACTION_REQUIRED']);
 
+const AUTO_ACTION_STATUS = Object.freeze({
+  PASS: 'PASS',
+  UNCHANGED: 'UNCHANGED',
+  STALE: 'STALE',
+  INCOMPLETE: 'INCOMPLETE',
+  CONFLICT: 'CONFLICT',
+});
+
+const MAX_AUTO_ACTIONS = 8;
+const MAX_AUTO_ATTEMPTS = 5;
+
 /**
  * Pull the numeric Actions run id from a job/run "details" URL
  * (`.../actions/runs/<run>/job/<job>` or `.../actions/runs/<run>`). Returns null
@@ -99,16 +110,40 @@ function decideUpdateBranch(payload, opts = {}) {
   return { should: true, reason: 'otherwise-clean-behind — only blocker is behind-base; merge base in' };
 }
 
+function indexFailures(failures) {
+  const byName = new Map();
+  for (const failure of failures) {
+    if (!failure?.name || byName.has(failure.name)) continue;
+    byName.set(failure.name, {
+      conclusion: String(failure.conclusion || '').toUpperCase(),
+      url: failure.jobUrl || failure.detailsUrl || null,
+    });
+  }
+  return byName;
+}
+
+function selectRerunChecks(failingNames, failuresByName) {
+  const checks = [];
+  for (const name of failingNames) {
+    const failure = failuresByName.get(name);
+    if (!failure?.conclusion) {
+      return { reason: `required check "${name}" has no known conclusion — cannot confirm flaky, fail closed` };
+    }
+    if (REAL_FAILURE_CONCLUSIONS.has(failure.conclusion)) {
+      return { reason: `required check "${name}" is a real failure (${failure.conclusion}) — never rerun` };
+    }
+    if (!INFRA_CONCLUSIONS.has(failure.conclusion)) {
+      return { reason: `required check "${name}" conclusion ${failure.conclusion} is not classified infrastructural — fail closed` };
+    }
+    checks.push({ name, conclusion: failure.conclusion, runId: runIdFromUrl(failure.url) });
+  }
+  return { checks };
+}
+
 /**
  * Decide whether to re-run flaky REQUIRED checks. Fires ONLY when EVERY failing
- * required check is infrastructural (cancelled/timed-out/stale/startup-failure)
- * with a derivable run id, and NONE is a real FAILURE/ERROR/ACTION_REQUIRED. A
- * single real failure, an unclassifiable conclusion, a required-failing check
- * with no matching `failures[]` entry, or a missing run id fails the WHOLE
- * decision closed (never rerun a genuinely-broken PR, never loop on a real bug).
- *
- * @param {object} payload - the `--pull --json` payload.
- * @returns {{ should: boolean, checks: Array<{name:string,conclusion:string,runId:string|null}>, runIds: string[], reason: string }}
+ * required check is infrastructural with a derivable run id, and NONE is a real
+ * failure or an unclassifiable signal.
  */
 function decideRerun(payload) {
   const empty = (reason) => ({ should: false, checks: [], runIds: [], reason });
@@ -119,28 +154,15 @@ function decideRerun(payload) {
   const failingNames = Array.isArray(rc.failing) ? rc.failing : [];
   if (failingNames.length === 0) return empty('no failing required checks');
 
-  const failures = Array.isArray(payload.failures) ? payload.failures : [];
-  const conclByName = new Map();
-  const urlByName = new Map();
-  for (const f of failures) {
-    if (!f || !f.name) continue;
-    if (!conclByName.has(f.name)) {
-      conclByName.set(f.name, String(f.conclusion || '').toUpperCase());
-      urlByName.set(f.name, f.jobUrl || f.detailsUrl || null);
-    }
-  }
-
-  const picked = [];
-  for (const name of failingNames) {
-    const concl = conclByName.get(name);
-    if (!concl) return empty(`required check "${name}" has no known conclusion — cannot confirm flaky, fail closed`);
-    if (REAL_FAILURE_CONCLUSIONS.has(concl)) return empty(`required check "${name}" is a real failure (${concl}) — never rerun`);
-    if (!INFRA_CONCLUSIONS.has(concl)) return empty(`required check "${name}" conclusion ${concl} is not classified infrastructural — fail closed`);
-    picked.push({ name, conclusion: concl, runId: runIdFromUrl(urlByName.get(name)) });
-  }
+  const selection = selectRerunChecks(
+    failingNames,
+    indexFailures(Array.isArray(payload.failures) ? payload.failures : []),
+  );
+  if (selection.reason) return empty(selection.reason);
 
+  const picked = selection.checks;
   const runIds = [...new Set(picked.map((p) => p.runId).filter(Boolean))];
-  if (runIds.length === 0) return empty('no run id derivable from failure jobUrl — fail closed');
+  if (picked.some((item) => !item.runId)) return empty('no run id derivable from failure jobUrl — fail closed');
   return {
     should: true,
     checks: picked,
@@ -164,6 +186,123 @@ function decideAutoActions(payload, opts = {}) {
   };
 }
 
+function boundedPolicyValue(value, fallback, maximum) {
+  const selected = value ?? fallback;
+  return Number.isSafeInteger(selected) && selected > 0 && selected <= maximum ? selected : null;
+}
+
+function normalizeActionHistory(history) {
+  if (!Array.isArray(history)) return { ok: false, reason: 'action history is incomplete' };
+  const byKey = new Map();
+  for (const item of history) {
+    if (!item || typeof item.key !== 'string' || !item.key
+      || !['pending', 'applied', 'failed'].includes(item.state)
+      || !Number.isSafeInteger(item.attempts) || item.attempts < 0) {
+      return { ok: false, reason: 'action history is incomplete' };
+    }
+    const prior = byKey.get(item.key);
+    if (prior && (prior.state !== item.state || prior.attempts !== item.attempts)) {
+      return { ok: false, conflict: true, reason: `action history conflicts for ${item.key}` };
+    }
+    if (!prior) byKey.set(item.key, item);
+  }
+  return { ok: true, byKey };
+}
+
+function validateAutoActionAuthority(payload) {
+  if (!payload?.evidence || !Array.isArray(payload.evidence.unreadable)
+    || typeof payload.evidence.tornRead !== 'boolean') {
+    return { ok: false, reason: 'verdict evidence is incomplete' };
+  }
+  if (payload.draft !== false) {
+    return { ok: false, reason: 'non-draft authority is incomplete' };
+  }
+
+  const failuresByName = new Map();
+  for (const failure of Array.isArray(payload.failures) ? payload.failures : []) {
+    if (!failure || typeof failure.name !== 'string' || !failure.name) continue;
+    const evidence = {
+      conclusion: String(failure.conclusion || '').toUpperCase(),
+      url: failure.jobUrl || failure.detailsUrl || null,
+    };
+    const prior = failuresByName.get(failure.name);
+    if (prior && (prior.conclusion !== evidence.conclusion || prior.url !== evidence.url)) {
+      return { ok: false, conflict: true, reason: `required check evidence conflicts for ${failure.name}` };
+    }
+    if (!prior) failuresByName.set(failure.name, evidence);
+  }
+  return { ok: true };
+}
+
+function buildAutoActionCandidates(decision, subjectRevision) {
+  const candidates = [];
+  if (decision.updateBranch.should) {
+    candidates.push({ type: 'updateBranch', key: `updateBranch:${subjectRevision}`, subjectRevision });
+  }
+  if (decision.rerunFlaky.should) {
+    const runIds = [...decision.rerunFlaky.runIds].sort((left, right) => left.localeCompare(right));
+    for (const runId of runIds) {
+      candidates.push({
+        type: 'rerunFlaky',
+        key: `rerunFlaky:${subjectRevision}:${runId}`,
+        subjectRevision,
+        runId,
+      });
+    }
+  }
+  return candidates;
+}
+
+function selectBoundedActions(candidates, history, maxActions, maxAttempts) {
+  const actions = [];
+  for (const candidate of candidates) {
+    const prior = history.get(candidate.key);
+    if (prior && (prior.state === 'pending' || prior.state === 'applied' || prior.attempts >= maxAttempts)) continue;
+    actions.push({ ...candidate, attempt: prior ? prior.attempts + 1 : 1 });
+    if (actions.length === maxActions) break;
+  }
+  return actions;
+}
+
+/** Select a deterministic, per-head, bounded action/retry batch. */
+function decideBoundedAutoActions(payload, opts = {}) {
+  const closed = (status, reason) => ({ status, reason, actions: [] });
+  const subjectRevision = payload?.headSha;
+  if (typeof subjectRevision !== 'string' || !/^[0-9a-f]{40}$/i.test(subjectRevision)) {
+    return closed(AUTO_ACTION_STATUS.INCOMPLETE, 'exact head authority is incomplete');
+  }
+  if (opts.expectedRevision != null && opts.expectedRevision !== subjectRevision) {
+    return closed(AUTO_ACTION_STATUS.STALE, 'payload head does not match expected revision');
+  }
+  const authority = validateAutoActionAuthority(payload);
+  if (!authority.ok) {
+    return closed(authority.conflict ? AUTO_ACTION_STATUS.CONFLICT : AUTO_ACTION_STATUS.INCOMPLETE, authority.reason);
+  }
+  const maxActions = boundedPolicyValue(opts.maxActions, 1, MAX_AUTO_ACTIONS);
+  const maxAttempts = boundedPolicyValue(opts.maxAttempts, 2, MAX_AUTO_ATTEMPTS);
+  if (maxActions == null || maxAttempts == null) {
+    return closed(AUTO_ACTION_STATUS.INCOMPLETE, 'auto-action policy exceeds bounded limits');
+  }
+  const history = normalizeActionHistory(opts.history || []);
+  if (!history.ok) {
+    return closed(history.conflict ? AUTO_ACTION_STATUS.CONFLICT : AUTO_ACTION_STATUS.INCOMPLETE, history.reason);
+  }
+
+  const decision = decideAutoActions(payload, opts);
+  if (decision.updateBranch.should && decision.rerunFlaky.should) {
+    return closed(AUTO_ACTION_STATUS.CONFLICT, 'payload authorizes conflicting update and rerun actions');
+  }
+
+  const candidates = buildAutoActionCandidates(decision, subjectRevision);
+  const actions = selectBoundedActions(candidates, history.byKey, maxActions, maxAttempts);
+  if (actions.length === 0) {
+    return closed(AUTO_ACTION_STATUS.UNCHANGED, candidates.length === 0
+      ? 'no safe auto-action transition'
+      : 'identical actions are pending, applied, or retry-exhausted');
+  }
+  return { status: AUTO_ACTION_STATUS.PASS, reason: 'bounded auto-actions selected', actions };
+}
+
 module.exports = {
   decideAutoActions,
   decideUpdateBranch,
@@ -172,4 +311,6 @@ module.exports = {
   isDegraded,
   INFRA_CONCLUSIONS,
   REAL_FAILURE_CONCLUSIONS,
+  AUTO_ACTION_STATUS,
+  decideBoundedAutoActions,
 };

package/lib/pr-monitor/differ.js

@@ -14,6 +14,107 @@
  */
 
 const { EVENT_TYPES: T, makeEvent } = require('./events');
+const {
+  VERDICT_STATES,
+  normalizePrNumber,
+  normalizeRepository,
+  normalizeSha,
+  object,
+  readArrayItems,
+  readDataProperty,
+} = require('./verdict');
+
+const CURRENT_VERDICT_STATES = new Set(Object.values(VERDICT_STATES));
+
+function compareText(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function normalizedReasonCodes(verdict) {
+  const reasons = readArrayItems(readDataProperty(verdict, 'reasons').value);
+  if (!reasons) return null;
+  const codes = [];
+  for (const entry of reasons) {
+    const code = readDataProperty(entry, 'code').value;
+    if (!object(entry) || typeof code !== 'string' || !code.trim()) return null;
+    codes.push(code.trim());
+  }
+  return [...new Set(codes)].sort(compareText);
+}
+
+function normalizeCurrentVerdict(verdict, { absent = false } = {}) {
+  if (absent && verdict == null) {
+    return {
+      state: null, repository: null, prNumber: null, headSha: null, baseSha: null, reasons: [],
+    };
+  }
+  const record = object(verdict);
+  const state = readDataProperty(record, 'state').value;
+  const repository = normalizeRepository(readDataProperty(record, 'repository').value);
+  const prNumber = normalizePrNumber(readDataProperty(record, 'prNumber').value);
+  const headSha = normalizeSha(readDataProperty(record, 'headSha').value);
+  const baseSha = normalizeSha(readDataProperty(record, 'baseSha').value);
+  const valid = record && CURRENT_VERDICT_STATES.has(state)
+    && repository && prNumber && headSha && baseSha;
+  const reasons = valid ? normalizedReasonCodes(verdict) : null;
+  if (!valid || reasons === null
+    || (state === VERDICT_STATES.MERGE_READY && reasons.length > 0)
+    || (state !== VERDICT_STATES.MERGE_READY && reasons.length === 0)) {
+    return {
+      state: VERDICT_STATES.INCOMPLETE,
+      repository: null,
+      prNumber: null,
+      headSha: null,
+      baseSha: null,
+      reasons: ['malformed_verdict'],
+    };
+  }
+  return {
+    state,
+    repository,
+    prNumber,
+    headSha,
+    baseSha,
+    reasons,
+  };
+}
+
+function difference(left, right) {
+  const rightSet = new Set(right);
+  return left.filter((value) => !rightSet.has(value));
+}
+
+/** Deterministically describe a transition between exact-current-head verdicts. */
+function diffVerdictEvidence(previous, next) {
+  const before = normalizeCurrentVerdict(previous, { absent: true });
+  const after = normalizeCurrentVerdict(next);
+  const addedReasons = difference(after.reasons, before.reasons);
+  const removedReasons = difference(before.reasons, after.reasons);
+  const headChanged = before.headSha !== after.headSha;
+  const baseChanged = before.baseSha !== after.baseSha;
+  const repositoryChanged = before.repository !== after.repository;
+  const prChanged = before.prNumber !== after.prNumber;
+  const stateChanged = before.state !== after.state;
+  return {
+    changed: headChanged || baseChanged || repositoryChanged || prChanged || stateChanged
+      || addedReasons.length > 0 || removedReasons.length > 0,
+    headChanged,
+    stateChanged,
+    baseChanged,
+    repositoryChanged,
+    prChanged,
+    from: before.state,
+    to: after.state,
+    repository: after.repository,
+    prNumber: after.prNumber,
+    headSha: after.headSha,
+    baseSha: after.baseSha,
+    addedReasons,
+    removedReasons,
+  };
+}
 
 /** Index an array of objects by a key field into a Map. */
 function indexBy(list, field) {
@@ -44,9 +145,9 @@ function diffChecks(prev, next, out) {
     const before = prevByName.get(String(c.name));
     const wasFailed = before?.class === 'failed';
     if (c.class === 'failed' && !wasFailed) {
-      out.push(makeEvent(T.CHECK_FAILED, `${c.name}:${next.headSha}`, { name: c.name }));
+      out.push(makeEvent(T.CHECK_FAILED, `${c.name}:${next.headSha}`, { name: c.displayName || c.name }));
     } else if (c.class === 'green' && wasFailed) {
-      out.push(makeEvent(T.CHECK_RECOVERED, `${c.name}:${next.headSha}`, { name: c.name }));
+      out.push(makeEvent(T.CHECK_RECOVERED, `${c.name}:${next.headSha}`, { name: c.displayName || c.name }));
     }
   }
   if (allGreen(next.checks) && !allGreen(prev.checks)) {
@@ -92,7 +193,9 @@ function diffReviews(prev, next, out) {
       || before.commitOid !== r.commitOid;
     if (changed) {
       out.push(makeEvent(T.REVIEW_SUBMITTED, `${r.author}:${r.commitOid || r.submittedAt}`, {
-        author: r.author, verdict: r.state, commitOid: r.commitOid || null,
+        author: r.displayAuthor || r.author,
+        verdict: r.state,
+        commitOid: r.displayCommitOid || r.commitOid || null,
       }));
     }
   }
@@ -139,7 +242,9 @@ function diffDegraded(prev, next, out) {
   const prevSurfaces = new Set((prev.degraded || []).map((d) => d.surface));
   for (const d of (next.degraded || [])) {
     if (!prevSurfaces.has(d.surface)) {
-      out.push(makeEvent(T.MONITOR_DEGRADED, d.surface, { surface: d.surface, error: d.error || '' }));
+      out.push(makeEvent(T.MONITOR_DEGRADED, d.surface, {
+        surface: d.displaySurface || d.surface, error: d.error || '',
+      }));
     }
   }
 }
@@ -190,6 +295,7 @@ function diffSnapshots(prev, next) {
 
 module.exports = {
   diffSnapshots,
+  diffVerdictEvidence,
   allGreen,
   indexBy,
 };