@futurelastic/colab-handbook 1.20.1-rc.4 → 1.20.1-rc.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.20.1-rc.4"
36
+ "version": "1.20.1-rc.5"
37
37
  }
package/tools/colab CHANGED
@@ -12409,17 +12409,27 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
12409
12409
  // the trunk-CI row reads (commit statuses on Forgejo) — never keyed on the gh flag, so a stale or red
12410
12410
  // branch head cannot pass here as `unread` while the CI row passes on the forge's statuses.
12411
12411
  const fc = forgeCi(repoAbs);
12412
+ let verifiedRun = null;
12412
12413
  if (headSha && fc) run = fc.ciVerdict(headSha, { branch });
12413
- else if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
12414
+ else if (headSha && gh) {
12415
+ // #691: one read, two summaries. `run` stays exactly what the stale-base and docs-only rows have
12416
+ // always read; `verifiedRun` applies the verifying-runs policy (#503) the trunk row uses, so the
12417
+ // head row below never refuses on a run that policy sets aside (a release lane, an ignored workflow).
12418
+ const rows = git.ghRunsForCommit(repoAbs, branch, headSha);
12419
+ run = git.summarizeRunsForCommit(rows, headSha);
12420
+ verifiedRun = git.summarizeRunsForCommit(rows, headSha, { verifying: verifyingPolicy(repoAbs), finishedRed: true });
12421
+ }
12414
12422
  // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
12415
12423
  // #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
12416
- // row — the class code-ship B1a reads through `colab ci-wait` on GitHub. null on GitHub, and where
12417
- // the head has no run to judge (the stale-base row speaks for those).
12418
- const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind }) : null;
12424
+ // row. #691: on GitHub it is emitted only for a head whose run FINISHED red — waiting on a running
12425
+ // one stays code-ship B1a's `colab ci-wait` — and is null otherwise, as it is wherever the head has
12426
+ // no run to judge (the stale-base row speaks for those).
12427
+ const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind })
12428
+ : (gh ? staleBase.githubBranchHeadRedVerdict({ headSha, run: verifiedRun, branch }) : null);
12419
12429
  return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha, headCi };
12420
12430
  }
12421
12431
 
12422
- /** #682: the forge branch-head CI row's name — one spelling for the JSON and the prose table. */
12432
+ /** #682: the branch-head CI row's name (forge; on GitHub a finished-red head only, #691) — one spelling for the JSON and the prose table. */
12423
12433
  const BRANCH_HEAD_CI_ROW = 'branch CI green at its head (#682)';
12424
12434
 
12425
12435
  /**
@@ -13243,7 +13253,7 @@ function cmdShipDryJson(opts) {
13243
13253
  } else {
13244
13254
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
13245
13255
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
13246
- const hc = staleJson.headCi; // #682: forge only — a red head needs a person, a running one clears
13256
+ const hc = staleJson.headCi; // #682 forge, #691 GitHub (red only) — a red head needs a person, a running one clears
13247
13257
  if (hc) checks.push({ name: BRANCH_HEAD_CI_ROW, ok: hc.ok, class: hc.ok ? null : (hc.selfClearing ? SELF_CLEARING : HUMAN_GATED), verdict: hc.verdict, detail: hc.detail });
13248
13258
  }
13249
13259
  // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
package/tools/lib/git.js CHANGED
@@ -1280,6 +1280,12 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1280
1280
  ...(allSkipped ? { allSkipped: true } : {}),
1281
1281
  ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1282
1282
  ...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
1283
+ // #691: opt-in (`opts.finishedRed`), so no reader that never asked sees a new field — every
1284
+ // JUDGED run that finished red: completed, and not success, cancelled or skipped (neither of
1285
+ // those two executed anything). The summary's single `conclusion` names only the first not-green
1286
+ // row it meets, which can be a `skipped` one beside a real failure; a caller asking "did any run
1287
+ // finish red here" reads this list instead. Absent when none did.
1288
+ ...(opts && opts.finishedRed && judged.some(isFinishedRed) ? { finishedRed: excludedRunSummary(judged.filter(isFinishedRed)) } : {}),
1283
1289
  // #651: the rows came from the unfiltered listing because the forge's filter index was empty.
1284
1290
  ...(allForSha.some((x) => x && x.readVia === 'unfiltered-listing') ? { readVia: 'unfiltered-listing' } : {}),
1285
1291
  };
@@ -1287,6 +1293,11 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1287
1293
  return { ...r, ...extra };
1288
1294
  }
1289
1295
 
1296
+ /** #691: a run that ran and failed — completed, and not success, cancelled or skipped. */
1297
+ function isFinishedRed(x) {
1298
+ return !!x && x.status === 'completed' && x.conclusion !== 'success' && x.conclusion !== 'cancelled' && x.conclusion !== 'skipped';
1299
+ }
1300
+
1290
1301
  /** Sort key for "which run of one workflow is newer": createdAt, then databaseId; null = unknown. */
