@futurelastic/colab-handbook 1.13.0-rc.52 → 1.13.0-rc.53
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 +83 -4
- package/tools/lib/git.js +25 -1
- package/tools/lib/landed-prs.js +58 -0
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -77,6 +77,7 @@ const releaseCut = require('./lib/release-cut');
|
|
|
77
77
|
const releaseFinalize = require('./lib/release-finalize');
|
|
78
78
|
const releaseChannel = require('./lib/release-channel');
|
|
79
79
|
const shippedBranch = require('./lib/shipped-branch');
|
|
80
|
+
const landedPrs = require('./lib/landed-prs');
|
|
80
81
|
const shipRoles = require('./lib/ship-roles'); // #372
|
|
81
82
|
const shipHandoff = require('./lib/ship-handoff'); // #578
|
|
82
83
|
const refsBrake = require('./lib/refs-brake'); // #385
|
|
@@ -4513,7 +4514,8 @@ CI grant merges into a repo whose own test suite is known-failing:
|
|
|
4513
4514
|
for the BRANCH's own current head (the same "ask by sha" check \`ship\` itself uses) — a human's
|
|
4514
4515
|
say-so alone is never enough. \`--evidence-run\` is a RECORDING-ONLY pointer for the audit trail;
|
|
4515
4516
|
it can never substitute for the measured run. If the branch has no run yet, open a PR for it
|
|
4516
|
-
(\`gh pr create\`) and let CI finish, then re-run this command.
|
|
4517
|
+
(\`gh pr create\`) and let CI finish, then re-run this command. You do not need to close that
|
|
4518
|
+
PR afterwards: \`colab ship\` closes it once the branch lands (#584).
|
|
4517
4519
|
2. NEVER STACKS. Creating a grant refuses outright if trunk is not currently red (nothing to
|
|
4518
4520
|
exempt), and refuses again if a PRIOR ci-grant already merged something and trunk has been red
|
|
4519
4521
|
continuously since — a second exemption on a still-broken repo is exactly the failure this gate
|
|
@@ -4862,7 +4864,7 @@ function cmdCiGrantCreate(repoAbs, num, opts) {
|
|
|
4862
4864
|
throw new UserError(
|
|
4863
4865
|
`"${opts.branch}" has no completed, successful CI run for its current head (${shortSha(evRun.sha)}) — ` +
|
|
4864
4866
|
`a CI grant requires MEASURED evidence, never a human's say-so alone. Open a PR for it ` +
|
|
4865
|
-
`(\`gh pr create\`) and let CI finish, then re-run this command.`);
|
|
4867
|
+
`(\`gh pr create\`) and let CI finish, then re-run this command — \`colab ship\` closes that PR once the branch lands (#584).`);
|
|
4866
4868
|
}
|
|
4867
4869
|
const evidenceSha = evRun.sha;
|
|
4868
4870
|
|
|
@@ -6329,6 +6331,9 @@ in a cleanup cron.
|
|
|
6329
6331
|
reported but never deleted (a label a triage session just created and has not
|
|
6330
6332
|
applied yet is indistinguishable from one whose members were all transferred
|
|
6331
6333
|
away — the labels API exposes no creation time, so a human decides).
|
|
6334
|
+
Also lists open PRs whose head commit already landed in trunk (#584) — CI-trigger
|
|
6335
|
+
PRs a squash ship left open. Report-only, --prune included: doctor never closes
|
|
6336
|
+
a PR. A PR whose head is not in the local clone is not judged.
|
|
6332
6337
|
`;
|
|
6333
6338
|
|
|
6334
6339
|
const EMPTY_SET = new Set();
|
|
@@ -6413,7 +6418,7 @@ function cmdDoctor(argv) {
|
|
|
6413
6418
|
const report = { deadWorktrees: [], orphanClaims: [], staleClaims: [], stalePlaces: [], unprovablePlaces: [], releasedPlaces: [], orphanPorts: [], brokenRecords: [], prunedPorts: [],
|
|
6414
6419
|
renamedHostRecords: [], unprovenHostRecords: [],
|
|
6415
6420
|
mergedFlips: [], mergedSweep: [], mergedDirty: [], mergedHookFail: [], mergedRemoveFail: [], shippedBranches: [], ghostPorts: [],
|
|
6416
|
-
spentGroupLabels: [], groupLabelsChecked: !!opts.sync, pruned: !!opts.prune };
|
|
6421
|
+
spentGroupLabels: [], groupLabelsChecked: !!opts.sync, landedPrs: [], landedPrsUnread: [], pruned: !!opts.prune };
|
|
6417
6422
|
|
|
6418
6423
|
// One answer per (repo, branch) — pass 5b asks about the same branch from a worktree and from each
|
|
6419
6424
|
// of its claims, and every miss costs two `git rev-parse` calls.
|
|
@@ -6804,6 +6809,28 @@ function cmdDoctor(argv) {
|
|
|
6804
6809
|
}
|
|
6805
6810
|
}
|
|
6806
6811
|
|
|
6812
|
+
// 9b. open PRs whose head already landed (#584) — the CI-trigger PRs a squash ship left open before
|
|
6813
|
+
// ship learned to close them, or that a ship on another machine could not close. Report-only,
|
|
6814
|
+
// --prune included: closing a PR is a write on a shared forge, and a human may still want it.
|
|
6815
|
+
// Behind --sync for the same reason as pass 9 (network). A PR whose head commit is not in this
|
|
6816
|
+
// clone is not judged — the answer would be a guess — so the list is honest, not exhaustive.
|
|
6817
|
+
if (opts.sync && git.ghAvailable()) {
|
|
6818
|
+
const repos = [...new Set([...(config.repos || []), ...knownRepos(config)].map((r) => path.resolve(r)))]
|
|
6819
|
+
.filter((r) => repoLive(r) && git.remoteUrl(r));
|
|
6820
|
+
for (const repo of repos) {
|
|
6821
|
+
const trunk = resolveTrunk(repo, projectDoc(repo));
|
|
6822
|
+
if (!trunk) continue;
|
|
6823
|
+
const listed = git.ghOpenPrs(repo);
|
|
6824
|
+
if (listed.error) { report.landedPrsUnread.push({ repo: shortRepo(repo), error: listed.error }); continue; }
|
|
6825
|
+
for (const pr of listed.prs) {
|
|
6826
|
+
if (!pr.headRefOid || pr.headRefName === trunk) continue;
|
|
6827
|
+
if (!git.git(['cat-file', '-e', `${pr.headRefOid}^{commit}`], repo).ok) continue;
|
|
6828
|
+
if (landed.landedState(repo, trunk, pr.headRefOid).state !== 'landed') continue;
|
|
6829
|
+
report.landedPrs.push({ repo: shortRepo(repo), number: pr.number, url: pr.url || '', branch: pr.headRefName || '', trunk });
|
|
6830
|
+
}
|
|
6831
|
+
}
|
|
6832
|
+
}
|
|
6833
|
+
|
|
6807
6834
|
// 10. notifyUrl against a DECLARED local observer (#414). Read-only, never pruned, never counted in
|
|
6808
6835
|
// the verdict — it is configuration, not state drift. Silent on a machine with no
|
|
6809
6836
|
// <COLAB_HOME>/notify-endpoint: unset is the right default where no observer runs.
|
|
@@ -6953,6 +6980,17 @@ function cmdDoctor(argv) {
|
|
|
6953
6980
|
print(' NOT exhaustive: a branch whose work trunk later rewrote can conflict against trunk');
|
|
6954
6981
|
print(' instead of matching it, and is omitted here rather than risk calling unmerged work spent.');
|
|
6955
6982
|
}
|
|
6983
|
+
// #584 — after the verdict, not counted: an open PR on a landed branch breaks nothing, it reads as
|
|
6984
|
+
// unmerged work on a tracker. Printed only under --sync.
|
|
6985
|
+
if (report.landedPrs.length) {
|
|
6986
|
+
print('');
|
|
6987
|
+
print(`Open PRs whose branch already landed (${report.landedPrs.length}) — the squash left them open:`);
|
|
6988
|
+
for (const p of report.landedPrs) print(` #${p.number} ${p.branch} [${p.repo}] → in ${p.trunk}${p.url ? ` ${p.url}` : ''}`);
|
|
6989
|
+
print(' `colab ship` closes these itself since #584; these predate that, or a ship could not close them.');
|
|
6990
|
+
print(' doctor never closes a PR, --prune included. To close one:');
|
|
6991
|
+
print(` gh pr close ${report.landedPrs[0].number} --comment "Landed on ${report.landedPrs[0].trunk} by squash." # in ${report.landedPrs[0].repo}`);
|
|
6992
|
+
}
|
|
6993
|
+
for (const u of report.landedPrsUnread) warn(`could not list open PRs in ${u.repo} (${u.error}) — landed-PR check skipped there`);
|
|
6956
6994
|
// Also after the verdict, and also not drift: a spent group label breaks nothing, it is picker
|
|
6957
6995
|
// noise on a tracker. Printed only under --sync, so silence here NEVER means "checked, clean" —
|
|
6958
6996
|
// which is why a --sync run that finds nothing says so explicitly below.
|
|
@@ -14085,11 +14123,13 @@ function cmdShip(argv) {
|
|
|
14085
14123
|
// a long ship these lines would otherwise scroll off above the `✓ Shipped` line — which is
|
|
14086
14124
|
// exactly how #304's failure went unnoticed in the first place.
|
|
14087
14125
|
deferredCollector = [];
|
|
14126
|
+
let reviewPrHandled = null; // #584: the #350 review PR, already closed (or warned about) above
|
|
14088
14127
|
// #350: the approved PR is spent — its work landed by squash, which the forge cannot see as a merge.
|
|
14089
14128
|
if (coreReview.verdict === 'approved' && coreReview.pr && gh) {
|
|
14090
14129
|
const closed = git.ghPrClose(repoAbs, coreReview.pr.number, `Landed on \`${target}\` as ${sha} by \`colab ship\` (#350), approved by ${coreReview.approval.by}.`);
|
|
14091
14130
|
if (closed.ok) print(` closed PR #${coreReview.pr.number} (landed as ${sha})`);
|
|
14092
14131
|
else warnDeferred(`could not close PR #${coreReview.pr.number} (${(closed.stderr || '').split('\n')[0]}) — it landed as ${sha}; close it by hand`);
|
|
14132
|
+
reviewPrHandled = coreReview.pr.number; // #584: either way the tail's landed-PR close must not touch it again
|
|
14093
14133
|
}
|
|
14094
14134
|
// Only when the target IS the shared checkout. `ephemeralTarget === false` means
|
|
14095
14135
|
// `targetDir === repoAbs` (see #234's note above); a declared integration line merged in a
|
|
@@ -14155,6 +14195,7 @@ function cmdShip(argv) {
|
|
|
14155
14195
|
// window itself now OPENS at the push (e2, #304), not here: post-ship's warnings belong in the
|
|
14156
14196
|
// same block, and re-assigning the collector here would silently discard them.
|
|
14157
14197
|
shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
|
|
14198
|
+
skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
|
|
14158
14199
|
evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
|
|
14159
14200
|
|
|
14160
14201
|
print('');
|
|
@@ -14174,6 +14215,38 @@ function cmdShip(argv) {
|
|
|
14174
14215
|
}
|
|
14175
14216
|
|
|
14176
14217
|
|
|
14218
|
+
/**
|
|
14219
|
+
* #584: close every open PR whose head is the branch this ship just landed — the PR a person or an
|
|
14220
|
+
* automation opened only to obtain branch CI. The forge never sees a squash as a merge of that PR, so
|
|
14221
|
+
* without this it stays open forever, reading as unmerged work. Only a PR whose head commit is the
|
|
14222
|
+
* landed tip (or an ancestor of it) is closed; one carrying commits that did not land is kept and
|
|
14223
|
+
* reported. Best-effort throughout: every failure defers a warning, none fails the ship.
|
|
14224
|
+
*/
|
|
14225
|
+
function shipCloseLandedPrs(repoAbs, sess, { target, sha, issues, skip = [] }) {
|
|
14226
|
+
const remoteName = git.remoteInfo(repoAbs).name || 'origin';
|
|
14227
|
+
const tipOf = (ref) => { const r = git.git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoAbs); return r.ok ? r.stdout.trim() : null; };
|
|
14228
|
+
const tip = tipOf(`refs/heads/${sess.branch}`) || tipOf(`refs/remotes/${remoteName}/${sess.branch}`);
|
|
14229
|
+
const headLanded = (oid) => {
|
|
14230
|
+
if (!tip) return false;
|
|
14231
|
+
if (oid === tip) return true;
|
|
14232
|
+
return git.git(['merge-base', '--is-ancestor', oid, tip], repoAbs).ok;
|
|
14233
|
+
};
|
|
14234
|
+
const res = landedPrs.closeLandedPrs({
|
|
14235
|
+
prs: git.ghOpenPrsForBranch(repoAbs, sess.branch),
|
|
14236
|
+
headLanded,
|
|
14237
|
+
close: (n, comment) => git.ghPrClose(repoAbs, n, comment),
|
|
14238
|
+
comment: landedPrs.landedPrComment({ target, sha, issues }),
|
|
14239
|
+
skip,
|
|
14240
|
+
});
|
|
14241
|
+
if (res.listError) {
|
|
14242
|
+
warnDeferred(`could not list open PRs for ${sess.branch} (${res.listError}) — any PR opened for its CI is still open; close it by hand (it landed as ${sha})`);
|
|
14243
|
+
return;
|
|
14244
|
+
}
|
|
14245
|
+
for (const n of res.closed) print(` closed PR #${n} — its branch ${sess.branch} landed as ${sha} (#584)`);
|
|
14246
|
+
for (const f of res.failed) warnDeferred(`could not close PR #${f.number} (${f.error}) — ${sess.branch} landed as ${sha}; close it by hand`);
|
|
14247
|
+
for (const k of res.kept) warnDeferred(`kept PR #${k.number} open: ${k.reason} (${sess.branch} landed as ${sha}) — it carries work that did not ship`);
|
|
14248
|
+
}
|
|
14249
|
+
|
|
14177
14250
|
/**
|
|
14178
14251
|
* The post-merge tail every landed branch gets — cmdShip's B3 through i2, moved here unchanged (#373)
|
|
14179
14252
|
* so a batch member gets exactly the same steps in the same order: worktree teardown (B3), the claims
|
|
@@ -14182,7 +14255,13 @@ function cmdShip(argv) {
|
|
|
14182
14255
|
* addition — '' on a serial ship (so its comment is byte-identical), the combined-run clause for a
|
|
14183
14256
|
* batch member.
|
|
14184
14257
|
*/
|
|
14185
|
-
function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '' }) {
|
|
14258
|
+
function shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts, evidenceExtra = '', skipPrs = [] }) {
|
|
14259
|
+
// #584: the CI-trigger PR(s) this squash left behind. FIRST, while the branch ref still resolves —
|
|
14260
|
+
// B3 below may delete it, and "did the PR's head land?" is answered against that tip.
|
|
14261
|
+
if (gh && sess.branch) {
|
|
14262
|
+
try { shipCloseLandedPrs(repoAbs, sess, { target, sha, issues: closeIssues, skip: skipPrs }); }
|
|
14263
|
+
catch (e) { warnDeferred(`landed-PR close for ${sess.branch} failed (${e.message}) — the ship landed as ${sha}; close any PR for it by hand`); }
|
|
14264
|
+
}
|
|
14186
14265
|
const worktreeKept = !!(sess.name && opts.keepWorktree);
|
|
14187
14266
|
if (sess.name && !opts.keepWorktree) {
|
|
14188
14267
|
print(`B3: removing worktree ${sess.name} …`);
|
package/tools/lib/git.js
CHANGED
|
@@ -691,6 +691,30 @@ function ghPrForBranch(repo, branch) {
|
|
|
691
691
|
} catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
|
|
692
692
|
}
|
|
693
693
|
|
|
694
|
+
/**
|
|
695
|
+
* #584: EVERY open pull request whose head is `branch` — not just the first, as ghPrForBranch
|
|
696
|
+
* returns — so `colab ship` can close each CI-trigger PR its squash left behind. `{ prs }` on
|
|
697
|
+
* success (possibly empty), `{ error }` when the read failed; never conflate the two.
|
|
698
|
+
*/
|
|
699
|
+
function ghOpenPrsForBranch(repo, branch) {
|
|
700
|
+
const r = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
|
|
701
|
+
if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
|
|
702
|
+
try {
|
|
703
|
+
const list = JSON.parse(r.stdout || '[]');
|
|
704
|
+
return { prs: Array.isArray(list) ? list : [] };
|
|
705
|
+
} catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
|
|
706
|
+
}
|
|
707
|
+
|
|
708
|
+
/** #584: every open pull request in the repo, for `colab doctor --sync`'s landed-PR listing. */
|
|
709
|
+
function ghOpenPrs(repo) {
|
|
710
|
+
const r = gh(['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,url,headRefOid,headRefName'], { cwd: repo });
|
|
711
|
+
if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
|
|
712
|
+
try {
|
|
713
|
+
const list = JSON.parse(r.stdout || '[]');
|
|
714
|
+
return { prs: Array.isArray(list) ? list : [] };
|
|
715
|
+
} catch (_) { return { error: 'gh pr list returned unparseable JSON' }; }
|
|
716
|
+
}
|
|
717
|
+
|
|
694
718
|
/**
|
|
695
719
|
* #367: the forge's visibility for this repo — "PUBLIC" | "PRIVATE" | "INTERNAL" — or null when it
|
|
696
720
|
* could not be read (no gh, no GitHub remote, offline). Null is "could not read", never "private":
|
|
@@ -1401,5 +1425,5 @@ module.exports = {
|
|
|
1401
1425
|
ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
|
|
1402
1426
|
ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
|
|
1403
1427
|
ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
|
|
1404
|
-
ghPrForBranch, ghPrCreate, ghPrClose, ghRepoVisibility,
|
|
1428
|
+
ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
|
|
1405
1429
|
};
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #584: a pull request opened only to obtain branch CI stays open forever once `colab ship`
|
|
4
|
+
* squash-lands its branch — the squash is a NEW commit, so the forge never sees the PR's head land,
|
|
5
|
+
* and nothing else closes it. Measured 2026-10-10: five such PRs open on two repos, all landed, the
|
|
6
|
+
* oldest 15 days old, each reading as unmerged work waiting for review.
|
|
7
|
+
*
|
|
8
|
+
* Pure rules only — tools/colab owns the gh calls. Two rules:
|
|
9
|
+
*
|
|
10
|
+
* 1. Close a PR only when its head commit LANDED: the PR head is the landed branch tip, or an
|
|
11
|
+
* ancestor of it. A PR head carrying commits the ship did NOT include (pushed to the remote
|
|
12
|
+
* branch after the local tip was cut, or from another machine) is KEPT, with a warning — closing
|
|
13
|
+
* it would hide work that is not on trunk.
|
|
14
|
+
* 2. Best-effort. A failed list or close is a warning, never a failed ship: the merge already landed
|
|
15
|
+
* and is pushed, so a non-zero exit here would read as "ship failed" and invite a re-merge.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** The comment a closed PR carries — the same shape as #350's close: where it landed, and why. */
|
|
19
|
+
function landedPrComment({ target, sha, issues }) {
|
|
20
|
+
const nums = (issues || []).map((n) => `#${n}`).join(' ');
|
|
21
|
+
return `Landed on \`${target}\` as ${sha} by \`colab ship\`${nums ? ` (${nums})` : ''}. ` +
|
|
22
|
+
'The branch was squash-merged, which the forge cannot see as a merge of this PR, so ship closes it (#584).';
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Decide and act on every open PR whose head is the landed branch.
|
|
27
|
+
*
|
|
28
|
+
* prs — the open PRs listed for the branch, as git.ghOpenPrsForBranch returns them:
|
|
29
|
+
* { prs: [{ number, headRefOid, url }] } or { error }
|
|
30
|
+
* headLanded — (oid) => true when that commit is in what landed (tip or ancestor); false otherwise
|
|
31
|
+
* close — (number, comment) => { ok, stderr }
|
|
32
|
+
* comment — the closing comment (landedPrComment)
|
|
33
|
+
* skip — PR numbers already handled by another path (#350's approved review PR)
|
|
34
|
+
*
|
|
35
|
+
* Returns { closed: [n], kept: [{ number, reason }], failed: [{ number, error }], listError }.
|
|
36
|
+
*/
|
|
37
|
+
function closeLandedPrs({ prs, headLanded, close, comment, skip = [] }) {
|
|
38
|
+
const out = { closed: [], kept: [], failed: [], listError: null };
|
|
39
|
+
if (!prs || prs.error || !Array.isArray(prs.prs)) { out.listError = (prs && prs.error) || 'could not list open PRs'; return out; }
|
|
40
|
+
const skipSet = new Set(skip.map(Number));
|
|
41
|
+
for (const pr of prs.prs) {
|
|
42
|
+
const number = Number(pr.number);
|
|
43
|
+
if (!Number.isFinite(number) || skipSet.has(number)) continue;
|
|
44
|
+
let landed = false;
|
|
45
|
+
try { landed = !!(pr.headRefOid && headLanded(pr.headRefOid)); } catch (_) { landed = false; }
|
|
46
|
+
if (!landed) {
|
|
47
|
+
out.kept.push({ number, reason: `its head ${String(pr.headRefOid || '?').slice(0, 12)} is not in what landed` });
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
let r;
|
|
51
|
+
try { r = close(number, comment); } catch (e) { r = { ok: false, stderr: e.message }; }
|
|
52
|
+
if (r && r.ok) out.closed.push(number);
|
|
53
|
+
else out.failed.push({ number, error: ((r && r.stderr) || 'gh pr close failed').split('\n')[0] });
|
|
54
|
+
}
|
|
55
|
+
return out;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
module.exports = { landedPrComment, closeLandedPrs };
|