@futurelastic/colab-handbook 1.13.0-rc.9 → 1.13.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.
@@ -0,0 +1,104 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/batch-history.js — the audit's reading of `colab batch-stats --json` (#556).
4
+ *
5
+ * Two halves, deliberately separate:
6
+ * measure the repo's batch picture as four rates — overlap of serial landings with a partner
7
+ * inside their trunk-CI cycle, batch fill, first-attempt green rate of combined runs,
8
+ * eviction rate of members at build. Always shown; never a finding by itself.
9
+ * judge an advisory ONLY against a threshold the repo declares in `thresholds:` (the four
10
+ * `batch-*` keys in tools/lib/thresholds.js, none of which has a default). The owner's
11
+ * ruling on #556 — "should not set any hard code number" — is why: nothing declared ⇒
12
+ * the numbers are shown and nothing is flagged. Replaces #506's proposed fixed
13
+ * "suggest ship-batch: 3".
14
+ *
15
+ * A rate with no samples is unmeasured (null), and an unmeasured rate is never judged — the same
16
+ * rule as `batch-min-samples`, which a repo may declare to demand more than one sample.
17
+ *
18
+ * Pure: a batch-stats report + the parsed descriptor in, `{ measured, picture, advisories }` out.
19
+ */
20
+
21
+ const thresholds = require('./thresholds');
22
+ const shipBatch = require('./ship-batch');
23
+
24
+ const pctOf = (num, den) => (den > 0 ? Math.round((num / den) * 100) : null);
25
+ const pctRate = (r) => (r === null || r === undefined ? null : Math.round(r * 100));
26
+
27
+ /** The four rates and their sample counts, from a batch-stats report. */
28
+ function measure(rep) {
29
+ const s = rep.serial || {};
30
+ const b = rep.batches || {};
31
+ const d = rep.dropped || {};
32
+ const finished = (b.builds || 0) - (b.pending || 0);
33
+ return {
34
+ overlap: { pct: pctOf(s.overlapped || 0, s.cyclesRead || 0), samples: s.cyclesRead || 0, overlapped: s.overlapped || 0 },
35
+ fill: { batches: b.landed || 0, byMembers: b.fill || {} },
36
+ firstGreen: { pct: pctRate(b.firstAttemptGreenRate), samples: finished, green: b.firstAttemptGreen || 0 },
37
+ eviction: { pct: pctRate(d.rate), samples: d.attempted || 0, dropped: d.count || 0 },
38
+ };
39
+ }
40
+
41
+ /** One line per rate, for the human report. `—` is unmeasured, never zero. */
42
+ function picture(rep, m = measure(rep)) {
43
+ const p = (x) => (x.pct === null ? '—' : `${x.pct}%`);
44
+ const fill = Object.keys(m.fill.byMembers).sort().map((k) => `${m.fill.byMembers[k]}×${k}`).join(' · ') || '—';
45
+ const head = `batch history ${String(rep.since || '').slice(0, 10)} … ${String(rep.until || '').slice(0, 10)}: ${(rep.landings || {}).total || 0} landing(s), ${(rep.landings || {}).batch || 0} batch · ${(rep.landings || {}).serial || 0} serial (ship-batch: ${(rep.config || {}).n || 1})`;
46
+ return [
47
+ head,
48
+ `overlap ${p(m.overlap)} of ${m.overlap.samples} serial landing(s) had a partner green inside their trunk-CI cycle · fill ${fill} · first-attempt green ${p(m.firstGreen)} of ${m.firstGreen.samples} combined run(s) · eviction ${p(m.eviction)} of ${m.eviction.samples} member(s)`,
49
+ ];
50
+ }
51
+
52
+ /**
53
+ * Advisories for the rates that cross a DECLARED threshold. `doc` is the parsed descriptor.
54
+ * Returns `{ advisories: [text], judged: [key], unjudged: [{ key, why }] }` — a declared key that
55
+ * could not be judged (no samples, under batch-min-samples, not applicable) says why, so a quiet
56
+ * report never reads as "checked and fine" when it was not checked.
57
+ */
58
+ function judge(rep, doc, m = measure(rep)) {
59
+ const t = thresholds.parseThresholds(doc).values;
60
+ const n = shipBatch.parseShipBatch(doc || {}).n || 1;
61
+ const minN = t['batch-min-samples'] === null ? 1 : t['batch-min-samples'];
62
+ const advisories = [];
63
+ const judged = [];
64
+ const unjudged = [];
65
+ const enough = (key, rate) => {
66
+ if (rate.pct === null || rate.samples < minN) {
67
+ unjudged.push({ key, why: `${rate.samples} sample(s)${minN > 1 ? `, batch-min-samples is ${minN}` : ''}` });
68
+ return false;
69
+ }
70
+ judged.push(key);
71
+ return true;
72
+ };
73
+
74
+ const ov = t['batch-overlap-pct'];
75
+ if (ov !== null) {
76
+ if (n > 1) unjudged.push({ key: 'batch-overlap-pct', why: `already opted in (ship-batch: ${n})` });
77
+ else if (enough('batch-overlap-pct', m.overlap) && m.overlap.pct >= ov) {
78
+ advisories.push(`batch history: ${m.overlap.pct}% of ${m.overlap.samples} serial landings overlapped a partner's green inside their trunk-CI cycle (thresholds.batch-overlap-pct: ${ov}) — consider opting in to ship-batch; colab batch-stats has the pairs`);
79
+ }
80
+ }
81
+ const fg = t['batch-first-green-pct-min'];
82
+ if (fg !== null) {
83
+ if (n <= 1 && !m.firstGreen.samples) unjudged.push({ key: 'batch-first-green-pct-min', why: 'not batching (ship-batch absent or 1)' });
84
+ else if (enough('batch-first-green-pct-min', m.firstGreen) && m.firstGreen.pct < fg) {
85
+ advisories.push(`batch history: ${m.firstGreen.pct}% of ${m.firstGreen.samples} combined runs went green on the first attempt (thresholds.batch-first-green-pct-min: ${fg}) — consider lowering ship-batch${n > 1 ? ` below ${n}` : ''}`);
86
+ }
87
+ }
88
+ const ev = t['batch-eviction-pct-max'];
89
+ if (ev !== null) {
90
+ if (n <= 1 && !m.eviction.samples) unjudged.push({ key: 'batch-eviction-pct-max', why: 'not batching (ship-batch absent or 1)' });
91
+ else if (enough('batch-eviction-pct-max', m.eviction) && m.eviction.pct > ev) {
92
+ advisories.push(`batch history: ${m.eviction.pct}% of ${m.eviction.samples} batch members were dropped at build (thresholds.batch-eviction-pct-max: ${ev}) — colab batch-stats lists them by class`);
93
+ }
94
+ }
95
+ return { advisories, judged, unjudged };
96
+ }
97
+
98
+ /** The batch-* threshold names a descriptor declares — what makes a no-flag audit run worth a note. */
99
+ function declaredBatchKeys(doc) {
100
+ const d = thresholds.parseThresholds(doc).declared;
101
+ return Object.keys(d).filter((k) => k.startsWith('batch-'));
102
+ }
103
+
104
+ module.exports = { measure, picture, judge, declaredBatchKeys };
@@ -0,0 +1,277 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/batch-stats.js — how batch landing (#373) actually performs in ONE repo (#554).
4
+ *
5
+ * The batch knobs (`ship-batch: <N>`, `ship-batch-wait: <duration>`) have no handbook default: a repo
6
+ * picks them from its own history. This module is that history, derived from two sources every
7
+ * machine can read — never from the optional machine-local journal, which is off by default and
8
+ * per-machine:
9
+ *
10
+ * commits trunk's first-parent log. A batch member's squash carries `Ship-Batch: <ref>
11
+ * <branch>@<sha>` (ship-batch.js memberTrailer); a member dropped at build is recorded on
12
+ * the batch head as `Ship-Batch-Dropped: <ref> <branch>@<sha> <class>`. A trunk commit
13
+ * with neither is a serial landing, known by its `Closes #N`.
14
+ * runs the repo's CI runs (REST rows). Runs on `ship-batch/**` are the combined runs; runs on
15
+ * a feature branch say when that branch went green at its head; runs on trunk say when a
16
+ * landing was pushed (created) and when its trunk-CI cycle ended (updated).
17
+ *
18
+ * Pure: facts in, a report out — no git, no gh, no clock. `tools/colab`'s `cmdBatchStats` reads.
19
+ *
20
+ * What it measures, per window:
21
+ * batches landed and their fill; every combined-run build, first-attempt green, green after
22
+ * the one re-run, red, still pending
23
+ * red red builds and how many of their members then landed serially (the fallback)
24
+ * dropped members dropped at build, by class, and the eviction rate among attempted members
25
+ * serial serial landings, and MISSED PARTNERS: another candidate that landed later but was
26
+ * already green when this one landed alone (could have joined), or turned green
27
+ * within this landing's trunk-CI cycle (a partner wait of `waitSec` would have caught
28
+ * it — the number `ship-batch-wait` is tuned from)
29
+ * queueWait per landed change, green-at-head → landing
30
+ */
31
+
32
+ const branchName = require('./branch-name');
33
+ const shipBatch = require('./ship-batch');
34
+
35
+ /** `Closes #N` / `Fixes #N` / `Resolves #N` numbers in a commit body (GitHub's own keywords). */
36
+ function closesIssues(body) {
37
+ const out = new Set();
38
+ const re = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)\b/gi;
39
+ let m;
40
+ while ((m = re.exec(String(body || '')))) out.add(Number(m[1]));
41
+ return [...out];
42
+ }
43
+
44
+ /** Value at the q-th quantile (nearest-rank) of numbers, or null for none. */
45
+ function quantile(values, q) {
46
+ const v = (values || []).filter(Number.isFinite).sort((a, b) => a - b);
47
+ if (!v.length) return null;
48
+ return v[Math.min(v.length - 1, Math.max(0, Math.ceil(q * v.length) - 1))];
49
+ }
50
+
51
+ function summary(values) {
52
+ const v = (values || []).filter(Number.isFinite);
53
+ return { samples: v.length, p50Sec: quantile(v, 0.5), p90Sec: quantile(v, 0.9), maxSec: v.length ? Math.max(...v) : null };
54
+ }
55
+
56
+ const rate = (num, den) => (den > 0 ? Math.round((num / den) * 1000) / 1000 : null);
57
+ const isBatchRef = (b) => String(b || '').startsWith(shipBatch.REF_PREFIX);
58
+
59
+ /**
60
+ * When did `branch` go green at the head it had at time `atMs`? Its runs created before `atMs` are
61
+ * read; the newest sha among them is the head at that moment. Green only when every run at that sha
62
+ * finished success (cancelled aside, as combinedVerdict reads it) by `atMs` → the latest finish.
63
+ * Null when there is no run, or the head was not green yet — unknown, never a guess.
64
+ */
65
+ function greenAt(runsByBranch, branch, atMs, sha = null) {
66
+ const rows = (runsByBranch.get(branch) || []).filter((r) => r.createdMs <= atMs);
67
+ if (!rows.length) return null;
68
+ const headSha = sha
69
+ ? (rows.some((r) => r.sha.startsWith(sha) || sha.startsWith(r.sha)) ? rows.find((r) => r.sha.startsWith(sha) || sha.startsWith(r.sha)).sha : null)
70
+ : rows.reduce((a, b) => (b.createdMs > a.createdMs ? b : a)).sha;
71
+ if (!headSha) return null;
72
+ const at = rows.filter((r) => r.sha === headSha);
73
+ const v = shipBatch.combinedVerdict(at.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt })));
74
+ if (v.state !== 'green') return null;
75
+ const done = Math.max(...at.filter((r) => r.conclusion === 'success').map((r) => r.updatedMs));
76
+ return done <= atMs ? done : null;
77
+ }
78
+
79
+ /** Which feature branch carried a serial landing that closed `issues`, as of `atMs`? Newest run wins. */
80
+ function branchForIssues(runsByBranch, issues, atMs) {
81
+ if (!issues.length) return null;
82
+ let best = null;
83
+ for (const [b, rows] of runsByBranch) {
84
+ const nums = branchName.branchIssueNumbers(b);
85
+ if (!nums.some((n) => issues.includes(n))) continue;
86
+ const before = rows.filter((r) => r.createdMs <= atMs);
87
+ if (!before.length) continue;
88
+ const t = Math.max(...before.map((r) => r.createdMs));
89
+ if (!best || t > best.t) best = { branch: b, t };
90
+ }
91
+ return best ? best.branch : null;
92
+ }
93
+
94
+ /**
95
+ * The report. Inputs:
96
+ * commits [{ sha, dateMs, body }] — trunk first-parent, inside the window, any order
97
+ * runs [{ id, branch, sha, event, status, conclusion, attempt, createdMs, updatedMs, message? }]
98
+ * `message` is the head commit's message, needed only for ship-batch/** rows
99
+ * builds optional { [sha]: [message, …] } — every commit message of an UNLANDED build, when the
100
+ * caller could read them (compare API); a landed build is read from trunk instead
101
+ * trunk trunk branch name
102
+ * config { n, waitSec } — the repo's declared knobs, echoed so the report says what it tunes
103
+ */
104
+ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config = {} } = {}) {
105
+ const notes = [];
106
+ const runsByBranch = new Map();
107
+ const trunkRuns = new Map(); // sha → rows
108
+ const batchRuns = new Map(); // `${ref} ${sha}` → rows
109
+ for (const r of runs || []) {
110
+ if (!r || !r.branch || !r.sha) continue;
111
+ if (r.branch === trunk) { (trunkRuns.get(r.sha) || trunkRuns.set(r.sha, []).get(r.sha)).push(r); continue; }
112
+ if (isBatchRef(r.branch)) { const k = `${r.branch} ${r.sha}`; (batchRuns.get(k) || batchRuns.set(k, []).get(k)).push(r); continue; }
113
+ (runsByBranch.get(r.branch) || runsByBranch.set(r.branch, []).get(r.branch)).push(r);
114
+ }
115
+ // When a landing reached trunk: its trunk push run was created then. Fallback: the commit date
116
+ // (a fast-forward keeps the build-time date, so it reads early by the combined run's length).
117
+ const landedAt = (sha, fallback) => {
118
+ const rows = trunkRuns.get(sha) || [];
119
+ return rows.length ? Math.min(...rows.map((r) => r.createdMs)) : fallback;
120
+ };
121
+ const cycleEnd = (sha) => {
122
+ const rows = (trunkRuns.get(sha) || []).filter((r) => r.status === 'completed');
123
+ return rows.length ? Math.max(...rows.map((r) => r.updatedMs)) : null;
124
+ };
125
+
126
+ // ---- landings, oldest first ----
127
+ const sorted = [...(commits || [])].sort((a, b) => a.dateMs - b.dateMs);
128
+ const batches = new Map(); // ref → { ref, commits: [], members: [], dropped: [] }
129
+ const landings = []; // { kind, sha, atMs, members: [{ branch, sha }], issues }
130
+ for (const c of sorted) {
131
+ const members = shipBatch.parseMemberTrailers([c.body]);
132
+ if (members.length) {
133
+ const ref = members[0].ref;
134
+ const b = batches.get(ref) || batches.set(ref, { ref, commits: [], members: [], dropped: [] }).get(ref);
135
+ b.commits.push(c);
136
+ b.members.push(...members);
137
+ b.dropped.push(...shipBatch.parseDroppedTrailers([c.body]));
138
+ } else {
139
+ landings.push({ kind: 'serial', sha: c.sha, atMs: landedAt(c.sha, c.dateMs), commitMs: c.dateMs, issues: closesIssues(c.body) });
140
+ }
141
+ }
142
+ for (const b of batches.values()) {
143
+ const head = b.commits[b.commits.length - 1];
144
+ b.headSha = head.sha;
145
+ landings.push({ kind: 'batch', ref: b.ref, sha: head.sha, atMs: landedAt(head.sha, head.dateMs), commitMs: head.dateMs, members: b.members });
146
+ }
147
+ landings.sort((a, b) => a.atMs - b.atMs);
148
+
149
+ // ---- every landed change, with its green-at-head time ----
150
+ const changes = []; // { landing, branch, sha, issues, greenMs, atMs }
151
+ for (const l of landings) {
152
+ if (l.kind === 'batch') {
153
+ for (const m of l.members) {
154
+ changes.push({ landing: l, branch: m.branch, issues: branchName.branchIssueNumbers(m.branch), greenMs: greenAt(runsByBranch, m.branch, l.atMs, m.sha), atMs: l.atMs });
155
+ }
156
+ } else {
157
+ const br = branchForIssues(runsByBranch, l.issues, l.atMs);
158
+ l.branch = br;
159
+ changes.push({ landing: l, branch: br, issues: l.issues, greenMs: br ? greenAt(runsByBranch, br, l.atMs) : null, atMs: l.atMs });
160
+ }
161
+ }
162
+
163
+ // ---- combined-run builds ----
164
+ const landedHeads = new Set([...batches.values()].map((b) => b.headSha));
165
+ const buildRows = [];
166
+ for (const [k, rows] of batchRuns) {
167
+ const [ref, sha] = k.split(' ');
168
+ const v = shipBatch.combinedVerdict(rows.map((r) => ({ status: r.status, conclusion: r.conclusion, attempt: r.attempt, databaseId: r.id })));
169
+ const landed = landedHeads.has(sha);
170
+ const messages = landed ? null : (builds[sha] || rows.map((r) => r.message).filter(Boolean).slice(0, 1));
171
+ buildRows.push({ ref, sha, state: v.state, attempt: v.attempt, landed, createdMs: Math.min(...rows.map((r) => r.createdMs)), messages });
172
+ }
173
+ const finished = buildRows.filter((b) => b.state === 'green' || b.state === 'red');
174
+ const firstGreen = buildRows.filter((b) => b.state === 'green' && b.attempt === 1).length;
175
+ const rerunGreen = buildRows.filter((b) => b.state === 'green' && b.attempt > 1).length;
176
+ const redBuilds = buildRows.filter((b) => b.state === 'red');
177
+
178
+ // ---- red builds → did their members then land serially? ----
179
+ const serialChanges = changes.filter((c) => c.landing.kind === 'serial');
180
+ let redMembers = 0, relanded = 0, redMembersUnread = 0;
181
+ for (const b of redBuilds) {
182
+ const members = b.messages && b.messages.length ? shipBatch.parseMemberTrailers(b.messages) : [];
183
+ if (!members.length) { redMembersUnread++; continue; }
184
+ for (const m of members) {
185
+ redMembers++;
186
+ const nums = branchName.branchIssueNumbers(m.branch);
187
+ if (serialChanges.some((c) => c.atMs >= b.createdMs && (c.branch === m.branch || c.issues.some((n) => nums.includes(n))))) relanded++;
188
+ }
189
+ }
190
+ if (redMembersUnread) notes.push(`${redMembersUnread} red build(s) whose members could not be read (the ref is gone and its commits were not readable)`);
191
+
192
+ // ---- dropped members: landed batches from trunk, unlanded builds from their messages ----
193
+ const dropped = [];
194
+ const seenDrop = new Set();
195
+ const addDrop = (d, landed) => {
196
+ const k = `${d.ref} ${d.branch}@${d.sha}`;
197
+ if (seenDrop.has(k)) return;
198
+ seenDrop.add(k);
199
+ dropped.push({ ...d, landed });
200
+ };
201
+ for (const b of batches.values()) for (const d of b.dropped) addDrop(d, true);
202
+ for (const b of buildRows) if (!b.landed && b.messages) for (const d of shipBatch.parseDroppedTrailers(b.messages)) addDrop(d, false);
203
+ const builtMembers = [...batches.values()].reduce((n, b) => n + b.members.length, 0)
204
+ + buildRows.filter((b) => !b.landed && b.messages).reduce((n, b) => n + shipBatch.parseMemberTrailers(b.messages).length, 0);
205
+ const byClass = {};
206
+ for (const d of dropped) byClass[d.cls] = (byClass[d.cls] || 0) + 1;
207
+
208
+ // ---- missed partners: serial landings that landed alone while a partner was (nearly) ready ----
209
+ const pairs = [];
210
+ let withMissed = 0, withNear = 0, cyclesUnread = 0, overlapped = 0;
211
+ // A partner is judged by ITS state at this landing's moment, never by the head it finally landed
212
+ // with: a serial ship syncs the other branches, so their final heads all post-date it. The cycle
213
+ // ends when this landing's trunk run finishes — or at the next landing, whichever is first (a
214
+ // re-run moves a run's updated_at hours later, and the next landing moves trunk anyway).
215
+ const landingTimes = landings.map((l) => l.atMs).sort((a, b) => a - b);
216
+ for (const c of serialChanges) {
217
+ const next = landingTimes.find((t) => t > c.atMs);
218
+ let end = cycleEnd(c.landing.sha);
219
+ if (end === null) cyclesUnread++;
220
+ else if (next !== undefined) end = Math.min(end, next);
221
+ let missed = false, near = false;
222
+ const label = c.branch || c.landing.sha.slice(0, 7);
223
+ for (const o of changes) {
224
+ if (o === c || o.landing === c.landing || o.atMs <= c.atMs || !o.branch || o.branch === c.branch) continue;
225
+ const gNow = greenAt(runsByBranch, o.branch, c.atMs);
226
+ if (gNow !== null) {
227
+ missed = true;
228
+ pairs.push({ kind: 'missed', landed: label, partner: o.branch });
229
+ continue;
230
+ }
231
+ if (end === null) continue;
232
+ const gEnd = greenAt(runsByBranch, o.branch, end);
233
+ if (gEnd !== null && gEnd > c.atMs) {
234
+ near = true;
235
+ const from = c.greenMs !== null ? c.greenMs : c.atMs;
236
+ pairs.push({ kind: 'near', landed: label, partner: o.branch, waitSec: Math.round((gEnd - from) / 1000) });
237
+ }
238
+ }
239
+ if (missed) withMissed++;
240
+ else if (near) withNear++;
241
+ if (end !== null && (missed || near)) overlapped++;
242
+ }
243
+ if (cyclesUnread) notes.push(`${cyclesUnread} serial landing(s) with no finished trunk run in the window — near misses not judged for them`);
244
+ const unknownGreen = changes.filter((c) => c.greenMs === null).length;
245
+ if (unknownGreen) notes.push(`${unknownGreen} landed change(s) with no readable green-at-head run — left out of queue wait and partner matching`);
246
+
247
+ const fill = {};
248
+ for (const b of batches.values()) fill[b.members.length] = (fill[b.members.length] || 0) + 1;
249
+ const queueWait = summary(changes.filter((c) => c.greenMs !== null).map((c) => Math.round((c.atMs - c.greenMs) / 1000)));
250
+
251
+ return {
252
+ trunk,
253
+ config: { n: config.n || 1, waitSec: config.waitSec || 0 },
254
+ history: batches.size > 0 || buildRows.length > 0,
255
+ landings: { total: landings.length, batch: batches.size, serial: landings.length - batches.size },
256
+ batches: {
257
+ landed: batches.size, fill,
258
+ builds: buildRows.length, firstAttemptGreen: firstGreen, greenAfterRerun: rerunGreen, red: redBuilds.length,
259
+ pending: buildRows.length - finished.length,
260
+ firstAttemptGreenRate: rate(firstGreen, finished.length),
261
+ },
262
+ red: { builds: redBuilds.length, members: redMembers, relandedSerially: relanded },
263
+ dropped: { count: dropped.length, attempted: builtMembers + dropped.length, rate: rate(dropped.length, builtMembers + dropped.length), byClass, members: dropped },
264
+ serial: {
265
+ landings: serialChanges.length, withMissedPartner: withMissed, withNearMiss: withNear,
266
+ // #556: the overlap rate's honest denominator — only a landing whose trunk-CI cycle was read
267
+ // could have been judged for a partner inside it; `overlapped` counts those that had one.
268
+ cyclesRead: serialChanges.length - cyclesUnread, overlapped,
269
+ nearMissWait: summary(pairs.filter((p) => p.kind === 'near').map((p) => p.waitSec)),
270
+ pairs,
271
+ },
272
+ queueWait,
273
+ notes,
274
+ };
275
+ }
276
+
277
+ module.exports = { derive, closesIssues, quantile, greenAt, branchForIssues };
@@ -0,0 +1,195 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/ci-profile.js — a repo's measured CI duration, and every CI wait bound derived from it (#559).
4
+ *
5
+ * Before this module every CI wait was a fleet-wide constant, and two of them disagreed: the skills
6
+ * passed `--timeout 15m` to `colab ci-wait` everywhere while its own default was 45 minutes, so a
7
+ * caller that omitted the flag silently waited three times as long. Repos' CI ranges from a few
8
+ * minutes to nearly half an hour, so one number was too long for a fast repo and too short for a
9
+ * slow one.
10
+ *
11
+ * The rule (epic #558): a threshold that depends on a repo's nature comes from THAT repo. Here the
12
+ * duration is MEASURED from the repo's own CI history; the only DECLARED part is the multiple of it
13
+ * a repo is willing to wait (`ci-wait-factor`, default 2). Where nothing has been measured yet, each
14
+ * bound is today's value exactly — documented as the bootstrap, never a different behaviour.
15
+ *
16
+ * Pure: run rows in, a profile and thresholds out — no git, no gh, no clock. `tools/colab` fetches
17
+ * (`fetchCiProfileRows`), caches (`ciProfileFor`) and prints (`cmdCiProfile`).
18
+ *
19
+ * What is measured, per sha: the wall time from the first run's creation to the last run's last
20
+ * update, across every run that verifies the code at that sha (verify-runs.js, the same set
21
+ * `ci-wait --sha` waits on). That is exactly the wait a session sits through: "every run at the sha
22
+ * has finished". Only clean first-attempt green shas count — a re-run measures an incident, a red
23
+ * run measures how fast it failed.
24
+ */
25
+
26
+ const ciWait = require('./ci-wait');
27
+ const ciVerdict = require('./ci-verdict');
28
+ const verifyRuns = require('./verify-runs');
29
+ const { quantile } = require('./batch-stats');
30
+
31
+ const FACTOR_KEY = 'ci-wait-factor';
32
+ const DEFAULT_FACTOR = 2;
33
+ /** A kind with fewer clean green shas than this in the window stays on its bootstrap value. */
34
+ const MIN_SAMPLES = 10;
35
+ const WINDOW_DAYS = 30;
36
+
37
+ /**
38
+ * The one platform constant: how long GitHub may take to start a run and materialize its job list
39
+ * (ci-verdict's zero-jobs floor). It floors every derived bound — a 20-second CI must not produce a
40
+ * wait shorter than the time a run can take to appear at all. Not repo-measurable at run-list cost:
41
+ * `run_started_at` equals `created_at` on every row we read, so the list carries no queue signal.
42
+ */
43
+ const PLATFORM_FLOOR_SEC = ciVerdict.ZERO_JOBS_AGE_FLOOR_MINUTES * 60;
44
+
45
+ /**
46
+ * Today's values, exactly — what a repo with no history gets, built from the constants that hold
47
+ * them rather than restated. The 6 h wedge age is also a CAP: it is the hosted-runner job limit, so
48
+ * measurement may only lower it (a safety limit a repo may only tighten, epic #558). Likewise the
49
+ * 30/60/120 s poll schedule is a REST-quota floor — measurement may only stretch it.
50
+ */
51
+ const BOOTSTRAP = Object.freeze({
52
+ branchWaitSec: 15 * 60,
53
+ trunkWaitSec: 15 * 60,
54
+ wedgeAgeSec: ciVerdict.WEDGE_AGE_HOURS * 3600,
55
+ emptyReadGraceSec: ciVerdict.EMPTY_READ_GRACE_MINUTES * 60,
56
+ zeroJobsFloorSec: PLATFORM_FLOOR_SEC,
57
+ scheduleSec: ciWait.DEFAULT_SCHEDULE_SEC,
58
+ });
59
+
60
+ /**
61
+ * `ci-wait-factor: <number ≥ 1>` — absent → 2. A malformed value falls back to the documented
62
+ * default (never to a different behaviour) and is reported; the audit fails it.
63
+ */
64
+ function parseFactor(doc) {
65
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, FACTOR_KEY) && doc[FACTOR_KEY] !== null && doc[FACTOR_KEY] !== undefined;
66
+ if (!has) return { value: DEFAULT_FACTOR, declared: false, valid: true, reason: `${FACTOR_KEY}: ${DEFAULT_FACTOR} (default)` };
67
+ const raw = doc[FACTOR_KEY];
68
+ const n = typeof raw === 'number' ? raw : (typeof raw === 'string' && /^\s*\d+(\.\d+)?\s*$/.test(raw) ? Number(raw) : NaN);
69
+ if (!Number.isFinite(n) || n < 1) {
70
+ return { value: DEFAULT_FACTOR, declared: true, valid: false,
71
+ reason: `${FACTOR_KEY} must be a number ≥ 1 (a multiple of the measured CI duration), got ${JSON.stringify(raw)} — using ${DEFAULT_FACTOR}` };
72
+ }
73
+ return { value: n, declared: true, valid: true, reason: `${FACTOR_KEY}: ${n}` };
74
+ }
75
+
76
+ /**
77
+ * Rows → one wall time per clean green sha. A row: `{ sha, branch, event, workflowName, status,
78
+ * conclusion, attempt, createdMs, updatedMs, headCommitMs }`.
79
+ *
80
+ * A branch group at a sha that is also a trunk sha is dropped: a branch cut moments ago re-runs
81
+ * trunk's content, and those near-instant runs would drag the branch duration down.
82
+ */
83
+ function shaDurations(rows, { trunk, policy = null } = {}) {
84
+ const groups = new Map();
85
+ for (const r of rows || []) {
86
+ if (!r || !r.sha || r.event === 'dynamic') continue;
87
+ const key = `${r.branch || ''}\u0000${r.sha}`;
88
+ if (!groups.has(key)) groups.set(key, []);
89
+ groups.get(key).push(r);
90
+ }
91
+ const trunkShas = new Set([...groups.values()].filter((g) => g[0].branch === trunk).map((g) => g[0].sha));
92
+ const out = [];
93
+ for (const g of groups.values()) {
94
+ const split = verifyRuns.splitVerifying(g, policy);
95
+ const counted = split ? split.counted : g;
96
+ if (!counted.length) continue;
97
+ if (!counted.every((r) => r.status === 'completed')) continue;
98
+ if (!counted.every((r) => ['success', 'skipped', 'neutral'].includes(r.conclusion))) continue;
99
+ if (!counted.some((r) => r.conclusion === 'success')) continue;
100
+ if (counted.some((r) => Number(r.attempt) > 1)) continue;
101
+ const created = Math.min(...counted.map((r) => r.createdMs));
102
+ const ended = Math.max(...counted.map((r) => r.updatedMs));
103
+ if (!Number.isFinite(created) || !Number.isFinite(ended) || ended < created) continue;
104
+ const kind = g[0].branch === trunk ? 'trunk' : 'branch';
105
+ if (kind === 'branch' && trunkShas.has(g[0].sha)) continue;
106
+ let lagSec = null;
107
+ if (kind === 'trunk') {
108
+ const c = Math.min(...counted.map((r) => r.headCommitMs).filter(Number.isFinite));
109
+ if (Number.isFinite(c) && created >= c) lagSec = Math.round((created - c) / 1000);
110
+ }
111
+ out.push({ sha: g[0].sha, kind, sec: Math.round((ended - created) / 1000), lagSec, endMs: ended });
112
+ }
113
+ return out;
114
+ }
115
+
116
+ function stats(values) {
117
+ const v = values.filter(Number.isFinite);
118
+ return {
119
+ source: v.length >= MIN_SAMPLES ? 'measured' : 'bootstrap',
120
+ samples: v.length,
121
+ p50Sec: quantile(v, 0.5),
122
+ p95Sec: quantile(v, 0.95),
123
+ maxSec: v.length ? Math.max(...v) : null,
124
+ };
125
+ }
126
+
127
+ /** Durations → `{ branch, trunk, lag, source }`; only samples ending at or after `sinceMs` count. */
128
+ function profile(durations, { sinceMs = null } = {}) {
129
+ const d = (durations || []).filter((x) => sinceMs === null || x.endMs >= sinceMs);
130
+ const branch = stats(d.filter((x) => x.kind === 'branch').map((x) => x.sec));
131
+ const trunk = stats(d.filter((x) => x.kind === 'trunk').map((x) => x.sec));
132
+ const lagV = d.filter((x) => x.kind === 'trunk' && x.lagSec !== null).map((x) => x.lagSec);
133
+ const lag = { source: lagV.length >= MIN_SAMPLES ? 'measured' : 'bootstrap', samples: lagV.length, p95Sec: quantile(lagV, 0.95) };
134
+ const n = [branch, trunk].filter((k) => k.source === 'measured').length;
135
+ return { branch, trunk, lag, source: n === 2 ? 'measured' : n === 0 ? 'bootstrap' : 'partial' };
136
+ }
137
+
138
+ const ceilMinute = (sec) => Math.ceil(sec / 60) * 60;
139
+
140
+ /** A kind's wait bound: GitHub must start the run, then `factor` times what it takes at p95. */
141
+ function boundFor(k, factor, bootstrapSec) {
142
+ if (!k || k.source !== 'measured' || !Number.isFinite(k.p95Sec)) return { sec: bootstrapSec, basis: 'bootstrap' };
143
+ return { sec: ceilMinute(PLATFORM_FLOOR_SEC + factor * k.p95Sec), basis: 'measured' };
144
+ }
145
+
146
+ /** The schedule for a bound: 30/60/120 s stretched in proportion to a bound past 15 min, never shrunk. */
147
+ function scheduleFor(boundSec) {
148
+ const k = Math.max(1, boundSec / BOOTSTRAP.branchWaitSec);
149
+ return BOOTSTRAP.scheduleSec.map((s) => Math.round(s * k));
150
+ }
151
+
152
+ /**
153
+ * Profile + factor → every threshold, each with the basis it came from. A null profile (nothing
154
+ * read, no cache) is the bootstrap in full.
155
+ */
156
+ function thresholds(prof, factor = DEFAULT_FACTOR) {
157
+ const f = Number.isFinite(factor) && factor >= 1 ? factor : DEFAULT_FACTOR;
158
+ const p = prof || {};
159
+ const branch = boundFor(p.branch, f, BOOTSTRAP.branchWaitSec);
160
+ const trunk = boundFor(p.trunk, f, BOOTSTRAP.trunkWaitSec);
161
+ const anyMeasured = branch.basis === 'measured' || trunk.basis === 'measured';
162
+ const wedgeAgeSec = anyMeasured ? Math.min(BOOTSTRAP.wedgeAgeSec, ceilMinute(f * Math.max(branch.sec, trunk.sec))) : BOOTSTRAP.wedgeAgeSec;
163
+ const lagMeasured = p.lag && p.lag.source === 'measured' && Number.isFinite(p.lag.p95Sec);
164
+ const emptyReadGraceSec = lagMeasured ? Math.max(PLATFORM_FLOOR_SEC, ceilMinute(f * p.lag.p95Sec)) : BOOTSTRAP.emptyReadGraceSec;
165
+ return {
166
+ factor: f,
167
+ branchWaitSec: branch.sec,
168
+ trunkWaitSec: trunk.sec,
169
+ ciWaitDefaultSec: { branch: branch.sec, trunk: trunk.sec, any: Math.max(branch.sec, trunk.sec) },
170
+ wedgeAgeSec,
171
+ emptyReadGraceSec,
172
+ zeroJobsFloorSec: BOOTSTRAP.zeroJobsFloorSec,
173
+ scheduleSec: { branch: scheduleFor(branch.sec), trunk: scheduleFor(trunk.sec), any: scheduleFor(Math.max(branch.sec, trunk.sec)) },
174
+ basis: {
175
+ branchWait: branch.basis,
176
+ trunkWait: trunk.basis,
177
+ wedgeAge: anyMeasured ? 'measured' : 'bootstrap',
178
+ emptyReadGrace: lagMeasured ? 'measured' : 'bootstrap',
179
+ zeroJobsFloor: 'default',
180
+ },
181
+ };
182
+ }
183
+
184
+ /** Which bound a wait uses: trunk when the target is trunk, branch for any other branch, else `any`. */
185
+ function kindFor({ branch = null, trunk = null, onTrunk = null } = {}) {
186
+ if (branch) return branch === trunk ? 'trunk' : 'branch';
187
+ if (onTrunk === true) return 'trunk';
188
+ if (onTrunk === false) return 'branch';
189
+ return 'any';
190
+ }
191
+
192
+ module.exports = {
193
+ FACTOR_KEY, DEFAULT_FACTOR, MIN_SAMPLES, WINDOW_DAYS, PLATFORM_FLOOR_SEC, BOOTSTRAP,
194
+ parseFactor, shaDurations, profile, thresholds, scheduleFor, kindFor,
195
+ };
@@ -72,24 +72,30 @@ function hoursSince(iso, nowMs) {
72
72
  function wedgedVerdict(run, opts = {}) {
73
73
  if (!run || run.status === 'completed' || run.status === 'none') return { wedged: false, reason: null };
74
74
  const age = hoursSince(run.createdAt, opts.nowMs);
75
+ // #559: both bounds may come from the repo's measured CI (tools/lib/ci-profile.js); absent → today's.
76
+ const floorMin = Number.isFinite(opts.zeroJobsFloorSec) ? opts.zeroJobsFloorSec / 60 : ZERO_JOBS_AGE_FLOOR_MINUTES;
77
+ const wedgeHours = Number.isFinite(opts.wedgeAgeSec) ? opts.wedgeAgeSec / 3600 : WEDGE_AGE_HOURS;
75
78
  if (run.jobCount === 0) {
76
79
  // #171: no createdAt (age unknown) never manufactures a positive here, same posture as the age
77
80
  // backstop below when createdAt is missing/unparseable — a missing signal must not wedge on its own.
78
- const floorHours = ZERO_JOBS_AGE_FLOOR_MINUTES / 60;
81
+ const floorHours = floorMin / 60;
79
82
  if (age !== null && age >= floorHours) {
80
83
  return {
81
84
  wedged: true,
82
- reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${ZERO_JOBS_AGE_FLOOR_MINUTES}m floor)`,
85
+ reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${fmtMin(floorMin)} floor)`,
83
86
  };
84
87
  }
85
88
  return { wedged: false, reason: null };
86
89
  }
87
- if (age !== null && age >= WEDGE_AGE_HOURS) {
88
- return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${WEDGE_AGE_HOURS}h backstop)` };
90
+ if (age !== null && age >= wedgeHours) {
91
+ return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${fmtHours(wedgeHours)} backstop)` };
89
92
  }
