@futurelastic/colab-handbook 1.22.0-rc.2 → 1.22.0-rc.3
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 +91 -31
- package/tools/lib/ci-forgejo.js +11 -0
- package/tools/lib/ship-batch.js +54 -2
- package/tools/lib/tracker-fake.js +6 -0
- package/tools/lib/tracker-github.js +4 -0
- package/tools/lib/tracker-scenarios.json +27 -1
- package/tools/lib/tracker.js +10 -2
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -11720,7 +11720,13 @@ is pending, or green within ${shipBatch.LANE_GRACE_SEC / 60}m of settling (the s
|
|
|
11720
11720
|
combined run red — is deleted and the batch you asked for is built in its place, so the survivors of a
|
|
11721
11721
|
decline can batch without landing serially first (#391). A green one still unlanded past that grace lost
|
|
11722
11722
|
its lander and is deleted and rebuilt the same way; a green one whose settle time cannot be read is
|
|
11723
|
-
still waited on — only a provably abandoned batch is deleted (#659).
|
|
11723
|
+
still waited on — only a provably abandoned batch is deleted (#659). One whose combined run never
|
|
11724
|
+
started — no run ${shipBatch.LANE_GRACE_SEC / 60}m after it was built — is abandoned too; an unreadable build time waits (#742).
|
|
11725
|
+
The ref is the turn (#742): a build pushes it create-only, a split replaces it and a delete removes it
|
|
11726
|
+
only while it still holds the head this call read (--force-with-lease). Of two landers at one base
|
|
11727
|
+
exactly one push lands; the other prints "another lander took the turn" and exits 3 — run it again,
|
|
11728
|
+
it waits on the winner. The combined run is read through the forge engine (GitHub runs; on a Forgejo
|
|
11729
|
+
remote the commit statuses, where a re-run is not counted, so a red batch asks to be classified again).
|
|
11724
11730
|
A call that goes serial on trunk CI not green gives up on its members, so it deletes every batch at
|
|
11725
11731
|
trunk's tip whose members it ALL names (its run cancelled if still going) — nobody would ever land
|
|
11726
11732
|
it, and it would hold this base for every later call; a batch also carrying another member stays (#656).
|
|
@@ -16141,6 +16147,15 @@ function workflowsFiringAt(repoAbs, treeish, branch) {
|
|
|
16141
16147
|
return workflowTriggers.workflowsFiringOnBranchPush({ readFile, workflows, branch });
|
|
16142
16148
|
}
|
|
16143
16149
|
|
|
16150
|
+
/**
|
|
16151
|
+
* #742: every run on batch `ref` at `sha`, WITH its attempt and updatedAt — read through the forge
|
|
16152
|
+
* contract's `runsAtRef` (GitHub: `gh run list --branch`; Forgejo: the commit's statuses), so the batch
|
|
16153
|
+
* turn reads the same facts on every engine. null = could not read, never "no runs".
|
|
16154
|
+
*/
|
|
16155
|
+
function batchRunsAt(repoAbs, ref, sha) {
|
|
16156
|
+
return (forgeCi(repoAbs) || tracker.forRepo(repoAbs)).runsAtRef(ref, sha);
|
|
16157
|
+
}
|
|
16158
|
+
|
|
16144
16159
|
/**
|
|
16145
16160
|
* #373: may a green run on a `ship-batch/**` ref stand in for trunk's OWN run at the same sha? Only
|
|
16146
16161
|
* on a repo that declared `ship-batch` > 1, only for a head commit a batch landed (its Ship-Batch:
|
|
@@ -16153,8 +16168,9 @@ function shipBatchTrunkSubstitute(repoAbs, trunk, sha) {
|
|
|
16153
16168
|
if (!msg.ok) return null;
|
|
16154
16169
|
const tr = shipBatch.parseMemberTrailers([msg.stdout])[0];
|
|
16155
16170
|
if (!tr || !shipBatch.parseBatchRef(tr.ref)) return null;
|
|
16156
|
-
const
|
|
16157
|
-
const
|
|
16171
|
+
const fc = forgeCi(repoAbs);
|
|
16172
|
+
const trunkRows = fc ? fc.ciRunsAt(sha) : git.ghRunsForCommit(repoAbs, trunk, sha, 20);
|
|
16173
|
+
const batchRows = batchRunsAt(repoAbs, tr.ref, sha);
|
|
16158
16174
|
if (trunkRows === null || batchRows === null) return null;
|
|
16159
16175
|
const covers = shipBatch.batchGreenCoversTrunk({
|
|
16160
16176
|
trunkRows, batchRows,
|
|
@@ -16181,10 +16197,11 @@ function shipDryJsonReport(opts) {
|
|
|
16181
16197
|
* lib/ship-batch.js laneHold; this only reads the remote.
|
|
16182
16198
|
*
|
|
16183
16199
|
* Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
|
|
16184
|
-
* trunk, and gh is usable
|
|
16200
|
+
* trunk, and gh is usable — or the remote is a forge the engine map names (#742: its runs are read
|
|
16201
|
+
* through the engine). Out: null, or `{ held, ref, why, released, detail }`.
|
|
16185
16202
|
*/
|
|
16186
16203
|
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
|
|
16187
|
-
if (target !== trunk ||
|
|
16204
|
+
if (target !== trunk || shipBatch.parseShipBatch(doc).n <= 1 || (!gh && !forgeCi(repoAbs))) return null;
|
|
16188
16205
|
// #605: a TRUNK RED: cure is never held by a batch (or a chain) — trunk is red, and the cure is the
|
|
16189
16206
|
// way out; no batch can land on a red trunk anyway.
|
|
16190
16207
|
if (ciResult && ciResult.cureVerdict && ciResult.cureVerdict.ok) {
|
|
@@ -16201,7 +16218,7 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
|
|
|
16201
16218
|
const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
|
|
16202
16219
|
const atTip = refs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
16203
16220
|
const batches = atTip.map((x) => {
|
|
16204
|
-
const runs =
|
|
16221
|
+
const runs = batchRunsAt(repoAbs, x.parsed.ref, x.sha);
|
|
16205
16222
|
let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
|
|
16206
16223
|
if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
|
|
16207
16224
|
const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
|
|
@@ -16369,18 +16386,45 @@ function cmdShipBatch(opts) {
|
|
|
16369
16386
|
}
|
|
16370
16387
|
|
|
16371
16388
|
const gh = isGhUsable(repoAbs);
|
|
16372
|
-
|
|
16389
|
+
// #742: on a forge the engine map names, the combined run is read through its engine (runsAtRef).
|
|
16390
|
+
const fc = forgeCi(repoAbs);
|
|
16391
|
+
if (!gh && !fc) throw new UserError(`gh not usable (${ghUnusableWhy(repoAbs)}) — a batch cannot read its combined run`);
|
|
16373
16392
|
|
|
16374
16393
|
// #415: every write on the resume path goes through here or shipBatchLand — under --dry, neither writes.
|
|
16375
|
-
|
|
16394
|
+
// #742: every delete is leased on the head this call read (`sha`), so a ref another lander rebuilt in
|
|
16395
|
+
// between is never deleted from under it.
|
|
16396
|
+
const remoteRefSha = (ref) => {
|
|
16397
|
+
const r = git.git(['ls-remote', remote, `refs/heads/${ref}`], repoAbs);
|
|
16398
|
+
return r.ok ? (r.stdout.split('\t')[0] || '').trim() : null;
|
|
16399
|
+
};
|
|
16400
|
+
const deleteRef = (ref, sha) => {
|
|
16376
16401
|
if (opts.dry) { print(` [dry] would delete ${remote}/${ref}`); return true; }
|
|
16377
|
-
const d = git.git(
|
|
16378
|
-
if (!d.ok)
|
|
16402
|
+
const d = git.git(shipBatch.batchDeleteArgs({ remote, ref, expect: sha }), repoAbs);
|
|
16403
|
+
if (!d.ok) {
|
|
16404
|
+
const now = remoteRefSha(ref);
|
|
16405
|
+
warn(now !== null && now !== sha
|
|
16406
|
+
? `did not delete ${remote}/${ref}: it ${now ? `moved to ${shortSha(now)}` : 'is already gone'} since this call read it at ${shortSha(sha)} — another lander's turn; left as it is (#742)`
|
|
16407
|
+
: `could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
|
|
16408
|
+
}
|
|
16379
16409
|
return d.ok;
|
|
16380
16410
|
};
|
|
16411
|
+
// #742: a delete the next step depends on (the ref's base is then free for this call's build).
|
|
16412
|
+
// 'deleted' · 'moved' — another lander rewrote or removed it since it was read: the turn is not ours
|
|
16413
|
+
// to take on this call · 'failed' — any other refusal.
|
|
16414
|
+
const clearRef = (ref, sha) => {
|
|
16415
|
+
if (deleteRef(ref, sha)) return 'deleted';
|
|
16416
|
+
const now = remoteRefSha(ref);
|
|
16417
|
+
return now !== null && now !== sha ? 'moved' : 'failed';
|
|
16418
|
+
};
|
|
16419
|
+
const turnMoved = (ref) => {
|
|
16420
|
+
J.step = 'turn-lost';
|
|
16421
|
+
print(`⏸ ship-batch: ${ref} changed on ${remote} since this call read it — another lander took the turn at this base (#742). Nothing landed.`);
|
|
16422
|
+
print(' Run this command again: it reads the batch now there and waits on it, or builds once it lands or is declined.');
|
|
16423
|
+
return 3;
|
|
16424
|
+
};
|
|
16381
16425
|
// A ref nothing can land any more may still have its run going: cancel it rather than let it finish.
|
|
16382
16426
|
const cancelRuns = (ref, sha) => {
|
|
16383
|
-
for (const r of (
|
|
16427
|
+
for (const r of (batchRunsAt(repoAbs, ref, sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
|
|
16384
16428
|
if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${ref}`); continue; }
|
|
16385
16429
|
const cx = git.ghRunCancel(repoAbs, r.databaseId);
|
|
16386
16430
|
if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${ref} — it will finish on a ref that is gone`);
|
|
@@ -16417,7 +16461,7 @@ function cmdShipBatch(opts) {
|
|
|
16417
16461
|
const b = rooted.find((x) => x.ref === ref);
|
|
16418
16462
|
print(` ${ref} carries ${b.members.join(', ')} — every one going serial now, so nothing would ever land it; ${opts.dry ? 'would delete it [DRY RUN]' : 'deleting it'} (#656)`);
|
|
16419
16463
|
cancelRuns(ref, b.sha);
|
|
16420
|
-
deleteRef(ref);
|
|
16464
|
+
deleteRef(ref, b.sha);
|
|
16421
16465
|
}
|
|
16422
16466
|
}
|
|
16423
16467
|
if (trunkCi === 'pending') {
|
|
@@ -16457,7 +16501,7 @@ function cmdShipBatch(opts) {
|
|
|
16457
16501
|
print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
|
|
16458
16502
|
}
|
|
16459
16503
|
swept.push({ ref: b.parsed.ref, members: offTrunk ? carriedBy(b.parsed.ref, trunkNow, b.sha) : [] });
|
|
16460
|
-
deleteRef(b.parsed.ref);
|
|
16504
|
+
deleteRef(b.parsed.ref, b.sha);
|
|
16461
16505
|
}
|
|
16462
16506
|
const rooted = batchRefs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
16463
16507
|
// Every member the chain up to `sha` carries (branch → the ref carrying it), read from its trailers.
|
|
@@ -16499,13 +16543,13 @@ function cmdShipBatch(opts) {
|
|
|
16499
16543
|
print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
|
|
16500
16544
|
} else {
|
|
16501
16545
|
const pc = chains.get(want);
|
|
16502
|
-
const verdict = shipBatch.combinedVerdict(
|
|
16546
|
+
const verdict = shipBatch.combinedVerdict(batchRunsAt(repoAbs, want, p.sha), batchRead);
|
|
16503
16547
|
const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
|
|
16504
16548
|
if (verdict.state === 'red') {
|
|
16505
16549
|
if (child) {
|
|
16506
16550
|
const carried = carriedBy(child.parsed.ref, p.sha, child.sha);
|
|
16507
16551
|
print(`✗ ship-batch: ${want} is red (${verdict.why}) — it will not land at ${shortSha(p.sha)}, so ${child.parsed.ref} built on it cannot land in order. Nothing landed; ${child.parsed.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto once ${want} is settled.`);
|
|
16508
|
-
deleteRef(child.parsed.ref);
|
|
16552
|
+
deleteRef(child.parsed.ref, child.sha);
|
|
16509
16553
|
J.step = 'chained-decline';
|
|
16510
16554
|
return serial(`its parent ${want} was declined — rebuild on ${trunk} once it is settled`, carried.length ? carried.map((m) => m.branch) : members);
|
|
16511
16555
|
}
|
|
@@ -16532,8 +16576,12 @@ function cmdShipBatch(opts) {
|
|
|
16532
16576
|
// #659: nor is a green one past the lane grace (laneHold's rule) — its lander is gone.
|
|
16533
16577
|
let foreignStep = null;
|
|
16534
16578
|
if (foreign.length) {
|
|
16535
|
-
const runs =
|
|
16536
|
-
|
|
16579
|
+
const runs = batchRunsAt(repoAbs, atBase.parsed.ref, atBase.sha);
|
|
16580
|
+
// #742: its build time ages a batch whose combined run never started (the build commits its head).
|
|
16581
|
+
const bt = git.git(['log', '-1', '--format=%cI', atBase.sha], repoAbs);
|
|
16582
|
+
const builtAtMs = bt.ok ? Date.parse(bt.stdout.trim()) : NaN;
|
|
16583
|
+
foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs, batchRead), {
|
|
16584
|
+
settledAtMs: shipBatch.settledAt(runs), builtAtMs: Number.isFinite(builtAtMs) ? builtAtMs : null, nowMs: Date.now() });
|
|
16537
16585
|
}
|
|
16538
16586
|
if (foreignStep && foreignStep.step === 'wait') {
|
|
16539
16587
|
print(`⏸ ship-batch: another batch is in flight at this base — ${atBase.parsed.ref} carries ${inBatch.map((m) => m.branch).join(', ')}${foreignStep.why ? ` (${foreignStep.why})` : ''}.`);
|
|
@@ -16542,10 +16590,13 @@ function cmdShipBatch(opts) {
|
|
|
16542
16590
|
}
|
|
16543
16591
|
if (foreignStep) {
|
|
16544
16592
|
const carried = inBatch.map((m) => m.branch).join(', ');
|
|
16545
|
-
print(
|
|
16546
|
-
|
|
16547
|
-
: ` ${atBase.parsed.ref} (${carried}) was
|
|
16548
|
-
|
|
16593
|
+
print({
|
|
16594
|
+
abandoned: ` ${atBase.parsed.ref} (${carried}) was abandoned — its ${foreignStep.why}; nothing landed from it. Deleting it and building the requested batch.`,
|
|
16595
|
+
'never-started': ` ${atBase.parsed.ref} (${carried}) was abandoned — ${foreignStep.why}; nothing landed from it. Deleting it and building the requested batch (#742).`,
|
|
16596
|
+
}[foreignStep.reason] || ` ${atBase.parsed.ref} (${carried}) was declined — its combined run is red (${foreignStep.why}); nothing landed from it. Deleting it and building the requested batch.`);
|
|
16597
|
+
const cleared = opts.dry ? 'deleted' : clearRef(atBase.parsed.ref, atBase.sha);
|
|
16598
|
+
if (cleared === 'moved') return turnMoved(atBase.parsed.ref);
|
|
16599
|
+
if (cleared !== 'deleted') throw new UserError(`could not clear the ${foreignStep.reason === 'red' ? 'declined' : 'abandoned'} ${atBase.parsed.ref} — delete it by hand (\`git push ${remote} --delete ${atBase.parsed.ref}\`), then run this command again`);
|
|
16549
16600
|
}
|
|
16550
16601
|
if (!foreignStep) {
|
|
16551
16602
|
const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
|
|
@@ -16562,7 +16613,7 @@ function cmdShipBatch(opts) {
|
|
|
16562
16613
|
}
|
|
16563
16614
|
}
|
|
16564
16615
|
}
|
|
16565
|
-
let verdict = existing && existing.matches ? shipBatch.combinedVerdict(
|
|
16616
|
+
let verdict = existing && existing.matches ? shipBatch.combinedVerdict(batchRunsAt(repoAbs, existing.ref, existing.sha), batchRead) : null;
|
|
16566
16617
|
// #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
|
|
16567
16618
|
// heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
|
|
16568
16619
|
// the same re-run / split path a light red does, and the split walks toward the culprit.
|
|
@@ -16586,7 +16637,9 @@ function cmdShipBatch(opts) {
|
|
|
16586
16637
|
|
|
16587
16638
|
if (step.step === 'rebuild') {
|
|
16588
16639
|
print(` ${existing.ref} no longer carries the requested members at their current heads — rebuilding`);
|
|
16589
|
-
|
|
16640
|
+
const cleared = clearRef(existing.ref, existing.sha);
|
|
16641
|
+
if (cleared === 'moved') return turnMoved(existing.ref);
|
|
16642
|
+
if (cleared !== 'deleted') throw new UserError(`could not delete ${existing.ref} to rebuild it — delete it by hand (\`git push ${remote} --delete ${existing.ref}\`), then run this command again`);
|
|
16590
16643
|
existing = null;
|
|
16591
16644
|
step = { step: 'build' };
|
|
16592
16645
|
}
|
|
@@ -16625,7 +16678,7 @@ function cmdShipBatch(opts) {
|
|
|
16625
16678
|
}
|
|
16626
16679
|
if (step.step === 'red-serial') {
|
|
16627
16680
|
print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}.`);
|
|
16628
|
-
deleteRef(existing.ref);
|
|
16681
|
+
deleteRef(existing.ref, existing.sha);
|
|
16629
16682
|
print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
|
|
16630
16683
|
return 4;
|
|
16631
16684
|
}
|
|
@@ -16641,7 +16694,7 @@ function cmdShipBatch(opts) {
|
|
|
16641
16694
|
return 3;
|
|
16642
16695
|
}
|
|
16643
16696
|
print(`✗ ship-batch: ${existing.ref} cannot land in order — ${ls.why}. Nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto.`);
|
|
16644
|
-
deleteRef(existing.ref);
|
|
16697
|
+
deleteRef(existing.ref, existing.sha);
|
|
16645
16698
|
return serial('its parent batch was discarded', existing.members.map((m) => m.branch));
|
|
16646
16699
|
}
|
|
16647
16700
|
if (step.step === 'land') return shipBatchLand(repoAbs, doc, trunk, remote, trunkNow, existing, verdict, opts);
|
|
@@ -16664,7 +16717,7 @@ function cmdShipBatch(opts) {
|
|
|
16664
16717
|
...(handoffs[b] ? { handoff: handoffs[b] } : {}) });
|
|
16665
16718
|
report = rep.body;
|
|
16666
16719
|
files = branchChangedFiles(repoAbs, trunkRef, refs.remoteSha);
|
|
16667
|
-
ciClass = shipBatch.branchCiClass(git.ghRunForSha(repoAbs, b), workflowsFiringAt(repoAbs, refs.remoteSha, b).length > 0);
|
|
16720
|
+
ciClass = shipBatch.branchCiClass(fc ? fc.ciVerdict(refs.remoteSha, { branch: b }) : git.ghRunForSha(repoAbs, b), workflowsFiringAt(repoAbs, refs.remoteSha, b).length > 0);
|
|
16668
16721
|
const el = rep.error ? { ok: false, why: rep.error }
|
|
16669
16722
|
// #591: a refused hand-off is worded as the single door words it — the same reason, the same detail.
|
|
16670
16723
|
: (report && report.handoff && !report.handoff.ok) ? { ok: false, why: `Refusing --handoff: ${report.handoff.detail}` }
|
|
@@ -16699,7 +16752,7 @@ function cmdShipBatch(opts) {
|
|
|
16699
16752
|
// member is ready. Wait for a partner until the repo's window, counted from when it became ready.
|
|
16700
16753
|
const lone = selected[0];
|
|
16701
16754
|
const commitIso = git.git(['log', '-1', '--format=%cI', lone.sha], repoAbs);
|
|
16702
|
-
const since = shipBatch.readySince(git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
|
|
16755
|
+
const since = shipBatch.readySince(fc ? fc.ciRunsAt(lone.sha) : git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
|
|
16703
16756
|
const pw = shipBatch.partnerWait({ n: cfg.n, waitSec: waitCfg.sec, eligibleCount: 1, readySinceMs: since, nowMs: Date.now() });
|
|
16704
16757
|
if (pw.wait) {
|
|
16705
16758
|
print(`⏸ PARTNER-WAIT ${lone.branch} — the only ready member; ${waitCfg.reason}, ready since ${new Date(since).toISOString()}, ${ciWait.fmtDuration(pw.leftSec * 1000)} left. Nothing landed.`);
|
|
@@ -16819,10 +16872,17 @@ function cmdShipBatch(opts) {
|
|
|
16819
16872
|
if (notJoining.length || dropped.length) print(` not in this batch: ${[...new Set([...notJoining, ...dropped.map((d) => d.branch)])].join(', ')}`);
|
|
16820
16873
|
return 0;
|
|
16821
16874
|
}
|
|
16822
|
-
//
|
|
16823
|
-
|
|
16875
|
+
// #742: the push IS the turn, so it is leased: create-only when no batch is live at this base (a
|
|
16876
|
+
// fresh build, or one whose old ref this call just deleted), or — a split rebuilding its own ref in
|
|
16877
|
+
// place — only while the remote still holds the head this call read. Of two landers at one base,
|
|
16878
|
+
// exactly one push lands; the other reads the remote again and waits on the winner.
|
|
16879
|
+
const expect = existing && existing.ref === ref ? existing.sha : '';
|
|
16880
|
+
const push = git.run('git', shipBatch.batchPushArgs({ remote, head, ref, expect }), { cwd: repoAbs });
|
|
16824
16881
|
cleanup();
|
|
16825
|
-
if (!push.ok)
|
|
16882
|
+
if (!push.ok) {
|
|
16883
|
+
if (shipBatch.pushRefusal({ remoteSha: remoteRefSha(ref), head }) === 'turn-lost') return turnMoved(ref);
|
|
16884
|
+
throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
|
|
16885
|
+
}
|
|
16826
16886
|
print(` pushed ${ref} = ${shortSha(base)} + ${built.length} commit(s) @ ${shortSha(head)} (${built.map((b) => b.branch).join(', ')})${parent ? ` — chained onto ${parent.ref}; it lands after it` : ''}`);
|
|
16827
16887
|
if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
|
|
16828
16888
|
print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
|
|
@@ -16918,7 +16978,7 @@ function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opt
|
|
|
16918
16978
|
}
|
|
16919
16979
|
print(' pushed.');
|
|
16920
16980
|
deferredCollector = [];
|
|
16921
|
-
if (!git.git(
|
|
16981
|
+
if (!git.git(shipBatch.batchDeleteArgs({ remote, ref: existing.ref, expect: existing.sha }), repoAbs).ok) warnDeferred(`could not delete ${remote}/${existing.ref} — delete it by hand (it has landed)`);
|
|
16922
16982
|
|
|
16923
16983
|
// The post-ship hook runs ONCE, over the whole batch — it is a trunk-checkout event, not a member one.
|
|
16924
16984
|
const changed = git.git(['diff', '--name-only', `${base}..${head}`], repoAbs);
|
package/tools/lib/ci-forgejo.js
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
* #681 adds the release half: `colab release cut` / `release finalize` (human bar) / `promote` read CI
|
|
8
8
|
* here and publish the release object here. So this module implements `tracker.FORGE_METHODS`:
|
|
9
9
|
* ciVerdict — the CI verdict at a commit (below);
|
|
10
|
+
* runsAtRef — the rows at a batch head (#742): the same status read, ignoring the ref;
|
|
10
11
|
* issueListAll — a READ of every issue (switch markers, the release hold, an existing tracking
|
|
11
12
|
* record), in the GitHub adapter's shape; nothing here writes an issue;
|
|
12
13
|
* releaseView / releaseCreate — the release object for a tag (`/releases`).
|
|
@@ -199,6 +200,16 @@ function create(repoAbs, eng) {
|
|
|
199
200
|
return ng.length ? { ...summary, notGreen: ng } : summary;
|
|
200
201
|
},
|
|
201
202
|
|
|
203
|
+
/**
|
|
204
|
+
* #742, tracker contract: the runs on batch `ref` at `sha`. A commit status belongs to the commit,
|
|
205
|
+
* so the ref is accepted and ignored (a batch head is a commit no other ref carries). No `attempt`:
|
|
206
|
+
* a re-run replaces the context's newest status, and nothing counts how often — the batch reads 1.
|
|
207
|
+
*/
|
|
208
|
+
runsAtRef: (ref, sha) => {
|
|
209
|
+
const full = fullOf(sha);
|
|
210
|
+
return full ? rowsAt(full) : null;
|
|
211
|
+
},
|
|
212
|
+
|
|
202
213
|
/** #681, not contract: the status rows at `sha` (statusRow's shape), or null when the read failed. */
|
|
203
214
|
ciRunsAt: (sha) => {
|
|
204
215
|
const full = fullOf(sha);
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -213,6 +213,42 @@ function batchRefName(baseSha) {
|
|
|
213
213
|
return `${REF_PREFIX}${String(baseSha || '').slice(0, 7)}`;
|
|
214
214
|
}
|
|
215
215
|
|
|
216
|
+
/**
|
|
217
|
+
* #742: every write to a batch ref is LEASED on the value the caller read. The ref is the turn: two
|
|
218
|
+
* landers at one base used to push it with `--force`, the second silently replacing the first, and
|
|
219
|
+
* both then believed they held the turn. Now
|
|
220
|
+
* - a build pushes create-only (`expect` empty: the ref must not exist on the remote);
|
|
221
|
+
* - a split replaces its own ref only while the remote still holds the head it read (`expect` sha);
|
|
222
|
+
* - a delete removes only the head it read, so a ref another lander rebuilt in between survives.
|
|
223
|
+
* git checks the lease against the advertised value and the remote re-checks the old value on update,
|
|
224
|
+
* so of two concurrent pushes exactly one wins. A refusal is classified by re-reading the remote,
|
|
225
|
+
* never by git's wording (a racer seen late is `remote rejected`, not `stale info`).
|
|
226
|
+
*/
|
|
227
|
+
const bareRef = (ref) => String(ref || '').replace(/^refs\/heads\//, '');
|
|
228
|
+
const leaseArg = (ref, expect) => `--force-with-lease=refs/heads/${bareRef(ref)}:${expect || ''}`;
|
|
229
|
+
|
|
230
|
+
/** `git push` argv putting `head` on batch `ref`, leased on `expect` ('' or null = create-only). Pure. */
|
|
231
|
+
function batchPushArgs({ remote, head, ref, expect = null }) {
|
|
232
|
+
return ['push', leaseArg(ref, expect), remote, `${head}:refs/heads/${bareRef(ref)}`];
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** `git push` argv deleting batch `ref` only while it still points at `expect` (a sha). Pure. */
|
|
236
|
+
function batchDeleteArgs({ remote, ref, expect }) {
|
|
237
|
+
if (!expect) throw new Error('batchDeleteArgs: a delete is leased on the sha that was read — none given');
|
|
238
|
+
return ['push', leaseArg(ref, expect), remote, '--delete', bareRef(ref)];
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/**
|
|
242
|
+
* #742: a leased push of batch `ref` was refused. Did another lander take the turn? `remoteSha` is the
|
|
243
|
+
* ref on the remote re-read after the refusal ('' when absent), `head` what we pushed.
|
|
244
|
+
* 'turn-lost' the ref now holds someone else's head — wait for it (exit 3), never an error;
|
|
245
|
+
* 'refused' anything else (no access, a hook, a network failure) — today's refusal.
|
|
246
|
+
*/
|
|
247
|
+
function pushRefusal({ remoteSha, head }) {
|
|
248
|
+
const r = String(remoteSha || '').trim();
|
|
249
|
+
return r && r !== String(head || '').trim() ? 'turn-lost' : 'refused';
|
|
250
|
+
}
|
|
251
|
+
|
|
216
252
|
/** `ship-batch/<hex7>` (with or without `refs/heads/`) → `{ ref, base7 }`, else null. */
|
|
217
253
|
function parseBatchRef(ref) {
|
|
218
254
|
const m = /^(?:refs\/heads\/)?(ship-batch\/([0-9a-f]{7}))$/.exec(String(ref || ''));
|
|
@@ -516,10 +552,25 @@ function nextStep({ enabled, wired, trunkCi, eligibleCount = 0, existing = null,
|
|
|
516
552
|
* time could not be read. That last one deliberately differs from laneHold, which releases
|
|
517
553
|
* it: deleting another caller's green run is not undoable, so the batch door clears only a
|
|
518
554
|
* provably abandoned ref (#391's pinned case, kept on purpose — recorded on #659).
|
|
519
|
-
*
|
|
555
|
+
* #742: a batch whose combined run NEVER STARTED (no run at its head) is in flight only for the same
|
|
556
|
+
* grace, counted from when it was built: a workflow that should have fired and did not (a runner
|
|
557
|
+
* outage, a disabled workflow, a lander that died between push and run) would otherwise pause every
|
|
558
|
+
* batch at this base until trunk moved — laneHold already releases it on the serial doors.
|
|
559
|
+
* clear no run, built ≥ graceSec ago → `reason: 'never-started'`
|
|
560
|
+
* wait no run inside the grace, or no run and a build time that could not be read (as for green:
|
|
561
|
+
* only a provably abandoned ref is deleted).
|
|
562
|
+
* `settledAtMs` is settledAt() of the ref's runs; `builtAtMs` the batch head's commit time (the build
|
|
563
|
+
* commits it); `nowMs` the clock.
|
|
520
564
|
*/
|
|
521
|
-
function foreignBatchStep(verdict, { settledAtMs = null, nowMs = null, graceSec = LANE_GRACE_SEC } = {}) {
|
|
565
|
+
function foreignBatchStep(verdict, { settledAtMs = null, builtAtMs = null, nowMs = null, graceSec = LANE_GRACE_SEC } = {}) {
|
|
522
566
|
if (verdict && verdict.state === 'red') return { step: 'clear', reason: 'red', why: verdict.why };
|
|
567
|
+
if (verdict && verdict.state === 'none' && Number.isFinite(builtAtMs) && Number.isFinite(nowMs)) {
|
|
568
|
+
const mins = Math.max(0, Math.round((nowMs - builtAtMs) / 60000));
|
|
569
|
+
if ((nowMs - builtAtMs) >= graceSec * 1000) {
|
|
570
|
+
return { step: 'clear', reason: 'never-started', why: `no combined run ${mins}m after it was built (grace ${graceSec}s) — treated as abandoned` };
|
|
571
|
+
}
|
|
572
|
+
return { step: 'wait', why: `built ${mins}m ago, its combined run has not appeared yet; past ${Math.round(graceSec / 60)}m with no run it is cleared` };
|
|
573
|
+
}
|
|
523
574
|
if (verdict && verdict.state === 'green' && Number.isFinite(settledAtMs) && Number.isFinite(nowMs)) {
|
|
524
575
|
const mins = Math.max(0, Math.round((nowMs - settledAtMs) / 60000));
|
|
525
576
|
if ((nowMs - settledAtMs) >= graceSec * 1000) {
|
|
@@ -767,6 +818,7 @@ module.exports = {
|
|
|
767
818
|
parseShipBatch, parseShipBatchWait, parseShipBatchSteps, sizeTrailer, parseSizeTrailer, adaptiveSize, splitHalves, partnerWait, readySince, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
|
|
768
819
|
droppedTrailer, parseDroppedTrailers, appendTrailers,
|
|
769
820
|
branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep, givenUpRefs,
|
|
821
|
+
batchPushArgs, batchDeleteArgs, pushRefusal,
|
|
770
822
|
batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
|
|
771
823
|
LANE_GRACE_SEC, laneHold, settledAt, MAX_CHAIN_DEPTH, batchChains, chainedLandStep,
|
|
772
824
|
};
|
|
@@ -184,6 +184,12 @@ function create(repoAbs, given = {}) {
|
|
|
184
184
|
return require('./git').summarizeRunsForCommit(clone(runs.filter((r) => r.headSha === sha && (!branch || r.headBranch === branch))), sha);
|
|
185
185
|
},
|
|
186
186
|
|
|
187
|
+
// #742: the seeded runs on `ref` at `sha`, with attempt (default 1) — the GitHub adapter's row shape.
|
|
188
|
+
runsAtRef: (ref, sha) => {
|
|
189
|
+
if (offline || !sha) return null;
|
|
190
|
+
return clone(runs.filter((r) => r.headBranch === ref && r.headSha === sha)).map((r) => ({ attempt: 1, ...r }));
|
|
191
|
+
},
|
|
192
|
+
|
|
187
193
|
releaseView: (tag) => {
|
|
188
194
|
if (offline) return result(false);
|
|
189
195
|
return releases.has(tag) ? result(true, { stdout: JSON.stringify({ tagName: tag }) }) : fail('release not found');
|
|
@@ -161,6 +161,10 @@ function create(repoAbs) {
|
|
|
161
161
|
return branch ? git().ghRunForCommit(repoAbs, branch, sha, undefined, opts) : git().ghRunForCommitAnyRef(repoAbs, sha, undefined, opts);
|
|
162
162
|
},
|
|
163
163
|
|
|
164
|
+
// #742: every run on batch `ref` at `sha`, with attempt and updatedAt — the read ship --batch made
|
|
165
|
+
// before the contract had it (ghRunsForRef, same argv).
|
|
166
|
+
runsAtRef: (ref, sha) => git().ghRunsForRef(repoAbs, ref, sha),
|
|
167
|
+
|
|
164
168
|
// --- releases ----------------------------------------------------------------------------
|
|
165
169
|
releaseView: (tag) => exec(['release', 'view', tag, '--json', 'tagName'], at),
|
|
166
170
|
releaseCreate: (tag, { notesFile, final = false }) => {
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"labels": "the label names defined on the repo, in the order labelList returns them.",
|
|
18
18
|
"issues": "[{number, title, body, state: OPEN|CLOSED, stateReason, labels: [name], assignees: [login], comments: [{author, body}], events: [{event: \"labeled\", label, actor}]}] — `events` is the label timeline claimHolder reads; the claimer is the actor of the LATEST labeled in-progress event.",
|
|
19
19
|
"prs": "[{number, head, base, title, body, state: OPEN|CLOSED|MERGED, author}] — issues and pull requests share ONE number sequence, as on GitHub.",
|
|
20
|
-
"runs": "[{headBranch, headSha, status, conclusion, event, workflowName, createdAt, databaseId}] — CI runs; runList returns them newest first by createdAt; ciVerdict (#678) summarizes the ones at one sha.",
|
|
20
|
+
"runs": "[{headBranch, headSha, status, conclusion, event, workflowName, createdAt, databaseId}] — CI runs; runList returns them newest first by createdAt; ciVerdict (#678) summarizes the ones at one sha; runsAtRef (#742) returns the ones on one ref at one sha as rows, with `attempt` and `updatedAt` when seeded.",
|
|
21
21
|
"releases": "[{tag, prerelease}]"
|
|
22
22
|
},
|
|
23
23
|
"scenarios": [
|
|
@@ -255,6 +255,32 @@
|
|
|
255
255
|
"steps": [
|
|
256
256
|
{ "call": "ciVerdict", "args": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", { "branch": "main" }], "expect": null }
|
|
257
257
|
]
|
|
258
|
+
},
|
|
259
|
+
{
|
|
260
|
+
"id": "runs-at-ref",
|
|
261
|
+
"description": "runsAtRef returns every CI run on one ref at one sha as rows (#742) — the facts ship --batch judges its combined run from, including when a finished run settled (updatedAt). A sha with no run on the ref is an empty list, never null.",
|
|
262
|
+
"given": {
|
|
263
|
+
"login": "alice",
|
|
264
|
+
"runs": [
|
|
265
|
+
{"headBranch": "ship-batch/1111111", "headSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "completed", "conclusion": "success", "event": "push", "workflowName": "CI", "createdAt": "2026-11-01T10:00:00Z", "updatedAt": "2026-11-01T10:05:00Z", "databaseId": 201, "attempt": 1},
|
|
266
|
+
{"headBranch": "ship-batch/1111111", "headSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "status": "completed", "conclusion": "failure", "event": "push", "workflowName": "CI", "createdAt": "2026-11-01T11:00:00Z", "updatedAt": "2026-11-01T11:04:00Z", "databaseId": 202, "attempt": 1}
|
|
267
|
+
]
|
|
268
|
+
},
|
|
269
|
+
"steps": [
|
|
270
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
|
|
271
|
+
"expect": [{"headSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "completed", "conclusion": "success", "updatedAt": "2026-11-01T10:05:00Z"}] },
|
|
272
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
|
|
273
|
+
"expect": [{"headSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "status": "completed", "conclusion": "failure"}] },
|
|
274
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "cccccccccccccccccccccccccccccccccccccccc"], "expect": [] }
|
|
275
|
+
]
|
|
276
|
+
},
|
|
277
|
+
{
|
|
278
|
+
"id": "runs-at-ref-unreadable",
|
|
279
|
+
"description": "A run read that cannot reach the tracker returns null — could not read, never an empty list a batch would take for a run that never started.",
|
|
280
|
+
"given": { "login": "alice", "offline": true },
|
|
281
|
+
"steps": [
|
|
282
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"], "expect": null }
|
|
283
|
+
]
|
|
258
284
|
}
|
|
259
285
|
]
|
|
260
286
|
}
|
package/tools/lib/tracker.js
CHANGED
|
@@ -24,6 +24,12 @@
|
|
|
24
24
|
* tools/lib/ci-forgejo.js, Forgejo commit statuses and `/releases`. `CI_METHODS` stays the subset
|
|
25
25
|
* the landing path (#678) needs. Which engine a repo gets is `engineFor` below.
|
|
26
26
|
*
|
|
27
|
+
* Batch turn (#742): `runsAtRef(ref, sha)` — every CI run on one ref at one sha, as rows
|
|
28
|
+
* `{ headSha, status, conclusion, createdAt, updatedAt, databaseId, workflowName, attempt? }`, or null
|
|
29
|
+
* when the read failed ([] is "no run yet"). `colab ship --batch` judges its combined run from these
|
|
30
|
+
* (the attempt caps the one re-run; updatedAt dates a green settle). A forge whose CI is a commit
|
|
31
|
+
* status reads the commit and ignores the ref, and may omit `attempt` (read as 1).
|
|
32
|
+
*
|
|
27
33
|
* Deliberately NOT in the contract yet (#501 left it so: no scenario needs them, and each would
|
|
28
34
|
* pin a GitHub-only shape into a spec other trackers must satisfy): the raw CI-run lists and REST
|
|
29
35
|
* probes behind `ciVerdict`, label create/delete/edit, raw `issue edit` flags and raw `api`
|
|
@@ -48,6 +54,7 @@ const METHODS = Object.freeze([
|
|
|
48
54
|
{ name: 'prEdit', kind: 'write', returns: 'result' },
|
|
49
55
|
{ name: 'runList', kind: 'read', returns: 'result + data: run[] | null' },
|
|
50
56
|
{ name: 'ciVerdict', kind: 'read', returns: 'run summary | null' },
|
|
57
|
+
{ name: 'runsAtRef', kind: 'read', returns: 'run[] | null' },
|
|
51
58
|
{ name: 'releaseView', kind: 'read', returns: 'result' },
|
|
52
59
|
{ name: 'releaseCreate', kind: 'write', returns: 'result' },
|
|
53
60
|
].map(Object.freeze));
|
|
@@ -56,11 +63,12 @@ const METHODS = Object.freeze([
|
|
|
56
63
|
const CI_METHODS = Object.freeze(['ciVerdict']);
|
|
57
64
|
|
|
58
65
|
/**
|
|
59
|
-
* The methods a forge engine implements (#681): landing (`CI_METHODS`)
|
|
66
|
+
* The methods a forge engine implements (#681): landing (`CI_METHODS`), the batch turn's run read
|
|
67
|
+
* (#742, `runsAtRef`), plus what a release needs —
|
|
60
68
|
* the issue list READ (switch markers, the release hold, an existing tracking record) and the release
|
|
61
69
|
* object. No issue write is here on purpose: #678's ruling keeps the forge's tracker the adopter's.
|
|
62
70
|
*/
|
|
63
|
-
const FORGE_METHODS = Object.freeze([...CI_METHODS, 'issueListAll', 'releaseView', 'releaseCreate']);
|
|
71
|
+
const FORGE_METHODS = Object.freeze([...CI_METHODS, 'runsAtRef', 'issueListAll', 'releaseView', 'releaseCreate']);
|
|
64
72
|
|
|
65
73
|
/**
|
|
66
74
|
* Throw, naming every contract method `impl` lacks. Returns `impl` when it is complete.
|