@futurelastic/colab-handbook 1.19.0 → 1.19.1-rc.1

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.19.0"
36
+ "version": "1.19.1-rc.1"
37
37
  }
package/tools/colab CHANGED
@@ -11991,6 +11991,7 @@ function readForgeCiVerdict(repoAbs, fc, target, trunk) {
11991
11991
  if (!run) return unread(`${engine} commit-status read failed for ${target}@${shortSha(sha)} — cannot confirm CI`);
11992
11992
  const at = `${via}@${shortSha(run.sha || sha)} (${engine} commit status)`;
11993
11993
  let verdict = classifyCiRun(repoAbs, run, at);
11994
+ if (!verdict.ok) verdict = { ...verdict, detail: verdict.detail + notGreenNote(run) }; // #682: name the contexts
11994
11995
  if (run.status === 'none' && target === trunk) {
11995
11996
  const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
11996
11997
  if (fresh.fresh) {
@@ -12066,6 +12067,12 @@ function classifyCiRun(repoAbs, run, at) {
12066
12067
  return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) + readViaNote(run) };
12067
12068
  }
12068
12069
 
12070
+ /** #682: a forge verdict's not-green contexts, named — '' on GitHub, or when every context is green. */
12071
+ function notGreenNote(run) {
12072
+ const ng = run && Array.isArray(run.notGreen) ? run.notGreen : [];
12073
+ return ng.length ? ` — not green: ${ng.map((x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`).join(', ')}` : '';
12074
+ }
12075
+
12069
12076
  /**
12070
12077
  * #651: the runs were read from the unfiltered `actions/runs` listing because the forge's filtered
12071
12078
  * queries (`head_sha=` / `branch=`) answered nothing. The verdict is judged as usual. The note says
@@ -12278,9 +12285,16 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
12278
12285
  if (headSha && fc) run = fc.ciVerdict(headSha, { branch });
12279
12286
  else if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
12280
12287
  // #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
12281
- return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha };
12288
+ // #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
12289
+ // row — the class code-ship B1a reads through `colab ci-wait` on GitHub. null on GitHub, and where
12290
+ // the head has no run to judge (the stale-base row speaks for those).
12291
+ const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind }) : null;
12292
+ return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha, headCi };
12282
12293
  }
12283
12294
 
12295
+ /** #682: the forge branch-head CI row's name — one spelling for the JSON and the prose table. */
12296
+ const BRANCH_HEAD_CI_ROW = 'branch CI green at its head (#682)';
12297
+
12284
12298
  /**
12285
12299
  * #294: WHICH paths are dirty in the trunk checkout, and — where the signal is strong enough — a
12286
12300
  * likely owner. Never a precondition: it enriches the ALREADY-COMPUTED "trunk checkout ready"
@@ -13102,6 +13116,8 @@ function cmdShipDryJson(opts) {
13102
13116
  } else {
13103
13117
  checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
13104
13118
  class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
13119
+ const hc = staleJson.headCi; // #682: forge only — a red head needs a person, a running one clears
13120
+ 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 });
13105
13121
  }
13106
13122
  // #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
13107
13123
  // its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
@@ -14353,7 +14369,9 @@ function cmdShip(argv) {
14353
14369
  docsRowOk = row.ok && docsCi.scan.ok;
14354
14370
  } else {
14355
14371
  checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
14372
+ if (staleResult.headCi) checks.push([staleResult.headCi.ok ? '✓' : '✗', BRANCH_HEAD_CI_ROW, staleResult.headCi.detail]); // #682
14356
14373
  }
14374
+ const headCiOk = docsCi.applies || !staleResult.headCi || staleResult.headCi.ok;
14357
14375
  // #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
14358
14376
  // heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
14359
14377
  // heavy lane at all, fails the table.
@@ -14385,7 +14403,7 @@ function cmdShip(argv) {
14385
14403
  // issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
14386
14404
  // have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
14387
14405
  // checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
14388
- const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
14406
+ const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && headCiOk && coreOk && recOk && heavyOk;
14389
14407
 
14390
14408
  // ---- report the table ----
14391
14409
  print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
@@ -16556,9 +16574,13 @@ Exit codes — branch on these, never on the text:
16556
16574
  5 UNKNOWN a read failed or returned a state it cannot classify
16557
16575
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
16558
16576
 
16577
+ On a remote the machine config's \`forges\` names as Forgejo (#678, #682), --sha reads the commit's
16578
+ combined status instead — no gh call, no conditional request; a status has no run id, so <run-id>
16579
+ is a usage error there. RED and --json name the contexts that are not green (\`notGreen\`).
16580
+
16559
16581
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
16560
16582
  --json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
16561
- detail, status, conclusion, url }`;
16583
+ detail, status, conclusion, url, notGreen? }`;
16562
16584
 
16563
16585
  function cmdCiWait(argv) {
16564
16586
  const opts = parseArgs(argv, {
@@ -16587,9 +16609,16 @@ function cmdCiWait(argv) {
16587
16609
  }
16588
16610
  opts.sha = full;
16589
16611
  }
16590
- if (!git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
16612
+ // #682: a remote the engine map names as a forge (#678) is read from its commit statuses, never
16613
+ // through gh — which would answer `no known GitHub host` (exit 5) for every wait there.
16614
+ const fc = forgeCi(repoAbs);
16615
+ if (fc && runId) {
16616
+ warn(`the remote is a ${fc.kind} forge — a commit status has no run id to wait on; pass --sha <sha> [--branch <b>]`);
16617
+ return ciWait.EXIT.USAGE;
16618
+ }
16619
+ if (!fc && !git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
16591
16620
 
16592
- const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`;
16621
+ const target = (runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`) + (fc ? ` (${fc.kind} commit status)` : '');
16593
16622
  const apiPath = runId
16594
16623
  ? `repos/{owner}/{repo}/actions/runs/${runId}`
16595
16624
  : `repos/{owner}/{repo}/actions/runs?head_sha=${encodeURIComponent(opts.sha)}${opts.branch ? `&branch=${encodeURIComponent(opts.branch)}` : ''}&per_page=100`;
@@ -16619,7 +16648,7 @@ function cmdCiWait(argv) {
16619
16648
  }
16620
16649
 
16621
16650
  const verifyPolicy = verifyingPolicy(repoAbs);
16622
- const poll = (etag) => {
16651
+ const poll = fc ? () => ciWait.forgePoll(fc.ciVerdict(opts.sha, { branch: opts.branch || null }), fc.kind) : (etag) => {
16623
16652
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
16624
16653
  if (r.kind !== 'ok') return r;
16625
16654
  let summary;
@@ -16665,11 +16694,12 @@ function cmdCiWait(argv) {
16665
16694
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
16666
16695
  ...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
16667
16696
  ...(s.readVia ? { readVia: s.readVia } : {}), // #654: the verdict names how it was read
16697
+ ...(Array.isArray(s.notGreen) && s.notGreen.length ? { notGreen: s.notGreen } : {}), // #682: forge contexts not green
16668
16698
  };
16669
16699
  if (opts.json) print(JSON.stringify(out, null, 2));
16670
16700
  else {
16671
16701
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
16672
- `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}`);
16702
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}${notGreenNote(s)}`);
16673
16703
  }
