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

package/lib/merge-rules.js

@@ -21,7 +21,8 @@
  *
  * PR context shape (all fields optional; absence is treated fail-closed by the
  * rules that need them):
- *   - checks:             Array<{ name, conclusion }>  CI check rollup
+ *   - checks:             Array<{ name, appId, status, conclusion } | { name, appId:null, state }>
+ *   - requiredChecks:     Array<{ context, appId }>     protected required set
  *   - requiredChecksKnown: boolean                     is the required set readable?
  *   - unresolvedThreads:  number | Array               open review threads
  *   - behindBase:         number | boolean             commits behind base
@@ -34,7 +35,7 @@
  *   - state:              string (OPEN | MERGED | CLOSED)  read by the command pre-flight, not a rule
  *
  * Built-in rule types (compose as a list, ANDed by default):
- *   checks_green | threads_resolved | not_behind | no_conflicts | not_draft |
+ *   verdict_clean | checks_green | threads_resolved | not_behind | no_conflicts | not_draft |
  *   min_approvals:N | settle_min:N | idle_min:N | last_comment_by:X |
  *   approved_by:[..] | not_commented_by:[..]
  * `checks_green` is bare (ALL checks must be green) or scoped:
@@ -48,14 +49,21 @@
  * documented follow-up and intentionally NOT implemented here.
  *
  * Follow-ups (documented, NOT built here): an opt-in `auto_update` executor
- * (update-branch when behind → wait for CI → re-check → merge); required-checks
- * SCOPING for `checks_green` (read the branch-protection required set instead of
- * requiring every rollup check green); a configurable merge `method`
+ * (update-branch when behind → wait for CI → re-check → merge); a configurable merge `method`
  * (squash | merge | rebase); and post-merge branch deletion.
  */
 
-const SUCCESS_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED', 'PASS', 'PASSED']);
+const SUCCESS_CONCLUSIONS = new Set(['SUCCESS']);
+const SAFE_OPTIONAL_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
 const MS_PER_MIN = 60_000;
