@futurelastic/colab-handbook 1.22.0-rc.2 → 1.22.0-rc.4
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 +118 -54
- package/tools/lib/ci-forgejo.js +64 -1
- package/tools/lib/ship-batch.js +54 -2
- package/tools/lib/ship-handoff.js +57 -18
- package/tools/lib/tracker-fake.js +26 -4
- package/tools/lib/tracker-github.js +12 -0
- package/tools/lib/tracker-scenarios.json +44 -2
- package/tools/lib/tracker.js +21 -4
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -11403,8 +11403,8 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
|
|
|
11403
11403
|
return `CI-Cure: branch ${branch} over-red ${trunk}@${shortSha(cureVerdict.redSha)} evidence ${shortSha(cureVerdict.evidenceSha)}${via}${admittedSuffix}${progressSuffix}`;
|
|
11404
11404
|
}
|
|
11405
11405
|
|
|
11406
|
-
const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <
|
|
11407
|
-
colab ship --batch <b1,b2[@<handoff-
|
|
11406
|
+
const HELP_SHIP = `colab ship [--repo <path>] [--worktree <name> | --branch <br> | --direct] [--message "<msg>"] [--refs <N[,M]>] [--keep-worktree] [--delete-branch | --keep-branch] [--adopt | --handoff <ref>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
|
|
11407
|
+
colab ship --batch <b1,b2[@<handoff-ref>][,…]> [--split] [--onto ship-batch/<sha7>] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry [--json]]
|
|
11408
11408
|
|
|
11409
11409
|
The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
|
|
11410
11410
|
CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
|
|
@@ -11516,19 +11516,23 @@ here, or pass --adopt if it genuinely has no issue — the squash then carries a
|
|
|
11516
11516
|
still a legitimate zero. --adopt never bypasses a branch that names issues.
|
|
11517
11517
|
|
|
11518
11518
|
A HAND-OFF (#578) is the non-force door for a branch whose claim lives on ANOTHER machine:
|
|
11519
|
-
\`colab ship --branch <br> --handoff <
|
|
11520
|
-
|
|
11519
|
+
\`colab ship --branch <br> --handoff <ref>\`, where <ref> names the executor's hand-off comment
|
|
11520
|
+
forge-neutrally — \`<forge-host>/<owner>/<repo>#<N>@comment:<id>\` (#740) — or by its URL
|
|
11521
|
+
(…/issues/<N>#issuecomment-<id>, kept as an alias). Either is resolved through the repo's tracker
|
|
11522
|
+
adapter: the GitHub tracker, or on a Forgejo remote the forge engine (reads only — colab writes no
|
|
11523
|
+
claim comment there, #678, so the claim below must come from the adopter's tracker layer). With zero claims here, ship takes the issue set from the branch
|
|
11521
11524
|
name's trailing run once the hand-off proves all of: the comment is on one of THIS repo's issues,
|
|
11522
11525
|
one the branch carries; it names the branch and a sha that is the remote branch's CURRENT head (a
|
|
11523
11526
|
branch that moved after its hand-off needs a new one — except by base-sync merges, #579, below); and every issue the branch carries has a
|
|
11524
11527
|
live \`🔒 Claimed\` comment on that branch, posted by the hand-off's author before it. Nothing is
|
|
11525
11528
|
claimed or taken over here: the executor keeps its claim, worktree and branch until it confirms
|
|
11526
|
-
the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <
|
|
11529
|
+
the land, the shipped branch is kept, the squash carries \`Colab-Handoff: <ref> @ <sha>\` (always the
|
|
11530
|
+
neutral form, whichever one was given), and each
|
|
11527
11531
|
🚢 comment names the hand-off. Any check failing refuses (exit 1); --force is never involved, and
|
|
11528
11532
|
the human takeover (\`colab claim --force\`) stays the only other way in. Not with --adopt
|
|
11529
11533
|
or --direct, and not when this machine already holds a claim on the branch.
|
|
11530
11534
|
|
|
11531
|
-
IN A BATCH (#591) the hand-off rides its member: \`--batch b1,b2@<
|
|
11535
|
+
IN A BATCH (#591) the hand-off rides its member: \`--batch b1,b2@<ref>\` (split on the first @).
|
|
11532
11536
|
That member is verified by this SAME door — same checks, same refusal text, which drops it from
|
|
11533
11537
|
the batch while the rest build — then joins the combined run with no sync of its own; its squash
|
|
11534
11538
|
carries the Colab-Handoff trailer, and the land reads the door back from that commit. Repeat the
|
|
@@ -11540,7 +11544,7 @@ the base in, push) — and the hand-off still verifies, because the commits betw
|
|
|
11540
11544
|
sha and the new head are each a PURE base-sync merge: two parents, the second already on the base,
|
|
11541
11545
|
and a tree equal to git's own conflict-free merge of the two. A fix-up, a rebase, or a merge whose
|
|
11542
11546
|
conflict was resolved by hand is not one, and still needs a new hand-off from the executor. The
|
|
11543
|
-
trailer then reads \`Colab-Handoff: <
|
|
11547
|
+
trailer then reads \`Colab-Handoff: <ref> @ <handed-off sha> (synced to <head> by N base merge(s))\`.
|
|
11544
11548
|
|
|
11545
11549
|
UNATTACHED CLAIMS (#319). A claim taken with no --worktree and no --branch (\`colab claim <N>
|
|
11546
11550
|
--session <id>\`) is carried by a branch ship only when BOTH hold: its session equals this ship's
|
|
@@ -11720,7 +11724,13 @@ is pending, or green within ${shipBatch.LANE_GRACE_SEC / 60}m of settling (the s
|
|
|
11720
11724
|
combined run red — is deleted and the batch you asked for is built in its place, so the survivors of a
|
|
11721
11725
|
decline can batch without landing serially first (#391). A green one still unlanded past that grace lost
|
|
11722
11726
|
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).
|
|
11727
|
+
still waited on — only a provably abandoned batch is deleted (#659). One whose combined run never
|
|
11728
|
+
started — no run ${shipBatch.LANE_GRACE_SEC / 60}m after it was built — is abandoned too; an unreadable build time waits (#742).
|
|
11729
|
+
The ref is the turn (#742): a build pushes it create-only, a split replaces it and a delete removes it
|
|
11730
|
+
only while it still holds the head this call read (--force-with-lease). Of two landers at one base
|
|
11731
|
+
exactly one push lands; the other prints "another lander took the turn" and exits 3 — run it again,
|
|
11732
|
+
it waits on the winner. The combined run is read through the forge engine (GitHub runs; on a Forgejo
|
|
11733
|
+
remote the commit statuses, where a re-run is not counted, so a red batch asks to be classified again).
|
|
11724
11734
|
A call that goes serial on trunk CI not green gives up on its members, so it deletes every batch at
|
|
11725
11735
|
trunk's tip whose members it ALL names (its run cancelled if still going) — nobody would ever land
|
|
11726
11736
|
it, and it would hold this base for every later call; a batch also carrying another member stays (#656).
|
|
@@ -13632,7 +13642,7 @@ function cmdShipDryJson(opts) {
|
|
|
13632
13642
|
// #591: the verified hand-off (or its refusal), so `ship --batch` puts this member's
|
|
13633
13643
|
// Colab-Handoff trailer on its squash and words a refusal exactly as the single door does.
|
|
13634
13644
|
...(handoff ? { handoff: handoff.ok
|
|
13635
|
-
? { ok: true, url: handoff.url, sha: handoff.sha, handedOff: handoff.handedOff, syncMerges: handoff.syncMerges || 0 }
|
|
13645
|
+
? { ok: true, url: handoff.url, ref: handoff.ref, sha: handoff.sha, handedOff: handoff.handedOff, syncMerges: handoff.syncMerges || 0 }
|
|
13636
13646
|
: { ok: false, reason: handoff.reason, detail: handoff.detail } } : {}),
|
|
13637
13647
|
};
|
|
13638
13648
|
// #373: `ship --batch` reads each member through this SAME function — handed the body, not stdout.
|
|
@@ -14729,7 +14739,7 @@ function autonomyGatePayload(gate) {
|
|
|
14729
14739
|
|
|
14730
14740
|
/** The sha a branch name resolves to, local first, else origin's copy (#324's remote-only shape). */
|
|
14731
14741
|
/**
|
|
14732
|
-
* #578 — `--handoff <comment
|
|
14742
|
+
* #578 — `--handoff <ref>` (#740: neutral reference or comment URL): verify the executor's recorded hand-off and, when it holds, take
|
|
14733
14743
|
* the session's issue set from it (tools/lib/ship-handoff.js says what it must prove). Returns null
|
|
14734
14744
|
* without --handoff, the failing verdict on a refusal, the passing one after mutating `sess`.
|
|
14735
14745
|
*
|
|
@@ -14743,17 +14753,12 @@ function applyShipHandoff(repoAbs, sess, opts, trunk) {
|
|
|
14743
14753
|
throw new UserError(`--handoff is the door for a branch with NO claim on this machine, and this machine holds ${sess.issues.map((n) => '#' + n).join(' ')} ` +
|
|
14744
14754
|
`for ${sess.branch} — ship it without --handoff`);
|
|
14745
14755
|
}
|
|
14746
|
-
|
|
14747
|
-
|
|
14748
|
-
|
|
14749
|
-
|
|
14750
|
-
|
|
14751
|
-
|
|
14752
|
-
const j = JSON.parse(r.stdout);
|
|
14753
|
-
comment = { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
|
|
14754
|
-
} catch (_) { comment = null; }
|
|
14755
|
-
}
|
|
14756
|
-
}
|
|
14756
|
+
// #740: a neutral reference (<forge-host>/<owner>/<repo>#<N>@comment:<id>) or the comment's URL, both
|
|
14757
|
+
// resolved through the repo's tracker adapter — the Forgejo forge engine on a forge remote (#678), the
|
|
14758
|
+
// GitHub tracker otherwise — so no read below reaches for one forge's API by hand.
|
|
14759
|
+
const u = shipHandoff.parseHandoffRef(opts.handoff);
|
|
14760
|
+
const reader = forgeCi(repoAbs) || tracker.forRepo(repoAbs);
|
|
14761
|
+
const comment = u ? reader.commentView(u.commentId) : null;
|
|
14757
14762
|
// The head check must read the remote as it is NOW, not a tracking ref from whenever this clone last fetched.
|
|
14758
14763
|
const remote = git.remoteFor(repoAbs);
|
|
14759
14764
|
if (u && comment) git.git(['fetch', '--quiet', remote, `+refs/heads/${sess.branch}:refs/remotes/${remote}/${sess.branch}`], repoAbs);
|
|
@@ -14769,13 +14774,18 @@ function applyShipHandoff(repoAbs, sess, opts, trunk) {
|
|
|
14769
14774
|
const issueStates = {}; // #647: an issue closed before the hand-off needs no claim — read state too
|
|
14770
14775
|
if (u && comment) {
|
|
14771
14776
|
for (const n of shipguard.branchIssueNumbers(sess.branch)) {
|
|
14772
|
-
const info =
|
|
14777
|
+
const info = reader.issueView(n, ['comments', 'state', 'closedAt']);
|
|
14773
14778
|
claimsByIssue[n] = info ? liveClaimComments(info.comments || []).map((c) => ({ ...c })) : null;
|
|
14774
14779
|
if (info) issueStates[n] = { state: info.state || '', closedAt: info.closedAt || '' };
|
|
14775
14780
|
}
|
|
14776
14781
|
}
|
|
14777
14782
|
const v = shipHandoff.handoffVerdict({ url: opts.handoff, comment, branch: sess.branch, refs, claimsByIssue, syncChain,
|
|
14778
14783
|
issueStates, refNumbers: refsFlagNumbers(opts.refs) });
|
|
14784
|
+
if (!v.ok && v.reason === 'no-executor-claim' && reader.kind === 'forgejo') {
|
|
14785
|
+
// #740: reads only on a forge (#678) — colab posts no 🔒 claim comment there, so the claim this door
|
|
14786
|
+
// checks exists only where the adopter's own tracker layer writes one in colab's claim format.
|
|
14787
|
+
return { ...v, detail: `${v.detail}. On a ${reader.kind} remote colab writes no claim comment (#678): a hand-off verifies there only where the adopter's tracker layer posts the executor's 🔒 claim in colab's format` };
|
|
14788
|
+
}
|
|
14779
14789
|
if (!v.ok) return v;
|
|
14780
14790
|
sess.issues = v.issues;
|
|
14781
14791
|
sess.handoff = v;
|
|
@@ -14864,7 +14874,7 @@ function cmdShip(argv) {
|
|
|
14864
14874
|
if (shippedBranch.conflictingFlags(opts)) throw new UserError('--delete-branch and --keep-branch contradict each other — pass one (see `colab ship --help`, #368)');
|
|
14865
14875
|
// #578: a hand-off names ONE branch; trunk-direct has no branch for it to name. #591: in a batch the
|
|
14866
14876
|
// hand-off rides its member (`--batch b1,b2@<url>`), so a bare --handoff beside --batch names no one.
|
|
14867
|
-
if (opts.handoff && opts.batch) throw new UserError('--handoff names one --branch ship; in a batch, attach it to its member: --batch <b1>,<b2>@<hand-off-
|
|
14877
|
+
if (opts.handoff && opts.batch) throw new UserError('--handoff names one --branch ship; in a batch, attach it to its member: --batch <b1>,<b2>@<hand-off-ref> (#591, see `colab ship --help`)');
|
|
14868
14878
|
if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
|
|
14869
14879
|
if (opts.split && !opts.batch) throw new UserError('--split applies to a red combined run of --batch only (#557) — run `colab ship --batch <b1,b2,…> --split` with the members the red batch carries');
|
|
14870
14880
|
if (opts.onto && !opts.batch) throw new UserError('--onto applies to --batch only (#605) — run `colab ship --batch <b1,b2,…> --onto ship-batch/<sha7>`');
|
|
@@ -16141,6 +16151,15 @@ function workflowsFiringAt(repoAbs, treeish, branch) {
|
|
|
16141
16151
|
return workflowTriggers.workflowsFiringOnBranchPush({ readFile, workflows, branch });
|
|
16142
16152
|
}
|
|
16143
16153
|
|
|
16154
|
+
/**
|
|
16155
|
+
* #742: every run on batch `ref` at `sha`, WITH its attempt and updatedAt — read through the forge
|
|
16156
|
+
* contract's `runsAtRef` (GitHub: `gh run list --branch`; Forgejo: the commit's statuses), so the batch
|
|
16157
|
+
* turn reads the same facts on every engine. null = could not read, never "no runs".
|
|
16158
|
+
*/
|
|
16159
|
+
function batchRunsAt(repoAbs, ref, sha) {
|
|
16160
|
+
return (forgeCi(repoAbs) || tracker.forRepo(repoAbs)).runsAtRef(ref, sha);
|
|
16161
|
+
}
|
|
16162
|
+
|
|
16144
16163
|
/**
|
|
16145
16164
|
* #373: may a green run on a `ship-batch/**` ref stand in for trunk's OWN run at the same sha? Only
|
|
16146
16165
|
* on a repo that declared `ship-batch` > 1, only for a head commit a batch landed (its Ship-Batch:
|
|
@@ -16153,8 +16172,9 @@ function shipBatchTrunkSubstitute(repoAbs, trunk, sha) {
|
|
|
16153
16172
|
if (!msg.ok) return null;
|
|
16154
16173
|
const tr = shipBatch.parseMemberTrailers([msg.stdout])[0];
|
|
16155
16174
|
if (!tr || !shipBatch.parseBatchRef(tr.ref)) return null;
|
|
16156
|
-
const
|
|
16157
|
-
const
|
|
16175
|
+
const fc = forgeCi(repoAbs);
|
|
16176
|
+
const trunkRows = fc ? fc.ciRunsAt(sha) : git.ghRunsForCommit(repoAbs, trunk, sha, 20);
|
|
16177
|
+
const batchRows = batchRunsAt(repoAbs, tr.ref, sha);
|
|
16158
16178
|
if (trunkRows === null || batchRows === null) return null;
|
|
16159
16179
|
const covers = shipBatch.batchGreenCoversTrunk({
|
|
16160
16180
|
trunkRows, batchRows,
|
|
@@ -16181,10 +16201,11 @@ function shipDryJsonReport(opts) {
|
|
|
16181
16201
|
* lib/ship-batch.js laneHold; this only reads the remote.
|
|
16182
16202
|
*
|
|
16183
16203
|
* Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
|
|
16184
|
-
* trunk, and gh is usable
|
|
16204
|
+
* trunk, and gh is usable — or the remote is a forge the engine map names (#742: its runs are read
|
|
16205
|
+
* through the engine). Out: null, or `{ held, ref, why, released, detail }`.
|
|
16185
16206
|
*/
|
|
16186
16207
|
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
|
|
16187
|
-
if (target !== trunk ||
|
|
16208
|
+
if (target !== trunk || shipBatch.parseShipBatch(doc).n <= 1 || (!gh && !forgeCi(repoAbs))) return null;
|
|
16188
16209
|
// #605: a TRUNK RED: cure is never held by a batch (or a chain) — trunk is red, and the cure is the
|
|
16189
16210
|
// way out; no batch can land on a red trunk anyway.
|
|
16190
16211
|
if (ciResult && ciResult.cureVerdict && ciResult.cureVerdict.ok) {
|
|
@@ -16201,7 +16222,7 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
|
|
|
16201
16222
|
const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
|
|
16202
16223
|
const atTip = refs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
16203
16224
|
const batches = atTip.map((x) => {
|
|
16204
|
-
const runs =
|
|
16225
|
+
const runs = batchRunsAt(repoAbs, x.parsed.ref, x.sha);
|
|
16205
16226
|
let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
|
|
16206
16227
|
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
16228
|
const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
|
|
@@ -16314,7 +16335,7 @@ function cmdShipBatch(opts) {
|
|
|
16314
16335
|
const batchRead = { verifying: verifyRuns.parsePolicy(doc) };
|
|
16315
16336
|
const trunk = resolveTrunk(repoAbs, doc);
|
|
16316
16337
|
if (!trunk) throw new UserError('Could not determine trunk branch (set project.yml trunk:)');
|
|
16317
|
-
// #591: a member built on another machine names its hand-off inline — `<branch>@<hand-off-
|
|
16338
|
+
// #591: a member built on another machine names its hand-off inline — `<branch>@<hand-off-ref>` (#740).
|
|
16318
16339
|
const entries = shipHandoff.parseBatchEntries(opts.batch === true ? '' : opts.batch);
|
|
16319
16340
|
if (entries.errors.length) throw new UserError(`--batch: ${entries.errors.join('; ')}`);
|
|
16320
16341
|
const members = entries.members;
|
|
@@ -16369,18 +16390,45 @@ function cmdShipBatch(opts) {
|
|
|
16369
16390
|
}
|
|
16370
16391
|
|
|
16371
16392
|
const gh = isGhUsable(repoAbs);
|
|
16372
|
-
|
|
16393
|
+
// #742: on a forge the engine map names, the combined run is read through its engine (runsAtRef).
|
|
16394
|
+
const fc = forgeCi(repoAbs);
|
|
16395
|
+
if (!gh && !fc) throw new UserError(`gh not usable (${ghUnusableWhy(repoAbs)}) — a batch cannot read its combined run`);
|
|
16373
16396
|
|
|
16374
16397
|
// #415: every write on the resume path goes through here or shipBatchLand — under --dry, neither writes.
|
|
16375
|
-
|
|
16398
|
+
// #742: every delete is leased on the head this call read (`sha`), so a ref another lander rebuilt in
|
|
16399
|
+
// between is never deleted from under it.
|
|
16400
|
+
const remoteRefSha = (ref) => {
|
|
16401
|
+
const r = git.git(['ls-remote', remote, `refs/heads/${ref}`], repoAbs);
|
|
16402
|
+
return r.ok ? (r.stdout.split('\t')[0] || '').trim() : null;
|
|
16403
|
+
};
|
|
16404
|
+
const deleteRef = (ref, sha) => {
|
|
16376
16405
|
if (opts.dry) { print(` [dry] would delete ${remote}/${ref}`); return true; }
|
|
16377
|
-
const d = git.git(
|
|
16378
|
-
if (!d.ok)
|
|
16406
|
+
const d = git.git(shipBatch.batchDeleteArgs({ remote, ref, expect: sha }), repoAbs);
|
|
16407
|
+
if (!d.ok) {
|
|
16408
|
+
const now = remoteRefSha(ref);
|
|
16409
|
+
warn(now !== null && now !== sha
|
|
16410
|
+
? `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)`
|
|
16411
|
+
: `could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
|
|
16412
|
+
}
|
|
16379
16413
|
return d.ok;
|
|
16380
16414
|
};
|
|
16415
|
+
// #742: a delete the next step depends on (the ref's base is then free for this call's build).
|
|
16416
|
+
// 'deleted' · 'moved' — another lander rewrote or removed it since it was read: the turn is not ours
|
|
16417
|
+
// to take on this call · 'failed' — any other refusal.
|
|
16418
|
+
const clearRef = (ref, sha) => {
|
|
16419
|
+
if (deleteRef(ref, sha)) return 'deleted';
|
|
16420
|
+
const now = remoteRefSha(ref);
|
|
16421
|
+
return now !== null && now !== sha ? 'moved' : 'failed';
|
|
16422
|
+
};
|
|
16423
|
+
const turnMoved = (ref) => {
|
|
16424
|
+
J.step = 'turn-lost';
|
|
16425
|
+
print(`⏸ ship-batch: ${ref} changed on ${remote} since this call read it — another lander took the turn at this base (#742). Nothing landed.`);
|
|
16426
|
+
print(' Run this command again: it reads the batch now there and waits on it, or builds once it lands or is declined.');
|
|
16427
|
+
return 3;
|
|
16428
|
+
};
|
|
16381
16429
|
// A ref nothing can land any more may still have its run going: cancel it rather than let it finish.
|
|
16382
16430
|
const cancelRuns = (ref, sha) => {
|
|
16383
|
-
for (const r of (
|
|
16431
|
+
for (const r of (batchRunsAt(repoAbs, ref, sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
|
|
16384
16432
|
if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${ref}`); continue; }
|
|
16385
16433
|
const cx = git.ghRunCancel(repoAbs, r.databaseId);
|
|
16386
16434
|
if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${ref} — it will finish on a ref that is gone`);
|
|
@@ -16417,7 +16465,7 @@ function cmdShipBatch(opts) {
|
|
|
16417
16465
|
const b = rooted.find((x) => x.ref === ref);
|
|
16418
16466
|
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
16467
|
cancelRuns(ref, b.sha);
|
|
16420
|
-
deleteRef(ref);
|
|
16468
|
+
deleteRef(ref, b.sha);
|
|
16421
16469
|
}
|
|
16422
16470
|
}
|
|
16423
16471
|
if (trunkCi === 'pending') {
|
|
@@ -16457,7 +16505,7 @@ function cmdShipBatch(opts) {
|
|
|
16457
16505
|
print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
|
|
16458
16506
|
}
|
|
16459
16507
|
swept.push({ ref: b.parsed.ref, members: offTrunk ? carriedBy(b.parsed.ref, trunkNow, b.sha) : [] });
|
|
16460
|
-
deleteRef(b.parsed.ref);
|
|
16508
|
+
deleteRef(b.parsed.ref, b.sha);
|
|
16461
16509
|
}
|
|
16462
16510
|
const rooted = batchRefs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
16463
16511
|
// Every member the chain up to `sha` carries (branch → the ref carrying it), read from its trailers.
|
|
@@ -16499,13 +16547,13 @@ function cmdShipBatch(opts) {
|
|
|
16499
16547
|
print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
|
|
16500
16548
|
} else {
|
|
16501
16549
|
const pc = chains.get(want);
|
|
16502
|
-
const verdict = shipBatch.combinedVerdict(
|
|
16550
|
+
const verdict = shipBatch.combinedVerdict(batchRunsAt(repoAbs, want, p.sha), batchRead);
|
|
16503
16551
|
const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
|
|
16504
16552
|
if (verdict.state === 'red') {
|
|
16505
16553
|
if (child) {
|
|
16506
16554
|
const carried = carriedBy(child.parsed.ref, p.sha, child.sha);
|
|
16507
16555
|
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);
|
|
16556
|
+
deleteRef(child.parsed.ref, child.sha);
|
|
16509
16557
|
J.step = 'chained-decline';
|
|
16510
16558
|
return serial(`its parent ${want} was declined — rebuild on ${trunk} once it is settled`, carried.length ? carried.map((m) => m.branch) : members);
|
|
16511
16559
|
}
|
|
@@ -16532,8 +16580,12 @@ function cmdShipBatch(opts) {
|
|
|
16532
16580
|
// #659: nor is a green one past the lane grace (laneHold's rule) — its lander is gone.
|
|
16533
16581
|
let foreignStep = null;
|
|
16534
16582
|
if (foreign.length) {
|
|
16535
|
-
const runs =
|
|
16536
|
-
|
|
16583
|
+
const runs = batchRunsAt(repoAbs, atBase.parsed.ref, atBase.sha);
|
|
16584
|
+
// #742: its build time ages a batch whose combined run never started (the build commits its head).
|
|
16585
|
+
const bt = git.git(['log', '-1', '--format=%cI', atBase.sha], repoAbs);
|
|
16586
|
+
const builtAtMs = bt.ok ? Date.parse(bt.stdout.trim()) : NaN;
|
|
16587
|
+
foreignStep = shipBatch.foreignBatchStep(shipBatch.combinedVerdict(runs, batchRead), {
|
|
16588
|
+
settledAtMs: shipBatch.settledAt(runs), builtAtMs: Number.isFinite(builtAtMs) ? builtAtMs : null, nowMs: Date.now() });
|
|
16537
16589
|
}
|
|
16538
16590
|
if (foreignStep && foreignStep.step === 'wait') {
|
|
16539
16591
|
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 +16594,13 @@ function cmdShipBatch(opts) {
|
|
|
16542
16594
|
}
|
|
16543
16595
|
if (foreignStep) {
|
|
16544
16596
|
const carried = inBatch.map((m) => m.branch).join(', ');
|
|
16545
|
-
print(
|
|
16546
|
-
|
|
16547
|
-
: ` ${atBase.parsed.ref} (${carried}) was
|
|
16548
|
-
|
|
16597
|
+
print({
|
|
16598
|
+
abandoned: ` ${atBase.parsed.ref} (${carried}) was abandoned — its ${foreignStep.why}; nothing landed from it. Deleting it and building the requested batch.`,
|
|
16599
|
+
'never-started': ` ${atBase.parsed.ref} (${carried}) was abandoned — ${foreignStep.why}; nothing landed from it. Deleting it and building the requested batch (#742).`,
|
|
16600
|
+
}[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.`);
|
|
16601
|
+
const cleared = opts.dry ? 'deleted' : clearRef(atBase.parsed.ref, atBase.sha);
|
|
16602
|
+
if (cleared === 'moved') return turnMoved(atBase.parsed.ref);
|
|
16603
|
+
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
16604
|
}
|
|
16550
16605
|
if (!foreignStep) {
|
|
16551
16606
|
const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
|
|
@@ -16562,7 +16617,7 @@ function cmdShipBatch(opts) {
|
|
|
16562
16617
|
}
|
|
16563
16618
|
}
|
|
16564
16619
|
}
|
|
16565
|
-
let verdict = existing && existing.matches ? shipBatch.combinedVerdict(
|
|
16620
|
+
let verdict = existing && existing.matches ? shipBatch.combinedVerdict(batchRunsAt(repoAbs, existing.ref, existing.sha), batchRead) : null;
|
|
16566
16621
|
// #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
|
|
16567
16622
|
// heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
|
|
16568
16623
|
// the same re-run / split path a light red does, and the split walks toward the culprit.
|
|
@@ -16586,7 +16641,9 @@ function cmdShipBatch(opts) {
|
|
|
16586
16641
|
|
|
16587
16642
|
if (step.step === 'rebuild') {
|
|
16588
16643
|
print(` ${existing.ref} no longer carries the requested members at their current heads — rebuilding`);
|
|
16589
|
-
|
|
16644
|
+
const cleared = clearRef(existing.ref, existing.sha);
|
|
16645
|
+
if (cleared === 'moved') return turnMoved(existing.ref);
|
|
16646
|
+
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
16647
|
existing = null;
|
|
16591
16648
|
step = { step: 'build' };
|
|
16592
16649
|
}
|
|
@@ -16625,7 +16682,7 @@ function cmdShipBatch(opts) {
|
|
|
16625
16682
|
}
|
|
16626
16683
|
if (step.step === 'red-serial') {
|
|
16627
16684
|
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);
|
|
16685
|
+
deleteRef(existing.ref, existing.sha);
|
|
16629
16686
|
print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
|
|
16630
16687
|
return 4;
|
|
16631
16688
|
}
|
|
@@ -16641,7 +16698,7 @@ function cmdShipBatch(opts) {
|
|
|
16641
16698
|
return 3;
|
|
16642
16699
|
}
|
|
16643
16700
|
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);
|
|
16701
|
+
deleteRef(existing.ref, existing.sha);
|
|
16645
16702
|
return serial('its parent batch was discarded', existing.members.map((m) => m.branch));
|
|
16646
16703
|
}
|
|
16647
16704
|
if (step.step === 'land') return shipBatchLand(repoAbs, doc, trunk, remote, trunkNow, existing, verdict, opts);
|
|
@@ -16664,7 +16721,7 @@ function cmdShipBatch(opts) {
|
|
|
16664
16721
|
...(handoffs[b] ? { handoff: handoffs[b] } : {}) });
|
|
16665
16722
|
report = rep.body;
|
|
16666
16723
|
files = branchChangedFiles(repoAbs, trunkRef, refs.remoteSha);
|
|
16667
|
-
ciClass = shipBatch.branchCiClass(git.ghRunForSha(repoAbs, b), workflowsFiringAt(repoAbs, refs.remoteSha, b).length > 0);
|
|
16724
|
+
ciClass = shipBatch.branchCiClass(fc ? fc.ciVerdict(refs.remoteSha, { branch: b }) : git.ghRunForSha(repoAbs, b), workflowsFiringAt(repoAbs, refs.remoteSha, b).length > 0);
|
|
16668
16725
|
const el = rep.error ? { ok: false, why: rep.error }
|
|
16669
16726
|
// #591: a refused hand-off is worded as the single door words it — the same reason, the same detail.
|
|
16670
16727
|
: (report && report.handoff && !report.handoff.ok) ? { ok: false, why: `Refusing --handoff: ${report.handoff.detail}` }
|
|
@@ -16699,7 +16756,7 @@ function cmdShipBatch(opts) {
|
|
|
16699
16756
|
// member is ready. Wait for a partner until the repo's window, counted from when it became ready.
|
|
16700
16757
|
const lone = selected[0];
|
|
16701
16758
|
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);
|
|
16759
|
+
const since = shipBatch.readySince(fc ? fc.ciRunsAt(lone.sha) : git.ghRunsForCommit(repoAbs, lone.branch, lone.sha), commitIso.ok ? commitIso.stdout.trim() : null);
|
|
16703
16760
|
const pw = shipBatch.partnerWait({ n: cfg.n, waitSec: waitCfg.sec, eligibleCount: 1, readySinceMs: since, nowMs: Date.now() });
|
|
16704
16761
|
if (pw.wait) {
|
|
16705
16762
|
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 +16876,17 @@ function cmdShipBatch(opts) {
|
|
|
16819
16876
|
if (notJoining.length || dropped.length) print(` not in this batch: ${[...new Set([...notJoining, ...dropped.map((d) => d.branch)])].join(', ')}`);
|
|
16820
16877
|
return 0;
|
|
16821
16878
|
}
|
|
16822
|
-
//
|
|
16823
|
-
|
|
16879
|
+
// #742: the push IS the turn, so it is leased: create-only when no batch is live at this base (a
|
|
16880
|
+
// fresh build, or one whose old ref this call just deleted), or — a split rebuilding its own ref in
|
|
16881
|
+
// place — only while the remote still holds the head this call read. Of two landers at one base,
|
|
16882
|
+
// exactly one push lands; the other reads the remote again and waits on the winner.
|
|
16883
|
+
const expect = existing && existing.ref === ref ? existing.sha : '';
|
|
16884
|
+
const push = git.run('git', shipBatch.batchPushArgs({ remote, head, ref, expect }), { cwd: repoAbs });
|
|
16824
16885
|
cleanup();
|
|
16825
|
-
if (!push.ok)
|
|
16886
|
+
if (!push.ok) {
|
|
16887
|
+
if (shipBatch.pushRefusal({ remoteSha: remoteRefSha(ref), head }) === 'turn-lost') return turnMoved(ref);
|
|
16888
|
+
throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
|
|
16889
|
+
}
|
|
16826
16890
|
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
16891
|
if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
|
|
16828
16892
|
print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
|
|
@@ -16918,7 +16982,7 @@ function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opt
|
|
|
16918
16982
|
}
|
|
16919
16983
|
print(' pushed.');
|
|
16920
16984
|
deferredCollector = [];
|
|
16921
|
-
if (!git.git(
|
|
16985
|
+
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
16986
|
|
|
16923
16987
|
// The post-ship hook runs ONCE, over the whole batch — it is a trunk-checkout event, not a member one.
|
|
16924
16988
|
const changed = git.git(['diff', '--name-only', `${base}..${head}`], repoAbs);
|
package/tools/lib/ci-forgejo.js
CHANGED
|
@@ -7,8 +7,11 @@
|
|
|
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;
|
|
13
|
+
* issueView / commentView — (#740) READS of one issue (its comments and state: the executor's
|
|
14
|
+
* claim a hand-off land checks) and of one comment by id (the hand-off itself);
|
|
12
15
|
* releaseView / releaseCreate — the release object for a tag (`/releases`).
|
|
13
16
|
* Plus three reads that are NOT contract (forge-shaped, like the GitHub adapter's raw run lists):
|
|
14
17
|
* `ciRunsAt` (the status rows at a commit), `ciRunsSince` (rows for every commit on a branch since a
|
|
@@ -142,6 +145,16 @@ function issueShape(i) {
|
|
|
142
145
|
};
|
|
143
146
|
}
|
|
144
147
|
|
|
148
|
+
/** One comment from Forgejo's comment API → the GitHub adapter's comment shape (`gh issue view --json comments`). Pure. */
|
|
149
|
+
function commentShape(c) {
|
|
150
|
+
return {
|
|
151
|
+
author: { login: (c && c.user && c.user.login) || '' },
|
|
152
|
+
body: c && c.body != null ? String(c.body) : '',
|
|
153
|
+
createdAt: (c && c.created_at) || null,
|
|
154
|
+
url: (c && c.html_url) || null,
|
|
155
|
+
};
|
|
156
|
+
}
|
|
157
|
+
|
|
145
158
|
function pick(o, fields) {
|
|
146
159
|
if (!Array.isArray(fields) || !fields.length) return o;
|
|
147
160
|
const out = {};
|
|
@@ -199,6 +212,16 @@ function create(repoAbs, eng) {
|
|
|
199
212
|
return ng.length ? { ...summary, notGreen: ng } : summary;
|
|
200
213
|
},
|
|
201
214
|
|
|
215
|
+
/**
|
|
216
|
+
* #742, tracker contract: the runs on batch `ref` at `sha`. A commit status belongs to the commit,
|
|
217
|
+
* so the ref is accepted and ignored (a batch head is a commit no other ref carries). No `attempt`:
|
|
218
|
+
* a re-run replaces the context's newest status, and nothing counts how often — the batch reads 1.
|
|
219
|
+
*/
|
|
220
|
+
runsAtRef: (ref, sha) => {
|
|
221
|
+
const full = fullOf(sha);
|
|
222
|
+
return full ? rowsAt(full) : null;
|
|
223
|
+
},
|
|
224
|
+
|
|
202
225
|
/** #681, not contract: the status rows at `sha` (statusRow's shape), or null when the read failed. */
|
|
203
226
|
ciRunsAt: (sha) => {
|
|
204
227
|
const full = fullOf(sha);
|
|
@@ -246,6 +269,46 @@ function create(repoAbs, eng) {
|
|
|
246
269
|
return result(true, { data: out.slice(0, limit).map((i) => pick(i, fields)) });
|
|
247
270
|
},
|
|
248
271
|
|
|
272
|
+
/**
|
|
273
|
+
* One issue (tracker contract, #740): the GitHub adapter's shape, narrowed to `fields`; null when it
|
|
274
|
+
* could not be read (absent, any failed read). `comments` costs a second, paged
|
|
275
|
+
* read, so it is made only when asked for — and a partial comment list is null, never a short list.
|
|
276
|
+
*/
|
|
277
|
+
issueView: (num, fields = null) => {
|
|
278
|
+
const r = httpGet(`${base}/issues/${Number(num)}`, eng.tokenEnv);
|
|
279
|
+
if (r.status !== 200) return null;
|
|
280
|
+
let i;
|
|
281
|
+
try { i = JSON.parse(r.body); } catch (_) { return null; }
|
|
282
|
+
if (!i || typeof i !== 'object' || Array.isArray(i)) return null;
|
|
283
|
+
const out = issueShape(i);
|
|
284
|
+
if (Array.isArray(fields) && fields.includes('comments')) {
|
|
285
|
+
const comments = [];
|
|
286
|
+
for (let page = 1; ; page++) {
|
|
287
|
+
if (page > MAX_PAGES) return null; // more comments than we read: never a partial claim read
|
|
288
|
+
const c = httpGet(`${base}/issues/${Number(num)}/comments?page=${page}&limit=${PAGE_LIMIT}`, eng.tokenEnv);
|
|
289
|
+
if (c.status !== 200) return null;
|
|
290
|
+
let list;
|
|
291
|
+
try { list = JSON.parse(c.body); } catch (_) { return null; }
|
|
292
|
+
if (!Array.isArray(list)) return null;
|
|
293
|
+
for (const x of list) comments.push(commentShape(x));
|
|
294
|
+
if (list.length < PAGE_LIMIT) break;
|
|
295
|
+
}
|
|
296
|
+
out.comments = comments;
|
|
297
|
+
}
|
|
298
|
+
return pick(out, fields);
|
|
299
|
+
},
|
|
300
|
+
|
|
301
|
+
/** One issue comment by id (tracker contract, #740): `{ body, login, createdAt, htmlUrl }`, null when unread. */
|
|
302
|
+
commentView: (id) => {
|
|
303
|
+
if (!/^\d+$/.test(String(id || ''))) return null;
|
|
304
|
+
const r = httpGet(`${base}/issues/comments/${String(id)}`, eng.tokenEnv);
|
|
305
|
+
if (r.status !== 200) return null;
|
|
306
|
+
let c;
|
|
307
|
+
try { c = JSON.parse(r.body); } catch (_) { return null; }
|
|
308
|
+
if (!c || typeof c !== 'object' || Array.isArray(c)) return null;
|
|
309
|
+
return { body: c.body == null ? '' : String(c.body), login: (c.user && c.user.login) || '', createdAt: c.created_at || '', htmlUrl: c.html_url || '' };
|
|
310
|
+
},
|
|
311
|
+
|
|
249
312
|
/** #681, not contract: the issues blocking issue `num` — `[{ number, state, closedAt }]`, null when unread. */
|
|
250
313
|
blockedBy: (num) => {
|
|
251
314
|
const r = httpGet(`${base}/issues/${Number(num)}/dependencies?limit=${PAGE_LIMIT}`, eng.tokenEnv);
|
|
@@ -292,4 +355,4 @@ function notGreen(rows) {
|
|
|
292
355
|
.map((x) => ({ name: x.workflowName || 'unnamed', status: x.status, conclusion: x.conclusion || null }));
|
|
293
356
|
}
|
|
294
357
|
|
|
295
|
-
module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, issueShape, PAGE_LIMIT };
|
|
358
|
+
module.exports = { create, withFetcher, statusRow, rowsFromPages, notGreen, issueShape, commentShape, PAGE_LIMIT };
|
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
|
};
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
/**
|
|
3
|
-
* #578 — `colab ship --branch <br> --handoff <
|
|
3
|
+
* #578 — `colab ship --branch <br> --handoff <ref>`: land a branch whose claim lives on
|
|
4
4
|
* ANOTHER machine, from the hand-off its executor already recorded, without `--force`.
|
|
5
5
|
*
|
|
6
6
|
* The problem. `colab ship` takes the issue set to close from THIS machine's claim registry only.
|
|
@@ -15,10 +15,17 @@
|
|
|
15
15
|
* nothing of A's is taken over: A keeps its claim, worktree and branch until it confirms the land
|
|
16
16
|
* (its own `colab worktree rm`, which releases the claim as usual).
|
|
17
17
|
*
|
|
18
|
+
* The reference (#740). A hand-off is named forge-neutrally — `<forge-host>/<owner>/<repo>#<N>@comment:<id>`
|
|
19
|
+
* — and resolved through the repo's tracker adapter (the GitHub tracker, or the Forgejo forge engine:
|
|
20
|
+
* `commentView`), so nothing here parses one forge's web URL to decide what repo a comment is on.
|
|
21
|
+
* The comment URL a browser shows (`https://<host>/<owner>/<repo>/issues/<N>#issuecomment-<id>`) stays
|
|
22
|
+
* accepted as an alias, and either way the squash trailer records the neutral form.
|
|
23
|
+
*
|
|
18
24
|
* What a hand-off must prove, in order — the first failure is the verdict:
|
|
19
|
-
* 1. the
|
|
20
|
-
* 2. the comment was read from THIS repo (fetched through
|
|
21
|
-
*
|
|
25
|
+
* 1. the reference is a neutral hand-off reference or an issue-comment URL;
|
|
26
|
+
* 2. the comment was read from THIS repo (fetched through the repo-bound adapter, so an off-repo id
|
|
27
|
+
* is unreadable) and its own web address names the same host, repo, issue and comment id the
|
|
28
|
+
* reference does;
|
|
22
29
|
* 3. that issue is one the branch NAME carries (its trailing number run, CONVENTIONS.md §4) — the
|
|
23
30
|
* issue set is exactly that run, so git corroborates every `Closes #N` (#87) by construction;
|
|
24
31
|
* 4. the body names the branch, as a whole token;
|
|
@@ -48,13 +55,38 @@
|
|
|
48
55
|
|
|
49
56
|
const { branchIssueNumbers } = require('./branch-name');
|
|
50
57
|
|
|
51
|
-
/** `https
|
|
58
|
+
/** `https://<host>/<o>/<r>/issues/<N>#issuecomment-<id>` → parts, or null. Host-agnostic (GHE, Forgejo). The alias form (#740). */
|
|
52
59
|
function parseHandoffUrl(url) {
|
|
53
60
|
const m = String(url || '').trim().match(/^https?:\/\/[^/\s]+\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)\/?#issuecomment-(\d+)$/);
|
|
54
61
|
if (!m) return null;
|
|
55
62
|
return { owner: m[1], repo: m[2], issue: Number(m[3]), commentId: m[4] };
|
|
56
63
|
}
|
|
57
64
|
|
|
65
|
+
/**
|
|
66
|
+
* #740 — `<forge-host>/<owner>/<repo>#<N>@comment:<id>` (the neutral form) or an issue-comment URL
|
|
67
|
+
* (the alias) → `{ host, owner, repo, issue, commentId, form: 'ref' | 'url' }`, or null. Pure. The
|
|
68
|
+
* host is lower-cased (a host name is case-insensitive); owner and repo keep their spelling and are
|
|
69
|
+
* compared case-insensitively by the verdict, as the forges themselves resolve them. No part holds
|
|
70
|
+
* a space, a `/`, a `#` or an `@`, so the batch grammar's first-`@` split (#591) and the trailer's
|
|
71
|
+
* `\S+` read both stay unambiguous.
|
|
72
|
+
*/
|
|
73
|
+
function parseHandoffRef(s) {
|
|
74
|
+
const str = String(s || '').trim();
|
|
75
|
+
const m = str.match(/^([^/\s#@]+)\/([^/\s#@]+)\/([^/\s#@]+)#(\d+)@comment:(\d+)$/);
|
|
76
|
+
if (m && !/^[a-z][a-z0-9+.-]*:$/i.test(m[1])) {
|
|
77
|
+
return { host: m[1].toLowerCase(), owner: m[2], repo: m[3], issue: Number(m[4]), commentId: m[5], form: 'ref' };
|
|
78
|
+
}
|
|
79
|
+
const u = parseHandoffUrl(str);
|
|
80
|
+
if (!u) return null;
|
|
81
|
+
const host = str.match(/^https?:\/\/([^/\s]+)/)[1].toLowerCase();
|
|
82
|
+
return { host, ...u, form: 'url' };
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** #740 — the neutral reference for `{ host, owner, repo, issue, commentId }`. Pure. */
|
|
86
|
+
function formatHandoffRef(p) {
|
|
87
|
+
return `${String(p.host).toLowerCase()}/${p.owner}/${p.repo}#${p.issue}@comment:${p.commentId}`;
|
|
88
|
+
}
|
|
89
|
+
|
|
58
90
|
function escapeRe(s) { return String(s).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); }
|
|
59
91
|
|
|
60
92
|
/** Does `body` name `branch` as a whole token (not as a prefix of a longer branch name)? */
|
|
@@ -71,8 +103,9 @@ function namedShas(body) {
|
|
|
71
103
|
|
|
72
104
|
/**
|
|
73
105
|
* The verdict. Inputs:
|
|
74
|
-
* url — the --handoff value
|
|
75
|
-
* comment — { body, login, createdAt, htmlUrl } as read from THIS repo
|
|
106
|
+
* url — the --handoff value: a neutral reference, or the comment's URL (#740)
|
|
107
|
+
* comment — { body, login, createdAt, htmlUrl } as read from THIS repo through the tracker
|
|
108
|
+
* adapter's `commentView`, or null (unreadable)
|
|
76
109
|
* branch — the branch being shipped
|
|
77
110
|
* refs — git.branchRefs(): { localSha, remoteSha, localFromRemote }
|
|
78
111
|
* claimsByIssue — { [n]: [{ login, branch, at, host, machine }] } live claim comments per issue,
|
|
@@ -82,20 +115,23 @@ function namedShas(body) {
|
|
|
82
115
|
* issueStates — (#647) { [n]: { state, closedAt } } per issue as read now; a missing entry is
|
|
83
116
|
* unknown and earns no exemption
|
|
84
117
|
* refNumbers — (#647) the --refs numbers; used only to say why they do not waive a claim
|
|
85
|
-
* Returns { ok: true, issues, refIssues, sha, handedOff, syncMerges, executor, url } or { ok: false, reason, detail }.
|
|
118
|
+
* Returns { ok: true, issues, refIssues, sha, handedOff, syncMerges, executor, url, ref, htmlUrl } or { ok: false, reason, detail }.
|
|
119
|
+
* `url` is the --handoff value as given; `ref` (#740) is the neutral reference, built from the comment's
|
|
120
|
+
* own web address as read back — so a URL-form input records the same `ref` a neutral one does.
|
|
86
121
|
* `issues` is the whole trailing run; `refIssues` is its closed-before-the-hand-off subset (#647).
|
|
87
122
|
* `sha` is what lands (the remote head); `handedOff` is the sha the hand-off named — equal to `sha`
|
|
88
123
|
* unless the head was synced, in which case `syncMerges` counts the merges between them.
|
|
89
124
|
*/
|
|
90
125
|
function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain, issueStates, refNumbers }) {
|
|
91
126
|
const no = (reason, detail) => ({ ok: false, reason, detail });
|
|
92
|
-
const u =
|
|
93
|
-
if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not
|
|
127
|
+
const u = parseHandoffRef(url);
|
|
128
|
+
if (!u) return no('bad-url', `--handoff ${url || '(empty)'} is not a hand-off reference — write <forge-host>/<owner>/<repo>#<N>@comment:<id> (or the comment's URL, …/issues/<N>#issuecomment-<id>)`);
|
|
94
129
|
if (!comment) return no('unreadable', `comment ${u.commentId} could not be read from this repo — it must be a comment on one of this repo's issues`);
|
|
95
|
-
|
|
96
|
-
|
|
130
|
+
// The comment's own web address, as the adapter read it back, is the authority on where it lives.
|
|
131
|
+
const got = parseHandoffRef(comment.htmlUrl);
|
|
132
|
+
if (!got || got.commentId !== u.commentId || got.issue !== u.issue || got.host !== u.host ||
|
|
97
133
|
got.owner.toLowerCase() !== u.owner.toLowerCase() || got.repo.toLowerCase() !== u.repo.toLowerCase()) {
|
|
98
|
-
return no('mismatch', `the
|
|
134
|
+
return no('mismatch', `the reference says ${formatHandoffRef(u)}, but comment ${u.commentId} is ${got ? formatHandoffRef(got) : (comment.htmlUrl || 'somewhere else')}`);
|
|
99
135
|
}
|
|
100
136
|
const issues = branchIssueNumbers(branch);
|
|
101
137
|
if (!issues.length) return no('branch-names-no-issue', `${branch} carries no trailing issue number, so a hand-off has no issue set to close — ship it with --adopt if it genuinely has none`);
|
|
@@ -141,7 +177,8 @@ function handoffVerdict({ url, comment, branch, refs, claimsByIssue, syncChain,
|
|
|
141
177
|
}
|
|
142
178
|
if (!executor) executor = { login: match.login, host: match.host, machine: match.machine || '' };
|
|
143
179
|
}
|
|
144
|
-
return { ok: true, issues, refIssues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim()
|
|
180
|
+
return { ok: true, issues, refIssues, sha: refs.remoteSha, handedOff: lineage[at], syncMerges: at, executor, url: String(url).trim(),
|
|
181
|
+
ref: formatHandoffRef(got), htmlUrl: comment.htmlUrl };
|
|
145
182
|
}
|
|
146
183
|
|
|
147
184
|
/** #647: was this issue CLOSED strictly before `at` (the hand-off's createdAt)? Unknown ⇒ false. */
|
|
@@ -153,14 +190,15 @@ function closedBefore(st, at) {
|
|
|
153
190
|
}
|
|
154
191
|
|
|
155
192
|
/**
|
|
156
|
-
* The squash trailer recording the door the issue set came through
|
|
193
|
+
* The squash trailer recording the door the issue set came through: the NEUTRAL reference (#740) —
|
|
194
|
+
* never one forge's web URL — and the HANDED-OFF sha —
|
|
157
195
|
* the one the executor vouched for — and, after a sync (#579), the head that actually landed.
|
|
158
196
|
*/
|
|
159
197
|
function handoffTrailer(v) {
|
|
160
198
|
if (!v || !v.ok) return '';
|
|
161
199
|
const handed = String(v.handedOff || v.sha).slice(0, 12);
|
|
162
200
|
const synced = v.syncMerges ? ` (synced to ${String(v.sha).slice(0, 12)} by ${v.syncMerges} base merge${v.syncMerges === 1 ? '' : 's'})` : '';
|
|
163
|
-
return `Colab-Handoff: ${v.url} @ ${handed}${synced}`;
|
|
201
|
+
return `Colab-Handoff: ${v.ref || v.url} @ ${handed}${synced}`;
|
|
164
202
|
}
|
|
165
203
|
|
|
166
204
|
/**
|
|
@@ -230,7 +268,8 @@ function parseBatchEntries(list) {
|
|
|
230
268
|
|
|
231
269
|
/**
|
|
232
270
|
* #591 — read a `Colab-Handoff:` trailer back off a squash commit body (handoffTrailer's inverse):
|
|
233
|
-
* `{ url, handedOff }` or null.
|
|
271
|
+
* `{ url, handedOff }` or null. `url` is whichever form the trailer holds: the neutral reference
|
|
272
|
+
* (#740), or the comment URL a squash written before it recorded. A batch lands in a second call, so the member's door is read from
|
|
234
273
|
* the commit the combined run graded, never re-supplied on the command line.
|
|
235
274
|
*/
|
|
236
275
|
function parseHandoffTrailer(body) {
|
|
@@ -238,4 +277,4 @@ function parseHandoffTrailer(body) {
|
|
|
238
277
|
return m ? { url: m[1], handedOff: m[2] } : null;
|
|
239
278
|
}
|
|
240
279
|
|
|
241
|
-
module.exports = { parseHandoffUrl, namesBranch, namedShas, handoffVerdict, closedBefore, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };
|
|
280
|
+
module.exports = { parseHandoffUrl, parseHandoffRef, formatHandoffRef, namesBranch, namedShas, handoffVerdict, closedBefore, handoffTrailer, syncMergeChain, parseBatchEntries, parseHandoffTrailer };
|
|
@@ -42,6 +42,13 @@ function create(repoAbs, given = {}) {
|
|
|
42
42
|
const runs = clone(given.runs || []);
|
|
43
43
|
const releases = new Map((given.releases || []).map((r) => [r.tag, clone(r)]));
|
|
44
44
|
const base = `https://tracker.invalid/${String(repoAbs).replace(/^\/+/, '')}`;
|
|
45
|
+
// #740: comment ids are ONE sequence across the repo, as on a real forge — commentView reads by id alone.
|
|
46
|
+
let lastCommentId = 0;
|
|
47
|
+
const commentOf = (num, c) => {
|
|
48
|
+
const id = c.id === undefined ? ++lastCommentId : Number(c.id);
|
|
49
|
+
lastCommentId = Math.max(lastCommentId, id);
|
|
50
|
+
return { id, issue: num, author: c.author, body: c.body, createdAt: c.createdAt || null };
|
|
51
|
+
};
|
|
45
52
|
|
|
46
53
|
for (const i of given.issues || []) {
|
|
47
54
|
issues.set(i.number, {
|
|
@@ -49,7 +56,7 @@ function create(repoAbs, given = {}) {
|
|
|
49
56
|
stateReason: i.stateReason || (i.state === 'CLOSED' ? 'COMPLETED' : ''),
|
|
50
57
|
createdAt: i.createdAt || null, closedAt: i.closedAt || null,
|
|
51
58
|
labels: clone(i.labels || []), assignees: clone(i.assignees || []),
|
|
52
|
-
comments: (i.comments || []).map((c) => (
|
|
59
|
+
comments: (i.comments || []).map((c) => commentOf(i.number, c)),
|
|
53
60
|
events: clone(i.events || []),
|
|
54
61
|
});
|
|
55
62
|
}
|
|
@@ -65,7 +72,7 @@ function create(repoAbs, given = {}) {
|
|
|
65
72
|
createdAt: i.createdAt, closedAt: i.closedAt, url: `${base}/issues/${i.number}`,
|
|
66
73
|
labels: i.labels.map((name) => ({ name })),
|
|
67
74
|
assignees: i.assignees.map((l) => ({ login: l })),
|
|
68
|
-
comments: i.comments.map((c) => ({ author: { login: c.author }, body: c.body })),
|
|
75
|
+
comments: i.comments.map((c) => ({ author: { login: c.author }, body: c.body, createdAt: c.createdAt, url: `${base}/issues/${i.number}#issuecomment-${c.id}` })),
|
|
69
76
|
};
|
|
70
77
|
}
|
|
71
78
|
function prShape(p) {
|
|
@@ -94,6 +101,14 @@ function create(repoAbs, given = {}) {
|
|
|
94
101
|
const i = issues.get(Number(num));
|
|
95
102
|
return offline || !i ? null : pick(issueShape(i), fields);
|
|
96
103
|
},
|
|
104
|
+
commentView: (id) => {
|
|
105
|
+
if (offline) return null;
|
|
106
|
+
for (const i of issues.values()) {
|
|
107
|
+
const c = i.comments.find((x) => String(x.id) === String(id));
|
|
108
|
+
if (c) return { body: c.body, login: c.author, createdAt: c.createdAt || '', htmlUrl: `${base}/issues/${i.number}#issuecomment-${c.id}` };
|
|
109
|
+
}
|
|
110
|
+
return null;
|
|
111
|
+
},
|
|
97
112
|
issueListAll: ({ limit, fields } = {}) => withList([...issues.values()]
|
|
98
113
|
.sort((a, b) => b.number - a.number).slice(0, limit).map((i) => pick(issueShape(i), fields))),
|
|
99
114
|
issueCreate: ({ title, body }) => {
|
|
@@ -108,8 +123,9 @@ function create(repoAbs, given = {}) {
|
|
|
108
123
|
const i = issues.get(Number(num));
|
|
109
124
|
if (offline) return result(false);
|
|
110
125
|
if (!i) return fail(`issue #${num} not found`);
|
|
111
|
-
i.
|
|
112
|
-
|
|
126
|
+
const c = commentOf(i.number, { author: login, body, createdAt: new Date().toISOString() });
|
|
127
|
+
i.comments.push(c);
|
|
128
|
+
return result(true, { stdout: `${base}/issues/${num}#issuecomment-${c.id}` });
|
|
113
129
|
},
|
|
114
130
|
issueClose: (num, { reason } = {}) => {
|
|
115
131
|
const i = issues.get(Number(num));
|
|
@@ -184,6 +200,12 @@ function create(repoAbs, given = {}) {
|
|
|
184
200
|
return require('./git').summarizeRunsForCommit(clone(runs.filter((r) => r.headSha === sha && (!branch || r.headBranch === branch))), sha);
|
|
185
201
|
},
|
|
186
202
|
|
|
203
|
+
// #742: the seeded runs on `ref` at `sha`, with attempt (default 1) — the GitHub adapter's row shape.
|
|
204
|
+
runsAtRef: (ref, sha) => {
|
|
205
|
+
if (offline || !sha) return null;
|
|
206
|
+
return clone(runs.filter((r) => r.headBranch === ref && r.headSha === sha)).map((r) => ({ attempt: 1, ...r }));
|
|
207
|
+
},
|
|
208
|
+
|
|
187
209
|
releaseView: (tag) => {
|
|
188
210
|
if (offline) return result(false);
|
|
189
211
|
return releases.has(tag) ? result(true, { stdout: JSON.stringify({ tagName: tag }) }) : fail('release not found');
|
|
@@ -123,6 +123,14 @@ function create(repoAbs) {
|
|
|
123
123
|
|
|
124
124
|
// --- issues ------------------------------------------------------------------------------
|
|
125
125
|
issueView: (num, fields) => git().ghIssueView(repoAbs, num, fields),
|
|
126
|
+
// #740: one comment by id — the read `colab ship --handoff` made with a raw `gh api`, same argv.
|
|
127
|
+
commentView: (id) => {
|
|
128
|
+
if (!/^\d+$/.test(String(id || ''))) return null;
|
|
129
|
+
const r = withData(exec(['api', `repos/{owner}/{repo}/issues/comments/${id}`], at));
|
|
130
|
+
const j = r.data;
|
|
131
|
+
if (!j || typeof j !== 'object' || Array.isArray(j)) return null;
|
|
132
|
+
return { body: j.body || '', login: (j.user && j.user.login) || '', createdAt: j.created_at || '', htmlUrl: j.html_url || '' };
|
|
133
|
+
},
|
|
126
134
|
issueListAll: ({ limit, fields, maxBuffer } = {}) => withData(exec(
|
|
127
135
|
['issue', 'list', '--state', 'all', '--limit', String(limit), '--json', fields.join(',')],
|
|
128
136
|
{ ...at, ...(maxBuffer ? { maxBuffer } : {}) })),
|
|
@@ -161,6 +169,10 @@ function create(repoAbs) {
|
|
|
161
169
|
return branch ? git().ghRunForCommit(repoAbs, branch, sha, undefined, opts) : git().ghRunForCommitAnyRef(repoAbs, sha, undefined, opts);
|
|
162
170
|
},
|
|
163
171
|
|
|
172
|
+
// #742: every run on batch `ref` at `sha`, with attempt and updatedAt — the read ship --batch made
|
|
173
|
+
// before the contract had it (ghRunsForRef, same argv).
|
|
174
|
+
runsAtRef: (ref, sha) => git().ghRunsForRef(repoAbs, ref, sha),
|
|
175
|
+
|
|
164
176
|
// --- releases ----------------------------------------------------------------------------
|
|
165
177
|
releaseView: (tag) => exec(['release', 'view', tag, '--json', 'tagName'], at),
|
|
166
178
|
releaseCreate: (tag, { notesFile, final = false }) => {
|
|
@@ -15,9 +15,9 @@
|
|
|
15
15
|
"login": "the account the tracker is authenticated as (what currentLogin returns, and the author of anything this tracker writes).",
|
|
16
16
|
"offline": "true = the tracker cannot be reached: reads return their `could not read` value (null, or `data: null`), writes return ok:false. Never a throw.",
|
|
17
17
|
"labels": "the label names defined on the repo, in the order labelList returns them.",
|
|
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.",
|
|
18
|
+
"issues": "[{number, title, body, state: OPEN|CLOSED, stateReason, labels: [name], assignees: [login], comments: [{id, author, body, createdAt}] (`id` is the comment's repo-wide id, the one commentView reads by — #740), 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": [
|
|
@@ -43,6 +43,22 @@
|
|
|
43
43
|
{ "call": "issueView", "args": [99, ["number"]], "expect": null }
|
|
44
44
|
]
|
|
45
45
|
},
|
|
46
|
+
{
|
|
47
|
+
"id": "comment-view",
|
|
48
|
+
"description": "commentView (#740) reads one comment of this repo by its id alone — body, author login, createdAt and the forge's own web address for it, which names the issue it sits on; an id the repo does not have reads as null. issueView with `comments` returns each comment's author as an object and its createdAt — what the executor's-claim read of a hand-off land orders by.",
|
|
49
|
+
"given": {
|
|
50
|
+
"login": "alice",
|
|
51
|
+
"issues": [{ "number": 90, "title": "feat: export", "state": "OPEN",
|
|
52
|
+
"comments": [{ "id": 555, "author": "exec", "body": "wrapped on feat/export-90 (head abcdef01).", "createdAt": "2026-10-08T12:00:00Z" }] }]
|
|
53
|
+
},
|
|
54
|
+
"steps": [
|
|
55
|
+
{ "call": "commentView", "args": ["555"],
|
|
56
|
+
"expect": { "body": "wrapped on feat/export-90 (head abcdef01).", "login": "exec", "createdAt": "2026-10-08T12:00:00Z", "htmlUrl": { "$re": "/issues/90#issuecomment-555$" } } },
|
|
57
|
+
{ "call": "commentView", "args": ["999"], "expect": null },
|
|
58
|
+
{ "call": "issueView", "args": [90, ["state", "closedAt", "comments"]],
|
|
59
|
+
"expect": { "state": "OPEN", "comments": [{ "author": { "login": "exec" }, "body": "wrapped on feat/export-90 (head abcdef01).", "createdAt": "2026-10-08T12:00:00Z" }] } }
|
|
60
|
+
]
|
|
61
|
+
},
|
|
46
62
|
{
|
|
47
63
|
"id": "issue-create",
|
|
48
64
|
"description": "issueCreate takes the next number in the sequence issues and pull requests share, returns it with the issue's URL, and the new issue is open with nothing on it.",
|
|
@@ -255,6 +271,32 @@
|
|
|
255
271
|
"steps": [
|
|
256
272
|
{ "call": "ciVerdict", "args": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", { "branch": "main" }], "expect": null }
|
|
257
273
|
]
|
|
274
|
+
},
|
|
275
|
+
{
|
|
276
|
+
"id": "runs-at-ref",
|
|
277
|
+
"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.",
|
|
278
|
+
"given": {
|
|
279
|
+
"login": "alice",
|
|
280
|
+
"runs": [
|
|
281
|
+
{"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},
|
|
282
|
+
{"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}
|
|
283
|
+
]
|
|
284
|
+
},
|
|
285
|
+
"steps": [
|
|
286
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
|
|
287
|
+
"expect": [{"headSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "completed", "conclusion": "success", "updatedAt": "2026-11-01T10:05:00Z"}] },
|
|
288
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
|
|
289
|
+
"expect": [{"headSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "status": "completed", "conclusion": "failure"}] },
|
|
290
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "cccccccccccccccccccccccccccccccccccccccc"], "expect": [] }
|
|
291
|
+
]
|
|
292
|
+
},
|
|
293
|
+
{
|
|
294
|
+
"id": "runs-at-ref-unreadable",
|
|
295
|
+
"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.",
|
|
296
|
+
"given": { "login": "alice", "offline": true },
|
|
297
|
+
"steps": [
|
|
298
|
+
{ "call": "runsAtRef", "args": ["ship-batch/1111111", "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"], "expect": null }
|
|
299
|
+
]
|
|
258
300
|
}
|
|
259
301
|
]
|
|
260
302
|
}
|
package/tools/lib/tracker.js
CHANGED
|
@@ -15,15 +15,27 @@
|
|
|
15
15
|
* "could not read" and never "none"; the read helpers keep their existing null-on-failure
|
|
16
16
|
* contract.
|
|
17
17
|
*
|
|
18
|
+
* Comment read (#740): `commentView(id)` reads ONE issue comment of this repo by its numeric id —
|
|
19
|
+
* `{ body, login, createdAt, htmlUrl }`, or null when it could not be read (absent, another repo's,
|
|
20
|
+
* offline). `htmlUrl` is the forge's own web address for it, the one fact a caller may check the
|
|
21
|
+
* comment's issue and repo against (tools/lib/ship-handoff.js, the hand-off reference).
|
|
22
|
+
*
|
|
18
23
|
* CI verdict (#678): `ciVerdict(sha, { branch })` answers "is this sha green" as ONE summary —
|
|
19
24
|
* `{ status, conclusion, sha, createdAt, databaseId, runCount, … }` (tools/lib/git.js
|
|
20
25
|
* `summarizeRunsForCommit`'s shape, the one ship's CI rows and the docs-only row already read), or
|
|
21
26
|
* null when the read failed. `status: 'none'` is "no run at this sha", never "could not read". A
|
|
22
27
|
* forge the CLI lands code on and releases on, but never writes issues to, implements
|
|
23
|
-
* `FORGE_METHODS` (#681): the CI verdict,
|
|
28
|
+
* `FORGE_METHODS` (#681): the CI verdict, READS of the issue list, one issue and one comment (#740),
|
|
29
|
+
* and the release object —
|
|
24
30
|
* tools/lib/ci-forgejo.js, Forgejo commit statuses and `/releases`. `CI_METHODS` stays the subset
|
|
25
31
|
* the landing path (#678) needs. Which engine a repo gets is `engineFor` below.
|
|
26
32
|
*
|
|
33
|
+
* Batch turn (#742): `runsAtRef(ref, sha)` — every CI run on one ref at one sha, as rows
|
|
34
|
+
* `{ headSha, status, conclusion, createdAt, updatedAt, databaseId, workflowName, attempt? }`, or null
|
|
35
|
+
* when the read failed ([] is "no run yet"). `colab ship --batch` judges its combined run from these
|
|
36
|
+
* (the attempt caps the one re-run; updatedAt dates a green settle). A forge whose CI is a commit
|
|
37
|
+
* status reads the commit and ignores the ref, and may omit `attempt` (read as 1).
|
|
38
|
+
*
|
|
27
39
|
* Deliberately NOT in the contract yet (#501 left it so: no scenario needs them, and each would
|
|
28
40
|
* pin a GitHub-only shape into a spec other trackers must satisfy): the raw CI-run lists and REST
|
|
29
41
|
* probes behind `ciVerdict`, label create/delete/edit, raw `issue edit` flags and raw `api`
|
|
@@ -35,6 +47,7 @@ const METHODS = Object.freeze([
|
|
|
35
47
|
{ name: 'currentLogin', kind: 'read', returns: 'login | null' },
|
|
36
48
|
{ name: 'issueView', kind: 'read', returns: 'object | null' },
|
|
37
49
|
{ name: 'issueListAll', kind: 'read', returns: 'result + data: issue[] | null' },
|
|
50
|
+
{ name: 'commentView', kind: 'read', returns: '{ body, login, createdAt, htmlUrl } | null' },
|
|
38
51
|
{ name: 'issueCreate', kind: 'write', returns: 'result + number, url' },
|
|
39
52
|
{ name: 'issueComment', kind: 'write', returns: 'result' },
|
|
40
53
|
{ name: 'issueClose', kind: 'write', returns: 'result' },
|
|
@@ -48,6 +61,7 @@ const METHODS = Object.freeze([
|
|
|
48
61
|
{ name: 'prEdit', kind: 'write', returns: 'result' },
|
|
49
62
|
{ name: 'runList', kind: 'read', returns: 'result + data: run[] | null' },
|
|
50
63
|
{ name: 'ciVerdict', kind: 'read', returns: 'run summary | null' },
|
|
64
|
+
{ name: 'runsAtRef', kind: 'read', returns: 'run[] | null' },
|
|
51
65
|
{ name: 'releaseView', kind: 'read', returns: 'result' },
|
|
52
66
|
{ name: 'releaseCreate', kind: 'write', returns: 'result' },
|
|
53
67
|
].map(Object.freeze));
|
|
@@ -56,11 +70,14 @@ const METHODS = Object.freeze([
|
|
|
56
70
|
const CI_METHODS = Object.freeze(['ciVerdict']);
|
|
57
71
|
|
|
58
72
|
/**
|
|
59
|
-
* The methods a forge engine implements (#681): landing (`CI_METHODS`)
|
|
73
|
+
* The methods a forge engine implements (#681): landing (`CI_METHODS`), the batch turn's run read
|
|
74
|
+
* (#742, `runsAtRef`), plus what a release needs —
|
|
60
75
|
* the issue list READ (switch markers, the release hold, an existing tracking record) and the release
|
|
61
|
-
* object
|
|
76
|
+
* object — plus (#740) the reads a hand-off land makes: one comment by id (`commentView`) and one
|
|
77
|
+
* issue's comments and state (`issueView`, for the executor's claim). No issue write is here on
|
|
78
|
+
* purpose: #678's ruling keeps the forge's tracker the adopter's.
|
|
62
79
|
*/
|
|
63
|
-
const FORGE_METHODS = Object.freeze([...CI_METHODS, 'issueListAll', 'releaseView', 'releaseCreate']);
|
|
80
|
+
const FORGE_METHODS = Object.freeze([...CI_METHODS, 'runsAtRef', 'issueListAll', 'issueView', 'commentView', 'releaseView', 'releaseCreate']);
|
|
64
81
|
|
|
65
82
|
/**
|
|
66
83
|
* Throw, naming every contract method `impl` lacks. Returns `impl` when it is complete.
|