@futurelastic/colab-handbook 1.21.0-rc.8 → 1.21.0-rc.9
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/audit/audit.mjs +32 -1
- package/package.json +1 -1
- package/tools/colab +110 -15
- package/tools/lib/config-set.js +1 -1
- package/tools/lib/git.js +4 -0
- package/tools/lib/release-only.js +182 -0
package/audit/audit.mjs
CHANGED
|
@@ -149,6 +149,8 @@ const treeGreenLib = require("../tools/lib/tree-green.js");
|
|
|
149
149
|
const docsOnlyLib = require("../tools/lib/docs-only.js");
|
|
150
150
|
// #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
|
|
151
151
|
const verifyRunsLib = require("../tools/lib/verify-runs.js");
|
|
152
|
+
// #736: `release-only-checks:` — read through the same module ship's release-only door uses.
|
|
153
|
+
const releaseOnlyLib = require("../tools/lib/release-only.js");
|
|
152
154
|
// #410: the optional `gate:` block — read through the same module the skills name.
|
|
153
155
|
const gateLib = require("../tools/lib/gate.js");
|
|
154
156
|
// #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
|
|
@@ -268,7 +270,11 @@ function parseScalarValue(raw) {
|
|
|
268
270
|
return val;
|
|
269
271
|
}
|
|
270
272
|
|
|
271
|
-
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630
|
|
273
|
+
const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds", "contention", "release-only-checks"]); // owner: #394 · gate: #410 · thresholds: #560 · contention: #630 · release-only-checks: #736
|
|
274
|
+
// #736: the one map whose KEYS are free text — a check's display name ("Install smoke", "CI / install (*)"),
|
|
275
|
+
// optionally quoted, never containing ":" — and whose every value is an INLINE list of paths. Still one
|
|
276
|
+
// level, still no block list: any other line under it is a finding.
|
|
277
|
+
const FREE_KEY_MAP_KEYS = new Set(["release-only-checks"]);
|
|
272
278
|
// The one map whose pairs may hold an INLINE list (`coupled: [a, b]`) — still one level, still no block list (#630).
|
|
273
279
|
const LIST_IN_MAP_KEYS = new Set(["contention"]);
|
|
274
280
|
// A key whose empty value may open EITHER a block list or a one-level map: `migrations:` is a list of
|
|
@@ -295,6 +301,19 @@ function parseFlatYaml(text) {
|
|
|
295
301
|
out[listKey].push(parseScalarValue(item[1]));
|
|
296
302
|
return;
|
|
297
303
|
}
|
|
304
|
+
if (mapKey !== null && FREE_KEY_MAP_KEYS.has(mapKey) && !item) {
|
|
305
|
+
const fp = line.match(/^(\s+)("[^"]+"|'[^']+'|[^\s#"'][^:#]*?)\s*:\s*(.*)$/);
|
|
306
|
+
const fpVal = fp ? fp[3].replace(/\s+#.*$/, "").trim() : "";
|
|
307
|
+
if (fp && (mapIndent === null || fp[1].length === mapIndent) && /^\[.*\]$/.test(fpVal)) {
|
|
308
|
+
if (mapIndent === null) mapIndent = fp[1].length;
|
|
309
|
+
if (out[mapKey] === null || typeof out[mapKey] !== "object") out[mapKey] = {};
|
|
310
|
+
const inner = fpVal.slice(1, -1).trim();
|
|
311
|
+
out[mapKey][fp[2]] = inner === "" ? [] : inner.split(",").map((x) => parseScalarValue(x));
|
|
312
|
+
return;
|
|
313
|
+
}
|
|
314
|
+
problems.push(`line ${idx + 1}: "${mapKey}:" takes one level of "<check name>: [paths]" pairs, each list inline — nothing deeper, no block list`);
|
|
315
|
+
return;
|
|
316
|
+
}
|
|
298
317
|
const pair = line.match(/^(\s+)([A-Za-z0-9_.-]+)\s*:\s*(.*)$/);
|
|
299
318
|
if (mapKey !== null && pair && !item) {
|
|
300
319
|
const [, indent, sub, subRaw] = pair;
|
|
@@ -1600,6 +1619,18 @@ function auditRepoInner(target, ctx) {
|
|
|
1600
1619
|
for (const why of vp.problems) fail(why);
|
|
1601
1620
|
}
|
|
1602
1621
|
|
|
1622
|
+
// ---- release-only-checks (#736) ---------------------------------------------
|
|
1623
|
+
// Checks that matter only to a release, each next to the paths it covers: ship's per-branch
|
|
1624
|
+
// release-only door lets a branch past a trunk red only on them when it touches none of those
|
|
1625
|
+
// paths. An invalid declaration fails: the reader ignores the whole key, so it exempts nothing.
|
|
1626
|
+
{
|
|
1627
|
+
const ro = releaseOnlyLib.parseReleaseOnly(cfg);
|
|
1628
|
+
info.releaseOnlyChecks = ro.declared && ro.valid
|
|
1629
|
+
? ro.checks.map((c) => ({ check: c.key, workflow: c.workflow, job: c.job, paths: c.paths }))
|
|
1630
|
+
: null;
|
|
1631
|
+
for (const why of ro.problems) fail(why);
|
|
1632
|
+
}
|
|
1633
|
+
|
|
1603
1634
|
// ---- gate (#410) ----------------------------------------------------------
|
|
1604
1635
|
// Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
|
|
1605
1636
|
// parseGate is the one reading. An invalid block fails: the reader falls back to the local full
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -50,6 +50,7 @@ const ciVerdict = require('./lib/ci-verdict');
|
|
|
50
50
|
const baseCiVerdict = require('./lib/base-ci-verdict');
|
|
51
51
|
const treeGreen = require('./lib/tree-green');
|
|
52
52
|
const verifyRuns = require('./lib/verify-runs');
|
|
53
|
+
const releaseOnly = require('./lib/release-only'); // #736: the release-only red-trunk door
|
|
53
54
|
const ciWait = require('./lib/ci-wait'); // #495
|
|
54
55
|
const ciProfile = require('./lib/ci-profile'); // #559
|
|
55
56
|
const thresholdsLib = require('./lib/thresholds'); // #560
|
|
@@ -11242,6 +11243,17 @@ function ciGrantTrailerLine(grantVerdict, branch, trunk) {
|
|
|
11242
11243
|
* through the widened door on a branch editing the CI config is a materially different fact from an
|
|
11243
11244
|
* ordinary one. The commit is the only artifact that still says so after the runs age out.
|
|
11244
11245
|
*/
|
|
11246
|
+
/**
|
|
11247
|
+
* #736: the `CI-Release-Only:` trailer — the audit trail of a merge that landed over a trunk red only on
|
|
11248
|
+
* release-only checks, naming the red it ignored. Deliberately NOT `CI-Grant:` / `CI-Cure:`:
|
|
11249
|
+
* computeAntiStacking greps exactly those two prefixes ("one exemption per red episode"), and a
|
|
11250
|
+
* release-only red is precisely the one many branches must be able to land over, one after another.
|
|
11251
|
+
*/
|
|
11252
|
+
function releaseOnlyTrailerLine(v, branch, trunk) {
|
|
11253
|
+
if (!v || !v.ok) return null;
|
|
11254
|
+
return `CI-Release-Only: branch ${branch} over-red ${trunk}@${shortSha(v.redSha)} ignored ${releaseOnly.ignoredList(v.ignored)}`;
|
|
11255
|
+
}
|
|
11256
|
+
|
|
11245
11257
|
function ciCureTrailerLine(cureVerdict, branch, trunk) {
|
|
11246
11258
|
if (!cureVerdict || !cureVerdict.ok) return null;
|
|
11247
11259
|
const via = (cureVerdict.carveOut
|
|
@@ -11465,6 +11477,19 @@ Its own honest limit: it proves the red jobs still ran the steps they ran and st
|
|
|
11465
11477
|
never what those steps ASSERTED. Known false refusal: a trunk job that failed by TIMEOUT ran longer
|
|
11466
11478
|
than any healthy run, so (4c) refuses the genuine repair; take the ordinary ci-grant door there.
|
|
11467
11479
|
|
|
11480
|
+
THE RELEASE-ONLY DOOR (#736) is tried before both. A repo may declare, in .github/project.yml, the
|
|
11481
|
+
checks that matter only to a release, each next to the paths it covers:
|
|
11482
|
+
release-only-checks:
|
|
11483
|
+
Install smoke: [packaging/, scripts/install.sh] # a whole workflow, by its name:
|
|
11484
|
+
"CI / install (*)": [installer/**] # one job of a workflow, * in the job part
|
|
11485
|
+
When trunk's red comes ONLY from declared checks (every other judged workflow — or job — green, at
|
|
11486
|
+
least one of them), and the branch touches none of the paths of the checks that are red, the row
|
|
11487
|
+
passes; the detail, \`--dry --json\`'s \`releaseOnly\` and a \`CI-Release-Only:\` trailer name the red it
|
|
11488
|
+
ignored. A branch that touches those paths falls through to the cure rule — it must show that check
|
|
11489
|
+
green itself. Read at trunk, never the branch's own descriptor. No anti-stacking: many branches may
|
|
11490
|
+
land over one release-only red. It makes nothing green — \`colab trunk-ci\` still reads RED and
|
|
11491
|
+
\`colab release cut\` still refuses that commit. Declaring nothing (or an invalid key) changes nothing.
|
|
11492
|
+
|
|
11468
11493
|
The default squash subject is the branch's HIGHEST-WEIGHT commit (breaking > feat > fix > perf >
|
|
11469
11494
|
refactor > docs > test > chore, ties to the oldest) — NOT its newest commit, which on a well-run
|
|
11470
11495
|
branch is the docs pass and used to retitle whole features as \`docs:\`, hiding them from the
|
|
@@ -12144,11 +12169,41 @@ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk, branch =
|
|
|
12144
12169
|
const r = readCiVerdict(repoAbs, gh, target, trunk);
|
|
12145
12170
|
// #678: on a forge the engine map names, the verdict is final — the #482 no-workflow door counts
|
|
12146
12171
|
// `.github/workflows` and reads the branch through gh, neither of which describes a forge's CI.
|
|
12147
|
-
if (forgeCi(repoAbs)) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
|
|
12172
|
+
if (forgeCi(repoAbs)) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
|
|
12148
12173
|
const nw = noWorkflowTrunkDoor(repoAbs, r, target, trunk, branch, docsOnlyThunk);
|
|
12149
|
-
if (nw) return { name, ...nw, grantVerdict: null, cureVerdict: null };
|
|
12150
|
-
if (r.final) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
|
|
12151
|
-
|
|
12174
|
+
if (nw) return { name, ...nw, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
|
|
12175
|
+
if (r.final) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
|
|
12176
|
+
// #736: the release-only door is built here, not passed in — it needs only the branch, so every
|
|
12177
|
+
// caller (the table, --dry, B1) gets it without a new parameter, and a call with no branch never does.
|
|
12178
|
+
const releaseOnlyThunk = branch ? (redSha) => shipReleaseOnly(repoAbs, target, trunk, redSha, branch) : null;
|
|
12179
|
+
return applyRedTrunkExemptions({ name, ...r.verdict }, target, trunk, r.run.sha, grantThunk, cureThunk, releaseOnlyThunk);
|
|
12180
|
+
}
|
|
12181
|
+
|
|
12182
|
+
/**
|
|
12183
|
+
* #736: the release-only door's measurement — I/O only; the rule is tools/lib/release-only.js.
|
|
12184
|
+
*
|
|
12185
|
+
* - the declaration is read at TRUNK (`projectDocAt`), never the branch: a branch that adds its own
|
|
12186
|
+
* check to the list does not change what its own ship reads (the same discipline as trust-humans);
|
|
12187
|
+
* - the runs at the red sha through the SAME verifying policy readCiVerdict used, asking for the judged
|
|
12188
|
+
* heads (git.summarizeRunsForCommit `opts.heads`), so "which workflow is red" is the gate's own answer;
|
|
12189
|
+
* - a run's jobs only for a workflow declared at job level (one `gh run view` each, lazily);
|
|
12190
|
+
* - the paths the branch changes: the three-dot diff the squash would land, renames as delete + add so
|
|
12191
|
+
* a file moved OUT of a covered path still counts as touching it.
|
|
12192
|
+
*
|
|
12193
|
+
* Returns release-only.js's verdict plus `redSha`, or null when nothing is declared (or the declaration
|
|
12194
|
+
* is invalid — the audit reports that; the reader takes it as absent), so a repo that declares nothing
|
|
12195
|
+
* pays nothing and reads exactly as before.
|
|
12196
|
+
*/
|
|
12197
|
+
function shipReleaseOnly(repoAbs, target, trunk, redSha, branch) {
|
|
12198
|
+
if (target !== trunk || !redSha || !branch) return null;
|
|
12199
|
+
const decl = releaseOnly.parseReleaseOnly(projectDocAt(repoAbs, trunk));
|
|
12200
|
+
if (!decl.valid || !decl.checks.length) return null;
|
|
12201
|
+
const run = git.ghRunForCommit(repoAbs, trunk, redSha, undefined, { verifying: verifyingPolicy(repoAbs), heads: true });
|
|
12202
|
+
const heads = run && Array.isArray(run.heads) ? run.heads : null;
|
|
12203
|
+
const diff = git.git(['diff', '--name-only', '-z', '--no-renames', `${target}...${shipRefFor(repoAbs, branch)}`, '--'], repoAbs);
|
|
12204
|
+
const changed = diff.ok ? diff.stdout.split('\0').map((x) => x.replace(/^\n+/, '')).filter(Boolean) : null;
|
|
12205
|
+
const v = releaseOnly.releaseOnlyVerdict({ heads, jobsOf: (id) => git.ghRunJobs(repoAbs, id), changed, checks: decl.checks });
|
|
12206
|
+
return v.applies ? { ...v, redSha } : null;
|
|
12152
12207
|
}
|
|
12153
12208
|
|
|
12154
12209
|
/**
|
|
@@ -12778,8 +12833,21 @@ function dirtyOwnerDetail(baseDetail, advisory) {
|
|
|
12778
12833
|
* on a human, or on the tracker read; a branch that does not falls through to the grant exactly as
|
|
12779
12834
|
* it always has, unaffected by this rule's existence.
|
|
12780
12835
|
*/
|
|
12781
|
-
function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThunk) {
|
|
12782
|
-
if (target !== trunk) return { ...raw, grantVerdict: null, cureVerdict: null };
|
|
12836
|
+
function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThunk, releaseOnlyThunk = null) {
|
|
12837
|
+
if (target !== trunk) return { ...raw, grantVerdict: null, cureVerdict: null, releaseOnlyVerdict: null };
|
|
12838
|
+
|
|
12839
|
+
// #736: the release-only door goes FIRST — no tracker read and no evidence to measure, only which
|
|
12840
|
+
// workflow is red and what the branch touches. It admits a branch over a red the repo declared
|
|
12841
|
+
// release-only; a refusal falls through to the cure rule and the grant exactly as before (a branch
|
|
12842
|
+
// that touches a red check's paths must show that check green itself — which is the cure rule).
|
|
12843
|
+
const releaseOnlyVerdict = releaseOnlyThunk ? releaseOnlyThunk(redSha) : null;
|
|
12844
|
+
if (releaseOnlyVerdict && releaseOnlyVerdict.ok) {
|
|
12845
|
+
return {
|
|
12846
|
+
name: raw.name, ok: true, class: null,
|
|
12847
|
+
detail: `PRECONDITION OVERRIDDEN by the release-only door (#736) — ${trunk}@${shortSha(redSha)} is red only on release-only check(s), IGNORED for this merge: ${releaseOnly.ignoredList(releaseOnlyVerdict.ignored)}; the branch touches none of their paths. The red still blocks a release cut (raw: ${raw.detail})`,
|
|
12848
|
+
grantVerdict: null, cureVerdict: null, releaseOnlyVerdict, redSha,
|
|
12849
|
+
};
|
|
12850
|
+
}
|
|
12783
12851
|
|
|
12784
12852
|
const cureVerdict = cureThunk ? cureThunk(redSha) : null;
|
|
12785
12853
|
if (cureVerdict && cureVerdict.ok) {
|
|
@@ -12793,7 +12861,7 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
|
|
|
12793
12861
|
return {
|
|
12794
12862
|
name: raw.name, ok: true, class: null,
|
|
12795
12863
|
detail: `PRECONDITION OVERRIDDEN by the cure rule (#281) — branch contains red ${shortSha(redSha)} and is green at its own head${via}${viaDry} (raw: ${raw.detail})`,
|
|
12796
|
-
grantVerdict: null, cureVerdict, redSha,
|
|
12864
|
+
grantVerdict: null, cureVerdict, releaseOnlyVerdict, redSha,
|
|
12797
12865
|
};
|
|
12798
12866
|
}
|
|
12799
12867
|
|
|
@@ -12808,21 +12876,22 @@ function applyRedTrunkExemptions(raw, target, trunk, redSha, grantThunk, cureThu
|
|
|
12808
12876
|
return {
|
|
12809
12877
|
name: raw.name, ok: true, class: null,
|
|
12810
12878
|
detail: `PRECONDITION OVERRIDDEN by ${who} on ${by} — trunk was red at ${shortSha(redSha)} (raw: ${raw.detail})`,
|
|
12811
|
-
grantVerdict, cureVerdict, redSha,
|
|
12879
|
+
grantVerdict, cureVerdict, releaseOnlyVerdict, redSha,
|
|
12812
12880
|
};
|
|
12813
12881
|
}
|
|
12814
12882
|
// #534: both doors were consulted and both refused — say WHY on the row itself, so the prose table,
|
|
12815
12883
|
// `--dry`, and B1's abort line all tell "needs a grant" from "missing evidence" from "stacked". The
|
|
12816
12884
|
// JSON payload already carried `ciCure.reason`; the prose detail used to end at the raw trunk read.
|
|
12817
|
-
return { ...raw, detail: `${raw.detail}${doorRefusalNote(cureVerdict, grantVerdict)}`, grantVerdict, cureVerdict, redSha };
|
|
12885
|
+
return { ...raw, detail: `${raw.detail}${doorRefusalNote(cureVerdict, grantVerdict, releaseOnlyVerdict)}`, grantVerdict, cureVerdict, releaseOnlyVerdict, redSha };
|
|
12818
12886
|
}
|
|
12819
12887
|
|
|
12820
12888
|
/**
|
|
12821
|
-
* Which red-trunk door let a trunk-CI row pass — `'cure rule'`, `'ci-grant'`, or null for a row that
|
|
12889
|
+
* Which red-trunk door let a trunk-CI row pass — `'release-only door'` (#736), `'cure rule'`, `'ci-grant'`, or null for a row that
|
|
12822
12890
|
* passed on its own (green) or did not pass (#538: B1 re-measures only a door the table relied on).
|
|
12823
12891
|
*/
|
|
12824
12892
|
function doorThatAdmitted(ciResult) {
|
|
12825
12893
|
if (!ciResult || !ciResult.ok) return null;
|
|
12894
|
+
if (ciResult.releaseOnlyVerdict && ciResult.releaseOnlyVerdict.ok) return 'release-only door';
|
|
12826
12895
|
if (ciResult.cureVerdict && ciResult.cureVerdict.ok) return 'cure rule';
|
|
12827
12896
|
if (ciResult.grantVerdict && ciResult.grantVerdict.ok) return 'ci-grant';
|
|
12828
12897
|
return null;
|
|
@@ -12838,8 +12907,9 @@ const B1_REMEASURE_MS = Number.isFinite(Number(process.env.COLAB_B1_REMEASURE_MS
|
|
|
12838
12907
|
* cure's `reason`, the grant's per-issue `missing[].reason` — never a re-wording, so the prose and
|
|
12839
12908
|
* the `--dry --json` fields cannot read differently.
|
|
12840
12909
|
*/
|
|
12841
|
-
function doorRefusalNote(cureVerdict, grantVerdict) {
|
|
12910
|
+
function doorRefusalNote(cureVerdict, grantVerdict, releaseOnlyVerdict = null) {
|
|
12842
12911
|
const parts = [];
|
|
12912
|
+
if (releaseOnlyVerdict && !releaseOnlyVerdict.ok && releaseOnlyVerdict.reason) parts.push(`release-only door (#736): ${releaseOnlyVerdict.reason}`);
|
|
12843
12913
|
if (cureVerdict && !cureVerdict.ok && cureVerdict.reason) parts.push(`cure rule (#281): ${cureVerdict.reason}`);
|
|
12844
12914
|
if (grantVerdict && !grantVerdict.ok) {
|
|
12845
12915
|
const why = (grantVerdict.missing || []).map((m) => (m.issue ? `#${m.issue}: ` : '') + m.reason)
|
|
@@ -13139,6 +13209,22 @@ function priorExemptionRedJobs(repoAbs, trunk, stacking) {
|
|
|
13139
13209
|
return raw === null ? null : ciCure.redJobSet(raw);
|
|
13140
13210
|
}
|
|
13141
13211
|
|
|
13212
|
+
/**
|
|
13213
|
+
* #736: the trunk-CI-green row's --dry --json additive payload for the release-only door — built from
|
|
13214
|
+
* the SAME verdict shipCiCheck computed. `null` when the door was not consulted or had nothing to say
|
|
13215
|
+
* (nothing declared, a green trunk, a red that is not a finished run), so a repo that declares nothing
|
|
13216
|
+
* sees `releaseOnly: null` and nothing else changes.
|
|
13217
|
+
*/
|
|
13218
|
+
function releaseOnlyPayload(ciResult) {
|
|
13219
|
+
const v = ciResult && ciResult.releaseOnlyVerdict;
|
|
13220
|
+
if (!v) return null;
|
|
13221
|
+
return {
|
|
13222
|
+
ok: v.ok, reason: v.reason, redSha: v.redSha || null,
|
|
13223
|
+
ignored: (v.ignored || []).map((x) => ({ ...x })),
|
|
13224
|
+
touched: (v.touched || []).map((x) => ({ check: x.check, paths: x.paths.slice() })),
|
|
13225
|
+
};
|
|
13226
|
+
}
|
|
13227
|
+
|
|
13142
13228
|
/**
|
|
13143
13229
|
* The trunk-CI-green row's --dry --json additive payload for the cure rule (#281), parallel to
|
|
13144
13230
|
* `ciGrantPayload` above and built from the SAME cureVerdict `shipCiCheck` already computed (never
|
|
@@ -13382,6 +13468,7 @@ function cmdShipDryJson(opts) {
|
|
|
13382
13468
|
// that same check, below. Parallel to ciGrantPayloadVal, never both non-null at once (the cure
|
|
13383
13469
|
// rule short-circuits before the grant is even consulted once it succeeds).
|
|
13384
13470
|
let ciCurePayloadVal = null;
|
|
13471
|
+
let releaseOnlyPayloadVal = null; // #736
|
|
13385
13472
|
// #293: null unless the sha this branch was cut from turned out to be measurably red — see
|
|
13386
13473
|
// `baseCiAdvisory`'s doc comment. ADVISORY ONLY: never folds into `ok` — the `checks` row it also
|
|
13387
13474
|
// produces (below) is always `ok: true` for the same reason.
|
|
@@ -13406,7 +13493,7 @@ function cmdShipDryJson(opts) {
|
|
|
13406
13493
|
const body = {
|
|
13407
13494
|
ok, dry: true, repo: shortRepo(repoAbs), branch: sess.branch, worktree: sess.name || null,
|
|
13408
13495
|
target, mode, issues: sess.issues, closeIssues, refsIssues, checklistFindings, refsBrakeFindings, checks,
|
|
13409
|
-
migrationGrant: migrationGrantPayload, ciGrant: ciGrantPayloadVal, ciCure: ciCurePayloadVal,
|
|
13496
|
+
migrationGrant: migrationGrantPayload, ciGrant: ciGrantPayloadVal, ciCure: ciCurePayloadVal, releaseOnly: releaseOnlyPayloadVal,
|
|
13410
13497
|
baseCi: baseCiPayloadVal, dirtyOwners: dirtyOwnersPayloadVal, autonomyGate: autonomyGatePayloadVal,
|
|
13411
13498
|
coreReview: coreReviewPayloadVal,
|
|
13412
13499
|
...machineTrailerPayload(mode === 'squash' || mode === 'pr-pending'),
|
|
@@ -13471,6 +13558,7 @@ function cmdShipDryJson(opts) {
|
|
|
13471
13558
|
() => shipDocsOnlyCi(repoAbs, doc, target, sess.branch)); // #711: the #482 door learns the #606 measurement
|
|
13472
13559
|
ciGrantPayloadVal = ciGrantPayload(ciResultJson);
|
|
13473
13560
|
ciCurePayloadVal = ciCurePayload(ciResultJson);
|
|
13561
|
+
releaseOnlyPayloadVal = releaseOnlyPayload(ciResultJson);
|
|
13474
13562
|
checks.push({ name: ciResultJson.name, ok: ciResultJson.ok, class: ciResultJson.class, detail: ciResultJson.detail });
|
|
13475
13563
|
|
|
13476
13564
|
// #293: advisory only — was the sha this branch was cut from actually green? Always `ok: true`
|
|
@@ -15323,6 +15411,7 @@ function cmdShip(argv) {
|
|
|
15323
15411
|
// never silently ride the same exemption twice.
|
|
15324
15412
|
let ciGrantForTrailer = null; // #105: set below when B1 shipped UNDER a grant — read at commit-message time
|
|
15325
15413
|
let ciCureForTrailer = null; // #281: set below when B1 shipped UNDER the cure rule — read at commit-message time
|
|
15414
|
+
let releaseOnlyForTrailer = null; // #736: set below when B1 shipped over a release-only red — read at commit-message time
|
|
15326
15415
|
if (gh || forgeCi(repoAbs)) { // #678: a forge's CI is re-read at B1 exactly as GitHub's is
|
|
15327
15416
|
const measureB1 = () => shipCiCheck(repoAbs, gh, target, trunk,
|
|
15328
15417
|
(redSha) => shipCiGrants(repoAbs, gh, sess.issues, sess.branch, trunk, redSha),
|
|
@@ -15350,7 +15439,10 @@ function cmdShip(argv) {
|
|
|
15350
15439
|
: `✗ B1: CI for ${target} is no longer green — aborting before merge. Nothing pushed. (${ciResultB1.detail})\n`);
|
|
15351
15440
|
return 1;
|
|
15352
15441
|
}
|
|
15353
|
-
if (ciResultB1.
|
|
15442
|
+
if (ciResultB1.releaseOnlyVerdict && ciResultB1.releaseOnlyVerdict.ok) {
|
|
15443
|
+
warn(` ✓ trunk CI green ONLY because the red is on release-only check(s), ignored for this merge: ${releaseOnly.ignoredList(ciResultB1.releaseOnlyVerdict.ignored)} — this merge carries a CI-Release-Only: trailer; the red still blocks a release cut.`);
|
|
15444
|
+
releaseOnlyForTrailer = ciResultB1.releaseOnlyVerdict;
|
|
15445
|
+
} else if (ciResultB1.cureVerdict && ciResultB1.cureVerdict.ok) {
|
|
15354
15446
|
warn(ciResultB1.cureVerdict.carveOut
|
|
15355
15447
|
? ` ✓ trunk CI green ONLY because of the machine-checkable cure rule, through the #321 WORKFLOW CARVE-OUT (this branch edits .github/workflows/**; jobs proven: ${ciResultB1.cureVerdict.carveOut.jobs.map((j) => j.name).join(', ')}) — this merge carries a CI-Cure: trailer.`
|
|
15356
15448
|
: ` ✓ trunk CI green ONLY because of the machine-checkable cure rule — this merge carries a CI-Cure: trailer.`);
|
|
@@ -15464,7 +15556,8 @@ function cmdShip(argv) {
|
|
|
15464
15556
|
// rule short-circuits before the grant is even consulted once it succeeds), so at most one of
|
|
15465
15557
|
// these two calls ever returns non-null.
|
|
15466
15558
|
const ciTrailer = ciGrantTrailerLine(ciGrantForTrailer, sess.branch, target) ||
|
|
15467
|
-
ciCureTrailerLine(ciCureForTrailer, sess.branch, target)
|
|
15559
|
+
ciCureTrailerLine(ciCureForTrailer, sess.branch, target) ||
|
|
15560
|
+
releaseOnlyTrailerLine(releaseOnlyForTrailer, sess.branch, target); // #736 — the three doors are exclusive per B1
|
|
15468
15561
|
// #324: an adopted remote-only branch records WHOSE work this was — there is no issue to comment
|
|
15469
15562
|
// on (a zero-claim ship by definition), so the immutable squash is the one place it survives.
|
|
15470
15563
|
// #367: on a public repo the host tail is dropped — the branch and sha stay, they are the audit trail.
|
|
@@ -15490,7 +15583,7 @@ function cmdShip(argv) {
|
|
|
15490
15583
|
for (const tl of ciTrailerLines) {
|
|
15491
15584
|
if (commitMsg.toLowerCase().includes(tl.toLowerCase())) continue;
|
|
15492
15585
|
const lastLine = commitMsg.split('\n').pop().trim();
|
|
15493
|
-
commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
|
|
15586
|
+
commitMsg += (/^(?:Co-authored-by|Signed-off-by|Claude-Session|Reviewed-by|CI-Grant|CI-Cure|CI-Release-Only|Colab-Adopted|Colab-Handoff|Machine):\s*\S/i.test(lastLine) ? '\n' : '\n\n') + tl;
|
|
15494
15587
|
}
|
|
15495
15588
|
} else {
|
|
15496
15589
|
// Preserve the branch's crafted commit (subject + footers); insert Closes/Refs above the footers.
|
|
@@ -16810,6 +16903,8 @@ scheduled finalize, a dispatch, a deploy — comes after the verdict and is set
|
|
|
16810
16903
|
the detail (--json: setAside). Override in .github/project.yml, by workflow name:
|
|
16811
16904
|
ship-gate-workflows: [CI] exactly these workflows count, whatever their trigger
|
|
16812
16905
|
ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered
|
|
16906
|
+
release-only-checks (#736) never changes this verdict: a red on a release-only check is RED here;
|
|
16907
|
+
only ship's per-branch release-only door reads that key.
|
|
16813
16908
|
|
|
16814
16909
|
The first output word is one verdict:
|
|
16815
16910
|
GREEN every judged workflow's newest run at the sha succeeded — ship's row would pass
|
package/tools/lib/config-set.js
CHANGED
|
@@ -46,7 +46,7 @@ const TUNING_KEYS = Object.freeze(Object.keys(TUNING));
|
|
|
46
46
|
* can say WHY it refuses them; any key outside TUNING is refused all the same.
|
|
47
47
|
*/
|
|
48
48
|
const AUTHORITY_KEYS = Object.freeze([
|
|
49
|
-
'autonomy', 'promotion', 'migration-grant', 'ci-grant', 'trust-humans',
|
|
49
|
+
'autonomy', 'promotion', 'migration-grant', 'ci-grant', 'release-only-checks', 'trust-humans',
|
|
50
50
|
'exposure', 'tier', 'trunk', 'deploy', 'release', 'production',
|
|
51
51
|
]);
|
|
52
52
|
|
package/tools/lib/git.js
CHANGED
|
@@ -1348,6 +1348,10 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1348
1348
|
// row it meets, which can be a `skipped` one beside a real failure; a caller asking "did any run
|
|
1349
1349
|
// finish red here" reads this list instead. Absent when none did.
|
|
1350
1350
|
...(opts && opts.finishedRed && judged.some(isFinishedRed) ? { finishedRed: excludedRunSummary(judged.filter(isFinishedRed)) } : {}),
|
|
1351
|
+
// #736: opt-in (`opts.heads`) — the JUDGED heads themselves (newest run per counted workflow, the
|
|
1352
|
+
// wholly skipped set aside), so the release-only door can tell which workflow made the sha red.
|
|
1353
|
+
// Absent unless asked, exactly like `finishedRed`.
|
|
1354
|
+
...(opts && opts.heads ? { heads: excludedRunSummary(judged) } : {}),
|
|
1351
1355
|
// #651: the rows came from the unfiltered listing because the forge's filter index was empty.
|
|
1352
1356
|
...(allForSha.some((x) => x && x.readVia === 'unfiltered-listing') ? { readVia: 'unfiltered-listing' } : {}),
|
|
1353
1357
|
};
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #736: checks that matter only to a RELEASE — building and installing the shipped artifact on a
|
|
4
|
+
* clean machine, signing, publishing. When one of them is red on trunk, every branch used to wait
|
|
5
|
+
* for a ci-grant or a cure, including branches that cannot affect that check at all. Measured: one
|
|
6
|
+
* release-only install lane went red from an untested change, and about six hours of finished work
|
|
7
|
+
* waited behind it, every branch green on every check it could reach.
|
|
8
|
+
*
|
|
9
|
+
* A repo declares those checks in project.yml, each next to the paths it covers:
|
|
10
|
+
*
|
|
11
|
+
* release-only-checks:
|
|
12
|
+
* Install smoke: [packaging/, scripts/install.sh] # a whole workflow (its `name:`)
|
|
13
|
+
* "CI / install (*)": [packaging/**] # one job of a workflow; `*` in the job part
|
|
14
|
+
*
|
|
15
|
+
* `colab ship`'s trunk-CI row then lets ONE branch past a trunk that is red ONLY on declared checks,
|
|
16
|
+
* provided the branch touches none of the paths those red checks cover — a third red-trunk door
|
|
17
|
+
* beside the cure rule (#281) and the ci-grant (#105). Like them it makes nothing green: `colab
|
|
18
|
+
* trunk-ci` still reads the red, and `colab release cut` still refuses at that commit, because
|
|
19
|
+
* neither reads this key. The verifying-runs policy (verify-runs.js) is deliberately untouched, so
|
|
20
|
+
* `ship-ignore-workflows` keeps its one shared meaning for ship and the cut.
|
|
21
|
+
*
|
|
22
|
+
* PURE: a parsed descriptor and run/job/diff facts in, verdicts out. The I/O is tools/colab's
|
|
23
|
+
* shipReleaseOnly. Every doubt refuses: the door is an exemption, and a false refusal costs exactly
|
|
24
|
+
* today's behaviour (the cure rule and the ci-grant are still consulted), while a false admission
|
|
25
|
+
* lands a branch over a red nobody looked at.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
const codeowners = require('./codeowners');
|
|
29
|
+
|
|
30
|
+
const KEY = 'release-only-checks';
|
|
31
|
+
const JOB_SEP = ' / ';
|
|
32
|
+
|
|
33
|
+
/** Conclusions of a run or job that executed nothing — never a red, never a verification. */
|
|
34
|
+
const NEUTRAL = new Set(['skipped', 'neutral']);
|
|
35
|
+
|
|
36
|
+
function unquote(s) {
|
|
37
|
+
const t = String(s).trim();
|
|
38
|
+
if (t.length > 1 && ((t[0] === '"' && t.endsWith('"')) || (t[0] === "'" && t.endsWith("'")))) return t.slice(1, -1).trim();
|
|
39
|
+
return t;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** `*` in a job name matches any run of characters (matrix legs: `install (*)`); the rest is literal. */
|
|
43
|
+
function jobPattern(job) {
|
|
44
|
+
return new RegExp(`^${job.split('*').map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The declaration from a parsed project.yml doc:
|
|
49
|
+
* `{ declared, valid, checks: [{key, workflow, job, paths, res, jobRe}], problems: string[] }`.
|
|
50
|
+
* Any problem makes the whole key invalid and the reader IGNORES it (no exemption at all) — a
|
|
51
|
+
* half-read declaration must never exempt a check its owner did not name. The audit fails it.
|
|
52
|
+
*/
|
|
53
|
+
function parseReleaseOnly(doc) {
|
|
54
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, KEY);
|
|
55
|
+
const none = { declared: false, valid: true, checks: [], problems: [] };
|
|
56
|
+
if (!has || doc[KEY] === null || doc[KEY] === undefined) return none;
|
|
57
|
+
const v = doc[KEY];
|
|
58
|
+
const bad = (why) => ({ declared: true, valid: false, checks: [], problems: [why] });
|
|
59
|
+
if (typeof v !== 'object' || Array.isArray(v)) {
|
|
60
|
+
return bad(`${KEY} must be a map of "<workflow>" or "<workflow> / <job>" to an inline list of the paths that check covers, got ${JSON.stringify(v)}`);
|
|
61
|
+
}
|
|
62
|
+
const entries = Object.entries(v);
|
|
63
|
+
if (!entries.length) return bad(`${KEY} declares no check — remove the key, or name at least one`);
|
|
64
|
+
const problems = [];
|
|
65
|
+
const checks = [];
|
|
66
|
+
for (const [rawKey, rawPaths] of entries) {
|
|
67
|
+
const key = unquote(rawKey);
|
|
68
|
+
// Split at the FIRST ` / ` — the way the forge displays a check ("CI / install (macos)"). A trailing
|
|
69
|
+
// ` /` with nothing after it is a job key with no job, never a workflow named "CI /".
|
|
70
|
+
const m = /^(.*?)\s+\/(?:\s+(.*))?$/.exec(key);
|
|
71
|
+
const workflow = (m ? m[1] : key).trim();
|
|
72
|
+
const job = m ? String(m[2] || '').trim() : null;
|
|
73
|
+
if (!workflow || (m && !job)) { problems.push(`${KEY}: "${key}" names no ${!workflow ? 'workflow' : 'job'}`); continue; }
|
|
74
|
+
const list = typeof rawPaths === 'string' ? [rawPaths] : rawPaths;
|
|
75
|
+
if (!Array.isArray(list) || !list.length) {
|
|
76
|
+
problems.push(`${KEY}: "${key}" must list the paths it covers (a check with no paths would exempt every branch), got ${JSON.stringify(rawPaths)}`);
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
79
|
+
const paths = [];
|
|
80
|
+
const res = [];
|
|
81
|
+
for (const p of list) {
|
|
82
|
+
const s = typeof p === 'string' ? unquote(p) : '';
|
|
83
|
+
const re = s ? codeowners.compile(s) : null;
|
|
84
|
+
if (!re) { problems.push(`${KEY}: "${key}" path ${JSON.stringify(p)} is not a CODEOWNERS-style pattern (no negation, no [ ] ranges)`); continue; }
|
|
85
|
+
paths.push(s);
|
|
86
|
+
res.push(re);
|
|
87
|
+
}
|
|
88
|
+
if (paths.length !== list.length) continue;
|
|
89
|
+
checks.push({ key, workflow, job, paths, res, jobRe: job ? jobPattern(job) : null });
|
|
90
|
+
}
|
|
91
|
+
if (problems.length) return { declared: true, valid: false, checks: [], problems };
|
|
92
|
+
return { declared: true, valid: true, checks, problems: [] };
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The checks that name `workflow`, split into whole-workflow and per-job ones. */
|
|
96
|
+
function checksFor(checks, workflow) {
|
|
97
|
+
const mine = checks.filter((c) => c.workflow === workflow);
|
|
98
|
+
return { whole: mine.find((c) => !c.job) || null, jobs: mine.filter((c) => c.job) };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
function isGreen(c) { return c === 'success'; }
|
|
102
|
+
function isNeutral(c) { return NEUTRAL.has(c); }
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Does the release-only door admit this branch over a red trunk?
|
|
106
|
+
*
|
|
107
|
+
* @param {object} a
|
|
108
|
+
* @param {Array<{workflowName, status, conclusion, databaseId}>|null} a.heads - the JUDGED heads at the
|
|
109
|
+
* red sha (newest run per counted workflow, git.summarizeRunsForCommit `opts.heads`); null = unread
|
|
110
|
+
* @param {(runId:number) => Array<{name, status, conclusion}>|null} [a.jobsOf] - a run's jobs; null = unread
|
|
111
|
+
* @param {string[]|null} a.changed - the paths the branch changes (three-dot diff); null = unread
|
|
112
|
+
* @param {Array} a.checks - parseReleaseOnly's `checks`
|
|
113
|
+
* @returns {{applies:boolean, ok:boolean, reason:string, ignored:Array, touched:Array}}
|
|
114
|
+
* `applies: false` — nothing declared, or the red is not a finished run (none, wedged, in flight):
|
|
115
|
+
* the door has nothing to say and the raw verdict stands with no note.
|
|
116
|
+
*/
|
|
117
|
+
function releaseOnlyVerdict({ heads, jobsOf = null, changed, checks }) {
|
|
118
|
+
const out = (applies, ok, reason, ignored = [], touched = []) => ({ applies, ok, reason, ignored, touched });
|
|
119
|
+
if (!Array.isArray(checks) || !checks.length) return out(false, false, 'no release-only check declared');
|
|
120
|
+
if (!Array.isArray(heads)) return out(true, false, 'could not read the runs at the red sha');
|
|
121
|
+
const unfinished = heads.filter((h) => h.status !== 'completed');
|
|
122
|
+
const red = heads.filter((h) => h.status === 'completed' && !isGreen(h.conclusion) && !isNeutral(h.conclusion));
|
|
123
|
+
if (!red.length) return out(false, false, 'no finished red run at the red sha');
|
|
124
|
+
if (unfinished.length) {
|
|
125
|
+
return out(true, false, `a run is still in flight at the red sha (${unfinished.map((h) => h.workflowName || 'unnamed').join(', ')})`);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
let verifiedElsewhere = heads.some((h) => h.status === 'completed' && isGreen(h.conclusion) && !checksFor(checks, h.workflowName).whole);
|
|
129
|
+
const ignored = [];
|
|
130
|
+
const redChecks = [];
|
|
131
|
+
for (const h of red) {
|
|
132
|
+
const name = h.workflowName || null;
|
|
133
|
+
const runRef = `${name || 'unnamed'}${h.databaseId ? ` (run ${h.databaseId})` : ''}`;
|
|
134
|
+
const { whole, jobs } = name ? checksFor(checks, name) : { whole: null, jobs: [] };
|
|
135
|
+
if (whole) {
|
|
136
|
+
ignored.push({ check: whole.key, workflow: name, job: null, runId: h.databaseId || null, conclusion: h.conclusion });
|
|
137
|
+
redChecks.push(whole);
|
|
138
|
+
continue;
|
|
139
|
+
}
|
|
140
|
+
if (!jobs.length) return out(true, false, `trunk is also red on ${runRef}, which is not a release-only check`);
|
|
141
|
+
const list = jobsOf && h.databaseId ? jobsOf(h.databaseId) : null;
|
|
142
|
+
if (!Array.isArray(list) || !list.length) return out(true, false, `could not read the jobs of ${runRef} to tell a release-only job from the rest`);
|
|
143
|
+
const redJobs = list.filter((j) => j.status === 'completed' && !isGreen(j.conclusion) && !isNeutral(j.conclusion));
|
|
144
|
+
const stillRunning = list.filter((j) => j.status !== 'completed');
|
|
145
|
+
if (stillRunning.length) return out(true, false, `${runRef} still has a job in flight (${stillRunning.map((j) => j.name).join(', ')})`);
|
|
146
|
+
if (!redJobs.length) return out(true, false, `${runRef} is red but no job of it finished red — nothing to attribute the red to`);
|
|
147
|
+
for (const j of redJobs) {
|
|
148
|
+
const c = jobs.find((x) => x.jobRe.test(String(j.name || '')));
|
|
149
|
+
if (!c) return out(true, false, `trunk is also red on ${name} / ${j.name || 'unnamed'} (run ${h.databaseId}), which is not a release-only check`);
|
|
150
|
+
ignored.push({ check: c.key, workflow: name, job: j.name, runId: h.databaseId || null, conclusion: j.conclusion });
|
|
151
|
+
if (!redChecks.includes(c)) redChecks.push(c);
|
|
152
|
+
}
|
|
153
|
+
if (list.some((j) => j.status === 'completed' && isGreen(j.conclusion) && !jobs.some((x) => x.jobRe.test(String(j.name || ''))))) verifiedElsewhere = true;
|
|
154
|
+
}
|
|
155
|
+
if (!verifiedElsewhere) {
|
|
156
|
+
return out(true, false, 'nothing but release-only checks verified the red sha — no other check ran green there', ignored);
|
|
157
|
+
}
|
|
158
|
+
if (!Array.isArray(changed)) return out(true, false, 'could not read the branch diff to check it against the release-only paths', ignored);
|
|
159
|
+
const touched = [];
|
|
160
|
+
for (const c of redChecks) {
|
|
161
|
+
const hits = changed.filter((p) => c.res.some((re) => re.test(p)));
|
|
162
|
+
if (hits.length) touched.push({ check: c.key, paths: hits });
|
|
163
|
+
}
|
|
164
|
+
if (touched.length) {
|
|
165
|
+
const t = touched.map((x) => `${x.paths.slice(0, 3).join(', ')}${x.paths.length > 3 ? ` (+${x.paths.length - 3})` : ''} — covered by "${x.check}"`).join('; ');
|
|
166
|
+
return out(true, false, `the branch touches what a red release-only check covers (${t}), so it must show that check green on itself — the cure rule or a ci-grant`, ignored, touched);
|
|
167
|
+
}
|
|
168
|
+
return out(true, true, `trunk is red only on release-only check(s), and the branch touches none of their paths`, ignored);
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** The compact list a detail or trailer names the ignored red by: `Install smoke (run 7), CI / install (macos) (run 9)`. */
|
|
172
|
+
function ignoredList(ignored) {
|
|
173
|
+
const seen = new Set();
|
|
174
|
+
const parts = [];
|
|
175
|
+
for (const x of ignored || []) {
|
|
176
|
+
const s = `${x.workflow}${x.job ? `${JOB_SEP}${x.job}` : ''}${x.runId ? ` (run ${x.runId})` : ''}`;
|
|
177
|
+
if (!seen.has(s)) { seen.add(s); parts.push(s); }
|
|
178
|
+
}
|
|
179
|
+
return parts.join(', ');
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
module.exports = { KEY, JOB_SEP, parseReleaseOnly, releaseOnlyVerdict, ignoredList };
|