+const {
+  normalizePrNumber,
+  normalizeRepository,
+  normalizeSha,
+  object,
+  readArrayItems,
+  readDataProperty,
+} = require('./pr-monitor/verdict');
 
 /** Coerce an epoch-ms number, a Date, or an ISO string to epoch ms (NaN if unparseable). */
 function toMs(value) {
@@ -85,11 +93,15 @@ function toAccountList(arg) {
   return [String(arg).trim().toLowerCase()];
 }
 
-/** A CI check is green if its conclusion is a success-class conclusion. */
+/** A CI check is green only when it is terminal and explicitly successful. */
 function isCheckGreen(check) {
   if (!check || typeof check !== 'object') return false;
-  const conclusion = String(check.conclusion ?? check.state ?? check.status ?? '').toUpperCase();
-  return SUCCESS_CONCLUSIONS.has(conclusion);
+  if (Object.prototype.hasOwnProperty.call(check, 'state')
+    && !Object.prototype.hasOwnProperty.call(check, 'status')) {
+    return String(check.state || '').toUpperCase() === 'SUCCESS';
+  }
+  return String(check.status || '').toUpperCase() === 'COMPLETED'
+    && SUCCESS_CONCLUSIONS.has(String(check.conclusion || '').toUpperCase());
 }
 
 /** The most recent comment by timestamp; ties and unparseable stamps fall back to array order. */
@@ -123,16 +135,49 @@ function checkName(check) {
   return String((check && check.name) || '');
 }
 
+function isCheckObservationWellFormed(check) {
+  if (!check || typeof check !== 'object' || typeof check.name !== 'string' || !check.name.trim()
+    || !Object.prototype.hasOwnProperty.call(check, 'appId')) return false;
+  const hasState = Object.prototype.hasOwnProperty.call(check, 'state');
+  const hasStatus = Object.prototype.hasOwnProperty.call(check, 'status');
+  const hasConclusion = Object.prototype.hasOwnProperty.call(check, 'conclusion');
+  if (hasState) {
+    return !hasStatus && !hasConclusion && check.appId === null
+      && typeof check.state === 'string' && Boolean(check.state.trim());
+  }
+  return hasStatus && hasConclusion && Number.isInteger(check.appId) && check.appId > 0
+    && typeof check.status === 'string' && Boolean(check.status.trim())
+    && (check.conclusion === null || typeof check.conclusion === 'string');
+}
+
+function normalizeRequiredCheck(check) {
+  if (!check || typeof check !== 'object' || typeof check.context !== 'string' || !check.context.trim()
+    || !Object.prototype.hasOwnProperty.call(check, 'appId')
+    || (check.appId !== null && (!Number.isInteger(check.appId) || check.appId <= 0))) return null;
+  return { context: check.context, appId: check.appId };
+}
+
+function matchesRequiredCheck(check, required) {
+  return checkName(check) === required.context
+    && (required.appId === null || check.appId === required.appId);
+}
+
+function isSafeOptionalCheck(check) {
+  if (Object.prototype.hasOwnProperty.call(check, 'state')) return isCheckGreen(check);
+  return String(check.status).toUpperCase() === 'COMPLETED'
+    && SAFE_OPTIONAL_CONCLUSIONS.has(String(check.conclusion || '').toUpperCase());
+}
+
 /**
- * `checks_green` — every CI check must be green per `isCheckGreen`. Optionally scoped:
- *   - bare string / no arg → ALL checks must be green (strict default).
- *   - { ignore: ["A","B"] } → the named checks are EXEMPT; every OTHER check
- *     must be green. `ignore: []` is identical to the bare form.
+ * `checks_green` — protected checks must be strict SUCCESS; optional check runs
+ * may also be terminal NEUTRAL or SKIPPED. Optionally scoped:
+ *   - bare string / no arg → protected checks strict, optional checks safely terminal.
+ *   - { ignore: ["A","B"] } → the named optional checks are EXEMPT;
+ *     `ignore: []` is identical to the bare form.
  *   - { only: ["A"] }       → ONLY the named checks must be green (present AND
- *     green per `isCheckGreen`); all others are ignored.
+ *     green per `isCheckGreen`); all optional others are ignored.
  * `ignore` + `only` together is malformed → fail-closed. Exact name match.
- * (`required_only` — scope to the branch-protection required set — is a
- * documented follow-up, not built here.)
+ * The protected required set is always enforced before optional scoping.
  */
 function checksGreen(ctx, arg) {
   let ignore = [];
@@ -164,14 +209,42 @@ function checksGreen(ctx, arg) {
   if (!Array.isArray(ctx.checks)) {
     return fail('check results are missing from the PR context (fail-closed).');
   }
+  if (!Array.isArray(ctx.requiredChecks)) {
+    return fail('required-check set is missing or malformed (fail-closed).');
+  }
+  if (ctx.checks.some((check) => !isCheckObservationWellFormed(check))) {
+    return fail('check results contain malformed observations (fail-closed).');
+  }
+
+  const required = ctx.requiredChecks.map(normalizeRequiredCheck);
+  if (required.some((check) => !check)) {
+    return fail('required-check set contains malformed entries (fail-closed).');
+  }
+  const requiredApps = new Map();
+  for (const check of required) {
+    if (!requiredApps.has(check.context)) requiredApps.set(check.context, new Set());
+    requiredApps.get(check.context).add(check.appId === null ? '*' : String(check.appId));
+  }
+  if ([...requiredApps.values()].some((apps) => apps.size > 1)) {
+    return fail('required-check set contains conflicting application identities (fail-closed).');
+  }
+
+  const requiredProblems = required.map((requiredCheck) => {
+    const matches = ctx.checks.filter((check) => matchesRequiredCheck(check, requiredCheck));
+    if (matches.length === 0) return `${requiredCheck.context} (missing)`;
+    if (matches.some((check) => !isCheckGreen(check))) return `${requiredCheck.context} (not successful)`;
+    return null;
+  }).filter(Boolean);
+  if (requiredProblems.length > 0) {
+    return fail(`protected required check(s) not green: ${requiredProblems.join(', ')}.`);
+  }
 
   if (only) {
     // Only the named checks matter — each must be PRESENT and green.
-    const byName = new Map(ctx.checks.map((c) => [checkName(c), c]));
     const problems = only.map((name) => {
-      const check = byName.get(name);
-      if (!check) return `${name} (missing)`;
-      if (!isCheckGreen(check)) return `${name} (${check.conclusion || 'not green'})`;
+      const matches = ctx.checks.filter((check) => checkName(check) === name);
+      if (matches.length === 0) return `${name} (missing)`;
+      if (matches.some((check) => !isCheckGreen(check))) return `${name} (not green)`;
       return null;
     }).filter(Boolean);
     if (problems.length > 0) return fail(`required check(s) not green: ${problems.join(', ')}.`);
@@ -180,7 +253,9 @@ function checksGreen(ctx, arg) {
 
   // Default / ignore: every check EXCEPT the exempt ones must be green.
   const exempt = new Set(ignore);
-  const notGreen = ctx.checks.filter((c) => !exempt.has(checkName(c)) && !isCheckGreen(c));
+  const notGreen = ctx.checks.filter((check) => !exempt.has(checkName(check))
+    && !required.some((requiredCheck) => matchesRequiredCheck(check, requiredCheck))
+    && !isSafeOptionalCheck(check));
   if (notGreen.length > 0) {
     const names = notGreen.map((c) => (c && c.name) || '?').join(', ');
     return fail(`${notGreen.length} check(s) not green: ${names}.`);
@@ -223,6 +298,52 @@ function notDraft(ctx) {
   return fail('draft status is unknown (fail-closed).');
 }
 
+/** Require the pure reducer's positive verdict to match the caller's immutable head lease. */
+function verdictClean(ctx) {
+  const verdict = object(readDataProperty(ctx, 'verdict').value);
+  if (!verdict) {
+    return fail('current-head verdict is missing or malformed (fail-closed).');
+  }
+  const repository = normalizeRepository(readDataProperty(ctx, 'repository').value);
+  const expectedRepository = normalizeRepository(readDataProperty(ctx, 'expectedRepository').value);
+  const prNumber = normalizePrNumber(readDataProperty(ctx, 'prNumber').value);
+  const expectedPrNumber = normalizePrNumber(readDataProperty(ctx, 'expectedPrNumber').value);
+  const head = normalizeSha(readDataProperty(ctx, 'headSha').value);
+  const expected = normalizeSha(readDataProperty(ctx, 'expectedHeadSha').value);
+  const base = normalizeSha(readDataProperty(ctx, 'baseSha').value);
+  const expectedBase = normalizeSha(readDataProperty(ctx, 'expectedBaseSha').value);
+  const verdictRepository = normalizeRepository(readDataProperty(verdict, 'repository').value);
+  const verdictPrNumber = normalizePrNumber(readDataProperty(verdict, 'prNumber').value);
+  const verdictHead = normalizeSha(readDataProperty(verdict, 'headSha').value);
+  const verdictBase = normalizeSha(readDataProperty(verdict, 'baseSha').value);
+  const verdictState = readDataProperty(verdict, 'state').value;
+  const verdictReasons = readArrayItems(readDataProperty(verdict, 'reasons').value);
+  if (!head || !expected || !base || !expectedBase || !verdictHead || !verdictBase) {
+    return fail('exact head lease, verdict head, or verdict base is missing or malformed (fail-closed).');
+  }
+  if (!repository || !expectedRepository || !prNumber || !expectedPrNumber
+    || !verdictRepository || !verdictPrNumber) {
+    return fail('repository or PR authority is missing or malformed (fail-closed).');
+  }
+  if (repository !== expectedRepository || verdictRepository !== repository
+    || prNumber !== expectedPrNumber || verdictPrNumber !== prNumber) {
+    return fail('current-head verdict does not match the exact repository and PR authority.');
+  }
+  if (head !== expected || verdictHead !== head) {
+    return fail('current-head verdict does not match the exact caller head lease.');
+  }
+  if (base !== expectedBase || verdictBase !== base) {
+    return fail('current-head verdict does not match the exact caller base lease.');
+  }
+  if (verdictState !== 'MERGE_READY') {
+    return fail(`current-head verdict is ${String(verdictState || 'INCOMPLETE')}, not MERGE_READY.`);
+  }
+  if (!verdictReasons || verdictReasons.length > 0) {
+    return fail('MERGE_READY verdict carries incomplete or contradictory reasons (fail-closed).');
+  }
+  return pass();
+}
+
 function minApprovals(ctx, arg) {
   const need = Number.parseInt(arg, 10);
   if (!Number.isFinite(need)) return fail('min_approvals requires a numeric argument, e.g. "min_approvals:2".');
@@ -306,6 +427,7 @@ function notWrapper(ctx, arg) {
 }
 
 const PREDICATES = {
+  verdict_clean: (ctx) => verdictClean(ctx),
   checks_green: (ctx, arg) => checksGreen(ctx, arg),
   threads_resolved: (ctx) => threadsResolved(ctx),
   not_behind: (ctx) => notBehind(ctx),