@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10
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 +248 -213
- package/README.vi.md +252 -186
- package/audit/audit.mjs +193 -10
- package/package.json +7 -1
- package/templates/README.md +30 -2
- package/templates/ci-laravel.yml +102 -21
- package/templates/ci-node.yml +61 -3
- package/templates/ci-python.yml +52 -3
- package/templates/deploy-adapter-portainer.mjs +206 -0
- package/templates/deploy-container-run.mjs +368 -0
- package/templates/deploy-container.yml +219 -0
- package/templates/dist-refs.yml +6 -0
- package/templates/docs-lint.mjs +1 -1
- package/templates/npx-launcher.mjs +118 -20
- package/templates/npx-service.mjs +828 -0
- package/templates/release-auto.yml +341 -32
- package/tools/colab +1902 -278
- package/tools/lib/adopt.js +373 -14
- package/tools/lib/branch-name.js +29 -1
- package/tools/lib/ci-cure.js +522 -31
- package/tools/lib/ci-grant.js +289 -22
- package/tools/lib/ci-wait.js +223 -0
- package/tools/lib/claim-comments.js +13 -64
- package/tools/lib/claim-identity.js +42 -7
- package/tools/lib/codec/claim.d.ts +41 -0
- package/tools/lib/codec/claim.js +153 -0
- package/tools/lib/codec/decision.d.ts +29 -0
- package/tools/lib/codec/decision.js +81 -0
- package/tools/lib/codec/grants.d.ts +82 -0
- package/tools/lib/codec/grants.js +268 -0
- package/tools/lib/codec/hold.d.ts +26 -0
- package/tools/lib/codec/hold.js +152 -0
- package/tools/lib/codec/index.d.ts +21 -0
- package/tools/lib/codec/index.js +32 -0
- package/tools/lib/codec/labels.d.ts +65 -0
- package/tools/lib/codec/labels.js +723 -0
- package/tools/lib/codec/markers.d.ts +35 -0
- package/tools/lib/codec/markers.js +138 -0
- package/tools/lib/codec/release.d.ts +17 -0
- package/tools/lib/codec/release.js +69 -0
- package/tools/lib/codec/samples.json +778 -0
- package/tools/lib/codeowners.js +68 -4
- package/tools/lib/container-close.js +38 -0
- package/tools/lib/cure-diff.js +198 -9
- package/tools/lib/decision-record.js +15 -39
- package/tools/lib/docs-only.js +15 -1
- package/tools/lib/exposure-shape.js +42 -8
- package/tools/lib/git.js +324 -42
- package/tools/lib/group-labels.js +65 -0
- package/tools/lib/install-check.js +14 -8
- package/tools/lib/install-route.js +139 -0
- package/tools/lib/instruction-file.js +1 -0
- package/tools/lib/labels.js +22 -647
- package/tools/lib/local-adopt.js +8 -4
- package/tools/lib/migration-grant.js +206 -104
- package/tools/lib/place.js +2 -2
- package/tools/lib/release-cut.js +199 -25
- package/tools/lib/release-finalize.js +111 -23
- package/tools/lib/release-policy.js +130 -22
- package/tools/lib/release-runner.js +125 -0
- package/tools/lib/release-tag.js +3 -1
- package/tools/lib/scratch-dirs.js +118 -0
- package/tools/lib/ship-batch.js +36 -1
- package/tools/lib/ship-human-door.js +76 -0
- package/tools/lib/stamp.js +7 -0
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +64 -0
- package/tools/lib/tree-green.js +88 -0
- package/tools/lib/util.js +17 -1
- package/tools/lib/verify-runs.js +104 -0
- package/tools/lib/wake.js +8 -90
- package/tools/lib/workflow-triggers.js +48 -0
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Trunk "tree already green" (#493) — the pure half of the rule, shared by `colab ship` / `colab
|
|
4
|
+
* trunk-ci` (tools/colab readCiVerdict) and the audit. No gh, no git, no I/O.
|
|
5
|
+
*
|
|
6
|
+
* THE RULE. A ship squash-merges a branch whose green run already contained the current base, so
|
|
7
|
+
* the trunk commit's tree is byte-identical to the tree that branch run passed. The CI templates'
|
|
8
|
+
* `dedupe` guard therefore skips the suite on a trunk push when it finds a green `push` run of the
|
|
9
|
+
* same workflow, on another ref of this repo, at exactly this tree — and leaves a
|
|
10
|
+
* `tree-already-green` notice annotation naming the run it relied on. A run in that shape (the
|
|
11
|
+
* guard succeeded, everything else skipped) concludes `success`, which is already the verdict;
|
|
12
|
+
* this module only lets the reader FIND the citation, and say so.
|
|
13
|
+
*
|
|
14
|
+
* Why read the citation from an annotation: job outputs and step summaries are not readable over
|
|
15
|
+
* the REST API, and a job name cannot carry a step output. An annotation is durable, shows in the
|
|
16
|
+
* UI, and is one call per skip-run. Why not recompute tree equality here instead: a second copy of
|
|
17
|
+
* the guard's matching logic in JavaScript is exactly the drift this repo keeps measuring.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
const NOTICE_TITLE = 'tree-already-green';
|
|
21
|
+
|
|
22
|
+
/** `tree-reuse:` in project.yml. Absent = reuse on. `off` = the one legal value. */
|
|
23
|
+
function parseTreeReuse(doc) {
|
|
24
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, 'tree-reuse');
|
|
25
|
+
if (!has || doc['tree-reuse'] === null || doc['tree-reuse'] === undefined) {
|
|
26
|
+
return { declared: false, valid: true, off: false, value: null, reason: 'tree-reuse absent — trunk may reuse a green run of an identical tree (#493)' };
|
|
27
|
+
}
|
|
28
|
+
const v = doc['tree-reuse'];
|
|
29
|
+
// YAML 1.1 readers turn a bare `off` into boolean false; both spell the same intent.
|
|
30
|
+
if (v === 'off' || v === false) {
|
|
31
|
+
return { declared: true, valid: true, off: true, value: 'off', reason: 'tree-reuse: off — trunk always runs its full suite' };
|
|
32
|
+
}
|
|
33
|
+
return {
|
|
34
|
+
declared: true, valid: false, off: true, value: v,
|
|
35
|
+
reason: `tree-reuse is ${JSON.stringify(v)} — the only defined value is "off"; the CI guard reads ANY tree-reuse line as off, so trunk runs its full suite, but say what you mean`,
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* From a commit's check runs (`[{id, name, status, conclusion, suite, annotations}]`), the ids of
|
|
41
|
+
* the check runs that ARE a tree-skip: in one check suite (one workflow run), exactly one job
|
|
42
|
+
* succeeded, it carries at least one annotation, and every other job was skipped (at least one).
|
|
43
|
+
* Name-independent on purpose — adopters rename jobs. Null in, null out (a failed read is not "none").
|
|
44
|
+
*/
|
|
45
|
+
function treeSkipCheckRuns(checkRuns) {
|
|
46
|
+
if (!Array.isArray(checkRuns)) return null;
|
|
47
|
+
const bySuite = new Map();
|
|
48
|
+
for (const c of checkRuns) {
|
|
49
|
+
if (!c || c.suite == null) continue;
|
|
50
|
+
if (!bySuite.has(c.suite)) bySuite.set(c.suite, []);
|
|
51
|
+
bySuite.get(c.suite).push(c);
|
|
52
|
+
}
|
|
53
|
+
const ids = [];
|
|
54
|
+
for (const runs of bySuite.values()) {
|
|
55
|
+
const ok = runs.filter((c) => c.status === 'completed' && c.conclusion === 'success');
|
|
56
|
+
const skipped = runs.filter((c) => c.status === 'completed' && c.conclusion === 'skipped');
|
|
57
|
+
if (ok.length === 1 && skipped.length >= 1 && ok.length + skipped.length === runs.length && Number(ok[0].annotations) > 0) {
|
|
58
|
+
ids.push(ok[0].id);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return ids;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** The citation in a check run's annotations (`[{title, message}]`), or null. */
|
|
65
|
+
function parseCitation(annotations) {
|
|
66
|
+
if (!Array.isArray(annotations)) return null;
|
|
67
|
+
const a = annotations.find((x) => x && x.title === NOTICE_TITLE && typeof x.message === 'string');
|
|
68
|
+
if (!a) return null;
|
|
69
|
+
const m = a.message.trim().match(/^(\S+)\s+tree=([0-9a-f]+)\s+head=([0-9a-f]+)\s+branch=(\S+)$/i);
|
|
70
|
+
if (!m) return null;
|
|
71
|
+
const runId = (m[1].match(/\/runs\/(\d+)/) || [])[1] || null;
|
|
72
|
+
return { url: m[1], runId, tree: m[2], head: m[3], branch: m[4] };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The verdict suffix for a green trunk read that relied on cited runs. `cites`: [{url, branch,
|
|
77
|
+
* head, proof}] where proof is 'verified' | 'unverified'; `unreadable`: count of skip-runs whose
|
|
78
|
+
* citation could not be read. '' when there is nothing to say (an ordinary green run).
|
|
79
|
+
*/
|
|
80
|
+
function citationNote(cites, unreadable = 0) {
|
|
81
|
+
const parts = (cites || []).map((c) =>
|
|
82
|
+
`relied on ${c.url} (${c.branch}@${String(c.head).slice(0, 7)}${c.proof === 'verified' ? ', tree verified locally' : ', tree not verified locally'})`);
|
|
83
|
+
for (let i = 0; i < unreadable; i++) parts.push('cited run unreadable');
|
|
84
|
+
if (!parts.length) return '';
|
|
85
|
+
return ` — tree already green (#493): suite skipped, ${parts.join('; ')}`;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
module.exports = { NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, citationNote };
|
package/tools/lib/util.js
CHANGED
|
@@ -51,12 +51,19 @@ function humanAge(iso) {
|
|
|
51
51
|
* spec.flags : { '--json': 'json', '--force': 'force' } boolean flags
|
|
52
52
|
* spec.values : { '--repo': 'repo', '--count': 'count' } flags that take a value
|
|
53
53
|
* spec.aliases : { '--issue': '--issues' } map an alias to its canonical flag
|
|
54
|
+
* spec.lists : { '--refs': 'refs' } value flags that ACCUMULATE: a repeat is
|
|
55
|
+
* joined onto the earlier value(s) with ',' — the same as one comma list (#479)
|
|
56
|
+
* spec.once : true a repeated `values` flag is a usage error
|
|
57
|
+
* instead of last-one-wins (#479). Off by default: most commands keep the old
|
|
58
|
+
* overwrite, where a dropped value is harmless; turn it on where it is not.
|
|
54
59
|
* Positionals collected into result._ .
|
|
55
60
|
*/
|
|
56
61
|
function parseArgs(argv, spec = {}) {
|
|
57
62
|
const flags = spec.flags || {};
|
|
58
63
|
const values = spec.values || {};
|
|
59
64
|
const aliases = spec.aliases || {};
|
|
65
|
+
const lists = spec.lists || {};
|
|
66
|
+
const seen = new Set();
|
|
60
67
|
const out = { _: [] };
|
|
61
68
|
for (let i = 0; i < argv.length; i++) {
|
|
62
69
|
let a = argv[i];
|
|
@@ -66,9 +73,18 @@ function parseArgs(argv, spec = {}) {
|
|
|
66
73
|
const eq = a.indexOf('=');
|
|
67
74
|
if (a.startsWith('--') && eq !== -1) { inlineVal = a.slice(eq + 1); a = a.slice(0, eq); }
|
|
68
75
|
if (flags[a]) { out[flags[a]] = true; }
|
|
69
|
-
else if (
|
|
76
|
+
else if (lists[a]) {
|
|
70
77
|
const v = inlineVal !== null ? inlineVal : argv[++i];
|
|
71
78
|
if (v === undefined) throw new UserError(`Option ${a} needs a value`);
|
|
79
|
+
const k = lists[a];
|
|
80
|
+
out[k] = out[k] === undefined ? v : `${out[k]},${v}`;
|
|
81
|
+
} else if (values[a]) {
|
|
82
|
+
const v = inlineVal !== null ? inlineVal : argv[++i];
|
|
83
|
+
if (v === undefined) throw new UserError(`Option ${a} needs a value`);
|
|
84
|
+
if (spec.once && seen.has(values[a])) {
|
|
85
|
+
throw new UserError(`Option ${a} given more than once — only one value is accepted; pass it once`);
|
|
86
|
+
}
|
|
87
|
+
seen.add(values[a]);
|
|
72
88
|
out[values[a]] = v;
|
|
73
89
|
} else if (a.startsWith('-') && a !== '-') {
|
|
74
90
|
throw new UserError(`Unknown option: ${a}`);
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Which workflow runs at a sha VERIFY the code there (#503) — the pure half of the rule `colab
|
|
4
|
+
* ship`'s CI gate, `colab trunk-ci` and `colab ci-wait` read. No gh, no git, no I/O.
|
|
5
|
+
*
|
|
6
|
+
* THE RULE. A run counts toward "is this sha green" when its trigger is a push or a pull request
|
|
7
|
+
* (`push`, `pull_request`, `pull_request_target`, `merge_group`) — the triggers that run a suite
|
|
8
|
+
* against the code. A run of any OTHER trigger is set aside and named: `workflow_run` (the
|
|
9
|
+
* handbook's own `release-auto.yml` fires on CI's completion, cuts a candidate, publishes, deploys
|
|
10
|
+
* to staging — 20–30 min after the verifying run already finished), `schedule` (the same template's
|
|
11
|
+
* daily finalize lands on trunk's head too), `workflow_dispatch`, `release`, `deployment`, … Those
|
|
12
|
+
* runs come AFTER the verdict and act on it; their failure belongs to the release lane, so they
|
|
13
|
+
* must neither turn trunk red for ship nor make ship wait for them.
|
|
14
|
+
*
|
|
15
|
+
* Measured (one adopted fork, 2026-10-05): CI green at 15:18Z, `Release (auto)` then in progress at
|
|
16
|
+
* the same trunk sha, and four green, graded candidates parked behind it — every landing cost one
|
|
17
|
+
* CI cycle plus one release cycle.
|
|
18
|
+
*
|
|
19
|
+
* A row with no `event` field (an older read, a hand-built fixture) is counted: absence of the field
|
|
20
|
+
* never excludes anything, so every verdict computable before #503 without it is computed the same.
|
|
21
|
+
*
|
|
22
|
+
* OVERRIDES (project.yml), matched against the run's workflow `name:` — the only workflow identity
|
|
23
|
+
* every run read carries (`gh run list` has no file path):
|
|
24
|
+
* ship-gate-workflows: [CI, Lint] the explicit set: exactly these workflows count, whatever
|
|
25
|
+
* their trigger; every other workflow is set aside.
|
|
26
|
+
* ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered (a deploy
|
|
27
|
+
* workflow that fires on a push to trunk). Wins over the gate
|
|
28
|
+
* list for a name in both.
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
const VERIFYING_EVENTS = Object.freeze(['push', 'pull_request', 'pull_request_target', 'merge_group']);
|
|
32
|
+
const GATE_KEY = 'ship-gate-workflows';
|
|
33
|
+
const IGNORE_KEY = 'ship-ignore-workflows';
|
|
34
|
+
|
|
35
|
+
/** One list key: absent → null; a non-empty list of non-empty strings → the names; else invalid. */
|
|
36
|
+
function parseNameList(doc, key) {
|
|
37
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, key);
|
|
38
|
+
if (!has || doc[key] === null || doc[key] === undefined) return { declared: false, valid: true, names: null };
|
|
39
|
+
let v = doc[key];
|
|
40
|
+
if (typeof v === 'string') v = [v];
|
|
41
|
+
if (!Array.isArray(v) || v.length === 0) {
|
|
42
|
+
return { declared: true, valid: false, names: null, reason: `${key} must be a non-empty list of workflow names (the workflow's \`name:\`), got ${JSON.stringify(doc[key])}` };
|
|
43
|
+
}
|
|
44
|
+
const bad = v.filter((x) => typeof x !== 'string' || !x.trim());
|
|
45
|
+
if (bad.length) {
|
|
46
|
+
return { declared: true, valid: false, names: null, reason: `${key} has ${bad.length} entr${bad.length === 1 ? 'y' : 'ies'} that ${bad.length === 1 ? 'is' : 'are'} not a workflow name: ${JSON.stringify(bad)}` };
|
|
47
|
+
}
|
|
48
|
+
return { declared: true, valid: true, names: v.map((x) => x.trim()) };
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* The policy from a parsed project.yml doc: `{ gate: string[]|null, ignore: string[], valid,
|
|
53
|
+
* problems: string[] }`. An invalid key is IGNORED by the reader (the default rule applies) and
|
|
54
|
+
* reported by the audit — a malformed override must not silently widen what ship counts as green
|
|
55
|
+
* in either direction, and the default is the measured-safe reading.
|
|
56
|
+
*/
|
|
57
|
+
function parsePolicy(doc) {
|
|
58
|
+
const g = parseNameList(doc, GATE_KEY);
|
|
59
|
+
const i = parseNameList(doc, IGNORE_KEY);
|
|
60
|
+
const problems = [g, i].filter((x) => !x.valid).map((x) => x.reason);
|
|
61
|
+
return {
|
|
62
|
+
gate: g.valid ? g.names : null,
|
|
63
|
+
ignore: i.valid && i.names ? i.names : [],
|
|
64
|
+
valid: problems.length === 0,
|
|
65
|
+
problems,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Why one row is set aside, or null when it counts. */
|
|
70
|
+
function setAsideReason(row, policy) {
|
|
71
|
+
const p = policy || { gate: null, ignore: [] };
|
|
72
|
+
const name = row && row.workflowName;
|
|
73
|
+
if (name && p.ignore && p.ignore.includes(name)) return `${IGNORE_KEY}`;
|
|
74
|
+
if (p.gate) return name && p.gate.includes(name) ? null : `not in ${GATE_KEY}`;
|
|
75
|
+
const ev = row && row.event;
|
|
76
|
+
if (ev === undefined || ev === null || ev === '') return null;
|
|
77
|
+
return VERIFYING_EVENTS.includes(ev) ? null : `event: ${ev}`;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Split rows into `{ counted, setAside }`; each set-aside row carries `setAsideWhy`. Null in → null out. */
|
|
81
|
+
function splitVerifying(rows, policy) {
|
|
82
|
+
if (!Array.isArray(rows)) return null;
|
|
83
|
+
const counted = [];
|
|
84
|
+
const setAside = [];
|
|
85
|
+
for (const r of rows) {
|
|
86
|
+
const why = setAsideReason(r, policy);
|
|
87
|
+
if (why) setAside.push({ ...r, setAsideWhy: why });
|
|
88
|
+
else counted.push(r);
|
|
89
|
+
}
|
|
90
|
+
return { counted, setAside };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The verdict-detail suffix naming what was set aside — '' when nothing was. `rows` is the compact
|
|
95
|
+
* summary shape (`{workflowName, status, conclusion, databaseId, why}`).
|
|
96
|
+
*/
|
|
97
|
+
function setAsideNote(rows) {
|
|
98
|
+
const list = Array.isArray(rows) ? rows : [];
|
|
99
|
+
if (!list.length) return '';
|
|
100
|
+
const names = list.map((x) => `${x.workflowName || 'unnamed'} (${x.conclusion || x.status || '?'}${x.databaseId ? `, run ${x.databaseId}` : ''}${x.why ? `; ${x.why}` : ''})`);
|
|
101
|
+
return ` — set aside ${list.length} run${list.length === 1 ? '' : 's'} that do${list.length === 1 ? 'es' : ''} not verify the code (post-CI release/deploy lane, #503): ${names.join(', ')}`;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote };
|
package/tools/lib/wake.js
CHANGED
|
@@ -31,91 +31,12 @@
|
|
|
31
31
|
* early on part of its condition, which rule 1 forbids.
|
|
32
32
|
*/
|
|
33
33
|
|
|
34
|
-
//
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
}
|
|
34
|
+
// The vocabulary and its parsers — CHECKABLE's validators, `parseWake`, `parseWakeLine`, the
|
|
35
|
+
// qualified-ref parser — live in codec/hold.js (#498, epic #496) beside the `Hold:` line they
|
|
36
|
+
// belong to. Re-exported below under the names this module always had; what stays here is
|
|
37
|
+
// EVALUATION, which needs facts a caller gathered and so is not wire format.
|
|
38
|
+
const codec = require('./codec/hold');
|
|
39
|
+
const { WAKE_KINDS, CHECKABLE_KINDS, parseWake, parseWakeLine, parseQualifiedIssueRef } = codec;
|
|
119
40
|
|
|
120
41
|
/**
|
|
121
42
|
* The facts that decide each kind, as a caller gathers them. Every key optional:
|
|
@@ -176,13 +97,10 @@ function evaluateWakeLine(conditions, facts) {
|
|
|
176
97
|
|
|
177
98
|
module.exports = {
|
|
178
99
|
WAKE_KINDS,
|
|
179
|
-
CHECKABLE_KINDS
|
|
100
|
+
CHECKABLE_KINDS,
|
|
180
101
|
parseWake,
|
|
181
102
|
parseWakeLine,
|
|
182
103
|
evaluateWake,
|
|
183
104
|
evaluateWakeLine,
|
|
184
|
-
parseQualifiedIssueRef
|
|
185
|
-
const m = QUALIFIED_ISSUE_RE.exec(String(arg));
|
|
186
|
-
return m ? { slug: m[1], number: Number(m[2]) } : null;
|
|
187
|
-
},
|
|
105
|
+
parseQualifiedIssueRef,
|
|
188
106
|
};
|
|
@@ -265,9 +265,57 @@ function prereleaseTagTriggers({ readFile, workflows, deploy }) {
|
|
|
265
265
|
return out;
|
|
266
266
|
}
|
|
267
267
|
|
|
268
|
+
// --------------------------------------------------- workflow_dispatch inputs (#474)
|
|
269
|
+
//
|
|
270
|
+
// The names declared under `on: workflow_dispatch: inputs:`, in order. `[]` for a bare
|
|
271
|
+
// `workflow_dispatch:` (or one with no inputs), and for a workflow with no dispatch trigger at all —
|
|
272
|
+
// a caller asking "can this be dispatched with dry_run?" needs the same answer for both. Same
|
|
273
|
+
// pragmatic, indentation-aware scan as parseWorkflowOn; the inline `on:` forms carry no inputs.
|
|
274
|
+
function workflowDispatchInputs(text) {
|
|
275
|
+
if (!text) return [];
|
|
276
|
+
const all = text.split(/\r?\n/);
|
|
277
|
+
const start = all.findIndex((l) => /^(on|["']on["'])\s*:\s*(#.*)?$/.test(l));
|
|
278
|
+
if (start === -1) return [];
|
|
279
|
+
const body = [];
|
|
280
|
+
for (let i = start + 1; i < all.length; i++) {
|
|
281
|
+
if (/^\S/.test(all[i])) break;
|
|
282
|
+
body.push(all[i]);
|
|
283
|
+
}
|
|
284
|
+
const indentOf = (l) => l.match(/^(\s*)/)[1].length;
|
|
285
|
+
const meaningful = (l) => l.trim() && !/^\s*#/.test(l);
|
|
286
|
+
const block = (from, parentIndent) => {
|
|
287
|
+
const out = [];
|
|
288
|
+
for (let j = from; j < body.length; j++) {
|
|
289
|
+
if (!meaningful(body[j])) continue;
|
|
290
|
+
if (indentOf(body[j]) <= parentIndent) break;
|
|
291
|
+
out.push(j);
|
|
292
|
+
}
|
|
293
|
+
return out;
|
|
294
|
+
};
|
|
295
|
+
const wd = body.findIndex((l) => /^\s*workflow_dispatch\s*:/.test(l));
|
|
296
|
+
if (wd === -1) return [];
|
|
297
|
+
const wdIndent = indentOf(body[wd]);
|
|
298
|
+
const inp = block(wd + 1, wdIndent).find((j) => /^\s*inputs\s*:\s*(#.*)?$/.test(body[j]));
|
|
299
|
+
if (inp === undefined) return [];
|
|
300
|
+
const lines = block(inp + 1, indentOf(body[inp]));
|
|
301
|
+
if (!lines.length) return [];
|
|
302
|
+
const keyIndent = Math.min(...lines.map((j) => indentOf(body[j])));
|
|
303
|
+
return lines.filter((j) => indentOf(body[j]) === keyIndent)
|
|
304
|
+
.map((j) => (body[j].match(/^\s*([A-Za-z_][\w-]*)\s*:/) || [])[1]).filter(Boolean);
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
// A workflow's top-level `name:` — what the runs API reports as `workflowName` — or null.
|
|
308
|
+
function workflowNameOf(text) {
|
|
309
|
+
if (!text) return null;
|
|
310
|
+
const m = text.match(/^name:\s*(.+?)\s*$/m);
|
|
311
|
+
if (!m) return null;
|
|
312
|
+
return m[1].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '').trim() || null;
|
|
313
|
+
}
|
|
314
|
+
|
|
268
315
|
module.exports = {
|
|
269
316
|
PRERELEASE_TAG_PROBE,
|
|
270
317
|
parseWorkflowOn, listField, githubFilterRegex, githubFilterMatches, workflowFiresOnTag,
|
|
271
318
|
workflowFiresOnBranchPush, workflowsFiringOnBranchPush,
|
|
272
319
|
isDeployWorkflow, isReleaseTagTemplateCopy, prereleaseTagTriggers,
|
|
320
|
+
workflowDispatchInputs, workflowNameOf,
|
|
273
321
|
};
|