@futurelastic/colab-handbook 1.20.3 → 1.20.4-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/package.json +1 -1
- package/templates/README.md +13 -6
- package/templates/ci-laravel-heavy.yml +153 -6
- package/templates/ci-laravel.yml +66 -17
- package/templates/ci-node-heavy.yml +157 -6
- package/templates/ci-node.yml +66 -18
- package/templates/ci-python-heavy.yml +157 -6
- package/templates/ci-python.yml +66 -18
- package/templates/instruction-files.yml +3 -2
- package/templates/publish-downloads.mjs +30 -1
- package/templates/publish-downloads.yml +5 -0
- package/templates/release-auto.yml +53 -7
- package/templates/release-tag.yml +1 -1
- package/tools/colab +89 -15
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/ci-wait.js +16 -2
- package/tools/lib/container-close.js +42 -2
- package/tools/lib/git.js +44 -1
- package/tools/lib/release-cut.js +128 -15
- package/tools/lib/release-finalize.js +3 -1
- package/tools/lib/release-runner.js +1 -1
- package/tools/lib/stale-base.js +15 -2
- package/tools/lib/stamp.js +1 -1
- package/tools/lib/state.js +150 -8
- package/tools/lib/verify-runs.js +207 -15
package/tools/lib/adopt.js
CHANGED
|
@@ -363,7 +363,7 @@ function releaseRungSteps(ctx = {}) {
|
|
|
363
363
|
const texts = ctx.workflowTexts || {};
|
|
364
364
|
const releaseWf = Object.keys(texts).find((f) => /colab release cut/.test(texts[f] || ''));
|
|
365
365
|
if (releaseWf) {
|
|
366
|
-
steps.push({ n: 6, text: `Release workflow present (.github/workflows/${releaseWf}) — check its \`HANDBOOK_REF\` names a ref the handbook carries (#480) and its \`runs-on\` is the self-hosted
|
|
366
|
+
steps.push({ n: 6, text: `Release workflow present (.github/workflows/${releaseWf}) — check its \`HANDBOOK_REF\` names a ref the handbook carries (#480) and its \`runs-on\` is the trunk class, [self-hosted, trunk], on a private repo` });
|
|
367
367
|
} else {
|
|
368
368
|
steps.push({ n: 6, text: 'Copy the release workflow — `colab template release-auto`, then walk its `# EDIT:` points: `HANDBOOK_REF` (a channel or tag the handbook carries, #480), the test-suite workflow `name:`, and on a PRIVATE repo the self-hosted runner label from ci.yml on every job except `npm` (#492)' });
|
|
369
369
|
}
|
package/tools/lib/ci-wait.js
CHANGED
|
@@ -35,6 +35,9 @@ const EXIT = Object.freeze({
|
|
|
35
35
|
RATE_LIMITED: 4,
|
|
36
36
|
UNKNOWN: 5,
|
|
37
37
|
ALREADY_WAITING: 6,
|
|
38
|
+
// #723: the deadline passed with an expected workflow still having NO run at the sha (only other
|
|
39
|
+
// workflows ran there). Not TIMEOUT: nothing is in flight to wait longer for — someone must get it a run.
|
|
40
|
+
NO_RUN: 7,
|
|
38
41
|
});
|
|
39
42
|
|
|
40
43
|
const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
|
|
@@ -112,10 +115,15 @@ function restRow(x) {
|
|
|
112
115
|
* The state of what is being waited on, from a summarized run (`{status, conclusion}`):
|
|
113
116
|
* `green` · `red` · `pending` · `unknown`. `none` (no run at the sha yet) is pending: runs appear
|
|
114
117
|
* seconds after a push, and the deadline bounds the wait if they never do.
|
|
118
|
+
*
|
|
119
|
+
* #723: a summary carrying `missing` (an expected workflow with no run at the sha) is never green —
|
|
120
|
+
* it is pending, like `none`: the run may still appear, and the deadline ends the wait as NO_RUN.
|
|
121
|
+
* A red stays red: a failure that already happened does not wait on a run that has not.
|
|
115
122
|
*/
|
|
116
123
|
function runState(s) {
|
|
117
124
|
if (!s) return 'unknown';
|
|
118
125
|
if (s.status === 'none') return 'pending';
|
|
126
|
+
if (Array.isArray(s.missing) && s.missing.length && s.status === 'completed' && s.conclusion === 'success') return 'pending';
|
|
119
127
|
if (s.status === 'completed') return s.conclusion === 'success' ? 'green' : 'red';
|
|
120
128
|
if (['queued', 'in_progress', 'waiting', 'requested', 'pending'].includes(s.status)) return 'pending';
|
|
121
129
|
return 'unknown';
|
|
@@ -162,7 +170,7 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
|
|
|
162
170
|
const d = delayFor(i, schedule) * 1000;
|
|
163
171
|
if (d) {
|
|
164
172
|
const left = start + deadlineSec * 1000 - now();
|
|
165
|
-
if (left <= 0) return
|
|
173
|
+
if (left <= 0) return deadline(`still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
166
174
|
sleep(Math.min(d, left));
|
|
167
175
|
}
|
|
168
176
|
// The poll that lands on the deadline is the last one: it must read the truth, not a 304.
|
|
@@ -186,7 +194,13 @@ function waitLoop({ poll, sleep, now = Date.now, deadlineSec = DEFAULT_DEADLINE_
|
|
|
186
194
|
if (last.state === 'green') return done('GREEN', null);
|
|
187
195
|
if (last.state === 'red') return done('RED', null);
|
|
188
196
|
if (last.state !== 'pending') return done('UNKNOWN', `unrecognised state (${JSON.stringify(last.summary || null)})`);
|
|
189
|
-
if (now() - start >= deadlineSec * 1000) return
|
|
197
|
+
if (now() - start >= deadlineSec * 1000) return deadline(`still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
198
|
+
}
|
|
199
|
+
// #723: a deadline that passes with an expected workflow still runless is NO_RUN, naming it.
|
|
200
|
+
function deadline(detail) {
|
|
201
|
+
const miss = last && last.summary && Array.isArray(last.summary.missing) ? last.summary.missing : [];
|
|
202
|
+
if (!miss.length) return done('TIMEOUT', detail);
|
|
203
|
+
return done('NO_RUN', `no-run:${miss.map((x) => x.name).join(',')} — no run of ${miss.length === 1 ? 'that workflow' : 'those workflows'} appeared by the ${fmtDuration(deadlineSec * 1000)} deadline`);
|
|
190
204
|
}
|
|
191
205
|
function done(outcome, detail, r) {
|
|
192
206
|
return { outcome, polls, notModified, forced, waitedMs: now() - start, last: last || r || null, detail };
|
|
@@ -20,6 +20,12 @@
|
|
|
20
20
|
* - its body holds no unticked checklist line. An unticked `- [ ]` on an epic is an item
|
|
21
21
|
* somebody listed and nobody filed as a sub-issue yet — the "two phases whose issues are not
|
|
22
22
|
* written yet" B2c's rule was protecting. It is reported, never closed over;
|
|
23
|
+
* - its body states no `Done when` acceptance (#713). `file-issues` tells a filer to put an
|
|
24
|
+
* epic's end state in a `Done when:` line, never a body checklist — so on an epic written to
|
|
25
|
+
* that convention the unticked check above sees nothing, and a phase epic filed with only its
|
|
26
|
+
* design child (the code children to be filed once the design is approved) read as spent the
|
|
27
|
+
* moment that one child shipped. "Every filed child closed" says nothing about whether the
|
|
28
|
+
* stated end state holds; that reading is the coordinator's, so ship proposes and never closes;
|
|
23
29
|
* - it is not a release tracking record (`<!-- colab:release …` body) — `colab release
|
|
24
30
|
* finalize` owns that record's lifecycle, not a child's ship.
|
|
25
31
|
*
|
|
@@ -36,6 +42,8 @@
|
|
|
36
42
|
* children-open at least one sub-issue is still open — the normal state of a live epic
|
|
37
43
|
* not-container every child closed, but no `epic` label — report for a human
|
|
38
44
|
* unfiled-items every child closed, but the body still lists unticked items — report
|
|
45
|
+
* done-when every child closed, but the body states `Done when` acceptance — ship posts
|
|
46
|
+
* a one-line proposal for the coordinator to check it and close (#713)
|
|
39
47
|
*
|
|
40
48
|
* Fail toward keeping open, the same asymmetry `group-labels.js` states for its own delete: a
|
|
41
49
|
* container closed early buries unwritten work behind a closed issue nobody browses, while one
|
|
@@ -52,6 +60,14 @@ const RELEASE_RECORD_RE = /^\s*<!--\s*colab:release\b/;
|
|
|
52
60
|
/** An UNTICKED GitHub checklist line anywhere in the body — `- [ ] …` / `* [ ] …`. */
|
|
53
61
|
const UNTICKED_RE = /^\s*[-*]\s*\[ \]\s*(.+)$/;
|
|
54
62
|
|
|
63
|
+
/**
|
|
64
|
+
* A `Done when` acceptance statement at the start of a line (#713): a heading (`## Done when`), a
|
|
65
|
+
* label line (`Done when:`, `**Done when:**`, `- Done when: …`), any case, `Done-when` too. Only at
|
|
66
|
+
* a line start, so prose that merely mentions the phrase mid-sentence does not count; a blockquote
|
|
67
|
+
* (`> Done when`) is a quotation, not this epic's own acceptance.
|
|
68
|
+
*/
|
|
69
|
+
const DONE_WHEN_RE = /^\s*(?:#{1,6}\s+)?(?:[-*+]\s+)?(?:\*\*|__)?done[ -]when\b/i;
|
|
70
|
+
|
|
55
71
|
function labelNames(labels) {
|
|
56
72
|
return (labels || []).map((l) => (l && typeof l === 'object' ? l.name : l)).map((n) => String(n));
|
|
57
73
|
}
|
|
@@ -70,6 +86,16 @@ function untickedItems(body) {
|
|
|
70
86
|
return out;
|
|
71
87
|
}
|
|
72
88
|
|
|
89
|
+
/** Does the body state `Done when` acceptance outside fenced code? (#713) */
|
|
90
|
+
function hasDoneWhen(body) {
|
|
91
|
+
let fenced = false;
|
|
92
|
+
for (const line of String(body || '').split('\n')) {
|
|
93
|
+
if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; continue; }
|
|
94
|
+
if (!fenced && DONE_WHEN_RE.test(line)) return true;
|
|
95
|
+
}
|
|
96
|
+
return false;
|
|
97
|
+
}
|
|
98
|
+
|
|
73
99
|
/**
|
|
74
100
|
* Classify ONE parent issue after a child of it closed.
|
|
75
101
|
*
|
|
@@ -99,6 +125,7 @@ function classifyContainer(parent) {
|
|
|
99
125
|
if (!labelNames(parent.labels).includes(EPIC_LABEL)) return { ...out, verdict: 'not-container' };
|
|
100
126
|
const unticked = untickedItems(parent.body);
|
|
101
127
|
if (unticked.length) return { ...out, unticked, verdict: 'unfiled-items' };
|
|
128
|
+
if (hasDoneWhen(parent.body)) return { ...out, verdict: 'done-when' };
|
|
102
129
|
return { ...out, verdict: 'close' };
|
|
103
130
|
}
|
|
104
131
|
|
|
@@ -120,6 +147,16 @@ function containerCloseComment({ child, sha, total, target }) {
|
|
|
120
147
|
return `📦 Closed by colab ship — ${via}${at}; all ${total} sub-issue(s) are closed and the body lists no unticked item (#371).`;
|
|
121
148
|
}
|
|
122
149
|
|
|
150
|
+
/**
|
|
151
|
+
* The proposal comment posted on an epic whose verdict is `done-when` (#713) — the epic stays OPEN.
|
|
152
|
+
* One line, issue-specific only: which child emptied it, and what the coordinator checks next.
|
|
153
|
+
*/
|
|
154
|
+
function containerProposalComment({ child, sha, total, target }) {
|
|
155
|
+
const via = child ? `its last open sub-issue #${child} shipped` : 'its last open sub-issue closed';
|
|
156
|
+
const at = sha ? ` to ${target || 'trunk'} at ${sha}` : '';
|
|
157
|
+
return `📋 All ${total} sub-issue(s) closed — ${via}${at}. Left open: check \`Done when\` and close if met, or file the remaining work as sub-issues (#713).`;
|
|
158
|
+
}
|
|
159
|
+
|
|
123
160
|
/** One report line for a verdict that is NOT `close` but still worth a human's eye; null otherwise. */
|
|
124
161
|
function containerFinding(c) {
|
|
125
162
|
const n = c.number !== null ? `#${c.number}` : 'parent';
|
|
@@ -128,6 +165,8 @@ function containerFinding(c) {
|
|
|
128
165
|
return `${n}: all ${c.total} sub-issue(s) closed, but it is not labelled \`epic\` — close it by hand if it is a container`;
|
|
129
166
|
case 'unfiled-items':
|
|
130
167
|
return `${n}: all ${c.total} sub-issue(s) closed, but ${c.unticked.length} unticked item(s) remain in its body — file them as sub-issues or tick them, then close`;
|
|
168
|
+
case 'done-when':
|
|
169
|
+
return `${n}: all ${c.total} sub-issue(s) closed, but its body states \`Done when\` — left open for the coordinator to check it`;
|
|
131
170
|
case 'unknown':
|
|
132
171
|
return `${n}: could not read the parent — container close skipped`;
|
|
133
172
|
default:
|
|
@@ -173,7 +212,8 @@ function parentRelationFinding(rel) {
|
|
|
173
212
|
}
|
|
174
213
|
|
|
175
214
|
module.exports = {
|
|
176
|
-
EPIC_LABEL, RELEASE_RECORD_RE,
|
|
215
|
+
EPIC_LABEL, RELEASE_RECORD_RE, DONE_WHEN_RE,
|
|
177
216
|
issueRepoSlug, parentRelation, parentRelationFinding,
|
|
178
|
-
untickedItems, classifyContainer, containerDeliveryLabels, containerCloseComment,
|
|
217
|
+
untickedItems, hasDoneWhen, classifyContainer, containerDeliveryLabels, containerCloseComment,
|
|
218
|
+
containerProposalComment, containerFinding,
|
|
179
219
|
};
|
package/tools/lib/git.js
CHANGED
|
@@ -1156,6 +1156,23 @@ function ghRunsForRef(repo, ref, sha, limit = 20) {
|
|
|
1156
1156
|
return runs.filter((x) => x && x.headSha === sha);
|
|
1157
1157
|
}
|
|
1158
1158
|
|
|
1159
|
+
/**
|
|
1160
|
+
* #723: the repo's workflows as a Map of file path → `{ state, id, name }` — one REST call. `state`
|
|
1161
|
+
* (`active`, `disabled_manually`, …): a disabled workflow never gets a run, so it is never expected at
|
|
1162
|
+
* a head. `id` / `name` are how its runs identify it (a run's `workflow_id`, its `name`). Null on any
|
|
1163
|
+
* failure: the caller then takes every workflow as active and matches runs by the definition's name.
|
|
1164
|
+
*/
|
|
1165
|
+
function ghWorkflowStates(repo) {
|
|
1166
|
+
const r = gh(['api', 'repos/{owner}/{repo}/actions/workflows?per_page=100'], { cwd: repo });
|
|
1167
|
+
if (!r.ok) return null;
|
|
1168
|
+
let j;
|
|
1169
|
+
try { j = JSON.parse(r.stdout); } catch (_) { return null; }
|
|
1170
|
+
if (!j || !Array.isArray(j.workflows)) return null;
|
|
1171
|
+
const m = new Map();
|
|
1172
|
+
for (const w of j.workflows) if (w && w.path) m.set(w.path, { state: w.state || null, id: w.id ?? null, name: w.name || null });
|
|
1173
|
+
return m;
|
|
1174
|
+
}
|
|
1175
|
+
|
|
1159
1176
|
function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
|
|
1160
1177
|
return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha, opts);
|
|
1161
1178
|
}
|
|
@@ -1267,6 +1284,14 @@ function excludedRunSummary(rows) {
|
|
|
1267
1284
|
* #688: a workflow whose every run at the sha was skipped is then set aside beside a run that can
|
|
1268
1285
|
* verify the code (setAsideWhollySkipped, below); the rows ride along as `skippedOnly`, and `allSkipped`
|
|
1269
1286
|
* says nothing but such workflows ran here. `runCount` no longer counts them (#461's rule).
|
|
1287
|
+
*
|
|
1288
|
+
* #723: `opts.expected` (verify-runs.js `expectedWorkflows(...).expected`, `[{name, path, dispatch}]`)
|
|
1289
|
+
* names the workflows that SHOULD have a run at the sha. One with no counted row there rides along as
|
|
1290
|
+
* `missing` (same entries), present only when non-empty. The summary's status and conclusion are left
|
|
1291
|
+
* exactly as the runs that exist make them — a caller that asked for `expected` reads `missing` and
|
|
1292
|
+
* holds a would-be green (ci-wait.runState, stale-base.githubBranchHeadRedVerdict). Measured: only a
|
|
1293
|
+
* small `instruction-files` workflow ran at a branch head, the repo's CI never got a run there, and the
|
|
1294
|
+
* head read green from that one unrelated run.
|
|
1270
1295
|
*/
|
|
1271
1296
|
function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
1272
1297
|
if (allForSha === null) return null;
|
|
@@ -1280,6 +1305,7 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1280
1305
|
setAside = split.setAside;
|
|
1281
1306
|
dispatchCounted = split.dispatchCounted || [];
|
|
1282
1307
|
}
|
|
1308
|
+
const missing = missingExpected(owned, opts && opts.expected);
|
|
1283
1309
|
const { heads, superseded } = newestRunPerWorkflow(owned);
|
|
1284
1310
|
const { judged, skippedOnly, allSkipped } = setAsideWhollySkipped(heads, superseded, opts && opts.verifying);
|
|
1285
1311
|
const extra = {
|
|
@@ -1289,6 +1315,7 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1289
1315
|
...(allSkipped ? { allSkipped: true } : {}),
|
|
1290
1316
|
...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
|
|
1291
1317
|
...(dispatchCounted.length ? { dispatchCounted: excludedRunSummary(dispatchCounted) } : {}),
|
|
1318
|
+
...(missing.length ? { missing: missing.map((e) => ({ name: e.name, path: e.path || null, dispatch: !!e.dispatch, ...(e.id != null ? { id: e.id } : {}) })) } : {}),
|
|
1292
1319
|
// #691: opt-in (`opts.finishedRed`), so no reader that never asked sees a new field — every
|
|
1293
1320
|
// JUDGED run that finished red: completed, and not success, cancelled or skipped (neither of
|
|
1294
1321
|
// those two executed anything). The summary's single `conclusion` names only the first not-green
|
|
@@ -1302,6 +1329,22 @@ function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
|
1302
1329
|
return { ...r, ...extra };
|
|
1303
1330
|
}
|
|
1304
1331
|
|
|
1332
|
+
/**
|
|
1333
|
+
* #723: the expected workflows with no counted row at the sha. A row stands for an expected workflow
|
|
1334
|
+
* when its workflow FILE id matches (`workflowId`, the workflows API's id), or its name matches the
|
|
1335
|
+
* definition's or the API's. A row carrying neither a name nor an id cannot be told apart from any
|
|
1336
|
+
* workflow, so its presence means nothing is called missing — absence of a field never adds a hold,
|
|
1337
|
+
* the same rule as everywhere above.
|
|
1338
|
+
*/
|
|
1339
|
+
function missingExpected(rows, expected) {
|
|
1340
|
+
const exp = Array.isArray(expected) ? expected.filter((e) => e && e.name) : [];
|
|
1341
|
+
if (!exp.length) return [];
|
|
1342
|
+
if (rows.some((x) => x && !x.workflowName && (x.workflowId === undefined || x.workflowId === null))) return [];
|
|
1343
|
+
const stands = (x, e) => !!x && ((e.id != null && x.workflowId != null && Number(x.workflowId) === Number(e.id))
|
|
1344
|
+
|| x.workflowName === e.name || (!!e.apiName && x.workflowName === e.apiName));
|
|
1345
|
+
return exp.filter((e) => !rows.some((x) => stands(x, e)));
|
|
1346
|
+
}
|
|
1347
|
+
|
|
1305
1348
|
/** #691: a run that ran and failed — completed, and not success, cancelled or skipped. */
|
|
1306
1349
|
function isFinishedRed(x) {
|
|
1307
1350
|
return !!x && x.status === 'completed' && x.conclusion !== 'success' && x.conclusion !== 'cancelled' && x.conclusion !== 'skipped';
|
|
@@ -1624,7 +1667,7 @@ module.exports = {
|
|
|
1624
1667
|
worktreeList, worktreeListDetailed, resolveWorktreePathForBranch, gitFailureLine,
|
|
1625
1668
|
dirtyTracked, dirtyUntracked, dirtyAny,
|
|
1626
1669
|
ghAvailable, ghState, ghInstalled, ghApiConditional, ghRunsAtShaRest, ghRunsAtShaUnfiltered, fullSha, ghIssueEdit, ghListLabels, ghOpenIssueNumbersByLabel, ghAssignedIssues,
|
|
1627
|
-
ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
|
|
1670
|
+
ghCurrentLogin, ghIssueView, ghIssueComment, ghRunForSha, ghRunForCommit, ghRunsForCommit, ghRunsForRef, ghWorkflowStates, ghRunsAtCommit, ghRunForCommitAnyRef, commitTimeMs, ghRunsSince, summarizeRunsForCommit, isRepoOwnedRun,
|
|
1628
1671
|
ghRunJobCount, ghRunJobs, ghActiveRunsOfWorkflow, ghWorkflowDispatch,
|
|
1629
1672
|
ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
|
|
1630
1673
|
ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -675,6 +675,7 @@ function handoffTrackingBody(version) {
|
|
|
675
675
|
'',
|
|
676
676
|
'- The final is automatic on every green head, by the operator\'s grant — but a database migration since the last final never rides an automatic deploy ungranted.',
|
|
677
677
|
`- **To let it ride:** a human runs \`COLAB_HUMAN=1 colab migration-grant <this issue> --branch ${version}\`; the next green run tags and deploys ${version}.`,
|
|
678
|
+
'- The same grant is the person\'s decision a destructive schema change needs here (a dropped column, a rewritten migration): this route has no hand cut, so the grant is how a person lets one ride (#709). Read the migration first — the grant is the review.',
|
|
678
679
|
`- **Veto:** add the \`${HOLD_LABEL}\` label to any open issue. While it is present no final is tagged; only a human removes it.`,
|
|
679
680
|
].join('\n') + '\n';
|
|
680
681
|
}
|
|
@@ -836,26 +837,109 @@ const SQL_DOWN_MARKER = /^\s*--\s*(\+(migrate|goose)\s+down|migrate:down)\b/i;
|
|
|
836
837
|
const SQL_DOWN_FILE = /\.down\.sql$/i;
|
|
837
838
|
|
|
838
839
|
/**
|
|
839
|
-
* The
|
|
840
|
-
*
|
|
841
|
-
*
|
|
842
|
-
*
|
|
840
|
+
* The SQL a migration runs: every line outside a Down section, `--` comment lines (markers included)
|
|
841
|
+
* blanked — Prisma labels its statements `-- DropIndex`. Skipped lines are blanked, not removed, so
|
|
842
|
+
* line numbers stay true and a statement split across lines (`DROP\n TABLE`) still matches, as it
|
|
843
|
+
* did when the whole file was read. `sections[i]` = the section line i+1 sits in.
|
|
843
844
|
*/
|
|
844
|
-
function
|
|
845
|
+
function sqlUpText(text) {
|
|
845
846
|
let section = 'pre';
|
|
846
847
|
const sections = [];
|
|
847
848
|
const kept = String(text).split('\n').map((l) => {
|
|
848
849
|
if (SQL_DOWN_MARKER.test(l)) section = 'down';
|
|
849
850
|
else if (SQL_UP_MARKER.test(l)) section = 'up';
|
|
850
851
|
sections.push(section);
|
|
851
|
-
// `--` comment lines (markers included) are blanked too: Prisma labels its statements `-- DropIndex`.
|
|
852
852
|
return section === 'down' || /^\s*--/.test(l) ? '' : l;
|
|
853
853
|
});
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
854
|
+
return { joined: kept.join('\n'), sections };
|
|
855
|
+
}
|
|
856
|
+
|
|
857
|
+
// #709: SQLite cannot widen a CHECK or change a column's type in place, so the documented way
|
|
858
|
+
// (sqlite.org/lang_altertable.html, "other kinds of table schema changes") is a table REBUILD:
|
|
859
|
+
// CREATE TABLE t_new (…); INSERT INTO t_new (…) SELECT … FROM t; DROP TABLE t; ALTER TABLE t_new RENAME TO t;
|
|
860
|
+
// Every row is copied before the drop, so the drop and the rename lose nothing. Read as additive only
|
|
861
|
+
// in that exact shape, and fails CLOSED on anything that could lose a row: a WHERE/JOIN/LIMIT or any
|
|
862
|
+
// other tail after `FROM t`, `SELECT DISTINCT`, `INSERT OR IGNORE|REPLACE` (both skip or merge rows
|
|
863
|
+
// on a stricter constraint), a TEMP table (gone at the end of the session), statements out of order,
|
|
864
|
+
// or an INSERT column list whose length differs from the SELECT list. One thing the file cannot show:
|
|
865
|
+
// whether an explicit SELECT list names EVERY column of `t` — `t` was created by an earlier
|
|
866
|
+
// migration — so such a rebuild is reported `columns: 'listed'` and the verdict says it was not
|
|
867
|
+
// checked; only `SELECT *` (`columns: 'all'`) proves every column is copied.
|
|
868
|
+
const SQL_IDENT = '(?:"[^"]+"|`[^`]+`|\\[[^\\]]+\\]|[A-Za-z_][\\w$]*)';
|
|
869
|
+
const SQL_NAME = `((?:${SQL_IDENT}\\s*\\.\\s*)?${SQL_IDENT})`;
|
|
870
|
+
const SQL_REBUILD = {
|
|
871
|
+
create: new RegExp(`\\bCREATE\\s+(TEMP\\s+|TEMPORARY\\s+)?TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${SQL_NAME}`, 'gi'),
|
|
872
|
+
insert: new RegExp(`\\bINSERT\\s+INTO\\s+${SQL_NAME}\\s*(?:\\(([^)]*)\\))?\\s*SELECT\\s+([^;]*?)\\s+FROM\\s+${SQL_NAME}\\s*(?=;|$)`, 'gi'),
|
|
873
|
+
drop: new RegExp(`\\bDROP\\s+TABLE\\s+(?:IF\\s+EXISTS\\s+)?${SQL_NAME}`, 'gi'),
|
|
874
|
+
rename: new RegExp(`\\bALTER\\s+TABLE\\s+${SQL_NAME}\\s+(RENAME)\\s+TO\\s+${SQL_NAME}`, 'gi'),
|
|
875
|
+
};
|
|
876
|
+
|
|
877
|
+
/** #709: an SQLite identifier as one comparable key — schema prefix, quoting and case dropped. */
|
|
878
|
+
function sqlKey(name) {
|
|
879
|
+
const parts = String(name).split('.');
|
|
880
|
+
return parts[parts.length - 1].trim().replace(/^["`[]|["`\]]$/g, '').toLowerCase();
|
|
881
|
+
}
|
|
882
|
+
|
|
883
|
+
/** #709: a SELECT or column list split on its top-level commas (a call's own commas stay inside). */
|
|
884
|
+
function sqlListItems(list) {
|
|
885
|
+
const items = [];
|
|
886
|
+
let depth = 0; let cur = '';
|
|
887
|
+
for (const ch of String(list)) {
|
|
888
|
+
if (ch === '(') depth += 1;
|
|
889
|
+
else if (ch === ')') depth -= 1;
|
|
890
|
+
if (ch === ',' && depth === 0) { items.push(cur); cur = ''; } else cur += ch;
|
|
891
|
+
}
|
|
892
|
+
items.push(cur);
|
|
893
|
+
return items.map((x) => x.trim()).filter(Boolean);
|
|
894
|
+
}
|
|
895
|
+
|
|
896
|
+
/**
|
|
897
|
+
* #709: every complete SQLite table rebuild in `joined` (sqlUpText's output) —
|
|
898
|
+
* [{ table, line, columns: 'all'|'listed', drop, rename }]: `drop`/`rename` are the offsets of the
|
|
899
|
+
* `DROP` and `RENAME` keywords SQL_DESTRUCTIVE would otherwise match, `line` the 1-based line of the
|
|
900
|
+
* drop. Pure; a shape it does not recognise is simply not listed, so its statements stay destructive.
|
|
901
|
+
*/
|
|
902
|
+
function sqlRebuilds(joined) {
|
|
903
|
+
const all = (re) => [...String(joined).matchAll(new RegExp(re.source, re.flags))];
|
|
904
|
+
const creates = all(SQL_REBUILD.create).filter((m) => !m[1]).map((m) => ({ at: m.index, name: sqlKey(m[2]) }));
|
|
905
|
+
const inserts = all(SQL_REBUILD.insert).map((m) => ({ at: m.index, into: sqlKey(m[1]), cols: m[2], select: m[3], from: sqlKey(m[4]) }));
|
|
906
|
+
const drops = all(SQL_REBUILD.drop).map((m) => ({ at: m.index, name: sqlKey(m[1]) }));
|
|
907
|
+
const renames = all(SQL_REBUILD.rename).map((m) => ({ at: m.index, kw: m.index + m[0].search(/RENAME/i), from: sqlKey(m[1]), to: sqlKey(m[3]) }));
|
|
908
|
+
const out = [];
|
|
909
|
+
for (const d of drops) {
|
|
910
|
+
const t = d.name;
|
|
911
|
+
for (const r of renames) {
|
|
912
|
+
if (r.at < d.at || r.to !== t || r.from === t) continue;
|
|
913
|
+
const fresh = r.from;
|
|
914
|
+
const copy = inserts.find((i) => i.into === fresh && i.from === t && i.at < d.at
|
|
915
|
+
&& creates.some((c) => c.name === fresh && c.at < i.at));
|
|
916
|
+
if (!copy) continue;
|
|
917
|
+
const select = copy.select.trim();
|
|
918
|
+
if (/^(DISTINCT|ALL)\b/i.test(select)) continue;
|
|
919
|
+
const star = new RegExp(`^(?:${SQL_IDENT}\\s*\\.\\s*)?\\*$`).test(select);
|
|
920
|
+
if (!star && copy.cols !== undefined && sqlListItems(copy.cols).length !== sqlListItems(select).length) continue;
|
|
921
|
+
out.push({ table: t, line: joined.slice(0, d.at).split('\n').length, columns: star ? 'all' : 'listed', drop: d.at, rename: r.kw });
|
|
922
|
+
break;
|
|
923
|
+
}
|
|
924
|
+
}
|
|
925
|
+
return out;
|
|
926
|
+
}
|
|
927
|
+
|
|
928
|
+
/**
|
|
929
|
+
* The first destructive SQL statement outside a Down section — `{ statement, line, inUp }` (1-based
|
|
930
|
+
* line in the original file; `inUp` = an Up marker opened the section it sits in) — or null. #709: the
|
|
931
|
+
* DROP and RENAME of a complete SQLite table rebuild (sqlRebuilds) are not destructive; any other
|
|
932
|
+
* destructive statement in the same file still is.
|
|
933
|
+
*/
|
|
934
|
+
function sqlDestructive(text) {
|
|
935
|
+
const { joined, sections } = sqlUpText(text);
|
|
936
|
+
const exempt = new Set(sqlRebuilds(joined).flatMap((r) => [r.drop, r.rename]));
|
|
937
|
+
for (const m of joined.matchAll(new RegExp(SQL_DESTRUCTIVE.source, 'gi'))) {
|
|
938
|
+
if (exempt.has(m.index)) continue;
|
|
939
|
+
const line = joined.slice(0, m.index).split('\n').length;
|
|
940
|
+
return { statement: m[0].replace(/\s+/g, ' '), line, inUp: sections[line - 1] === 'up' };
|
|
941
|
+
}
|
|
942
|
+
return null;
|
|
859
943
|
}
|
|
860
944
|
|
|
861
945
|
function laravelUpBody(text) {
|
|
@@ -1006,6 +1090,12 @@ function schemaVerdictCore(changes, since, declared, layout, none, missing) {
|
|
|
1006
1090
|
.filter((c) => String(c.status || '').charAt(0) === 'A' && c.path.endsWith('.php'))
|
|
1007
1091
|
.map((c) => ({ name: base(c.path), adds: laravelColumnEvents(laravelUpBody(String(c.content || ''))).filter((e) => e.kind === 'add').map((e) => `${e.table}.${e.column}`) }));
|
|
1008
1092
|
const addedBefore = (p) => laravelAdds.filter((a) => a.name < base(p)).flatMap((a) => a.adds);
|
|
1093
|
+
// #709: every SQLite table rebuild read as additive, named in the verdict — never silently.
|
|
1094
|
+
const rebuilds = [];
|
|
1095
|
+
// `lineOf` maps a line of `text` to the file's own line — a declared schema file is read by its added lines.
|
|
1096
|
+
const noteRebuilds = (path, text, lineOf = (n) => n) => {
|
|
1097
|
+
for (const r of sqlRebuilds(sqlUpText(text).joined)) rebuilds.push({ path, ...r, line: lineOf(r.line) });
|
|
1098
|
+
};
|
|
1009
1099
|
for (const c of migrations) {
|
|
1010
1100
|
const st = String(c.status || '').charAt(0);
|
|
1011
1101
|
if (st !== 'A') { findings.push(`${c.path}: ${st === 'D' ? 'deleted' : st === 'R' ? 'renamed' : 'edited'} — an existing migration was rewritten`); continue; }
|
|
@@ -1017,21 +1107,31 @@ function schemaVerdictCore(changes, since, declared, layout, none, missing) {
|
|
|
1017
1107
|
if (SQL_DOWN_FILE.test(c.path)) continue;
|
|
1018
1108
|
const m = sqlDestructive(text);
|
|
1019
1109
|
if (m) findings.push(`${c.path}:${m.line}: \`${m.statement}\`${m.inUp ? ' in the Up section' : ''}`);
|
|
1110
|
+
noteRebuilds(c.path, text);
|
|
1020
1111
|
}
|
|
1021
1112
|
}
|
|
1022
1113
|
for (const c of schemaFiles) {
|
|
1023
1114
|
const f = schemaFileFinding(c);
|
|
1024
1115
|
if (f) findings.push(f);
|
|
1116
|
+
else if (Array.isArray(c.added)) noteRebuilds(c.path, c.added.map((l) => l.text).join('\n'), (n) => (c.added[n - 1] ? c.added[n - 1].line : '?'));
|
|
1117
|
+
else if (typeof c.content === 'string') noteRebuilds(c.path, c.content);
|
|
1025
1118
|
}
|
|
1026
1119
|
if (findings.length) {
|
|
1027
|
-
|
|
1120
|
+
// `destructive` (#709): a measured destructive finding — not a failed read, not a declaration
|
|
1121
|
+
// contradiction — the one refusal a recorded human decision can clear on route deploy-tag-fast.
|
|
1122
|
+
return { ok: false, destructive: true, 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('; ')}` };
|
|
1028
1123
|
}
|
|
1029
1124
|
const read = [
|
|
1030
1125
|
...(migrations.length ? [`${migrations.length} migration file(s) added`] : []),
|
|
1031
1126
|
...(schemaFiles.length ? [`declared schema file(s) changed (${schemaFiles.map((c) => c.path).join(', ')}), the SQL they added read`] : []),
|
|
1032
1127
|
].join(' and ');
|
|
1033
|
-
|
|
1034
|
-
|
|
1128
|
+
const rebuilt = rebuilds.length ? ` — ${rebuilds.length} SQLite table rebuild(s) read as additive (every row copied before the drop): ${rebuilds.map((r) => `${r.path}:${r.line} \`${r.table}\``).join(', ')}` : '';
|
|
1129
|
+
const listed = rebuilds.filter((r) => r.columns === 'listed');
|
|
1130
|
+
if (unread.length) return notChecked(`${read} since ${since}, none destructive${rebuilt} — but ${unreadWhy()}`);
|
|
1131
|
+
if (listed.length) {
|
|
1132
|
+
return notChecked(`${read} since ${since}, none destructive${rebuilt} — but ${listed.map((r) => `\`${r.table}\``).join(', ')} ${listed.length === 1 ? 'is' : 'are'} copied by an explicit column list, and whether it names every column of the old table is not read here (that table was created by an earlier migration); a column the copy leaves out is dropped, so a person reads it before the final — \`SELECT * FROM <table>\` is read as copying every column (#709)`);
|
|
1133
|
+
}
|
|
1134
|
+
return { ok: true, detail: `${read} since ${since}, none destructive${rebuilt} (${scope})` };
|
|
1035
1135
|
}
|
|
1036
1136
|
|
|
1037
1137
|
/**
|
|
@@ -1342,7 +1442,19 @@ function decide(facts) {
|
|
|
1342
1442
|
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');
|
|
1343
1443
|
}
|
|
1344
1444
|
|
|
1345
|
-
|
|
1445
|
+
// #709: on route deploy-tag-fast no person can cut by hand — the route tags only from the release
|
|
1446
|
+
// workflow, so the deploy runs in the same run — and "a destructive schema change is a person's
|
|
1447
|
+
// decision" (§6 contract item 1) had no act that could make it. The act is the migration grant on
|
|
1448
|
+
// the version's tracking issue: a person, through COLAB_HUMAN=1, bound to this version. A MEASURED
|
|
1449
|
+
// destructive finding (never a failed read, never a declaration contradiction) with that grant live
|
|
1450
|
+
// passes, and the row says whose decision cleared it. Without the grant it refuses exactly as before,
|
|
1451
|
+
// and migration-grant's hand-off below names the one command.
|
|
1452
|
+
let schema = f.schema;
|
|
1453
|
+
const granted = fast && f.migrations && f.migrations.ok && f.migrations.granted;
|
|
1454
|
+
if (schema && !schema.ok && schema.destructive && !schema.unread && granted) {
|
|
1455
|
+
schema = { ok: true, detail: `${schema.detail} — cleared by a person's decision: the migration grant on the tracking issue #${granted}${v.ok ? ` for ${v.version}` : ''} (route deploy-tag-fast, CONVENTIONS.md §6 contract item 4)` };
|
|
1456
|
+
}
|
|
1457
|
+
for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', schema], ['switch-dependencies', f.switches]]) {
|
|
1346
1458
|
if (!verdict) add(condition, false, 'not measured', true);
|
|
1347
1459
|
else {
|
|
1348
1460
|
add(condition, verdict.ok, verdict.detail, isUnread(verdict));
|
|
@@ -1438,6 +1550,7 @@ function tagMessage(verdict, { sha, lastFinal, checkedBy }) {
|
|
|
1438
1550
|
}
|
|
1439
1551
|
|
|
1440
1552
|
module.exports = {
|
|
1553
|
+
sqlRebuilds, sqlUpText,
|
|
1441
1554
|
CONDITIONS, FAST_CONDITIONS, STANDING_CONDITIONS, BUMPS, MIGRATION_FILE, RELEASE_BRANCH, HOLD_LABEL,
|
|
1442
1555
|
isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
|
|
1443
1556
|
parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
|
|
@@ -603,7 +603,9 @@ function migrationGrantVerdictCore({ paths, grant, since, layout, none, missing
|
|
|
603
603
|
return { ok: true, detail: `no migration file changed since ${since || 'the first commit'}` };
|
|
604
604
|
}
|
|
605
605
|
const list = paths.join(', ');
|
|
606
|
-
|
|
606
|
+
// `granted` (#709): the tracking issue whose live grant cleared it — what lets route deploy-tag-fast
|
|
607
|
+
// read the same human decision as clearing a destructive schema change (release-cut.js decide()).
|
|
608
|
+
if (grant && grant.ok) return { ok: true, granted: grant.issue, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
|
|
607
609
|
return {
|
|
608
610
|
ok: false,
|
|
609
611
|
detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}) and no migration grant on the release${grant && grant.reason ? ` (${grant.reason})` : ''} — an automatically deployed final never carries an ungranted migration; a human finalizes, or grants it first (COLAB_HUMAN=1 colab migration-grant <tracking issue> --branch <version>)`,
|
|
@@ -114,7 +114,7 @@ function findings({ readFile, workflows, visibility }) {
|
|
|
114
114
|
const own = selfHostedLabel(workflows, readFile, wf);
|
|
115
115
|
const hint = own
|
|
116
116
|
? `use the label your ${own.wf} already runs on: runs-on: [${own.labels.join(', ')}]`
|
|
117
|
-
: 'use
|
|
117
|
+
: 'use the trunk runner class: runs-on: [self-hosted, trunk] (CONVENTIONS.md §7, "Runner classes")';
|
|
118
118
|
for (const j of hosted) {
|
|
119
119
|
out.push(`${wf} job \`${j.job}\` runs on GitHub-hosted (${j.runsOn.join(', ')}, line ${j.line}) on a ${String(visibility).toLowerCase()} repo — hosted minutes are billed here, and a billing refusal fails this run at trunk's head, which turns trunk red for \`colab ship\`; ${hint} (templates/release-auto.yml, RUNNERS)`);
|
|
120
120
|
}
|
package/tools/lib/stale-base.js
CHANGED
|
@@ -141,19 +141,32 @@ function branchHeadCiVerdict(a) {
|
|
|
141
141
|
* refuses here. `run.finishedRed` (tools/lib/git.js) lists every judged red run; without it the
|
|
142
142
|
* summary's own status/conclusion decides.
|
|
143
143
|
*
|
|
144
|
+
* #723: a head where an EXPECTED workflow has no run (`run.missing`, git.summarizeRunsForCommit's
|
|
145
|
+
* `opts.expected`) is pending, self-clearing, never a pass: ship --dry used to read READY on a head
|
|
146
|
+
* where only an unrelated workflow had run and the repo's CI never got a run at all. A red still wins
|
|
147
|
+
* (it is checked first). The detail names the missing workflow and how to get it a run — a hint only.
|
|
148
|
+
*
|
|
144
149
|
* @param {object} a
|
|
145
150
|
* @param {string|null} a.headSha - the branch head on the remote
|
|
146
151
|
* @param {object|null} a.run - summarizeRunsForCommit's verdict at headSha, verifying policy applied
|
|
147
152
|
* @param {string} a.branch
|
|
148
|
-
* @returns {null|{ok:false, verdict:'red', selfClearing:
|
|
153
|
+
* @returns {null|{ok:false, verdict:'red'|'pending', selfClearing:boolean, detail:string}}
|
|
149
154
|
*/
|
|
150
155
|
function githubBranchHeadRedVerdict(a) {
|
|
151
156
|
const run = a && a.run;
|
|
152
157
|
if (!a || !a.headSha || !run || run.status === 'none') return null;
|
|
153
158
|
const listed = Array.isArray(run.finishedRed) ? run.finishedRed : [];
|
|
154
159
|
const summaryRed = run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
|
|
155
|
-
if (!listed.length && !summaryRed) return null;
|
|
156
160
|
const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (GitHub Actions)`;
|
|
161
|
+
const missing = Array.isArray(run.missing) ? run.missing : [];
|
|
162
|
+
if (!listed.length && !summaryRed) {
|
|
163
|
+
if (!missing.length) return null;
|
|
164
|
+
const { missingHint } = require('./verify-runs');
|
|
165
|
+
return { ok: false, verdict: 'pending', selfClearing: true,
|
|
166
|
+
detail: `${at} has no run of ${missing.map((x) => x.name).join(', ')}, though ${missing.length === 1 ? 'its' : 'their'} definition fires on a push to this branch — ` +
|
|
167
|
+
`the runs that exist there do not stand in for it (#723). Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`; ` +
|
|
168
|
+
`if it ends NO_RUN (exit 7), ${missingHint(missing, a.branch)}` };
|
|
169
|
+
}
|
|
157
170
|
const failing = listed.length
|
|
158
171
|
? listed.map((x) => `${x.workflowName || 'run'} (${x.conclusion || 'none'})`).join(', ')
|
|
159
172
|
: `conclusion=${run.conclusion || 'none'}`;
|
package/tools/lib/stamp.js
CHANGED
|
@@ -515,7 +515,7 @@ const WORKFLOW_FINGERPRINTS = [
|
|
|
515
515
|
{ marker: 'Run exactly this tag, verify (deploy-container-run --deploy-only)', kind: 'step', template: 'deploy-container' },
|
|
516
516
|
// branch-name (#348): its one step.
|
|
517
517
|
{ marker: 'Check branch name (CONVENTIONS §4)', kind: 'step', template: 'branch-name' },
|
|
518
|
-
// Shared by
|
|
518
|
+
// Shared by the ci-* templates, light and heavy (#716): proves derivation, cannot say from which. Note the exact
|
|
519
519
|
// parenthetical — hand-written installers on this fleet say "(pinned binary)", which is why the
|
|
520
520
|
// step NAME discriminates where the URL inside the step does not.
|
|
521
521
|
{ marker: 'Install gitleaks (pinned release binary)', kind: 'step', template: null },
|