@futurelastic/colab-handbook 1.13.0-rc.31 → 1.13.0-rc.32

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.13.0-rc.31"
36
+ "version": "1.13.0-rc.32"
37
37
  }
package/tools/colab CHANGED
@@ -10960,6 +10960,37 @@ function noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch) {
10960
10960
  detail: `none — ${at} has no repo-owned workflow (#482), so the branch's own run decides, and ${ownAt} ${why}${excludedRunsNote(r.run)}` };
10961
10961
  }
10962
10962
 
10963
+ /**
10964
+ * The verifying-runs policy every CI read uses (#503), plus the lost-push rescue's resolver (#567):
10965
+ * the names of the workflows whose definition AT THAT SHA is triggered by a branch push or a pull
10966
+ * request. Lazy — called only when a `workflow_dispatch` run has no push sibling — and fail-closed:
10967
+ * a sha that is not local, or a tree that cannot be read, yields null and the run stays set aside.
10968
+ */
10969
+ function verifyingPolicy(repoAbs) {
10970
+ return { ...verifyRuns.parsePolicy(projectDoc(repoAbs)), dispatchVerifies: (sha) => pushVerifiedWorkflowsAt(repoAbs, sha) };
10971
+ }
10972
+
10973
+ function pushVerifiedWorkflowsAt(repoAbs, sha) {
10974
+ if (!sha) return null;
10975
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) {
10976
+ // Not local yet (another machine landed it): one fetch of that commit, then fail closed.
10977
+ git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
10978
+ if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
10979
+ }
10980
+ const ls = git.git(['ls-tree', '--name-only', `${sha}:.github/workflows`], repoAbs);
10981
+ if (!ls.ok) return null;
10982
+ const names = [];
10983
+ for (const f of ls.stdout.split('\n').map((x) => x.trim()).filter((x) => /\.ya?ml$/.test(x))) {
10984
+ const rel = `.github/workflows/${f}`;
10985
+ const show = git.git(['show', `${sha}:${rel}`], repoAbs);
10986
+ if (!show.ok) continue;
10987
+ const t = verifyRuns.workflowTriggers(show.stdout);
10988
+ // GitHub names a workflow with no `name:` by its file path.
10989
+ if (t && t.verifiesBranches) names.push(t.name || rel);
10990
+ }
10991
+ return names;
10992
+ }
10993
+
10963
10994
  /** Number of workflow files in `.github/workflows` at `sha`, or null when the tree cannot be read. */
10964
10995
  function trunkWorkflowFiles(repoAbs, sha) {
10965
10996
  if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) return null;
