@futurelastic/colab-handbook 1.12.0-rc.8 → 1.12.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 +7 -4
- package/README.vi.md +4 -2
- package/audit/audit.mjs +4 -2
- package/package.json +1 -1
- package/templates/README.md +21 -2
- package/templates/ci-laravel.yml +82 -0
- package/templates/ci-node.yml +79 -0
- package/templates/ci-python.yml +79 -0
- package/templates/pre-push-guard +21 -1
- package/templates/release-auto.yml +31 -6
- package/tools/colab +149 -22
- package/tools/lib/conflict-markers.js +47 -0
- package/tools/lib/hermetic.js +72 -6
- package/tools/lib/install-check.js +20 -1
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-finalize.js +51 -11
- package/tools/lib/ship-batch.js +11 -1
- package/tools/lib/stamp.js +38 -1
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* notify-endpoint.js — is this machine's `notifyUrl` set, and SHOULD it be? (#414)
|
|
4
|
+
*
|
|
5
|
+
* `notifyUrl` is optional by design (lib/notify.js): unset means colab makes no network call of its
|
|
6
|
+
* own, and silence is the right behaviour on a machine with no observer. But a machine that DOES run
|
|
7
|
+
* a local observer (a companion dashboard ingesting `issue.merged`, `issue.closed`,
|
|
8
|
+
* `readiness.marked`, `gate.recorded`) depends on the push for the kinds it cannot recover by
|
|
9
|
+
* polling state.json, and an unset key there is a silent outage. Measured on a two-machine fleet
|
|
10
|
+
* running the same observer: the machine set up by hand had recorded 2 292 `issue.merged` events;
|
|
11
|
+
* the one set up a month later with install.sh had 0, and nothing said so until someone asked for
|
|
12
|
+
* lead time.
|
|
13
|
+
*
|
|
14
|
+
* Two inputs answer "should it be set", and colab guesses neither:
|
|
15
|
+
*
|
|
16
|
+
* 1. an explicit URL a human passes to `install.sh --notify-url <url>`;
|
|
17
|
+
* 2. the DECLARED ENDPOINT FILE, `<COLAB_HOME>/notify-endpoint` — the convention by which a local
|
|
18
|
+
* observer announces itself. The observer writes its own events URL there (one http(s) URL on
|
|
19
|
+
* the first non-comment line); colab only reads it. No port is probed and no well-known URL is
|
|
20
|
+
* hard-coded: an observer's address is the observer's fact, not the handbook's.
|
|
21
|
+
*
|
|
22
|
+
* What reads this:
|
|
23
|
+
* - install.sh seeds `notifyUrl` from (1), else (2), ONLY when the key is absent — an existing
|
|
24
|
+
* value is someone's deliberate choice and is never overwritten. When nothing seeds it, install
|
|
25
|
+
* says plainly that the key is unset and what that costs.
|
|
26
|
+
* - `install.sh --check` and `colab doctor` report `notifyUrl: unset` when (2) exists and the key
|
|
27
|
+
* does not. No declared endpoint → nothing is reported: silence stays right for a machine with
|
|
28
|
+
* no observer.
|
|
29
|
+
*
|
|
30
|
+
* CommonJS, zero dependencies. Runnable as a script (install.sh's entry):
|
|
31
|
+
* node tools/lib/notify-endpoint.js seed --colab-home <dir> [--url <url>] [--dry]
|
|
32
|
+
* It writes config.json through lib/state.js, the CLI's own writer, so the file's shape cannot drift
|
|
33
|
+
* from what `colab config set` produces. state.js reads COLAB_HOME at require time, so the entry
|
|
34
|
+
* sets it from --colab-home before requiring it.
|
|
35
|
+
*/
|
|
36
|
+
|
|
37
|
+
const fs = require('fs');
|
|
38
|
+
const path = require('path');
|
|
39
|
+
|
|
40
|
+
const ENDPOINT_FILE = 'notify-endpoint';
|
|
41
|
+
const HTTP_RE = /^https?:\/\//i;
|
|
42
|
+
|
|
43
|
+
/** The event kinds a local observer only learns of by push — named in the "unset" line. */
|
|
44
|
+
const PUSH_ONLY_KINDS = Object.freeze(['issue.merged', 'issue.closed', 'readiness.marked', 'gate.recorded']);
|
|
45
|
+
|
|
46
|
+
function endpointFile(colabHome) {
|
|
47
|
+
return path.join(colabHome, ENDPOINT_FILE);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Read the declared endpoint. Returns null when no file exists (the common, silent case), else
|
|
52
|
+
* `{ file, url }` for a usable URL or `{ file, invalid }` naming what is wrong with it — a declared
|
|
53
|
+
* endpoint that cannot be used is reported, never silently treated as absent.
|
|
54
|
+
*/
|
|
55
|
+
function readDeclared(colabHome) {
|
|
56
|
+
const file = endpointFile(colabHome);
|
|
57
|
+
let raw;
|
|
58
|
+
try { raw = fs.readFileSync(file, 'utf8'); } catch (_) { return null; }
|
|
59
|
+
const line = raw.split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).find(Boolean);
|
|
60
|
+
if (!line) return { file, invalid: 'empty — no URL on any non-comment line' };
|
|
61
|
+
if (!HTTP_RE.test(line)) return { file, invalid: `not an http(s) URL: ${line}` };
|
|
62
|
+
return { file, url: line };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function configuredUrl(cfg) {
|
|
66
|
+
return cfg && typeof cfg.notifyUrl === 'string' ? cfg.notifyUrl.trim() : '';
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* The read-only verdict both health checks print. `state`:
|
|
71
|
+
* 'set' notifyUrl is configured (payload: url; `declared` when the file names another)
|
|
72
|
+
* 'unset-declared' notifyUrl absent while an observer declared an endpoint — the outage case
|
|
73
|
+
* 'declared-invalid' notifyUrl absent and the declared file is unusable
|
|
74
|
+
* 'unset' neither — a machine with no observer; callers stay silent
|
|
75
|
+
*/
|
|
76
|
+
function status(cfg, colabHome) {
|
|
77
|
+
const url = configuredUrl(cfg);
|
|
78
|
+
const declared = readDeclared(colabHome);
|
|
79
|
+
if (url) {
|
|
80
|
+
return declared && declared.url && declared.url !== url
|
|
81
|
+
? { state: 'set', url, declared }
|
|
82
|
+
: { state: 'set', url };
|
|
83
|
+
}
|
|
84
|
+
if (!declared) return { state: 'unset' };
|
|
85
|
+
if (declared.invalid) return { state: 'declared-invalid', declared };
|
|
86
|
+
return { state: 'unset-declared', declared };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** One human line for a status, or null when the right output is silence. */
|
|
90
|
+
function healthLine(st) {
|
|
91
|
+
if (st.state === 'unset-declared') {
|
|
92
|
+
return `notifyUrl: unset — ${st.declared.file} declares a local observer at ${st.declared.url}, ` +
|
|
93
|
+
`which receives no events (${PUSH_ONLY_KINDS.join(', ')}). Fix: colab config set notifyUrl ${st.declared.url}`;
|
|
94
|
+
}
|
|
95
|
+
if (st.state === 'declared-invalid') {
|
|
96
|
+
return `notifyUrl: unset — ${st.declared.file} is ${st.declared.invalid}, so nothing could be seeded from it`;
|
|
97
|
+
}
|
|
98
|
+
if (st.state === 'set' && st.declared) {
|
|
99
|
+
return `notifyUrl: ${st.url} — differs from the endpoint declared in ${st.declared.file} (${st.declared.url}); ` +
|
|
100
|
+
'left as configured, check which one the local observer listens on';
|
|
101
|
+
}
|
|
102
|
+
return null;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Decide what install.sh does. Pure: returns `{ action, url?, source?, lines[] }` and writes nothing.
|
|
107
|
+
* action 'keep' the key is already set — never overwritten
|
|
108
|
+
* action 'seed' write `url` (from the flag, else the declared file)
|
|
109
|
+
* action 'none' nothing to seed — the lines say plainly the key is unset and what it costs
|
|
110
|
+
*/
|
|
111
|
+
function plan({ cfg, colabHome, flagUrl }) {
|
|
112
|
+
const current = configuredUrl(cfg);
|
|
113
|
+
const declared = readDeclared(colabHome);
|
|
114
|
+
if (flagUrl && !HTTP_RE.test(flagUrl)) {
|
|
115
|
+
return { action: 'error', lines: [`--notify-url must be an http(s) URL, got: ${flagUrl}`] };
|
|
116
|
+
}
|
|
117
|
+
if (current) {
|
|
118
|
+
const lines = [`✓ notifyUrl = ${current} (already set → left untouched)`];
|
|
119
|
+
if (flagUrl && flagUrl !== current) {
|
|
120
|
+
lines.push(`⚠ --notify-url ${flagUrl} NOT applied: an existing value is never overwritten. ` +
|
|
121
|
+
`To change it: colab config set notifyUrl ${flagUrl}`);
|
|
122
|
+
}
|
|
123
|
+
const hl = healthLine(status(cfg, colabHome));
|
|
124
|
+
if (hl) lines.push(`⚠ ${hl}`);
|
|
125
|
+
return { action: 'keep', lines };
|
|
126
|
+
}
|
|
127
|
+
if (flagUrl) return { action: 'seed', url: flagUrl, source: '--notify-url', lines: [] };
|
|
128
|
+
if (declared && declared.url) return { action: 'seed', url: declared.url, source: declared.file, lines: [] };
|
|
129
|
+
const lines = [];
|
|
130
|
+
if (declared && declared.invalid) lines.push(`⚠ ${declared.file} is ${declared.invalid} — ignored.`);
|
|
131
|
+
lines.push(
|
|
132
|
+
'⚠ notifyUrl is UNSET — colab pushes no events from this machine.',
|
|
133
|
+
` A local observer (e.g. a companion dashboard) here will never receive ${PUSH_ONLY_KINDS.join(', ')}.`,
|
|
134
|
+
' Observer on this machine? Re-run with --notify-url <its events URL>, or: colab config set notifyUrl <url>',
|
|
135
|
+
' No observer here? Nothing to do — unset is the right default.',
|
|
136
|
+
);
|
|
137
|
+
return { action: 'none', lines };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function main(argv) {
|
|
141
|
+
const sub = argv[0];
|
|
142
|
+
const val = (flag) => {
|
|
143
|
+
const i = argv.indexOf(flag);
|
|
144
|
+
return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : undefined;
|
|
145
|
+
};
|
|
146
|
+
const colabHome = val('--colab-home') || process.env.COLAB_HOME || path.join(require('os').homedir(), '.colab');
|
|
147
|
+
if (sub !== 'seed') {
|
|
148
|
+
process.stderr.write('usage: notify-endpoint.js seed --colab-home <dir> [--url <url>] [--dry]\n');
|
|
149
|
+
return 2;
|
|
150
|
+
}
|
|
151
|
+
process.env.COLAB_HOME = colabHome; // before state.js computes its paths
|
|
152
|
+
const state = require('./state');
|
|
153
|
+
const cfg = state.loadConfig();
|
|
154
|
+
const p = plan({ cfg, colabHome, flagUrl: val('--url') });
|
|
155
|
+
const out = (l) => process.stdout.write(` ${l}\n`);
|
|
156
|
+
if (p.action === 'error') { process.stderr.write(` ✗ ${p.lines[0]}\n`); return 2; }
|
|
157
|
+
if (p.action !== 'seed') { p.lines.forEach(out); return 0; }
|
|
158
|
+
if (argv.includes('--dry')) { out(`[dry] seed notifyUrl = ${p.url} (from ${p.source})`); return 0; }
|
|
159
|
+
// Re-read inside the write: a key set between plan and write is still never overwritten.
|
|
160
|
+
const fresh = state.loadConfig();
|
|
161
|
+
if (configuredUrl(fresh)) { out(`✓ notifyUrl = ${configuredUrl(fresh)} (already set → left untouched)`); return 0; }
|
|
162
|
+
fresh.notifyUrl = p.url;
|
|
163
|
+
state.saveConfig(fresh);
|
|
164
|
+
out(`📡 notifyUrl seeded: ${p.url} (from ${p.source}) — colab now pushes its events there`);
|
|
165
|
+
return 0;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
if (require.main === module) process.exitCode = main(process.argv.slice(2));
|
|
169
|
+
|
|
170
|
+
module.exports = { ENDPOINT_FILE, PUSH_ONLY_KINDS, endpointFile, readDeclared, status, healthLine, plan, main };
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/release-channel.js — the release CHANNELS `next` and `stable` (#445).
|
|
4
|
+
*
|
|
5
|
+
* Adopters follow a channel, not a hand-bumped pin:
|
|
6
|
+
*
|
|
7
|
+
* next always the newest CANDIDATE (vX.Y.Z-rc.N) — moved by `colab release cut`
|
|
8
|
+
* stable always the newest FINAL (vX.Y.Z) — moved by `colab release finalize`
|
|
9
|
+
*
|
|
10
|
+
* They are BRANCHES, not tags. A moving tag is refused by every clone that already fetched it
|
|
11
|
+
* (`would clobber existing tag`), and a non-semver tag can be read as "the newest version" by tag
|
|
12
|
+
* readers (`git describe --tags`, stamps). A branch moves cleanly and no tag reader sees it. Version
|
|
13
|
+
* tags stay immutable.
|
|
14
|
+
*
|
|
15
|
+
* Forward only. A channel is fast-forwarded to the commit the tag names, never forced: a channel
|
|
16
|
+
* that is not an ancestor of that commit is a finding (somebody moved it by hand, or a branch of the
|
|
17
|
+
* same name means something else in this repo) and is reported, never overwritten. `stable` lagging
|
|
18
|
+
* behind `next` is the design, not drift — they are two channels, each moving forward on its own.
|
|
19
|
+
*
|
|
20
|
+
* Best-effort, like the GitHub pre-release (#443): the tag is already on the remote when a channel
|
|
21
|
+
* moves, so a channel that could not move is reported (warning, --json `channel.ok: false`) and
|
|
22
|
+
* never a reason to undo the tag. The next cut / finalize retries, and finalize's already-final path
|
|
23
|
+
* repairs a `stable` a dead run left behind.
|
|
24
|
+
*
|
|
25
|
+
* The push carries COLAB_RELEASE=1 — the process-identity assertion templates/pre-push-guard reads
|
|
26
|
+
* for these two refs, the COLAB_SHIP precedent. Nothing else writes them.
|
|
27
|
+
*
|
|
28
|
+
* Two halves: decideMove is pure (facts in, an action out); moveChannel measures and writes through
|
|
29
|
+
* git, on the remote it is given.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
const git = require('./git');
|
|
33
|
+
|
|
34
|
+
const CHANNELS = Object.freeze({ next: 'next', stable: 'stable' });
|
|
35
|
+
/** The env a release command pushes a channel with — what pre-push-guard lets through. */
|
|
36
|
+
const RELEASE_ENV = 'COLAB_RELEASE';
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* What to do with `channel`, given where it is now and where it should be.
|
|
40
|
+
*
|
|
41
|
+
* current the channel's commit on the remote, or null when the branch does not exist
|
|
42
|
+
* target the commit the tag names
|
|
43
|
+
* currentIsAncestor current is an ancestor of target (a fast-forward)
|
|
44
|
+
* targetIsAncestor target is an ancestor of current (the channel is already past it)
|
|
45
|
+
*
|
|
46
|
+
* Returns { action: 'create' | 'move' | 'noop' | 'refuse', detail }.
|
|
47
|
+
*/
|
|
48
|
+
function decideMove({ channel, current, target, label, currentIsAncestor, targetIsAncestor }) {
|
|
49
|
+
const at = label ? `${label} (${short(target)})` : short(target);
|
|
50
|
+
if (!target) return { action: 'refuse', detail: `${channel}: no target commit` };
|
|
51
|
+
if (!current) return { action: 'create', detail: `${channel} created at ${at}` };
|
|
52
|
+
if (current === target) return { action: 'noop', detail: `${channel} already at ${at}` };
|
|
53
|
+
if (currentIsAncestor) return { action: 'move', detail: `${channel} fast-forwarded ${short(current)} -> ${at}` };
|
|
54
|
+
if (targetIsAncestor) return { action: 'noop', detail: `${channel} already past ${at} (at ${short(current)}) — a channel only moves forward` };
|
|
55
|
+
return {
|
|
56
|
+
action: 'refuse',
|
|
57
|
+
detail: `${channel} NOT moved: it is at ${short(current)}, which is not an ancestor of ${at} — a channel only fast-forwards; find out who moved it before moving it back by hand`,
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function short(sha) { return sha ? String(sha).slice(0, 7) : '—'; }
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Move `channel` on `remote` to `sha` (the commit `label`, a tag, names). Forward only, never forced.
|
|
65
|
+
* Returns { channel, ok, action, detail } — ok is false only on a refusal or a failed push/read.
|
|
66
|
+
* With `dry`, measures and reports what it would do, writing nothing.
|
|
67
|
+
*/
|
|
68
|
+
function moveChannel(repoAbs, { remote, channel, sha, label, dry = false, env = process.env }) {
|
|
69
|
+
const fail = (detail) => ({ channel, ok: false, action: 'refuse', detail });
|
|
70
|
+
const ls = git.git(['ls-remote', '--heads', remote, `refs/heads/${channel}`], repoAbs);
|
|
71
|
+
if (!ls.ok) return fail(`${channel} NOT moved: could not read it on ${remote} (${(ls.stderr || '').split('\n')[0] || ls.code})`);
|
|
72
|
+
const line = ls.stdout.split('\n').find((l) => l.endsWith(`\trefs/heads/${channel}`));
|
|
73
|
+
const current = line ? line.split('\t')[0] : null;
|
|
74
|
+
|
|
75
|
+
let currentIsAncestor = false;
|
|
76
|
+
let targetIsAncestor = false;
|
|
77
|
+
if (current && current !== sha) {
|
|
78
|
+
// The channel's commit is not necessarily local yet (a clone that never fetched the branch).
|
|
79
|
+
const have = git.git(['cat-file', '-e', `${current}^{commit}`], repoAbs);
|
|
80
|
+
if (!have.ok) {
|
|
81
|
+
const f = git.git(['fetch', '--quiet', remote, `refs/heads/${channel}`], repoAbs);
|
|
82
|
+
if (!f.ok) return fail(`${channel} NOT moved: could not fetch it from ${remote} to check it only moves forward (${(f.stderr || '').split('\n')[0] || f.code})`);
|
|
83
|
+
}
|
|
84
|
+
currentIsAncestor = git.git(['merge-base', '--is-ancestor', current, sha], repoAbs).ok;
|
|
85
|
+
if (!currentIsAncestor) targetIsAncestor = git.git(['merge-base', '--is-ancestor', sha, current], repoAbs).ok;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const d = decideMove({ channel, current, target: sha, label, currentIsAncestor, targetIsAncestor });
|
|
89
|
+
if (d.action === 'refuse') return { channel, ok: false, ...d };
|
|
90
|
+
if (d.action === 'noop' || dry) return { channel, ok: true, ...d, ...(dry && d.action !== 'noop' ? { detail: `[--dry] would be: ${d.detail}` } : {}) };
|
|
91
|
+
|
|
92
|
+
// No --force, no lease: git itself refuses a non-fast-forward, so a channel moved meanwhile is
|
|
93
|
+
// refused here too rather than overwritten.
|
|
94
|
+
const push = git.run('git', ['push', remote, `${sha}:refs/heads/${channel}`], { cwd: repoAbs, env: { ...env, [RELEASE_ENV]: '1' } });
|
|
95
|
+
if (!push.ok) return fail(`${channel} NOT moved: git push ${remote} ${short(sha)}:refs/heads/${channel} failed (${(push.stderr || '').split('\n').filter(Boolean).pop() || push.code})`);
|
|
96
|
+
return { channel, ok: true, ...d };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
module.exports = { CHANNELS, RELEASE_ENV, decideMove, moveChannel };
|
|
@@ -26,7 +26,8 @@
|
|
|
26
26
|
* issue opened late can never shorten the window a human had to veto in;
|
|
27
27
|
* - events are comments on the issue carrying `<!-- colab:release-event k=v … -->` markers.
|
|
28
28
|
*
|
|
29
|
-
* Nothing else is stored: trunk-green-throughout is re-measured from GitHub's run list on every run
|
|
29
|
+
* Nothing else is stored: trunk-green-throughout is re-measured from GitHub's run list on every run —
|
|
30
|
+
* over `main` and, where project.yml's `trunk:` is another branch, that branch too (#437, windowBranches).
|
|
30
31
|
*
|
|
31
32
|
* `--auto` (#423) changes WHICH candidate a run judges, nothing else: instead of always the newest
|
|
32
33
|
* one (whose clock a daily cut keeps restarting, so on a repo cutting a candidate every day no
|
|
@@ -238,20 +239,22 @@ function periodVerdict({ cutAt, trackingCreatedAt, testPeriodDays, now }) {
|
|
|
238
239
|
}
|
|
239
240
|
|
|
240
241
|
/**
|
|
241
|
-
* Trunk CI green THROUGHOUT the period. `runs` is `gh run list --branch
|
|
242
|
-
* `truncated` true when
|
|
242
|
+
* Trunk CI green THROUGHOUT the period. `runs` is the window's `gh run list --branch <b>` rows, merged
|
|
243
|
+
* across windowBranches() by mergeWindowRuns() (null = unread), `truncated` true when a read hit its
|
|
244
|
+
* limit, `branches` the branches read (named in the detail). Only runs created at/after `periodStart`, of a
|
|
243
245
|
* workflow in `suiteWorkflows` (the workflows that vetted the candidate — an unrelated scheduled
|
|
244
246
|
* workflow cannot veto a release), and not `pull_request` events, count.
|
|
245
247
|
*
|
|
246
248
|
* Returns { ok, permanent, pending, detail }:
|
|
247
249
|
* - a completed run that failed (anything but success/skipped/neutral/cancelled) -> permanent:
|
|
248
250
|
* trunk was red during this candidate's period, and nothing later un-reds it;
|
|
249
|
-
* - cancelled -> fine when a LATER run of the same workflow succeeded or is still running
|
|
251
|
+
* - cancelled -> fine when a LATER run of the same workflow ON THE SAME BRANCH succeeded or is still running
|
|
250
252
|
* (pending), otherwise not clean (not permanent: a re-run can settle it);
|
|
251
253
|
* - a run still queued/in progress -> pending.
|
|
252
254
|
*/
|
|
253
|
-
function trunkGreenVerdict(runs, { periodStart, periodEnd = null, suiteWorkflows, truncated }) {
|
|
254
|
-
|
|
255
|
+
function trunkGreenVerdict(runs, { periodStart, periodEnd = null, suiteWorkflows, truncated, branches = ['main'] }) {
|
|
256
|
+
const on = (branches && branches.length ? branches : ['main']).join(' + ');
|
|
257
|
+
if (runs === null || runs === undefined) return { ok: false, permanent: false, pending: false, detail: `gh run list on ${on} failed — cannot confirm trunk stayed green` };
|
|
255
258
|
if (truncated) return { ok: false, permanent: false, pending: false, detail: 'the run list hit its read limit — cannot confirm trunk stayed green' };
|
|
256
259
|
const startMs = Date.parse(periodStart);
|
|
257
260
|
// #423: --auto bounds the window to the candidate's own period — a run after it closed is about newer code.
|
|
@@ -260,19 +263,56 @@ function trunkGreenVerdict(runs, { periodStart, periodEnd = null, suiteWorkflows
|
|
|
260
263
|
const inWindow = runs.filter((r) => r && Date.parse(r.createdAt) >= startMs && Date.parse(r.createdAt) < endMs && suite.has(r.workflowName || '(unnamed workflow)') && r.event !== 'pull_request');
|
|
261
264
|
const red = inWindow.filter((r) => r.status === 'completed' && !NOT_RED.has(r.conclusion) && r.conclusion !== 'cancelled');
|
|
262
265
|
if (red.length) {
|
|
263
|
-
return { ok: false, permanent: true, pending: false, detail: `trunk went red during the test period: ${red.map((r) => `${r.workflowName} ${r.conclusion} at ${String(r.headSha).slice(0, 7)} (${r.createdAt})`).join('; ')}` };
|
|
266
|
+
return { ok: false, permanent: true, pending: false, detail: `trunk went red during the test period: ${red.map((r) => `${r.workflowName} ${r.conclusion}${r.branch ? ` on ${r.branch}` : ''} at ${String(r.headSha).slice(0, 7)} (${r.createdAt})`).join('; ')}` };
|
|
264
267
|
}
|
|
265
268
|
const unsettled = [];
|
|
266
269
|
let pending = inWindow.some((r) => r.status !== 'completed');
|
|
267
270
|
for (const c of inWindow.filter((r) => r.status === 'completed' && r.conclusion === 'cancelled')) {
|
|
268
|
-
|
|
271
|
+
// #437: a later run on ANOTHER branch tested other code — it never settles this one's cancellation.
|
|
272
|
+
const later = inWindow.filter((r) => r.workflowName === c.workflowName && (r.branch || null) === (c.branch || null) && Date.parse(r.createdAt) > Date.parse(c.createdAt));
|
|
269
273
|
if (later.some((r) => r.status === 'completed' && r.conclusion === 'success')) continue;
|
|
270
274
|
if (later.some((r) => r.status !== 'completed')) { pending = true; continue; }
|
|
271
|
-
unsettled.push(`${c.workflowName} cancelled at ${String(c.headSha).slice(0, 7)} with no later run`);
|
|
275
|
+
unsettled.push(`${c.workflowName} cancelled${c.branch ? ` on ${c.branch}` : ''} at ${String(c.headSha).slice(0, 7)} with no later run`);
|
|
272
276
|
}
|
|
273
277
|
if (unsettled.length) return { ok: false, permanent: false, pending: false, detail: `not settled: ${unsettled.join('; ')}` };
|
|
274
278
|
if (pending) return { ok: false, permanent: false, pending: true, detail: 'a trunk run in the test period is still in flight' };
|
|
275
|
-
return { ok: true, permanent: false, pending: false, detail: `${inWindow.length}
|
|
279
|
+
return { ok: true, permanent: false, pending: false, detail: `${inWindow.length} run(s) on ${on} of the candidate's workflows since ${periodStart}${periodEnd ? ` until ${periodEnd}` : ''}, none red` };
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* #437: the branches whose runs make up the trunk-green window. Candidates are cut from `main`, so
|
|
284
|
+
* `main` is always read; where project.yml's `trunk:` is another branch (`trunk: dev` + `deploy: tag`)
|
|
285
|
+
* it is read too. On that shape `main` receives CI only at promotions, so a `main`-only window holds
|
|
286
|
+
* little beyond the promotion's own run and "trunk stayed green" would be close to vacuous — `trunk:`
|
|
287
|
+
* is where the code under test actually moves during the period. A red run there counts exactly as a
|
|
288
|
+
* red run on `main` does on `trunk: main`, where every run after the cut is newer code too.
|
|
289
|
+
*/
|
|
290
|
+
function windowBranches(trunk) {
|
|
291
|
+
const t = String(trunk || '').trim();
|
|
292
|
+
return t && t !== 'main' ? [t, 'main'] : ['main'];
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
/**
|
|
296
|
+
* #437: `reads` is [{ branch, read }] where `read` is ghRunsSince()'s { runs, truncated } or null. Returns
|
|
297
|
+
* { runs, truncated } with every row tagged `branch` (deduplicated by databaseId, first read wins), or
|
|
298
|
+
* null when ANY branch could not be read — a window missing one branch is not a window that was clean.
|
|
299
|
+
*/
|
|
300
|
+
function mergeWindowRuns(reads) {
|
|
301
|
+
const list = reads || [];
|
|
302
|
+
if (!list.length || list.some((x) => !x || !x.read || !Array.isArray(x.read.runs))) return null;
|
|
303
|
+
const seen = new Set();
|
|
304
|
+
const runs = [];
|
|
305
|
+
for (const { branch, read } of list) {
|
|
306
|
+
for (const r of read.runs) {
|
|
307
|
+
if (!r) continue;
|
|
308
|
+
if (r.databaseId !== undefined && r.databaseId !== null) {
|
|
309
|
+
if (seen.has(r.databaseId)) continue;
|
|
310
|
+
seen.add(r.databaseId);
|
|
311
|
+
}
|
|
312
|
+
runs.push({ ...r, branch });
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
return { runs, truncated: list.some((x) => !!x.read.truncated) };
|
|
276
316
|
}
|
|
277
317
|
|
|
278
318
|
/**
|
|
@@ -475,7 +515,7 @@ module.exports = {
|
|
|
475
515
|
STATES, CONDITIONS, HOLD_LABEL, CUT_SUBJECT_SUFFIX,
|
|
476
516
|
parseVersion, compareVersions, parseCandidate,
|
|
477
517
|
parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
|
|
478
|
-
selectCandidate, openCandidates, pickNewestClean, periodVerdict, trunkGreenVerdict, regressionVerdict,
|
|
518
|
+
selectCandidate, openCandidates, pickNewestClean, periodVerdict, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
|
|
479
519
|
handoffCommand, decide, tagMessage, migrationGrantVerdict,
|
|
480
520
|
carriedIssues, previousFinal, releasedEvent, releasedComment,
|
|
481
521
|
};
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -257,6 +257,16 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
|
|
|
257
257
|
return (batchRows || []).length >= a.length;
|
|
258
258
|
}
|
|
259
259
|
|
|
260
|
+
/**
|
|
261
|
+
* #415: branches the command line names that a staged batch does not carry, in command-line order.
|
|
262
|
+
* `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
|
|
263
|
+
* dropped at build is EXPECTED to be missing on resume — the caller must say so, never stay silent.
|
|
264
|
+
*/
|
|
265
|
+
function notStaged(requested, staged) {
|
|
266
|
+
const have = new Set((staged || []).map((m) => m && m.branch).filter(Boolean));
|
|
267
|
+
return [...new Set(requested || [])].filter((b) => b && !have.has(b));
|
|
268
|
+
}
|
|
269
|
+
|
|
260
270
|
/** The clause each member's 🚢 evidence comment gains: which combined run graded it. */
|
|
261
271
|
function evidenceSuffix({ n, ref, headSha, runIds }) {
|
|
262
272
|
const runs = (runIds || []).length ? (runIds || []).join(', ') : '(id unread)';
|
|
@@ -273,5 +283,5 @@ module.exports = {
|
|
|
273
283
|
MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
|
|
274
284
|
parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
|
|
275
285
|
branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
|
|
276
|
-
batchGreenCoversTrunk, evidenceSuffix, serialLine,
|
|
286
|
+
batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged,
|
|
277
287
|
};
|
package/tools/lib/stamp.js
CHANGED
|
@@ -86,6 +86,43 @@ function packageVersion(root) {
|
|
|
86
86
|
}
|
|
87
87
|
}
|
|
88
88
|
|
|
89
|
+
/** The npm name this CLI publishes under — must equal the root package.json's `name` (a test pins it). */
|
|
90
|
+
const PACKAGE_NAME = '@futurelastic/colab-handbook';
|
|
91
|
+
|
|
92
|
+
/** True when `root` is its own git checkout — the toplevel git finds IS `root`, not an enclosing repo. */
|
|
93
|
+
function ownsGit(root) {
|
|
94
|
+
const top = gitIn(root, ['rev-parse', '--show-toplevel']);
|
|
95
|
+
return top.ok && realPath(top.out) === realPath(require('path').resolve(root));
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* `{ root, version }` when `root` is THIS CLI installed from the npm registry, else null (#444).
|
|
100
|
+
*
|
|
101
|
+
* Three conditions, all required:
|
|
102
|
+
* - no git of its own (an enclosing repo does not count — see handbookInfo);
|
|
103
|
+
* - `<root>/package.json` names this package, so an unrelated package.json never qualifies;
|
|
104
|
+
* - `root` sits under a `node_modules/` directory. Without this, a handbook working tree that is
|
|
105
|
+
* file-synced to another machine with its `.git` deliberately left behind would pass the first
|
|
106
|
+
* two and be reported as a registry install. npx, `npm i` and `npm i -g` all install there.
|
|
107
|
+
*
|
|
108
|
+
* `version` is package.json's verbatim — a candidate's `1.12.0-rc.8` included. That is the point:
|
|
109
|
+
* this answers "which build is running", where handbookInfo answers "what may I stamp with", and a
|
|
110
|
+
* candidate is never the latter (#334) — so its stricter packageVersion is right for it, wrong here.
|
|
111
|
+
*/
|
|
112
|
+
function npmPackageInfo(root) {
|
|
113
|
+
const p = require('path');
|
|
114
|
+
if (!p.resolve(root).split(p.sep).includes('node_modules')) return null;
|
|
115
|
+
let j;
|
|
116
|
+
try {
|
|
117
|
+
j = JSON.parse(require('fs').readFileSync(p.join(root, 'package.json'), 'utf8'));
|
|
118
|
+
} catch (_) {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
if (!j || j.name !== PACKAGE_NAME || typeof j.version !== 'string' || !j.version) return null;
|
|
122
|
+
if (ownsGit(root)) return null;
|
|
123
|
+
return { root, version: j.version };
|
|
124
|
+
}
|
|
125
|
+
|
|
89
126
|
/**
|
|
90
127
|
* The handbook's own identity: { root, hasGit, untagged, version }.
|
|
91
128
|
* Before the first tag exists the version is 'v0' and `untagged` is true, which DEACTIVATES stamp
|
|
@@ -693,7 +730,7 @@ module.exports = {
|
|
|
693
730
|
FROZEN_STAMP_NAME, FROZEN_STAMP_FILE, FROZEN_SOURCES, classifyFrozen,
|
|
694
731
|
AUTHORITY_FLIP_VERSION,
|
|
695
732
|
gitIn, gitCommonDir, isHandbookItself,
|
|
696
|
-
handbookInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
|
|
733
|
+
handbookInfo, PACKAGE_NAME, npmPackageInfo, freezeVersion, templateNames, templateFiles, templateChangedSince, templateAt,
|
|
697
734
|
AXES, axesPredating,
|
|
698
735
|
WRITES_VETO_MARKER, writesRulingKnownAt,
|
|
699
736
|
stampLine, stampCommentPrefix, insertStamp, parseWorkflowStamp, parseClaudeStamp,
|