@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.
- package/README.md +50 -20
- package/README.vi.md +53 -23
- package/audit/audit.mjs +116 -15
- package/package.json +1 -1
- package/templates/README.md +1 -1
- package/templates/ci-laravel.yml +72 -5
- package/templates/ci-node.yml +74 -6
- package/templates/ci-python.yml +74 -6
- package/templates/release-auto.yml +68 -4
- package/tools/colab +784 -91
- package/tools/lib/batch-history.js +104 -0
- package/tools/lib/batch-stats.js +277 -0
- package/tools/lib/ci-profile.js +195 -0
- package/tools/lib/ci-verdict.js +13 -5
- package/tools/lib/ci-wait.js +6 -1
- package/tools/lib/codec/claim.js +6 -3
- package/tools/lib/config-set.js +319 -0
- package/tools/lib/disposition.js +9 -6
- package/tools/lib/docs-only.js +1 -1
- package/tools/lib/engines.js +52 -0
- package/tools/lib/git.js +70 -15
- package/tools/lib/install-check.js +77 -5
- package/tools/lib/journal.js +3 -0
- package/tools/lib/notify-endpoint.js +114 -59
- package/tools/lib/notify.js +68 -22
- package/tools/lib/release-cut.js +39 -3
- package/tools/lib/release-finalize.js +110 -15
- package/tools/lib/release-policy.js +11 -3
- package/tools/lib/ship-batch.js +109 -2
- package/tools/lib/shipguard.js +12 -1
- package/tools/lib/thresholds.js +110 -0
- package/tools/lib/verify-runs.js +117 -4
|
@@ -39,6 +39,12 @@
|
|
|
39
39
|
* On a route whose final is a human act (`deploy-tag`) --auto never tags: it stops at
|
|
40
40
|
* candidate-ready and posts the one command, number pre-filled.
|
|
41
41
|
*
|
|
42
|
+
* `--tag` (#548) may name ANY open candidate, not only the newest, so a human can release what
|
|
43
|
+
* finished testing without trunk freezing for a whole period. An older one is held to the same rule
|
|
44
|
+
* --auto applies to it: its own test period and its own trunk window are required on every row
|
|
45
|
+
* (selectCandidate marks it `older`; decide() reads that). Newer candidates stay open, and a
|
|
46
|
+
* version's record closes as superseded only once a final ABOVE it is tagged.
|
|
47
|
+
*
|
|
42
48
|
* Before ANY final, the three #424 pre-tag checks (release-tag.js preTagChecks) are required:
|
|
43
49
|
* manifest-version, on-trunk, outranks-final.
|
|
44
50
|
*
|
|
@@ -71,7 +77,7 @@ const STATES = Object.freeze([
|
|
|
71
77
|
|
|
72
78
|
const CONDITIONS = Object.freeze([
|
|
73
79
|
'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
|
|
74
|
-
'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
|
|
80
|
+
'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
|
|
75
81
|
...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
|
|
76
82
|
]);
|
|
77
83
|
|
|
@@ -134,6 +140,8 @@ function trackingBody({ version, row, final, testPeriodDays }) {
|
|
|
134
140
|
* { kind: 'already-final', version, detail }
|
|
135
141
|
* { kind: 'refused', detail }
|
|
136
142
|
* { kind: 'candidate', candidate: { tag, version, n, sha, cutAt }, superseded: [version], detail }
|
|
143
|
+
* { kind: 'candidate', older: true, newest: <tag>, … } #548: `pin` names an open candidate that
|
|
144
|
+
* is not the newest — decide() then requires its own test period and trunk window, as --auto does
|
|
137
145
|
*/
|
|
138
146
|
function selectCandidate(tags, pin, remote = 'origin') {
|
|
139
147
|
const all = tags || [];
|
|
@@ -159,16 +167,32 @@ function selectCandidate(tags, pin, remote = 'origin') {
|
|
|
159
167
|
const newest = open[open.length - 1];
|
|
160
168
|
const superseded = [...new Set(open.map((x) => x.p.version).filter((v) => v !== newest.p.version))];
|
|
161
169
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
const
|
|
170
|
+
// #548: --tag may name an OLDER open candidate. It is then judged on its own clock, exactly as
|
|
171
|
+
// --auto judges it (decide() makes test-period and trunk-green over its own window required), so a
|
|
172
|
+
// human can release what finished testing while trunk keeps merging; the newer candidates stay open.
|
|
173
|
+
const chosen = pin ? open.find((x) => x.t.name === pin) : newest;
|
|
174
|
+
if (!chosen) return { kind: 'refused', detail: `--tag ${pin} is not an open candidate` };
|
|
175
|
+
const older = chosen !== newest;
|
|
176
|
+
const t = chosen.t;
|
|
166
177
|
if (!t.annotated || !String(t.subject || '').endsWith(CUT_SUBJECT_SUFFIX)) {
|
|
167
178
|
return { kind: 'refused', detail: `${t.name} was not made by \`colab release cut\` (not an annotated tag whose message ends "${CUT_SUBJECT_SUFFIX}") — a candidate cut by hand is never finalized (CONVENTIONS.md §6)` };
|
|
168
179
|
}
|
|
169
180
|
if (!t.onMain) return { kind: 'refused', detail: `${t.name} (${String(t.sha).slice(0, 7)}) is not on ${remote}/main — candidates are cut from main` };
|
|
170
181
|
if (!t.date || Number.isNaN(Date.parse(t.date))) return { kind: 'refused', detail: `${t.name} has no readable tagger date — the test period cannot be placed` };
|
|
171
182
|
|
|
183
|
+
if (older) {
|
|
184
|
+
// Only versions BELOW the pinned one are superseded by it; a newer version's candidates stay open.
|
|
185
|
+
const below = [...new Set(open.map((x) => x.p.version).filter((v) => compareVersions(v, chosen.p.version) < 0))];
|
|
186
|
+
const newer = open.filter((x) => compareVersions(x.p.version, chosen.p.version) > 0 || (x.p.version === chosen.p.version && x.p.n > chosen.p.n)).map((x) => x.t.name);
|
|
187
|
+
return {
|
|
188
|
+
kind: 'candidate',
|
|
189
|
+
older: true,
|
|
190
|
+
newest: newest.t.name,
|
|
191
|
+
candidate: { tag: t.name, version: chosen.p.version, n: chosen.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
|
|
192
|
+
superseded: below,
|
|
193
|
+
detail: `${t.name} at ${String(t.sha).slice(0, 7)}, cut ${new Date(t.date).toISOString()} — an older candidate, judged on its own clock (newer, still open: ${newer.join(', ')})${below.length ? `; supersedes ${below.join(', ')}` : ''}`,
|
|
194
|
+
};
|
|
195
|
+
}
|
|
172
196
|
return {
|
|
173
197
|
kind: 'candidate',
|
|
174
198
|
candidate: { tag: t.name, version: newest.p.version, n: newest.p.n, sha: t.sha, cutAt: new Date(t.date).toISOString() },
|
|
@@ -295,9 +319,72 @@ function whyNoFinal({ state, candidate, checks, period, skipped, now } = {}) {
|
|
|
295
319
|
return { line, next };
|
|
296
320
|
}
|
|
297
321
|
|
|
322
|
+
// ---- the run that cut the candidate (#566) ------------------------------------------------------
|
|
323
|
+
|
|
324
|
+
// Slack around the tag's cut instant: the tagger date is the runner's clock, a run's createdAt /
|
|
325
|
+
// updatedAt are GitHub's, both to the second.
|
|
326
|
+
const CUT_RUN_SLACK_MS = 120000;
|
|
327
|
+
|
|
328
|
+
/**
|
|
329
|
+
* Did the run that CUT this candidate finish what it does after the cut? `rows` are the workflow
|
|
330
|
+
* runs at the candidate's commit (`git.ghRunsAtCommit`, null = unread), WITHOUT the #425 own-workflow
|
|
331
|
+
* filter — the release workflow is exactly the one this reads; only the calling run itself is dropped
|
|
332
|
+
* (`ownRunId`), since a run cannot vouch for or against itself while it is still running.
|
|
333
|
+
*
|
|
334
|
+
* The cutter is every run that was in progress at `cutAt` (the annotated tag's date): created no later
|
|
335
|
+
* than the cut, and either not finished or finished no earlier than it. Each one must have concluded
|
|
336
|
+
* `success`. Measured (#566): the run that cut a candidate had its image-publish job CANCELLED; ci-green
|
|
337
|
+
* and full-suite set that run aside as superseded (#461 — a cancelled run never stands for its workflow
|
|
338
|
+
* while that workflow has any other run at the sha) and counted an EARLIER run of the same workflow at
|
|
339
|
+
* the same commit that concluded success having cut nothing. finalize said candidate-ready for a
|
|
340
|
+
* candidate whose image did not exist. Here only the cutter vouches, and cancelled is a failure: a run
|
|
341
|
+
* cancelled after its cut may have stopped before its publish.
|
|
342
|
+
*
|
|
343
|
+
* A CANCELLED row whose job count `jobCount(databaseId)` reads 0 never ran — the measured shape of a
|
|
344
|
+
* pending run GitHub cancelled out of the release workflow's concurrency group when a newer one queued —
|
|
345
|
+
* so it cut nothing and is dropped. Asked lazily, only for a cancelled row; null (unread) keeps it.
|
|
346
|
+
*
|
|
347
|
+
* No run in progress at the cut → ok: the candidate was cut by hand (`colab release cut` outside a
|
|
348
|
+
* workflow), and no run owes it anything. A completed row with no `updatedAt` (an older read) cannot
|
|
349
|
+
* be placed around the cut and is not counted — absence of the field never refuses.
|
|
350
|
+
*
|
|
351
|
+
* Returns { ok, detail, runs } — `runs` the cutter rows' ids, for the report.
|
|
352
|
+
*/
|
|
353
|
+
function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } = {}) {
|
|
354
|
+
if (rows === null || rows === undefined) return { ok: false, detail: `the workflow runs at ${tag} could not be read — the run that cut it cannot be checked`, runs: [] };
|
|
355
|
+
const cut = Date.parse(cutAt);
|
|
356
|
+
if (Number.isNaN(cut)) return { ok: false, detail: `${tag} carries no readable cut time — the run that cut it cannot be found`, runs: [] };
|
|
357
|
+
const own = ownRunId === null || ownRunId === undefined || ownRunId === '' ? null : String(ownRunId);
|
|
358
|
+
const cutters = rows.filter((r) => {
|
|
359
|
+
if (!r || (own && String(r.databaseId) === own)) return false;
|
|
360
|
+
const created = Date.parse(r.createdAt);
|
|
361
|
+
if (Number.isNaN(created) || created > cut + CUT_RUN_SLACK_MS) return false;
|
|
362
|
+
if (r.status !== 'completed') return true;
|
|
363
|
+
const ended = Date.parse(r.updatedAt);
|
|
364
|
+
if (Number.isNaN(ended) || ended < cut - CUT_RUN_SLACK_MS) return false;
|
|
365
|
+
if (r.conclusion === 'cancelled' && typeof jobCount === 'function' && r.databaseId != null && jobCount(r.databaseId) === 0) return false;
|
|
366
|
+
return true;
|
|
367
|
+
});
|
|
368
|
+
const ids = cutters.map((r) => r.databaseId).filter((x) => x !== null && x !== undefined);
|
|
369
|
+
const name = (r) => `${r.workflowName || '(unnamed workflow)'} run ${r.databaseId != null ? r.databaseId : '(id unread)'}`;
|
|
370
|
+
if (!cutters.length) return { ok: true, detail: `no workflow run at ${tag} was in progress when it was cut (${cutAt}) — cut by hand, no run's publish to wait for`, runs: [] };
|
|
371
|
+
const bad = cutters.filter((r) => !(r.status === 'completed' && r.conclusion === 'success'));
|
|
372
|
+
if (!bad.length) return { ok: true, detail: `the run that cut ${tag} (${cutters.map(name).join(', ')}) concluded success`, runs: ids };
|
|
373
|
+
const how = (r) => (r.status === 'completed' ? `concluded ${r.conclusion || 'with no conclusion'}` : `is still ${r.status || 'running'}`);
|
|
374
|
+
const rerun = bad.filter((r) => r.status === 'completed' && r.databaseId != null).map((r) => `gh run rerun ${r.databaseId} --failed`);
|
|
375
|
+
return {
|
|
376
|
+
ok: false,
|
|
377
|
+
detail: `the run that cut ${tag} — ${bad.map((r) => `${name(r)} ${how(r)}`).join('; ')} — did not finish what it publishes after the cut (an image, a package, a Release): ${tag}'s artifacts may not exist. An earlier green run at the same commit that cut nothing cannot vouch for it (#566). ${rerun.length ? `Re-run it (${rerun.join('; ')}) and finalize again, or cut a new candidate.` : 'Wait for it to finish, then finalize again.'}`,
|
|
378
|
+
runs: ids,
|
|
379
|
+
};
|
|
380
|
+
}
|
|
381
|
+
|
|
298
382
|
// ---- the test period ----------------------------------------------------------------------------
|
|
299
383
|
|
|
300
|
-
/**
|
|
384
|
+
/**
|
|
385
|
+
* { start, endsAt, days, elapsed, detail } — start = max(cutAt, trackingCreatedAt), ISO strings. `days` 0
|
|
386
|
+
* (#549, human final only) is no test period: elapsed at once, and the detail says so.
|
|
387
|
+
*/
|
|
301
388
|
function periodVerdict({ cutAt, trackingCreatedAt, testPeriodDays, now }) {
|
|
302
389
|
const cut = Date.parse(cutAt);
|
|
303
390
|
const created = trackingCreatedAt ? Date.parse(trackingCreatedAt) : NaN;
|
|
@@ -310,8 +397,11 @@ function periodVerdict({ cutAt, trackingCreatedAt, testPeriodDays, now }) {
|
|
|
310
397
|
return {
|
|
311
398
|
start: new Date(startMs).toISOString(),
|
|
312
399
|
endsAt: new Date(endMs).toISOString(),
|
|
400
|
+
days: testPeriodDays,
|
|
313
401
|
elapsed,
|
|
314
|
-
detail:
|
|
402
|
+
detail: testPeriodDays === 0
|
|
403
|
+
? 'no test period (release.test-period: 0d, a human final — the human\'s finalize is the test, #549)'
|
|
404
|
+
: elapsed
|
|
315
405
|
? `${testPeriodDays}d test period from ${new Date(startMs).toISOString()} ended ${new Date(endMs).toISOString()}`
|
|
316
406
|
: `${testPeriodDays}d test period from ${new Date(startMs).toISOString()} ends ${new Date(endMs).toISOString()} (${hours}h left)`,
|
|
317
407
|
};
|
|
@@ -450,6 +540,7 @@ function handoffCommand(tag) {
|
|
|
450
540
|
* trunk trunkGreenVerdict(...)
|
|
451
541
|
* regressions regressionVerdict(...)
|
|
452
542
|
* ci, suite, schema, switches { ok, detail }
|
|
543
|
+
* cutRun #566 — cutRunVerdict(): the run that cut the candidate concluded success
|
|
453
544
|
* finalGrant #441 — release-policy.js finalGrantVerdict() of policy.effective.finalGrant (only
|
|
454
545
|
* read when the policy carries one; absent = unresolved, never a grant)
|
|
455
546
|
* migrations #441 — migrationGrantVerdict() (only read when the policy carries a grant)
|
|
@@ -517,11 +608,15 @@ function decide(facts) {
|
|
|
517
608
|
}
|
|
518
609
|
const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
|
|
519
610
|
add('regressions', reg.ok, reg.detail);
|
|
611
|
+
// #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
|
|
612
|
+
// --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
|
|
613
|
+
// no longer explains why THIS one, and its own clean period is what does.
|
|
614
|
+
const ownClock = auto || !!s.older;
|
|
520
615
|
const per = f.period || { elapsed: false, detail: 'not measured' };
|
|
521
|
-
add('test-period', per.elapsed, per.detail,
|
|
616
|
+
add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
|
|
522
617
|
const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
|
|
523
|
-
add('trunk-green', tr.ok, tr.detail,
|
|
524
|
-
for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
618
|
+
add('trunk-green', tr.ok, tr.detail, ownClock);
|
|
619
|
+
for (const [condition, v] of [['ci-green', f.ci], ['full-suite', f.suite], ['cut-run', f.cutRun], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
525
620
|
add(condition, v && v.ok, v ? v.detail : 'not measured');
|
|
526
621
|
}
|
|
527
622
|
// #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
|
|
@@ -533,14 +628,14 @@ function decide(facts) {
|
|
|
533
628
|
}
|
|
534
629
|
|
|
535
630
|
if (held.length) return out('held');
|
|
536
|
-
if ((reg.permanent) || (
|
|
631
|
+
if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
|
|
537
632
|
const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition));
|
|
538
633
|
if (blocking.length) return out('refused');
|
|
539
|
-
if (
|
|
634
|
+
if (ownClock) {
|
|
540
635
|
if (!tr.ok && !tr.pending) return out('refused');
|
|
541
636
|
if (!per.elapsed || tr.pending) return out('testing');
|
|
542
|
-
return out('finalized', { finalTag: cand.version, grant: grantUsed });
|
|
543
637
|
}
|
|
638
|
+
if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
|
|
544
639
|
if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
|
|
545
640
|
return out('finalized', { finalTag: cand.version });
|
|
546
641
|
}
|
|
@@ -590,7 +685,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
|
|
|
590
685
|
'',
|
|
591
686
|
`Candidate: ${candidate.tag}`,
|
|
592
687
|
`Commit: ${candidate.sha}`,
|
|
593
|
-
period ? `Test period: ${period.start} -> ${period.endsAt}` : null,
|
|
688
|
+
period ? (period.days === 0 ? 'Test period: none (release.test-period: 0d — the human final is the test)' : `Test period: ${period.start} -> ${period.endsAt}`) : null,
|
|
594
689
|
`Finalized by: ${actor}`,
|
|
595
690
|
verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
|
|
596
691
|
'',
|
|
@@ -603,7 +698,7 @@ module.exports = {
|
|
|
603
698
|
STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
|
|
604
699
|
parseVersion, compareVersions, parseCandidate,
|
|
605
700
|
parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
|
|
606
|
-
selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
701
|
+
selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
607
702
|
handoffCommand, decide, tagMessage, migrationGrantVerdict,
|
|
608
703
|
carriedIssues, previousFinal, releasedEvent, releasedComment,
|
|
609
704
|
};
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
* route: public-tool # none | rapid-app | public-tool | library-fast | deploy-tag | deploy-tag-fast | live
|
|
12
12
|
* candidates: auto # auto | off
|
|
13
13
|
* candidates-per-day: 1 # positive integer — an opt-in cap; no route has one by default (#443)
|
|
14
|
-
* test-period: 3d # <N>d, never below the route's 3 days
|
|
14
|
+
* test-period: 3d # <N>d, never below the route's 3 days — or 0d where the final is human (#549)
|
|
15
15
|
* final: auto # auto | human
|
|
16
16
|
* guard-run: <command> # #422 — a breaking-change detector `release cut --auto` runs
|
|
17
17
|
* guard-result: <path> # #422 — or the file an earlier CI step wrote its result to
|
|
@@ -95,6 +95,8 @@ const FINAL = Object.freeze(['auto', 'human']);
|
|
|
95
95
|
// The routes' own test period (CONVENTIONS.md §6: "The test period is 3 days"). A floor, not a
|
|
96
96
|
// suggestion: a declared period may be longer, never shorter.
|
|
97
97
|
const TEST_PERIOD_DAYS = 3;
|
|
98
|
+
// #549: the one value below the floor — no test period at all, and only where the final is human.
|
|
99
|
+
const TEST_PERIOD_ZERO = '0d';
|
|
98
100
|
|
|
99
101
|
/**
|
|
100
102
|
* Each route's own policy — CONVENTIONS.md §6, *Release routes*, row for row.
|
|
@@ -369,8 +371,14 @@ function evaluateRelease(cfg) {
|
|
|
369
371
|
const days = parseTestPeriod(v);
|
|
370
372
|
if (days === null) fail(`release.test-period is ${JSON.stringify(v)}, expected a whole number of days like "${TEST_PERIOD_DAYS}d"`);
|
|
371
373
|
else if (effective.testPeriodDays === null) fail(`release.test-period: ${v} has no period to set — ${route} cuts no candidate, so there is no test period. Remove the key`);
|
|
372
|
-
else if (days
|
|
373
|
-
|
|
374
|
+
else if (days === 0 && effective.final === 'human') {
|
|
375
|
+
// #549: a human final may declare no test period — the human's finalize is the test.
|
|
376
|
+
effective.testPeriodDays = 0;
|
|
377
|
+
} else if (days === 0) {
|
|
378
|
+
widen('test-period', v, `the final is automatic here, so the test period is the only look a candidate gets before it becomes a release — no human looked. ${TEST_PERIOD_ZERO} fits only a human final (final: human). Set ${effective.testPeriodDays}d or longer`);
|
|
379
|
+
} else if (days < effective.testPeriodDays) {
|
|
380
|
+
widen('test-period', v, `the test period is ${effective.testPeriodDays}d, and a shorter one finalizes a candidate before the route's own window has passed. Set ${effective.testPeriodDays}d or longer` +
|
|
381
|
+
(effective.final === 'human' ? ` — or ${TEST_PERIOD_ZERO} for no test period, since the final here is a human act` : ''));
|
|
374
382
|
} else effective.testPeriodDays = days;
|
|
375
383
|
}
|
|
376
384
|
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -46,6 +46,70 @@ function parseShipBatch(doc) {
|
|
|
46
46
|
return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
|
|
47
47
|
}
|
|
48
48
|
|
|
49
|
+
const WAIT_KEY = 'ship-batch-wait';
|
|
50
|
+
const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* #555: `ship-batch-wait:` from project.yml — how long a LONE ready candidate waits for a partner
|
|
54
|
+
* before it lands alone. A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
|
|
55
|
+
* bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
|
|
56
|
+
*
|
|
57
|
+
* Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
|
|
58
|
+
* (owner, 2026-10-07: "Should not set any hard code number") — the repo chooses, from its own
|
|
59
|
+
* history. Anything malformed FAILS CLOSED to no wait, with the reason: a bad value must never delay
|
|
60
|
+
* a landing. The audit and the CI templates' descriptor check fail the same values.
|
|
61
|
+
*/
|
|
62
|
+
function parseShipBatchWait(doc) {
|
|
63
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, WAIT_KEY);
|
|
64
|
+
if (!has || doc[WAIT_KEY] === null || doc[WAIT_KEY] === undefined) {
|
|
65
|
+
return { sec: 0, declared: false, valid: true, reason: `${WAIT_KEY} absent` };
|
|
66
|
+
}
|
|
67
|
+
const v = doc[WAIT_KEY];
|
|
68
|
+
const m = typeof v === 'string' ? /^(\d+)([smh])$/.exec(v.trim()) : null;
|
|
69
|
+
if (m) {
|
|
70
|
+
const sec = Number(m[1]) * WAIT_UNITS[m[2]];
|
|
71
|
+
if (Number.isSafeInteger(sec)) return { sec, declared: true, valid: true, reason: `${WAIT_KEY}: ${v.trim()}` };
|
|
72
|
+
}
|
|
73
|
+
return { sec: 0, declared: true, valid: false, reason: `${WAIT_KEY} is ${JSON.stringify(v)}, expected a whole number with a unit — 90s, 6m, 1h (omit for no wait)` };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* #555: does a batch call with ONE eligible member wait for a partner, or let it go serial now?
|
|
78
|
+
* Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
|
|
79
|
+
* already in flight — the lane is otherwise idle by then):
|
|
80
|
+
* n parseShipBatch(doc).n
|
|
81
|
+
* waitSec parseShipBatchWait(doc).sec (0 = absent, zero, or malformed)
|
|
82
|
+
* eligibleCount members that passed their own gates
|
|
83
|
+
* readySinceMs when the lone member became ready — its head CI's last update, else its head
|
|
84
|
+
* commit's date; null = unreadable
|
|
85
|
+
* nowMs the clock
|
|
86
|
+
* Out: `{ wait: true, leftSec }` or `{ wait: false, reason }`. The window is counted from the member's
|
|
87
|
+
* own ready time, not from this call, so the command stays stateless and re-entrant: every call
|
|
88
|
+
* re-derives how much is left, on any machine, and the window can never restart.
|
|
89
|
+
*/
|
|
90
|
+
function partnerWait({ n, waitSec, eligibleCount, readySinceMs, nowMs }) {
|
|
91
|
+
if (!(n > 1)) return { wait: false, reason: 'not-enabled' };
|
|
92
|
+
if (!(waitSec > 0)) return { wait: false, reason: 'no-window' };
|
|
93
|
+
if (eligibleCount !== 1) return { wait: false, reason: eligibleCount > 1 ? 'has-partner' : 'none-ready' };
|
|
94
|
+
if (!Number.isFinite(readySinceMs) || !Number.isFinite(nowMs)) return { wait: false, reason: 'ready-time-unread' };
|
|
95
|
+
const leftSec = Math.ceil(waitSec - Math.max(0, nowMs - readySinceMs) / 1000);
|
|
96
|
+
if (leftSec <= 0) return { wait: false, reason: 'window-elapsed' };
|
|
97
|
+
return { wait: true, leftSec };
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* When did a member become ready? The newest `updatedAt` among its finished head runs (a run's last
|
|
102
|
+
* update is its completion), else — no run, because none can arrive — its head commit's date.
|
|
103
|
+
* Null when neither reads; the caller then does not wait.
|
|
104
|
+
*/
|
|
105
|
+
function readySince(rows, commitIso) {
|
|
106
|
+
const done = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
|
|
107
|
+
.map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
|
|
108
|
+
if (done.length) return Math.max(...done);
|
|
109
|
+
const c = Date.parse(commitIso || '');
|
|
110
|
+
return Number.isFinite(c) ? c : null;
|
|
111
|
+
}
|
|
112
|
+
|
|
49
113
|
function batchRefName(baseSha) {
|
|
50
114
|
return `${REF_PREFIX}${String(baseSha || '').slice(0, 7)}`;
|
|
51
115
|
}
|
|
@@ -77,6 +141,48 @@ function parseMemberTrailers(messages) {
|
|
|
77
141
|
return out;
|
|
78
142
|
}
|
|
79
143
|
|
|
144
|
+
/**
|
|
145
|
+
* #554: a member dropped at build used to leave no trace in git — only a `✗ <member>: …` line on
|
|
146
|
+
* one terminal — so eviction rate could not be measured. The batch head now records each drop:
|
|
147
|
+
*
|
|
148
|
+
* Ship-Batch-Dropped: <ref> <branch>@<sha> <class>
|
|
149
|
+
*
|
|
150
|
+
* appended to the LAST built member's message (the head commit), so it reaches trunk with a landed
|
|
151
|
+
* batch and rides the head commit's message of a combined run that went red. `class` is one token
|
|
152
|
+
* from DROP_CLASSES; the human reason stays on the terminal. A branch (already pushed, so already
|
|
153
|
+
* public) and a sha, never a host — the same rule as memberTrailer.
|
|
154
|
+
*/
|
|
155
|
+
const DROP_TRAILER_KEY = 'Ship-Batch-Dropped';
|
|
156
|
+
const DROP_CLASSES = ['conflict', 'generated-no-hook', 'hook-failed', 'hook-markers', 'squash-failed', 'empty', 'message', 'commit-failed'];
|
|
157
|
+
|
|
158
|
+
function droppedTrailer({ ref, branch, sha, cls }) {
|
|
159
|
+
const c = DROP_CLASSES.includes(cls) ? cls : 'other';
|
|
160
|
+
return `${DROP_TRAILER_KEY}: ${ref} ${branch}@${String(sha || '').slice(0, 12)} ${c}`;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** Every `Ship-Batch-Dropped:` trailer across commit messages → [{ ref, branch, sha, cls }]. */
|
|
164
|
+
function parseDroppedTrailers(messages) {
|
|
165
|
+
const out = [];
|
|
166
|
+
for (const msg of messages || []) {
|
|
167
|
+
for (const line of String(msg || '').split('\n')) {
|
|
168
|
+
const m = new RegExp(`^${DROP_TRAILER_KEY}:\\s+(\\S+)\\s+(\\S+)@([0-9a-f]{7,40})\\s+([a-z-]+)\\s*$`).exec(line.trim());
|
|
169
|
+
if (m) out.push({ ref: m[1], branch: m[2], sha: m[3], cls: m[4] });
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
return out;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* `msg` with `lines` appended to its final trailer block — never as a new paragraph, which would
|
|
177
|
+
* split the block and hide the earlier trailers from `git interpret-trailers`. Lines already
|
|
178
|
+
* present are not repeated (a rebuild re-composes the same message).
|
|
179
|
+
*/
|
|
180
|
+
function appendTrailers(msg, lines) {
|
|
181
|
+
const body = String(msg || '').replace(/\s+$/, '');
|
|
182
|
+
const add = (lines || []).filter((l) => l && !body.split('\n').includes(l));
|
|
183
|
+
return add.length ? `${body}\n${add.join('\n')}\n` : `${body}\n`;
|
|
184
|
+
}
|
|
185
|
+
|
|
80
186
|
/**
|
|
81
187
|
* A member's OWN head CI, read as a joining class (§4 Branch CI):
|
|
82
188
|
* green every run at its head finished, all success
|
|
@@ -315,8 +421,9 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
|
|
|
315
421
|
}
|
|
316
422
|
|
|
317
423
|
module.exports = {
|
|
318
|
-
MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
|
|
319
|
-
parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
|
|
424
|
+
MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
|
|
425
|
+
parseShipBatch, parseShipBatchWait, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
|
|
426
|
+
droppedTrailer, parseDroppedTrailers, appendTrailers,
|
|
320
427
|
branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
|
|
321
428
|
batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
|
|
322
429
|
};
|
package/tools/lib/shipguard.js
CHANGED
|
@@ -190,10 +190,21 @@ function bodyShaClaims(message) {
|
|
|
190
190
|
* an issue that carries no delivery-type label is still covered.
|
|
191
191
|
*/
|
|
192
192
|
const TOOL_MARKS = ['🔒 Claimed', '✅ Released', '🚢 Shipped', '🔖 Referenced', '↩️ Sent back'];
|
|
193
|
+
/**
|
|
194
|
+
* #535: a comment whose WHOLE body is one signature line (`— <name> · <machine>/<session>`) is
|
|
195
|
+
* not evidence either. Some deployments post one after every comment; it records who spoke, never
|
|
196
|
+
* what was delivered. Only the bare line is excluded — a distill that merely ENDS in a signature
|
|
197
|
+
* still counts, so the test is on the whole trimmed body, single line, no `m` flag.
|
|
198
|
+
*/
|
|
199
|
+
const SIGNATURE_ONLY = /^—[^\S\n][^\n]*\S$/;
|
|
200
|
+
function isSignatureOnly(body) {
|
|
201
|
+
return SIGNATURE_ONLY.test(body);
|
|
202
|
+
}
|
|
193
203
|
function evidenceComments(comments) {
|
|
194
204
|
return (Array.isArray(comments) ? comments : []).filter((c) => {
|
|
195
205
|
const body = String((c && c.body) || '').trim();
|
|
196
206
|
if (!body) return false;
|
|
207
|
+
if (isSignatureOnly(body)) return false;
|
|
197
208
|
return !TOOL_MARKS.some((mark) => body.startsWith(mark));
|
|
198
209
|
});
|
|
199
210
|
}
|
|
@@ -312,6 +323,6 @@ function zeroClaimVerdict(issuesCount, branchName, brokenClaimsCount, { remoteOn
|
|
|
312
323
|
|
|
313
324
|
module.exports = {
|
|
314
325
|
branchIssueNumbers, commitIssueNumbers, corroborateIssues, branchType,
|
|
315
|
-
subjectSanity, bodyShaClaims, evidenceComments, hasEvidence, TOOL_MARKS,
|
|
326
|
+
subjectSanity, bodyShaClaims, evidenceComments, hasEvidence, isSignatureOnly, TOOL_MARKS,
|
|
316
327
|
closesCoverage, zeroClaimVerdict,
|
|
317
328
|
};
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/thresholds.js — repo-declared values for the ADVISORY thresholds (#560, epic #558).
|
|
4
|
+
*
|
|
5
|
+
* Before this module each of these numbers was one fleet-wide constant, written into a skill's
|
|
6
|
+
* prose or a tool's source. The ruling on #560: today's value stays as the documented default, and
|
|
7
|
+
* a repo may override it in `.github/project.yml`:
|
|
8
|
+
*
|
|
9
|
+
* thresholds:
|
|
10
|
+
* hot-file-count: 4
|
|
11
|
+
* hold-stale-days: 45
|
|
12
|
+
*
|
|
13
|
+
* Nothing changes for a repo that declares nothing. Only ADVISORY thresholds live here — a number
|
|
14
|
+
* that decides what gets flagged, ranked or warned about. Safety limits (a cap a repo may only
|
|
15
|
+
* tighten) and protocol counts are out of scope (epic #558) and keep their own fields.
|
|
16
|
+
*
|
|
17
|
+
* Every value is a whole number with a per-key floor (and, for a percent, a ceiling of 100), and the
|
|
18
|
+
* unit is in the key's name. That keeps the CI templates' shell copy of this rule (the descriptor
|
|
19
|
+
* check, #416) small enough to be held to this table by tools/lib/ci-template-descriptor-check.test.js.
|
|
20
|
+
*
|
|
21
|
+
* NO-DEFAULT keys (#556): `def: null`. The batch-history judgement has no fleet-wide number to fall
|
|
22
|
+
* back on — the owner's ruling is that none be hard-coded — so an undeclared one means "do not judge":
|
|
23
|
+
* its value is null, and its reader shows the measurement without an advisory.
|
|
24
|
+
*
|
|
25
|
+
* A malformed value — a typo'd key, a non-number, a number under the floor — falls back to the
|
|
26
|
+
* default and is reported; the audit and the descriptor check fail it. A typo'd key is a problem,
|
|
27
|
+
* not an ignored extra: silently reverting to the default is exactly the failure #416 measured.
|
|
28
|
+
*
|
|
29
|
+
* Pure: a parsed descriptor in, values out. Both YAML readers feed it — the CLI's (numbers come
|
|
30
|
+
* through as numbers) and the audit's (they come through as digit strings) — so it accepts both.
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
const KEY = 'thresholds';
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* key → { def, min, max?, what, where }. `where` names the one place that reads the value. `def: null`
|
|
37
|
+
* = no default (#556): undeclared means its reader does not judge. `max` absent = MAX_VALUE.
|
|
38
|
+
* Order is the order `colab thresholds` prints.
|
|
39
|
+
*/
|
|
40
|
+
const SPEC = Object.freeze({
|
|
41
|
+
'hot-file-count': { def: 3, min: 2, what: 'waiting issues on one path before triage files HOT FILE', where: 'skills/code-triage/3-hot-file.md' },
|
|
42
|
+
'dependents-count': { def: 3, min: 1, what: 'open issues blocked_by one issue before triage ranks it as leverage', where: 'skills/code-triage/4-order.md' },
|
|
43
|
+
'hold-stale-days': { def: 30, min: 1, what: 'days a hold\'s wake condition may stand unmoved before a human confirms it', where: 'tools/lib/disposition.js' },
|
|
44
|
+
'smoke-minutes': { def: 3, min: 1, what: 'target run time of gate.smoke', where: 'skills/code-wrap/SKILL.md' },
|
|
45
|
+
'claude-md-kb': { def: 40, min: 1, what: 'authored KB of CLAUDE.md plus its @-imports before the audit warns', where: 'audit/audit.mjs' },
|
|
46
|
+
'claude-md-line-multiple': { def: 6, min: 2, what: 'longest line as a multiple of the file\'s median line before the audit warns', where: 'audit/audit.mjs' },
|
|
47
|
+
'claude-md-line-floor-bytes': { def: 2048, min: 0, what: 'a line under this many bytes is never flagged on the multiple alone', where: 'audit/audit.mjs' },
|
|
48
|
+
'transitional-days': { def: 180, min: 1, what: 'days a transitional descriptor value holds before the audit says how long', where: 'audit/audit.mjs' },
|
|
49
|
+
'doc-budget-slack': { def: 100, min: 0, what: 'lines under a doc budget before check-doc-budget asks to lower it', where: 'scripts/check-doc-budget.mjs' },
|
|
50
|
+
// #556 — the audit's batch-history advisories (tools/lib/batch-history.js). No defaults, by ruling.
|
|
51
|
+
'batch-min-samples': { def: null, min: 1, what: 'measured events a batch rate needs before the audit judges it (undeclared: any)', where: 'audit/audit.mjs --batch-history' },
|
|
52
|
+
'batch-first-green-pct-min': { def: null, min: 0, max: 100, what: 'first-attempt green % of combined runs below which the audit suggests lowering ship-batch', where: 'audit/audit.mjs --batch-history' },
|
|
53
|
+
'batch-eviction-pct-max': { def: null, min: 0, max: 100, what: '% of batch members dropped at build above which the audit flags eviction', where: 'audit/audit.mjs --batch-history' },
|
|
54
|
+
'batch-overlap-pct': { def: null, min: 0, max: 100, what: '% of serial landings with a missed or near-miss partner at which the audit suggests opting in to ship-batch', where: 'audit/audit.mjs --batch-history' },
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
const DEFAULTS = Object.freeze(Object.fromEntries(Object.entries(SPEC).map(([k, s]) => [k, s.def])));
|
|
58
|
+
|
|
59
|
+
/** At most nine digits — the CI templates' shell check compares with `[ -ge ]`, which must not overflow. */
|
|
60
|
+
const MAX_VALUE = 999999999;
|
|
61
|
+
|
|
62
|
+
function wholeNumber(raw) {
|
|
63
|
+
if (typeof raw === 'number') return Number.isInteger(raw) && raw <= MAX_VALUE ? raw : NaN;
|
|
64
|
+
if (typeof raw === 'string' && /^\s*[0-9]{1,9}\s*$/.test(raw)) return Number(raw);
|
|
65
|
+
return NaN;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* `doc` → `{ values, declared, problems }`. `values` always carries every key (the default where
|
|
70
|
+
* nothing valid was declared — null for a no-default key); `declared` names the keys whose declared value is in force;
|
|
71
|
+
* `problems` is one sentence per malformed entry, each ending with the default it fell back to.
|
|
72
|
+
*/
|
|
73
|
+
function parseThresholds(doc) {
|
|
74
|
+
const values = Object.assign({}, DEFAULTS);
|
|
75
|
+
const declared = {};
|
|
76
|
+
const problems = [];
|
|
77
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, KEY);
|
|
78
|
+
const raw = has ? doc[KEY] : undefined;
|
|
79
|
+
if (raw === undefined || raw === null || raw === '') return { values, declared, problems };
|
|
80
|
+
if (typeof raw !== 'object' || Array.isArray(raw)) {
|
|
81
|
+
problems.push(`${KEY} must be a map of "name: whole number" pairs, got ${JSON.stringify(raw)} — every threshold keeps its default`);
|
|
82
|
+
return { values, declared, problems };
|
|
83
|
+
}
|
|
84
|
+
for (const [k, v] of Object.entries(raw)) {
|
|
85
|
+
const spec = SPEC[k];
|
|
86
|
+
if (!spec) {
|
|
87
|
+
problems.push(`${KEY}.${k} is not a known threshold (known: ${Object.keys(SPEC).join(', ')}) — ignored`);
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
if (v === null || v === undefined || v === '') continue; // an empty entry declares nothing
|
|
91
|
+
const n = wholeNumber(v);
|
|
92
|
+
const max = spec.max === undefined ? MAX_VALUE : spec.max;
|
|
93
|
+
if (!Number.isFinite(n) || n < spec.min || n > max) {
|
|
94
|
+
const range = spec.max === undefined ? `≥ ${spec.min}` : `${spec.min}–${spec.max}`;
|
|
95
|
+
problems.push(`${KEY}.${k} must be a whole number ${range}, got ${JSON.stringify(v)} — ${spec.def === null ? 'not declared, so not judged' : `using the default ${spec.def}`}`);
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
values[k] = n;
|
|
99
|
+
declared[k] = true;
|
|
100
|
+
}
|
|
101
|
+
return { values, declared, problems };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** The resolved value of one key — the convenience a single consumer wants. Null = undeclared, no default. */
|
|
105
|
+
function thresholdValue(doc, key) {
|
|
106
|
+
if (!SPEC[key]) throw new Error(`unknown threshold ${key}`);
|
|
107
|
+
return parseThresholds(doc).values[key];
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
module.exports = { KEY, SPEC, DEFAULTS, MAX_VALUE, parseThresholds, thresholdValue };
|