16674
16704
  return code;
16675
16705
  }
@@ -122,9 +122,22 @@ function create(repoAbs, eng) {
122
122
  if (page === MAX_PAGES) return null; // more statuses than we read: never a partial verdict
123
123
  }
124
124
  const rows = rowsFromPages(full, pages);
125
- return rows === null ? null : require('./git').summarizeRunsForCommit(rows, full);
125
+ if (rows === null) return null;
126
+ const summary = require('./git').summarizeRunsForCommit(rows, full);
127
+ // #682: additive — the contexts that keep this sha from green, so a refusal can name them.
128
+ const ng = notGreen(rows);
129
+ return ng.length ? { ...summary, notGreen: ng } : summary;
126
130
  },
127
131
  };
128
132
  }
129
133
 
130
- module.exports = { create, withFetcher, statusRow, rowsFromPages, PAGE_LIMIT };
134
+ /**
135
+ * #682: every context that is not `success` — still pending, or finished red — in the compact
136
+ * `{name, status, conclusion}` shape a verdict detail names them by. Pure; [] when all are green.
137
+ */
138
+ function notGreen(rows) {
139
+ return (rows || []).filter((x) => !(x.status === 'completed' && x.conclusion === 'success'))
140
+ .map((x) => ({ name: x.workflowName || 'unnamed', status: x.status, conclusion: x.conclusion || null }));
141
+ }
142
+
143
+ module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, PAGE_LIMIT };
@@ -118,6 +118,17 @@ function runState(s) {
118
118
  return 'unknown';
119
119
  }
120
120
 
