@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/README.vi.md +2 -2
- package/audit/audit.mjs +218 -53
- package/package.json +1 -1
- package/templates/README.md +18 -3
- package/templates/ci-laravel.yml +360 -40
- package/templates/ci-node.yml +491 -35
- package/templates/ci-python.yml +301 -32
- package/templates/deploy-container-run.mjs +17 -3
- package/templates/deploy-xserver.yml +12 -0
- package/templates/instruction-files.yml +16 -0
- package/templates/pre-commit-instruction-files +55 -0
- package/templates/release-auto.yml +16 -3
- package/tools/colab +884 -98
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/audit-cache.js +277 -0
- package/tools/lib/batch-stats.js +66 -43
- package/tools/lib/ci-cure.js +10 -1
- package/tools/lib/claim-comments.js +3 -2
- package/tools/lib/codec/decision.d.ts +7 -0
- package/tools/lib/codec/decision.js +54 -0
- package/tools/lib/codec/hold.d.ts +8 -1
- package/tools/lib/codec/hold.js +42 -8
- package/tools/lib/codec/release.js +6 -3
- package/tools/lib/codec/samples.json +45 -0
- package/tools/lib/config-set.js +4 -3
- package/tools/lib/cure-diff.js +27 -1
- package/tools/lib/decision-record.js +42 -0
- package/tools/lib/docs-only.js +47 -0
- package/tools/lib/git.js +57 -8
- package/tools/lib/grant-policy.js +133 -0
- package/tools/lib/instruction-file.js +75 -0
- package/tools/lib/instruction-gate.js +179 -0
- package/tools/lib/landed-prs.js +58 -0
- package/tools/lib/migration-grant.js +29 -5
- package/tools/lib/owner-policy.js +110 -0
- package/tools/lib/release-cut.js +127 -10
- package/tools/lib/release-finalize.js +66 -5
- package/tools/lib/ship-batch.js +188 -14
- package/tools/lib/ship-handoff.js +212 -0
- package/tools/lib/stamp.js +6 -2
- package/tools/lib/template-trunk.js +80 -0
- package/tools/lib/tree-green.js +21 -4
- package/tools/lib/workflow-triggers.js +57 -0
package/tools/lib/release-cut.js
CHANGED
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
* section carrying its measured cost (parseMigrationSection). Every signal is written into the tag
|
|
47
47
|
* message, so the reason for the bump is recorded mechanically.
|
|
48
48
|
*
|
|
49
|
-
* Never a final tag — with
|
|
49
|
+
* Never a final tag — with two exceptions, `library-fast` (#590, below) and `deploy-tag-fast` (#446): on the latter the operator granted a
|
|
50
50
|
* final on every green trunk head, so `--auto` tags `vX.Y.Z` directly (no candidate, no test period)
|
|
51
51
|
* and the release workflow deploys it in the same run. That branch adds five checks, all in the
|
|
52
52
|
* same closed vocabulary:
|
|
@@ -60,6 +60,14 @@
|
|
|
60
60
|
* migration-grant no migration since the last final unless the version's tracking issue is
|
|
61
61
|
* granted one — otherwise a refusal whose `handoff` names the human command
|
|
62
62
|
*
|
|
63
|
+
* #590: route `library-fast` is the second final route — a library released per merge, nothing
|
|
64
|
+
* deployed. `cut` (by hand or `--auto`) tags `vX.Y.Z` directly once a first final exists, with
|
|
65
|
+
* `already-final` in place of `already-candidate` and the `release-hold` veto, and none of the fast
|
|
66
|
+
* route's grant, spacing, migration hand-off or health gate. Its version on `version-source:
|
|
67
|
+
* manifest` is the manifest's (decideManifestVersion): equal to the last final is a NO-OP, a break the
|
|
68
|
+
* manifest under-declares is a refusal; on `version-source: tag` the bump is computed as for a
|
|
69
|
+
* candidate.
|
|
70
|
+
*
|
|
63
71
|
* Elsewhere finalizing a candidate is the release skill's (#339), and a final is a human act on
|
|
64
72
|
* every row where a tag reaches production.
|
|
65
73
|
*/
|
|
@@ -110,6 +118,25 @@ function isFastRoute(policy) {
|
|
|
110
118
|
return !!(policy && policy.effective && policy.effective.finalize === 'on-green-head');
|
|
111
119
|
}
|
|
112
120
|
|
|
121
|
+
/**
|
|
122
|
+
* #590: is this policy route library-fast as declared — no candidates, an automatic final reached
|
|
123
|
+
* by the tag itself? There `cut` tags the FINAL directly, as on deploy-tag-fast, but nothing deploys:
|
|
124
|
+
* no grant, no spacing, no migration hand-off, no health gate. A `final: human` narrowing keeps
|
|
125
|
+
* `finalize: on-tag` but makes every final a human act, so it is not this.
|
|
126
|
+
*/
|
|
127
|
+
function isLibraryRoute(policy) {
|
|
128
|
+
const e = policy && policy.effective;
|
|
129
|
+
return !!(e && e.finalize === 'on-tag' && e.final === 'auto' && e.candidates === 'off');
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** #590: the route a refusal names — the one in effect, never the derived default it replaced. */
|
|
133
|
+
function routeWhy(policy) {
|
|
134
|
+
const releasePolicy = require('./release-policy');
|
|
135
|
+
const route = policy && policy.effective && policy.effective.route;
|
|
136
|
+
const own = route && releasePolicy.ROUTE_POLICY[route];
|
|
137
|
+
return { route, why: own ? own.why : policy.derived.why };
|
|
138
|
+
}
|
|
139
|
+
|
|
113
140
|
/** The file a major's migration section is read from, at the candidate commit (#422). */
|
|
114
141
|
const MIGRATION_FILE = 'MIGRATION.md';
|
|
115
142
|
|
|
@@ -413,6 +440,63 @@ function decideAutoVersion({ lastFinal, signals, migration, tags }) {
|
|
|
413
440
|
return { ok: true, detail: `${lastFinal} -> ${version} (${bump}, computed: ${why})`, version, bump, why, overridden: null, migration: mig };
|
|
414
441
|
}
|
|
415
442
|
|
|
443
|
+
// ---- #590: library-fast — the version the manifest already says ------------------------------
|
|
444
|
+
|
|
445
|
+
/**
|
|
446
|
+
* Route library-fast with `release.version-source: manifest`: the release is the version a merge
|
|
447
|
+
* already put in the manifest, so the cut computes no bump — it checks the manifest's.
|
|
448
|
+
* manifests release-tag.js manifestVersions() at the commit (null = unread)
|
|
449
|
+
* breaking [why] — a breaking signal since the last final (autoSignals' `breaking`, or the
|
|
450
|
+
* manual cut's semverSuggestion when it says major); empty when none
|
|
451
|
+
* migration (version) => parseMigrationSection result, asked only for a major
|
|
452
|
+
* Returns decideVersion's shape, plus `nothing` (the manifest still says the last final — a no-op
|
|
453
|
+
* under --auto) and `fallback` (no manifest declares a version: the caller computes the bump as on
|
|
454
|
+
* version-source: tag).
|
|
455
|
+
*/
|
|
456
|
+
function decideManifestVersion({ lastFinal, manifests, tags, breaking, migration }) {
|
|
457
|
+
const refuse = (detail, extra = {}) => ({ ok: false, detail, ...extra });
|
|
458
|
+
if (!lastFinal) return refuse('no final release tag (vX.Y.Z) on main yet — the first version is a human decision, not a computed bump');
|
|
459
|
+
const last = parseVersion(lastFinal);
|
|
460
|
+
if (!last) return refuse(`the last release tag ${lastFinal} is not vX.Y.Z — cannot compare the manifest against it`);
|
|
461
|
+
if (manifests === null || manifests === undefined) return refuse('the manifests could not be read at the commit — an unread version is not a release', { unread: true });
|
|
462
|
+
const bad = manifests.filter((m) => m.error).map((m) => `${m.file}: ${m.error}`);
|
|
463
|
+
if (bad.length) return refuse(`a manifest does not read — ${bad.join('; ')}`);
|
|
464
|
+
const stated = manifests.filter((m) => !m.dynamic && m.version !== undefined && m.version !== null);
|
|
465
|
+
if (!stated.length) return { ok: false, fallback: true, detail: 'no manifest states a version' };
|
|
466
|
+
const values = [...new Set(stated.map((m) => String(m.version).replace(/^v/, '')))];
|
|
467
|
+
if (values.length > 1) return refuse(`the manifests disagree on the version — ${stated.map((m) => `${m.file} says ${m.version}`).join('; ')}`);
|
|
468
|
+
const v = parseVersion(`v${values[0]}`);
|
|
469
|
+
const where = stated.map((m) => m.file).join(', ');
|
|
470
|
+
if (!v) return refuse(`${where} says ${values[0]}, which is not X.Y.Z — route library-fast tags finals only, never a pre-release`);
|
|
471
|
+
const version = formatVersion(v);
|
|
472
|
+
const cmp = (a, b) => (a.major - b.major) || (a.minor - b.minor) || (a.patch - b.patch);
|
|
473
|
+
if (cmp(v, last) === 0) {
|
|
474
|
+
return refuse(`${where} still says ${values[0]}, the last final ${lastFinal} — nothing to release until a merge bumps it (route library-fast, release.version-source: manifest)`, { nothing: true });
|
|
475
|
+
}
|
|
476
|
+
if (cmp(v, last) < 0) return refuse(`${where} says ${values[0]}, below the last final ${lastFinal} — the manifest moved backwards`);
|
|
477
|
+
if ((tags || []).includes(version)) return refuse(`${version} is already a final tag`);
|
|
478
|
+
|
|
479
|
+
const bump = v.major !== last.major ? 'major' : v.minor !== last.minor ? 'minor' : 'patch';
|
|
480
|
+
const brk = breaking || [];
|
|
481
|
+
let mig = null;
|
|
482
|
+
if (bump === 'major') {
|
|
483
|
+
if (last.major === 0) {
|
|
484
|
+
return refuse(`${where} says ${values[0]} — the step from 0.x to ${version} is a human decision (CONVENTIONS.md §6, Versioning): tag it by hand, and later finals follow the manifest`, { bump });
|
|
485
|
+
}
|
|
486
|
+
mig = typeof migration === 'function' ? migration(version) : (migration || null);
|
|
487
|
+
if (!mig || !mig.ok) {
|
|
488
|
+
return refuse(`${lastFinal} -> ${version} is a major, refused: ${mig ? mig.detail : `no migration section read for ${version}`}`, { bump, migration: mig });
|
|
489
|
+
}
|
|
490
|
+
} else if (brk.length) {
|
|
491
|
+
const owed = last.major === 0 ? 'minor' : 'major';
|
|
492
|
+
if (owed === 'major' || bump === 'patch') {
|
|
493
|
+
return refuse(`a breaking change since ${lastFinal} (${brk.join('; ')}) but ${where} only bumps to ${values[0]} (a ${bump}) — a break needs a ${owed}. Bump the manifest on trunk, or show the change is not breaking`, { bump });
|
|
494
|
+
}
|
|
495
|
+
}
|
|
496
|
+
const why = `${where} says ${values[0]}${brk.length ? ` (breaking since ${lastFinal}: ${brk.join('; ')})` : ''}`;
|
|
497
|
+
return { ok: true, detail: `${lastFinal} -> ${version} (${bump}, from the manifest: ${why})`, version, bump, why, overridden: null, migration: mig };
|
|
498
|
+
}
|
|
499
|
+
|
|
416
500
|
// ---- --auto: cadence (#422) ------------------------------------------------------------------
|
|
417
501
|
|
|
418
502
|
/**
|
|
@@ -866,17 +950,26 @@ function decide(facts) {
|
|
|
866
950
|
|
|
867
951
|
const p = f.policy;
|
|
868
952
|
const fast = isFastRoute(p) && !(p.findings && p.findings.length);
|
|
953
|
+
// #590: route library-fast — a final with no candidate, like the fast route, and nothing deployed.
|
|
954
|
+
const library = !fast && isLibraryRoute(p) && !(p.findings && p.findings.length);
|
|
955
|
+
const finalRoute = fast || library;
|
|
869
956
|
if (!p) add('release-policy', false, 'no release policy was evaluated', true);
|
|
870
957
|
else if (p.findings && p.findings.length) add('release-policy', false, `the release: block is invalid — ${p.findings.map((x) => x.text).join('; ')}`);
|
|
871
958
|
else if (fast && !f.auto) {
|
|
872
959
|
add('release-policy', false, 'route deploy-tag-fast tags its finals only from the release workflow (`colab release cut --auto`), where the deploy runs in the same run — a final cut by hand would reach production with no deploy job behind it');
|
|
873
960
|
} else if (fast) {
|
|
874
961
|
add('release-policy', true, `${p.derived.axis} (${p.derived.row}, route deploy-tag-fast): a final on every green head, granted by decision #${p.effective.finalGrant.issue}, health gate ${p.effective.healthGate.url} (rollback: ${p.effective.healthGate.rollback}), spacing ${p.effective.finalSpacingHours}h`);
|
|
962
|
+
} else if (library) {
|
|
963
|
+
add('release-policy', true, `${p.derived.axis} (${p.derived.row}, route library-fast): a final on every release the version source owes — no candidate, nothing deployed (version source: ${versionSourceOf(p)})`);
|
|
875
964
|
} else if (p.effective.candidates !== 'auto') {
|
|
876
965
|
const narrowed = p.declared && p.declared.candidates === 'off' && p.derived.candidates === 'auto';
|
|
966
|
+
const { route, why } = routeWhy(p);
|
|
967
|
+
const humanFinal = route === 'library-fast' && p.effective.final === 'human';
|
|
877
968
|
add('release-policy', false, narrowed
|
|
878
969
|
? 'release: candidates: off — this repo narrowed its rung row to no automatic candidates'
|
|
879
|
-
:
|
|
970
|
+
: humanFinal
|
|
971
|
+
? `route library-fast with release.final: human — every final here is a human act: tag vX.Y.Z by hand (CONVENTIONS.md §6, The release rung)`
|
|
972
|
+
: `candidates are off on ${p.derived.axis}${route ? `, route ${route}` : ''}: ${why} (CONVENTIONS.md §6, The release rung)`);
|
|
880
973
|
} else {
|
|
881
974
|
add('release-policy', true, `${p.derived.axis} (${p.derived.row}${p.effective.route ? `, route ${p.effective.route}` : ''}): candidates auto, final ${p.effective.final}, test period ${p.effective.testPeriodDays}d`);
|
|
882
975
|
}
|
|
@@ -904,23 +997,38 @@ function decide(facts) {
|
|
|
904
997
|
if (trig.length) add('prerelease-trigger', false, `a deploy would fire on a candidate tag: ${trig.map((t) => t.text).join('; ')}`);
|
|
905
998
|
else add('prerelease-trigger', true, 'no deploy workflow fires on a pre-release tag');
|
|
906
999
|
|
|
907
|
-
const
|
|
1000
|
+
const computed = () => (f.auto
|
|
908
1001
|
? decideAutoVersion({ lastFinal: f.lastFinal, signals: f.auto.signals, migration: f.auto.migration, tags: f.tags })
|
|
909
|
-
: decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags });
|
|
1002
|
+
: decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags }));
|
|
1003
|
+
let v;
|
|
1004
|
+
if (library && versionSourceOf(p) === 'manifest') {
|
|
1005
|
+
// #590: the manifest is the version; the signals only decide whether it under-declares a break.
|
|
1006
|
+
if (f.override && f.override.bump) v = { ok: false, detail: `--bump ${f.override.bump} has nothing to override — on route library-fast with release.version-source: manifest the version is the manifest's; bump it on trunk` };
|
|
1007
|
+
else {
|
|
1008
|
+
const sig = f.auto ? (f.auto.signals || {}) : null;
|
|
1009
|
+
if (sig && sig.unread && sig.unread.length) v = { ok: false, unread: true, detail: `a bump signal could not be read — fail closed: ${sig.unread.join('; ')}` };
|
|
1010
|
+
else {
|
|
1011
|
+
const breaking = sig ? (sig.breaking || [])
|
|
1012
|
+
: (f.suggestion && f.suggestion.bump === 'major' ? [f.suggestion.why || 'a breaking change'] : []);
|
|
1013
|
+
v = decideManifestVersion({ lastFinal: f.lastFinal, manifests: f.manifests, tags: f.tags, breaking, migration: f.auto ? f.auto.migration : f.migration });
|
|
1014
|
+
if (v.fallback) v = computed();
|
|
1015
|
+
}
|
|
1016
|
+
}
|
|
1017
|
+
} else v = computed();
|
|
910
1018
|
add('version', v.ok, v.detail, isUnread(v));
|
|
911
1019
|
// "Nothing merged since the last final" is a no-op for the release workflow, not a failure.
|
|
912
1020
|
if (f.auto && v.nothing) noop = true;
|
|
913
1021
|
|
|
914
1022
|
let tag = null;
|
|
915
1023
|
let derivable = [];
|
|
916
|
-
if (v.ok &&
|
|
1024
|
+
if (v.ok && finalRoute) {
|
|
917
1025
|
const finalHere = (f.tagsAtSha || []).filter((t) => VERSION_RE.test(t));
|
|
918
1026
|
if (finalHere.length) {
|
|
919
1027
|
add('already-final', false, `this commit is already the final ${finalHere.join(', ')} — a head that carries a final is the route holding`);
|
|
920
1028
|
if (f.auto) noop = true;
|
|
921
1029
|
} else {
|
|
922
1030
|
tag = v.version;
|
|
923
|
-
add('already-final', true, `next final: ${tag} (no candidate — route deploy-tag-fast)`);
|
|
1031
|
+
add('already-final', true, `next final: ${tag} (no candidate — route ${fast ? 'deploy-tag-fast' : 'library-fast'})`);
|
|
924
1032
|
}
|
|
925
1033
|
} else if (v.ok) {
|
|
926
1034
|
const here = candidateNumbers(f.tagsAtSha || [], v.version);
|
|
@@ -966,6 +1074,10 @@ function decide(facts) {
|
|
|
966
1074
|
const mig = f.migrations || { ok: false, detail: 'migrations since the last final were not measured' };
|
|
967
1075
|
add('migration-grant', mig.ok, mig.detail, !f.migrations || isUnread(mig));
|
|
968
1076
|
if (!mig.ok && v.ok && mig.paths && mig.paths.length) handoff = migrationHandoff(f.trackingIssue, v.version);
|
|
1077
|
+
} else if (library) {
|
|
1078
|
+
// #590: a human veto still holds an automatic final; nothing else the fast route adds applies.
|
|
1079
|
+
const h = f.holds || { ok: false, detail: `${HOLD_LABEL} was not measured` };
|
|
1080
|
+
add('release-hold', h.ok, h.detail, !f.holds || isUnread(h));
|
|
969
1081
|
}
|
|
970
1082
|
|
|
971
1083
|
const refusals = checks.filter((c) => !c.ok);
|
|
@@ -981,7 +1093,7 @@ function decide(facts) {
|
|
|
981
1093
|
signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
|
|
982
1094
|
derivable,
|
|
983
1095
|
versionSourceDeclared: !!(p && p.effective && p.effective.versionSourceDeclared),
|
|
984
|
-
final: fast, grant, handoff,
|
|
1096
|
+
final: finalRoute, route: finalRoute ? (fast ? 'deploy-tag-fast' : 'library-fast') : null, grant, handoff,
|
|
985
1097
|
healthGate: fast ? p.effective.healthGate : null,
|
|
986
1098
|
};
|
|
987
1099
|
}
|
|
@@ -996,8 +1108,9 @@ function tagMessage(verdict, { sha, lastFinal }) {
|
|
|
996
1108
|
// #446: a fast-route final. Its subject deliberately does NOT end in "(colab release cut)", so no
|
|
997
1109
|
// reader of candidates (cutCandidates, finalize's CUT_SUBJECT_SUFFIX) ever mistakes it for one.
|
|
998
1110
|
const fast = !!verdict.final;
|
|
1111
|
+
const route = verdict.route || 'deploy-tag-fast';
|
|
999
1112
|
const lines = [
|
|
1000
|
-
fast ? `${verdict.tag} — release (colab release cut,
|
|
1113
|
+
fast ? `${verdict.tag} — release (colab release cut, ${route})` : `${verdict.tag} — release candidate (colab release cut)`,
|
|
1001
1114
|
'',
|
|
1002
1115
|
`Commit: ${sha}`,
|
|
1003
1116
|
`Since: ${lastFinal}`,
|
|
@@ -1015,14 +1128,18 @@ function tagMessage(verdict, { sha, lastFinal }) {
|
|
|
1015
1128
|
'Conditions (CONVENTIONS.md §6):',
|
|
1016
1129
|
...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
|
|
1017
1130
|
'',
|
|
1018
|
-
fast
|
|
1131
|
+
fast
|
|
1132
|
+
? (route === 'library-fast'
|
|
1133
|
+
? 'A final with no candidate: route library-fast — a library released per merge; nothing deploys from this tag (CONVENTIONS.md §6).'
|
|
1134
|
+
: 'A final with no candidate: route deploy-tag-fast, by the operator\'s grant (CONVENTIONS.md §6).')
|
|
1135
|
+
: 'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
|
|
1019
1136
|
];
|
|
1020
1137
|
return lines.join('\n') + '\n';
|
|
1021
1138
|
}
|
|
1022
1139
|
|
|
1023
1140
|
module.exports = {
|
|
1024
1141
|
CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
|
|
1025
|
-
isFastRoute, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
1142
|
+
isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
1026
1143
|
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
1027
1144
|
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
|
|
1028
1145
|
fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,
|
|
@@ -77,7 +77,7 @@ const STATES = Object.freeze([
|
|
|
77
77
|
|
|
78
78
|
const CONDITIONS = Object.freeze([
|
|
79
79
|
'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
|
|
80
|
-
'ci-green', 'full-suite', 'cut-run', 'schema-additive', 'switch-dependencies',
|
|
80
|
+
'ci-green', 'full-suite', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
|
|
81
81
|
...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
|
|
82
82
|
]);
|
|
83
83
|
|
|
@@ -379,6 +379,56 @@ function cutRunVerdict(rows, { tag, cutAt, ownRunId = null, jobCount = null } =
|
|
|
379
379
|
};
|
|
380
380
|
}
|
|
381
381
|
|
|
382
|
+
// ---- a failed deploy job: a report on a human final, a gate on an automatic one (#565) -------------
|
|
383
|
+
|
|
384
|
+
// A job whose name says it deploys. The release workflow deploys the candidate to staging after it has
|
|
385
|
+
// built, tested and published it; that job's failure is about the deploy target (a host the runner
|
|
386
|
+
// cannot reach, a registry permission, a sibling image that was never built), never about the code.
|
|
387
|
+
const DEPLOY_JOB_RE = /\bdeploy/i;
|
|
388
|
+
|
|
389
|
+
/** Does a job named `name` deploy? Read from the name: GitHub's job read carries no environment. */
|
|
390
|
+
function isDeployJob(name) {
|
|
391
|
+
return DEPLOY_JOB_RE.test(String(name || ''));
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
/**
|
|
395
|
+
* The runs at a candidate's commit that failed ONLY in deploy jobs (#565). `rows` are the run rows
|
|
396
|
+
* (null = unread); `jobsOf(databaseId)` returns that run's jobs (`git.ghRunJobs`, null = unread), asked
|
|
397
|
+
* lazily and only for a completed run that concluded `failure`.
|
|
398
|
+
*
|
|
399
|
+
* A run is deploy-only when its jobs were read, at least one did not pass, and every job that did not
|
|
400
|
+
* pass (anything but success/skipped/neutral — cancelled included) is a deploy job. A job that builds,
|
|
401
|
+
* tests or publishes failing keeps the run a failure; so does a run whose jobs could not be read.
|
|
402
|
+
*
|
|
403
|
+
* Returns { rows, failures } — `rows` a copy of `rows` where each deploy-only run reads `success` and
|
|
404
|
+
* carries `deployFailed` (its failed deploy jobs), `failures` [{ workflowName, databaseId, jobs }] for
|
|
405
|
+
* the report. Measuring this never decides anything: decide() uses the rewritten reading only on a
|
|
406
|
+
* human final, and names the failures either way.
|
|
407
|
+
*/
|
|
408
|
+
function deployOnlyFailures(rows, jobsOf) {
|
|
409
|
+
if (!Array.isArray(rows) || typeof jobsOf !== 'function') return { rows, failures: [] };
|
|
410
|
+
const failures = [];
|
|
411
|
+
const out = rows.map((r) => {
|
|
412
|
+
if (!r || r.status !== 'completed' || r.conclusion !== 'failure' || r.databaseId == null) return r;
|
|
413
|
+
const jobs = jobsOf(r.databaseId);
|
|
414
|
+
if (!Array.isArray(jobs) || !jobs.length) return r;
|
|
415
|
+
const bad = jobs.filter((j) => j && !(j.status === 'completed' && NOT_RED.has(j.conclusion)));
|
|
416
|
+
if (!bad.length || !bad.every((j) => isDeployJob(j.name))) return r;
|
|
417
|
+
const named = bad.map((j) => `${j.name} (${j.status === 'completed' ? j.conclusion || 'no conclusion' : j.status || 'unknown'})`);
|
|
418
|
+
failures.push({ workflowName: r.workflowName || '(unnamed workflow)', databaseId: r.databaseId, jobs: named });
|
|
419
|
+
return { ...r, conclusion: 'success', deployFailed: named };
|
|
420
|
+
});
|
|
421
|
+
return { rows: out, failures };
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
/** The `deploy-report` check's detail — what failed, and what it means on this final. */
|
|
425
|
+
function deployReportDetail(failures, { blocking }) {
|
|
426
|
+
const what = failures.map((f) => `${f.workflowName} run ${f.databaseId}: ${f.jobs.join(', ')}`).join('; ');
|
|
427
|
+
return blocking
|
|
428
|
+
? `a deploy job failed at this candidate (${what}); an automatic final treats it as blocking, so ci-green, full-suite and cut-run read the run as failed`
|
|
429
|
+
: `a deploy job failed at this candidate (${what}); its build, tests and publish passed, so on a human final this is a report, not a gate: ci-green, full-suite and cut-run read that run without its deploy jobs. Check the deploy target before you finalize`;
|
|
430
|
+
}
|
|
431
|
+
|
|
382
432
|
// ---- the test period ----------------------------------------------------------------------------
|
|
383
433
|
|
|
384
434
|
/**
|
|
@@ -534,7 +584,8 @@ function handoffCommand(tag) {
|
|
|
534
584
|
* `facts`:
|
|
535
585
|
* policy release-policy.js evaluateRelease(doc)
|
|
536
586
|
* selection selectCandidate(...)
|
|
537
|
-
* tracking { number|null, createdAt|null, held, wouldCreate } | { error }
|
|
587
|
+
* tracking { number|null, title|null, createdAt|null, held, wouldCreate } | { error } — `title` is the
|
|
588
|
+
* matched issue's own, shown so a record that is not `release: vX.Y.Z` is visible (#575)
|
|
538
589
|
* supersededHeld [issue numbers]
|
|
539
590
|
* period periodVerdict(...) (when there is a candidate)
|
|
540
591
|
* trunk trunkGreenVerdict(...)
|
|
@@ -586,7 +637,7 @@ function decide(facts) {
|
|
|
586
637
|
|
|
587
638
|
const t = f.tracking || {};
|
|
588
639
|
if (t.error) { add('tracking-issue', false, t.error); return out('refused'); }
|
|
589
|
-
add('tracking-issue', true, t.number ? `#${t.number} (${trackingTitle(cand.version)})` : `none yet — ${t.wouldCreate ? 'this run opens' : 'a non-dry run opens'} "${trackingTitle(cand.version)}"`);
|
|
640
|
+
add('tracking-issue', true, t.number ? `#${t.number} (${t.title ? JSON.stringify(t.title) : trackingTitle(cand.version)})` : `none yet — ${t.wouldCreate ? 'this run opens' : 'a non-dry run opens'} "${trackingTitle(cand.version)}"`);
|
|
590
641
|
|
|
591
642
|
const held = [...(t.held && t.number ? [t.number] : []), ...(f.supersededHeld || [])];
|
|
592
643
|
add('release-hold', !held.length, held.length
|
|
@@ -616,7 +667,17 @@ function decide(facts) {
|
|
|
616
667
|
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);
|
|
617
668
|
const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
|
|
618
669
|
add('trunk-green', tr.ok, tr.detail, ownClock);
|
|
619
|
-
|
|
670
|
+
// #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
|
|
671
|
+
// sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
|
|
672
|
+
// those runs counted as passed; it is absent when no such run exists.
|
|
673
|
+
const dr = f.deployReport && Array.isArray(f.deployReport.failures) && f.deployReport.failures.length ? f.deployReport : null;
|
|
674
|
+
const lenient = !!dr && !auto;
|
|
675
|
+
const pick = (strict, relaxed) => (lenient && relaxed ? relaxed : strict);
|
|
676
|
+
for (const [condition, v] of [['ci-green', pick(f.ci, dr && dr.ci)], ['full-suite', pick(f.suite, dr && dr.suite)], ['cut-run', pick(f.cutRun, dr && dr.cutRun)]]) {
|
|
677
|
+
add(condition, v && v.ok, v ? v.detail : 'not measured');
|
|
678
|
+
}
|
|
679
|
+
if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
|
|
680
|
+
for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
620
681
|
add(condition, v && v.ok, v ? v.detail : 'not measured');
|
|
621
682
|
}
|
|
622
683
|
// #424: before any final — the tag equals the manifests, the commit is on trunk, the version outranks the latest final.
|
|
@@ -698,7 +759,7 @@ module.exports = {
|
|
|
698
759
|
STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
|
|
699
760
|
parseVersion, compareVersions, parseCandidate,
|
|
700
761
|
parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
|
|
701
|
-
selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
762
|
+
selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
702
763
|
handoffCommand, decide, tagMessage, migrationGrantVerdict,
|
|
703
764
|
carriedIssues, previousFinal, releasedEvent, releasedComment,
|
|
704
765
|
};
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -18,7 +18,11 @@
|
|
|
18
18
|
* semantic conflicts need no shared file. The combined run is the gate.
|
|
19
19
|
*/
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
// The SAFETY ceiling (#557): what any repo may declare, never what it gets. 3 until a red batch had
|
|
22
|
+
// a cheaper exit than N serial cycles; split-and-retry (nextStep's `split`) is that exit, so the
|
|
23
|
+
// ceiling is now 8 — the size from which bisection beats a serial fallback. A repo's own
|
|
24
|
+
// `ship-batch: <N>` is its ceiling; `ship-batch-steps` makes the size adapt below it.
|
|
25
|
+
const MAX_BATCH = 8;
|
|
22
26
|
const REF_PREFIX = 'ship-batch/';
|
|
23
27
|
// A concrete ref a `branches:` filter is tested against. Any 7-hex tail works: GitHub's filters see
|
|
24
28
|
// the literal ref name, and the question is only whether `ship-batch/**` (or a wider glob) admits it.
|
|
@@ -26,7 +30,7 @@ const PROBE_REF = `${REF_PREFIX}0000000`;
|
|
|
26
30
|
const TRAILER_KEY = 'Ship-Batch';
|
|
27
31
|
|
|
28
32
|
/**
|
|
29
|
-
* `ship-batch:` from project.yml. Absent → 1 (serial, today's behaviour). An integer 1..
|
|
33
|
+
* `ship-batch:` from project.yml. Absent → 1 (serial, today's behaviour). An integer 1..MAX_BATCH → that
|
|
30
34
|
* (a single-digit string reads the same). Anything else — 0, 4, 2.5, true, a word — FAILS CLOSED to
|
|
31
35
|
* serial, with the reason: a malformed opt-in must never widen what ship does. The audit fails the
|
|
32
36
|
* same values.
|
|
@@ -39,19 +43,111 @@ function parseShipBatch(doc) {
|
|
|
39
43
|
const v = doc['ship-batch'];
|
|
40
44
|
// A digit string is accepted too: the audit's flat reader keeps every scalar a string, and the two
|
|
41
45
|
// readers must agree on what is valid — a value one accepts and the other refuses is drift.
|
|
42
|
-
const n = typeof v === 'number' ? v : (typeof v === 'string' && /^[1-9]
|
|
46
|
+
const n = typeof v === 'number' ? v : (typeof v === 'string' && /^[1-9][0-9]*$/.test(v.trim()) ? Number(v.trim()) : NaN);
|
|
43
47
|
if (Number.isInteger(n) && n >= 1 && n <= MAX_BATCH) {
|
|
44
48
|
return { n, declared: true, valid: true, reason: `ship-batch: ${n}` };
|
|
45
49
|
}
|
|
46
50
|
return { n: 1, declared: true, valid: false, reason: `ship-batch is ${JSON.stringify(v)}, expected an integer 1–${MAX_BATCH} (omit for serial)` };
|
|
47
51
|
}
|
|
48
52
|
|
|
53
|
+
const STEPS_KEY = 'ship-batch-steps';
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* #557: `ship-batch-steps:` from project.yml — the sizes an ADAPTIVE batch walks through, smallest
|
|
57
|
+
* first: grow one step after a green batch, shrink one after a red one. Written `2,4,8` (a YAML flow
|
|
58
|
+
* list `[2, 4, 8]` reads the same). Strictly ascending whole numbers within 1..`ship-batch` — the
|
|
59
|
+
* repo's own ceiling, which stays the largest a batch may ever be.
|
|
60
|
+
*
|
|
61
|
+
* Absent → `steps: null`: the size is fixed at `ship-batch`, today's behaviour exactly. The handbook
|
|
62
|
+
* gives NO default steps — the repo chooses them from its own `colab batch-stats`. Anything malformed
|
|
63
|
+
* FAILS CLOSED to `steps: null`, with the reason: the fixed size the repo already declared, never
|
|
64
|
+
* wider. The audit and the CI templates' descriptor check fail the same values.
|
|
65
|
+
*/
|
|
66
|
+
function parseShipBatchSteps(doc) {
|
|
67
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, STEPS_KEY);
|
|
68
|
+
if (!has || doc[STEPS_KEY] === null || doc[STEPS_KEY] === undefined) {
|
|
69
|
+
return { steps: null, declared: false, valid: true, reason: `${STEPS_KEY} absent` };
|
|
70
|
+
}
|
|
71
|
+
const v = doc[STEPS_KEY];
|
|
72
|
+
const n = parseShipBatch(doc).n;
|
|
73
|
+
const bad = (why) => ({ steps: null, declared: true, valid: false, reason: `${STEPS_KEY} is ${JSON.stringify(v)}, ${why} (omit for a fixed size)` });
|
|
74
|
+
let parts;
|
|
75
|
+
if (Array.isArray(v)) parts = v.map((x) => String(x).trim());
|
|
76
|
+
else if (typeof v === 'number') parts = [String(v)];
|
|
77
|
+
else if (typeof v === 'string') parts = v.trim().replace(/^\[(.*)\]$/, '$1').split(',').map((x) => x.trim());
|
|
78
|
+
else return bad('expected ascending whole numbers like 2,4,8');
|
|
79
|
+
if (!parts.length || parts.some((x) => !/^[1-9][0-9]*$/.test(x))) return bad('expected ascending whole numbers like 2,4,8');
|
|
80
|
+
const steps = parts.map(Number);
|
|
81
|
+
if (steps.some((x, i) => i > 0 && x <= steps[i - 1])) return bad('expected strictly ascending sizes like 2,4,8');
|
|
82
|
+
if (steps[steps.length - 1] > n) return bad(`expected every size within ship-batch: ${n}, the repo's own ceiling`);
|
|
83
|
+
return { steps, declared: true, valid: true, reason: `${STEPS_KEY}: ${steps.join(',')}` };
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* #557: the trailer every batch head carries where steps are declared — the size the build TARGETED
|
|
88
|
+
* (not its fill), plus ` red` when the build is a split half of a red batch:
|
|
89
|
+
*
|
|
90
|
+
* Ship-Batch-Size: <s> built at step s
|
|
91
|
+
* Ship-Batch-Size: <s> red a split half; its parent batch, built at step s, went red
|
|
92
|
+
*
|
|
93
|
+
* It reaches trunk with a landed batch, so the next build reads the lane's last outcome from trunk
|
|
94
|
+
* alone — no batch state in ~/.colab, the same posture as memberTrailer.
|
|
95
|
+
*/
|
|
96
|
+
const SIZE_TRAILER_KEY = 'Ship-Batch-Size';
|
|
97
|
+
|
|
98
|
+
function sizeTrailer({ size, red = false }) {
|
|
99
|
+
return `${SIZE_TRAILER_KEY}: ${size}${red ? ' red' : ''}`;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** The LAST `Ship-Batch-Size:` trailer across commit messages → `{ size, red }`, else null. */
|
|
103
|
+
function parseSizeTrailer(messages) {
|
|
104
|
+
let out = null;
|
|
105
|
+
for (const msg of messages || []) {
|
|
106
|
+
for (const line of String(msg || '').split('\n')) {
|
|
107
|
+
const m = new RegExp(`^${SIZE_TRAILER_KEY}:\\s+([1-9][0-9]*)(\\s+red)?\\s*$`).exec(line.trim());
|
|
108
|
+
if (m) out = { size: Number(m[1]), red: !!m[2] };
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return out;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* #557: the size the NEXT batch is built at.
|
|
116
|
+
* steps null (absent or malformed) → n, fixed — today's behaviour
|
|
117
|
+
* no trailer on trunk yet → the smallest step: a lane starts small and earns its width
|
|
118
|
+
* last landed batch green → the smallest step ABOVE its size (the largest step if none)
|
|
119
|
+
* last landed batch a red's half → the largest step BELOW its parent's size (the smallest if none)
|
|
120
|
+
* Never above n: parseShipBatchSteps already refuses a step above it.
|
|
121
|
+
*/
|
|
122
|
+
function adaptiveSize({ n, steps, last }) {
|
|
123
|
+
if (!Array.isArray(steps) || !steps.length) return n;
|
|
124
|
+
if (!last || !Number.isFinite(last.size)) return steps[0];
|
|
125
|
+
if (last.red) {
|
|
126
|
+
const below = steps.filter((s) => s < last.size);
|
|
127
|
+
return below.length ? below[below.length - 1] : steps[0];
|
|
128
|
+
}
|
|
129
|
+
const above = steps.filter((s) => s > last.size);
|
|
130
|
+
return above.length ? above[0] : steps[steps.length - 1];
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* #557: split a red batch — the members (batch order) that form the FIRST half, tested next on the
|
|
135
|
+
* same base; the rest wait for the next batch. Sequential halves keep one batch per base, so the lane
|
|
136
|
+
* hold, the foreign-batch rule and the rebuild rule all hold unchanged; worst case for one culprit is
|
|
137
|
+
* about 2·log2(k)+1 cycles against 1+k for the serial fallback it replaces.
|
|
138
|
+
*/
|
|
139
|
+
function splitHalves(members) {
|
|
140
|
+
const list = Array.isArray(members) ? members : [];
|
|
141
|
+
const cut = Math.ceil(list.length / 2);
|
|
142
|
+
return { first: list.slice(0, cut), held: list.slice(cut) };
|
|
143
|
+
}
|
|
144
|
+
|
|
49
145
|
const WAIT_KEY = 'ship-batch-wait';
|
|
50
146
|
const WAIT_UNITS = { s: 1, m: 60, h: 3600 };
|
|
51
147
|
|
|
52
148
|
/**
|
|
53
149
|
* #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
|
|
150
|
+
* before it lands alone (as a batch of one, #562). A whole number plus a unit: `90s`, `6m`, `1h`. The unit is required, so a
|
|
55
151
|
* bare `6` (seconds? minutes?) is refused, never guessed. `0s`/`0m` is valid and means no wait.
|
|
56
152
|
*
|
|
57
153
|
* Absent → `sec: 0`, today's behaviour exactly. The handbook gives NO default value and NO ceiling
|
|
@@ -74,7 +170,8 @@ function parseShipBatchWait(doc) {
|
|
|
74
170
|
}
|
|
75
171
|
|
|
76
172
|
/**
|
|
77
|
-
* #555: does a batch call with ONE eligible member wait for a partner, or
|
|
173
|
+
* #555: does a batch call with ONE eligible member wait for a partner, or build now? (Past the window
|
|
174
|
+
* it lands alone — through the batch path, as a batch of one, #562 — never serially.)
|
|
78
175
|
* Facts in (all already read by the caller, after it has ruled out a pending trunk run and a batch
|
|
79
176
|
* already in flight — the lane is otherwise idle by then):
|
|
80
177
|
* n parseShipBatch(doc).n
|
|
@@ -305,18 +402,26 @@ function combinedVerdict(rows) {
|
|
|
305
402
|
/**
|
|
306
403
|
* The one decision per `colab ship --batch` call. The command is RE-ENTRANT: it reads remote state,
|
|
307
404
|
* takes one step, and exits — the caller waits (bounded, code-ship B1a) and calls again.
|
|
308
|
-
* serial(reason) land nothing; hand the members back as a serial list (exit 4)
|
|
405
|
+
* serial(reason) land nothing; hand the members back as a serial list (exit 4) — never for
|
|
406
|
+
* a lone ready member: one member is a valid batch (#562)
|
|
309
407
|
* wait-trunk trunk's own run is still in flight (exit 3)
|
|
310
408
|
* rebuild a batch ref exists on a base trunk has moved past, or its members/heads are
|
|
311
409
|
* no longer the ones asked for → delete it, then build afresh
|
|
312
410
|
* build build + push the batch ref (exit 3)
|
|
313
411
|
* wait-run the combined run is pending or has not appeared (exit 3)
|
|
314
|
-
* red-rerun-or-
|
|
315
|
-
* red:infra is re-run once, a red:finding
|
|
316
|
-
*
|
|
412
|
+
* red-rerun-or-split combined run red on its FIRST attempt, k > 1 members — the caller classifies
|
|
413
|
+
* it (§4): a red:infra is re-run once, a red:finding re-runs this command with
|
|
414
|
+
* `--split` (exit 4, ref kept) (#557)
|
|
415
|
+
* split red after the one re-run, or `--split` on a first-attempt red, k > 1 → rebuild
|
|
416
|
+
* the same ref with the first half of its members (splitHalves); the rest wait
|
|
417
|
+
* for the next batch (exit 3) (#557)
|
|
418
|
+
* red-rerun-or-serial a red batch of ONE on its first attempt: re-run once, or that member goes
|
|
419
|
+
* serial — it cannot split (exit 4, ref kept)
|
|
420
|
+
* red-serial a batch of one red after the re-run (or `--split`) — land nothing, serial
|
|
421
|
+
* (exit 4, ref deleted); that member returns to its implementer
|
|
317
422
|
* land green → fast-forward trunk if it has not moved
|
|
318
423
|
*/
|
|
319
|
-
function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null, trunkNow = null, verdict = null }) {
|
|
424
|
+
function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null, trunkNow = null, verdict = null, split = false }) {
|
|
320
425
|
if (!enabled) return { step: 'serial', reason: 'not-enabled' };
|
|
321
426
|
if (!wired) return { step: 'serial', reason: 'unwired' };
|
|
322
427
|
if (trunkCi === 'red') return { step: 'serial', reason: 'trunk-red' };
|
|
@@ -325,10 +430,18 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
|
|
|
325
430
|
if (!trunkNow || !String(trunkNow).startsWith(existing.base7)) return { step: 'rebuild', reason: 'trunk-moved' };
|
|
326
431
|
if (!existing.matches) return { step: 'rebuild', reason: 'members-changed' };
|
|
327
432
|
if (!verdict || verdict.state === 'pending' || verdict.state === 'none') return { step: 'wait-run' };
|
|
328
|
-
if (verdict.state === 'red')
|
|
433
|
+
if (verdict.state === 'red') {
|
|
434
|
+
// #557: a red batch of k > 1 splits instead of going serial. After its one re-run, it splits by
|
|
435
|
+
// itself; on the first attempt the caller has classified it (red:finding → `--split`).
|
|
436
|
+
const k = Array.isArray(existing.members) ? existing.members.length : 1;
|
|
437
|
+
if (verdict.attempt >= 2 || split) return k > 1 ? { step: 'split' } : { step: 'red-serial' };
|
|
438
|
+
return k > 1 ? { step: 'red-rerun-or-split' } : { step: 'red-rerun-or-serial' };
|
|
439
|
+
}
|
|
329
440
|
return { step: 'land' };
|
|
330
441
|
}
|
|
331
|
-
|
|
442
|
+
// #562: a batch of ONE is a batch — a lone ready member still lands through the combined run, so
|
|
443
|
+
// the setups a repo runs only on ship-batch/** and trunk gate it before trunk moves.
|
|
444
|
+
if (eligibleCount < 1) return { step: 'serial', reason: 'none-ready' };
|
|
332
445
|
return { step: 'build' };
|
|
333
446
|
}
|
|
334
447
|
|
|
@@ -366,6 +479,66 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
|
|
|
366
479
|
return (batchRows || []).length >= a.length;
|
|
367
480
|
}
|
|
368
481
|
|
|
482
|
+
/**
|
|
483
|
+
* #581: the lane reservation. A batch ref at trunk's CURRENT tip whose combined run is in flight (or
|
|
484
|
+
* green and not yet landed) holds the trunk lane: a serial `colab ship` into trunk that landed now
|
|
485
|
+
* would move trunk under it, and the batch's next call would throw the green run away and rebuild —
|
|
486
|
+
* measured five builds in two hours on one repo, every member ready the whole time. The ref itself
|
|
487
|
+
* is the reservation: it already sits on the remote every lander reads, it names its base, and its
|
|
488
|
+
* runs say whether it is alive. No second record to write, expire or keep in sync.
|
|
489
|
+
*
|
|
490
|
+
* Facts in, per batch ref on the remote (`batches`):
|
|
491
|
+
* ref, base7 parseBatchRef
|
|
492
|
+
* verdict combinedVerdict of the runs at its head
|
|
493
|
+
* builtAtMs the batch head's commit time (the build commits it), null = unread
|
|
494
|
+
* settledAtMs the newest `updatedAt` of its runs once green, null = unread
|
|
495
|
+
* plus `trunkNow` (the remote trunk sha), `nowMs`, and `graceSec`.
|
|
496
|
+
*
|
|
497
|
+
* Out: `{ held: true, ref, why }` for the first batch that holds the lane, else `{ held: false,
|
|
498
|
+
* released: [{ ref, why }] }` naming each batch at this base that does NOT hold it, and why.
|
|
499
|
+
* - a batch on an older base holds nothing: trunk already moved past it, it rebuilds anyway;
|
|
500
|
+
* - red (first attempt or after its re-run) → declined, holds nothing;
|
|
501
|
+
* - pending, or a run list that could not be read → held (fail closed: a pause clears itself);
|
|
502
|
+
* - no run yet → held for `graceSec` after it was built, then released (its run never came);
|
|
503
|
+
* - green → held for `graceSec` after it went green — its lander lands it on its next call —
|
|
504
|
+
* then released: a green batch nobody lands is abandoned, and must not hold the lane forever.
|
|
505
|
+
* An unread time (built/settled) is released, never held: a hold has to be provably alive.
|
|
506
|
+
*/
|
|
507
|
+
const LANE_GRACE_SEC = 900;
|
|
508
|
+
|
|
509
|
+
function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {}) {
|
|
510
|
+
const now = String(trunkNow || '');
|
|
511
|
+
const released = [];
|
|
512
|
+
if (!now) return { held: false, released };
|
|
513
|
+
const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
|
|
514
|
+
const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
|
|
515
|
+
for (const b of (Array.isArray(batches) ? batches : [])) {
|
|
516
|
+
if (!b || !b.base7 || !now.startsWith(b.base7)) continue;
|
|
517
|
+
const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
|
|
518
|
+
if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
|
|
519
|
+
if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
|
|
520
|
+
if (v.state === 'none') {
|
|
521
|
+
if (fresh(b.builtAtMs)) return { held: true, ref: b.ref, why: `built ${mins(b.builtAtMs)}, its combined run has not appeared yet` };
|
|
522
|
+
released.push({ ref: b.ref, why: Number.isFinite(b.builtAtMs)
|
|
523
|
+
? `no combined run ${mins(b.builtAtMs)} after it was built (grace ${graceSec}s) — treated as abandoned`
|
|
524
|
+
: 'no combined run, and its build time could not be read — not provably alive' });
|
|
525
|
+
continue;
|
|
526
|
+
}
|
|
527
|
+
if (fresh(b.settledAtMs)) return { held: true, ref: b.ref, why: `combined run green ${mins(b.settledAtMs)} — its lander lands it on its next call` };
|
|
528
|
+
released.push({ ref: b.ref, why: Number.isFinite(b.settledAtMs)
|
|
529
|
+
? `combined run green ${mins(b.settledAtMs)} and still not landed (grace ${graceSec}s) — treated as abandoned`
|
|
530
|
+
: 'combined run green, but when it went green could not be read — not provably alive' });
|
|
531
|
+
}
|
|
532
|
+
return { held: false, released };
|
|
533
|
+
}
|
|
534
|
+
|
|
535
|
+
/** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
|
|
536
|
+
function settledAt(rows) {
|
|
537
|
+
const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
|
|
538
|
+
.map((r) => Date.parse(r.updatedAt || '')).filter(Number.isFinite);
|
|
539
|
+
return t.length ? Math.max(...t) : null;
|
|
540
|
+
}
|
|
541
|
+
|
|
369
542
|
/**
|
|
370
543
|
* #415: branches the command line names that a staged batch does not carry, in command-line order.
|
|
371
544
|
* `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
|
|
@@ -421,9 +594,10 @@ function landPushFailure({ stderr, remoteNow, base, max = 8 } = {}) {
|
|
|
421
594
|
}
|
|
422
595
|
|
|
423
596
|
module.exports = {
|
|
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,
|
|
597
|
+
MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY, WAIT_KEY, STEPS_KEY, SIZE_TRAILER_KEY, DROP_TRAILER_KEY, DROP_CLASSES,
|
|
598
|
+
parseShipBatch, parseShipBatchWait, parseShipBatchSteps, sizeTrailer, parseSizeTrailer, adaptiveSize, splitHalves, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
|
|
426
599
|
droppedTrailer, parseDroppedTrailers, appendTrailers,
|
|
427
600
|
branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
|
|
428
601
|
batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
|
|
602
|
+
LANE_GRACE_SEC, laneHold, settledAt,
|
|
429
603
|
};
|