@futurelastic/colab-handbook 1.19.0-rc.1 → 1.19.1-rc.1
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/package.json +1 -1
- package/tools/colab +37 -7
- package/tools/lib/ci-forgejo.js +15 -2
- package/tools/lib/ci-wait.js +12 -1
- package/tools/lib/stale-base.js +47 -1
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -11991,6 +11991,7 @@ function readForgeCiVerdict(repoAbs, fc, target, trunk) {
|
|
|
11991
11991
|
if (!run) return unread(`${engine} commit-status read failed for ${target}@${shortSha(sha)} — cannot confirm CI`);
|
|
11992
11992
|
const at = `${via}@${shortSha(run.sha || sha)} (${engine} commit status)`;
|
|
11993
11993
|
let verdict = classifyCiRun(repoAbs, run, at);
|
|
11994
|
+
if (!verdict.ok) verdict = { ...verdict, detail: verdict.detail + notGreenNote(run) }; // #682: name the contexts
|
|
11994
11995
|
if (run.status === 'none' && target === trunk) {
|
|
11995
11996
|
const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
|
|
11996
11997
|
if (fresh.fresh) {
|
|
@@ -12066,6 +12067,12 @@ function classifyCiRun(repoAbs, run, at) {
|
|
|
12066
12067
|
return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) + verifyRuns.dispatchCountedNote(run && run.dispatchCounted) + readViaNote(run) };
|
|
12067
12068
|
}
|
|
12068
12069
|
|
|
12070
|
+
/** #682: a forge verdict's not-green contexts, named — '' on GitHub, or when every context is green. */
|
|
12071
|
+
function notGreenNote(run) {
|
|
12072
|
+
const ng = run && Array.isArray(run.notGreen) ? run.notGreen : [];
|
|
12073
|
+
return ng.length ? ` — not green: ${ng.map((x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`).join(', ')}` : '';
|
|
12074
|
+
}
|
|
12075
|
+
|
|
12069
12076
|
/**
|
|
12070
12077
|
* #651: the runs were read from the unfiltered `actions/runs` listing because the forge's filtered
|
|
12071
12078
|
* queries (`head_sha=` / `branch=`) answered nothing. The verdict is judged as usual. The note says
|
|
@@ -12278,9 +12285,16 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
|
|
|
12278
12285
|
if (headSha && fc) run = fc.ciVerdict(headSha, { branch });
|
|
12279
12286
|
else if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
|
|
12280
12287
|
// #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
|
|
12281
|
-
|
|
12288
|
+
// #682: on a forge, `headCi` is the branch head's own CI verdict (green / red / pending), its own
|
|
12289
|
+
// row — the class code-ship B1a reads through `colab ci-wait` on GitHub. null on GitHub, and where
|
|
12290
|
+
// the head has no run to judge (the stale-base row speaks for those).
|
|
12291
|
+
const headCi = fc ? staleBase.branchHeadCiVerdict({ headSha, run, branch, engine: fc.kind }) : null;
|
|
12292
|
+
return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ciReadable: !!(fc || gh) }), run, headSha, headCi };
|
|
12282
12293
|
}
|
|
12283
12294
|
|
|
12295
|
+
/** #682: the forge branch-head CI row's name — one spelling for the JSON and the prose table. */
|
|
12296
|
+
const BRANCH_HEAD_CI_ROW = 'branch CI green at its head (#682)';
|
|
12297
|
+
|
|
12284
12298
|
/**
|
|
12285
12299
|
* #294: WHICH paths are dirty in the trunk checkout, and — where the signal is strong enough — a
|
|
12286
12300
|
* likely owner. Never a precondition: it enriches the ALREADY-COMPUTED "trunk checkout ready"
|
|
@@ -13102,6 +13116,8 @@ function cmdShipDryJson(opts) {
|
|
|
13102
13116
|
} else {
|
|
13103
13117
|
checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
|
|
13104
13118
|
class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
|
|
13119
|
+
const hc = staleJson.headCi; // #682: forge only — a red head needs a person, a running one clears
|
|
13120
|
+
if (hc) checks.push({ name: BRANCH_HEAD_CI_ROW, ok: hc.ok, class: hc.ok ? null : (hc.selfClearing ? SELF_CLEARING : HUMAN_GATED), verdict: hc.verdict, detail: hc.detail });
|
|
13105
13121
|
}
|
|
13106
13122
|
// #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
|
|
13107
13123
|
// its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
|
|
@@ -14353,7 +14369,9 @@ function cmdShip(argv) {
|
|
|
14353
14369
|
docsRowOk = row.ok && docsCi.scan.ok;
|
|
14354
14370
|
} else {
|
|
14355
14371
|
checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
|
|
14372
|
+
if (staleResult.headCi) checks.push([staleResult.headCi.ok ? '✓' : '✗', BRANCH_HEAD_CI_ROW, staleResult.headCi.detail]); // #682
|
|
14356
14373
|
}
|
|
14374
|
+
const headCiOk = docsCi.applies || !staleResult.headCi || staleResult.headCi.ok;
|
|
14357
14375
|
// #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
|
|
14358
14376
|
// heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
|
|
14359
14377
|
// heavy lane at all, fails the table.
|
|
@@ -14385,7 +14403,7 @@ function cmdShip(argv) {
|
|
|
14385
14403
|
// issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
|
|
14386
14404
|
// have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
|
|
14387
14405
|
// checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
|
|
14388
|
-
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
|
|
14406
|
+
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && headCiOk && coreOk && recOk && heavyOk;
|
|
14389
14407
|
|
|
14390
14408
|
// ---- report the table ----
|
|
14391
14409
|
print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
|
|
@@ -16556,9 +16574,13 @@ Exit codes — branch on these, never on the text:
|
|
|
16556
16574
|
5 UNKNOWN a read failed or returned a state it cannot classify
|
|
16557
16575
|
6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
|
|
16558
16576
|
|
|
16577
|
+
On a remote the machine config's \`forges\` names as Forgejo (#678, #682), --sha reads the commit's
|
|
16578
|
+
combined status instead — no gh call, no conditional request; a status has no run id, so <run-id>
|
|
16579
|
+
is a usage error there. RED and --json name the contexts that are not green (\`notGreen\`).
|
|
16580
|
+
|
|
16559
16581
|
It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
|
|
16560
16582
|
--json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
|
|
16561
|
-
detail, status, conclusion, url }`;
|
|
16583
|
+
detail, status, conclusion, url, notGreen? }`;
|
|
16562
16584
|
|
|
16563
16585
|
function cmdCiWait(argv) {
|
|
16564
16586
|
const opts = parseArgs(argv, {
|
|
@@ -16587,9 +16609,16 @@ function cmdCiWait(argv) {
|
|
|
16587
16609
|
}
|
|
16588
16610
|
opts.sha = full;
|
|
16589
16611
|
}
|
|
16590
|
-
|
|
16612
|
+
// #682: a remote the engine map names as a forge (#678) is read from its commit statuses, never
|
|
16613
|
+
// through gh — which would answer `no known GitHub host` (exit 5) for every wait there.
|
|
16614
|
+
const fc = forgeCi(repoAbs);
|
|
16615
|
+
if (fc && runId) {
|
|
16616
|
+
warn(`the remote is a ${fc.kind} forge — a commit status has no run id to wait on; pass --sha <sha> [--branch <b>]`);
|
|
16617
|
+
return ciWait.EXIT.USAGE;
|
|
16618
|
+
}
|
|
16619
|
+
if (!fc && !git.ghInstalled()) { warn('gh is not installed — cannot read CI'); return ciWait.EXIT.UNKNOWN; }
|
|
16591
16620
|
|
|
16592
|
-
const target = runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}
|
|
16621
|
+
const target = (runId ? `run ${runId}` : `sha ${shortSha(opts.sha)}${opts.branch ? ` on ${opts.branch}` : ''}`) + (fc ? ` (${fc.kind} commit status)` : '');
|
|
16593
16622
|
const apiPath = runId
|
|
16594
16623
|
? `repos/{owner}/{repo}/actions/runs/${runId}`
|
|
16595
16624
|
: `repos/{owner}/{repo}/actions/runs?head_sha=${encodeURIComponent(opts.sha)}${opts.branch ? `&branch=${encodeURIComponent(opts.branch)}` : ''}&per_page=100`;
|
|
@@ -16619,7 +16648,7 @@ function cmdCiWait(argv) {
|
|
|
16619
16648
|
}
|
|
16620
16649
|
|
|
16621
16650
|
const verifyPolicy = verifyingPolicy(repoAbs);
|
|
16622
|
-
const poll = (etag) => {
|
|
16651
|
+
const poll = fc ? () => ciWait.forgePoll(fc.ciVerdict(opts.sha, { branch: opts.branch || null }), fc.kind) : (etag) => {
|
|
16623
16652
|
const r = git.ghApiConditional(repoAbs, apiPath, etag);
|
|
16624
16653
|
if (r.kind !== 'ok') return r;
|
|
16625
16654
|
let summary;
|
|
@@ -16665,11 +16694,12 @@ function cmdCiWait(argv) {
|
|
|
16665
16694
|
...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
|
|
16666
16695
|
...(Array.isArray(s.dispatchCounted) && s.dispatchCounted.length ? { dispatchCounted: s.dispatchCounted } : {}),
|
|
16667
16696
|
...(s.readVia ? { readVia: s.readVia } : {}), // #654: the verdict names how it was read
|
|
16697
|
+
...(Array.isArray(s.notGreen) && s.notGreen.length ? { notGreen: s.notGreen } : {}), // #682: forge contexts not green
|
|
16668
16698
|
};
|
|
16669
16699
|
if (opts.json) print(JSON.stringify(out, null, 2));
|
|
16670
16700
|
else {
|
|
16671
16701
|
print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
|
|
16672
|
-
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}`);
|
|
16702
|
+
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}${verifyRuns.dispatchCountedNote(s.dispatchCounted)}${readViaNote(s)}${notGreenNote(s)}`);
|
|
16673
16703
|
}
|
|
16674
16704
|
return code;
|
|
16675
16705
|
}
|
package/tools/lib/ci-forgejo.js
CHANGED
|
@@ -122,9 +122,22 @@ function create(repoAbs, eng) {
|
|
|
122
122
|
if (page === MAX_PAGES) return null; // more statuses than we read: never a partial verdict
|
|
123
123
|
}
|
|
124
124
|
const rows = rowsFromPages(full, pages);
|
|
125
|
-
|
|
125
|
+
if (rows === null) return null;
|
|
126
|
+
const summary = require('./git').summarizeRunsForCommit(rows, full);
|
|
127
|
+
// #682: additive — the contexts that keep this sha from green, so a refusal can name them.
|
|
128
|
+
const ng = notGreen(rows);
|
|
129
|
+
return ng.length ? { ...summary, notGreen: ng } : summary;
|
|
126
130
|
},
|
|
127
131
|
};
|
|
128
132
|
}
|
|
129
133
|
|
|
130
|
-
|
|
134
|
+
/**
|
|
135
|
+
* #682: every context that is not `success` — still pending, or finished red — in the compact
|
|
136
|
+
* `{name, status, conclusion}` shape a verdict detail names them by. Pure; [] when all are green.
|
|
137
|
+
*/
|
|
138
|
+
function notGreen(rows) {
|
|
139
|
+
return (rows || []).filter((x) => !(x.status === 'completed' && x.conclusion === 'success'))
|
|
140
|
+
.map((x) => ({ name: x.workflowName || 'unnamed', status: x.status, conclusion: x.conclusion || null }));
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, PAGE_LIMIT };
|
package/tools/lib/ci-wait.js
CHANGED
|
@@ -118,6 +118,17 @@ function runState(s) {
|
|
|
118
118
|
return 'unknown';
|
|
119
119
|
}
|
|
120
120
|
|
|
121
|
+
/**
|
|
122
|
+
* #682: one poll on a forge the engine map names, from its `ciVerdict` summary (tools/lib/ci-forgejo.js)
|
|
123
|
+
* — the waitLoop result shape, with no ETag (a forge read is never conditional, so no 304 can pin a
|
|
124
|
+
* stale state). A null summary is a failed read: `error`, which ends the wait UNKNOWN, never "keep
|
|
125
|
+
* waiting". Pure.
|
|
126
|
+
*/
|
|
127
|
+
function forgePoll(summary, engine = 'forge') {
|
|
128
|
+
if (!summary) return { kind: 'error', status: null, detail: `${engine} commit-status read failed` };
|
|
129
|
+
return { kind: 'ok', status: 200, etag: null, summary, state: runState(summary) };
|
|
130
|
+
}
|
|
131
|
+
|
|
121
132
|
/**
|
|
122
133
|
* #505: how many 304s in a row may stand for the state before the next poll re-reads without
|
|
123
134
|
* `If-None-Match`. Measured: the runs-list read kept answering 304 for ten minutes while every run
|
|
@@ -223,6 +234,6 @@ function sleepSync(ms) {
|
|
|
223
234
|
|
|
224
235
|
module.exports = {
|
|
225
236
|
EXIT, DEFAULT_SCHEDULE_SEC, DEFAULT_DEADLINE_SEC, DEFAULT_MAX_NOT_MODIFIED,
|
|
226
|
-
delayFor, parseHttp, classifyResponse, restRow, runState, waitLoop, fmtDuration, parseDuration,
|
|
237
|
+
delayFor, parseHttp, classifyResponse, restRow, runState, forgePoll, waitLoop, fmtDuration, parseDuration,
|
|
227
238
|
acquireLock, sleepSync,
|
|
228
239
|
};
|
package/tools/lib/stale-base.js
CHANGED
|
@@ -77,4 +77,50 @@ function staleBaseVerdict(a) {
|
|
|
77
77
|
'push, wait on the new run (15-minute bound), then re-run ship' };
|
|
78
78
|
}
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
/**
|
|
81
|
+
* #682: is the branch head's OWN CI green? Read on a forge the engine map names (#678), where no
|
|
82
|
+
* `colab ci-wait` used to exist for code-ship B1a to classify the branch with — so a red or running
|
|
83
|
+
* branch head passed `colab ship --dry` as READY on the stale-base row alone (that row asks only
|
|
84
|
+
* whether the run saw the base). The forge's summary is the same `ciVerdict` the trunk row reads.
|
|
85
|
+
*
|
|
86
|
+
* completed / success -> green, passes
|
|
87
|
+
* completed / other -> red, human-gated: a branch lands only on its own green (C7.contract.03);
|
|
88
|
+
* whether it is red:infra (one re-run) or red:finding (send back) is B1a's
|
|
89
|
+
* anything unfinished -> pending, self-clearing: wait (`colab ci-wait`), then ship again
|
|
90
|
+
*
|
|
91
|
+
* Returns null where this row says nothing: no head on the remote, an unread run (the stale-base
|
|
92
|
+
* row already refuses that as `unread`), or no status at all (the `none` row of Branch CI governs).
|
|
93
|
+
* `run.notGreen` (tools/lib/ci-forgejo.js) names the contexts that keep the sha from green.
|
|
94
|
+
*
|
|
95
|
+
* @param {object} a
|
|
96
|
+
* @param {string|null} a.headSha - the branch head on the remote
|
|
97
|
+
* @param {object|null} a.run - the forge's ciVerdict summary at headSha
|
|
98
|
+
* @param {string} a.branch
|
|
99
|
+
* @param {string} [a.engine] - for the detail line, e.g. 'forgejo'
|
|
100
|
+
* @returns {null|{ok:boolean, verdict:'green'|'red'|'pending', selfClearing:boolean, detail:string}}
|
|
101
|
+
*/
|
|
102
|
+
function branchHeadCiVerdict(a) {
|
|
103
|
+
const run = a && a.run;
|
|
104
|
+
if (!a || !a.headSha || !run || run.status === 'none') return null;
|
|
105
|
+
const at = `${a.branch}@${String(a.headSha).slice(0, 7)} (${a.engine || 'forge'} commit status)`;
|
|
106
|
+
const ng = Array.isArray(run.notGreen) ? run.notGreen : [];
|
|
107
|
+
const name = (x) => `${x.name} (${x.status === 'completed' ? (x.conclusion || 'none') : x.status})`;
|
|
108
|
+
if (run.status === 'completed' && run.conclusion === 'success') {
|
|
109
|
+
const n = run.runCount == null ? 1 : run.runCount;
|
|
110
|
+
return { ok: true, verdict: 'green', selfClearing: false, detail: `${n} context${n === 1 ? '' : 's'} at ${at}: ${n === 1 ? 'success' : 'all success'}` };
|
|
111
|
+
}
|
|
112
|
+
if (run.status === 'completed') {
|
|
113
|
+
const red = ng.filter((x) => x.status === 'completed');
|
|
114
|
+
const still = ng.filter((x) => x.status !== 'completed');
|
|
115
|
+
return { ok: false, verdict: 'red', selfClearing: false,
|
|
116
|
+
detail: `${at} is red — failing: ${red.length ? red.map(name).join(', ') : `conclusion=${run.conclusion || 'none'}`}` +
|
|
117
|
+
`${still.length ? `; still running: ${still.map(name).join(', ')}` : ''}. A branch lands only on its own green (C7.contract.03): ` +
|
|
118
|
+
'red:infra → re-run once; red:finding → send it back (code-ship B1a)' };
|
|
119
|
+
}
|
|
120
|
+
const still = ng.filter((x) => x.status !== 'completed');
|
|
121
|
+
return { ok: false, verdict: 'pending', selfClearing: true,
|
|
122
|
+
detail: `${at} has not finished — still running: ${still.length ? still.map(name).join(', ') : `status=${run.status}`}. ` +
|
|
123
|
+
`Wait with \`colab ci-wait --sha ${a.headSha} --branch ${a.branch}\`, then run ship again` };
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
module.exports = { staleBaseVerdict, branchHeadCiVerdict };
|