90
93
  return { wedged: false, reason: null };
91
94
  }
92
95
 
96
+ const fmtMin = (m) => `${Number.isInteger(m) ? m : m.toFixed(1)}m`;
97
+ const fmtHours = (h) => (Number.isInteger(h) ? `${h}h` : `${Math.round(h * 60)}m`);
98
+
93
99
  // #413: how long after a trunk commit "no run at this sha" is still the ordinary state. GitHub
94
100
  // creates a push run seconds after the push, but a ship reading trunk right after another ship
95
101
  // landed it can get there first. Ten minutes covers queueing on a busy account; past it, an empty
@@ -107,7 +113,9 @@ function emptyReadVerdict(committedAtMs, opts = {}) {
107
113
  if (committedAtMs == null || !Number.isFinite(committedAtMs)) return { fresh: false, minutes: null };
108
114
  const now = opts.nowMs != null ? opts.nowMs : Date.now();
109
115
  const minutes = (now - committedAtMs) / 60000;
110
- return { fresh: minutes >= 0 && minutes < EMPTY_READ_GRACE_MINUTES, minutes };
116
+ // #559: the grace may be the repo's measured push→run lag (tools/lib/ci-profile.js); absent → 10 min.
117
+ const graceMinutes = Number.isFinite(opts.graceSec) ? opts.graceSec / 60 : EMPTY_READ_GRACE_MINUTES;
118
+ return { fresh: minutes >= 0 && minutes < graceMinutes, minutes, graceMinutes };
111
119
  }
