@futurelastic/colab-handbook 1.16.0-rc.2 → 1.16.0-rc.21
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/README.md +20 -18
- package/README.vi.md +22 -20
- package/package.json +1 -1
- package/templates/README.md +38 -4
- package/templates/publish-downloads.mjs +659 -0
- package/templates/publish-downloads.yml +184 -0
- package/tools/colab +66 -20
- package/tools/lib/ci-verdict.js +98 -7
- package/tools/lib/git.js +68 -12
- package/tools/lib/install-check.js +1 -1
- package/tools/lib/ship-handoff.js +34 -5
package/tools/lib/git.js
CHANGED
|
@@ -996,8 +996,8 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
|
996
996
|
|
|
997
997
|
// createdAt + databaseId are additive (#155): a NON-completed pick needs both to let a caller
|
|
998
998
|
// judge whether it is merely slow or structurally WEDGED (tools/lib/ci-verdict.js) — createdAt for
|
|
999
|
-
// the age backstop, databaseId to look up its
|
|
1000
|
-
//
|
|
999
|
+
// the age backstop, databaseId to look up its jobs (ghRunJobs, below — a second call, made lazily
|
|
1000
|
+
// by the caller, never here: an ordinary green check must not pay for a read it never needs).
|
|
1001
1001
|
const r = gh(['run', 'list', '--branch', branch, '-L', String(limit),
|
|
1002
1002
|
// workflowName is additive (#338): `colab release cut`'s full-suite condition groups the rows by
|
|
1003
1003
|
// workflow — a workflow whose only run at the sha was cancelled never ran its suite.
|
|
@@ -1059,6 +1059,14 @@ function fullSha(repo, sha) {
|
|
|
1059
1059
|
* Every workflow run at `sha` in ONE REST call (#495) — `actions/runs?head_sha=<sha>[&branch=<b>]`,
|
|
1060
1060
|
* rows in `gh run list --json` shape. Returns `{ rows }` on success, `{ rateLimited: true }` on a
|
|
1061
1061
|
* rate limit, `{}` on any other failure (the caller decides whether to fall back).
|
|
1062
|
+
*
|
|
1063
|
+
* #651: an EMPTY filtered answer is not believed on its own. The forge's filter index was measured
|
|
1064
|
+
* returning `total_count: 0` for both `head_sha=` and `branch=` about 10 hours after the runs
|
|
1065
|
+
* finished, while the unfiltered listing held them (green). Read that way, a green trunk is "CI is
|
|
1066
|
+
* not wired" (HUMAN_GATED). So an empty answer is re-read from the unfiltered listing, filtered
|
|
1067
|
+
* here by the same two keys (UNFILTERED_RUN_PAGES pages at most). Rows found that way carry
|
|
1068
|
+
* `readVia: 'unfiltered-listing'`, so the verdict can say how it was read. Nothing found either:
|
|
1069
|
+
* the empty set stands, and the read still fails closed.
|
|
1062
1070
|
*/
|
|
1063
1071
|
function ghRunsAtShaRest(repo, sha, branch) {
|
|
1064
1072
|
sha = fullSha(repo, sha); // #529: the API's head_sha is 40-hex; an abbreviated one matches no row
|
|
@@ -1068,7 +1076,51 @@ function ghRunsAtShaRest(repo, sha, branch) {
|
|
|
1068
1076
|
const r = ghApiConditional(repo, `repos/{owner}/{repo}/actions/runs?${q}`);
|
|
1069
1077
|
if (r.kind === 'rate-limited') return { rateLimited: true, detail: r.detail };
|
|
1070
1078
|
if (r.kind !== 'ok' || !r.json || !Array.isArray(r.json.workflow_runs)) return {};
|
|
1071
|
-
|
|
1079
|
+
const rows = r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === sha);
|
|
1080
|
+
if (rows.length) return { rows };
|
|
1081
|
+
const fb = ghRunsAtShaUnfiltered(repo, sha, branch);
|
|
1082
|
+
if (fb.rateLimited) return fb;
|
|
1083
|
+
return { rows: fb.rows && fb.rows.length ? fb.rows : rows };
|
|
1084
|
+
}
|
|
1085
|
+
|
|
1086
|
+
/** #651: how many pages (100 runs each, newest first) the unfiltered re-read may spend. */
|
|
1087
|
+
const UNFILTERED_RUN_PAGES = 3;
|
|
1088
|
+
/** #651: a run is never created before its commit. This margin absorbs committer-clock skew. */
|
|
1089
|
+
const UNFILTERED_SKEW_MS = 60 * 60 * 1000;
|
|
1090
|
+
|
|
1091
|
+
/**
|
|
1092
|
+
* #651: the runs at `sha` (and on `branch`, when given) read from the UNFILTERED `actions/runs`
|
|
1093
|
+
* listing, filtered here by the same keys the server filter would have used. Bounded: at most
|
|
1094
|
+
* UNFILTERED_RUN_PAGES pages. It stops early on a short page, and on a page whose oldest run was
|
|
1095
|
+
* created before the commit, with UNFILTERED_SKEW_MS of margin. A sha with no run yet usually
|
|
1096
|
+
* costs one extra read, because page 1 already reaches back past the commit. Returns `{ rows }`
|
|
1097
|
+
* (possibly empty), `{ rateLimited: true }`, or `{}` when no page could be read.
|
|
1098
|
+
*/
|
|
1099
|
+
function ghRunsAtShaUnfiltered(repo, sha, branch) {
|
|
1100
|
+
const ciWait = require('./ci-wait');
|
|
1101
|
+
const born = commitTimeMs(repo, sha);
|
|
1102
|
+
const floor = born == null ? null : born - UNFILTERED_SKEW_MS;
|
|
1103
|
+
const found = [];
|
|
1104
|
+
let readAny = false;
|
|
1105
|
+
for (let page = 1; page <= UNFILTERED_RUN_PAGES; page++) {
|
|
1106
|
+
const r = ghApiConditional(repo, `repos/{owner}/{repo}/actions/runs?per_page=100&page=${page}`);
|
|
1107
|
+
if (r.kind === 'rate-limited') return { rateLimited: true, detail: r.detail };
|
|
1108
|
+
if (r.kind !== 'ok' || !r.json || !Array.isArray(r.json.workflow_runs)) break;
|
|
1109
|
+
readAny = true;
|
|
1110
|
+
const raw = r.json.workflow_runs;
|
|
1111
|
+
for (const x of raw) {
|
|
1112
|
+
if (!x || x.head_sha !== sha) continue;
|
|
1113
|
+
if (branch && x.head_branch !== branch) continue;
|
|
1114
|
+
found.push({ ...ciWait.restRow(x), readVia: 'unfiltered-listing' });
|
|
1115
|
+
}
|
|
1116
|
+
if (raw.length < 100) break;
|
|
1117
|
+
const oldest = raw.reduce((m, x) => {
|
|
1118
|
+
const t = x && x.created_at ? Date.parse(x.created_at) : NaN;
|
|
1119
|
+
return Number.isFinite(t) && (m === null || t < m) ? t : m;
|
|
1120
|
+
}, null);
|
|
1121
|
+
if (floor != null && oldest != null && oldest < floor) break;
|
|
1122
|
+
}
|
|
1123
|
+
return readAny ? { rows: found } : {};
|
|
1072
1124
|
}
|
|
1073
1125
|
|
|
1074
1126
|
/** Is a `gh` binary on PATH (#495)? No API call — cached per process. The credential is proven by
|
|
@@ -1211,6 +1263,8 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1211
1263
|
...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
|
|
1212
1264
|
...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
|
|
1213
1265
|
...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
|
|
1266
|
+
// #651: the rows came from the unfiltered listing because the forge's filter index was empty.
|
|
1267
|
+
...(allForSha.some((x) => x && x.readVia === 'unfiltered-listing') ? { readVia: 'unfiltered-listing' } : {}),
|
|
1214
1268
|
};
|
|
1215
1269
|
const r = summarizeRepoOwnedRuns(heads, sha);
|
|
1216
1270
|
return { ...r, ...extra };
|
|
@@ -1341,8 +1395,9 @@ function summarizeRepoOwnedRuns(forSha, sha) {
|
|
|
1341
1395
|
/**
|
|
1342
1396
|
* Job count for one workflow run (#155) — how many jobs GitHub has attached to it. A queued run
|
|
1343
1397
|
* with ZERO jobs has not been picked up by any runner: the measured shape of a billing lockout or a
|
|
1344
|
-
* dead runner pool
|
|
1345
|
-
*
|
|
1398
|
+
* dead runner pool. The wedge read in tools/colab `classifyCiRunRaw` now takes the count from
|
|
1399
|
+
* `ghRunJobs` below (#650 needs the jobs' statuses too, from the same one call); this stays for the
|
|
1400
|
+
* callers that need only the count (release-finalize's displaced-run check). Deliberately a separate call from `ghRunForSha` (never folded into
|
|
1346
1401
|
* its `--json` field list): job counts require `gh run view`, one call per run, and the ordinary
|
|
1347
1402
|
* green-trunk ship makes zero of these — callers fetch it lazily, only for a run that is already
|
|
1348
1403
|
* non-completed and therefore a wedge candidate.
|
|
@@ -1364,14 +1419,15 @@ function ghRunJobCount(repo, runDatabaseId) {
|
|
|
1364
1419
|
* failure, run gone, unparseable body). `null` must NOT be read as "no jobs"; every consumer of
|
|
1365
1420
|
* this fails closed on it.
|
|
1366
1421
|
*
|
|
1367
|
-
* A SIBLING of `ghRunJobCount` above, deliberately not a refactor of it
|
|
1368
|
-
*
|
|
1369
|
-
*
|
|
1422
|
+
* A SIBLING of `ghRunJobCount` above, deliberately not a refactor of it — the release-finalize
|
|
1423
|
+
* caller needs only the count. Since #650 this is also the wedge read: `classifyCiRunRaw` calls it
|
|
1424
|
+
* (once, for a non-completed run only) instead of `ghRunJobCount`, because telling "every job
|
|
1425
|
+
* completed, the forge never concluded the run" from #155's shapes needs the jobs' statuses and
|
|
1426
|
+
* timestamps, and `gh run view --json jobs` costs the same one call either way.
|
|
1370
1427
|
*
|
|
1371
|
-
* Costs one `gh run view` per run, so callers fetch it LAZILY —
|
|
1372
|
-
* (condition 2b, #297, and the #321 carve-out)
|
|
1373
|
-
*
|
|
1374
|
-
* green run of its own. Every other ship path makes zero of these calls.
|
|
1428
|
+
* Costs one `gh run view` per run, so callers fetch it LAZILY — the wedge read above, the cure rule
|
|
1429
|
+
* (tools/lib/ci-cure.js, condition 2b, #297, and the #321 carve-out), and the release paths. An
|
|
1430
|
+
* ordinary green or plain-failed trunk read makes zero of these calls.
|
|
1375
1431
|
*
|
|
1376
1432
|
* Step-level detail is the whole point: GitHub reports a job whose steps were all SKIPPED as
|
|
1377
1433
|
* `conclusion: success`, so run- and job-level conclusions are blind to exactly the fast-exit the
|
|
@@ -162,7 +162,7 @@ function checkSkills({ root, home, colabHome }) {
|
|
|
162
162
|
const byId = Object.fromEntries(all.map((e) => [e.id, e]));
|
|
163
163
|
const targets = all.filter((e) => e.skills_dir).map((e) => ({ e, dir: engines.expandHome(e.skills_dir, home) }));
|
|
164
164
|
for (const dir of engines.rememberedDirs(colabHome)) {
|
|
165
|
-
if (!targets.some((t) => t.dir === dir)) targets.push({ e: byId.generic || { id: 'generic', label: 'another
|
|
165
|
+
if (!targets.some((t) => t.dir === dir)) targets.push({ e: byId.generic || { id: 'generic', label: 'another agent runtime', note: [], caveat: [] }, dir });
|
|
166
166
|
}
|
|
167
167
|
|
|
168
168
|
const rows = [];
|
|
@@ -35,6 +35,13 @@
|
|
|
35
35
|
* 7. every issue the branch carries has a LIVE `🔒 Claimed` comment naming this branch, posted by
|
|
36
36
|
* the hand-off's author before the hand-off — the claim really does live elsewhere, and the
|
|
37
37
|
* party handing off is the party holding it.
|
|
38
|
+
* ONE exemption (#647): an issue the trailing run carries that was already CLOSED before the
|
|
39
|
+
* hand-off was posted only names history (a flaky test named after it) — it needs no claim, and
|
|
40
|
+
* goes back in `refIssues` so the squash says `Refs #A` and ship neither closes it nor posts a
|
|
41
|
+
* ship comment on it. Closed AFTER the hand-off is no exemption: closing an issue must never
|
|
42
|
+
* launder away the claim it lacked. An issue whose state could not be read is not exempt. Every
|
|
43
|
+
* OPEN issue still needs its claim, `--refs` or not — `--refs` decides Closes vs Refs, never who
|
|
44
|
+
* may land; and at least one issue must remain to close, or there is nothing handed off.
|
|
38
45
|
*
|
|
39
46
|
* Pure: every input is already read. tools/colab does the IO (`gh api`, `git fetch`, issue views).
|
|
40
47
|
*/
|
|
@@ -72,11 +79,15 @@ function namedShas(body) {
|
|
|
72
79
|
* or null for an issue whose comments could not be read
|
|
73
80
|
* syncChain — (#579) the first-parent ancestors of the remote head reached through pure
|
|
74
81
|
* base-sync merges only, nearest first (syncMergeChain's output); [] or absent = none
|
|
75
|
-
*
|
|
82
|
+
* issueStates — (#647) { [n]: { state, closedAt } } per issue as read now; a missing entry is
|
|
83
|
+
* unknown and earns no exemption
|
|
84
|
+
* refNumbers — (#647) the --refs numbers; used only to say why they do not waive a claim
|
|
85
|
+
* Returns { ok: true, issues, refIssues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
|
|
86
|
+
* `issues` is the whole trailing run; `refIssues` is its closed-before-the-hand-off subset (#647).
|
|
76
87
|
* `sha` is what lands (the remote head); `handedOff` is the sha the hand-off named — equal to `sha`
|
|
77
88
|
* unless the head was synced, in which case `syncMerges` counts the merges between them.
|
|
78
89
|
*/
|
|
79
|
-
function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain }) {
|
|
90
|
+
function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain, issueStates, refNumbers }) {
|
|
80
91
|
const no = (reason, detail) => ({ ok: false, reason, detail });
|
|
81
92
|
const u = parseHandoffUrl(url);
|
|
82
93
|
if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not an issue-comment URL (…/issues/<N>#issuecomment-<id>)`);
|
|
@@ -109,18 +120,36 @@ function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain }
|
|
|
109
120
|
? `the hand-off names ${shas.map((s) => s.slice(0, 8)).join(', ')}, but the remote ${branch} is at ${head.slice(0, 8)}${synced} — the branch moved after it was handed off by more than a clean merge of its base; ask its executor for a new hand-off`
|
|
110
121
|
: `the hand-off names no head sha — it must say which commit it hands off (the remote is at ${head.slice(0, 8)})`);
|
|
111
122
|
}
|
|
123
|
+
const refIssues = issues.filter((n) => closedBefore(issueStates && issueStates[n], comment.createdAt));
|
|
124
|
+
if (refIssues.length === issues.length) {
|
|
125
|
+
return no('nothing-to-close', `every issue ${branch} carries (${issues.map((n) => '#' + n).join(' ')}) was closed before the hand-off — there is no open, claimed issue for it to land`);
|
|
126
|
+
}
|
|
127
|
+
const waived = new Set((refNumbers || []).map(Number));
|
|
112
128
|
let executor = null;
|
|
113
129
|
for (const n of issues) {
|
|
130
|
+
if (refIssues.includes(n)) continue;
|
|
114
131
|
const live = claimsByIssue ? claimsByIssue[n] : null;
|
|
115
132
|
if (!live) return no('claims-unreadable', `#${n}'s comments could not be read — the executor's claim cannot be checked`);
|
|
116
133
|
const match = live.find((c) => c.branch === branch && c.login === comment.login && c.at < comment.createdAt);
|
|
117
134
|
if (!match) {
|
|
118
|
-
|
|
135
|
+
const st = issueStates && issueStates[n];
|
|
136
|
+
const why = st && String(st.state).toUpperCase() === 'CLOSED'
|
|
137
|
+
? ` (it was closed at ${st.closedAt || 'an unreadable time'}, not before the hand-off at ${comment.createdAt} — only an issue already closed when the hand-off was posted needs no claim)`
|
|
138
|
+
: waived.has(n) ? ' (--refs keeps it open in the squash; it does not waive the claim of an open issue)' : '';
|
|
139
|
+
return no('no-executor-claim', `#${n} has no live 🔒 claim on ${branch} by ${comment.login || 'the hand-off author'} posted before the hand-off${why} — ` +
|
|
119
140
|
'the hand-off must come from the party holding the claim');
|
|
120
141
|
}
|
|
121
142
|
if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
|
|
122
143
|
}
|
|
123
|
-
return { ok: true, issues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim() };
|
|
144
|
+
return { ok: true, issues, refIssues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim() };
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** #647: was this issue CLOSED strictly before `at` (the hand-off's createdAt)? Unknown ⇒ false. */
|
|
148
|
+
function closedBefore(st, at) {
|
|
149
|
+
if (!st || String(st.state || '').toUpperCase() !== 'CLOSED') return false;
|
|
150
|
+
const c = Date.parse(st.closedAt || '');
|
|
151
|
+
const h = Date.parse(at || '');
|
|
152
|
+
return Number.isFinite(c) && Number.isFinite(h) && c < h;
|
|
124
153
|
}
|
|
125
154
|
|
|
126
155
|
/**
|
|
@@ -209,4 +238,4 @@ function parseHandoffTrailer(body) {
|
|
|
209
238
|
return m ? { url: m[1], handedOff: m[2] } : null;
|
|
210
239
|
}
|
|
211
240
|
|
|
212
|
-
module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };
|
|
241
|
+
module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, closedBefore, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };
|