@futurelastic/colab-handbook 1.15.0-rc.1 → 1.15.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit/audit.mjs CHANGED
@@ -1521,6 +1521,17 @@ function auditRepoInner(target, ctx) {
1521
1521
  if (!ds.valid) fail(ds.reason);
1522
1522
  }
1523
1523
 
1524
+ // ---- docs-only-paths (#626) -----------------------------------------------
1525
+ // Extra repo paths whose content files (text + the design-artifact binaries) count as
1526
+ // documentation for the no-CI-wait path only (tools/lib/docs-only.js parseDocsOnlyPaths) — never
1527
+ // for the autonomy exception. Reported as the list (`[]` when absent), or null when invalid. An
1528
+ // invalid value fails: every reader takes it as absent, so the declaration silently adds nothing.
1529
+ {
1530
+ const dp = docsOnlyLib.parseDocsOnlyPaths(cfg);
1531
+ info.docsOnlyPaths = dp.valid ? dp.include : null;
1532
+ if (!dp.valid) fail(dp.reason);
1533
+ }
1534
+
1524
1535
  // ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
1525
1536
  // Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
1526
1537
  // the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.15.0-rc.1"
36
+ "version": "1.15.0-rc.3"
37
37
  }
package/tools/colab CHANGED
@@ -1302,7 +1302,10 @@ Refuses, naming each failed condition (all are reported, not just the first):
1302
1302
  already-candidate this commit already carries a candidate of the same version
1303
1303
  ci-green every run at the commit finished and one succeeded — colab ship's whole-sha check
