@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.
@@ -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 label on a private repo` });
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
  }
@@ -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 done('TIMEOUT', `still ${last ? last.state : 'unread'} at the ${fmtDuration(deadlineSec * 1000)} deadline`);
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 done('TIMEOUT', `still pending at the ${fmtDuration(deadlineSec * 1000)} deadline`);
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, containerFinding,
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,
@@ -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 first destructive SQL statement outside a Down section — `{ statement, line, inUp }` (1-based
840
- * line in the original file; `inUp` = an Up marker opened the section it sits in) — or null. Skipped
841
- * lines are blanked, not removed, so line numbers stay true and a statement split across lines
842
- * (`DROP\n TABLE`) still matches, as it did when the whole file was read.
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 sqlDestructive(text) {
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
- const joined = kept.join('\n');
855
- const m = SQL_DESTRUCTIVE.exec(joined);
856
- if (!m) return null;
857
- const line = joined.slice(0, m.index).split('\n').length;
858
- return { statement: m[0].replace(/\s+/g, ' '), line, inUp: sections[line - 1] === 'up' };
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
- 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('; ')}` };
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
- if (unread.length) return notChecked(`${read} since ${since}, none destructive — but ${unreadWhy()}`);
1034
- return { ok: true, detail: `${read} since ${since}, none destructive (${scope})` };
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
- for (const [condition, verdict] of [['ci-green', f.ci], ['full-suite', f.suite], ['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
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
- if (grant && grant.ok) return { ok: true, detail: `${paths.length} migration file(s) since ${since || 'the first commit'} (${list}), granted on the tracking issue #${grant.issue}` };
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 your self-hosted trunk runner label';
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
  }
@@ -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:false, detail:string}}
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'}`;
@@ -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 all three ci-* templates: proves derivation, cannot say from which. Note the exact
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 },