@futurelastic/colab-handbook 1.15.0-rc.2 → 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 +3 -1
- package/tools/lib/docs-only.js +58 -5
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
|
@@ -11817,13 +11817,15 @@ const DOCS_TIP_WALK = 50;
|
|
|
11817
11817
|
function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
|
|
11818
11818
|
if (!tipSha) return null;
|
|
11819
11819
|
const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
|
|
11820
|
+
const declared = docsOnly.parseDocsOnlyPaths(projectDoc(repoAbs));
|
|
11820
11821
|
if (!setting.on) return null;
|
|
11821
11822
|
const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
|
|
11822
11823
|
if (!list.ok) return null;
|
|
11823
11824
|
let skipped = 0;
|
|
11824
11825
|
let code = null;
|
|
11825
11826
|
for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
|
|
11826
|
-
|
|
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 });
|
|
11827
11829
|
if (!c.docsOnly) { code = sha; break; }
|
|
11828
11830
|
skipped++;
|
|
11829
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
|
};
|