@@ -10990,7 +11021,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10990
11021
  if (!gh) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI` } };
10991
11022
  // #503: only runs that VERIFY the code count — a post-CI release/deploy run at the same sha is set
10992
11023
  // aside and named, never a red and never a reason to wait (tools/lib/verify-runs.js).
10993
- const readOpts = { verifying: verifyRuns.parsePolicy(projectDoc(repoAbs)) };
11024
+ const readOpts = { verifying: verifyingPolicy(repoAbs) };
10994
11025
  let run = git.ghRunForSha(repoAbs, target, undefined, undefined, readOpts);
10995
11026
  let via = target;
10996
11027
  if (run && run.status === 'none' && target !== trunk) {
@@ -11091,7 +11122,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
11091
11122
  */
11092
11123
  function classifyCiRun(repoAbs, run, at) {
11093
11124
  const v = classifyCiRunRaw(repoAbs, run, at);
11094
- return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) };
11125
+ return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) };
11095
11126
  }
11096
11127
 
11097
11128
  /**
@@ -14594,7 +14625,8 @@ function cmdTrunkCi(argv) {
14594
14625
  if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
14595
14626
  out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail,
14596
14627
  ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}),
14597
- ...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {}) };
14628
+ ...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {}),
14629
+ ...(r.run && Array.isArray(r.run.dispatchCounted) && r.run.dispatchCounted.length ? { dispatchCounted: r.run.dispatchCounted } : {}) };
14598
14630
  if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
14599
14631
  }
14600
14632
  if (opts.json) {
@@ -14849,7 +14881,7 @@ function cmdCiWait(argv) {
14849
14881
  if (!opts.json) for (const n of cp.notes) process.stderr.write(`ci-wait: ${n}\n`);
14850
14882
  }
14851
14883
 
14852
- const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
14884
+ const verifyPolicy = verifyingPolicy(repoAbs);
14853
14885
  const poll = (etag) => {
14854
14886
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
14855
14887
  if (r.kind !== 'ok') return r;
@@ -14885,11 +14917,12 @@ function cmdCiWait(argv) {
14885
14917
  waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
14886
14918
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
14887
14919
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
14920
+ ...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
14888
14921
  };
14889
14922
  if (opts.json) print(JSON.stringify(out, null, 2));
14890
14923
  else {
14891
14924
  print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
14892
- `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}`);
14925
+ `${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}`);
14893
14926
  }
14894
14927
  return code;
14895
14928
  }
package/tools/lib/git.js CHANGED
@@ -1144,7 +1144,8 @@ function excludedRunSummary(rows) {
1144
1144
  * #503: `opts.verifying` (a tools/lib/verify-runs.js policy, `{gate, ignore}`) narrows the owned rows
1145
1145
  * to the runs that VERIFY the code — push / pull-request triggered, or the declared set — BEFORE the
1146
1146
  * per-workflow reduction; the rest (a `workflow_run` release, a scheduled finalize, a deploy) ride
1147
- * along as `setAside`, each with its reason. Opt-in: without `opts.verifying` nothing changes, so
1147
+ * along as `setAside`, each with its reason. #567: a `workflow_dispatch` run the policy's
1148
+ * `dispatchVerifies` resolver rescues (lost push event) is counted and named in `dispatchCounted`. Opt-in: without `opts.verifying` nothing changes, so
1148
1149
  * readers that never asked (release finalize, the base-ci advisory, ci-grant) read exactly as before.
1149
1150
  */
1150
1151
  function summarizeRunsForCommit(allForSha, sha, opts = {}) {
@@ -1152,16 +1153,19 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
1152
1153
  const dropped = allForSha.filter((x) => !isRepoOwnedRun(x));
1153
1154
  let owned = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
1154
1155
  let setAside = [];
1156
+ let dispatchCounted = [];
1155
1157
  if (opts && opts.verifying) {
1156
1158
  const split = require('./verify-runs').splitVerifying(owned, opts.verifying);
1157
1159
  owned = split.counted;
1158
1160
  setAside = split.setAside;
1161
+ dispatchCounted = split.dispatchCounted || [];
1159
1162
  }
1160
1163
  const { heads, superseded } = newestRunPerWorkflow(owned);
1161
1164
  const extra = {
1162
1165
  ...(dropped.length ? { excluded: excludedRunSummary(dropped) } : {}),
1163
1166
  ...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
1164
1167
  ...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
1168
+ ...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
1165
1169
  };
1166
1170
  const r = summarizeRepoOwnedRuns(heads, sha);
1167
1171
  return { ...r, ...extra };
@@ -26,6 +26,19 @@
26
26
  * ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered (a deploy
27
27
  * workflow that fires on a push to trunk). Wins over the gate
28
28
  * list for a name in both.
29
+ *
30
+ * A LOST PUSH (#567). The forge can drop a trunk commit's `push` event (measured: a ship's push landed
31
+ * during a window of HTTP 500s and CI never started for that sha). Re-running is impossible (there is
32
+ * no run), and dispatching the same CI workflow at that sha produced a `workflow_dispatch` run the
33
+ * rule above set aside — so trunk stayed unmeasured until a human wrote an empty commit. Now: a
34
+ * `workflow_dispatch` run COUNTS when (a) its workflow's own definition at that sha is triggered by a
35
+ * branch push or a pull request — i.e. it is the workflow that verifies the code, not a release lane
36
+ * that merely accepts a manual trigger — and (b) no push / pull-request run of that same workflow is
37
+ * at the sha. (b) keeps the rescue narrow: where the push run exists, it is the verdict, as before.
38
+ * The caller supplies (a) as `policy.dispatchVerifies(sha) → string[] | null` (the workflow names, read
39
+ * from the tree at that sha — this module does no I/O); null / absent / unreadable → nothing is
40
+ * rescued, the run stays set aside (fail closed). With `ship-gate-workflows` declared this rescue is
41
+ * moot: the gate list already counts its workflows whatever their trigger.
29
42
  */
30
43
 
31
44
  const VERIFYING_EVENTS = Object.freeze(['push', 'pull_request', 'pull_request_target', 'merge_group']);
@@ -77,17 +90,117 @@ function setAsideReason(row, policy) {
77
90
  return VERIFYING_EVENTS.includes(ev) ? null : `event: ${ev}`;
78
91
  }
79
92
 
80
- /** Split rows into `{ counted, setAside }`; each set-aside row carries `setAsideWhy`. Null in → null out. */
93
+ /**
94
+ * Split rows into `{ counted, setAside, dispatchCounted }`; each set-aside row carries `setAsideWhy`,
95
+ * and `dispatchCounted` lists the `workflow_dispatch` rows the lost-push rescue (#567) moved into
96
+ * `counted`. Null in → null out.
97
+ */
81
98
  function splitVerifying(rows, policy) {
82
99
  if (!Array.isArray(rows)) return null;
83
100
  const counted = [];
84
- const setAside = [];
101
+ let setAside = [];
85
102
  for (const r of rows) {
86
103
  const why = setAsideReason(r, policy);
87
104
  if (why) setAside.push({ ...r, setAsideWhy: why });
88
105
  else counted.push(r);
89
106
  }
90
- return { counted, setAside };
107
+ const dispatchCounted = [];
108
+ const resolver = policy && typeof policy.dispatchVerifies === 'function' ? policy.dispatchVerifies : null;
109
+ const candidates = setAside.filter((x) => x.setAsideWhy === 'event: workflow_dispatch' && x.workflowName
110
+ && !counted.some((c) => c.workflowName === x.workflowName));
111
+ if (resolver && candidates.length) {
112
+ const byShas = new Map();
113
+ const namesAt = (sha) => {
114
+ if (!byShas.has(sha)) {
115
+ let v = null;
116
+ try { v = resolver(sha); } catch (_) { v = null; }
117
+ byShas.set(sha, Array.isArray(v) ? v : null);
118
+ }
119
+ return byShas.get(sha);
120
+ };
121
+ const keep = [];
122
+ for (const x of setAside) {
123
+ const names = candidates.includes(x) && x.headSha ? namesAt(x.headSha) : null;
124
+ if (names && names.includes(x.workflowName)) {
125
+ const { setAsideWhy, ...row } = x;
126
+ counted.push(row);
127
+ dispatchCounted.push(row);
128
+ } else keep.push(x);
129
+ }
130
+ setAside = keep;
131
+ }
132
+ return { counted, setAside, dispatchCounted };
133
+ }
134
+
135
+ /** Strip a trailing ` # comment` and matching quotes from a one-line YAML scalar. */
136
+ function yamlScalar(raw) {
137
+ let v = String(raw).replace(/\s+#.*$/, '').trim();
138
+ if (v.length > 1 && ((v[0] === '"' && v.endsWith('"')) || (v[0] === "'" && v.endsWith("'")))) v = v.slice(1, -1);
139
+ return v;
140
+ }
141
+
142
+ const BRANCH_TRIGGERS = Object.freeze(['push', 'pull_request', 'pull_request_target', 'merge_group']);
143
+
144
+ /**
145
+ * What one workflow file says about itself (#567): `{ name, verifiesBranches }`, or null when the text
146
+ * has no top-level `on:` at all. `name` is the top-level `name:` (null when absent — GitHub then names
147
+ * the workflow by its path, which the caller knows). `verifiesBranches` is true when the triggers
148
+ * include a pull request, or a push that is not tags-only (`push: { tags: [...] }` with no
149
+ * `branches`/`branches-ignore` is a release lane, never a code verifier). A deliberately small reader
150
+ * of the three `on:` shapes (scalar, flow list, block map / block list) — not a YAML parser.
151
+ */
152
+ function workflowTriggers(text) {
153
+ const lines = String(text || '').split(/\r?\n/);
154
+ let name = null;
155
+ let onIdx = -1;
156
+ let onInline = null;
157
+ for (let i = 0; i < lines.length; i++) {
158
+ const l = lines[i];
159
+ let m = /^name:\s*(.*)$/.exec(l);
160
+ if (m && name === null) { name = yamlScalar(m[1]) || null; continue; }
161
+ m = /^(?:on|"on"|'on'|true):\s*(.*)$/.exec(l);
162
+ if (m && onIdx < 0) { onIdx = i; onInline = yamlScalar(m[1]); }
163
+ }
164
+ if (onIdx < 0) return null;
165
+ const events = new Map(); // event -> its child lines (block map form only)
166
+ if (onInline) {
167
+ const list = onInline.startsWith('[') ? onInline.replace(/^\[|\]$/g, '').split(',') : [onInline];
168
+ for (const e of list) { const v = yamlScalar(e); if (v) events.set(v, []); }
169
+ } else {
170
+ let evIndent = null;
171
+ let cur = null;
172
+ for (let i = onIdx + 1; i < lines.length; i++) {
173
+ const l = lines[i];
174
+ if (!l.trim() || /^\s*#/.test(l)) continue;
175
+ const indent = l.length - l.trimStart().length;
176
+ if (indent === 0) break;
177
+ if (evIndent === null) evIndent = indent;
178
+ if (indent < evIndent) break;
179
+ if (indent === evIndent) {
180
+ const t = l.trim();
181
+ const m = /^-\s*(.+)$/.exec(t) || /^([A-Za-z_]+)\s*:/.exec(t);
182
+ cur = m ? yamlScalar(m[1].replace(/:.*$/, '')) : null;
183
+ if (cur) events.set(cur, []);
184
+ } else if (cur) events.get(cur).push(l.trim());
185
+ }
186
+ }
187
+ let verifies = false;
188
+ for (const [ev, body] of events) {
189
+ if (!BRANCH_TRIGGERS.includes(ev)) continue;
190
+ if (ev !== 'push') { verifies = true; break; }
191
+ const keys = body.map((t) => (/^([A-Za-z_-]+)\s*:/.exec(t) || [])[1]).filter(Boolean);
192
+ const tagsOnly = (keys.includes('tags') || keys.includes('tags-ignore')) && !keys.includes('branches') && !keys.includes('branches-ignore');
193
+ if (!tagsOnly) { verifies = true; break; }
194
+ }
195
+ return { name, verifiesBranches: verifies };
196
+ }
197
+
198
+ /** The compact verdict-detail note for rows the lost-push rescue counted — '' when none. */
199
+ function dispatchCountedNote(rows) {
200
+ const list = Array.isArray(rows) ? rows : [];
201
+ if (!list.length) return '';
202
+ const names = list.map((x) => `${x.workflowName || 'unnamed'}${x.databaseId ? ` (run ${x.databaseId})` : ''}`);
203
+ return ` — counted ${list.length} workflow_dispatch run${list.length === 1 ? '' : 's'} of a push-verifying workflow with no push run at this sha (lost push event, #567): ${names.join(', ')}`;
91
204
  }
92
205
 
93
206
  /**
@@ -101,4 +214,4 @@ function setAsideNote(rows) {
101
214
  return ` — set aside ${list.length} run${list.length === 1 ? '' : 's'} that do${list.length === 1 ? 'es' : ''} not verify the code (post-CI release/deploy lane, #503): ${names.join(', ')}`;
102
215
  }
103
216
 
104
- module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote };
217
+ module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote, workflowTriggers, dispatchCountedNote };