@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 +11 -0
- package/package.json +1 -1
- package/tools/colab +16 -5
- package/tools/lib/docs-only.js +58 -5
- package/tools/lib/release-cut.js +31 -1
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
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
|
-
|
|
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
|
-
|
|
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
|
}
|
package/tools/lib/docs-only.js
CHANGED
|
@@ -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
|
-
|
|
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
|
};
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -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,
|