@futurelastic/colab-handbook 1.14.0-rc.9 → 1.14.0
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/README.md +19 -0
- package/README.vi.md +19 -0
- package/audit/audit.mjs +59 -15
- package/package.json +1 -1
- package/templates/README.md +64 -2
- package/templates/ci-laravel-heavy.yml +370 -0
- package/templates/ci-laravel.yml +27 -218
- package/templates/ci-node-heavy.yml +293 -0
- package/templates/ci-node.yml +23 -202
- package/templates/ci-python-heavy.yml +302 -0
- package/templates/ci-python.yml +26 -207
- package/templates/release-auto.yml +70 -1
- package/templates/release-tag.yml +20 -3
- package/tools/colab +463 -38
- package/tools/lib/disposition.js +27 -10
- package/tools/lib/docs-only.js +76 -21
- package/tools/lib/git.js +6 -1
- package/tools/lib/integration-profile.js +161 -0
- package/tools/lib/release-cut.js +10 -0
- package/tools/lib/release-finalize.js +9 -2
- package/tools/lib/secret-scan.js +132 -0
- package/tools/lib/ship-batch.js +71 -2
- package/tools/lib/stamp.js +16 -1
package/tools/lib/disposition.js
CHANGED
|
@@ -69,7 +69,19 @@ const HUMAN = 'human';
|
|
|
69
69
|
* GitHub's close reason takes. Frozen and closed: a kind outside this list is not a disposition
|
|
70
70
|
* with an unknown authority, it is not a disposition.
|
|
71
71
|
*/
|
|
72
|
-
const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-
|
|
72
|
+
const KINDS = Object.freeze(['done', 'split', 'routed-out', 'hold', 'needs-owner', 'not planned', 'leave']);
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* #609 — names this module still READS but never writes. `needs-owner` replaced `needs-boss`
|
|
76
|
+
* ("Boss" named one deployment's human; the standard is for any owner). During the switch a
|
|
77
|
+
* reader must accept both, or an issue marked under the old name reads as unrecognised — "not
|
|
78
|
+
* cleared" — to a tool that only knows the new one. Each legacy name classifies exactly like the
|
|
79
|
+
* kind it maps to. Kept out of KINDS / TOKENS / TOKEN_BY_KIND on purpose: those are what a writer
|
|
80
|
+
* may emit, and `formatMarker` refuses a legacy kind. Drop an entry once the old name has had no
|
|
81
|
+
* open use for its window (a separate issue, filed then).
|
|
82
|
+
*/
|
|
83
|
+
const LEGACY_KINDS = Object.freeze({ 'needs-boss': 'needs-owner' });
|
|
84
|
+
const LEGACY_TOKENS = Object.freeze({ 'needs-boss': 'needs-owner' });
|
|
73
85
|
|
|
74
86
|
/**
|
|
75
87
|
* The same seven by MARKER TOKEN. No token is a prefix or a decorated variant of another — the
|
|
@@ -82,13 +94,14 @@ const TOKEN_BY_KIND = Object.freeze({
|
|
|
82
94
|
split: 'split',
|
|
83
95
|
'routed-out': 'routed-out',
|
|
84
96
|
hold: 'hold',
|
|
85
|
-
'needs-
|
|
97
|
+
'needs-owner': 'needs-owner',
|
|
86
98
|
'not planned': 'not-planned',
|
|
87
99
|
leave: 'leave',
|
|
88
100
|
});
|
|
89
|
-
const KIND_BY_TOKEN = Object.freeze(
|
|
90
|
-
Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind]))
|
|
91
|
-
)
|
|
101
|
+
const KIND_BY_TOKEN = Object.freeze({
|
|
102
|
+
...Object.fromEntries(Object.entries(TOKEN_BY_KIND).map(([kind, token]) => [token, kind])),
|
|
103
|
+
...LEGACY_TOKENS, // read-only: a legacy token parses to the current kind (#609)
|
|
104
|
+
});
|
|
92
105
|
const TOKENS = Object.freeze(Object.values(TOKEN_BY_KIND));
|
|
93
106
|
|
|
94
107
|
/**
|
|
@@ -149,7 +162,10 @@ function parseMarker(text) {
|
|
|
149
162
|
if (typeof text !== 'string' || text === '') return null;
|
|
150
163
|
const tokens = [...text.matchAll(new RegExp(MARKER_PATTERN, 'g'))].map((m) => m[1]);
|
|
151
164
|
if (tokens.length === 0) return null;
|
|
152
|
-
|
|
165
|
+
// Distinct by the KIND a token reads as, so a legacy token and its current spelling (#609) are
|
|
166
|
+
// one proposal, not two; an unrecognised token stays distinct by its own spelling.
|
|
167
|
+
const distinct = [...new Set(tokens.map((t) => (
|
|
168
|
+
Object.prototype.hasOwnProperty.call(LEGACY_TOKENS, t) ? TOKEN_BY_KIND[LEGACY_TOKENS[t]] : t)))];
|
|
153
169
|
if (distinct.length > 1) {
|
|
154
170
|
return { token: null, kind: null, recognised: false, why: `${distinct.length} markers proposing different dispositions` };
|
|
155
171
|
}
|
|
@@ -251,9 +267,10 @@ function verdict(kind, authority, applicable, why, blockers, extra) {
|
|
|
251
267
|
*/
|
|
252
268
|
function classify(facts) {
|
|
253
269
|
const f = facts && typeof facts === 'object' ? facts : {};
|
|
254
|
-
const
|
|
270
|
+
const named = f.kind !== undefined && f.kind !== null
|
|
255
271
|
? f.kind
|
|
256
272
|
: (f.token !== undefined && f.token !== null ? KIND_BY_TOKEN[f.token] : undefined);
|
|
273
|
+
const kind = Object.prototype.hasOwnProperty.call(LEGACY_KINDS, named) ? LEGACY_KINDS[named] : named;
|
|
257
274
|
|
|
258
275
|
if (!KINDS.includes(kind)) {
|
|
259
276
|
return verdict(null, HUMAN, false, 'not a recognised disposition — not cleared, never a default', []);
|
|
@@ -331,11 +348,11 @@ function classify(facts) {
|
|
|
331
348
|
: verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
|
|
332
349
|
}
|
|
333
350
|
|
|
334
|
-
case 'needs-
|
|
351
|
+
case 'needs-owner':
|
|
335
352
|
// Record-first: the pass writes the question down with the apply lever pre-filled and moves
|
|
336
353
|
// on. It does not stop and wait, and it never applies this itself.
|
|
337
354
|
return verdict(kind, HUMAN, true,
|
|
338
|
-
'never applied by an agent — the agent records the question,
|
|
355
|
+
'never applied by an agent — the agent records the question, the owner answers, the issue returns to intake', []);
|
|
339
356
|
|
|
340
357
|
case 'not planned': {
|
|
341
358
|
const sup = f.supersededBy && typeof f.supersededBy === 'object' ? f.supersededBy : {};
|
|
@@ -375,7 +392,7 @@ function classify(facts) {
|
|
|
375
392
|
|
|
376
393
|
module.exports = {
|
|
377
394
|
AGENT, HUMAN,
|
|
378
|
-
KINDS, TOKENS, TOKEN_BY_KIND, KIND_BY_TOKEN,
|
|
395
|
+
KINDS, TOKENS, TOKEN_BY_KIND, KIND_BY_TOKEN, LEGACY_KINDS, LEGACY_TOKENS,
|
|
379
396
|
ASSERTS_AN_OUTCOME, SKIP_FENCE_CLASSES, EVIDENCE_FIELDS, HOLD_STALE_DAYS, MARKER_PATTERN,
|
|
380
397
|
parseMarker, formatMarker, evidenceShape, axisPermits, classify,
|
|
381
398
|
};
|
package/tools/lib/docs-only.js
CHANGED
|
@@ -8,15 +8,33 @@
|
|
|
8
8
|
* caller. Nothing here takes a list, a flag, an env var or a project.yml field. The allowlist and the
|
|
9
9
|
* exclusions below are constants, so widening them is a handbook change reviewed in a commit.
|
|
10
10
|
*
|
|
11
|
-
* Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary
|
|
12
|
-
*
|
|
13
|
-
* approved.
|
|
11
|
+
* Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary (other
|
|
12
|
+
* than a design artifact under `docs/`, below), a symlink, a submodule pointer. A false "no" costs a
|
|
13
|
+
* human click. A false "yes" merges code nobody approved.
|
|
14
|
+
*
|
|
15
|
+
* #606: the same rule also decides when `colab ship` lands a change WITHOUT WAITING FOR CI
|
|
16
|
+
* (shipDocsOnly, below — on by default, narrowed by `ci-docs-skip`). So widening anything here
|
|
17
|
+
* widens BOTH at once — the binary design-artifact rule below did exactly that: a PNG mockup under
|
|
18
|
+
* `docs/design/` is now docs-only for the autonomy exception too (CONVENTIONS.md §2).
|
|
14
19
|
*/
|
|
15
20
|
|
|
16
21
|
/** Extensions that count as documentation. Compared exactly (`README.MD` does not match). */
|
|
17
22
|
const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
|
|
18
23
|
/** A path under this top-level directory counts as documentation whatever its extension. */
|
|
19
24
|
const DOCS_DIR = 'docs/';
|
|
25
|
+
/**
|
|
26
|
+
* #606: a BINARY under `docs/` with one of these extensions is a design artifact (a mockup, a
|
|
27
|
+
* diagram, a printed spec) and counts as documentation. Case-insensitive (`Mock.PNG` matches). Any
|
|
28
|
+
* other binary under `docs/`, and every binary outside it, is still not docs-only.
|
|
29
|
+
*/
|
|
30
|
+
const DOCS_BINARY_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.pdf']);
|
|
31
|
+
function docsBinaryOk(p) {
|
|
32
|
+
const s = String(p);
|
|
33
|
+
if (!s.startsWith(DOCS_DIR)) return false;
|
|
34
|
+
const base = s.slice(s.lastIndexOf('/') + 1);
|
|
35
|
+
const dot = base.lastIndexOf('.');
|
|
36
|
+
return dot > 0 && DOCS_BINARY_EXTENSIONS.includes(base.slice(dot).toLowerCase());
|
|
37
|
+
}
|
|
20
38
|
/** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
|
|
21
39
|
const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
|
|
22
40
|
/**
|
|
@@ -77,15 +95,18 @@ function pathReason(p) {
|
|
|
77
95
|
* Returns `{ docsOnly, files, offenders: [{ path, reason }], reason }`. `files` counts distinct paths.
|
|
78
96
|
* `reason` is one line for a human, set on both outcomes.
|
|
79
97
|
*/
|
|
80
|
-
function classify(entries) {
|
|
98
|
+
function classify(entries, { exclude = [] } = {}) {
|
|
81
99
|
const paths = new Map();
|
|
82
100
|
for (const e of entries || []) {
|
|
83
101
|
const why = [];
|
|
84
102
|
const nameWhy = pathReason(e.path);
|
|
85
103
|
if (nameWhy) why.push(nameWhy);
|
|
104
|
+
// #606: a path the repo's suite reads, listed in `ci-docs-skip` — documentation, but it needs CI.
|
|
105
|
+
const listed = excludedBy(e.path, exclude);
|
|
106
|
+
if (!nameWhy && listed) why.push(`listed in ci-docs-skip (${listed}) — the suite reads it`);
|
|
86
107
|
if (e.oldMode === MODE_SYMLINK || e.newMode === MODE_SYMLINK) why.push('symlink change');
|
|
87
108
|
if (e.oldMode === MODE_GITLINK || e.newMode === MODE_GITLINK) why.push('submodule change');
|
|
88
|
-
if (e.binary) why.push('binary change');
|
|
109
|
+
if (e.binary && !docsBinaryOk(e.path)) why.push('binary change');
|
|
89
110
|
const prev = paths.get(e.path) || [];
|
|
90
111
|
paths.set(e.path, [...new Set([...prev, ...why])]);
|
|
91
112
|
}
|
|
@@ -101,6 +122,12 @@ function classify(entries) {
|
|
|
101
122
|
return { docsOnly: true, files, offenders: [], reason: `docs-only (${files} files)` };
|
|
102
123
|
}
|
|
103
124
|
|
|
125
|
+
/** The `ci-docs-skip` member `p` is, or sits under — a path prefix, never a string prefix. */
|
|
126
|
+
function excludedBy(p, exclude) {
|
|
127
|
+
const s = String(p);
|
|
128
|
+
return (exclude || []).find((x) => s === x || s.startsWith(`${x}/`)) || null;
|
|
129
|
+
}
|
|
130
|
+
|
|
104
131
|
/**
|
|
105
132
|
* Parse `git diff --raw -z --no-renames --no-abbrev` output into
|
|
106
133
|
* `[{ path, oldMode, newMode, oldSha, newSha, status }]`. The sha/status fields are additive
|
|
@@ -151,10 +178,30 @@ function readEntries(git, repo, cmd, range) {
|
|
|
151
178
|
* The branch shape: what `branch` changes relative to its merge base with `base` — the same three-dot
|
|
152
179
|
* diff the squash would land.
|
|
153
180
|
*/
|
|
154
|
-
function branchChanges(git, repo, base, branch) {
|
|
181
|
+
function branchChanges(git, repo, base, branch, opts = {}) {
|
|
155
182
|
const entries = readEntries(git, repo, 'diff', [`${base}...${branch}`, '--']);
|
|
156
183
|
if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read the diff ${base}...${branch}` };
|
|
157
|
-
return classify(entries);
|
|
184
|
+
return classify(entries, opts);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** One commit's own change (against its parent(s), `diff-tree -m`) — the shape a trunk squash has. */
|
|
188
|
+
function commitChanges(git, repo, sha, opts = {}) {
|
|
189
|
+
const entries = readEntries(git, repo, 'diff-tree', [sha]);
|
|
190
|
+
if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read commit ${String(sha).slice(0, 7)}` };
|
|
191
|
+
return classify(entries, opts);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* #606: does `colab ship` treat this branch as needing no CI? The SAME classification as the
|
|
196
|
+
* autonomy exception (#345), narrowed by the repo's `ci-docs-skip` list — a path the suite reads is
|
|
197
|
+
* documentation but still needs CI — and switched off entirely by `ci-docs-skip: off`. An invalid
|
|
198
|
+
* value reads as off (every reader takes doubt as "CI required"); the audit fails it.
|
|
199
|
+
* Returns the classify() shape plus `{ setting }` (parseCiDocsSkip's verdict).
|
|
200
|
+
*/
|
|
201
|
+
function shipDocsOnly(git, repo, base, branch, doc) {
|
|
202
|
+
const setting = parseCiDocsSkip(doc);
|
|
203
|
+
if (!setting.on) return { docsOnly: false, files: 0, offenders: [], reason: setting.reason, setting };
|
|
204
|
+
return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude }), setting };
|
|
158
205
|
}
|
|
159
206
|
|
|
160
207
|
/**
|
|
@@ -179,24 +226,32 @@ function directChanges(git, repo, trunk, since) {
|
|
|
179
226
|
}
|
|
180
227
|
|
|
181
228
|
/**
|
|
182
|
-
* #570: `ci-docs-skip:` in project.yml —
|
|
183
|
-
*
|
|
184
|
-
*
|
|
229
|
+
* #570/#606: `ci-docs-skip:` in project.yml — which changes `colab ship` may land without waiting for
|
|
230
|
+
* CI (#606), and the paths the CI templates' legacy guard (#570) excludes. ON BY DEFAULT for ship:
|
|
231
|
+
* absent = on, nothing excluded. A list = on, and each member is a repo path whose changes always run
|
|
232
|
+
* the suite even though this module calls them documentation (`docs/api/` feeding a generator, a
|
|
233
|
+
* README a link checker reads). `[]` = on, nothing excluded. `off` = the one opt-out, for a repo whose
|
|
234
|
+
* suite reads most of its docs (YAML 1.1 readers turn a bare `off` into boolean false; both spell it).
|
|
185
235
|
*
|
|
186
|
-
* The CI guard parses the same
|
|
187
|
-
*
|
|
188
|
-
*
|
|
189
|
-
*
|
|
236
|
+
* The legacy CI guard parses the same list in shell, but stays opt-in until its follow-up removes it:
|
|
237
|
+
* there `off` and absent both mean "run the full suite". Both readers take anything else — an empty
|
|
238
|
+
* `ci-docs-skip:` included — as "CI required", the stricter direction. So an invalid value here is a finding:
|
|
239
|
+
* a declaration that silently opts the repo out. Members are plain paths (the guard matches `p == x`
|
|
240
|
+
* or `p` under `x/`): no glob, no `..` or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
|
|
190
241
|
*/
|
|
191
242
|
const CI_DOCS_SKIP_KEY = 'ci-docs-skip';
|
|
192
243
|
function parseCiDocsSkip(doc) {
|
|
193
244
|
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, CI_DOCS_SKIP_KEY);
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
245
|
+
if (!has) {
|
|
246
|
+
return { declared: false, valid: true, on: true, exclude: [], reason: 'ci-docs-skip absent — on by default (#606): colab ship lands a docs-only change without waiting for CI' };
|
|
247
|
+
}
|
|
248
|
+
const v = doc[CI_DOCS_SKIP_KEY];
|
|
249
|
+
if (v === 'off' || v === false) {
|
|
250
|
+
return { declared: true, valid: true, on: false, exclude: null, reason: 'ci-docs-skip: off — colab ship requires CI for every change' };
|
|
197
251
|
}
|
|
198
252
|
const bad = (why) => ({ declared: true, valid: false, on: false, exclude: null,
|
|
199
|
-
reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none)
|
|
253
|
+
reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none) or \`off\`; every reader takes anything else as "CI required", so the declaration silently opts this repo out of the docs-only path` });
|
|
254
|
+
if (v === null || v === undefined) return bad('is empty');
|
|
200
255
|
if (!Array.isArray(v)) return bad(`is ${JSON.stringify(v)}`);
|
|
201
256
|
const exclude = [];
|
|
202
257
|
for (const m of v) {
|
|
@@ -207,11 +262,11 @@ function parseCiDocsSkip(doc) {
|
|
|
207
262
|
exclude.push(s);
|
|
208
263
|
}
|
|
209
264
|
return { declared: true, valid: true, on: true, exclude,
|
|
210
|
-
reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — a docs-only change
|
|
265
|
+
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' };
|
|
211
266
|
}
|
|
212
267
|
|
|
213
268
|
module.exports = {
|
|
214
|
-
DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
|
|
269
|
+
DOC_EXTENSIONS, DOCS_DIR, DOCS_BINARY_EXTENSIONS, docsBinaryOk, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
|
|
215
270
|
pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
|
|
216
|
-
CI_DOCS_SKIP_KEY, parseCiDocsSkip,
|
|
271
|
+
CI_DOCS_SKIP_KEY, parseCiDocsSkip, excludedBy, commitChanges, shipDocsOnly,
|
|
217
272
|
};
|
package/tools/lib/git.js
CHANGED
|
@@ -755,6 +755,11 @@ function ghPrClose(repo, num, comment) {
|
|
|
755
755
|
return gh(['pr', 'close', String(num), '--comment', comment], { cwd: repo });
|
|
756
756
|
}
|
|
757
757
|
|
|
758
|
+
/** #605: cancel one workflow run (a deleted batch ref's run still in flight). The run result, ok or not. */
|
|
759
|
+
function ghRunCancel(repo, id) {
|
|
760
|
+
return gh(['run', 'cancel', String(id)], { cwd: repo });
|
|
761
|
+
}
|
|
762
|
+
|
|
758
763
|
function ghIssueComment(repo, issueNum, body) {
|
|
759
764
|
const r = gh(['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
|
|
760
765
|
if (r.ok || !isGraphqlRateLimit(r.stderr)) return r;
|
|
@@ -1441,5 +1446,5 @@ module.exports = {
|
|
|
1441
1446
|
ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
|
|
1442
1447
|
ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
|
|
1443
1448
|
ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
|
|
1444
|
-
ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
|
|
1449
|
+
ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility, ghRunCancel,
|
|
1445
1450
|
};
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/integration-profile.js — where a repo's heavy CI lane runs, and what a green trunk
|
|
4
|
+
* promises (#610). The pure half: project.yml in, a profile and verdicts out. No git, no gh.
|
|
5
|
+
*
|
|
6
|
+
* #607 split CI into a light lane (every push; the lane `colab ship` reads) and a heavy lane (the
|
|
7
|
+
* whole suite, e2e, load: nightly and at every official build). That is ONE shape. Some repos cannot
|
|
8
|
+
* accept a trunk that is only light-green between releases; others want the heavy lane more often
|
|
9
|
+
* than at release. `integration-profile:` makes the shape a declared choice:
|
|
10
|
+
*
|
|
11
|
+
* gated every landing waits on a green heavy run at the candidate's exact sha
|
|
12
|
+
* (the branch head, or the batch head under `colab ship --batch`). Trunk is
|
|
13
|
+
* always heavy-green.
|
|
14
|
+
* qualify ship reads the light lane only; the heavy lane runs on trunk on a clock (the
|
|
15
|
+
* heavy workflow's cron), plus nightly and at the release gate. Trunk may be heavy-
|
|
16
|
+
* red for at most one clock window; a red is reverted first.
|
|
17
|
+
* release-heavy #607's shape and the DEFAULT when the key is absent: light per merge, heavy
|
|
18
|
+
* nightly and at the official build.
|
|
19
|
+
* promote a `develop → main` repo: the heavy lane gates the promotion. Kept for repos that
|
|
20
|
+
* already run it for an approval gate; not offered to new repos.
|
|
21
|
+
*
|
|
22
|
+
* Under EVERY profile a final release needs the heavy lane green at the candidate's sha, wherever the
|
|
23
|
+
* repo has a heavy lane at all (release-finalize.js `heavy-lane`).
|
|
24
|
+
*
|
|
25
|
+
* The heavy lane is found by its workflow FILE (`heavy-workflow:`, default `ci-heavy.yml` — the name
|
|
26
|
+
* #607's templates give it, and the name release-auto.yml already dispatches by). Run rows carry the
|
|
27
|
+
* workflow's `name:`, not its file, so the caller reads the file at the sha to learn which rows are
|
|
28
|
+
* heavy (`tools/colab` heavyWorkflowNameAt).
|
|
29
|
+
*
|
|
30
|
+
* FAIL CLOSED, like parseShipBatch: a malformed value reads as the default (`release-heavy`, ship
|
|
31
|
+
* unchanged) and the audit fails it. A typo must never silently weaken a declared `gated` — but it
|
|
32
|
+
* cannot strengthen anything either, and the audit is where a broken descriptor is reported.
|
|
33
|
+
*/
|
|
34
|
+
|
|
35
|
+
const KEY = 'integration-profile';
|
|
36
|
+
const HEAVY_KEY = 'heavy-workflow';
|
|
37
|
+
const PROFILES = Object.freeze(['gated', 'qualify', 'release-heavy', 'promote']);
|
|
38
|
+
const DEFAULT_PROFILE = 'release-heavy';
|
|
39
|
+
const DEFAULT_HEAVY_WORKFLOW = 'ci-heavy.yml';
|
|
40
|
+
|
|
41
|
+
function hasKey(doc, key) {
|
|
42
|
+
return !!doc && Object.prototype.hasOwnProperty.call(doc, key) && doc[key] !== null && doc[key] !== undefined && doc[key] !== '';
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** `{ profile, declared, valid, reason }` — absent → release-heavy, undeclared; bad → release-heavy, invalid. */
|
|
46
|
+
function parseProfile(doc) {
|
|
47
|
+
if (!hasKey(doc, KEY)) return { profile: DEFAULT_PROFILE, declared: false, valid: true, reason: `${KEY} absent (${DEFAULT_PROFILE})` };
|
|
48
|
+
const raw = doc[KEY];
|
|
49
|
+
const v = typeof raw === 'string' ? raw.trim() : raw;
|
|
50
|
+
if (typeof v === 'string' && PROFILES.includes(v)) return { profile: v, declared: true, valid: true, reason: `${KEY}: ${v}` };
|
|
51
|
+
return { profile: DEFAULT_PROFILE, declared: true, valid: false,
|
|
52
|
+
reason: `${KEY} is ${JSON.stringify(raw)}, expected one of ${PROFILES.join(' | ')} (omit for ${DEFAULT_PROFILE})` };
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** `{ file, declared, valid, reason }` — a bare workflow file name under .github/workflows. */
|
|
56
|
+
function parseHeavyWorkflow(doc) {
|
|
57
|
+
if (!hasKey(doc, HEAVY_KEY)) return { file: DEFAULT_HEAVY_WORKFLOW, declared: false, valid: true, reason: `${HEAVY_KEY} absent (${DEFAULT_HEAVY_WORKFLOW})` };
|
|
58
|
+
const raw = doc[HEAVY_KEY];
|
|
59
|
+
const v = typeof raw === 'string' ? raw.trim() : '';
|
|
60
|
+
if (/^[A-Za-z0-9._-]+\.ya?ml$/.test(v)) return { file: v, declared: true, valid: true, reason: `${HEAVY_KEY}: ${v}` };
|
|
61
|
+
return { file: DEFAULT_HEAVY_WORKFLOW, declared: true, valid: false,
|
|
62
|
+
reason: `${HEAVY_KEY} is ${JSON.stringify(raw)}, expected a workflow file name in .github/workflows (e.g. ${DEFAULT_HEAVY_WORKFLOW})` };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* The heavy lane's verdict at one sha, from the rows of that workflow at that sha
|
|
67
|
+
* (`{status, conclusion}`). Same all-runs reading as ship's: any finished not-green row (cancelled
|
|
68
|
+
* aside) is red; any unfinished row is pending; green needs a success. A red re-run green later is
|
|
69
|
+
* still red here only while the red row is the newest — callers pass the newest attempt's rows.
|
|
70
|
+
* null rows → `unread` (the run list could not be read — never "none")
|
|
71
|
+
*/
|
|
72
|
+
function heavyVerdict(rows) {
|
|
73
|
+
if (!Array.isArray(rows)) return { state: 'unread', why: 'the run list could not be read' };
|
|
74
|
+
if (!rows.length) return { state: 'none', why: 'no heavy run at this sha' };
|
|
75
|
+
// A re-run is the same run with a higher attempt; separate dispatches are separate rows. The newest
|
|
76
|
+
// dispatch speaks for the sha (a red then a green re-dispatch is green), so read the newest row.
|
|
77
|
+
const newest = rows.slice().sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')))[0];
|
|
78
|
+
const ref = newest.url || (newest.databaseId !== undefined && newest.databaseId !== null ? `run ${newest.databaseId}` : null);
|
|
79
|
+
if (newest.status !== 'completed') return { state: 'pending', why: `the heavy run is ${newest.status || 'in flight'}`, url: ref };
|
|
80
|
+
if (newest.conclusion === 'success') return { state: 'green', why: 'the heavy run succeeded', url: ref };
|
|
81
|
+
if (newest.conclusion === 'cancelled') return { state: 'none', why: 'the newest heavy run was cancelled', url: ref };
|
|
82
|
+
return { state: 'red', why: `the heavy run finished ${newest.conclusion || 'without a conclusion'}`, url: ref };
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* #610's one restriction: on exposure `live` the promotion deploys, so a trunk that may be heavy-red
|
|
87
|
+
* (qualify, release-heavy) must not feed it — unless the deploy is a tag the release gate qualifies.
|
|
88
|
+
* Only a DECLARED profile is refused: an absent key reads release-heavy for ship, but a repo that never
|
|
89
|
+
* declared is not suddenly failing; it gets a suggestion instead. Returns null or `{ level, message }`.
|
|
90
|
+
*/
|
|
91
|
+
function liveRestriction({ profile, declared, exposure, deploy }) {
|
|
92
|
+
if (exposure !== 'live') return null;
|
|
93
|
+
if (deploy === 'tag') return null;
|
|
94
|
+
if (profile === 'gated' || profile === 'promote') return null;
|
|
95
|
+
if (declared) {
|
|
96
|
+
return { level: 'fail', message: `${KEY}: ${profile} on exposure: live with deploy: ${deploy || '(none)'} — ${profile} allows a heavy-red trunk, and here the promotion deploys it. Choose gated, or deploy from a qualified tag (CONVENTIONS.md §7, Integration profiles)` };
|
|
97
|
+
}
|
|
98
|
+
return { level: 'suggest', message: `exposure: live reads ${KEY}: ${DEFAULT_PROFILE} by default, which allows a heavy-red trunk to be promoted — consider declaring ${KEY}: gated (CONVENTIONS.md §7, Integration profiles)` };
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The gate a `colab ship` landing must pass under the profile, given the heavy verdict at the
|
|
103
|
+
* candidate. Only `gated` gates a landing; every other profile returns null (ship reads the light
|
|
104
|
+
* lane exactly as before). `docsOnly` landings never wait on CI (#606) and are exempt here too.
|
|
105
|
+
* → null | { ok, action: 'pass'|'dispatch'|'wait'|'refuse', detail }
|
|
106
|
+
*/
|
|
107
|
+
function landingGate({ profile, docsOnly = false, heavyPresent, verdict, file, at }) {
|
|
108
|
+
if (profile !== 'gated' || docsOnly) return null;
|
|
109
|
+
if (!heavyPresent) {
|
|
110
|
+
return { ok: false, action: 'refuse', detail: `${KEY}: gated, but no .github/workflows/${file} at ${at} — gated lands only on a green heavy run, and there is no heavy lane to run (add one from templates/ci-<stack>-heavy.yml, or name it with ${HEAVY_KEY}:)` };
|
|
111
|
+
}
|
|
112
|
+
const v = verdict || { state: 'unread', why: 'not read' };
|
|
113
|
+
const link = v.url ? ` (${v.url})` : '';
|
|
114
|
+
switch (v.state) {
|
|
115
|
+
case 'green': return { ok: true, action: 'pass', detail: `${KEY}: gated — heavy lane green at ${at}${link}` };
|
|
116
|
+
case 'none': return { ok: false, action: 'dispatch', detail: `${KEY}: gated — no heavy run at ${at} yet (${v.why})` };
|
|
117
|
+
case 'pending': return { ok: false, action: 'wait', detail: `${KEY}: gated — ${v.why} at ${at}${link}` };
|
|
118
|
+
case 'red': return { ok: false, action: 'refuse', detail: `${KEY}: gated — ${v.why} at ${at}${link}; it blocks landing (fix it, or re-dispatch the heavy lane once a flake is proven)` };
|
|
119
|
+
default: return { ok: false, action: 'wait', detail: `${KEY}: gated — cannot read the heavy lane at ${at} (${v.why})` };
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* A batch's effective verdict under `gated`: the combined (light) verdict AND the heavy verdict at the
|
|
125
|
+
* batch head. Shapes match ship-batch.js combinedVerdict (`{state, attempt, runIds, why}`), so the
|
|
126
|
+
* existing re-run / split / land machinery reads it unchanged — a heavy red splits the wave toward the
|
|
127
|
+
* culprit exactly as a light red does. `heavy: null` (profile not gated) → the light verdict as is.
|
|
128
|
+
*/
|
|
129
|
+
function waveVerdict(light, heavy) {
|
|
130
|
+
if (!heavy || !light) return light;
|
|
131
|
+
if (light.state !== 'green') return light;
|
|
132
|
+
if (heavy.state === 'green') return { ...light, why: `${light.why}; heavy lane green` };
|
|
133
|
+
if (heavy.state === 'red') return { ...light, state: 'red', why: `heavy lane: ${heavy.why}${heavy.url ? ` (${heavy.url}; re-dispatch it for a red:infra, it is not one of the run ids below)` : ''}` };
|
|
134
|
+
return { ...light, state: 'pending', heavyMissing: heavy.state === 'none', why: `light green; heavy lane: ${heavy.why}` };
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The final release's heavy-lane condition — under EVERY profile (#610). A repo with no heavy lane at
|
|
139
|
+
* the candidate has nothing to gate (#607's templates say the same: "no heavy lane here → no gate"),
|
|
140
|
+
* so it passes and says so; refusing every release of a repo that never wrote one would break every
|
|
141
|
+
* adopter. With one: green → ok; red → blocking; none / running / unreadable → `pending` — the
|
|
142
|
+
* candidate keeps testing, it is not refused (the release workflow starts the heavy lane at each
|
|
143
|
+
* candidate; by hand: the printed command).
|
|
144
|
+
* → { ok, pending, detail }
|
|
145
|
+
*/
|
|
146
|
+
function releaseHeavyCondition({ present, file, verdict, at, ref }) {
|
|
147
|
+
if (!present) return { ok: true, pending: false, detail: `no .github/workflows/${file} at ${at} — no heavy lane in this repo, nothing to gate` };
|
|
148
|
+
const v = verdict || { state: 'unread', why: 'not read' };
|
|
149
|
+
const link = v.url ? ` (${v.url})` : '';
|
|
150
|
+
const start = `gh workflow run ${file} --ref ${ref || '<the candidate tag>'} -f ref=${ref || '<the candidate tag>'}`;
|
|
151
|
+
if (v.state === 'green') return { ok: true, pending: false, detail: `heavy lane green at ${at}${link}` };
|
|
152
|
+
if (v.state === 'red') return { ok: false, pending: false, detail: `heavy lane red at ${at}${link} — a final needs it green at this exact sha: re-run it green, or cut a new candidate` };
|
|
153
|
+
if (v.state === 'pending') return { ok: false, pending: true, detail: `heavy lane still running at ${at}${link} — no final until it is green` };
|
|
154
|
+
if (v.state === 'none') return { ok: false, pending: true, detail: `no heavy run at ${at} yet — start it: ${start}` };
|
|
155
|
+
return { ok: false, pending: true, detail: `cannot read the heavy lane at ${at} (${v.why}) — not finalized in this run` };
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
module.exports = {
|
|
159
|
+
KEY, HEAVY_KEY, PROFILES, DEFAULT_PROFILE, DEFAULT_HEAVY_WORKFLOW,
|
|
160
|
+
parseProfile, parseHeavyWorkflow, heavyVerdict, liveRestriction, landingGate, waveVerdict, releaseHeavyCondition,
|
|
161
|
+
};
|
package/tools/lib/release-cut.js
CHANGED
|
@@ -931,6 +931,8 @@ function promotionVerdict({ trunk, sha, parents, headOnTrunk, mergedFromTrunk, e
|
|
|
931
931
|
* triggers workflow-triggers.js prereleaseTagTriggers(...) findings
|
|
932
932
|
* lastFinal, suggestion, override, tags, tagsAtSha
|
|
933
933
|
* ci, suite, schema, switches { ok, detail } each, measured by the caller
|
|
934
|
+
* heavy #610 — integration-profile.js releaseHeavyCondition(), read on the final routes only;
|
|
935
|
+
* absent → no row
|
|
934
936
|
*
|
|
935
937
|
* Returns { ok, checks: [{ condition, ok, detail }], refusals, version, tag, bump, overridden }.
|
|
936
938
|
* Every check is reported, not just the first failure: a caller fixing one refusal should not
|
|
@@ -1062,6 +1064,14 @@ function decide(facts) {
|
|
|
1062
1064
|
else add(condition, verdict.ok, verdict.detail, isUnread(verdict));
|
|
1063
1065
|
}
|
|
1064
1066
|
|
|
1067
|
+
// #610: a final needs the heavy lane green at its exact sha, under every integration profile. Only
|
|
1068
|
+
// the two final routes tag a final here; a candidate is gated at `release finalize`. A heavy run
|
|
1069
|
+
// still to start or still running is the route holding (a no-op under --auto), not a refusal.
|
|
1070
|
+
if (finalRoute && tag && f.heavy) {
|
|
1071
|
+
add('heavy-lane', f.heavy.ok, f.heavy.detail, f.heavy.pending);
|
|
1072
|
+
if (!f.heavy.ok && f.heavy.pending && f.auto) noop = true;
|
|
1073
|
+
}
|
|
1074
|
+
|
|
1065
1075
|
// #446: what the fast route keeps in place of the test period it does not have.
|
|
1066
1076
|
let handoff = null;
|
|
1067
1077
|
let grant = null;
|
|
@@ -77,7 +77,7 @@ const STATES = Object.freeze([
|
|
|
77
77
|
|
|
78
78
|
const CONDITIONS = Object.freeze([
|
|
79
79
|
'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
|
|
80
|
-
'ci-green', 'full-suite', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
|
|
80
|
+
'ci-green', 'full-suite', 'heavy-lane', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
|
|
81
81
|
...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
|
|
82
82
|
]);
|
|
83
83
|
|
|
@@ -591,6 +591,7 @@ function handoffCommand(tag) {
|
|
|
591
591
|
* trunk trunkGreenVerdict(...)
|
|
592
592
|
* regressions regressionVerdict(...)
|
|
593
593
|
* ci, suite, schema, switches { ok, detail }
|
|
594
|
+
* heavy #610 — integration-profile.js releaseHeavyCondition(): { ok, pending, detail }; absent → no row
|
|
594
595
|
* cutRun #566 — cutRunVerdict(): the run that cut the candidate concluded success
|
|
595
596
|
* finalGrant #441 — release-policy.js finalGrantVerdict() of policy.effective.finalGrant (only
|
|
596
597
|
* read when the policy carries one; absent = unresolved, never a grant)
|
|
@@ -677,6 +678,10 @@ function decide(facts) {
|
|
|
677
678
|
add(condition, v && v.ok, v ? v.detail : 'not measured');
|
|
678
679
|
}
|
|
679
680
|
if (dr) add('deploy-report', false, deployReportDetail(dr.failures, { blocking: !lenient }), false);
|
|
681
|
+
// #610: the heavy lane green at the candidate's exact sha, under every integration profile.
|
|
682
|
+
// integration-profile.js releaseHeavyCondition; absent from `facts` (a caller predating it) → no row.
|
|
683
|
+
const hv = f.heavy || null;
|
|
684
|
+
if (hv) add('heavy-lane', hv.ok, hv.detail);
|
|
680
685
|
for (const [condition, v] of [['schema-additive', f.schema], ['switch-dependencies', f.switches]]) {
|
|
681
686
|
add(condition, v && v.ok, v ? v.detail : 'not measured');
|
|
682
687
|
}
|
|
@@ -690,12 +695,14 @@ function decide(facts) {
|
|
|
690
695
|
|
|
691
696
|
if (held.length) return out('held');
|
|
692
697
|
if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
|
|
693
|
-
const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition)
|
|
698
|
+
const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition)
|
|
699
|
+
&& !(c.condition === 'heavy-lane' && hv && hv.pending));
|
|
694
700
|
if (blocking.length) return out('refused');
|
|
695
701
|
if (ownClock) {
|
|
696
702
|
if (!tr.ok && !tr.pending) return out('refused');
|
|
697
703
|
if (!per.elapsed || tr.pending) return out('testing');
|
|
698
704
|
}
|
|
705
|
+
if (hv && hv.pending) return out('testing'); // #610: the heavy lane is still to run or still running
|
|
699
706
|
if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
|
|
700
707
|
if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
|
|
701
708
|
return out('finalized', { finalTag: cand.version });
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #606 — the secret check `colab ship` runs on a DOCS-ONLY change before it merges.
|
|
4
|
+
*
|
|
5
|
+
* A docs-only change lands without waiting for CI (tools/lib/docs-only.js shipDocsOnly), so the CI
|
|
6
|
+
* suite's own secret scan (gitleaks in the templates) may never see it. This is the cheap stand-in:
|
|
7
|
+
* the lines the change ADDS — `git diff -U0 <base>...<branch>`, text files only (git prints no lines
|
|
8
|
+
* for a binary) — matched against generic credential shapes, plus the repo's own forbidden terms
|
|
9
|
+
* when it keeps a file at TERMS_PATH. Seconds, no dependency, no network.
|
|
10
|
+
*
|
|
11
|
+
* A finding is reported as `file:line (rule)`, never with the matched text: the refusal is printed
|
|
12
|
+
* to a terminal and may be pasted onto an Issue, and a public repo's Issues are public.
|
|
13
|
+
*
|
|
14
|
+
* It is a backstop, not gitleaks: generic shapes only, added lines only. A shape it misses is
|
|
15
|
+
* missed; nothing here claims the change is clean beyond these rules.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** The repo-local forbidden-terms file (project.schema.md "ci-docs-skip"), read at the TARGET's tip. */
|
|
19
|
+
const TERMS_PATH = '.github/secret-scan-terms';
|
|
20
|
+
|
|
21
|
+
/** Generic credential shapes. `test` gets one added line. */
|
|
22
|
+
const RULES = Object.freeze([
|
|
23
|
+
{ rule: 'private key', re: /-----BEGIN ([A-Z0-9]+ )*PRIVATE KEY( BLOCK)?-----/ },
|
|
24
|
+
{ rule: 'AWS access key', re: /(^|[^A-Z0-9])(AKIA|ASIA)[A-Z0-9]{16}([^A-Z0-9]|$)/ },
|
|
25
|
+
{ rule: 'GitHub token', re: /(gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{60,})/ },
|
|
26
|
+
{ rule: 'Slack token', re: /xox[abposr]-[A-Za-z0-9-]{10,}/ },
|
|
27
|
+
{ rule: 'Google API key', re: /AIza[0-9A-Za-z_-]{35}/ },
|
|
28
|
+
{ rule: 'Stripe live key', re: /(sk|rk)_live_[0-9A-Za-z]{20,}/ },
|
|
29
|
+
{ rule: 'LLM API key', re: /sk-(ant|proj)-[A-Za-z0-9_-]{20,}/ },
|
|
30
|
+
]);
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* `password=…` and its kin. The value must hold a lower-case letter AND a digit, so a documented
|
|
34
|
+
* placeholder (`YOUR_API_KEY`, `changeme`, `$PASSWORD`, `<secret>`, `${{ secrets.X }}`) is not a
|
|
35
|
+
* finding while `password=hunter22` is.
|
|
36
|
+
*/
|
|
37
|
+
const ASSIGN = /(password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)["']?\s*[:=]\s*["']?([^"'\s<>{}$]{8,})/i;
|
|
38
|
+
function assignment(line) {
|
|
39
|
+
const m = ASSIGN.exec(line);
|
|
40
|
+
return !!m && /[0-9]/.test(m[2]) && /[a-z]/.test(m[2]);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Parse a forbidden-terms file — the format of templates/identity-vocabulary.example: one term per
|
|
45
|
+
* line, trimmed; blank and `#` lines are comments; a plain term matches case-insensitively as a
|
|
46
|
+
* substring; `re:<ERE>` is a regular expression matched against the lower-cased line; a term
|
|
47
|
+
* shorter than 3 characters is refused as a mistake. Returns `{ terms: [{line, test}], problems }`.
|
|
48
|
+
*/
|
|
49
|
+
function parseTerms(text) {
|
|
50
|
+
const terms = [];
|
|
51
|
+
const problems = [];
|
|
52
|
+
String(text || '').split(/\r?\n/).forEach((raw, i) => {
|
|
53
|
+
const t = raw.trim();
|
|
54
|
+
if (!t || t.startsWith('#')) return;
|
|
55
|
+
const line = i + 1;
|
|
56
|
+
if (t.startsWith('re:')) {
|
|
57
|
+
try {
|
|
58
|
+
const re = new RegExp(t.slice(3));
|
|
59
|
+
terms.push({ line, test: (s) => re.test(s.toLowerCase()) });
|
|
60
|
+
} catch (_) {
|
|
61
|
+
problems.push(`${TERMS_PATH} line ${line} is not a valid regular expression`);
|
|
62
|
+
}
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
if (t.length < 3) { problems.push(`${TERMS_PATH} line ${line} is shorter than 3 characters`); return; }
|
|
66
|
+
const want = t.toLowerCase();
|
|
67
|
+
terms.push({ line, test: (s) => s.toLowerCase().includes(want) });
|
|
68
|
+
});
|
|
69
|
+
return { terms, problems };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The added lines of a `git diff -U0 --no-renames --no-color` patch: `[{ file, line, text }]`.
|
|
74
|
+
* `line` is the line number in the new file.
|
|
75
|
+
*/
|
|
76
|
+
function addedLines(patch) {
|
|
77
|
+
const out = [];
|
|
78
|
+
let file = null;
|
|
79
|
+
let ln = 0;
|
|
80
|
+
let inHunk = false;
|
|
81
|
+
for (const l of String(patch || '').split('\n')) {
|
|
82
|
+
// A file header only outside a hunk: an added line `++ x` prints as `+++ x` inside one.
|
|
83
|
+
if (l.startsWith('diff --git ')) { inHunk = false; file = null; continue; }
|
|
84
|
+
if (!inHunk && l.startsWith('+++ ')) { const f = l.slice(4); file = f === '/dev/null' ? null : f.replace(/^b\//, ''); continue; }
|
|
85
|
+
const h = /^@@ -\S+ \+(\d+)(?:,\d+)? @@/.exec(l);
|
|
86
|
+
if (h) { ln = Number(h[1]); inHunk = true; continue; }
|
|
87
|
+
if (inHunk && l.startsWith('+') && file) { out.push({ file, line: ln, text: l.slice(1) }); ln++; }
|
|
88
|
+
}
|
|
89
|
+
return out;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Pure: findings `[{ file, line, rule }]` over added lines, against RULES + assignment + `terms`. */
|
|
93
|
+
function scanLines(lines, terms = []) {
|
|
94
|
+
const findings = [];
|
|
95
|
+
for (const { file, line, text } of lines) {
|
|
96
|
+
for (const r of RULES) if (r.re.test(text)) findings.push({ file, line, rule: r.rule });
|
|
97
|
+
if (assignment(text)) findings.push({ file, line, rule: 'credential assignment' });
|
|
98
|
+
for (const t of terms) if (t.test(text)) findings.push({ file, line, rule: `forbidden term, line ${t.line} of ${TERMS_PATH}` });
|
|
99
|
+
}
|
|
100
|
+
return findings;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Scan what `branch` adds relative to its merge base with `base`, with the forbidden terms read from
|
|
105
|
+
* `base`'s tree (the branch cannot edit them and stay docs-only: `.github/` is never documentation).
|
|
106
|
+
* Returns `{ ok, findings, files, reason }`; `ok: false` with no findings means the scan could not
|
|
107
|
+
* run — a caller refuses on that too, it never reads it as clean.
|
|
108
|
+
*/
|
|
109
|
+
function scanBranch(git, repo, base, branch) {
|
|
110
|
+
const d = git.git(['diff', '-U0', '--no-renames', '--no-color', '--no-ext-diff', `${base}...${branch}`, '--'], repo);
|
|
111
|
+
if (!d.ok) return { ok: false, findings: [], reason: `could not read the diff ${base}...${branch}` };
|
|
112
|
+
let terms = [];
|
|
113
|
+
if (git.git(['cat-file', '-e', `${base}:${TERMS_PATH}`], repo).ok) {
|
|
114
|
+
const t = git.git(['show', `${base}:${TERMS_PATH}`], repo);
|
|
115
|
+
if (!t.ok) return { ok: false, findings: [], reason: `could not read ${TERMS_PATH} at ${base}` };
|
|
116
|
+
const parsed = parseTerms(t.stdout);
|
|
117
|
+
if (parsed.problems.length) return { ok: false, findings: [], reason: parsed.problems.join('; ') };
|
|
118
|
+
terms = parsed.terms;
|
|
119
|
+
}
|
|
120
|
+
const lines = addedLines(d.stdout);
|
|
121
|
+
const findings = scanLines(lines, terms);
|
|
122
|
+
const files = new Set(lines.map((l) => l.file)).size;
|
|
123
|
+
const extra = terms.length ? ` and ${terms.length} forbidden term(s)` : '';
|
|
124
|
+
if (findings.length) {
|
|
125
|
+
const shown = findings.slice(0, 5).map((f) => `${f.file}:${f.line} (${f.rule})`).join('; ');
|
|
126
|
+
const more = findings.length > 5 ? `; +${findings.length - 5} more` : '';
|
|
127
|
+
return { ok: false, findings, files, reason: `${findings.length} finding(s): ${shown}${more}` };
|
|
128
|
+
}
|
|
129
|
+
return { ok: true, findings, files, reason: `${lines.length} added line(s) in ${files} file(s) clean against the credential shapes${extra}` };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
module.exports = { TERMS_PATH, RULES, parseTerms, addedLines, scanLines, scanBranch, assignment };
|