121
+ /**
122
+ * #682: one poll on a forge the engine map names, from its `ciVerdict` summary (tools/lib/ci-forgejo.js)
123
+ * — the waitLoop result shape, with no ETag (a forge read is never conditional, so no 304 can pin a
124
+ * stale state). A null summary is a failed read: `error`, which ends the wait UNKNOWN, never "keep
125
+ * waiting". Pure.
126
+ */
127
+ function forgePoll(summary, engine = 'forge') {
128
+ if (!summary) return { kind: 'error', status: null, detail: `${engine} commit-status read failed` };
129
+ return { kind: 'ok', status: 200, etag: null, summary, state: runState(summary) };
130
+ }
131
+
121
132
  /**
122
133
  * #505: how many 304s in a row may stand for the state before the next poll re-reads without
123
134
  * `If-None-Match`. Measured: the runs-list read kept answering 304 for ten minutes while every run
@@ -223,6 +234,6 @@ function sleepSync(ms) {
223
234
 
224
235
  module.exports = {
225
236
  EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC, DEFAULT_MAX_NOT_MODIFIED,
226
- delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
237
+ delayFor, parseHttp, classifyResponse, restRow, runState, forgePoll, waitLoop, fmtDuration, parseDuration,
227
238
  acquireLock, sleepSync,
228
239
  };
@@ -77,4 +77,50 @@ function staleBaseVerdict(a) {
77
77
  'push, wait on the new run (15-minute bound), then re-run ship' };
78
78
  }
79
79
 
80
- module.exports = { staleBaseVerdict };
80
+ /**
81
+ * #682: is the branch head's OWN CI green? Read on a forge the engine map names (#678), where no
82
+ * `colab ci-wait` used to exist for code-ship B1a to classify the branch with — so a red or running
83
+ * branch head passed `colab ship --dry` as READY on the stale-base row alone (that row asks only
84
+ * whether the run saw the base). The forge's summary is the same `ciVerdict` the trunk row reads.
85
+ *
86
+ * completed / success -> green, passes
87
+ * completed / other -> red, human-gated: a branch lands only on its own green (C7.contract.03);
88
+ * whether it is red:infra (one re-run) or red:finding (send back) is B1a's
89
+ * anything unfinished -> pending, self-clearing: wait (`colab ci-wait`), then ship again
90
+ *
91
+ * Returns null where this row says nothing: no head on the remote, an unread run (the stale-base
92
+ * row already refuses that as `unread`), or no status at all (the `none` row of Branch CI governs).
93
+ * `run.notGreen` (tools/lib/ci-forgejo.js) names the contexts that keep the sha from green.
94
+ *
95
+ * @param {object} a
96
+ * @param {string|null} a.headSha - the branch head on the remote
97
+ * @param {object|null} a.run - the forge's ciVerdict summary at headSha
98
+ * @param {string} a.branch
99
+ * @param {string} [a.engine] - for the detail line, e.g. 'forgejo'
100
+ * @returns {null|{ok:boolean, verdict:'green'|'red'|'pending', selfClearing:boolean, detail:string}}
101
+ */
102
+ function branchHeadCiVerdict(a) {
103
+ const run = a && a.run;
104
+ if (!a || !a.headSha || !run || run.status === 'none') return null;
105
+ const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (${a.engine || 'forge'} commit status)`;
106
+ const ng = Array.isArray(run.notGreen) ? run.notGreen : [];
107
+ const name = (x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`;
108
+ if (run.status === 'completed' && run.conclusion === 'success') {
109
+ const n = run.runCount == null ? 1 : run.runCount;
110
+ return { ok: true, verdict: 'green', selfClearing: false, detail: `${n} context${n === 1 ? '' : 's'} at ${at}: ${n === 1 ? 'success' : 'all success'}` };
111
+ }
112
+ if (run.status === 'completed') {
113
+ const red = ng.filter((x) => x.status === 'completed');
114
+ const still = ng.filter((x) => x.status !== 'completed');
115
+ return { ok: false, verdict: 'red', selfClearing: false,
116
+ detail: `${at} is red — failing: ${red.length ? red.map(name).join(', ') : `conclusion=${run.conclusion || 'none'}`}` +
117
+ `${still.length ? `; still running: ${still.map(name).join(', ')}` : ''}. A branch lands only on its own green (C7.contract.03): ` +
118
+ 'red:infra → re-run once; red:finding → send it back (code-ship B1a)' };
119
+ }
120
+ const still = ng.filter((x) => x.status !== 'completed');
121
+ return { ok: false, verdict: 'pending', selfClearing: true,
122
+ detail: `${at} has not finished — still running: ${still.length ? still.map(name).join(', ') : `status=${run.status}`}. ` +
123
+ `Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`, then run ship again` };
124
+ }
125
+
126
+ module.exports = { staleBaseVerdict, branchHeadCiVerdict };