@futurelastic/colab-handbook 1.20.3 → 1.20.4-rc.10
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 +1 -1
- package/templates/README.md +13 -6
- package/templates/ci-laravel-heavy.yml +153 -6
- package/templates/ci-laravel.yml +66 -17
- package/templates/ci-node-heavy.yml +157 -6
- package/templates/ci-node.yml +66 -18
- package/templates/ci-python-heavy.yml +157 -6
- package/templates/ci-python.yml +66 -18
- package/templates/instruction-files.yml +3 -2
- package/templates/publish-downloads.mjs +30 -1
- package/templates/publish-downloads.yml +5 -0
- package/templates/release-auto.yml +53 -7
- package/templates/release-tag.yml +1 -1
- package/tools/colab +89 -15
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/ci-wait.js +16 -2
- package/tools/lib/container-close.js +42 -2
- package/tools/lib/git.js +44 -1
- package/tools/lib/release-cut.js +128 -15
- package/tools/lib/release-finalize.js +3 -1
- package/tools/lib/release-runner.js +1 -1
- package/tools/lib/stale-base.js +15 -2
- package/tools/lib/stamp.js +1 -1
- package/tools/lib/state.js +150 -8
- package/tools/lib/verify-runs.js +207 -15
package/tools/lib/state.js
CHANGED
|
@@ -187,27 +187,168 @@ function sleep(ms) {
|
|
|
187
187
|
while (Date.now() < end) { /* spin */ }
|
|
188
188
|
}
|
|
189
189
|
|
|
190
|
-
|
|
191
|
-
|
|
190
|
+
/*
|
|
191
|
+
* The state lock (#712). `mkdir LOCK_DIR` is still the acquire — atomic, and the same primitive an
|
|
192
|
+
* older colab on this machine uses, so the two still exclude each other. What changed is that the
|
|
193
|
+
* holder now writes LOCK_OWNER inside it, and a waiter uses that record to tell a dead lock from a
|
|
194
|
+
* live one. Before, the directory recorded nothing: a holder that died inside the critical section
|
|
195
|
+
* left it forever, every state write on the machine (claims, worktrees, ports, places, ship) failed
|
|
196
|
+
* with "Lock stuck", and nobody could tell whether removing it by hand was safe.
|
|
197
|
+
*
|
|
198
|
+
* A waiter breaks the lock itself, logging one line, only when the holder is provably gone:
|
|
199
|
+
* - its pid is dead (same host), or
|
|
200
|
+
* - its pid is alive but started at a different time than the record says (pid reused), or
|
|
201
|
+
* - liveness cannot be proven at all — no readable owner (an older colab, or a holder that died
|
|
202
|
+
* between mkdir and writing the record), another host, or a start time `ps` cannot give — AND
|
|
203
|
+
* the lock is older than LOCK_STALE_MS, far above any real critical section (they are
|
|
204
|
+
* synchronous file edits: milliseconds).
|
|
205
|
+
* A live, matching holder is never broken, however old: the waiter gives up with the holder named.
|
|
206
|
+
*
|
|
207
|
+
* Breaking is race-safe in two layers. Breakers serialize on LOCK_BREAK (a second mkdir lock, held
|
|
208
|
+
* for microseconds), and inside it the breaker renames LOCK_DIR to a private name and re-reads the
|
|
209
|
+
* owner from THAT copy: only the exact stale owner it judged (same token) is removed. Anything else
|
|
210
|
+
* — a waiter that acquired a fresh lock in between — is renamed straight back.
|
|
211
|
+
*/
|
|
212
|
+
const LOCK_OWNER = 'owner.json';
|
|
213
|
+
const LOCK_BREAK = LOCK_DIR + '.break';
|
|
214
|
+
const LOCK_STALE_MS = 60 * 1000;
|
|
215
|
+
const PROC_START_MS = Date.now() - Math.round(process.uptime() * 1000);
|
|
216
|
+
const START_TOLERANCE_MS = 3000; // `ps -o lstart` truncates to whole seconds; uptime starts after exec
|
|
217
|
+
|
|
218
|
+
function lockOwnerRecord() {
|
|
219
|
+
return {
|
|
220
|
+
pid: process.pid, host: os.hostname(), start: PROC_START_MS, at: Date.now(),
|
|
221
|
+
token: `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`,
|
|
222
|
+
};
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** The owner record in `dir`, or null when absent/unreadable (an older colab, or mid-write). */
|
|
226
|
+
function readLockOwner(dir = LOCK_DIR) {
|
|
227
|
+
try {
|
|
228
|
+
const o = JSON.parse(fs.readFileSync(path.join(dir, LOCK_OWNER), 'utf8'));
|
|
229
|
+
return o && Number.isInteger(o.pid) && typeof o.token === 'string' ? o : null;
|
|
230
|
+
} catch (_) { return null; }
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** true = alive, false = no such process, null = cannot tell. */
|
|
234
|
+
function pidAlive(pid) {
|
|
235
|
+
try { process.kill(pid, 0); return true; } catch (e) {
|
|
236
|
+
if (e.code === 'ESRCH') return false;
|
|
237
|
+
if (e.code === 'EPERM') return true; // exists, owned by someone else
|
|
238
|
+
return null;
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** Start time (ms) of a live pid per `ps`, or null when ps cannot say. */
|
|
243
|
+
function pidStartMs(pid) {
|
|
244
|
+
try {
|
|
245
|
+
const out = require('child_process').execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)],
|
|
246
|
+
{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim();
|
|
247
|
+
const t = Date.parse(out);
|
|
248
|
+
return Number.isFinite(t) ? t : null;
|
|
249
|
+
} catch (_) { return null; }
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Judge the lock currently at LOCK_DIR. Returns { stale, owner, ageMs, reason } or null when there
|
|
254
|
+
* is no lock to judge. `startCache` (token -> ps start) keeps `ps` to once per holder per wait.
|
|
255
|
+
*/
|
|
256
|
+
function judgeLock(startCache = new Map(), now = Date.now()) {
|
|
257
|
+
let st;
|
|
258
|
+
try { st = fs.statSync(LOCK_DIR); } catch (_) { return null; }
|
|
259
|
+
const owner = readLockOwner();
|
|
260
|
+
const ageMs = Math.max(0, now - (owner && Number.isFinite(owner.at) ? owner.at : st.mtimeMs));
|
|
261
|
+
const old = ageMs > LOCK_STALE_MS;
|
|
262
|
+
if (!owner) return { stale: old, owner, ageMs, reason: 'no owner record' };
|
|
263
|
+
if (owner.host && owner.host !== os.hostname()) return { stale: old, owner, ageMs, reason: `held from host ${owner.host}` };
|
|
264
|
+
const alive = pidAlive(owner.pid);
|
|
265
|
+
if (alive === false) return { stale: true, owner, ageMs, reason: `pid ${owner.pid} is gone` };
|
|
266
|
+
if (alive === null) return { stale: old, owner, ageMs, reason: `pid ${owner.pid} liveness unknown` };
|
|
267
|
+
if (!startCache.has(owner.token)) startCache.set(owner.token, pidStartMs(owner.pid));
|
|
268
|
+
const psStart = startCache.get(owner.token);
|
|
269
|
+
if (psStart == null || !Number.isFinite(owner.start)) {
|
|
270
|
+
return { stale: old, owner, ageMs, reason: `pid ${owner.pid} alive, start time unverifiable` };
|
|
271
|
+
}
|
|
272
|
+
if (Math.abs(psStart - owner.start) > START_TOLERANCE_MS) {
|
|
273
|
+
return { stale: true, owner, ageMs, reason: `pid ${owner.pid} was reused by another process` };
|
|
274
|
+
}
|
|
275
|
+
return { stale: false, owner, ageMs, reason: `pid ${owner.pid} is alive` };
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
function describeHolder(j) {
|
|
279
|
+
if (!j) return 'holder unknown (lock vanished)';
|
|
280
|
+
const age = `${Math.round(j.ageMs / 1000)}s old`;
|
|
281
|
+
if (!j.owner) return `no owner recorded, ${age}`;
|
|
282
|
+
return `held by pid ${j.owner.pid} on ${j.owner.host || '?'}, ${age} — ${j.reason}`;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
function rmLockDir(dir) {
|
|
286
|
+
try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* best effort */ }
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Remove the lock `judged` found stale — but only if it is still that same lock. Returns true when
|
|
291
|
+
* it removed it. Never throws: a failed break just means the waiter keeps waiting.
|
|
292
|
+
*/
|
|
293
|
+
function breakStaleLock(judged, log = (m) => process.stderr.write(m + '\n')) {
|
|
294
|
+
try { fs.mkdirSync(LOCK_BREAK); } catch (e) {
|
|
295
|
+
// Another breaker is at it. A breaker that died mid-break leaves an empty LOCK_BREAK; clear it
|
|
296
|
+
// once it is far older than the microseconds a break takes, and let the next round retry.
|
|
297
|
+
try { if (Date.now() - fs.statSync(LOCK_BREAK).mtimeMs > 10 * 1000) fs.rmdirSync(LOCK_BREAK); } catch (_) { /* gone */ }
|
|
298
|
+
return false;
|
|
299
|
+
}
|
|
300
|
+
try {
|
|
301
|
+
const grave = `${LOCK_DIR}.stale-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
|
|
302
|
+
try { fs.renameSync(LOCK_DIR, grave); } catch (_) { return false; } // released meanwhile
|
|
303
|
+
const now = readLockOwner(grave);
|
|
304
|
+
const same = judged.owner ? (now && now.token === judged.owner.token) : !now;
|
|
305
|
+
if (!same) {
|
|
306
|
+
// A fresh lock replaced the stale one between judging and renaming — put it back untouched.
|
|
307
|
+
try { fs.renameSync(grave, LOCK_DIR); } catch (_) { /* LOCK_DIR re-taken: nothing safe to do */ }
|
|
308
|
+
return false;
|
|
309
|
+
}
|
|
310
|
+
rmLockDir(grave);
|
|
311
|
+
log(`colab: broke a stale state lock ${LOCK_DIR} (${describeHolder(judged)})`);
|
|
312
|
+
return true;
|
|
313
|
+
} finally {
|
|
314
|
+
try { fs.rmdirSync(LOCK_BREAK); } catch (_) { /* gone */ }
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/** Acquire the state lock, run fn, always release. Returns fn's result. */
|
|
319
|
+
function withLock(fn, { tries = 100, waitMs = 100, log } = {}) {
|
|
192
320
|
ensureDir();
|
|
193
|
-
|
|
321
|
+
const startCache = new Map();
|
|
322
|
+
let me = null;
|
|
323
|
+
let written = false;
|
|
324
|
+
let last = null;
|
|
194
325
|
for (let i = 0; i < tries; i++) {
|
|
195
326
|
try {
|
|
196
327
|
fs.mkdirSync(LOCK_DIR);
|
|
197
|
-
|
|
328
|
+
me = lockOwnerRecord();
|
|
329
|
+
try { fs.writeFileSync(path.join(LOCK_DIR, LOCK_OWNER), JSON.stringify(me) + '\n'); written = true; } catch (_) {
|
|
330
|
+
// Unrecorded is still a held lock — it just ages out like an older colab's would.
|
|
331
|
+
}
|
|
198
332
|
break;
|
|
199
333
|
} catch (e) {
|
|
200
334
|
if (e.code !== 'EEXIST') throw e;
|
|
335
|
+
last = judgeLock(startCache);
|
|
336
|
+
if (last && last.stale && breakStaleLock(last, log)) continue; // retry the mkdir at once
|
|
201
337
|
sleep(waitMs);
|
|
202
338
|
}
|
|
203
339
|
}
|
|
204
|
-
if (!
|
|
205
|
-
|
|
340
|
+
if (!me) {
|
|
341
|
+
const holder = describeHolder(judgeLock(startCache) || last);
|
|
342
|
+
throw new Error(`Lock stuck: ${LOCK_DIR} (${holder}). `
|
|
343
|
+
+ 'A live holder is never broken automatically; remove the directory by hand only if that process is not a colab writer.');
|
|
206
344
|
}
|
|
207
345
|
try {
|
|
208
346
|
return fn();
|
|
209
347
|
} finally {
|
|
210
|
-
|
|
348
|
+
// Release only our own lock: if a waiter judged us dead and broke it, LOCK_DIR is now theirs —
|
|
349
|
+
// including an ownerless one, when we did write our record and it is no longer there.
|
|
350
|
+
const cur = readLockOwner();
|
|
351
|
+
if (cur ? cur.token === me.token : !written) rmLockDir(LOCK_DIR);
|
|
211
352
|
}
|
|
212
353
|
}
|
|
213
354
|
|
|
@@ -257,6 +398,7 @@ function mutate(fn) {
|
|
|
257
398
|
}
|
|
258
399
|
|
|
259
400
|
module.exports = {
|
|
260
|
-
COLAB_DIR, STATE_FILE, CONFIG_FILE, LOCK_DIR, STATE_VERSION, DEFAULT_CONFIG,
|
|
401
|
+
COLAB_DIR, STATE_FILE, CONFIG_FILE, LOCK_DIR, LOCK_OWNER, LOCK_STALE_MS, STATE_VERSION, DEFAULT_CONFIG,
|
|
261
402
|
loadConfig, saveConfig, loadState, saveState, withLock, mutate, emptyState, atomicWrite,
|
|
403
|
+
_lock: { judgeLock, breakStaleLock, readLockOwner }, // for tools/lib/state-lock.test.js
|
|
262
404
|
};
|
package/tools/lib/verify-runs.js
CHANGED
|
@@ -150,6 +150,28 @@ const BRANCH_TRIGGERS = Object.freeze(['push', 'pull_request', 'pull_request_tar
|
|
|
150
150
|
* of the three `on:` shapes (scalar, flow list, block map / block list) — not a YAML parser.
|
|
151
151
|
*/
|
|
152
152
|
function workflowTriggers(text) {
|
|
153
|
+
const parsed = onEvents(text);
|
|
154
|
+
if (!parsed) return null;
|
|
155
|
+
const { name, events } = parsed;
|
|
156
|
+
let verifies = false;
|
|
157
|
+
for (const [ev, e] of events) {
|
|
158
|
+
if (!BRANCH_TRIGGERS.includes(ev)) continue;
|
|
159
|
+
if (ev !== 'push') { verifies = true; break; }
|
|
160
|
+
const keys = e.body.map((b) => (/^([A-Za-z_-]+)\s*:/.exec(b.text) || [])[1]).filter(Boolean);
|
|
161
|
+
const tagsOnly = (keys.includes('tags') || keys.includes('tags-ignore')) && !keys.includes('branches') && !keys.includes('branches-ignore');
|
|
162
|
+
if (!tagsOnly) { verifies = true; break; }
|
|
163
|
+
}
|
|
164
|
+
return { name, verifiesBranches: verifies };
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* The top-level `name:` and the `on:` events of one workflow file: `{ name, events }`, or null when
|
|
169
|
+
* the text has no top-level `on:`. `events` maps an event name to `{ inline, body }` — `inline` is
|
|
170
|
+
* what follows `<event>:` on its own line ('' for the block form), `body` the child lines with their
|
|
171
|
+
* indent (`{ indent, text }`, text trimmed). The scalar and flow-list forms of `on:` give events with
|
|
172
|
+
* no inline value and no body. Shared by workflowTriggers (#567) and pushTrigger (#723).
|
|
173
|
+
*/
|
|
174
|
+
function onEvents(text) {
|
|
153
175
|
const lines = String(text || '').split(/\r?\n/);
|
|
154
176
|
let name = null;
|
|
155
177
|
let onIdx = -1;
|
|
@@ -162,10 +184,10 @@ function workflowTriggers(text) {
|
|
|
162
184
|
if (m && onIdx < 0) { onIdx = i; onInline = yamlScalar(m[1]); }
|
|
163
185
|
}
|
|
164
186
|
if (onIdx < 0) return null;
|
|
165
|
-
const events = new Map();
|
|
187
|
+
const events = new Map();
|
|
166
188
|
if (onInline) {
|
|
167
189
|
const list = onInline.startsWith('[') ? onInline.replace(/^\[|\]$/g, '').split(',') : [onInline];
|
|
168
|
-
for (const e of list) { const v = yamlScalar(e); if (v) events.set(v, []); }
|
|
190
|
+
for (const e of list) { const v = yamlScalar(e); if (v) events.set(v, { inline: '', body: [] }); }
|
|
169
191
|
} else {
|
|
170
192
|
let evIndent = null;
|
|
171
193
|
let cur = null;
|
|
@@ -178,21 +200,188 @@ function workflowTriggers(text) {
|
|
|
178
200
|
if (indent < evIndent) break;
|
|
179
201
|
if (indent === evIndent) {
|
|
180
202
|
const t = l.trim();
|
|
181
|
-
const
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
203
|
+
const li = /^-\s*(.+)$/.exec(t);
|
|
204
|
+
const mk = li ? null : /^([A-Za-z_]+)\s*:\s*(.*)$/.exec(t);
|
|
205
|
+
cur = li ? yamlScalar(li[1].replace(/:.*$/, '')) : (mk ? yamlScalar(mk[1]) : null);
|
|
206
|
+
if (cur) events.set(cur, { inline: mk ? yamlScalar(mk[2]) : '', body: [] });
|
|
207
|
+
} else if (cur) events.get(cur).body.push({ indent, text: l.trim() });
|
|
185
208
|
}
|
|
186
209
|
}
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
210
|
+
return { name, events };
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** A YAML flow list `[a, 'b', "c"]` or a single scalar → the strings; '' → []. */
|
|
214
|
+
function flowList(v) {
|
|
215
|
+
const t = String(v || '').trim();
|
|
216
|
+
if (!t) return [];
|
|
217
|
+
const inner = t.startsWith('[') && t.endsWith(']') ? t.slice(1, -1) : t;
|
|
218
|
+
return inner.split(',').map(yamlScalar).filter(Boolean);
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
const PUSH_FILTER_KEYS = Object.freeze(['branches', 'branches-ignore', 'tags', 'tags-ignore', 'paths', 'paths-ignore']);
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* #723: what one workflow file says about a BRANCH PUSH — the question "should this workflow have a
|
|
225
|
+
* run at the head of branch B?" asks. Returns null when the text has no top-level `on:`, else
|
|
226
|
+
* `{ name, push, readable, branches, branchesIgnore, tagsOnly, paths, dispatch }`:
|
|
227
|
+
* push the triggers include `push`
|
|
228
|
+
* readable the push filters were read; false for a shape this small reader does not follow
|
|
229
|
+
* (a flow map `push: {…}`, an unknown key) — the caller then never expects a run
|
|
230
|
+
* branches / branchesIgnore the glob lists, null when absent
|
|
231
|
+
* tagsOnly `tags`/`tags-ignore` with no branch filter: a branch push never fires it
|
|
232
|
+
* paths a `paths` / `paths-ignore` filter is present: whether a push fires it depends on
|
|
233
|
+
* the files the push changed, which this reader does not judge
|
|
234
|
+
* dispatch the triggers include `workflow_dispatch` — `gh workflow run` can give it a run
|
|
235
|
+
* Not a YAML parser; the same deliberately small reader as workflowTriggers.
|
|
236
|
+
*/
|
|
237
|
+
function pushTrigger(text) {
|
|
238
|
+
const parsed = onEvents(text);
|
|
239
|
+
if (!parsed) return null;
|
|
240
|
+
const { name, events } = parsed;
|
|
241
|
+
const out = { name, push: events.has('push'), readable: true, branches: null, branchesIgnore: null,
|
|
242
|
+
tagsOnly: false, paths: false, dispatch: events.has('workflow_dispatch') };
|
|
243
|
+
if (!out.push) return out;
|
|
244
|
+
const e = events.get('push');
|
|
245
|
+
if (e.inline && !['null', '~', '{}'].includes(e.inline)) { out.readable = false; return out; }
|
|
246
|
+
const lists = {};
|
|
247
|
+
let key = null;
|
|
248
|
+
let keyIndent = null;
|
|
249
|
+
for (const b of e.body) {
|
|
250
|
+
if (keyIndent === null) keyIndent = b.indent;
|
|
251
|
+
if (b.indent === keyIndent) {
|
|
252
|
+
const m = /^([A-Za-z_-]+)\s*:\s*(.*)$/.exec(b.text);
|
|
253
|
+
if (!m || !PUSH_FILTER_KEYS.includes(m[1])) { out.readable = false; return out; }
|
|
254
|
+
key = m[1];
|
|
255
|
+
lists[key] = flowList(m[2]);
|
|
256
|
+
} else if (key && b.indent > keyIndent) {
|
|
257
|
+
const li = /^-\s*(.+)$/.exec(b.text);
|
|
258
|
+
if (!li) { out.readable = false; return out; }
|
|
259
|
+
lists[key].push(yamlScalar(li[1]));
|
|
260
|
+
} else { out.readable = false; return out; }
|
|
194
261
|
}
|
|
195
|
-
|
|
262
|
+
out.branches = lists.branches || null;
|
|
263
|
+
out.branchesIgnore = lists['branches-ignore'] || null;
|
|
264
|
+
out.tagsOnly = !!(lists.tags || lists['tags-ignore']) && !out.branches && !out.branchesIgnore;
|
|
265
|
+
out.paths = !!(lists.paths || lists['paths-ignore']);
|
|
266
|
+
return out;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* One GitHub filter pattern (`*` not across `/`, `**` across, `?` / `+` / `[…]` on the preceding
|
|
271
|
+
* character as in a regex) → a RegExp over the whole branch name, or null when it cannot be read.
|
|
272
|
+
*/
|
|
273
|
+
function filterPatternRe(p) {
|
|
274
|
+
let re = '';
|
|
275
|
+
const s = String(p);
|
|
276
|
+
for (let i = 0; i < s.length; i++) {
|
|
277
|
+
const c = s[i];
|
|
278
|
+
if (c === '*') { if (s[i + 1] === '*') { re += '.*'; i++; } else re += '[^/]*'; }
|
|
279
|
+
else if (c === '?' || c === '+') re += c;
|
|
280
|
+
else if (c === '[') { const j = s.indexOf(']', i); if (j < 0) return null; re += s.slice(i, j + 1); i = j; }
|
|
281
|
+
else if (c === '\\') { if (i + 1 >= s.length) return null; re += s[i + 1].replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); i++; }
|
|
282
|
+
else re += c.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
|
|
283
|
+
}
|
|
284
|
+
try { return new RegExp(`^${re}$`); } catch (_) { return null; }
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/**
|
|
288
|
+
* #723: does a push to `branch` pass a workflow's branch filters? true / false, or null when a
|
|
289
|
+
* pattern cannot be read. `branches` is ordered with `!` negations (the last match decides);
|
|
290
|
+
* `branches-ignore` excludes on any match. Neither list → true.
|
|
291
|
+
*/
|
|
292
|
+
function branchFilterMatches(branch, { branches = null, branchesIgnore = null } = {}) {
|
|
293
|
+
if (branches) {
|
|
294
|
+
let hit = false;
|
|
295
|
+
for (const raw of branches) {
|
|
296
|
+
const neg = raw.startsWith('!');
|
|
297
|
+
const re = filterPatternRe(neg ? raw.slice(1) : raw);
|
|
298
|
+
if (!re) return null;
|
|
299
|
+
if (re.test(branch)) hit = !neg;
|
|
300
|
+
}
|
|
301
|
+
return hit;
|
|
302
|
+
}
|
|
303
|
+
if (branchesIgnore) {
|
|
304
|
+
for (const raw of branchesIgnore) {
|
|
305
|
+
const re = filterPatternRe(raw);
|
|
306
|
+
if (!re) return null;
|
|
307
|
+
if (re.test(branch)) return false;
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
return true;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** GitHub's skip directives (docs: "Skipping workflow runs") — a push run is not created for them. */
|
|
314
|
+
const SKIP_DIRECTIVES = Object.freeze(['[skip ci]', '[ci skip]', '[no ci]', '[skip actions]', '[actions skip]']);
|
|
315
|
+
|
|
316
|
+
function skipsWorkflows(message) {
|
|
317
|
+
const m = String(message || '');
|
|
318
|
+
const low = m.toLowerCase();
|
|
319
|
+
return SKIP_DIRECTIVES.some((d) => low.includes(d)) || /^skip-checks:\s*true\s*$/mi.test(m);
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/**
|
|
323
|
+
* #723: the workflows that SHOULD have a push run at the head of `branch` — the expected set a
|
|
324
|
+
* branch verdict reads before it may call the head green. A workflow is expected when its definition
|
|
325
|
+
* AT THE HEAD (GitHub reads the workflow file from the pushed commit):
|
|
326
|
+
* - is triggered by `push`, read cleanly, not tags-only, with no `paths` / `paths-ignore` filter,
|
|
327
|
+
* - passes its branch filters for `branch` (an unreadable pattern → not expected),
|
|
328
|
+
* - is not in `ship-ignore-workflows`, and is in `ship-gate-workflows` when that list is declared,
|
|
329
|
+
* - is not reported anything but `active` by the workflows API (`states`: path → `{state, id, name}`
|
|
330
|
+
* or a bare state string; null = unread, every workflow taken as active). The API's `id` and
|
|
331
|
+
* `name` ride on the entry, so a run is matched by its workflow id too (git.js missingExpected).
|
|
332
|
+
* Nothing is expected when the head commit's message carries a skip directive (`headMessage`).
|
|
333
|
+
*
|
|
334
|
+
* Every doubt resolves to NOT expected: that is today's reading (the runs that exist decide), so the
|
|
335
|
+
* set can only add a hold where a workflow demonstrably should have run, never invent one.
|
|
336
|
+
*
|
|
337
|
+
* @param {object} a
|
|
338
|
+
* @param {Array<{path:string, text:string}>} a.defs - the workflow files at the head
|
|
339
|
+
* @param {string} a.branch
|
|
340
|
+
* @param {object} [a.policy] - parsePolicy's `{gate, ignore}`
|
|
341
|
+
* @param {Map<string,(string|{state:string, id:number, name:string})>|null} [a.states]
|
|
342
|
+
* @param {string|null} [a.headMessage]
|
|
343
|
+
* @returns {{ expected: Array<{name:string, path:string, dispatch:boolean, id?:number, apiName?:string}>, skipDirective: boolean }}
|
|
344
|
+
*/
|
|
345
|
+
function expectedWorkflows({ defs, branch, policy = null, states = null, headMessage = null }) {
|
|
346
|
+
if (skipsWorkflows(headMessage)) return { expected: [], skipDirective: true };
|
|
347
|
+
const p = policy || { gate: null, ignore: [] };
|
|
348
|
+
const expected = [];
|
|
349
|
+
for (const d of defs || []) {
|
|
350
|
+
const t = pushTrigger(d.text);
|
|
351
|
+
if (!t || !t.push || !t.readable || t.tagsOnly || t.paths) continue;
|
|
352
|
+
if (branchFilterMatches(branch, t) !== true) continue;
|
|
353
|
+
const name = t.name || d.path;
|
|
354
|
+
if (p.ignore && p.ignore.includes(name)) continue;
|
|
355
|
+
if (p.gate && !p.gate.includes(name)) continue;
|
|
356
|
+
const st = states && states.has(d.path) ? states.get(d.path) : null;
|
|
357
|
+
const info = st && typeof st === 'object' ? st : { state: st };
|
|
358
|
+
if (info.state && info.state !== 'active') continue;
|
|
359
|
+
expected.push({ name, path: d.path, dispatch: t.dispatch,
|
|
360
|
+
...(info.id != null ? { id: info.id } : {}), ...(info.name && info.name !== name ? { apiName: info.name } : {}) });
|
|
361
|
+
}
|
|
362
|
+
return { expected, skipDirective: false };
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
/**
|
|
366
|
+
* #723: how to get a run for each missing workflow — a hint, never an action. `gh workflow run` where
|
|
367
|
+
* the workflow takes `workflow_dispatch` (#567 counts that run as the push run it stands in for);
|
|
368
|
+
* otherwise a draft PR, or an empty re-push, which is the implementer's call.
|
|
369
|
+
*/
|
|
370
|
+
function missingHint(missing, branch) {
|
|
371
|
+
const list = Array.isArray(missing) ? missing : [];
|
|
372
|
+
if (!list.length) return '';
|
|
373
|
+
const b = branch || '<branch>';
|
|
374
|
+
const parts = list.map((x) => (x.dispatch
|
|
375
|
+
? `\`gh workflow run ${String(x.path || x.name).split('/').pop()} --ref ${b}\``
|
|
376
|
+
: `${x.name}: no workflow_dispatch — open a draft PR (\`gh pr create --draft --head ${b}\`) or push an empty commit (the implementer's call)`));
|
|
377
|
+
return `to get the run: ${parts.join('; ')}`;
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** #723: the verdict-detail suffix naming the expected workflows with no run at the sha — '' when none. */
|
|
381
|
+
function missingNote(missing, branch) {
|
|
382
|
+
const list = Array.isArray(missing) ? missing : [];
|
|
383
|
+
if (!list.length) return '';
|
|
384
|
+
return ` — no run of ${list.map((x) => x.name).join(', ')} at this sha, though ${list.length === 1 ? 'its' : 'their'} definition fires on a push to this branch (#723); ${missingHint(list, branch)}`;
|
|
196
385
|
}
|
|
197
386
|
|
|
198
387
|
/** The compact verdict-detail note for rows the lost-push rescue counted — '' when none. */
|
|
@@ -225,4 +414,7 @@ function skippedOnlyNote(rows) {
|
|
|
225
414
|
return ` — not judged, every run skipped so it ran nothing here (#688; name a workflow in ship-gate-workflows if it must run): ${names.join(', ')}`;
|
|
226
415
|
}
|
|
227
416
|
|
|
228
|
-
module.exports = {
|
|
417
|
+
module.exports = {
|
|
418
|
+
VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, SKIP_DIRECTIVES, parsePolicy, setAsideReason, splitVerifying, setAsideNote, skippedOnlyNote,
|
|
419
|
+
workflowTriggers, pushTrigger, branchFilterMatches, skipsWorkflows, expectedWorkflows, missingHint, missingNote, dispatchCountedNote,
|
|
420
|
+
};
|