1304
1304
  full-suite every workflow that ran at the commit has a successful run (a cancelled-only
1305
- workflow never ran its tests)
1305
+ workflow never ran its tests). Both read only the runs that verify the code,
1306
+ by colab ship's rule: a schedule / workflow_dispatch / workflow_run run (a
1307
+ nightly still in flight) is set aside and named; project.yml
1308
+ ship-gate-workflows / ship-ignore-workflows narrow it the same way
1306
1309
  schema-additive a migration since the last final tag is destructive (Laravel database/migrations
1307
1310
  up() drops/renames/->change(), Prisma DROP/RENAME/ALTER COLUMN, and .php/.sql
1308
1311
  under a project.yml \`migrations:\` prefix) or an existing migration was
@@ -1440,7 +1443,7 @@ function releaseCutChanges(repoAbs, from, sha, declared) {
1440
1443
  * — by branch window for a fresh head (cut), by commit for an older candidate (finalize). Also
1441
1444
  * returns the issue list it read (null when unread or gh unusable), so a caller does not read it twice.
1442
1445
  */
1443
- function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, issues: knownIssues }) {
1446
+ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, issues: knownIssues, verifying }) {
1444
1447
  let ci; let suite; let switches; let issues = null;
1445
1448
  if (!isGhUsable(repoAbs)) {
1446
1449
  const why = ghUnusableWhy(repoAbs);
@@ -1449,11 +1452,16 @@ function measureCandidateConditions(repoAbs, { sha, lastFinal, at, readRuns, iss
1449
1452
  switches = { ok: false, unread: true, detail: `gh not usable (${why}) — the colab:switch markers cannot be read` };
1450
1453
  } else {
1451
1454
  // #616: a workflow whose every run at the sha was skipped did not run — not counted either way.
1452
- const rows = releaseCut.withoutSkippedOnlyWorkflows(readRuns());
1455
+ // #624: `verifying` (release cut only) narrows the rows to the runs that verify the code — a
1456
+ // scheduled run still in flight at the sha is not part of its verdict. Finalize passes none.
1457
+ const read = verifying ? releaseCut.verifyingRunsForCut(readRuns(), verifying) : { rows: readRuns() };
1458
+ const note = releaseCut.verifyingNote(read);
1459
+ const rows = releaseCut.withoutSkippedOnlyWorkflows(read.rows);
1453
1460
  const run = git.summarizeRunsForCommit(rows, sha);
1454
1461
  if (!run) ci = { ok: false, detail: `gh run list failed — cannot confirm CI at ${at}` };
1455
- else { const v = classifyCiRun(repoAbs, run, at); ci = { ok: v.ok, detail: v.detail }; }
1462
+ else { const v = classifyCiRun(repoAbs, run, at); ci = { ok: v.ok, detail: v.detail + note }; }
1456
1463
  suite = releaseCut.fullSuiteVerdict(rows, at);
1464
+ if (note && rows) suite = { ...suite, detail: suite.detail + note };
1457
1465
  // #423: an --auto finalize judges several candidates in one run — the issue list is read once.
1458
1466
  issues = knownIssues !== undefined ? knownIssues : readAllIssuesForSwitches(repoAbs);
1459
1467
  switches = releaseCut.switchVerdict(issues);
@@ -1721,6 +1729,7 @@ function cmdReleaseCut(argv) {
1721
1729
 
1722
1730
  const { ci, suite, schema, switches, issues, migrations: migrationPathsSince } = measureCandidateConditions(repoAbs, {
1723
1731
  sha, lastFinal, at, readRuns: () => releaseCut.withoutOwnWorkflow(git.ghRunsForCommit(repoAbs, 'main', sha)), // #425
1732
+ verifying: verifyingPolicy(repoAbs), // #624: the ship gate's rule for which runs may veto
1724
1733
  });
1725
1734
  const { manifests, ancestry } = measurePreTag(repoAbs, sha, `${remote}/main`); // #424
1726
1735
 
@@ -11808,13 +11817,15 @@ const DOCS_TIP_WALK = 50;
11808
11817
  function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
11809
11818
  if (!tipSha) return null;
11810
11819
  const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
11820
+ const declared = docsOnly.parseDocsOnlyPaths(projectDoc(repoAbs));
11811
11821
  if (!setting.on) return null;
11812
11822
  const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
11813
11823
  if (!list.ok) return null;
11814
11824
  let skipped = 0;
11815
11825
  let code = null;
11816
11826
  for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
11817
- const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude });
11827
+ // #626: the declared `docs-only-paths` widen this door (the no-CI-wait path), never autonomy.
11828
+ const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude, include: declared.include });
11818
11829
  if (!c.docsOnly) { code = sha; break; }
11819
11830
  skipped++;
11820
11831
  }
@@ -16,6 +16,11 @@
16
16
  * (shipDocsOnly, below — on by default, narrowed by `ci-docs-skip`). So widening anything here
17
17
  * widens BOTH at once — the binary design-artifact rule below did exactly that: a PNG mockup under
18
18
  * `docs/design/` is now docs-only for the autonomy exception too (CONVENTIONS.md §2).
19
+ *
20
+ * #626: the ONE repo-declared widening, `docs-only-paths:`, reaches only the no-CI-wait path
21
+ * (shipDocsOnly and the trunk-tip door) through classify()'s `include` option. branchChanges and
22
+ * directChanges called without it — the #345 autonomy exception — are exactly as narrow as before:
23
+ * no project.yml field widens who may merge.
19
24
  */
20
25
 
21
26
  /** Extensions that count as documentation. Compared exactly (`README.MD` does not match). */
@@ -35,6 +40,22 @@ function docsBinaryOk(p) {
35
40
  const dot = base.lastIndexOf('.');
36
41
  return dot > 0 && DOCS_BINARY_EXTENSIONS.includes(base.slice(dot).toLowerCase());
37
42
  }
43
+ /**
44
+ * #626: under a path the repo declares in `docs-only-paths`, a file with one of these extensions is
45
+ * documentation — text or binary. Every other extension there is not. Case-insensitive.
46
+ */
47
+ const DECLARED_EXTENSIONS = Object.freeze([...DOC_EXTENSIONS, ...DOCS_BINARY_EXTENSIONS]);
48
+ function extOf(p) {
49
+ const s = String(p);
50
+ const base = s.slice(s.lastIndexOf('/') + 1);
51
+ const dot = base.lastIndexOf('.');
52
+ return dot > 0 ? base.slice(dot).toLowerCase() : '';
53
+ }
54
+ /** The declared `docs-only-paths` member a content file sits in, or null. */
55
+ function includedBy(p, include) {
56
+ const m = excludedBy(p, include);
57
+ return m && DECLARED_EXTENSIONS.includes(extOf(p)) ? m : null;
58
+ }
38
59
  /** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
39
60
  const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
40
61
  /**
@@ -67,7 +88,7 @@ const MODE_GITLINK = '160000';
67
88
  * Classify ONE path by name alone. Returns `null` when the path is documentation, else the reason it
68
89
  * is not.
69
90
  */
70
- function pathReason(p) {
91
+ function pathReason(p, { include = [] } = {}) {
71
92
  const segs = String(p).split('/');
72
93
  const base = segs[segs.length - 1];
73
94
  if (NEVER_BASENAMES.includes(base)) return `${base} is agent rules, not documentation`;
@@ -82,6 +103,7 @@ function pathReason(p) {
82
103
  }
83
104
  }
84
105
  if (String(p).startsWith(DOCS_DIR)) return null;
106
+ if (includedBy(p, include)) return null;
85
107
  const dot = base.lastIndexOf('.');
86
108
  const ext = dot > 0 ? base.slice(dot) : '';
87
109
  if (DOC_EXTENSIONS.includes(ext)) return null;
@@ -95,18 +117,18 @@ function pathReason(p) {
95
117
  * Returns `{ docsOnly, files, offenders: [{ path, reason }], reason }`. `files` counts distinct paths.
96
118
  * `reason` is one line for a human, set on both outcomes.
97
119
  */
98
- function classify(entries, { exclude = [] } = {}) {
120
+ function classify(entries, { exclude = [], include = [] } = {}) {
99
121
  const paths = new Map();
100
122
  for (const e of entries || []) {
101
123
  const why = [];
102
- const nameWhy = pathReason(e.path);
124
+ const nameWhy = pathReason(e.path, { include });
103
125
  if (nameWhy) why.push(nameWhy);
104
126
  // #606: a path the repo's suite reads, listed in `ci-docs-skip` — documentation, but it needs CI.
105
127
  const listed = excludedBy(e.path, exclude);
106
128
  if (!nameWhy && listed) why.push(`listed in ci-docs-skip (${listed}) — the suite reads it`);
107
129
  if (e.oldMode === MODE_SYMLINK || e.newMode === MODE_SYMLINK) why.push('symlink change');
108
130
  if (e.oldMode === MODE_GITLINK || e.newMode === MODE_GITLINK) why.push('submodule change');
109
- if (e.binary && !docsBinaryOk(e.path)) why.push('binary change');
131
+ if (e.binary && !docsBinaryOk(e.path) && !includedBy(e.path, include)) why.push('binary change');
110
132
  const prev = paths.get(e.path) || [];
111
133
  paths.set(e.path, [...new Set([...prev, ...why])]);
112
134
  }
@@ -201,7 +223,8 @@ function commitChanges(git, repo, sha, opts = {}) {
201
223
  function shipDocsOnly(git, repo, base, branch, doc) {
202
224
  const setting = parseCiDocsSkip(doc);
203
225
  if (!setting.on) return { docsOnly: false, files: 0, offenders: [], reason: setting.reason, setting };
204
- return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude }), setting };
226
+ const declared = parseDocsOnlyPaths(doc);
227
+ return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude, include: declared.include }), setting, declared };
205
228
  }
206
229
 
207
230
  /**
@@ -265,8 +288,38 @@ function parseCiDocsSkip(doc) {
265
288
  reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — colab ship lands a docs-only change without waiting for CI' };
266
289
  }
267
290
 
291
+ /**
292
+ * #626: `docs-only-paths:` in project.yml — extra repo paths whose content files (DECLARED_EXTENSIONS:
293
+ * the text types plus the design-artifact binaries) count as documentation FOR THE NO-CI-WAIT PATH
294
+ * ONLY (shipDocsOnly, the trunk-tip door). It never widens the autonomy exception. Shape: a list of
295
+ * plain repo paths, validated exactly as `ci-docs-skip` members are — no glob (write
296
+ * `public/images/blog`, not `public/images/blog/**`). Absent or `[]` = nothing added. An invalid
297
+ * value reads as absent (the stricter direction: nothing widened); the audit fails it.
298
+ * `ci-docs-skip` members still win over it, and so do the never-rules above.
299
+ */
300
+ const DOCS_ONLY_PATHS_KEY = 'docs-only-paths';
301
+ function parseDocsOnlyPaths(doc) {
302
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, DOCS_ONLY_PATHS_KEY);
303
+ if (!has) return { declared: false, valid: true, include: [], reason: 'docs-only-paths absent — nothing added to the docs-only rule' };
304
+ const v = doc[DOCS_ONLY_PATHS_KEY];
305
+ const bad = (why) => ({ declared: true, valid: false, include: [],
306
+ reason: `docs-only-paths ${why} — it must be a list of plain repo paths (no glob, \`..\`, \`.\` or leading \`/\`); every reader takes anything else as absent, so the declaration silently adds nothing` });
307
+ if (!Array.isArray(v)) return bad(v === null || v === undefined ? 'is empty' : `is ${JSON.stringify(v)}`);
308
+ const include = [];
309
+ for (const m of v) {
310
+ const s = typeof m === 'string' ? m.replace(/\/+$/, '') : null;
311
+ if (!s || !/^[A-Za-z0-9._/-]+$/.test(s) || s.startsWith('/') || s.split('/').some((x) => x === '..' || x === '.' || x === '')) {
312
+ return bad(`lists ${JSON.stringify(m)}, which is not a plain repo path`);
313
+ }
314
+ include.push(s);
315
+ }
316
+ return { declared: true, valid: true, include,
317
+ reason: include.length ? `docs-only-paths: ${include.join(', ')} (content files there skip the CI wait)` : 'docs-only-paths: [] — nothing added' };
318
+ }
319
+
268
320
  module.exports = {
269
321
  DOC_EXTENSIONS, DOCS_DIR, DOCS_BINARY_EXTENSIONS, docsBinaryOk, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
270
322
  pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
271
323
  CI_DOCS_SKIP_KEY, parseCiDocsSkip, excludedBy, commitChanges, shipDocsOnly,
324
+ DECLARED_EXTENSIONS, includedBy, DOCS_ONLY_PATHS_KEY, parseDocsOnlyPaths,
272
325
  };