1291
1302
  function runRecency(x) {
1292
1303
  const t = x && x.createdAt ? Date.parse(x.createdAt) : NaN;
@@ -123,4 +123,43 @@ function branchHeadCiVerdict(a) {
123
123
  `Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`, then run ship again` };
124
124
  }
125
125
 
126
- module.exports = { staleBaseVerdict, branchHeadCiVerdict };
126
+ /**
127
+ * #691: the GitHub half of #682's row. On GitHub the branch head's class used to be left wholly to
128
+ * code-ship B1a (`colab ci-wait`), so `colab ship --dry --json` read READY on a head whose run had
129
+ * FINISHED red — measured on a required secret-scan job that failed before scanning anything. The
130
+ * row now refuses that one state, human-gated, in dry and real ship alike; everything else stays as
131
+ * it was on GitHub (null — no row):
132
+ *
133
+ * a run at the head finished red -> red, human-gated (red:infra or red:finding is B1a's call)
134
+ * green / in flight / no run / unread -> null: B1a's ci-wait still owns the wait, the stale-base
135
+ * row still speaks for `none` and an unread run
136
+ *
137
+ * "Finished red" is #606's docs-only rule (`docsOnlyBranchRow`): completed, and not success,
138
+ * cancelled or skipped — so a code branch is never held to a weaker rule than a docs-only one.
139
+ * `run` is the head's summary read under the verifying-runs policy (#503), the same rule the trunk
140
+ * row uses, so a run that policy sets aside (a release lane, a `ship-ignore-workflows` entry) never
141
+ * refuses here. `run.finishedRed` (tools/lib/git.js) lists every judged red run; without it the
142
+ * summary's own status/conclusion decides.
143
+ *
144
+ * @param {object} a
145
+ * @param {string|null} a.headSha - the branch head on the remote
146
+ * @param {object|null} a.run - summarizeRunsForCommit's verdict at headSha, verifying policy applied
147
+ * @param {string} a.branch
148
+ * @returns {null|{ok:false, verdict:'red', selfClearing:false, detail:string}}
149
+ */
150
+ function githubBranchHeadRedVerdict(a) {
151
+ const run = a && a.run;
152
+ if (!a || !a.headSha || !run || run.status === 'none') return null;
153
+ const listed = Array.isArray(run.finishedRed) ? run.finishedRed : [];
154
+ const summaryRed = run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
155
+ if (!listed.length && !summaryRed) return null;
156
+ const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (GitHub Actions)`;
157
+ const failing = listed.length
158
+ ? listed.map((x) => `${x.workflowName || 'run'} (${x.conclusion || 'none'})`).join(', ')
159
+ : `conclusion=${run.conclusion || 'none'}`;
160
+ return { ok: false, verdict: 'red', selfClearing: false,
161
+ detail: `${at} finished red — failing: ${failing}. A branch lands only on its own green (C7.contract.03): ` +
162
+ 'red:infra → re-run once; red:finding → send it back (code-ship B1a)' };
163
+ }
164
+
165
+ module.exports = { staleBaseVerdict, branchHeadCiVerdict, githubBranchHeadRedVerdict };