@futurelastic/colab-handbook 1.16.0-rc.8 → 1.16.0

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/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 job count (ghRunJobCount, below — a second call, made
1000
- // lazily by the caller, never here: an ordinary green check must not pay for a read it never needs).
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
- return { rows: r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === sha) };
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, and the PRIMARY signal tools/lib/ci-verdict.js uses to call a non-completed run
1345
- * WEDGED rather than merely slow. Deliberately a separate call from `ghRunForSha` (never folded into
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: that function sits on the
1368
- * wedge-detection hot path, and rewriting it as `ghRunJobs(...).length` would be churn with real
1369
- * regression surface for no gain here.
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 — tools/lib/ci-cure.js's cure rule
1372
- * (condition 2b, #297, and the #321 carve-out) is the only caller today, and `colab ship` reaches
1373
- * it only for a branch that is already blocked by a red trunk and has passed containment and a
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
@@ -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
- * Returns { ok: true, issues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
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
- return no('no-executor-claim', `#${n} has no live 🔒 claim on ${branch} by ${comment.login || 'the hand-off author'} posted before the hand-off — ` +
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 };