@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13790 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,822 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/release-cut.js — the decision behind `colab release cut` (#338).
|
|
4
|
+
*
|
|
5
|
+
* CONVENTIONS.md §6's release rung lets an agent cut a release CANDIDATE, `vX.Y.Z-rc.N`, where the
|
|
6
|
+
* rung row says so and only once four conditions hold on the exact commit the tag names. This module
|
|
7
|
+
* is that decision, pure: facts in (what the CLI measured from git, `gh` and project.yml), a verdict
|
|
8
|
+
* out — a list of named checks, each `ok` or not, and the tag to create when every one is.
|
|
9
|
+
*
|
|
10
|
+
* PURE BY CONSTRUCTION, the ci-verdict.js / release-policy.js posture: no git, no network, no `gh`,
|
|
11
|
+
* no clock. Every refusal is reachable from `node --test` without a fixture repo; the CLI tests in
|
|
12
|
+
* release-cut-cli.test.js cover the measuring half.
|
|
13
|
+
*
|
|
14
|
+
* The checks, in the order they are reported (the `condition` names are a closed vocabulary — a
|
|
15
|
+
* caller reading `--json` keys on them):
|
|
16
|
+
*
|
|
17
|
+
* release-policy the rung row + the repo's `release:` block (release-policy.js — the SAME
|
|
18
|
+
* reading the audit uses) leave `candidates: auto`
|
|
19
|
+
* prerelease-trigger no deploy workflow fires on a pre-release tag (workflow-triggers.js — the
|
|
20
|
+
* SAME logic as the audit's #332 check, not a second copy)
|
|
21
|
+
* version a patch/minor bump is owed and allowed: never a major, never 0.x -> 1.0,
|
|
22
|
+
* never onto a version that is already final
|
|
23
|
+
* already-candidate the commit does not already carry a candidate of this version
|
|
24
|
+
* ci-green §6 condition 1 — every run at the sha finished, one succeeded
|
|
25
|
+
* full-suite §6 condition 2 — every workflow that ran at the sha has a successful run
|
|
26
|
+
* schema-additive §6 condition 3 — no destructive migration since the last final tag
|
|
27
|
+
* switch-dependencies §6 condition 4 — the colab:switch markers are readable, and no finished
|
|
28
|
+
* switch needs one that is still unfinished
|
|
29
|
+
*
|
|
30
|
+
* manifest-version #424 — the tag equals every declared manifest's version (release-tag.js)
|
|
31
|
+
* on-trunk #424 — the commit is an ancestor of the release branch, `main` — on every
|
|
32
|
+
* trunk shape (§6: never tag from `dev`); a shallow checkout is a refusal
|
|
33
|
+
* outranks-final #424 — the version is strictly greater than the highest final tag
|
|
34
|
+
* cadence #422, --auto only — a declared release.candidates-per-day cap (no route has
|
|
35
|
+
* one by default since #443); inside the window the run is a NO-OP
|
|
36
|
+
* (verdict.noop), not a refusal, and the first run after it cuts main's head
|
|
37
|
+
* already-candidate (above) under --auto, head already carrying a candidate is a NO-OP (#443):
|
|
38
|
+
* the newest candidate names head, which is the guarantee holding
|
|
39
|
+
* promotion #429, --auto on `trunk:` other than `main` only — `main`'s head is a promotion
|
|
40
|
+
* of trunk (a --no-ff merge whose later parent is on trunk, or a fast-forward
|
|
41
|
+
* onto trunk). Any other head is a NO-OP, like cadence; an unread trunk refuses.
|
|
42
|
+
* Absent entirely on `trunk: main`, so that repo's --json is unchanged.
|
|
43
|
+
*
|
|
44
|
+
* `--auto` (#422) computes the bump with no human input (autoSignals + decideAutoVersion): commit
|
|
45
|
+
* types, a repo guard's result and an exports diff, majors included — a major only with a migration
|
|
46
|
+
* section carrying its measured cost (parseMigrationSection). Every signal is written into the tag
|
|
47
|
+
* message, so the reason for the bump is recorded mechanically.
|
|
48
|
+
*
|
|
49
|
+
* Never a final tag. Finalizing a candidate is the release skill's (#339), and a final is a human
|
|
50
|
+
* act on every row where a tag reaches production.
|
|
51
|
+
*/
|
|
52
|
+
|
|
53
|
+
const migrationPaths = require('./migration-paths');
|
|
54
|
+
const releaseTag = require('./release-tag');
|
|
55
|
+
|
|
56
|
+
const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
|
|
57
|
+
const BUMPS = Object.freeze(['patch', 'minor']);
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The branch a candidate is cut on and a final is tagged on — `main`, whatever `trunk:` says (§6:
|
|
61
|
+
* "Do not tag from `dev`"). This is NOT project.yml's `trunk:`; on `trunk: dev` the two differ and
|
|
62
|
+
* the candidate is cut on the promotion merge (#429).
|
|
63
|
+
*/
|
|
64
|
+
const RELEASE_BRANCH = 'main';
|
|
65
|
+
|
|
66
|
+
const CONDITIONS = Object.freeze([
|
|
67
|
+
'release-policy', 'cadence', 'promotion', 'prerelease-trigger', 'version', 'already-candidate',
|
|
68
|
+
...releaseTag.PRE_TAG_CONDITIONS,
|
|
69
|
+
'ci-green', 'full-suite', 'schema-additive', 'switch-dependencies',
|
|
70
|
+
]);
|
|
71
|
+
|
|
72
|
+
/** The file a major's migration section is read from, at the candidate commit (#422). */
|
|
73
|
+
const MIGRATION_FILE = 'MIGRATION.md';
|
|
74
|
+
|
|
75
|
+
/** `vX.Y.Z` -> { major, minor, patch }, or null for anything else (a candidate included). */
|
|
76
|
+
function parseVersion(tag) {
|
|
77
|
+
const m = VERSION_RE.exec(String(tag || ''));
|
|
78
|
+
return m ? { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) } : null;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function formatVersion(v) { return `v${v.major}.${v.minor}.${v.patch}`; }
|
|
82
|
+
|
|
83
|
+
function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
|
|
84
|
+
|
|
85
|
+
/** The candidate numbers already used for `version` (`vX.Y.Z`) among `tags`, ascending. */
|
|
86
|
+
function candidateNumbers(tags, version) {
|
|
87
|
+
const re = new RegExp(`^${escapeRe(version)}-rc\\.([1-9][0-9]*)$`);
|
|
88
|
+
return (tags || []).map((t) => re.exec(t)).filter(Boolean).map((m) => Number(m[1])).sort((a, b) => a - b);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** Next `N` for `vX.Y.Z-rc.N`: one past the highest used, so a deleted rc.2 is never re-issued over rc.3. */
|
|
92
|
+
function nextCandidateNumber(tags, version) {
|
|
93
|
+
const used = candidateNumbers(tags, version);
|
|
94
|
+
return used.length ? used[used.length - 1] + 1 : 1;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Which version the candidate is for.
|
|
99
|
+
*
|
|
100
|
+
* lastFinal the nearest final tag on main (release-tag.js — candidates skipped), or null
|
|
101
|
+
* suggestion release-status's `semverSuggestion` shape: { bump: 'major'|'minor'|'patch'|null, why }
|
|
102
|
+
* override { bump, reason } from --bump/--reason, either may be absent
|
|
103
|
+
* tags every tag name in the repo, to refuse a version that is already final
|
|
104
|
+
*
|
|
105
|
+
* Returns { ok, detail, version?, bump?, why?, overridden? }. Refusal order is deliberate: a request
|
|
106
|
+
* for a major is refused before anything is read about the commits, because no fact changes it.
|
|
107
|
+
*/
|
|
108
|
+
function decideVersion({ lastFinal, suggestion, override, tags }) {
|
|
109
|
+
const o = override || {};
|
|
110
|
+
const s = suggestion || { bump: null, why: 'no suggestion' };
|
|
111
|
+
const refuse = (detail) => ({ ok: false, detail });
|
|
112
|
+
|
|
113
|
+
if (o.bump !== undefined && o.bump !== null) {
|
|
114
|
+
if (o.bump === 'major') {
|
|
115
|
+
return refuse('--bump major refused: a major — including the pre-1.0 -> 1.0.0 step — is a human decision (CONVENTIONS.md §6, Versioning); no flag lets an agent cut one');
|
|
116
|
+
}
|
|
117
|
+
if (!BUMPS.includes(o.bump)) return refuse(`--bump ${JSON.stringify(o.bump)} is not patch or minor`);
|
|
118
|
+
if (!o.reason || !String(o.reason).trim()) {
|
|
119
|
+
return refuse(`--bump ${o.bump} needs --reason "<why>": an override of the computed bump is recorded on the tag, and an unexplained one cannot be`);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
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');
|
|
124
|
+
const last = parseVersion(lastFinal);
|
|
125
|
+
if (!last) return refuse(`the last release tag ${lastFinal} is not vX.Y.Z — cannot compute a bump from it`);
|
|
126
|
+
|
|
127
|
+
let computed = s.bump || null;
|
|
128
|
+
let why = s.why || '';
|
|
129
|
+
if (computed === 'major') {
|
|
130
|
+
if (last.major > 0) {
|
|
131
|
+
return refuse(`a breaking change since ${lastFinal} (${why}) on a >=1.0 repo — ${last.major + 1}.0.0 is a human decision, so nothing is cut (CONVENTIONS.md §6). ` +
|
|
132
|
+
'If the change is not in fact breaking, a human says so; --bump does not override a detected breaking change');
|
|
133
|
+
}
|
|
134
|
+
computed = 'minor';
|
|
135
|
+
why = `${why}; pre-1.0, a breaking change ships as a minor (SemVer §4, CONVENTIONS.md §6)`;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const bump = o.bump || computed;
|
|
139
|
+
if (!bump) {
|
|
140
|
+
return refuse(`${why || 'no bump computed'} — nothing to cut. If a release is owed anyway, pass --bump patch|minor --reason "<why>"`);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
const next = bump === 'minor'
|
|
144
|
+
? { major: last.major, minor: last.minor + 1, patch: 0 }
|
|
145
|
+
: { major: last.major, minor: last.minor, patch: last.patch + 1 };
|
|
146
|
+
// Unreachable through the arithmetic above — kept so a future edit that lets a major through
|
|
147
|
+
// fails here, loudly, rather than tagging one.
|
|
148
|
+
if (next.major !== last.major) return refuse(`${formatVersion(next)} changes the major version — a human decision`);
|
|
149
|
+
|
|
150
|
+
const version = formatVersion(next);
|
|
151
|
+
if ((tags || []).includes(version)) return refuse(`${version} is already a final tag — a candidate for a released version is meaningless`);
|
|
152
|
+
|
|
153
|
+
const overridden = o.bump && o.bump !== computed ? { from: computed, to: o.bump, reason: String(o.reason).trim() } : null;
|
|
154
|
+
const detail = overridden
|
|
155
|
+
? `${lastFinal} -> ${version} (${bump}, overridden from ${computed || 'no bump'}: ${overridden.reason})`
|
|
156
|
+
: `${lastFinal} -> ${version} (${bump}: ${why})`;
|
|
157
|
+
return { ok: true, detail, version, bump, why, overridden };
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
// ---- --auto: the computed bump (#422) ---------------------------------------------------------
|
|
161
|
+
//
|
|
162
|
+
// CONVENTIONS.md §6, *Versioning*: fixes/chores -> patch; a feature or an epic's switch-removal child
|
|
163
|
+
// -> minor; a breaking change -> minor below 1.0, major from 1.0. Breaking is read from three places,
|
|
164
|
+
// because the break that bites is the one the commit types do not reveal:
|
|
165
|
+
//
|
|
166
|
+
// commits `!` / `BREAKING CHANGE:` since the last final
|
|
167
|
+
// guard a repo-declared detector (project.yml `release.guard-run` — a command — or
|
|
168
|
+
// `release.guard-result` — a file an earlier CI step wrote). THE CONTRACT: one JSON object
|
|
169
|
+
// { "breaking": true|false, "findings": ["<one line each>"] } on stdout / in the file.
|
|
170
|
+
// Exit non-zero, unparseable output or a missing file is a REFUSAL — an unread guard is
|
|
171
|
+
// not a clean one. The command runs at the repo root with COLAB_RELEASE_FROM (the last
|
|
172
|
+
// final tag) and COLAB_RELEASE_SHA (the commit being tagged) in its environment.
|
|
173
|
+
// exports a removed or renamed public export since the last final: package.json `exports`
|
|
174
|
+
// subpaths and `bin` names, plus — when `release.exports` names one — a committed list
|
|
175
|
+
// of public symbols, one per line (`#` comments allowed); a line gone is a break (a
|
|
176
|
+
// rename is a removal plus an addition).
|
|
177
|
+
|
|
178
|
+
/** Validate one guard's raw output against the contract. Returns { name, breaking, findings } or { name, error }. */
|
|
179
|
+
function parseGuardOutput(name, text) {
|
|
180
|
+
let j;
|
|
181
|
+
try { j = JSON.parse(String(text || '').trim()); } catch (e) {
|
|
182
|
+
return { name, error: `${name} output is not JSON (${e.message}) — expected {"breaking": bool, "findings": [string]}` };
|
|
183
|
+
}
|
|
184
|
+
if (!j || typeof j !== 'object' || Array.isArray(j) || typeof j.breaking !== 'boolean') {
|
|
185
|
+
return { name, error: `${name} output has no boolean "breaking" — expected {"breaking": bool, "findings": [string]}` };
|
|
186
|
+
}
|
|
187
|
+
const findings = j.findings === undefined ? [] : j.findings;
|
|
188
|
+
if (!Array.isArray(findings) || findings.some((f) => typeof f !== 'string')) {
|
|
189
|
+
return { name, error: `${name} "findings" is not a list of strings` };
|
|
190
|
+
}
|
|
191
|
+
return { name, breaking: j.breaking, findings };
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
function pkgExportKeys(pkg) {
|
|
195
|
+
const keys = new Set();
|
|
196
|
+
if (!pkg || typeof pkg !== 'object') return keys;
|
|
197
|
+
const ex = pkg.exports;
|
|
198
|
+
if (typeof ex === 'string' || Array.isArray(ex)) keys.add('exports:.');
|
|
199
|
+
else if (ex && typeof ex === 'object') {
|
|
200
|
+
const sub = Object.keys(ex).filter((k) => k.startsWith('.'));
|
|
201
|
+
if (sub.length) for (const k of sub) keys.add(`exports:${k}`);
|
|
202
|
+
else keys.add('exports:.'); // a conditions-only map is the root export
|
|
203
|
+
}
|
|
204
|
+
if (typeof pkg.bin === 'string') keys.add(`bin:${pkg.name || '(package name)'}`);
|
|
205
|
+
else if (pkg.bin && typeof pkg.bin === 'object') for (const k of Object.keys(pkg.bin)) keys.add(`bin:${k}`);
|
|
206
|
+
return keys;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
function listLines(text) {
|
|
210
|
+
return new Set(String(text || '').split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* Removed public exports between the last final (`before`) and the candidate (`after`).
|
|
215
|
+
* before/after { pkg: string|null, list: string|null } — package.json text and the declared list
|
|
216
|
+
* file's text at each side (null = absent)
|
|
217
|
+
* listFile release.exports, or null
|
|
218
|
+
* Returns { removed: [string], detail } or { error }.
|
|
219
|
+
*/
|
|
220
|
+
function exportsDiff({ before, after, listFile }) {
|
|
221
|
+
const parse = (t, side) => {
|
|
222
|
+
if (t === null || t === undefined) return { pkg: null };
|
|
223
|
+
try { return { pkg: JSON.parse(t) }; } catch (e) { return { error: `package.json at ${side} does not parse (${e.message})` }; }
|
|
224
|
+
};
|
|
225
|
+
const b = parse(before && before.pkg, 'the last final');
|
|
226
|
+
const a = parse(after && after.pkg, 'the candidate');
|
|
227
|
+
if (b.error || a.error) return { error: b.error || a.error };
|
|
228
|
+
const removed = [];
|
|
229
|
+
const bk = pkgExportKeys(b.pkg); const ak = pkgExportKeys(a.pkg);
|
|
230
|
+
for (const k of bk) if (!ak.has(k)) removed.push(`package.json ${k.replace(':', ' ')}`);
|
|
231
|
+
const read = ['package.json exports/bin'];
|
|
232
|
+
if (listFile) {
|
|
233
|
+
if (!after || after.list === null || after.list === undefined) {
|
|
234
|
+
return { error: `release.exports names ${listFile}, which does not exist at the candidate — an unread export list is not a clean one` };
|
|
235
|
+
}
|
|
236
|
+
if (before && before.list !== null && before.list !== undefined) {
|
|
237
|
+
const al = listLines(after.list);
|
|
238
|
+
for (const l of listLines(before.list)) if (!al.has(l)) removed.push(`${listFile}: ${l}`);
|
|
239
|
+
read.push(listFile);
|
|
240
|
+
} else read.push(`${listFile} (new since the last final — no baseline)`);
|
|
241
|
+
}
|
|
242
|
+
return { removed, detail: removed.length ? `removed export(s): ${removed.join('; ')}` : `no export removed (read: ${read.join(', ')})` };
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* Switch-removal children (`role=remove`) closed done after `sinceIso` — each one makes the release a
|
|
247
|
+
* minor. `only` (#429), a Set of issue numbers, replaces the date filter: on `trunk:` other than
|
|
248
|
+
* `main` an issue closes when it merges to trunk, not when it is promoted, so the caller passes the
|
|
249
|
+
* issues whose closing keyword is in the promoted range and the close date stops deciding.
|
|
250
|
+
*/
|
|
251
|
+
function switchRemovalsSince(issues, sinceIso, { only = null } = {}) {
|
|
252
|
+
const since = Date.parse(sinceIso || '');
|
|
253
|
+
const out = [];
|
|
254
|
+
for (const issue of issues || []) {
|
|
255
|
+
if (!closedDone(issue)) continue;
|
|
256
|
+
if (only) {
|
|
257
|
+
if (!only.has(Number(issue.number))) continue;
|
|
258
|
+
} else {
|
|
259
|
+
const closed = Date.parse(issue.closedAt || '');
|
|
260
|
+
if (!Number.isNaN(since) && !(closed > since)) continue;
|
|
261
|
+
}
|
|
262
|
+
const { markers } = parseSwitchMarkers(issue.body);
|
|
263
|
+
for (const mk of markers) if (mk.role === 'remove') out.push({ number: issue.number, name: mk.name });
|
|
264
|
+
}
|
|
265
|
+
return out;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/**
|
|
269
|
+
* Every bump signal, gathered — the input decideAutoVersion reads and the lines the release notes
|
|
270
|
+
* print. `cc` is ccSummary's shape { total, counts, breaking }; `guard` is null (none declared) or a
|
|
271
|
+
* parseGuardOutput result; `exports` an exportsDiff result; `switchRemovals` switchRemovalsSince's.
|
|
272
|
+
* Returns { total, breaking: [why], minor: [why], patch: [why], unread: [why], lines: [string] }.
|
|
273
|
+
*/
|
|
274
|
+
function autoSignals({ cc, guard, exports: ex, switchRemovals }) {
|
|
275
|
+
const c = cc || { total: 0, counts: {}, breaking: false };
|
|
276
|
+
const counts = c.counts || {};
|
|
277
|
+
const sig = { total: c.total || 0, breaking: [], minor: [], patch: [], unread: [], lines: [] };
|
|
278
|
+
const line = (s) => sig.lines.push(s);
|
|
279
|
+
|
|
280
|
+
if (c.breaking) { sig.breaking.push('a commit marked breaking (! or BREAKING CHANGE:)'); line('commits: breaking — a commit marked ! or BREAKING CHANGE:'); }
|
|
281
|
+
else line('commits: no commit marked breaking');
|
|
282
|
+
if (counts.feat) sig.minor.push(`${counts.feat} feat commit(s)`);
|
|
283
|
+
if (sig.total) {
|
|
284
|
+
const parts = Object.entries(counts).filter(([, n]) => n).map(([t, n]) => `${n} ${t}`);
|
|
285
|
+
line(`commits: ${sig.total} since the last final (${parts.join(', ') || 'none typed'})`);
|
|
286
|
+
if (!counts.feat) sig.patch.push(`${sig.total} commit(s), none a feature`);
|
|
287
|
+
} else line('commits: none since the last final');
|
|
288
|
+
|
|
289
|
+
const sw = switchRemovals || [];
|
|
290
|
+
if (sw.length) {
|
|
291
|
+
sig.minor.push(`switch-removal child merged: ${sw.map((s) => `#${s.number} (${s.name})`).join(', ')}`);
|
|
292
|
+
line(`switches: removed — ${sw.map((s) => `#${s.number} ${s.name}`).join(', ')}`);
|
|
293
|
+
} else line('switches: no switch-removal child merged');
|
|
294
|
+
|
|
295
|
+
if (!guard) line('guard: none declared (release.guard-run / release.guard-result)');
|
|
296
|
+
else if (guard.error) { sig.unread.push(`guard ${guard.error}`); line(`guard: UNREAD — ${guard.error}`); }
|
|
297
|
+
else {
|
|
298
|
+
if (guard.breaking) sig.breaking.push(`guard ${guard.name} reported a breaking change`);
|
|
299
|
+
line(`guard ${guard.name}: ${guard.breaking ? 'BREAKING' : 'not breaking'}${guard.findings.length ? ` — ${guard.findings.join('; ')}` : ''}`);
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
if (!ex) line('exports: not read');
|
|
303
|
+
else if (ex.error) { sig.unread.push(`exports: ${ex.error}`); line(`exports: UNREAD — ${ex.error}`); }
|
|
304
|
+
else {
|
|
305
|
+
if (ex.removed.length) sig.breaking.push(`${ex.removed.length} public export(s) removed or renamed`);
|
|
306
|
+
line(`exports: ${ex.detail}`);
|
|
307
|
+
}
|
|
308
|
+
return sig;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* The section of MIGRATION.md for `version` (vX.0.0): a heading naming it, up to the next heading of
|
|
313
|
+
* the same or a higher level, carrying a non-empty `Measured cost:` line. Returns { ok, section, detail }.
|
|
314
|
+
*/
|
|
315
|
+
function parseMigrationSection(text, version) {
|
|
316
|
+
if (text === null || text === undefined) {
|
|
317
|
+
return { ok: false, section: null, detail: `no ${MIGRATION_FILE} at the candidate commit — a major needs a migration section for ${version} with its measured cost (CONVENTIONS.md §6, Versioning)` };
|
|
318
|
+
}
|
|
319
|
+
const lines = String(text).split(/\r?\n/);
|
|
320
|
+
const want = escapeRe(version);
|
|
321
|
+
let start = -1; let level = 0;
|
|
322
|
+
for (let i = 0; i < lines.length; i++) {
|
|
323
|
+
const h = /^(#{1,6})\s+(.*)$/.exec(lines[i]);
|
|
324
|
+
if (h && new RegExp(`(^|[^0-9A-Za-z.])${want}([^0-9A-Za-z.-]|$)`).test(h[2])) { start = i; level = h[1].length; break; }
|
|
325
|
+
}
|
|
326
|
+
if (start === -1) return { ok: false, section: null, detail: `${MIGRATION_FILE} has no heading naming ${version} — a major needs its own migration section` };
|
|
327
|
+
let end = lines.length;
|
|
328
|
+
for (let i = start + 1; i < lines.length; i++) {
|
|
329
|
+
const h = /^(#{1,6})\s/.exec(lines[i]);
|
|
330
|
+
if (h && h[1].length <= level) { end = i; break; }
|
|
331
|
+
}
|
|
332
|
+
const section = lines.slice(start, end).join('\n').trim();
|
|
333
|
+
if (!/^\s*(?:[-*]\s*)?\**Measured cost:?\**:?\s*\S/im.test(section)) {
|
|
334
|
+
return { ok: false, section, detail: `${MIGRATION_FILE}'s ${version} section has no non-empty "Measured cost:" line — a major states what adopters must change and how much of it was measured` };
|
|
335
|
+
}
|
|
336
|
+
return { ok: true, section, detail: `${MIGRATION_FILE} carries a ${version} migration section with its measured cost` };
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
/**
|
|
340
|
+
* --auto's version: the bump from `signals` (autoSignals), no override possible.
|
|
341
|
+
* migration (version) => parseMigrationSection result — asked only when the bump is a major
|
|
342
|
+
* Returns decideVersion's shape plus { signals, migration }.
|
|
343
|
+
*/
|
|
344
|
+
function decideAutoVersion({ lastFinal, signals, migration, tags }) {
|
|
345
|
+
const refuse = (detail, extra = {}) => ({ ok: false, detail, ...extra });
|
|
346
|
+
const s = signals || { total: 0, breaking: [], minor: [], patch: [], unread: [] };
|
|
347
|
+
if (s.unread && s.unread.length) return refuse(`a bump signal could not be read — fail closed: ${s.unread.join('; ')}`);
|
|
348
|
+
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');
|
|
349
|
+
const last = parseVersion(lastFinal);
|
|
350
|
+
if (!last) return refuse(`the last release tag ${lastFinal} is not vX.Y.Z — cannot compute a bump from it`);
|
|
351
|
+
if (!s.total && !s.breaking.length && !s.minor.length) return refuse(`nothing merged since ${lastFinal} — nothing to cut`, { nothing: true });
|
|
352
|
+
|
|
353
|
+
let bump; let why;
|
|
354
|
+
if (s.breaking.length) {
|
|
355
|
+
if (last.major === 0) { bump = 'minor'; why = `${s.breaking.join('; ')} — pre-1.0, a breaking change ships as a minor (SemVer §4)`; }
|
|
356
|
+
else { bump = 'major'; why = s.breaking.join('; '); }
|
|
357
|
+
} else if (s.minor.length) { bump = 'minor'; why = s.minor.join('; '); }
|
|
358
|
+
else { bump = 'patch'; why = s.patch.join('; ') || 'fixes/chores only'; }
|
|
359
|
+
|
|
360
|
+
const next = bump === 'major' ? { major: last.major + 1, minor: 0, patch: 0 }
|
|
361
|
+
: bump === 'minor' ? { major: last.major, minor: last.minor + 1, patch: 0 }
|
|
362
|
+
: { major: last.major, minor: last.minor, patch: last.patch + 1 };
|
|
363
|
+
const version = formatVersion(next);
|
|
364
|
+
let mig = null;
|
|
365
|
+
if (bump === 'major') {
|
|
366
|
+
mig = typeof migration === 'function' ? migration(version) : (migration || null);
|
|
367
|
+
if (!mig || !mig.ok) {
|
|
368
|
+
return refuse(`${lastFinal} -> ${version} is a major (${why}), refused: ${mig ? mig.detail : `no migration section read for ${version}`}`, { bump, migration: mig });
|
|
369
|
+
}
|
|
370
|
+
}
|
|
371
|
+
if ((tags || []).includes(version)) return refuse(`${version} is already a final tag — a candidate for a released version is meaningless`);
|
|
372
|
+
return { ok: true, detail: `${lastFinal} -> ${version} (${bump}, computed: ${why})`, version, bump, why, overridden: null, migration: mig };
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
// ---- --auto: cadence (#422) ------------------------------------------------------------------
|
|
376
|
+
|
|
377
|
+
/**
|
|
378
|
+
* The route's candidates-per-day cap as a rolling 24h window. `candidates` is [{ name, date }] for
|
|
379
|
+
* every candidate `colab release cut` made (date = tagger date); `perDay` null = uncapped.
|
|
380
|
+
* Returns { ok, detail, nextAt }. Not ok is a NO-OP for the caller, never a refusal.
|
|
381
|
+
*/
|
|
382
|
+
function cadenceVerdict({ candidates, perDay, now }) {
|
|
383
|
+
if (perDay === null || perDay === undefined) return { ok: true, detail: 'no candidates-per-day cap on this route', nextAt: null };
|
|
384
|
+
const nowMs = Date.parse(now);
|
|
385
|
+
const recent = (candidates || []).map((c) => ({ ...c, ms: Date.parse(c.date) }))
|
|
386
|
+
.filter((c) => !Number.isNaN(c.ms) && c.ms > nowMs - 86400000 && c.ms <= nowMs)
|
|
387
|
+
.sort((a, b) => a.ms - b.ms);
|
|
388
|
+
if (recent.length < perDay) return { ok: true, detail: `${recent.length} candidate(s) in the last 24h, cap ${perDay}`, nextAt: null };
|
|
389
|
+
const nextAt = new Date(recent[recent.length - perDay].ms + 86400000).toISOString();
|
|
390
|
+
return { ok: false, detail: `${recent.length} candidate(s) in the last 24h (${recent.map((c) => c.name).join(', ')}) — release.candidates-per-day caps at ${perDay} a day; the first run from ${nextAt} cuts main's head, never an older commit`, nextAt };
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
// ---- #443: the newest candidate names trunk's head -------------------------------------------
|
|
394
|
+
|
|
395
|
+
/** Events that run DOWNSTREAM of the suite (the release workflow itself) — never part of "head is green". */
|
|
396
|
+
const DOWNSTREAM_EVENTS = Object.freeze(['workflow_run', 'schedule', 'workflow_dispatch']);
|
|
397
|
+
|
|
398
|
+
/**
|
|
399
|
+
* #443's guarantee, read back: once main's head is green, the newest candidate names it. `colab
|
|
400
|
+
* release-status` flags a head that has been green for longer than one CI cycle and carries no tag.
|
|
401
|
+
*
|
|
402
|
+
* candidatesAuto the effective policy says candidates: auto (else nothing is owed: 'off')
|
|
403
|
+
* sha main's head
|
|
404
|
+
* tagsAtSha every tag pointing at it — a candidate OR a final names it
|
|
405
|
+
* owed commits on main since the last final (0 = nothing to release; null = no final yet)
|
|
406
|
+
* runs `gh run list --commit <sha>` rows: {status, conclusion, event, createdAt,
|
|
407
|
+
* updatedAt}; null when the read failed
|
|
408
|
+
* promotion on `trunk:` other than main, measurePromotion's verdict — a head that is not a
|
|
409
|
+
* promotion is cut by hand, never by --auto, so it is not flagged (null elsewhere)
|
|
410
|
+
* now ISO timestamp (the module stays clock-free)
|
|
411
|
+
*
|
|
412
|
+
* "One CI cycle" is measured, not configured: the longest suite run at this sha (updatedAt -
|
|
413
|
+
* createdAt). The release workflow fires when the suite completes, so a head still untagged one
|
|
414
|
+
* whole suite-duration after it went green is one the release run did not tag.
|
|
415
|
+
*
|
|
416
|
+
* Returns { state, flag, detail, greenAt, cycleMs } — state is one of: off · named · nothing-owed ·
|
|
417
|
+
* not-promotion · unread · not-green · pending · untagged. Only `untagged` flags.
|
|
418
|
+
*/
|
|
419
|
+
function headCandidateVerdict({ candidatesAuto, sha, tagsAtSha, owed, runs, promotion, now }) {
|
|
420
|
+
const at = `main@${String(sha || '').slice(0, 7)}`;
|
|
421
|
+
const out = (state, detail, extra = {}) => ({ state, flag: state === 'untagged', detail, greenAt: null, cycleMs: null, ...extra });
|
|
422
|
+
if (!candidatesAuto) return out('off', 'candidates are not automatic here — nothing names the head by itself');
|
|
423
|
+
const named = (tagsAtSha || []).filter((t) => /^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[1-9][0-9]*)?$/.test(t));
|
|
424
|
+
if (named.length) return out('named', `${at} is ${named.join(', ')}`);
|
|
425
|
+
if (owed === 0) return out('nothing-owed', `nothing merged on main since the last final — no candidate is owed`);
|
|
426
|
+
if (owed === null || owed === undefined) return out('nothing-owed', 'no final tag yet — the first version is a human decision, so no candidate is owed');
|
|
427
|
+
if (promotion && !promotion.ok) return out('not-promotion', `${at} is not a promotion of trunk — --auto never cuts it (${promotion.detail})`);
|
|
428
|
+
if (!Array.isArray(runs)) return out('unread', `gh run list failed — cannot tell whether ${at} is green`);
|
|
429
|
+
const suite = runs.filter((r) => r && !DOWNSTREAM_EVENTS.includes(r.event));
|
|
430
|
+
if (!suite.length) return out('not-green', `no suite run at ${at} yet — nothing is owed until it is green`);
|
|
431
|
+
if (suite.some((r) => r.status !== 'completed')) return out('not-green', `a suite run at ${at} is still in flight`);
|
|
432
|
+
if (suite.some((r) => r.conclusion !== 'success' && r.conclusion !== 'cancelled')) return out('not-green', `${at} is not green — no candidate is owed for a red head`);
|
|
433
|
+
const ok = suite.filter((r) => r.conclusion === 'success');
|
|
434
|
+
if (!ok.length) return out('not-green', `no successful suite run at ${at}`);
|
|
435
|
+
const ms = (x) => Date.parse(x);
|
|
436
|
+
const greenMs = Math.max(...ok.map((r) => ms(r.updatedAt)).filter((n) => !Number.isNaN(n)));
|
|
437
|
+
const cycleMs = Math.max(0, ...ok.map((r) => ms(r.updatedAt) - ms(r.createdAt)).filter((n) => !Number.isNaN(n)));
|
|
438
|
+
if (!Number.isFinite(greenMs)) return out('unread', `the suite runs at ${at} carry no completion time`);
|
|
439
|
+
const greenAt = new Date(greenMs).toISOString();
|
|
440
|
+
const untaggedMs = ms(now) - greenMs;
|
|
441
|
+
const mins = (n) => `${Math.round(n / 60000)}m`;
|
|
442
|
+
if (untaggedMs <= cycleMs) return out('pending', `${at} went green at ${greenAt}; inside one CI cycle (${mins(cycleMs)}) — the release run may still tag it`, { greenAt, cycleMs });
|
|
443
|
+
return out('untagged', `${at} has been green since ${greenAt} (${mins(untaggedMs)}, longer than one CI cycle of ${mins(cycleMs)}) and carries no candidate — head not a candidate`, { greenAt, cycleMs });
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
/**
|
|
447
|
+
* The GitHub pre-release a candidate gets (#443): `gh release create` arguments, notes = the tag's
|
|
448
|
+
* own message. The release workflow publishes its own; a candidate cut by hand published none, so
|
|
449
|
+
* the CLI now does it for every cut — the workflow's publish step then finds it and skips.
|
|
450
|
+
*/
|
|
451
|
+
function prereleaseArgs(tag, notesFile) {
|
|
452
|
+
return ['release', 'create', tag, '--verify-tag', '--title', tag, '--notes-file', notesFile, '--prerelease', '--latest=false'];
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
// ---- §6 condition 2: the full suite ------------------------------------------------------------
|
|
456
|
+
|
|
457
|
+
/**
|
|
458
|
+
* `rows` is `git.ghRunsForCommit`'s list for the sha (null when the read failed). Condition 1 (the
|
|
459
|
+
* ship check) treats a `cancelled` sibling as not-bad — right for a cancel-in-progress straggler
|
|
460
|
+
* next to its own re-run, wrong for "the suite passed": a workflow whose only run at the sha was
|
|
461
|
+
* cancelled never ran its tests. So: group by workflow, and every workflow needs a successful run.
|
|
462
|
+
*/
|
|
463
|
+
function fullSuiteVerdict(rows, at) {
|
|
464
|
+
if (rows === null || rows === undefined) return { ok: false, detail: `gh run list failed — cannot confirm the suite ran at ${at}` };
|
|
465
|
+
if (!rows.length) return { ok: false, detail: `no workflow run at ${at} — the suite never ran on this commit` };
|
|
466
|
+
const byWorkflow = new Map();
|
|
467
|
+
for (const r of rows) {
|
|
468
|
+
const name = r.workflowName || '(unnamed workflow)';
|
|
469
|
+
if (!byWorkflow.has(name)) byWorkflow.set(name, []);
|
|
470
|
+
byWorkflow.get(name).push(r);
|
|
471
|
+
}
|
|
472
|
+
const missing = [];
|
|
473
|
+
for (const [name, runs] of byWorkflow) {
|
|
474
|
+
if (!runs.some((r) => r.status === 'completed' && r.conclusion === 'success')) {
|
|
475
|
+
missing.push(`${name} (${runs.map((r) => (r.status === 'completed' ? r.conclusion || 'none' : r.status)).join(', ')})`);
|
|
476
|
+
}
|
|
477
|
+
}
|
|
478
|
+
if (missing.length) return { ok: false, detail: `no successful run at ${at} for: ${missing.join('; ')}` };
|
|
479
|
+
return { ok: true, detail: `${byWorkflow.size} workflow(s) at ${at}, each with a successful run` };
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
/**
|
|
483
|
+
* The run rows minus the CALLING workflow's own runs (#425). Inside the release workflow
|
|
484
|
+
* (templates/release-auto.yml) `release cut` / `release finalize` read the runs at the very commit
|
|
485
|
+
* that workflow is running on — and its own run is one of them, still in progress. Counted, it makes
|
|
486
|
+
* ci-green "not every run finished" and full-suite "no successful run" forever, and a refused run's
|
|
487
|
+
* red conclusion would poison the next run's read the same way. The release workflow is never part of
|
|
488
|
+
* the suite it judges, so its rows are dropped — keyed on GITHUB_WORKFLOW (the running workflow's
|
|
489
|
+
* `name:`), and only when GITHUB_ACTIONS says we are inside Actions. Off Actions: rows unchanged.
|
|
490
|
+
* null (a failed read) passes through untouched.
|
|
491
|
+
*/
|
|
492
|
+
function withoutOwnWorkflow(rows, env = process.env) {
|
|
493
|
+
if (!Array.isArray(rows)) return rows;
|
|
494
|
+
const own = env && env.GITHUB_ACTIONS === 'true' ? String(env.GITHUB_WORKFLOW || '') : '';
|
|
495
|
+
if (!own) return rows;
|
|
496
|
+
return rows.filter((r) => (r && r.workflowName) !== own);
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
// ---- §6 condition 3: schema changes are additive -----------------------------------------------
|
|
500
|
+
|
|
501
|
+
/**
|
|
502
|
+
* The migration layouts `colab ship`'s migration gate reads — one rule for both, and it lives in
|
|
503
|
+
* migration-paths.js (#383): the two defaults plus whatever project.yml `migrations:` declares
|
|
504
|
+
* (`declared` = that module's normalised prefixes; omitted = the defaults alone).
|
|
505
|
+
*/
|
|
506
|
+
function isMigrationPath(f, declared) {
|
|
507
|
+
return migrationPaths.isMigrationPath(f, declared);
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
// Laravel schema-builder calls that destroy or rewrite existing structure. Read only inside `up()`:
|
|
511
|
+
// a `down()` that drops what `up()` created is the ordinary shape of an ADDITIVE migration.
|
|
512
|
+
const LARAVEL_DESTRUCTIVE = /(\b(drop|dropIfExists|dropColumn|dropColumns|dropForeign|dropConstrainedForeignId|dropIndex|dropPrimary|dropUnique|dropSoftDeletes|dropTimestamps|dropMorphs|dropRememberToken|rename|renameColumn|renameIndex)\s*\(|->\s*change\s*\()/;
|
|
513
|
+
// SQL (Prisma writes plain migration.sql). `--` comment lines are stripped first: Prisma labels its
|
|
514
|
+
// statements `-- DropIndex`, which is a comment, not a statement.
|
|
515
|
+
const SQL_DESTRUCTIVE = /\b(DROP\s+(TABLE|COLUMN|INDEX|CONSTRAINT|TYPE|VIEW|SCHEMA)|RENAME\s+(TO|COLUMN)|ALTER\s+COLUMN|TRUNCATE)\b/i;
|
|
516
|
+
|
|
517
|
+
function laravelUpBody(text) {
|
|
518
|
+
const up = text.search(/function\s+up\s*\(/);
|
|
519
|
+
if (up === -1) return text;
|
|
520
|
+
const down = text.slice(up).search(/function\s+down\s*\(/);
|
|
521
|
+
return down === -1 ? text.slice(up) : text.slice(up, up + down);
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
/**
|
|
525
|
+
* `changes` is [{ status, path, content }] for every changed path since the last final tag —
|
|
526
|
+
* `status` is git's --name-status letter (A/M/D/R…), `content` the file at the candidate commit
|
|
527
|
+
* (added files only). Non-migration paths are ignored here.
|
|
528
|
+
*
|
|
529
|
+
* Heuristic, and it says so: it reads two layouts and a list of destructive calls. It fails CLOSED
|
|
530
|
+
* — an edited or deleted migration counts as destructive, because rewriting history a database has
|
|
531
|
+
* already run is not an add. A false positive costs a human cutting the candidate; a false negative
|
|
532
|
+
* is the §6 judgement the release notes still owe (read the diff, not only this).
|
|
533
|
+
*/
|
|
534
|
+
function schemaVerdict(changes, since, declared) {
|
|
535
|
+
const inPaths = (changes || []).filter((c) => isMigrationPath(c.path, declared));
|
|
536
|
+
const migrations = inPaths.filter((c) => /\.(php|sql)$/.test(c.path));
|
|
537
|
+
// #383: a declared path widens what COUNTS as a migration, not what this heuristic can READ. A
|
|
538
|
+
// declared migration in any other format (a Node boot migration, a Go file) is named in the
|
|
539
|
+
// detail, so the §6 judgement the release notes owe knows exactly which files it still has to
|
|
540
|
+
// read by hand — never silently folded into "none destructive". Only for DECLARED paths: under
|
|
541
|
+
// the defaults a non-php/sql file is Prisma's migration_lock.toml and the like, as it always was.
|
|
542
|
+
const unread = (declared && declared.length)
|
|
543
|
+
? inPaths.filter((c) => !/\.(php|sql)$/.test(c.path) && !migrationPaths.isMigrationPath(c.path, []))
|
|
544
|
+
: [];
|
|
545
|
+
const scope = `Laravel database/migrations + Prisma prisma/migrations${declared && declared.length ? ` + declared ${declared.join(', ')} (php/sql only)` : ''} — other layouts are not read`;
|
|
546
|
+
const unreadNote = unread.length
|
|
547
|
+
? `; ${unread.length} declared migration file(s) in a format this check does not read — a human reads them: ${unread.map((c) => c.path).join(', ')}`
|
|
548
|
+
: '';
|
|
549
|
+
if (!migrations.length) return { ok: true, detail: `no migration file changed since ${since} (${scope})${unreadNote}` };
|
|
550
|
+
const findings = [];
|
|
551
|
+
for (const c of migrations) {
|
|
552
|
+
const st = String(c.status || '').charAt(0);
|
|
553
|
+
if (st !== 'A') { findings.push(`${c.path}: ${st === 'D' ? 'deleted' : st === 'R' ? 'renamed' : 'edited'} — an existing migration was rewritten`); continue; }
|
|
554
|
+
const text = String(c.content || '');
|
|
555
|
+
if (c.path.endsWith('.php')) {
|
|
556
|
+
const m = LARAVEL_DESTRUCTIVE.exec(laravelUpBody(text));
|
|
557
|
+
if (m) findings.push(`${c.path}: \`${m[0].trim()}\` in up()`);
|
|
558
|
+
} else {
|
|
559
|
+
const sql = text.split('\n').filter((l) => !/^\s*--/.test(l)).join('\n');
|
|
560
|
+
const m = SQL_DESTRUCTIVE.exec(sql);
|
|
561
|
+
if (m) findings.push(`${c.path}: \`${m[0]}\``);
|
|
562
|
+
}
|
|
563
|
+
}
|
|
564
|
+
if (findings.length) {
|
|
565
|
+
return { ok: false, detail: `destructive schema change since ${since} — a release carrying one is a human's to cut (CONVENTIONS.md §6, Switched epics rule 5): ${findings.join('; ')}` };
|
|
566
|
+
}
|
|
567
|
+
return { ok: true, detail: `${migrations.length} migration file(s) added since ${since}, none destructive (${scope})${unreadNote}` };
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
// ---- §6 condition 4: switch dependencies -------------------------------------------------------
|
|
571
|
+
|
|
572
|
+
const SWITCH_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
|
|
573
|
+
const MARKER_RE = /<!--\s*colab:switch\b([\s\S]*?)-->/g;
|
|
574
|
+
|
|
575
|
+
/**
|
|
576
|
+
* Every `<!-- colab:switch … -->` marker in one issue body (CONVENTIONS.md §5, Switched epics).
|
|
577
|
+
* Returns { markers: [{ name, needs: [], role: null|'add'|'remove' }], malformed: [text] } — an
|
|
578
|
+
* unknown token, a bad name, `needs` on a child, or two markers for one name disagreeing are all
|
|
579
|
+
* `malformed`: "not cleared", reported, never defaulted.
|
|
580
|
+
*/
|
|
581
|
+
function parseSwitchMarkers(body) {
|
|
582
|
+
const markers = [];
|
|
583
|
+
const malformed = [];
|
|
584
|
+
const text = String(body || '');
|
|
585
|
+
let m;
|
|
586
|
+
MARKER_RE.lastIndex = 0;
|
|
587
|
+
while ((m = MARKER_RE.exec(text)) !== null) {
|
|
588
|
+
const raw = m[0];
|
|
589
|
+
const fields = {};
|
|
590
|
+
let bad = null;
|
|
591
|
+
for (const tok of m[1].trim().split(/\s+/).filter(Boolean)) {
|
|
592
|
+
const kv = /^(name|needs|role)=(.*)$/.exec(tok);
|
|
593
|
+
if (!kv) { bad = `unrecognised token ${JSON.stringify(tok)}`; break; }
|
|
594
|
+
if (kv[1] in fields) { bad = `${kv[1]} given twice`; break; }
|
|
595
|
+
fields[kv[1]] = kv[2];
|
|
596
|
+
}
|
|
597
|
+
if (!bad && !fields.name) bad = 'no name=';
|
|
598
|
+
if (!bad && !SWITCH_NAME_RE.test(fields.name)) bad = `name ${JSON.stringify(fields.name)} does not match ${SWITCH_NAME_RE}`;
|
|
599
|
+
if (!bad && fields.role !== undefined && fields.role !== 'add' && fields.role !== 'remove') bad = `role ${JSON.stringify(fields.role)} is not add or remove`;
|
|
600
|
+
if (!bad && fields.role !== undefined && fields.needs !== undefined) bad = 'needs= belongs on the epic marker, not on a role= child marker';
|
|
601
|
+
let needs = [];
|
|
602
|
+
if (!bad && fields.needs !== undefined) {
|
|
603
|
+
needs = fields.needs.split(',').map((s) => s.trim());
|
|
604
|
+
const wrong = needs.find((n) => !SWITCH_NAME_RE.test(n));
|
|
605
|
+
if (wrong !== undefined) bad = `needs names ${JSON.stringify(wrong)}, not a switch name`;
|
|
606
|
+
}
|
|
607
|
+
if (bad) { malformed.push(`${raw.replace(/\s+/g, ' ')}: ${bad}`); continue; }
|
|
608
|
+
markers.push({ name: fields.name, needs: needs.sort(), role: fields.role || null });
|
|
609
|
+
}
|
|
610
|
+
// Two markers on one issue for the same name must agree.
|
|
611
|
+
const seen = new Map();
|
|
612
|
+
for (const mk of markers) {
|
|
613
|
+
const key = JSON.stringify([mk.role, mk.needs]);
|
|
614
|
+
if (seen.has(mk.name) && seen.get(mk.name) !== key) malformed.push(`two colab:switch markers for "${mk.name}" disagree`);
|
|
615
|
+
seen.set(mk.name, key);
|
|
616
|
+
}
|
|
617
|
+
return { markers, malformed };
|
|
618
|
+
}
|
|
619
|
+
|
|
620
|
+
/** Closed by a merge: CLOSED and not closed as not-planned. */
|
|
621
|
+
function closedDone(issue) {
|
|
622
|
+
return String(issue.state || '').toUpperCase() === 'CLOSED' && String(issue.stateReason || '').toUpperCase() !== 'NOT_PLANNED';
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
/**
|
|
626
|
+
* `issues` is [{ number, state, stateReason, body }] — every issue in the repo (null when the read
|
|
627
|
+
* failed). A switch EXISTS once a `role=add` child is closed done, is FINISHED once a `role=remove`
|
|
628
|
+
* child is. Rule 3: a finished switch whose epic `needs` another that is not finished is a release
|
|
629
|
+
* the configuration never supported — B shipped live on top of an A that is still dark.
|
|
630
|
+
*
|
|
631
|
+
* Reads the markers only. The `blocked_by` edge that enforces rule 3 before a merge is not re-read
|
|
632
|
+
* here: this is the release-time consequence, not the edge audit.
|
|
633
|
+
*/
|
|
634
|
+
function switchVerdict(issues) {
|
|
635
|
+
if (issues === null || issues === undefined) return { ok: false, detail: 'the issue list could not be read — switch dependencies cannot be cleared' };
|
|
636
|
+
const problems = [];
|
|
637
|
+
const needsOf = new Map(); // name -> { needs: [..], from: #N }
|
|
638
|
+
const declared = new Set();
|
|
639
|
+
const finished = new Set();
|
|
640
|
+
const exists = new Set();
|
|
641
|
+
for (const issue of issues) {
|
|
642
|
+
const { markers, malformed } = parseSwitchMarkers(issue.body);
|
|
643
|
+
for (const bad of malformed) problems.push(`#${issue.number}: ${bad}`);
|
|
644
|
+
for (const mk of markers) {
|
|
645
|
+
declared.add(mk.name);
|
|
646
|
+
if (mk.role === null) {
|
|
647
|
+
const prev = needsOf.get(mk.name);
|
|
648
|
+
if (prev && JSON.stringify(prev.needs) !== JSON.stringify(mk.needs)) {
|
|
649
|
+
problems.push(`#${prev.from} and #${issue.number} declare switch "${mk.name}" with different needs=`);
|
|
650
|
+
} else if (!prev) needsOf.set(mk.name, { needs: mk.needs, from: issue.number });
|
|
651
|
+
} else if (closedDone(issue)) {
|
|
652
|
+
(mk.role === 'add' ? exists : finished).add(mk.name);
|
|
653
|
+
}
|
|
654
|
+
}
|
|
655
|
+
}
|
|
656
|
+
for (const [name, { needs, from }] of needsOf) {
|
|
657
|
+
for (const dep of needs) {
|
|
658
|
+
if (!declared.has(dep)) problems.push(`#${from}: switch "${name}" needs "${dep}", which no issue declares`);
|
|
659
|
+
else if (finished.has(name) && !finished.has(dep)) {
|
|
660
|
+
problems.push(`switch "${name}" is finished (its role=remove child closed) but needs "${dep}", which is ${exists.has(dep) ? 'still switched' : 'not landed'}`);
|
|
661
|
+
}
|
|
662
|
+
}
|
|
663
|
+
}
|
|
664
|
+
if (problems.length) return { ok: false, detail: `switch dependencies not cleared (CONVENTIONS.md §5, Switched epics rule 3): ${problems.join('; ')}` };
|
|
665
|
+
if (!declared.size) return { ok: true, detail: 'no colab:switch markers in this repo' };
|
|
666
|
+
const unfinished = [...exists].filter((n) => !finished.has(n));
|
|
667
|
+
return { ok: true, detail: `${declared.size} switch(es) declared — ${finished.size} finished, ${unfinished.length} unfinished (dark in this release); every declared dependency satisfied` };
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
/**
|
|
671
|
+
* #429 — is `main@sha` a promotion of `trunk`? Topology, not the subject line: `colab promote
|
|
672
|
+
* --message` overrides the subject and a hand-run `git merge --no-ff dev` writes git's own.
|
|
673
|
+
* trunk project.yml's `trunk:` (never `main` here — the caller skips the check there)
|
|
674
|
+
* sha, parents the head and its parent shas, first parent first
|
|
675
|
+
* headOnTrunk sha is an ancestor of origin/<trunk> (a fast-forward promotion)
|
|
676
|
+
* mergedFromTrunk some non-first parent is an ancestor of origin/<trunk> (the --no-ff merge)
|
|
677
|
+
* error origin/<trunk> could not be read — an unread trunk is not a clean one
|
|
678
|
+
* Returns { ok, detail, unread }. Not-a-promotion is `ok: false` without `unread`: decide() reads it
|
|
679
|
+
* as a no-op, because a hotfix on `main` is cut by the next promotion or by hand.
|
|
680
|
+
*/
|
|
681
|
+
function promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk, error } = {}) {
|
|
682
|
+
const short = (x) => String(x || '').slice(0, 7);
|
|
683
|
+
if (error) return { ok: false, unread: true, detail: `origin/${trunk} could not be read (${error}) — whether \`${RELEASE_BRANCH}\` is a promotion is unknown, and an unread trunk is not a clean one` };
|
|
684
|
+
if (headOnTrunk) return { ok: true, detail: `${RELEASE_BRANCH}@${short(sha)} is on ${trunk} — a fast-forward promotion` };
|
|
685
|
+
const ps = parents || [];
|
|
686
|
+
if (ps.length >= 2 && mergedFromTrunk) {
|
|
687
|
+
return { ok: true, detail: `${RELEASE_BRANCH}@${short(sha)} promotes ${trunk}@${short(mergedFromTrunk === true ? ps[ps.length - 1] : mergedFromTrunk)}` };
|
|
688
|
+
}
|
|
689
|
+
const what = ps.length >= 2 ? `a merge of a branch not on ${trunk}` : 'a direct commit';
|
|
690
|
+
return { ok: false, detail: `${RELEASE_BRANCH}@${short(sha)} is not a promotion of ${trunk} (${what}) — the next promotion's range carries it; to release it now, cut by hand with \`colab release cut\`` };
|
|
691
|
+
}
|
|
692
|
+
|
|
693
|
+
// ---- the verdict ------------------------------------------------------------------------------
|
|
694
|
+
|
|
695
|
+
/**
|
|
696
|
+
* `facts`:
|
|
697
|
+
* policy release-policy.js evaluateRelease(doc)
|
|
698
|
+
* triggers workflow-triggers.js prereleaseTagTriggers(...) findings
|
|
699
|
+
* lastFinal, suggestion, override, tags, tagsAtSha
|
|
700
|
+
* ci, suite, schema, switches { ok, detail } each, measured by the caller
|
|
701
|
+
*
|
|
702
|
+
* Returns { ok, checks: [{ condition, ok, detail }], refusals, version, tag, bump, overridden }.
|
|
703
|
+
* Every check is reported, not just the first failure: a caller fixing one refusal should not
|
|
704
|
+
* discover the next only on the re-run.
|
|
705
|
+
*/
|
|
706
|
+
function decide(facts) {
|
|
707
|
+
const f = facts || {};
|
|
708
|
+
const checks = [];
|
|
709
|
+
const add = (condition, ok, detail) => checks.push({ condition, ok: !!ok, detail });
|
|
710
|
+
|
|
711
|
+
const p = f.policy;
|
|
712
|
+
if (!p) add('release-policy', false, 'no release policy was evaluated');
|
|
713
|
+
else if (p.findings && p.findings.length) add('release-policy', false, `the release: block is invalid — ${p.findings.map((x) => x.text).join('; ')}`);
|
|
714
|
+
else if (p.effective.candidates !== 'auto') {
|
|
715
|
+
const narrowed = p.declared && p.declared.candidates === 'off' && p.derived.candidates === 'auto';
|
|
716
|
+
add('release-policy', false, narrowed
|
|
717
|
+
? 'release: candidates: off — this repo narrowed its rung row to no automatic candidates'
|
|
718
|
+
: `candidates are off on ${p.derived.axis}: ${p.derived.why} (CONVENTIONS.md §6, The release rung)`);
|
|
719
|
+
} else {
|
|
720
|
+
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`);
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
// #422: --auto honours the route's cadence. Inside the window the run is a no-op, not a refusal.
|
|
724
|
+
let noop = false;
|
|
725
|
+
if (f.auto) {
|
|
726
|
+
const cad = f.auto.cadence || { ok: false, detail: 'cadence not measured' };
|
|
727
|
+
add('cadence', cad.ok, cad.detail);
|
|
728
|
+
if (!cad.ok) noop = !!f.auto.cadence;
|
|
729
|
+
// #429: on `trunk:` other than main, only a promotion head is a candidate; anything else no-ops.
|
|
730
|
+
const pr = f.auto.promotion;
|
|
731
|
+
if (pr) {
|
|
732
|
+
add('promotion', pr.ok, pr.detail);
|
|
733
|
+
if (!pr.ok && !pr.unread) noop = true;
|
|
734
|
+
}
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
const trig = f.triggers || [];
|
|
738
|
+
if (trig.length) add('prerelease-trigger', false, `a deploy would fire on a candidate tag: ${trig.map((t) => t.text).join('; ')}`);
|
|
739
|
+
else add('prerelease-trigger', true, 'no deploy workflow fires on a pre-release tag');
|
|
740
|
+
|
|
741
|
+
const v = f.auto
|
|
742
|
+
? decideAutoVersion({ lastFinal: f.lastFinal, signals: f.auto.signals, migration: f.auto.migration, tags: f.tags })
|
|
743
|
+
: decideVersion({ lastFinal: f.lastFinal, suggestion: f.suggestion, override: f.override, tags: f.tags });
|
|
744
|
+
add('version', v.ok, v.detail);
|
|
745
|
+
// "Nothing merged since the last final" is a no-op for the release workflow, not a failure.
|
|
746
|
+
if (f.auto && v.nothing) noop = true;
|
|
747
|
+
|
|
748
|
+
let tag = null;
|
|
749
|
+
let derivable = [];
|
|
750
|
+
if (v.ok) {
|
|
751
|
+
const here = candidateNumbers(f.tagsAtSha || [], v.version);
|
|
752
|
+
if (here.length) {
|
|
753
|
+
add('already-candidate', false, `this commit is already ${v.version}-rc.${here[here.length - 1]} — a second candidate for the same commit tests nothing new`);
|
|
754
|
+
// #443: under --auto, main's head already carrying a candidate is the guarantee HOLDING — the
|
|
755
|
+
// newest candidate names head — so a re-run (the daily schedule, a CI re-run) is a no-op.
|
|
756
|
+
if (f.auto) noop = true;
|
|
757
|
+
} else {
|
|
758
|
+
tag = `${v.version}-rc.${nextCandidateNumber(f.tags, v.version)}`;
|
|
759
|
+
add('already-candidate', true, `next candidate: ${tag}`);
|
|
760
|
+
}
|
|
761
|
+
}
|
|
762
|
+
|
|
763
|
+
// #424: the three pre-tag checks, on the tag this run would create.
|
|
764
|
+
if (tag) {
|
|
765
|
+
for (const c of releaseTag.preTagChecks({ tag, manifests: f.manifests, ancestry: f.ancestry, tags: f.tags, trunk: RELEASE_BRANCH, versionSource: versionSourceOf(p) })) {
|
|
766
|
+
add(c.condition, c.ok, c.detail);
|
|
767
|
+
if (c.derivable && c.derivable.length) derivable = c.derivable;
|
|
768
|
+
}
|
|
769
|
+
} else if (f.ancestry && f.ancestry.shallow) {
|
|
770
|
+
// A shallow checkout cannot even find the last final, so no tag is computed — name the cause.
|
|
771
|
+
add('on-trunk', false, 'a shallow checkout cannot answer whether the commit is on main (nor find the last final tag) — fetch full history (fetch-depth: 0) and re-run');
|
|
772
|
+
}
|
|
773
|
+
|
|
774
|
+
for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
775
|
+
if (!verdict) add(condition, false, 'not measured');
|
|
776
|
+
else add(condition, verdict.ok, verdict.detail);
|
|
777
|
+
}
|
|
778
|
+
|
|
779
|
+
const refusals = checks.filter((c) => !c.ok);
|
|
780
|
+
const ok = refusals.length === 0 && !!tag;
|
|
781
|
+
return {
|
|
782
|
+
ok, noop: !ok && noop, checks, refusals, version: v.ok ? v.version : null, tag: ok ? tag : null,
|
|
783
|
+
bump: v.ok ? v.bump : (v.bump || null), overridden: v.ok ? v.overridden : null,
|
|
784
|
+
signals: f.auto ? f.auto.signals || null : null, migration: v.migration || null,
|
|
785
|
+
derivable,
|
|
786
|
+
};
|
|
787
|
+
}
|
|
788
|
+
|
|
789
|
+
/** #438: the policy's version source — 'manifest' when there is no policy to read. */
|
|
790
|
+
function versionSourceOf(policy) {
|
|
791
|
+
return policy && policy.effective && policy.effective.versionSource === 'tag' ? 'tag' : 'manifest';
|
|
792
|
+
}
|
|
793
|
+
|
|
794
|
+
/** The annotated tag's message — where the chosen bump, its reason and every checked condition are recorded. */
|
|
795
|
+
function tagMessage(verdict, { sha, lastFinal }) {
|
|
796
|
+
const lines = [
|
|
797
|
+
`${verdict.tag} — release candidate (colab release cut)`,
|
|
798
|
+
'',
|
|
799
|
+
`Commit: ${sha}`,
|
|
800
|
+
`Since: ${lastFinal}`,
|
|
801
|
+
`Bump: ${verdict.bump}${verdict.overridden ? ` (overridden from ${verdict.overridden.from || 'no bump'} — reason: ${verdict.overridden.reason})` : ''}${verdict.signals ? ' (computed by --auto)' : ''}`,
|
|
802
|
+
'',
|
|
803
|
+
...(verdict.signals ? ['Signals (every input the bump read):', ...verdict.signals.lines.map((l) => `- ${l}`), ''] : []),
|
|
804
|
+
...(verdict.migration && verdict.migration.section ? ['Migration:', '', verdict.migration.section, ''] : []),
|
|
805
|
+
...(verdict.derivable && verdict.derivable.length ? [`Derivable manifests (release.version-source: tag, not checked against the tag): ${verdict.derivable.join(', ')}`, ''] : []),
|
|
806
|
+
'Conditions (CONVENTIONS.md §6):',
|
|
807
|
+
...verdict.checks.map((c) => `- ${c.condition}: ${c.detail}`),
|
|
808
|
+
'',
|
|
809
|
+
'A candidate, never a final: finalizing it is the release skill\'s, after its test period.',
|
|
810
|
+
];
|
|
811
|
+
return lines.join('\n') + '\n';
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
module.exports = {
|
|
815
|
+
CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH,
|
|
816
|
+
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
817
|
+
parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict,
|
|
818
|
+
fullSuiteVerdict, withoutOwnWorkflow, isMigrationPath, schemaVerdict,
|
|
819
|
+
parseSwitchMarkers, switchVerdict,
|
|
820
|
+
promotionVerdict, decide, tagMessage, versionSourceOf,
|
|
821
|
+
DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs,
|
|
822
|
+
};
|