@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.9
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/LICENSE +21 -0
- package/README.md +310 -3
- package/README.vi.md +280 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13785 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +259 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/wake.js — the closed `wake:` vocabulary of a `Hold:` line, parsed and evaluated once
|
|
4
|
+
* (CONVENTIONS.md §5, *Holds*, #382).
|
|
5
|
+
*
|
|
6
|
+
* WHY THIS EXISTS. A hold used to name its wake as one of three forms — `review-by:<date>`, `#N`
|
|
7
|
+
* (a `blocked_by` edge), or `ruling`. Anything else ("until the fix is deployed", "when some
|
|
8
|
+
* capability lands") could only be prose in the `Because:` line, backed by a date. Nobody reads
|
|
9
|
+
* that prose before the date. Measured across adopting repos, 2026-09-25 → 26: four holds whose
|
|
10
|
+
* condition had already come true sat parked for hours to days, one of them waiting on another
|
|
11
|
+
* repo's issue number that did not exist. Every one was right when set. What failed was
|
|
12
|
+
* RELEASE: the condition came true and nothing noticed, because the only machine-readable part
|
|
13
|
+
* was the date. So the vocabulary is widened to forms a scheduler can evaluate every beat, and
|
|
14
|
+
* it stays CLOSED — no free text is ever evaluated.
|
|
15
|
+
*
|
|
16
|
+
* ONE SPELLING, NOT TWO. The checkable forms below are spelled name for name the way the one
|
|
17
|
+
* adopting scheduler that already evaluates wakes spells them, argument rules included. That
|
|
18
|
+
* scheduler accepts two more kinds (a claim released, a session gone) that describe a live
|
|
19
|
+
* session, not a tracker fact a hold on an issue can wait on; they are deliberately not adopted
|
|
20
|
+
* here. The rule is one-directional: every name in this file is one that scheduler accepts, and
|
|
21
|
+
* no consumer invents a second spelling for any of them. `wake.test.js` pins the list.
|
|
22
|
+
*
|
|
23
|
+
* PURE BY CONSTRUCTION: strings in, verdicts out. No git, no network, no `gh`. `evaluate()` takes
|
|
24
|
+
* facts a caller already gathered — the same posture as readiness.js and disposition.js — so a
|
|
25
|
+
* consumer outside this repo reaches the same verdict from facts it collected its own way.
|
|
26
|
+
*
|
|
27
|
+
* WHICH DIRECTION THIS FAILS IN. Towards "not met" and towards "not a wake". A condition whose
|
|
28
|
+
* fact is absent evaluates to `null` (unmeasured), never to `true`, so a hold never wakes on a
|
|
29
|
+
* guess. A line with one unparseable piece is refused whole, never read as its parseable rest:
|
|
30
|
+
* reading `issueClosed:o/r#12, until it is deployed` as just the first half would wake the hold
|
|
31
|
+
* early on part of its condition, which rule 1 forbids.
|
|
32
|
+
*/
|
|
33
|
+
|
|
34
|
+
// A cross-repo issue ref: `<owner>/<repo>#<n>`. Same character class the scheduler uses.
|
|
35
|
+
const QUALIFIED_ISSUE_RE = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#(\d+)$/;
|
|
36
|
+
const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
|
|
37
|
+
|
|
38
|
+
function isIsoDate(arg) {
|
|
39
|
+
if (!ISO_DATE_RE.test(arg)) return false;
|
|
40
|
+
const t = Date.parse(`${arg}T00:00:00Z`);
|
|
41
|
+
// Date.parse rolls 2026-02-31 over to March; round-trip it so an impossible date is refused.
|
|
42
|
+
return !Number.isNaN(t) && new Date(t).toISOString().slice(0, 10) === arg;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The checkable kinds, each with its argument validator — spelled and validated exactly as the
|
|
47
|
+
* adopting scheduler does (see the header). Frozen: this list is the vocabulary.
|
|
48
|
+
*/
|
|
49
|
+
const CHECKABLE = Object.freeze({
|
|
50
|
+
// Bare `<n>` (this repo's own issue) OR qualified `<owner>/<repo>#<n>` (another repo's).
|
|
51
|
+
issueClosed: (arg) => /^\d+$/.test(arg) || QUALIFIED_ISSUE_RE.test(arg),
|
|
52
|
+
branchLanded: (arg) => arg.length > 0 && !/\s/.test(arg),
|
|
53
|
+
trunkAt: (arg) => /^[0-9a-f]{7,40}$/i.test(arg),
|
|
54
|
+
labelPresent: (arg) => arg.length > 0,
|
|
55
|
+
// Epoch-ms digits OR anything Date.parse accepts — permissive on FORMAT only, because this is
|
|
56
|
+
// the one argument a human chooses; the kind itself is still closed.
|
|
57
|
+
after: (arg) => /^\d+$/.test(arg) || !Number.isNaN(Date.parse(arg)),
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
/** The handbook's own three forms, older than the checkable ones and unchanged by #382. */
|
|
61
|
+
const NATIVE = Object.freeze(['review-by', 'edge', 'ruling']);
|
|
62
|
+
|
|
63
|
+
/** Every kind a `wake:` may carry, in the order CONVENTIONS lists them. */
|
|
64
|
+
const WAKE_KINDS = Object.freeze([...NATIVE, ...Object.keys(CHECKABLE)]);
|
|
65
|
+
|
|
66
|
+
const WAKE_KINDS_TEXT = 'review-by:<date> · #N · ruling · issueClosed:<n|owner/repo#n> · ' +
|
|
67
|
+
'branchLanded:<ref> · trunkAt:<sha> · labelPresent:<label> · after:<date>';
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Parse ONE wake condition. `null` for anything outside the closed vocabulary, or whose argument
|
|
71
|
+
* fails its kind's validator — the caller treats `null` as "this line names no wake", never as
|
|
72
|
+
* "skip this piece".
|
|
73
|
+
* @returns {{kind:string, arg:string|null, raw:string}|null}
|
|
74
|
+
*/
|
|
75
|
+
function parseWake(raw) {
|
|
76
|
+
if (typeof raw !== 'string') return null;
|
|
77
|
+
const s = raw.trim();
|
|
78
|
+
if (s === '') return null;
|
|
79
|
+
if (s === 'ruling') return { kind: 'ruling', arg: null, raw: s };
|
|
80
|
+
const edge = /^#(\d+)$/.exec(s);
|
|
81
|
+
if (edge) return { kind: 'edge', arg: edge[1], raw: s };
|
|
82
|
+
const idx = s.indexOf(':');
|
|
83
|
+
if (idx <= 0) return null;
|
|
84
|
+
const kind = s.slice(0, idx);
|
|
85
|
+
const arg = s.slice(idx + 1);
|
|
86
|
+
if (arg === '') return null;
|
|
87
|
+
if (kind === 'review-by') return isIsoDate(arg) ? { kind, arg, raw: s } : null;
|
|
88
|
+
const validate = Object.prototype.hasOwnProperty.call(CHECKABLE, kind) ? CHECKABLE[kind] : null;
|
|
89
|
+
if (!validate || !validate(arg)) return null;
|
|
90
|
+
return { kind, arg, raw: s };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Parse the value of a `wake:` field — one condition, or several separated by commas, ANDed.
|
|
95
|
+
* Accepts the string as written on the `Hold:` line, or an array of condition strings.
|
|
96
|
+
* @returns {{ok:true, conditions:Array<{kind,arg,raw}>}|{ok:false, error:string}}
|
|
97
|
+
*/
|
|
98
|
+
function parseWakeLine(value) {
|
|
99
|
+
const parts = Array.isArray(value)
|
|
100
|
+
? value
|
|
101
|
+
: (typeof value === 'string' ? value.split(',') : null);
|
|
102
|
+
if (!parts) return { ok: false, error: 'wake: is missing' };
|
|
103
|
+
const pieces = parts.map((p) => (typeof p === 'string' ? p.trim() : p)).filter((p) => p !== '');
|
|
104
|
+
if (pieces.length === 0) return { ok: false, error: 'wake: is empty — a hold must name what ends it' };
|
|
105
|
+
const conditions = [];
|
|
106
|
+
for (const p of pieces) {
|
|
107
|
+
const c = parseWake(p);
|
|
108
|
+
if (!c) {
|
|
109
|
+
return {
|
|
110
|
+
ok: false,
|
|
111
|
+
error: `wake condition ${JSON.stringify(p)} is not in the closed vocabulary — ${WAKE_KINDS_TEXT}. ` +
|
|
112
|
+
'A wait with no checkable form stays prose in Because: and carries review-by:<date>.',
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
conditions.push(c);
|
|
116
|
+
}
|
|
117
|
+
return { ok: true, conditions };
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The facts that decide each kind, as a caller gathers them. Every key optional:
|
|
122
|
+
* now — epoch ms (for review-by / after); absent ⇒ dates unmeasured.
|
|
123
|
+
* issueClosed — { "<n>" | "<owner/repo#n>": true|false } (an edge's issue too, by number)
|
|
124
|
+
* branchLanded — { "<ref>": true|false } (ref is an ancestor of trunk)
|
|
125
|
+
* trunkAt — { "<sha>": true|false } (trunk contains sha)
|
|
126
|
+
* labels — string[] the held issue carries now
|
|
127
|
+
*
|
|
128
|
+
* `review-by:` and `after:` are met on or after their date (UTC midnight for a bare date).
|
|
129
|
+
* Returns `true` (met), `false` (measured, not met) or `null` (unmeasured — never guessed).
|
|
130
|
+
* `ruling` is always `null`: it waits on the owner's act, and the owner's act IS removing the
|
|
131
|
+
* label, so no fact could ever make it "met" before the hold is already gone.
|
|
132
|
+
*/
|
|
133
|
+
function evaluateWake(cond, facts) {
|
|
134
|
+
const f = facts && typeof facts === 'object' ? facts : {};
|
|
135
|
+
const lookup = (map, key) => {
|
|
136
|
+
if (!map || typeof map !== 'object' || !Object.prototype.hasOwnProperty.call(map, key)) return null;
|
|
137
|
+
return typeof map[key] === 'boolean' ? map[key] : null;
|
|
138
|
+
};
|
|
139
|
+
switch (cond && cond.kind) {
|
|
140
|
+
case 'review-by':
|
|
141
|
+
return Number.isFinite(f.now) ? f.now >= Date.parse(`${cond.arg}T00:00:00Z`) : null;
|
|
142
|
+
case 'after': {
|
|
143
|
+
if (!Number.isFinite(f.now)) return null;
|
|
144
|
+
const t = /^\d+$/.test(cond.arg) ? Number(cond.arg) : Date.parse(cond.arg);
|
|
145
|
+
return Number.isNaN(t) ? null : f.now >= t;
|
|
146
|
+
}
|
|
147
|
+
case 'edge':
|
|
148
|
+
case 'issueClosed':
|
|
149
|
+
return lookup(f.issueClosed, cond.arg);
|
|
150
|
+
case 'branchLanded':
|
|
151
|
+
return lookup(f.branchLanded, cond.arg);
|
|
152
|
+
case 'trunkAt':
|
|
153
|
+
return lookup(f.trunkAt, cond.arg);
|
|
154
|
+
case 'labelPresent':
|
|
155
|
+
return Array.isArray(f.labels) ? f.labels.includes(cond.arg) : null;
|
|
156
|
+
case 'ruling':
|
|
157
|
+
default:
|
|
158
|
+
return null;
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* AND over a parsed line: `true` only when EVERY condition is measured met; `false` as soon as
|
|
164
|
+
* one is measured not met; otherwise `null`. A hold never wakes early on part of its condition.
|
|
165
|
+
*/
|
|
166
|
+
function evaluateWakeLine(conditions, facts) {
|
|
167
|
+
if (!Array.isArray(conditions) || conditions.length === 0) return null;
|
|
168
|
+
let unmeasured = false;
|
|
169
|
+
for (const c of conditions) {
|
|
170
|
+
const v = evaluateWake(c, facts);
|
|
171
|
+
if (v === false) return false;
|
|
172
|
+
if (v !== true) unmeasured = true;
|
|
173
|
+
}
|
|
174
|
+
return unmeasured ? null : true;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
module.exports = {
|
|
178
|
+
WAKE_KINDS,
|
|
179
|
+
CHECKABLE_KINDS: Object.freeze(Object.keys(CHECKABLE)),
|
|
180
|
+
parseWake,
|
|
181
|
+
parseWakeLine,
|
|
182
|
+
evaluateWake,
|
|
183
|
+
evaluateWakeLine,
|
|
184
|
+
parseQualifiedIssueRef(arg) {
|
|
185
|
+
const m = QUALIFIED_ISSUE_RE.exec(String(arg));
|
|
186
|
+
return m ? { slug: m[1], number: Number(m[2]) } : null;
|
|
187
|
+
},
|
|
188
|
+
};
|
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/workflow-triggers.js — what a GitHub workflow's `on:` block fires on (#332, #338).
|
|
4
|
+
*
|
|
5
|
+
* Moved out of audit/audit.mjs, unchanged, so `colab release cut` refuses on exactly the trigger
|
|
6
|
+
* the audit flags — one reading of "would a candidate tag deploy?", not two. A CLI that cut a
|
|
7
|
+
* `-rc` tag the audit would have called a deploying one is the two-places drift this repo exists
|
|
8
|
+
* to kill (the release-policy.js precedent). audit.mjs consumes this through createRequire.
|
|
9
|
+
*
|
|
10
|
+
* CommonJS, pure: text in, facts out. Its one in-repo dependency is stamp.js's provenance reading
|
|
11
|
+
* (#346), so "is this our release-tag template?" has one answer, the one drift reporting trusts.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
const { parseWorkflowStamp, workflowProvenance } = require('./stamp.js');
|
|
15
|
+
|
|
16
|
+
// -------------------------------------------------------- workflow `on:` triggers
|
|
17
|
+
//
|
|
18
|
+
// project.yml gets a flat reader; a GitHub workflow's `on:` block is nested, so it
|
|
19
|
+
// gets its own pragmatic parser. Workflows are machine-formatted enough that a small
|
|
20
|
+
// indentation-aware scan (not a full YAML engine) reads triggers reliably. We only
|
|
21
|
+
// need a few facts per workflow: which events fire it, and — for push and
|
|
22
|
+
// pull_request — the branch/tag filter lists. Everything else is ignored on purpose.
|
|
23
|
+
//
|
|
24
|
+
// Returns { found, events:Set,
|
|
25
|
+
// pushBranches:[]|null, pushBranchesIgnore:[]|null, pushTags:[]|null,
|
|
26
|
+
// pushTagsIgnore:[]|null, prBranches:[]|null }.
|
|
27
|
+
// A null list means the filter is ABSENT. For push, absent branches + absent tags =
|
|
28
|
+
// "all branches" (a bare `push:` fires on every branch). Absent branches but PRESENT
|
|
29
|
+
// tags = "tags only" — no branch push at all (a release/tag workflow).
|
|
30
|
+
function parseWorkflowOn(text) {
|
|
31
|
+
const res = { found: false, events: new Set(), pushBranches: null, pushBranchesIgnore: null, pushTags: null, pushTagsIgnore: null, prBranches: null };
|
|
32
|
+
if (!text) return res;
|
|
33
|
+
const all = text.split(/\r?\n/);
|
|
34
|
+
let start = -1;
|
|
35
|
+
for (let i = 0; i < all.length; i++) {
|
|
36
|
+
// top-level `on:` at column 0 (YAML also lets it be quoted).
|
|
37
|
+
if (/^(on|["']on["'])\s*:/.test(all[i])) { start = i; break; }
|
|
38
|
+
}
|
|
39
|
+
if (start === -1) return res;
|
|
40
|
+
res.found = true;
|
|
41
|
+
const header = all[start];
|
|
42
|
+
const inline = header.slice(header.indexOf(":") + 1).replace(/#.*$/, "").trim();
|
|
43
|
+
|
|
44
|
+
// Inline forms `on: push` / `on: [push, pull_request]` carry no branch filters.
|
|
45
|
+
if (inline) {
|
|
46
|
+
const items = inline.startsWith("[") ? inline.replace(/^\[|\].*$/g, "").split(",") : [inline];
|
|
47
|
+
items.map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean).forEach((e) => res.events.add(e));
|
|
48
|
+
return res;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// Block form: everything indented past column 0 belongs to the `on:` block.
|
|
52
|
+
const body = [];
|
|
53
|
+
for (let i = start + 1; i < all.length; i++) {
|
|
54
|
+
if (/^\S/.test(all[i])) break; // next column-0 key ends the block
|
|
55
|
+
body.push(all[i]);
|
|
56
|
+
}
|
|
57
|
+
const meaningful = body.filter((l) => l.trim() && !/^\s*#/.test(l));
|
|
58
|
+
if (!meaningful.length) return res;
|
|
59
|
+
const childIndent = Math.min(...meaningful.map((l) => l.match(/^(\s*)/)[1].length));
|
|
60
|
+
|
|
61
|
+
for (let i = 0; i < body.length; i++) {
|
|
62
|
+
const m = body[i].match(/^(\s*)([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
|
|
63
|
+
if (!m || m[1].length !== childIndent) continue;
|
|
64
|
+
const ev = m[2];
|
|
65
|
+
res.events.add(ev);
|
|
66
|
+
if (ev !== "push" && ev !== "pull_request" && ev !== "pull_request_target") continue;
|
|
67
|
+
// The event's sub-block = following lines indented deeper than childIndent.
|
|
68
|
+
const sub = [];
|
|
69
|
+
for (let j = i + 1; j < body.length; j++) {
|
|
70
|
+
if (body[j].trim() === "") { sub.push(body[j]); continue; }
|
|
71
|
+
if (body[j].match(/^(\s*)/)[1].length <= childIndent) break;
|
|
72
|
+
sub.push(body[j]);
|
|
73
|
+
}
|
|
74
|
+
if (ev === "push") {
|
|
75
|
+
res.pushBranches = listField(sub, "branches");
|
|
76
|
+
res.pushBranchesIgnore = listField(sub, "branches-ignore");
|
|
77
|
+
res.pushTags = listField(sub, "tags");
|
|
78
|
+
res.pushTagsIgnore = listField(sub, "tags-ignore");
|
|
79
|
+
} else {
|
|
80
|
+
const b = listField(sub, "branches");
|
|
81
|
+
if (b !== null) res.prBranches = b;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return res;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// Extract a YAML list field ("branches"/"tags") from an event sub-block. Handles the
|
|
88
|
+
// flow form (`branches: [a, b]`), the block form (`branches:` then `- a` lines) and a
|
|
89
|
+
// bare scalar (`branches: main`). Returns null when the field is absent entirely.
|
|
90
|
+
function listField(subLines, field) {
|
|
91
|
+
const re = new RegExp("^(\\s*)" + field + "\\s*:\\s*(.*)$");
|
|
92
|
+
for (let i = 0; i < subLines.length; i++) {
|
|
93
|
+
const m = subLines[i].match(re);
|
|
94
|
+
if (!m) continue;
|
|
95
|
+
const indent = m[1].length;
|
|
96
|
+
const inline = m[2].replace(/#.*$/, "").trim();
|
|
97
|
+
if (inline) {
|
|
98
|
+
if (inline.startsWith("[")) {
|
|
99
|
+
return inline.replace(/^\[|\].*$/g, "").split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
|
|
100
|
+
}
|
|
101
|
+
return [inline.replace(/^["']|["']$/g, "")];
|
|
102
|
+
}
|
|
103
|
+
const out = [];
|
|
104
|
+
for (let j = i + 1; j < subLines.length; j++) {
|
|
105
|
+
if (subLines[j].trim() === "") continue;
|
|
106
|
+
const bm = subLines[j].match(/^(\s*)-\s*(.+)$/);
|
|
107
|
+
if (bm && bm[1].length > indent) {
|
|
108
|
+
out.push(bm[2].replace(/#.*$/, "").trim().replace(/^["']|["']$/g, ""));
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
if (subLines[j].match(/^(\s*)/)[1].length <= indent) break; // dedent ends the list
|
|
112
|
+
}
|
|
113
|
+
return out;
|
|
114
|
+
}
|
|
115
|
+
return null;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
// GitHub's filter-pattern glob, exactly (#332) — not audit.mjs's minimal globMatch, because the
|
|
119
|
+
// question this answers is whether a pre-release tag slips THROUGH a filter, and an approximation
|
|
120
|
+
// errs silently. Per GitHub's "filter pattern cheat sheet": `*` is any run of characters except
|
|
121
|
+
// `/` — so it DOES match `-`, which is the whole hazard (`v*.*.*` matches `v1.2.0-rc.1`); `**` is
|
|
122
|
+
// any run including `/`; `?` and `+` are zero-or-one / one-or-more of the PRECEDING character (not
|
|
123
|
+
// shell `?`); `[...]` is a character class; `\` escapes the next character. Everything else is
|
|
124
|
+
// literal, including `.`. Returns null for a pattern that does not compile.
|
|
125
|
+
function githubFilterRegex(pattern) {
|
|
126
|
+
const lit = (c) => c.replace(/[.*+?^${}()|[\]\\\/-]/g, "\\$&");
|
|
127
|
+
let rx = "";
|
|
128
|
+
for (let i = 0; i < pattern.length; i++) {
|
|
129
|
+
const c = pattern[i];
|
|
130
|
+
if (c === "\\" && i + 1 < pattern.length) { rx += lit(pattern[++i]); continue; }
|
|
131
|
+
if (c === "*") {
|
|
132
|
+
if (pattern[i + 1] === "*") { rx += ".*"; i++; } else rx += "[^/]*";
|
|
133
|
+
continue;
|
|
134
|
+
}
|
|
135
|
+
if ((c === "?" || c === "+") && rx) { rx += c; continue; }
|
|
136
|
+
if (c === "[") {
|
|
137
|
+
const close = pattern.indexOf("]", i + 1);
|
|
138
|
+
if (close > i + 1) { rx += "[" + pattern.slice(i + 1, close).replace(/\\/g, "\\\\") + "]"; i = close; continue; }
|
|
139
|
+
}
|
|
140
|
+
rx += lit(c);
|
|
141
|
+
}
|
|
142
|
+
try { return new RegExp("^" + rx + "$"); } catch { return null; }
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
// A GitHub include-filter list (`tags:`, `branches:`) evaluated the way GitHub does: patterns in
|
|
146
|
+
// order, a `!` pattern excludes what it matches, a LATER positive pattern re-includes it. The last
|
|
147
|
+
// pattern that matches decides; none matching means not included.
|
|
148
|
+
function githubFilterMatches(patterns, ref) {
|
|
149
|
+
let included = false;
|
|
150
|
+
for (const raw of patterns) {
|
|
151
|
+
const neg = raw.startsWith("!");
|
|
152
|
+
const rx = githubFilterRegex(neg ? raw.slice(1) : raw);
|
|
153
|
+
if (rx && rx.test(ref)) included = !neg;
|
|
154
|
+
}
|
|
155
|
+
return included;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
// Does a parsed `on:` block (parseWorkflowOn) fire on a push of tag `tag`? GitHub's rules: a
|
|
159
|
+
// `tags:` list decides by inclusion; a `tags-ignore:` list fires on every tag it does not match; a
|
|
160
|
+
// push with NO ref filter at all fires on every branch AND every tag; a push filtered by branches
|
|
161
|
+
// only never fires on a tag.
|
|
162
|
+
function workflowFiresOnTag(on, tag) {
|
|
163
|
+
if (!on.found || !on.events.has("push")) return false;
|
|
164
|
+
if (on.pushTags !== null) return githubFilterMatches(on.pushTags, tag);
|
|
165
|
+
if (on.pushTagsIgnore !== null) return !githubFilterMatches(on.pushTagsIgnore, tag);
|
|
166
|
+
return on.pushBranches === null && on.pushBranchesIgnore === null;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// ---- a deploy trigger that fires on a pre-release tag (#332) ---------------
|
|
170
|
+
// GitHub's tag glob `*` matches `-`, so `v*.*.*` and `v*` both fire on `v1.2.0-rc.1`: the first
|
|
171
|
+
// release-candidate tag would deploy. In scope: every deploy-*.yml, plus — when `deploy: tag` says a
|
|
172
|
+
// tag IS the path to production — any other workflow carrying an explicit tag filter, whatever it is
|
|
173
|
+
// named, except a copy of the handbook's own release-tag template (isReleaseTagTemplateCopy, #346).
|
|
174
|
+
// Severity follows reach: `fail` under `deploy: tag` (production is reachable by that tag),
|
|
175
|
+
// `warn` elsewhere. The audit maps severity onto its fail/warn; `colab release cut` refuses on
|
|
176
|
+
// either, because both mean "cutting a candidate runs a deploy".
|
|
177
|
+
const PRERELEASE_TAG_PROBE = "v1.2.0-rc.1";
|
|
178
|
+
|
|
179
|
+
/** Workflow file names that count as deploy workflows by name (`deploy-*.yml`, `deploy.yml`). */
|
|
180
|
+
/**
|
|
181
|
+
* Does a workflow fire on a push to BRANCH `branch` (#373)? The branch-side sibling of
|
|
182
|
+
* workflowFiresOnTag, same filter semantics: `branches:` decides by inclusion, `branches-ignore:`
|
|
183
|
+
* fires on everything it does not match, a bare `push:` fires on every branch, and a push filtered
|
|
184
|
+
* by tags only (no branch filter) never fires on a branch at all.
|
|
185
|
+
*/
|
|
186
|
+
function workflowFiresOnBranchPush(on, branch) {
|
|
187
|
+
if (!on.found || !on.events.has("push")) return false;
|
|
188
|
+
if (on.pushBranches !== null) return githubFilterMatches(on.pushBranches, branch);
|
|
189
|
+
if (on.pushBranchesIgnore !== null) return !githubFilterMatches(on.pushBranchesIgnore, branch);
|
|
190
|
+
return on.pushTags === null && on.pushTagsIgnore === null;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* The workflow files (names under .github/workflows/) that fire on a push to `branch` (#373).
|
|
195
|
+
* `readFile(relPath)` returns the text or null, exactly as prereleaseTagTriggers takes it.
|
|
196
|
+
*/
|
|
197
|
+
function workflowsFiringOnBranchPush({ readFile, workflows, branch }) {
|
|
198
|
+
const out = [];
|
|
199
|
+
for (const wf of workflows || []) {
|
|
200
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
201
|
+
if (text && workflowFiresOnBranchPush(parseWorkflowOn(text), branch)) out.push(wf);
|
|
202
|
+
}
|
|
203
|
+
return out;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
function isDeployWorkflow(file) {
|
|
207
|
+
return /^deploy[-.]/.test(file);
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Is this workflow a copy of the handbook's `release-tag` template, and NOT deploy-named? (#346)
|
|
212
|
+
*
|
|
213
|
+
* That template fires on `v*.*.*` ON PURPOSE, candidates included, so a `-rc.N` tag publishes as a
|
|
214
|
+
* GitHub pre-release (#333). It publishes a Release record and deploys nothing — its header says
|
|
215
|
+
* deployment does not belong in it. Under `deploy: tag` the scope rule below would otherwise fail it
|
|
216
|
+
* for the very trigger it exists to have, with a "fix" that undoes #333.
|
|
217
|
+
*
|
|
218
|
+
* Identity is provenance, never the file name: the template's stamp (`colab-handbook: release-tag @`)
|
|
219
|
+
* or its fingerprints in stamp.js (header marker, coined step names) — the evidence drift reporting
|
|
220
|
+
* already trusts. A file merely NAMED release.yml / release-tag.yml gets no exemption (an empty
|
|
221
|
+
* template-name set means a name can never stand in for lineage here).
|
|
222
|
+
*
|
|
223
|
+
* Guardrail (ruling on #346): a `deploy-*.yml` / `deploy.yml` stays in scope even if it carries the
|
|
224
|
+
* stamp — a deploy-named file is presumed to deploy, whatever it was copied from. Accepted edge: an
|
|
225
|
+
* adopter who adds a deploy step to their copied release.yml is exempted too. The template header
|
|
226
|
+
* already says deployment does not belong there; this exemption holds them to it, it does not check.
|
|
227
|
+
*/
|
|
228
|
+
function isReleaseTagTemplateCopy(file, text) {
|
|
229
|
+
if (!text || isDeployWorkflow(file)) return false;
|
|
230
|
+
const stamp = parseWorkflowStamp(text);
|
|
231
|
+
if (stamp) return stamp.name === "release-tag";
|
|
232
|
+
return workflowProvenance(text, file.replace(/\.ya?ml$/, ""), new Set()).template === "release-tag";
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* `readFile(relPath)` returns a workflow's text (or null); `workflows` are file names under
|
|
237
|
+
* .github/workflows/; `deploy` is project.yml's value. Returns [{ workflow, trigger, level, text }].
|
|
238
|
+
*/
|
|
239
|
+
function prereleaseTagTriggers({ readFile, workflows, deploy }) {
|
|
240
|
+
const isTagDeploy = deploy === "tag";
|
|
241
|
+
const out = [];
|
|
242
|
+
for (const wf of workflows || []) {
|
|
243
|
+
const text = readFile(`.github/workflows/${wf}`);
|
|
244
|
+
if (isReleaseTagTemplateCopy(wf, text)) continue;
|
|
245
|
+
const on = parseWorkflowOn(text);
|
|
246
|
+
const inScope = isDeployWorkflow(wf) || (isTagDeploy && (on.pushTags !== null || on.pushTagsIgnore !== null));
|
|
247
|
+
if (!inScope || !workflowFiresOnTag(on, PRERELEASE_TAG_PROBE)) continue;
|
|
248
|
+
const trigger = on.pushTags !== null
|
|
249
|
+
? `push.tags ${JSON.stringify(on.pushTags)}`
|
|
250
|
+
: on.pushTagsIgnore !== null
|
|
251
|
+
? `push.tags-ignore ${JSON.stringify(on.pushTagsIgnore)}`
|
|
252
|
+
: "an unfiltered push trigger (fires on every tag)";
|
|
253
|
+
out.push({
|
|
254
|
+
workflow: wf,
|
|
255
|
+
trigger,
|
|
256
|
+
level: isTagDeploy ? "fail" : "warn",
|
|
257
|
+
text:
|
|
258
|
+
`.github/workflows/${wf}: ${trigger} matches the pre-release tag ${PRERELEASE_TAG_PROBE} — ` +
|
|
259
|
+
"GitHub's tag glob `*` matches `-`, so a release-candidate tag " +
|
|
260
|
+
(isTagDeploy ? "would deploy to production" : "would run this deploy") +
|
|
261
|
+
`. Fix: add "!v*.*.*-*" after the pattern, or use a strict pattern that cannot match "-" ` +
|
|
262
|
+
"(e.g. v[0-9]+.[0-9]+.[0-9]+)",
|
|
263
|
+
});
|
|
264
|
+
}
|
|
265
|
+
return out;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
module.exports = {
|
|
269
|
+
PRERELEASE_TAG_PROBE,
|
|
270
|
+
parseWorkflowOn, listField, githubFilterRegex, githubFilterMatches, workflowFiresOnTag,
|
|
271
|
+
workflowFiresOnBranchPush, workflowsFiringOnBranchPush,
|
|
272
|
+
isDeployWorkflow, isReleaseTagTemplateCopy, prereleaseTagTriggers,
|
|
273
|
+
};
|