@@ -23,6 +23,7 @@
23
23
  * already-candidate the commit does not already carry a candidate of this version
24
24
  * ci-green §6 condition 1 — every run at the sha finished, one succeeded
25
25
  * full-suite §6 condition 2 — every workflow that ran at the sha has a successful run
26
+ * (both over the code-verifying runs only, the ship gate's rule — #624)
26
27
  * schema-additive §6 condition 3 — no destructive migration since the last final tag
27
28
  * switch-dependencies §6 condition 4 — the colab:switch markers are readable, and no finished
28
29
  * switch needs one that is still unfinished
@@ -75,6 +76,7 @@
75
76
  const migrationPaths = require('./migration-paths');
76
77
  const releaseTag = require('./release-tag');
77
78
  const { stripCode } = require('./instruction-file');
79
+ const verifyRuns = require('./verify-runs');
78
80
 
79
81
  const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
80
82
  const BUMPS = Object.freeze(['patch', 'minor']);
@@ -737,6 +739,34 @@ function withoutSkippedOnlyWorkflows(rows) {
737
739
  return rows.filter((r) => !drop.has((r && r.workflowName) || '(unnamed workflow)'));
738
740
  }
739
741
 
742
+ /**
743
+ * #624: the run rows `release cut` judges ci-green and full-suite over — the runs that VERIFY the code
744
+ * at the sha, by the ship gate's own rule (verify-runs.js, #503: push / pull_request / merge_group
745
+ * triggers, project.yml `ship-gate-workflows` / `ship-ignore-workflows`, the #567 dispatch rescue).
746
+ * One rule for "which workflows may veto", not a second. Measured: a qualified sha whose CI push run
747
+ * had succeeded was refused ci-green AND full-suite because a scheduled `Nightly` run at the same sha
748
+ * was still in progress — a run that comes after the verdict, not part of it. Returns `{ rows,
749
+ * setAside }`; each set-aside row carries `setAsideWhy`. null passes through as `{ rows: null }`.
750
+ */
751
+ function verifyingRunsForCut(rows, policy) {
752
+ if (!Array.isArray(rows)) return { rows, setAside: [], dispatchCounted: [] };
753
+ const split = verifyRuns.splitVerifying(rows, policy || { gate: null, ignore: [] });
754
+ return { rows: split.counted, setAside: split.setAside, dispatchCounted: split.dispatchCounted || [] };
755
+ }
756
+
757
+ /**
758
+ * #624: the detail suffix naming what `verifyingRunsForCut` set aside (and any lost-push dispatch run
759
+ * it counted, #567) — the ship gate's own wording, so one reader learns one phrase. '' when neither.
760
+ */
761
+ function verifyingNote(read) {
762
+ if (!read) return '';
763
+ const summary = (list) => (list || []).map((x) => ({
764
+ workflowName: x.workflowName || null, status: x.status || null, conclusion: x.conclusion || null,
765
+ databaseId: x.databaseId || null, ...(x.setAsideWhy ? { why: x.setAsideWhy } : {}),
766
+ }));
767
+ return verifyRuns.setAsideNote(summary(read.setAside)) + verifyRuns.dispatchCountedNote(summary(read.dispatchCounted));
768
+ }
769
+
740
770
  /**
741
771
  * The run rows minus the CALLING workflow's own runs (#425). Inside the release workflow
742
772
  * (templates/release-auto.yml) `release cut` / `release finalize` read the runs at the very commit
@@ -1226,7 +1256,7 @@ module.exports = {
1226
1256
  isFastRoute, isLibraryRoute, decideManifestVersion, spacingVerdict, holdsVerdict, migrationHandoff,
1227
1257
  parseVersion, formatVersion, candidateNumbers, nextCandidateNumber, decideVersion,
1228
1258
  parseGuardOutput, exportsDiff, switchRemovalsSince, autoSignals, parseMigrationSection, decideAutoVersion, cadenceVerdict, qualifiedShaVerdict,
1229
- fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, isMigrationPath, schemaVerdict,
1259
+ fullSuiteVerdict, withoutOwnWorkflow, withoutSkippedOnlyWorkflows, verifyingRunsForCut, verifyingNote, isMigrationPath, schemaVerdict,
1230
1260
  parseSwitchMarkers, switchVerdict,
1231
1261
  promotionVerdict, decide, tagMessage, versionSourceOf,
1232
1262
  DOWNSTREAM_EVENTS, headCandidateVerdict, prereleaseArgs, finalReleaseArgs, handoffTrackingBody,