@futurelastic/colab-handbook 1.14.0-rc.8 → 1.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -0
- package/README.vi.md +19 -0
- package/audit/audit.mjs +77 -16
- package/package.json +1 -1
- package/templates/README.md +64 -2
- package/templates/ci-laravel-heavy.yml +370 -0
- package/templates/ci-laravel.yml +27 -218
- package/templates/ci-node-heavy.yml +293 -0
- package/templates/ci-node.yml +23 -202
- package/templates/ci-python-heavy.yml +302 -0
- package/templates/ci-python.yml +26 -207
- package/templates/release-auto.yml +70 -1
- package/templates/release-tag.yml +20 -3
- package/tools/colab +475 -38
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/disposition.js +27 -10
- package/tools/lib/docs-only.js +76 -21
- package/tools/lib/git.js +6 -1
- package/tools/lib/instruction-file.js +26 -0
- package/tools/lib/instruction-gate.js +31 -2
- package/tools/lib/integration-profile.js +161 -0
- package/tools/lib/release-cut.js +10 -0
- package/tools/lib/release-finalize.js +9 -2
- package/tools/lib/secret-scan.js +132 -0
- package/tools/lib/ship-batch.js +71 -2
- package/tools/lib/stamp.js +16 -1
package/tools/colab
CHANGED
|
@@ -70,6 +70,8 @@ const shipBatch = require('./lib/ship-batch');
|
|
|
70
70
|
const batchStats = require('./lib/batch-stats');
|
|
71
71
|
const conflictMarkers = require('./lib/conflict-markers');
|
|
72
72
|
const docsOnly = require('./lib/docs-only');
|
|
73
|
+
const integrationProfile = require('./lib/integration-profile');
|
|
74
|
+
const secretScan = require('./lib/secret-scan'); // #606
|
|
73
75
|
const configSet = require('./lib/config-set'); // #561
|
|
74
76
|
const cureDiff = require('./lib/cure-diff');
|
|
75
77
|
const codeowners = require('./lib/codeowners');
|
|
@@ -87,6 +89,7 @@ const localAdopt = require('./lib/local-adopt'); // #393
|
|
|
87
89
|
const ownerBranch = require('./lib/owner-branch'); // #394
|
|
88
90
|
const humanDoor = require('./lib/ship-human-door'); // #525
|
|
89
91
|
const instructionGate = require('./lib/instruction-gate'); // #588
|
|
92
|
+
const instructionFile = require('./lib/instruction-file'); // #602
|
|
90
93
|
const {
|
|
91
94
|
HOST, UserError, normIssueNum, issueTag, claimKey, today, nowISO, hoursSince, humanAge,
|
|
92
95
|
parseArgs, table, shortRepo,
|
|
@@ -1708,8 +1711,17 @@ function cmdReleaseCut(argv) {
|
|
|
1708
1711
|
}
|
|
1709
1712
|
}
|
|
1710
1713
|
|
|
1714
|
+
// #610: on a final route the heavy lane must be green at this sha. Under --auto (the release
|
|
1715
|
+
// workflow) a missing run is started here, once, and the run no-ops until it is green.
|
|
1716
|
+
let heavy = null;
|
|
1717
|
+
if (fast || library) {
|
|
1718
|
+
const lane = heavyLaneAt(repoAbs, doc, sha);
|
|
1719
|
+
heavy = integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `main@${shortSha(sha)}`, ref: 'main' });
|
|
1720
|
+
if (lane.present && lane.verdict.state === 'none' && opts.auto && !opts.dry) dispatchHeavyLane(repoAbs, lane.file, 'main', sha);
|
|
1721
|
+
}
|
|
1722
|
+
|
|
1711
1723
|
const verdict = releaseCut.decide({
|
|
1712
|
-
policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto,
|
|
1724
|
+
policy, triggers, lastFinal, suggestion, tags, tagsAtSha, ci, suite, schema, switches, manifests, ancestry, auto, heavy,
|
|
1713
1725
|
override: opts.bump ? { bump: opts.bump, reason: opts.reason } : null,
|
|
1714
1726
|
finalGrant: fastFacts.finalGrant, holds: fastFacts.holds, migrations: fastFacts.migrations, migration: libraryMigration,
|
|
1715
1727
|
trackingIssue: fastFacts.tracking ? fastFacts.tracking.number : null,
|
|
@@ -1994,6 +2006,16 @@ function readRegressionEdges(repoAbs, num) {
|
|
|
1994
2006
|
}
|
|
1995
2007
|
}
|
|
1996
2008
|
|
|
2009
|
+
/**
|
|
2010
|
+
* #610: the heavy lane at a release candidate, as release-finalize.js decide()'s `heavy` fact. Read
|
|
2011
|
+
* the same way ship's gated landing reads it (heavyLaneAt). Inside the release workflow the heavy
|
|
2012
|
+
* lane is a separate workflow, never the one running, so #425's own-workflow filter does not apply.
|
|
2013
|
+
*/
|
|
2014
|
+
function releaseHeavyFact(repoAbs, doc, cand) {
|
|
2015
|
+
const lane = heavyLaneAt(repoAbs, doc, cand.sha);
|
|
2016
|
+
return integrationProfile.releaseHeavyCondition({ present: lane.present, file: lane.file, verdict: lane.verdict, at: `${cand.tag}@${shortSha(cand.sha)}`, ref: cand.tag });
|
|
2017
|
+
}
|
|
2018
|
+
|
|
1997
2019
|
function cmdReleaseFinalize(argv) {
|
|
1998
2020
|
const opts = parseArgs(argv, {
|
|
1999
2021
|
values: { '--repo': 'repo', '--tag': 'tag', '--answered-by': 'answeredBy' },
|
|
@@ -2136,6 +2158,7 @@ function cmdReleaseFinalize(argv) {
|
|
|
2136
2158
|
const verdict = releaseFinalize.decide({
|
|
2137
2159
|
policy, selection: sel, tracking, supersededHeld, period, trunk, regressions,
|
|
2138
2160
|
ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
|
|
2161
|
+
heavy: releaseHeavyFact(repoAbs, doc, cand), // #610
|
|
2139
2162
|
manifests, ancestry, tags: tagNames, finalGrant, migrations,
|
|
2140
2163
|
human: { bar: humanBar, answeredBy: opts.answeredBy || null },
|
|
2141
2164
|
});
|
|
@@ -9315,6 +9338,13 @@ async function cmdAdopt(argv) {
|
|
|
9315
9338
|
: `detected (the repo's default branch, ${nowDate})`;
|
|
9316
9339
|
entries.push({ key: 'trunk', value: extra.trunk, comment: `# trunk: ${trunkNote}` });
|
|
9317
9340
|
}
|
|
9341
|
+
// #602: on a fork, the instruction-file check cannot see the `upstream` remote in CI — so the
|
|
9342
|
+
// fork verdict above (adoptDetectFork, the one fork test) is recorded as the key CI reads.
|
|
9343
|
+
// Detected, never asked, like trunk and stack; never written over an existing declaration.
|
|
9344
|
+
if (extra.fork && !(instructionFile.INSTRUCTION_FILES_KEY in cfg)) {
|
|
9345
|
+
entries.push({ key: instructionFile.INSTRUCTION_FILES_KEY, value: 'upstream',
|
|
9346
|
+
comment: `# instruction-files: detected — a fork (${extra.fork.source === 'flag' ? '--fork' : `remote "${extra.fork.remote}"`}, ${nowDate}); CLAUDE.md/AGENTS.md are the upstream's, so the instruction-file check leaves them unjudged (CONVENTIONS.md §9, #602)` });
|
|
9347
|
+
}
|
|
9318
9348
|
if (!('stack' in cfg)) {
|
|
9319
9349
|
if (opts.stack !== undefined) {
|
|
9320
9350
|
const stackNote = stackAnsweredInteractively
|
|
@@ -9972,7 +10002,9 @@ What this command will NOT do, by design:
|
|
|
9972
10002
|
• It skips the handbook repo itself.
|
|
9973
10003
|
|
|
9974
10004
|
Exit code: 0 when nothing is behind, 1 when anything is behind — the frozen copy included,
|
|
9975
|
-
since a stale CLI is as much a thing to act on as a stale workflow
|
|
10005
|
+
since a stale CLI is as much a thing to act on as a stale workflow — except a CI template
|
|
10006
|
+
(\`ci-*\`) copy: CI templates are guidance, so one behind is reported but never exits 1 (#607).
|
|
10007
|
+
2 on usage error.
|
|
9976
10008
|
`;
|
|
9977
10009
|
|
|
9978
10010
|
function cmdUpdate(argv) {
|
|
@@ -10047,7 +10079,11 @@ function cmdUpdate(argv) {
|
|
|
10047
10079
|
skippedRepos: repos.filter((r) => !r.artifacts.length).length,
|
|
10048
10080
|
refreshable: all.filter((a) => a.state === 'behind' && a.applicable && !a.written).length,
|
|
10049
10081
|
written: written.length,
|
|
10082
|
+
// #607: a CI template is guidance — a `ci-*` copy behind its template is a suggestion, counted in
|
|
10083
|
+
// `behind` (it can still be refreshed) but never what makes this command exit 1.
|
|
10084
|
+
suggestions: all.filter((a) => a.state === 'behind' && /^ci-/.test(a.template || '')).length,
|
|
10050
10085
|
};
|
|
10086
|
+
const actionable = summary.behind - summary.suggestions;
|
|
10051
10087
|
|
|
10052
10088
|
if (opts.json) {
|
|
10053
10089
|
print(JSON.stringify({
|
|
@@ -10057,7 +10093,7 @@ function cmdUpdate(argv) {
|
|
|
10057
10093
|
applied: !!opts.apply,
|
|
10058
10094
|
repos, written, failed, frozen, summary,
|
|
10059
10095
|
}, null, 2));
|
|
10060
|
-
return
|
|
10096
|
+
return actionable > 0 || frozen.state === 'behind' ? 1 : 0;
|
|
10061
10097
|
}
|
|
10062
10098
|
|
|
10063
10099
|
// --- report ------------------------------------------------------------
|
|
@@ -10100,6 +10136,9 @@ function cmdUpdate(argv) {
|
|
|
10100
10136
|
`${summary.current} current, ${summary.behind} behind, ${summary.diverged} diverged, ` +
|
|
10101
10137
|
`${summary.unstamped} unstamped, ${summary.na} n-a` +
|
|
10102
10138
|
(summary.unrelated ? `, ${summary.unrelated} unrelated (name clash only — not ours).` : '.'));
|
|
10139
|
+
if (summary.suggestions) {
|
|
10140
|
+
print(`${summary.suggestions} of the behind copies are CI templates — guidance, adopt what helps; they never fail this command (#607).`);
|
|
10141
|
+
}
|
|
10103
10142
|
if (summary.skippedRepos) {
|
|
10104
10143
|
print(`${summary.skippedRepos} repo(s) had nothing to assess (nothing adopted, an audit-only slug, a missing path, or the handbook itself).`);
|
|
10105
10144
|
}
|
|
@@ -10134,7 +10173,7 @@ function cmdUpdate(argv) {
|
|
|
10134
10173
|
print(' --apply never touches it: it is the toolchain your always-on services are running.');
|
|
10135
10174
|
}
|
|
10136
10175
|
|
|
10137
|
-
return
|
|
10176
|
+
return actionable > 0 || frozen.state === 'behind' ? 1 : 0;
|
|
10138
10177
|
}
|
|
10139
10178
|
|
|
10140
10179
|
// ---------------------------------------------------------------------------
|
|
@@ -10484,7 +10523,12 @@ function migDetail(migrations, grants, target, branch, ctx) {
|
|
|
10484
10523
|
* from its base. An empty result is now left empty; the caller decides what to say about it
|
|
10485
10524
|
* (buildSquashMessage below), rather than this layer inventing a commit to hide it.
|
|
10486
10525
|
*/
|
|
10487
|
-
function branchCommits(mainRoot, trunk,
|
|
10526
|
+
function branchCommits(mainRoot, trunk, branchName) {
|
|
10527
|
+
// #603: read the branch through the ref it resolves to. A hand-off branch (or any --branch with no
|
|
10528
|
+
// local ref) is remote-only on the lander, and a bare name does not DWIM to refs/remotes/<remote>/
|
|
10529
|
+
// — the log failed, the list came back empty, and the squash subject read "(none …)" on a branch
|
|
10530
|
+
// that has commits. shipRefFor is local || remote || the name itself, so a sha passes unchanged.
|
|
10531
|
+
const branch = shipRefFor(mainRoot, branchName);
|
|
10488
10532
|
const mb = git.git(['merge-base', trunk, branch], mainRoot);
|
|
10489
10533
|
const base = mb.ok && mb.stdout ? mb.stdout : trunk;
|
|
10490
10534
|
const logShas = git.git(['log', '--first-parent', `${base}..${branch}`, '--no-merges', '--format=%H'], mainRoot);
|
|
@@ -10508,7 +10552,7 @@ function commitFiles(mainRoot, sha) {
|
|
|
10508
10552
|
|
|
10509
10553
|
/** Files the whole branch changed against its base — the denominator for the same signal. */
|
|
10510
10554
|
function branchChangedFiles(mainRoot, base, branch) {
|
|
10511
|
-
const r = git.git(['diff', '--name-only', `${base}...${branch}`], mainRoot);
|
|
10555
|
+
const r = git.git(['diff', '--name-only', `${base}...${shipRefFor(mainRoot, branch)}`], mainRoot); // #603: same remote-only gap
|
|
10512
10556
|
return r.ok ? r.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : [];
|
|
10513
10557
|
}
|
|
10514
10558
|
|
|
@@ -10582,7 +10626,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
|
|
|
10582
10626
|
}
|
|
10583
10627
|
|
|
10584
10628
|
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 <comment-url>] [--answered-by <name>] [--session <id>] [--session-name <s>] [--dry] [--json]
|
|
10585
|
-
colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
|
|
10629
|
+
colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--onto ship-batch/<sha7>] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry [--json]]
|
|
10586
10630
|
|
|
10587
10631
|
The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
|
|
10588
10632
|
CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
|
|
@@ -10627,6 +10671,10 @@ Sequence (each step gated; any failure aborts before the push — the target is
|
|
|
10627
10671
|
and worktree untouched. Re-run the same command once an account other than the
|
|
10628
10672
|
author approved the branch's CURRENT head: it lands by the ordinary squash below
|
|
10629
10673
|
and closes the PR. Accounts sharing one login cannot approve each other.
|
|
10674
|
+
b5. heavy lane (#610) only with integration-profile: gated, never for a docs-only change:
|
|
10675
|
+
the heavy workflow (heavy-workflow:, default ci-heavy.yml) green at the
|
|
10676
|
+
branch's remote head. None yet → a real ship dispatches it and PAUSES —
|
|
10677
|
+
"⏸ HEAVY-PENDING", exit 3, nothing merged; running → the same pause; red → ✗.
|
|
10630
10678
|
c. B0 sync merge the target INTO the branch; non-generated conflict → abort (human merge);
|
|
10631
10679
|
generated-only conflict → repo's .colab/hooks/pre-ship regenerates, else abort
|
|
10632
10680
|
d. B1 squash re-check CI green, then squash-merge branch → target (Closes every claimed issue,
|
|
@@ -10871,7 +10919,20 @@ The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref
|
|
|
10871
10919
|
combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
|
|
10872
10920
|
\`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
|
|
10873
10921
|
'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
|
|
10874
|
-
A red batch, or one with no run / not landed past that grace, holds nothing.
|
|
10922
|
+
A red batch, or one with no run / not landed past that grace, holds nothing. A TRUNK RED: cure is never held.
|
|
10923
|
+
SPECULATIVE CHAIN (#605): --onto ship-batch/<sha7> builds the batch on that in-flight batch's HEAD
|
|
10924
|
+
instead of trunk's tip, named ship-batch/<parent-head-sha7> (one batch per base still holds). The chain
|
|
10925
|
+
is read from ls-remote alone: a ref's parent is the ref whose head its name starts with, and it is kept
|
|
10926
|
+
while that chain ends at a batch on trunk's tip (at most ${shipBatch.MAX_CHAIN_DEPTH} deep); a ref whose parent is gone or rebuilt,
|
|
10927
|
+
or whose root trunk moved past, is deleted by the next --batch call (its run cancelled if still going).
|
|
10928
|
+
- refused (1): the named ref has no combined run in flight or green, is not rooted at trunk's tip,
|
|
10929
|
+
or is already ${shipBatch.MAX_CHAIN_DEPTH} deep; a member the chain below already carries does not join (✗, the rest go on);
|
|
10930
|
+
- lands in order: green and its parent not landed yet → ⏸ BATCH-CHAINED (exit 3); once trunk's tip IS
|
|
10931
|
+
the parent's head, the same command (with or without --onto) lands it — no second build, no second run;
|
|
10932
|
+
- declined (4): the parent is red, gone, or trunk moved some other way — the child is deleted, → SERIAL.
|
|
10933
|
+
Every ref of a chain rooted at trunk's tip holds the lane, exactly as one batch does.
|
|
10934
|
+
--dry --json: one JSON document on stdout ({ batch: { ref, parentRef, rootSha, base, depth, step, exit,
|
|
10935
|
+
members: [{ branch, sha, eligible, inBatch, why }] } }), the prose on stderr.
|
|
10875
10936
|
A member that conflicts with the members already in is dropped to the next batch; the rest go on —
|
|
10876
10937
|
unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
|
|
10877
10938
|
regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
|
|
@@ -11444,6 +11505,13 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
11444
11505
|
via = `${trunk} (by commit — the branch-filtered read was empty)`;
|
|
11445
11506
|
}
|
|
11446
11507
|
}
|
|
11508
|
+
// #606: trunk's tip has no FINISHED run and is a docs-only commit (an adopter's CI `paths-ignore`s
|
|
11509
|
+
// docs, or the run is simply not done) — docs change no code, so trunk's CI is the verdict of the
|
|
11510
|
+
// newest trunk commit that is NOT docs-only. A finished red run at the tip is never overridden.
|
|
11511
|
+
if (target === trunk && (run.status === 'none' || run.status !== 'completed')) {
|
|
11512
|
+
const door = docsOnlyTipDoor(repoAbs, trunk, run.sha, readOpts);
|
|
11513
|
+
if (door) return door;
|
|
11514
|
+
}
|
|
11447
11515
|
const at = `${via}@${shortSha(run.sha)}`;
|
|
11448
11516
|
let verdict = classifyCiRun(repoAbs, run, at);
|
|
11449
11517
|
// #413: still no run anywhere at a trunk sha committed minutes ago — the run may not exist YET
|
|
@@ -11622,6 +11690,75 @@ function baseCiAdvisory(repoAbs, gh, base, branch) {
|
|
|
11622
11690
|
};
|
|
11623
11691
|
}
|
|
11624
11692
|
|
|
11693
|
+
/**
|
|
11694
|
+
* #606: trunk's tip is docs-only and has no finished run — read trunk CI at the newest first-parent
|
|
11695
|
+
* ancestor that is NOT docs-only (tools/lib/docs-only.js commitChanges, narrowed by trunk's
|
|
11696
|
+
* `ci-docs-skip`). Returns a readCiVerdict result, or null when the door does not apply: the repo
|
|
11697
|
+
* declared `ci-docs-skip: off` (or an invalid value), the tip is not local or not docs-only, no code
|
|
11698
|
+
* commit within DOCS_TIP_WALK commits, or that commit's runs are unreadable. A null keeps every
|
|
11699
|
+
* existing reading of the tip unchanged — the door only ever answers for a docs-only tip.
|
|
11700
|
+
*/
|
|
11701
|
+
const DOCS_TIP_WALK = 50;
|
|
11702
|
+
function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
|
|
11703
|
+
if (!tipSha) return null;
|
|
11704
|
+
const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
|
|
11705
|
+
if (!setting.on) return null;
|
|
11706
|
+
const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
|
|
11707
|
+
if (!list.ok) return null;
|
|
11708
|
+
let skipped = 0;
|
|
11709
|
+
let code = null;
|
|
11710
|
+
for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
|
|
11711
|
+
const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude });
|
|
11712
|
+
if (!c.docsOnly) { code = sha; break; }
|
|
11713
|
+
skipped++;
|
|
11714
|
+
}
|
|
11715
|
+
if (!code || skipped === 0) return null;
|
|
11716
|
+
const run = git.ghRunForCommitAnyRef(repoAbs, code, undefined, readOpts);
|
|
11717
|
+
if (!run) return null;
|
|
11718
|
+
const at = `${trunk}@${shortSha(code)}`;
|
|
11719
|
+
const v = classifyCiRun(repoAbs, run, at);
|
|
11720
|
+
const note = `docs-only tip (#606): ${trunk}@${shortSha(tipSha)}${skipped > 1 ? ` and ${skipped - 1} commit(s) below it` : ''} change only documentation, so trunk CI is read at the newest code commit — `;
|
|
11721
|
+
const verdict = { ...v, detail: note + v.detail, docsOnlyTip: { tip: tipSha, read: code, skipped } };
|
|
11722
|
+
return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
|
|
11723
|
+
}
|
|
11724
|
+
|
|
11725
|
+
/**
|
|
11726
|
+
* #606: is this branch DOCS-ONLY for CI purposes — so `colab ship` lands it without waiting for CI?
|
|
11727
|
+
* tools/lib/docs-only.js shipDocsOnly (the #345 rule, narrowed by `ci-docs-skip`, off by `off`),
|
|
11728
|
+
* measured on the ref ship would land. When it applies, the secret check runs too
|
|
11729
|
+
* (tools/lib/secret-scan.js) — the suite's own secret scan may never see this change.
|
|
11730
|
+
* Returns `{ applies, files, reason, scan }`; `scan` only when `applies`.
|
|
11731
|
+
*/
|
|
11732
|
+
function shipDocsOnlyCi(repoAbs, doc, target, branch) {
|
|
11733
|
+
const ref = shipRefFor(repoAbs, branch);
|
|
11734
|
+
const d = docsOnly.shipDocsOnly(git, repoAbs, target, ref, doc);
|
|
11735
|
+
if (!d.docsOnly) return { applies: false, files: d.files, reason: d.reason, scan: null };
|
|
11736
|
+
return { applies: true, files: d.files, reason: d.reason, scan: secretScan.scanBranch(git, repoAbs, target, ref) };
|
|
11737
|
+
}
|
|
11738
|
+
|
|
11739
|
+
/** #606: the 🚢 comment's evidence clause for a docs-only ship — files, and the trunk sha CI was read at. */
|
|
11740
|
+
function docsOnlyEvidence(dc, ci) {
|
|
11741
|
+
if (!dc || !dc.applies) return '';
|
|
11742
|
+
const tip = ci && ci.docsOnlyTip;
|
|
11743
|
+
const read = tip ? ` — trunk CI read at ${shortSha(tip.read)}, the newest code commit below the docs-only tip ${shortSha(tip.tip)}` : ' — trunk CI read at its tip';
|
|
11744
|
+
return ` — docs-only: CI not required (${dc.files} files)${read}; secret check clean`;
|
|
11745
|
+
}
|
|
11746
|
+
|
|
11747
|
+
/**
|
|
11748
|
+
* #606: the branch-run row for a docs-only branch, in place of #395's stale-base row. CI is not
|
|
11749
|
+
* required, so no run, a run in flight, or a run measured on an older base is fine — but a run that
|
|
11750
|
+
* EXISTS at the pushed head and finished red still refuses: ship never overrides a red verdict.
|
|
11751
|
+
*/
|
|
11752
|
+
function docsOnlyBranchRow(dc, stale) {
|
|
11753
|
+
const run = stale && stale.run;
|
|
11754
|
+
const red = !!run && run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
|
|
11755
|
+
if (red) {
|
|
11756
|
+
return { ok: false, class: HUMAN_GATED,
|
|
11757
|
+
detail: `docs-only (${dc.files} files), but the branch's own run at ${shortSha(stale.headSha)} finished ${run.conclusion || 'red'} — CI is not required here, and a red verdict is still never overridden (#606)` };
|
|
11758
|
+
}
|
|
11759
|
+
return { ok: true, class: null, detail: `docs-only: CI not required (${dc.files} files) — the branch's own run is not awaited (#606; ${stale ? stale.verdict : 'unread'})` };
|
|
11760
|
+
}
|
|
11761
|
+
|
|
11625
11762
|
/**
|
|
11626
11763
|
* #395: does the branch's CI verdict cover the CURRENT `base`? A PRECONDITION, unlike
|
|
11627
11764
|
* `baseCiAdvisory` above: serial ship syncs the base in locally (B0) and squashes without the synced
|
|
@@ -11650,7 +11787,8 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
|
|
|
11650
11787
|
if (contains === false && git.git(['diff', '--quiet', `${baseTip}...${headSha}`], repoAbs).code === 0) contains = 'no-change';
|
|
11651
11788
|
}
|
|
11652
11789
|
if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
|
|
11653
|
-
|
|
11790
|
+
// #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
|
|
11791
|
+
return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh }), run, headSha };
|
|
11654
11792
|
}
|
|
11655
11793
|
|
|
11656
11794
|
/**
|
|
@@ -12455,13 +12593,28 @@ function cmdShipDryJson(opts) {
|
|
|
12455
12593
|
// read is exempt: the batch grades the COMBINED head (trunk + every member), which is exactly the
|
|
12456
12594
|
// re-run this row demands of a serial land, so a member behind trunk is the ordinary case there.
|
|
12457
12595
|
const staleJson = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
|
|
12458
|
-
|
|
12596
|
+
// #606: a docs-only branch needs no CI of its own — its row replaces the stale-base one, and the
|
|
12597
|
+
// secret check stands in for the suite's secret scan. Same producers as the prose path.
|
|
12598
|
+
const docsCiJson = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
|
|
12599
|
+
if (docsCiJson.applies) {
|
|
12600
|
+
const row = docsOnlyBranchRow(docsCiJson, staleJson);
|
|
12601
|
+
checks.push({ name: 'branch CI (docs-only, #606)', ok: row.ok, class: row.class, verdict: staleJson.verdict, detail: row.detail });
|
|
12602
|
+
checks.push({ name: 'docs-only secret check (#606)', ok: docsCiJson.scan.ok, class: docsCiJson.scan.ok ? null : HUMAN_GATED, detail: docsCiJson.scan.reason });
|
|
12603
|
+
} else if (opts._batchMember) {
|
|
12459
12604
|
checks.push({ name: 'branch run contains current base (#395)', ok: true, class: null, verdict: staleJson.verdict,
|
|
12460
12605
|
detail: `batch member — the combined run grades it (${staleJson.detail})` });
|
|
12461
12606
|
} else {
|
|
12462
12607
|
checks.push({ name: 'branch run contains current base (#395)', ok: staleJson.ok,
|
|
12463
12608
|
class: staleJson.ok ? null : SELF_CLEARING, verdict: staleJson.verdict, detail: staleJson.detail });
|
|
12464
12609
|
}
|
|
12610
|
+
// #610: the same gated heavy-lane read as the prose path. A missing or running heavy run clears on
|
|
12611
|
+
// its own (a real ship dispatches it); a red, or no heavy lane at all, needs a person.
|
|
12612
|
+
const heavyJson = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCiJson.applies, batchMember: !!opts._batchMember });
|
|
12613
|
+
if (heavyJson) {
|
|
12614
|
+
checks.push({ name: 'heavy lane green (integration-profile: gated, #610)', ok: heavyJson.ok,
|
|
12615
|
+
class: heavyJson.ok ? null : (heavyJson.action === 'refuse' ? HUMAN_GATED : SELF_CLEARING),
|
|
12616
|
+
action: heavyJson.action, detail: heavyJson.detail });
|
|
12617
|
+
}
|
|
12465
12618
|
|
|
12466
12619
|
// #350: same single producer as the prose path. 'pending' is not a failure — it is `mode`.
|
|
12467
12620
|
const coreReviewJson = shipCoreReview(repoAbs, gh, target, sess.branch);
|
|
@@ -12547,7 +12700,7 @@ function cmdShipDryJson(opts) {
|
|
|
12547
12700
|
// lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
|
|
12548
12701
|
// Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
|
|
12549
12702
|
if (!dryMode.evidenceClose && !opts._batchMember) {
|
|
12550
|
-
const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
12703
|
+
const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResultJson);
|
|
12551
12704
|
if (laneJson) {
|
|
12552
12705
|
checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
|
|
12553
12706
|
detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
|
|
@@ -13422,7 +13575,7 @@ function shipRefFor(repoAbs, branch) {
|
|
|
13422
13575
|
|
|
13423
13576
|
function cmdShip(argv) {
|
|
13424
13577
|
const opts = parseArgs(argv, {
|
|
13425
|
-
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
|
|
13578
|
+
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff', '--onto': 'onto' },
|
|
13426
13579
|
// #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
|
|
13427
13580
|
// `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
|
|
13428
13581
|
// accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
|
|
@@ -13442,6 +13595,9 @@ function cmdShip(argv) {
|
|
|
13442
13595
|
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-url> (#591, see `colab ship --help`)');
|
|
13443
13596
|
if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
|
|
13444
13597
|
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');
|
|
13598
|
+
if (opts.onto && !opts.batch) throw new UserError('--onto applies to --batch only (#605) — run `colab ship --batch <b1,b2,…> --onto ship-batch/<sha7>`');
|
|
13599
|
+
if (opts.onto && !shipBatch.parseBatchRef(opts.onto)) throw new UserError(`--onto ${opts.onto}: not a batch ref — expected ship-batch/<sha7> (#605)`);
|
|
13600
|
+
if (opts.batch && opts.json) return cmdShipBatchJson(opts); // #605: the batch's facts as JSON, prose on stderr
|
|
13445
13601
|
if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
|
|
13446
13602
|
// A fully separate code path, deliberately: the prose/table path below is unchanged by this
|
|
13447
13603
|
// feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
|
|
@@ -13633,7 +13789,24 @@ function cmdShip(argv) {
|
|
|
13633
13789
|
// #395: the branch's run must have been measured on a head that contains the base's CURRENT tip —
|
|
13634
13790
|
// B0 below syncs locally and never re-runs CI, so this is the only place a stale verdict is caught.
|
|
13635
13791
|
const staleResult = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
|
|
13636
|
-
|
|
13792
|
+
// #606: a docs-only branch needs no CI of its own — this row replaces the stale-base one (a red
|
|
13793
|
+
// run that exists still refuses), and the secret check stands in for the suite's secret scan.
|
|
13794
|
+
const docsCi = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
|
|
13795
|
+
let docsRowOk = true;
|
|
13796
|
+
if (docsCi.applies) {
|
|
13797
|
+
const row = docsOnlyBranchRow(docsCi, staleResult);
|
|
13798
|
+
checks.push([row.ok ? '✓' : '✗', 'branch CI (docs-only, #606)', row.detail]);
|
|
13799
|
+
checks.push([docsCi.scan.ok ? '✓' : '✗', 'docs-only secret check (#606)', docsCi.scan.reason]);
|
|
13800
|
+
docsRowOk = row.ok && docsCi.scan.ok;
|
|
13801
|
+
} else {
|
|
13802
|
+
checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
|
|
13803
|
+
}
|
|
13804
|
+
// #610: integration-profile: gated — the heavy lane green at the branch head. A missing or running
|
|
13805
|
+
// heavy run is a pause (⏸, taken below once every real precondition passes); only a red, or no
|
|
13806
|
+
// heavy lane at all, fails the table.
|
|
13807
|
+
const heavyGate = shipHeavyGate(repoAbs, doc, sess.branch, { docsOnlyApplies: docsCi.applies });
|
|
13808
|
+
if (heavyGate) checks.push([heavyGate.ok ? '✓' : (heavyGate.action === 'refuse' ? '✗' : '⏸'), 'heavy lane green (integration-profile: gated, #610)', heavyGate.detail]);
|
|
13809
|
+
const heavyOk = !heavyGate || heavyGate.action !== 'refuse';
|
|
13637
13810
|
|
|
13638
13811
|
// #350: the core-path review. A 'pending' verdict is not a failed precondition — it is the pause,
|
|
13639
13812
|
// taken below once every real precondition has passed, so it is the ONLY thing between the branch
|
|
@@ -13644,7 +13817,7 @@ function cmdShip(argv) {
|
|
|
13644
13817
|
|
|
13645
13818
|
// #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
|
|
13646
13819
|
// hold is not a failed precondition — it is a pause, taken below once every real one has passed.
|
|
13647
|
-
const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
13820
|
+
const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult);
|
|
13648
13821
|
if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
|
|
13649
13822
|
for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
|
|
13650
13823
|
|
|
@@ -13659,7 +13832,7 @@ function cmdShip(argv) {
|
|
|
13659
13832
|
// issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
|
|
13660
13833
|
// have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
|
|
13661
13834
|
// checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
|
|
13662
|
-
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && staleResult.ok && coreOk && recOk;
|
|
13835
|
+
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk && heavyOk;
|
|
13663
13836
|
|
|
13664
13837
|
// ---- report the table ----
|
|
13665
13838
|
print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
|
|
@@ -13882,6 +14055,8 @@ function cmdShip(argv) {
|
|
|
13882
14055
|
print(' Gate: every closing issue must already carry an evidence comment — checked at run time.');
|
|
13883
14056
|
} else if (lane && lane.held && coreReview.verdict !== 'pending') {
|
|
13884
14057
|
print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${lane.ref} holds the ${trunk} lane (#581); run again once it has landed or been declined`);
|
|
14058
|
+
} else if (heavyGate && !heavyGate.ok && coreReview.verdict !== 'pending') {
|
|
14059
|
+
print(` Plan: PAUSE (⏸ exit 3, nothing merged) — ${heavyGate.action === 'dispatch' ? `a real ship dispatches ${heavyGate.file} at ${shortSha(heavyGate.sha)}` : 'the heavy lane is not green yet'} (integration-profile: gated, #610); run again once it is green`);
|
|
13885
14060
|
} else if (coreReview.verdict === 'pending') {
|
|
13886
14061
|
print(` Plan: push ${sess.branch} · ${coreReview.pr ? `PR #${coreReview.pr.number} already open` : 'open a PR → ' + target} · ` +
|
|
13887
14062
|
'PAUSE (⏸ exit 3, no squash) until an account other than the author approves the current head (#350)');
|
|
@@ -13950,6 +14125,14 @@ function cmdShip(argv) {
|
|
|
13950
14125
|
// ---- (b5) #581: a batch holds the trunk lane — pause before B0, so nothing is synced or merged ----
|
|
13951
14126
|
if (lane && lane.held) { printBatchLanePause(lane, trunk); return 3; }
|
|
13952
14127
|
|
|
14128
|
+
// ---- (b6) #610: gated — the heavy lane must be green at the branch head before trunk moves ----
|
|
14129
|
+
if (heavyGate && !heavyGate.ok) {
|
|
14130
|
+
print(`⏸ HEAVY-PENDING ${sess.branch} — ${heavyGate.detail}. Nothing landed.`);
|
|
14131
|
+
if (heavyGate.action === 'dispatch' && gh) dispatchHeavyLane(repoAbs, heavyGate.file, sess.branch, heavyGate.sha);
|
|
14132
|
+
else print(' Wait on the heavy run (bounded, B1a), then run this command again.');
|
|
14133
|
+
return 3;
|
|
14134
|
+
}
|
|
14135
|
+
|
|
13953
14136
|
// ---- (c) B0: merge the TARGET into the branch (in the worktree, or an ephemeral one) ----
|
|
13954
14137
|
const generated = [...DEFAULT_GENERATED, ...(Array.isArray(doc.generated) ? doc.generated.map(String) : [])];
|
|
13955
14138
|
const hasPreShip = fs.existsSync(path.join(repoAbs, '.colab', 'hooks', 'pre-ship'));
|
|
@@ -14024,6 +14207,18 @@ function cmdShip(argv) {
|
|
|
14024
14207
|
return 1;
|
|
14025
14208
|
}
|
|
14026
14209
|
}
|
|
14210
|
+
// #606: the same for the docs-only CI path — B0 may have made the change something CI must see,
|
|
14211
|
+
// or added a line the secret check has not read. Re-measured on the synced branch.
|
|
14212
|
+
if (docsCi.applies) {
|
|
14213
|
+
const again = docsOnly.shipDocsOnly(git, repoAbs, mergeRef, sess.branch, doc);
|
|
14214
|
+
const rescan = again.docsOnly ? secretScan.scanBranch(git, repoAbs, mergeRef, sess.branch) : null;
|
|
14215
|
+
if (!again.docsOnly || !rescan.ok) {
|
|
14216
|
+
cleanupEphemeral();
|
|
14217
|
+
process.stderr.write(`✗ B1: the docs-only CI path (#606) no longer holds after B0 sync — ${again.docsOnly ? rescan.reason : again.reason}. Nothing pushed.\n`);
|
|
14218
|
+
process.stderr.write(` Push the synced branch and re-run once its CI run completes (\`git push origin ${sess.branch}\`, then \`colab ship\` again) — or remove the finding first if the secret check refused.\n`);
|
|
14219
|
+
return 1;
|
|
14220
|
+
}
|
|
14221
|
+
}
|
|
14027
14222
|
if (autonomyGate.via === 'tuning') {
|
|
14028
14223
|
const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
|
|
14029
14224
|
if (!again.tuning) {
|
|
@@ -14097,7 +14292,7 @@ function cmdShip(argv) {
|
|
|
14097
14292
|
}
|
|
14098
14293
|
// #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
|
|
14099
14294
|
// built in that window is exactly as live as one the table saw.
|
|
14100
|
-
const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
|
|
14295
|
+
const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciCureForTrailer ? { cureVerdict: ciCureForTrailer } : null) : null;
|
|
14101
14296
|
if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
|
|
14102
14297
|
// WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
|
|
14103
14298
|
// (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
|
|
@@ -14460,7 +14655,7 @@ function cmdShip(argv) {
|
|
|
14460
14655
|
// same block, and re-assigning the collector here would silently discard them.
|
|
14461
14656
|
shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
|
|
14462
14657
|
skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
|
|
14463
|
-
evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
|
|
14658
|
+
evidenceExtra: (opts.humanDoorEvidence || '') + docsOnlyEvidence(docsCi, ciResult) + handoffEvidence(sess.handoff) }); // #525, #578, #606
|
|
14464
14659
|
|
|
14465
14660
|
print('');
|
|
14466
14661
|
print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
|
|
@@ -14671,21 +14866,29 @@ function shipDryJsonReport(opts) {
|
|
|
14671
14866
|
* Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
|
|
14672
14867
|
* trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
|
|
14673
14868
|
*/
|
|
14674
|
-
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
|
|
14869
|
+
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
|
|
14675
14870
|
if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
|
|
14871
|
+
// #605: a TRUNK RED: cure is never held by a batch (or a chain) — trunk is red, and the cure is the
|
|
14872
|
+
// way out; no batch can land on a red trunk anyway.
|
|
14873
|
+
if (ciResult && ciResult.cureVerdict && ciResult.cureVerdict.ok) {
|
|
14874
|
+
return { held: false, released: [], detail: 'a TRUNK RED: cure is never held by a batch (#605)' };
|
|
14875
|
+
}
|
|
14676
14876
|
const remote = git.remoteFor(repoAbs);
|
|
14677
14877
|
const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
|
|
14678
14878
|
if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
|
|
14679
14879
|
const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
|
|
14680
14880
|
const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
|
|
14681
|
-
|
|
14682
|
-
|
|
14881
|
+
// #605: the lane holder is the CHAIN rooted at trunk's tip — a batch built --onto another batch's head
|
|
14882
|
+
// reaches trunk only through it, so its run holds the lane exactly as the root's does.
|
|
14883
|
+
const refs = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) })).filter((x) => x.parsed);
|
|
14884
|
+
const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
|
|
14885
|
+
const atTip = refs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
14683
14886
|
const batches = atTip.map((x) => {
|
|
14684
14887
|
const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
|
|
14685
14888
|
let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
|
|
14686
14889
|
if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
|
|
14687
14890
|
const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
|
|
14688
|
-
return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
|
|
14891
|
+
return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs),
|
|
14689
14892
|
builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
|
|
14690
14893
|
});
|
|
14691
14894
|
const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
|
|
@@ -14696,14 +14899,90 @@ function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
|
|
|
14696
14899
|
}
|
|
14697
14900
|
|
|
14698
14901
|
/** #581: the pause a serial ship takes while a batch holds the trunk lane — one message, every door. */
|
|
14902
|
+
/**
|
|
14903
|
+
* #610: the heavy lane at one sha — which workflow it is, whether the tree there has it, and its
|
|
14904
|
+
* verdict. The heavy workflow is named by FILE (`heavy-workflow:`, default ci-heavy.yml); its run
|
|
14905
|
+
* rows carry the workflow's `name:`, so the file at that sha is read to learn which rows are heavy.
|
|
14906
|
+
* `rows: null` (gh unreadable) stays `unread` — never "no heavy run", which would dispatch.
|
|
14907
|
+
*/
|
|
14908
|
+
function heavyLaneAt(repoAbs, doc, sha) {
|
|
14909
|
+
const file = integrationProfile.parseHeavyWorkflow(doc).file;
|
|
14910
|
+
const rel = `.github/workflows/${file}`;
|
|
14911
|
+
let present = false, name = rel;
|
|
14912
|
+
if (sha) {
|
|
14913
|
+
if (!git.git(['cat-file', '-e', `${sha}^{commit}`], repoAbs).ok) git.git(['fetch', '--quiet', git.remoteFor(repoAbs) || 'origin', sha], repoAbs);
|
|
14914
|
+
const show = git.git(['show', `${sha}:${rel}`], repoAbs);
|
|
14915
|
+
if (show.ok) {
|
|
14916
|
+
present = true;
|
|
14917
|
+
const t = verifyRuns.workflowTriggers(show.stdout);
|
|
14918
|
+
if (t && t.name) name = t.name; // GitHub names a workflow with no `name:` by its file path
|
|
14919
|
+
}
|
|
14920
|
+
}
|
|
14921
|
+
const rows = present ? git.ghRunsAtCommit(repoAbs, sha) : [];
|
|
14922
|
+
const heavyRows = Array.isArray(rows) ? rows.filter((r) => (r.workflowName || '') === name) : null;
|
|
14923
|
+
return { file, name, present, verdict: integrationProfile.heavyVerdict(heavyRows) };
|
|
14924
|
+
}
|
|
14925
|
+
|
|
14926
|
+
/**
|
|
14927
|
+
* #610: `integration-profile: gated` — a serial landing waits on a green heavy run at the branch's
|
|
14928
|
+
* remote head. Null under every other profile (ship reads the light lane, as before), for a docs-only
|
|
14929
|
+
* change (no CI wait at all, #606), and for a batch member read (the batch head is graded instead).
|
|
14930
|
+
*/
|
|
14931
|
+
function shipHeavyGate(repoAbs, doc, branch, { docsOnlyApplies = false, batchMember = false } = {}) {
|
|
14932
|
+
const profile = integrationProfile.parseProfile(doc).profile;
|
|
14933
|
+
if (profile !== 'gated' || docsOnlyApplies || batchMember) return null;
|
|
14934
|
+
const refs = git.branchRefs(repoAbs, branch);
|
|
14935
|
+
const sha = refs.remoteSha || null;
|
|
14936
|
+
const at = sha ? `${branch}@${shortSha(sha)}` : branch;
|
|
14937
|
+
if (!sha) return { ok: false, action: 'wait', detail: `integration-profile: gated — ${branch} is not on the remote yet, so the heavy lane cannot run at its head (push it)`, sha: null, file: null };
|
|
14938
|
+
if (refs.localSha && refs.localSha !== sha && !git.git(['merge-base', '--is-ancestor', refs.localSha, sha], repoAbs).ok) {
|
|
14939
|
+
return { ok: false, action: 'wait', detail: `integration-profile: gated — local ${branch} has commits the remote head ${shortSha(sha)} does not; the heavy lane would test the wrong code (push it)`, sha: null, file: null };
|
|
14940
|
+
}
|
|
14941
|
+
const lane = heavyLaneAt(repoAbs, doc, sha);
|
|
14942
|
+
const gate = integrationProfile.landingGate({ profile, heavyPresent: lane.present, verdict: lane.verdict, file: lane.file, at });
|
|
14943
|
+
return { ...gate, sha, file: lane.file, name: lane.name };
|
|
14944
|
+
}
|
|
14945
|
+
|
|
14946
|
+
/** #610: start the heavy lane at `sha` on `ref` — the real path only, never --dry. Never waits. */
|
|
14947
|
+
function dispatchHeavyLane(repoAbs, file, ref, sha) {
|
|
14948
|
+
const d = git.ghWorkflowDispatch(repoAbs, file, ref, { ref: sha });
|
|
14949
|
+
if (d.ok) print(` ↻ dispatched ${file} on ${ref} at ${shortSha(sha)} (#610) — wait with \`gh run watch\` (bounded, B1a), then run this command again.`);
|
|
14950
|
+
else warn(` ${file} could NOT be dispatched (${d.detail}) — run it yourself: gh workflow run ${file} --ref ${ref} -f ref=${sha}`);
|
|
14951
|
+
return d.ok;
|
|
14952
|
+
}
|
|
14953
|
+
|
|
14699
14954
|
function printBatchLanePause(lane, trunk) {
|
|
14700
14955
|
print(`⏸ BATCH-IN-FLIGHT ${lane.ref} — ${lane.why}. Nothing landed.`);
|
|
14701
14956
|
print(` Landing now would move ${trunk} under it and throw its combined run away (#581). Wait for it to land`);
|
|
14702
14957
|
print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
|
|
14703
14958
|
}
|
|
14704
14959
|
|
|
14960
|
+
/**
|
|
14961
|
+
* #605: `colab ship --batch … --dry --json` — the same single step as the prose path (it IS the prose
|
|
14962
|
+
* path, with its prose moved to stderr), plus one JSON document on stdout carrying the facts a caller
|
|
14963
|
+
* keys on: the batch ref, the ref it is chained onto, the trunk sha its chain is rooted at, the step
|
|
14964
|
+
* taken and the exit class, and one row per member. A caller never parses prose for the chain.
|
|
14965
|
+
*/
|
|
14966
|
+
function cmdShipBatchJson(opts) {
|
|
14967
|
+
const batch = { trunk: null, trunkSha: null, ref: null, parentRef: null, rootSha: null, base: null, depth: null, step: null, exit: null, error: null, members: [] };
|
|
14968
|
+
const was = PRINT_TO_STDERR;
|
|
14969
|
+
PRINT_TO_STDERR = true;
|
|
14970
|
+
let code;
|
|
14971
|
+
try { code = cmdShipBatch({ ...opts, _json: batch }); }
|
|
14972
|
+
catch (e) {
|
|
14973
|
+
if (!(e instanceof UserError)) throw e;
|
|
14974
|
+
process.stderr.write(`✗ ${e.message}\n`);
|
|
14975
|
+
batch.error = e.message;
|
|
14976
|
+
batch.step = batch.step || 'refused';
|
|
14977
|
+
code = 1;
|
|
14978
|
+
} finally { PRINT_TO_STDERR = was; }
|
|
14979
|
+
batch.exit = code;
|
|
14980
|
+
process.stdout.write(`${JSON.stringify({ batch }, null, 2)}\n`);
|
|
14981
|
+
return code;
|
|
14982
|
+
}
|
|
14983
|
+
|
|
14705
14984
|
function cmdShipBatch(opts) {
|
|
14706
|
-
for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
|
|
14985
|
+
for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ...(opts._json ? [] : [['json', '--json']])]) {
|
|
14707
14986
|
if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
|
|
14708
14987
|
}
|
|
14709
14988
|
const repoAbs = resolveRepo(opts);
|
|
@@ -14717,7 +14996,12 @@ function cmdShipBatch(opts) {
|
|
|
14717
14996
|
const members = entries.members;
|
|
14718
14997
|
const handoffs = entries.handoffs;
|
|
14719
14998
|
if (members.includes(trunk)) throw new UserError(`Refusing: ${trunk} is the trunk itself — it cannot be a batch member`);
|
|
14999
|
+
const J = opts._json || {}; // #605: the --dry --json report, filled as the facts are read
|
|
15000
|
+
J.trunk = trunk;
|
|
14720
15001
|
const serial = (why, list = members) => {
|
|
15002
|
+
J.step = J.step && J.step !== 'build' ? J.step : 'serial';
|
|
15003
|
+
J.reason = why;
|
|
15004
|
+
if (!J.members || !J.members.length) J.members = list.map((b) => ({ branch: b, sha: null, eligible: null, inBatch: false, why }));
|
|
14721
15005
|
print(`✗ ship-batch: ${why}`);
|
|
14722
15006
|
print(shipBatch.serialLine(list));
|
|
14723
15007
|
return 4;
|
|
@@ -14778,6 +15062,7 @@ function cmdShipBatch(opts) {
|
|
|
14778
15062
|
const lsTrunk = git.git(['ls-remote', remote, `refs/heads/${trunk}`], repoAbs);
|
|
14779
15063
|
const trunkNow = lsTrunk.ok ? (lsTrunk.stdout.split('\t')[0] || '').trim() : '';
|
|
14780
15064
|
if (!trunkNow) throw new UserError(`could not read ${trunk} on ${remote}`);
|
|
15065
|
+
J.trunkSha = trunkNow;
|
|
14781
15066
|
const lsBatch = git.git(['ls-remote', remote, 'refs/heads/ship-batch/*'], repoAbs);
|
|
14782
15067
|
const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
|
|
14783
15068
|
.map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
|
|
@@ -14789,14 +15074,102 @@ function cmdShipBatch(opts) {
|
|
|
14789
15074
|
if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
|
|
14790
15075
|
return d.ok;
|
|
14791
15076
|
};
|
|
14792
|
-
|
|
14793
|
-
|
|
15077
|
+
// #605: the sweep is chain-aware. A ref built `--onto` another batch's head is kept while its chain
|
|
15078
|
+
// ends at a batch on trunk's tip (lib/ship-batch.js batchChains, read from ls-remote alone); a ref
|
|
15079
|
+
// whose parent is gone, or whose root trunk has moved past, is deleted. Without any chained ref this
|
|
15080
|
+
// is exactly the old sweep: every ref not built on trunk's tip goes.
|
|
15081
|
+
const chains = shipBatch.batchChains({ refs: batchRefs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
|
|
15082
|
+
const carriedBy = (ref, from, sha) => {
|
|
15083
|
+
const lg = git.git(['log', '--format=%B%x00', `${from}..${sha}`], repoAbs);
|
|
15084
|
+
return shipBatch.parseMemberTrailers(lg.ok ? lg.stdout.split('\0') : []).filter((m) => m.ref === ref).reverse();
|
|
15085
|
+
};
|
|
15086
|
+
const swept = [];
|
|
15087
|
+
for (const b of batchRefs.filter((x) => !chains.get(x.parsed.ref).rooted)) {
|
|
15088
|
+
const c = chains.get(b.parsed.ref);
|
|
15089
|
+
// A ref built on a head trunk never reached (an orphaned chain link) may still have its run going;
|
|
15090
|
+
// nothing can ever land it, so cancel that run. A ref on an OLD trunk tip is today's case, untouched.
|
|
15091
|
+
const baseFull = git.git(['rev-parse', '--verify', '-q', `${b.parsed.base7}^{commit}`], repoAbs);
|
|
15092
|
+
const offTrunk = !baseFull.ok || !git.git(['merge-base', '--is-ancestor', baseFull.stdout.trim(), trunkNow], repoAbs).ok;
|
|
15093
|
+
if (offTrunk) {
|
|
15094
|
+
print(` ${b.parsed.ref} is not rooted at ${trunk}'s tip — ${c.why}; nothing landed from it; deleting it`);
|
|
15095
|
+
for (const r of (git.ghRunsForRef(repoAbs, b.parsed.ref, b.sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
|
|
15096
|
+
if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${b.parsed.ref}`); continue; }
|
|
15097
|
+
const cx = git.ghRunCancel(repoAbs, r.databaseId);
|
|
15098
|
+
if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${b.parsed.ref} — it will finish on a ref that is gone`);
|
|
15099
|
+
}
|
|
15100
|
+
} else {
|
|
15101
|
+
print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
|
|
15102
|
+
}
|
|
15103
|
+
swept.push({ ref: b.parsed.ref, members: offTrunk ? carriedBy(b.parsed.ref, trunkNow, b.sha) : [] });
|
|
14794
15104
|
deleteRef(b.parsed.ref);
|
|
14795
15105
|
}
|
|
14796
|
-
const
|
|
15106
|
+
const rooted = batchRefs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
15107
|
+
// Every member the chain up to `sha` carries (branch → the ref carrying it), read from its trailers.
|
|
15108
|
+
const carriedByChain = (sha) => new Map(shipBatch.parseMemberTrailers((() => {
|
|
15109
|
+
const lg = git.git(['log', '--format=%B%x00', `${trunkNow}..${sha}`], repoAbs);
|
|
15110
|
+
return lg.ok ? lg.stdout.split('\0') : [];
|
|
15111
|
+
})()).map((m) => [m.branch, m.ref]));
|
|
15112
|
+
|
|
15113
|
+
// #605: --onto <ship-batch ref> builds on that ref's HEAD instead of trunk's tip. `base` is what the
|
|
15114
|
+
// batch sits on from here on; without --onto it is trunk's tip, and nothing below changes.
|
|
15115
|
+
let base = trunkNow;
|
|
15116
|
+
let parent = null; // { ref, sha, chain, verdict } while the parent has not landed
|
|
15117
|
+
if (opts.onto) {
|
|
15118
|
+
const want = shipBatch.parseBatchRef(opts.onto).ref;
|
|
15119
|
+
const p = batchRefs.find((x) => x.parsed.ref === want) || null;
|
|
15120
|
+
const ours = swept.find((x) => x.members.some((m) => members.includes(m.branch)));
|
|
15121
|
+
if (p && p.sha === trunkNow) {
|
|
15122
|
+
print(` ${want} has landed — ${trunk} is at its head ${shortSha(trunkNow)}; this batch sits on ${trunk}'s tip`);
|
|
15123
|
+
} else if (!p || !chains.get(want).rooted) {
|
|
15124
|
+
if (ours) {
|
|
15125
|
+
print(`✗ ship-batch: ${ours.ref} was built on ${want}, which ${p ? `is no longer rooted at ${trunk}'s tip (${chains.get(want).why})` : `is gone from ${remote}`} — nothing landed; ${ours.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}. Rebuild with the same command without --onto.`);
|
|
15126
|
+
J.step = 'chained-decline';
|
|
15127
|
+
return serial('its parent batch was discarded, or trunk moved some other way — the chain cannot land in order', ours.members.map((m) => m.branch));
|
|
15128
|
+
}
|
|
15129
|
+
// The parent landed and its lander deleted the ref: our batch (if staged) now sits on trunk's tip.
|
|
15130
|
+
const atTip = rooted.find((x) => trunkNow.startsWith(x.parsed.base7));
|
|
15131
|
+
const landedParent = !p && atTip && carriedBy(atTip.parsed.ref, trunkNow, atTip.sha).some((m) => members.includes(m.branch));
|
|
15132
|
+
if (!landedParent && p) {
|
|
15133
|
+
throw new UserError(`--onto ${want}: it is not rooted at ${trunk}'s tip (${chains.get(want).why}) — build on ${trunk} instead (drop --onto)`);
|
|
15134
|
+
}
|
|
15135
|
+
if (!landedParent) {
|
|
15136
|
+
// ls-remote cannot tell "never existed" from "discarded" or "trunk moved some other way" — and
|
|
15137
|
+
// for the last two the issue's rule is a decline. So a missing parent declines: nothing of
|
|
15138
|
+
// this chain can land in order, and the members go back to the queue (#605).
|
|
15139
|
+
J.step = 'chained-decline';
|
|
15140
|
+
print(`✗ ship-batch: --onto ${want}: no such batch ref on ${remote} — it was discarded, landed under other members, or never existed.`);
|
|
15141
|
+
return serial(`nothing to chain onto — build on ${trunk} instead (the same command without --onto)`);
|
|
15142
|
+
}
|
|
15143
|
+
print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
|
|
15144
|
+
} else {
|
|
15145
|
+
const pc = chains.get(want);
|
|
15146
|
+
const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha));
|
|
15147
|
+
const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
|
|
15148
|
+
if (verdict.state === 'red') {
|
|
15149
|
+
if (child) {
|
|
15150
|
+
const carried = carriedBy(child.parsed.ref, p.sha, child.sha);
|
|
15151
|
+
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.`);
|
|
15152
|
+
deleteRef(child.parsed.ref);
|
|
15153
|
+
J.step = 'chained-decline';
|
|
15154
|
+
return serial(`its parent ${want} was declined — rebuild on ${trunk} once it is settled`, carried.length ? carried.map((m) => m.branch) : members);
|
|
15155
|
+
}
|
|
15156
|
+
throw new UserError(`--onto ${want}: its combined run is red (${verdict.why}) — nothing to chain onto; build on ${trunk} instead (drop --onto)`);
|
|
15157
|
+
}
|
|
15158
|
+
if (verdict.state === 'none' && !child) {
|
|
15159
|
+
throw new UserError(`--onto ${want}: it has no combined run in flight or green yet — wait for its run to start, then run this command again`);
|
|
15160
|
+
}
|
|
15161
|
+
if (!child && pc.depth >= shipBatch.MAX_CHAIN_DEPTH) {
|
|
15162
|
+
throw new UserError(`--onto ${want}: it is already ${pc.depth} deep from ${trunk}'s tip — a chain is at most ${shipBatch.MAX_CHAIN_DEPTH} batches (#605); wait for its root to land`);
|
|
15163
|
+
}
|
|
15164
|
+
base = p.sha;
|
|
15165
|
+
parent = { ref: want, sha: p.sha, chain: pc, verdict };
|
|
15166
|
+
}
|
|
15167
|
+
}
|
|
15168
|
+
Object.assign(J, { base, parentRef: parent ? parent.ref : null, rootSha: trunkNow, depth: parent ? parent.chain.depth + 1 : 1, ref: shipBatch.batchRefName(base) });
|
|
15169
|
+
const atBase = rooted.find((x) => (!parent || x.parsed.ref !== parent.ref) && base.startsWith(x.parsed.base7)) || null;
|
|
14797
15170
|
let existing = null;
|
|
14798
15171
|
if (atBase) {
|
|
14799
|
-
const log = git.git(['log', '--format=%B%x00', `${
|
|
15172
|
+
const log = git.git(['log', '--format=%B%x00', `${base}..${atBase.sha}`], repoAbs);
|
|
14800
15173
|
const inBatch = shipBatch.parseMemberTrailers(log.ok ? log.stdout.split('\0') : []).reverse();
|
|
14801
15174
|
const foreign = inBatch.filter((m) => !members.includes(m.branch));
|
|
14802
15175
|
// #391: a DECLINED batch (combined run red) is not in flight — clear it and build the one asked for.
|
|
@@ -14825,8 +15198,24 @@ function cmdShipBatch(opts) {
|
|
|
14825
15198
|
}
|
|
14826
15199
|
}
|
|
14827
15200
|
}
|
|
14828
|
-
|
|
14829
|
-
|
|
15201
|
+
let verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
|
|
15202
|
+
// #610: integration-profile: gated — a wave lands only on a green heavy run at its head too. The
|
|
15203
|
+
// heavy verdict joins the combined one (integration-profile.js waveVerdict), so a heavy red takes
|
|
15204
|
+
// the same re-run / split path a light red does, and the split walks toward the culprit.
|
|
15205
|
+
let heavyWave = null;
|
|
15206
|
+
if (verdict && integrationProfile.parseProfile(doc).profile === 'gated') {
|
|
15207
|
+
heavyWave = heavyLaneAt(repoAbs, doc, existing.sha);
|
|
15208
|
+
if (!heavyWave.present) {
|
|
15209
|
+
print(`✗ ship-batch: integration-profile: gated, but no .github/workflows/${heavyWave.file} at ${existing.ref}@${shortSha(existing.sha)} — a wave lands only on a green heavy run, and there is no heavy lane to run. Nothing landed.`);
|
|
15210
|
+
print(' Add one: `colab template ci-<stack>-heavy --dest .github/workflows/ci-heavy.yml` (or name yours with heavy-workflow:), land it, then re-run once it is on trunk.');
|
|
15211
|
+
return 4;
|
|
15212
|
+
}
|
|
15213
|
+
verdict = integrationProfile.waveVerdict(verdict, heavyWave.verdict);
|
|
15214
|
+
}
|
|
15215
|
+
// #605: a chained batch is measured against its own base (the parent's head), not trunk's tip.
|
|
15216
|
+
let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow: base, verdict, split: !!opts.split });
|
|
15217
|
+
J.step = step.step;
|
|
15218
|
+
if (existing) J.members = existing.members.map((m) => ({ branch: m.branch, sha: m.sha, eligible: true, inBatch: true, why: `staged in ${existing.ref}` }));
|
|
14830
15219
|
if (opts.split && !(verdict && verdict.state === 'red')) {
|
|
14831
15220
|
print(` --split ignored: ${existing ? `${existing.ref} is not red (${verdict ? verdict.state : 'members changed'})` : 'no batch is staged at this base'} — only a red combined run splits (#557)`);
|
|
14832
15221
|
}
|
|
@@ -14839,6 +15228,7 @@ function cmdShipBatch(opts) {
|
|
|
14839
15228
|
}
|
|
14840
15229
|
if (step.step === 'wait-run') {
|
|
14841
15230
|
print(`⏸ BATCH-PENDING ${existing.ref}@${shortSha(existing.sha)} — combined run ${verdict && verdict.runIds.length ? verdict.runIds.join(', ') + ' ' : ''}${verdict ? verdict.why : ''}.`);
|
|
15231
|
+
if (verdict && verdict.heavyMissing && heavyWave && !opts.dry) dispatchHeavyLane(repoAbs, heavyWave.file, existing.ref, existing.sha); // #610
|
|
14842
15232
|
print(` Wait on it (bounded, B1a: gh run watch <id>), then run this command again. Nothing landed.`);
|
|
14843
15233
|
return 3;
|
|
14844
15234
|
}
|
|
@@ -14875,15 +15265,33 @@ function cmdShipBatch(opts) {
|
|
|
14875
15265
|
print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
|
|
14876
15266
|
return 4;
|
|
14877
15267
|
}
|
|
15268
|
+
if (step.step === 'land' && parent) {
|
|
15269
|
+
// #605: land in order — only once trunk's tip IS the parent's head. Until then the parent is in
|
|
15270
|
+
// flight (wait, exit 3); a parent that is red will never land at that sha (delete, exit 4).
|
|
15271
|
+
const ls = shipBatch.chainedLandStep({ parent: parent.chain, parentVerdict: parent.verdict });
|
|
15272
|
+
J.step = ls.step === 'wait' ? 'chained-wait' : 'chained-decline';
|
|
15273
|
+
J.reason = ls.why;
|
|
15274
|
+
if (ls.step === 'wait') {
|
|
15275
|
+
print(`⏸ BATCH-CHAINED ${existing.ref}@${shortSha(existing.sha)} — combined run green; it lands after ${parent.ref}: ${ls.why}. Nothing landed.`);
|
|
15276
|
+
print(` Wait for ${parent.ref} to land (bounded, B1a), then run this command again — it lands with no second run.`);
|
|
15277
|
+
return 3;
|
|
15278
|
+
}
|
|
15279
|
+
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.`);
|
|
15280
|
+
deleteRef(existing.ref);
|
|
15281
|
+
return serial('its parent batch was discarded', existing.members.map((m) => m.branch));
|
|
15282
|
+
}
|
|
14878
15283
|
if (step.step === 'land') return shipBatchLand(repoAbs, doc, trunk, remote, trunkNow, existing, verdict, opts);
|
|
14879
15284
|
|
|
14880
15285
|
// ---- (d) pick the members — each through its OWN ship gates ----
|
|
14881
15286
|
const st = state.loadState();
|
|
14882
15287
|
const evaluated = [];
|
|
15288
|
+
// #605: a member the chain below already carries lands with that batch — it never joins a second one.
|
|
15289
|
+
const inChain = parent ? carriedByChain(parent.sha) : new Map();
|
|
14883
15290
|
for (const b of members) {
|
|
14884
15291
|
const refs = git.branchRefs(repoAbs, b, remote);
|
|
14885
15292
|
let why = null, report = null, ciClass = null, files = [];
|
|
14886
15293
|
if (!refs.remoteSha) why = `not on ${remote} — push it first; its CI has never seen it`;
|
|
15294
|
+
else if (inChain.has(b)) why = `already in ${inChain.get(b)} — it lands with that batch, not this one`;
|
|
14887
15295
|
else if (refs.localSha && refs.localSha !== refs.remoteSha) why = `local ${shortSha(refs.localSha)} ≠ ${remote} ${shortSha(refs.remoteSha)} — its CI never saw this head`;
|
|
14888
15296
|
if (!why) {
|
|
14889
15297
|
// #591: a hand-off member is read through the SAME door a single --handoff ship uses
|
|
@@ -14916,12 +15324,13 @@ function cmdShipBatch(opts) {
|
|
|
14916
15324
|
return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
|
|
14917
15325
|
})()
|
|
14918
15326
|
: shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
|
|
14919
|
-
print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)} (${splitHalf ? `split of a red batch of ${splitHalf.first.length + splitHalf.held.length}` : sizeLabel})${opts.dry ? ' [DRY RUN]' : ''}`);
|
|
15327
|
+
print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(trunkNow)}${parent ? ` · onto ${parent.ref}@${shortSha(parent.sha)} (depth ${parent.chain.depth + 1}, lands after it)` : ''} (${splitHalf ? `split of a red batch of ${splitHalf.first.length + splitHalf.held.length}` : sizeLabel})${opts.dry ? ' [DRY RUN]' : ''}`);
|
|
14920
15328
|
print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
|
|
14921
15329
|
e.ok && !selected.includes(e) ? (splitHalf ? 'eligible — held by the split for the next batch' : `eligible — waits for the next batch (cap ${size})`) : e.why]), ['', 'MEMBER', 'DETAIL']));
|
|
14922
15330
|
const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
|
|
15331
|
+
J.members = evaluated.map((e) => ({ branch: e.branch, sha: e.sha || null, eligible: e.ok, inBatch: selected.includes(e), why: e.why }));
|
|
14923
15332
|
step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
|
|
14924
|
-
if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
|
|
15333
|
+
if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf && !parent) {
|
|
14925
15334
|
// #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
|
|
14926
15335
|
// member is ready. Wait for a partner until the repo's window, counted from when it became ready.
|
|
14927
15336
|
const lone = selected[0];
|
|
@@ -14940,10 +15349,11 @@ function cmdShipBatch(opts) {
|
|
|
14940
15349
|
if (step.step === 'serial') return serial('no member can join — each one above says why');
|
|
14941
15350
|
|
|
14942
15351
|
// ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
|
|
14943
|
-
|
|
15352
|
+
// #605: on a chain, the batch is built on the parent's head and named after it — one batch per base.
|
|
15353
|
+
const ref = shipBatch.batchRefName(base);
|
|
14944
15354
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-ship-batch-'));
|
|
14945
|
-
const add = git.git(['worktree', 'add', '--detach', dir,
|
|
14946
|
-
if (!add.ok) { try { fs.rmdirSync(dir); } catch (_) {} throw new UserError(`could not check out ${shortSha(
|
|
15355
|
+
const add = git.git(['worktree', 'add', '--detach', dir, base], repoAbs);
|
|
15356
|
+
if (!add.ok) { try { fs.rmdirSync(dir); } catch (_) {} throw new UserError(`could not check out ${shortSha(base)} to build the batch: ${git.gitFailureLine(add.stderr)}`); }
|
|
14947
15357
|
const cleanup = () => git.git(['worktree', 'remove', '--force', dir], repoAbs);
|
|
14948
15358
|
const machineLine = shipMachineTrailerDecision(repoAbs, doc).line;
|
|
14949
15359
|
const built = [];
|
|
@@ -15011,6 +15421,8 @@ function cmdShipBatch(opts) {
|
|
|
15011
15421
|
built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
|
|
15012
15422
|
}
|
|
15013
15423
|
for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
|
|
15424
|
+
for (const d of dropped) Object.assign(J.members.find((r) => r.branch === d.branch) || {}, { inBatch: false, why: d.why });
|
|
15425
|
+
J.step = 'build';
|
|
15014
15426
|
// #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
|
|
15015
15427
|
// batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
|
|
15016
15428
|
// Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
|
|
@@ -15036,8 +15448,10 @@ function cmdShipBatch(opts) {
|
|
|
15036
15448
|
}
|
|
15037
15449
|
if (opts.dry) {
|
|
15038
15450
|
cleanup();
|
|
15039
|
-
print(`→ READY: would push ${ref} = ${shortSha(
|
|
15040
|
-
print(
|
|
15451
|
+
print(`→ READY: would push ${ref} = ${shortSha(base)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
|
|
15452
|
+
print(parent
|
|
15453
|
+
? ` then wait on ONE combined run, and fast-forward trunk to it only once ${parent.ref} has landed at ${shortSha(parent.sha)} (#605).`
|
|
15454
|
+
: ' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
|
|
15041
15455
|
if (notJoining.length || dropped.length) print(` not in this batch: ${[...new Set([...notJoining, ...dropped.map((d) => d.branch)])].join(', ')}`);
|
|
15042
15456
|
return 0;
|
|
15043
15457
|
}
|
|
@@ -15045,7 +15459,7 @@ function cmdShipBatch(opts) {
|
|
|
15045
15459
|
const push = git.run('git', ['push', '--force', remote, `${head}:refs/heads/${ref}`], { cwd: repoAbs });
|
|
15046
15460
|
cleanup();
|
|
15047
15461
|
if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
|
|
15048
|
-
print(` pushed ${ref} = ${shortSha(
|
|
15462
|
+
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` : ''}`);
|
|
15049
15463
|
if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
|
|
15050
15464
|
print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
|
|
15051
15465
|
return 3;
|
|
@@ -16087,6 +16501,10 @@ workflow \`.github/workflows/instruction-files.yml\`.
|
|
|
16087
16501
|
--repo <path> repo to run in (default: cwd)
|
|
16088
16502
|
--json { ok, error?, mode, base, fail, reason, files: [{ path, conforming, message }], changed }
|
|
16089
16503
|
|
|
16504
|
+
A fork whose CLAUDE.md/AGENTS.md belong to its upstream declares \`instruction-files: upstream\` in
|
|
16505
|
+
.github/project.yml (read on the judged side — HEAD, the index or the working tree): nothing is judged
|
|
16506
|
+
and the verdict is a pass (\`--json\`: \`exempt: "upstream"\`) — CONVENTIONS.md §9 "A fork of an upstream", #602.
|
|
16507
|
+
|
|
16090
16508
|
Exit: 0 pass · 1 fail · 2 cannot judge (not a repo, base not fetched — never read as a pass).
|
|
16091
16509
|
The fix for a failure is always the same: move the prose to AGENTS.md (handbook-sync's graft step
|
|
16092
16510
|
does the move), keeping CLAUDE.md to \`@AGENTS.md\`, blank lines and tool blocks.
|
|
@@ -16564,6 +16982,23 @@ function cmdPromote(argv) {
|
|
|
16564
16982
|
else checks.push(['✗', 'trunk CI green', `${trunk}@${shortSha(run.sha)}: status=${run.status} conclusion=${run.conclusion || 'none'} (fail-to-start counts as not green)`]);
|
|
16565
16983
|
}
|
|
16566
16984
|
|
|
16985
|
+
// #610: integration-profile: promote — the heavy lane gates the promotion: green at the exact sha
|
|
16986
|
+
// being promoted (origin's trunk tip). Never dispatched from here: promotion is a human act, and
|
|
16987
|
+
// the command to start the heavy lane is printed instead.
|
|
16988
|
+
let heavyOk = true;
|
|
16989
|
+
if (integrationProfile.parseProfile(doc).profile === 'promote') {
|
|
16990
|
+
const tipR = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
|
|
16991
|
+
const tip = tipR.ok ? tipR.stdout : null;
|
|
16992
|
+
const lane = tip ? heavyLaneAt(repoAbs, doc, tip) : null;
|
|
16993
|
+
const at = tip ? `${trunk}@${shortSha(tip)}` : trunk;
|
|
16994
|
+
let detail;
|
|
16995
|
+
if (!lane) { heavyOk = false; detail = `${remote}/${trunk} could not be read`; }
|
|
16996
|
+
else if (!lane.present) { heavyOk = false; detail = `no .github/workflows/${lane.file} at ${at} — integration-profile: promote gates the promotion on the heavy lane, and there is none`; }
|
|
16997
|
+
else if (lane.verdict.state === 'green') detail = `heavy lane green at ${at}${lane.verdict.url ? ` (${lane.verdict.url})` : ''}`;
|
|
16998
|
+
else { heavyOk = false; detail = `heavy lane ${lane.verdict.state} at ${at} (${lane.verdict.why})${lane.verdict.state === 'none' ? ` — start it: gh workflow run ${lane.file} --ref ${trunk} -f ref=${tip}` : ''}`; }
|
|
16999
|
+
checks.push([heavyOk ? '✓' : '✗', 'heavy lane green (integration-profile: promote, #610)', detail]);
|
|
17000
|
+
}
|
|
17001
|
+
|
|
16567
17002
|
const localTrunk = git.git(['rev-parse', trunk], repoAbs);
|
|
16568
17003
|
const originTrunk = git.git(['rev-parse', `${remote}/${trunk}`], repoAbs);
|
|
16569
17004
|
const trunkSyncOk = localTrunk.ok && originTrunk.ok && localTrunk.stdout === originTrunk.stdout;
|
|
@@ -16593,7 +17028,7 @@ function cmdPromote(argv) {
|
|
|
16593
17028
|
ahead > 0 ? `${ahead} commit(s) to promote` : `could not count ${remote}/${MAIN}..${remote}/${trunk}`]);
|
|
16594
17029
|
}
|
|
16595
17030
|
|
|
16596
|
-
const preOk = ciOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
|
|
17031
|
+
const preOk = ciOk && heavyOk && trunkSyncOk && mainSyncOk && checkoutOk && (!opts.auto || ahead > 0);
|
|
16597
17032
|
|
|
16598
17033
|
// ---- report ----
|
|
16599
17034
|
say(`promote ${shortRepo(repoAbs)} · ${trunk} → ${MAIN}` + (opts.dry ? ' [DRY RUN]' : ''));
|
|
@@ -16837,7 +17272,9 @@ re-running install.sh; \`colab update\` reports it when it is behind. \`colab --
|
|
|
16837
17272
|
which of the two you are talking to.
|
|
16838
17273
|
`;
|
|
16839
17274
|
|
|
16840
|
-
|
|
17275
|
+
// #605: `ship --batch --dry --json` keeps stdout for its one JSON document; the prose goes to stderr.
|
|
17276
|
+
let PRINT_TO_STDERR = false;
|
|
17277
|
+
function print(s) { (PRINT_TO_STDERR ? process.stderr : process.stdout).write(s.endsWith('\n') ? s : s + '\n'); return 0; }
|
|
16841
17278
|
function warn(s) { process.stderr.write(`! ${s}\n`); }
|
|
16842
17279
|
/**
|
|
16843
17280
|
* `colab ship` sets this to an array while it runs B3 (worktree teardown) through B4 (per-issue
|