112
120
 
113
121
  module.exports = { WEDGE_AGE_HOURS, ZERO_JOBS_AGE_FLOOR_MINUTES, EMPTY_READ_GRACE_MINUTES, wedgedVerdict, emptyReadVerdict };
@@ -38,7 +38,10 @@ const EXIT = Object.freeze({
38
38
  });
39
39
 
40
40
  const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
41
- const DEFAULT_DEADLINE_SEC = 45 * 60;
41
+ // #559: the bootstrap deadline — the same 15 minutes every skill passed as `--timeout 15m`, so a caller
42
+ // that omits the flag no longer silently waits three times as long (it was 45 min). Once a repo has CI
43
+ // history, `colab ci-wait` derives its deadline from it instead (tools/lib/ci-profile.js).
44
+ const DEFAULT_DEADLINE_SEC = 15 * 60;
42
45
 
43
46
  /** Seconds to sleep before poll number `i` (0-based, i ≥ 1); the last step repeats. */
44
47
  function delayFor(i, schedule = DEFAULT_SCHEDULE_SEC) {
@@ -94,6 +97,8 @@ function restRow(x) {
94
97
  return {
95
98
  headSha: x.head_sha, status: x.status, conclusion: x.conclusion || null,
96
99
  createdAt: x.created_at || null, databaseId: x.id, workflowName: x.name || null,
100
+ // #555: a finished run's last update is its completion — when a lone batch member became ready.
101
+ updatedAt: x.updated_at || null,
97
102
  event: x.event || null, url: x.html_url || null,
98
103
  // #510: the workflow FILE's id — the cure rule's same-workflow test, which a display name cannot answer.
99
104
  workflowId: x.workflow_id ?? null,