@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.
Files changed (94) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +310 -3
  3. package/README.vi.md +280 -0
  4. package/audit/audit.mjs +3035 -0
  5. package/package.json +26 -5
  6. package/templates/README.md +257 -0
  7. package/templates/adr-README.md +57 -0
  8. package/templates/branch-name.yml +51 -0
  9. package/templates/ci-laravel.yml +540 -0
  10. package/templates/ci-node.yml +291 -0
  11. package/templates/ci-python.yml +281 -0
  12. package/templates/deploy-xserver.yml +531 -0
  13. package/templates/dist-refs.yml +177 -0
  14. package/templates/docs-lint.mjs +993 -0
  15. package/templates/docs-lint.yml +55 -0
  16. package/templates/gotchas-d-README.md +41 -0
  17. package/templates/identity-vocabulary.example +58 -0
  18. package/templates/npx-launcher.mjs +213 -0
  19. package/templates/pre-commit-dispatch +88 -0
  20. package/templates/pre-commit-identity +267 -0
  21. package/templates/pre-push-guard +137 -0
  22. package/templates/release-auto.yml +475 -0
  23. package/templates/release-tag.yml +245 -0
  24. package/templates/repo-CLAUDE-block.md +21 -0
  25. package/tools/colab +13785 -0
  26. package/tools/lib/adopt.js +882 -0
  27. package/tools/lib/axis-authority.js +96 -0
  28. package/tools/lib/base-ci-verdict.js +93 -0
  29. package/tools/lib/blocked-by.js +262 -0
  30. package/tools/lib/branch-name.js +137 -0
  31. package/tools/lib/checklist.js +143 -0
  32. package/tools/lib/ci-cure.js +512 -0
  33. package/tools/lib/ci-grant.js +307 -0
  34. package/tools/lib/ci-verdict.js +113 -0
  35. package/tools/lib/claim-comments.js +212 -0
  36. package/tools/lib/claim-identity.js +195 -0
  37. package/tools/lib/codeowners.js +208 -0
  38. package/tools/lib/consumer-evidence.js +74 -0
  39. package/tools/lib/container-close.js +141 -0
  40. package/tools/lib/cure-diff.js +267 -0
  41. package/tools/lib/decision-record.js +335 -0
  42. package/tools/lib/dirty-owner.js +150 -0
  43. package/tools/lib/disposition.js +378 -0
  44. package/tools/lib/docs-only.js +156 -0
  45. package/tools/lib/exposure-shape.js +207 -0
  46. package/tools/lib/gate.js +80 -0
  47. package/tools/lib/git.js +1059 -0
  48. package/tools/lib/group-labels.js +120 -0
  49. package/tools/lib/hermetic.js +193 -0
  50. package/tools/lib/identity.js +187 -0
  51. package/tools/lib/install-check.js +259 -0
  52. package/tools/lib/instruction-file.js +302 -0
  53. package/tools/lib/journal.js +430 -0
  54. package/tools/lib/labels.js +653 -0
  55. package/tools/lib/landed.js +230 -0
  56. package/tools/lib/local-adopt.js +133 -0
  57. package/tools/lib/lockfile-drift.js +119 -0
  58. package/tools/lib/machine-trailer.js +83 -0
  59. package/tools/lib/machine.js +238 -0
  60. package/tools/lib/migration-grant.js +641 -0
  61. package/tools/lib/migration-paths.js +135 -0
  62. package/tools/lib/notify.js +188 -0
  63. package/tools/lib/npm-publish-guard.js +242 -0
  64. package/tools/lib/orphan-worktree.js +127 -0
  65. package/tools/lib/owner-branch.js +182 -0
  66. package/tools/lib/place.js +782 -0
  67. package/tools/lib/ports.js +167 -0
  68. package/tools/lib/procs.js +185 -0
  69. package/tools/lib/readiness.js +240 -0
  70. package/tools/lib/records.js +185 -0
  71. package/tools/lib/refs-brake.js +95 -0
  72. package/tools/lib/release-channel.js +99 -0
  73. package/tools/lib/release-cut.js +822 -0
  74. package/tools/lib/release-finalize.js +481 -0
  75. package/tools/lib/release-policy.js +358 -0
  76. package/tools/lib/release-tag.js +225 -0
  77. package/tools/lib/ship-batch.js +277 -0
  78. package/tools/lib/ship-roles.js +71 -0
  79. package/tools/lib/ship-target-sync.js +181 -0
  80. package/tools/lib/shipguard.js +317 -0
  81. package/tools/lib/shipped-branch.js +56 -0
  82. package/tools/lib/solo.js +213 -0
  83. package/tools/lib/squash.js +515 -0
  84. package/tools/lib/stale-base.js +70 -0
  85. package/tools/lib/stamp.js +740 -0
  86. package/tools/lib/state.js +262 -0
  87. package/tools/lib/teardown.js +83 -0
  88. package/tools/lib/trust-humans.js +104 -0
  89. package/tools/lib/util.js +98 -0
  90. package/tools/lib/wake.js +188 -0
  91. package/tools/lib/workflow-triggers.js +273 -0
  92. package/tools/lib/writes-authority.js +237 -0
  93. package/tools/lib/yaml.js +101 -0
  94. 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
+ };