@futurelastic/colab-handbook 1.14.0-rc.10 → 1.14.0-rc.12
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/audit/audit.mjs +8 -5
- package/package.json +1 -1
- package/tools/colab +309 -30
- package/tools/lib/docs-only.js +76 -21
- package/tools/lib/git.js +6 -1
- package/tools/lib/secret-scan.js +132 -0
- package/tools/lib/ship-batch.js +71 -2
package/audit/audit.mjs
CHANGED
|
@@ -1497,13 +1497,16 @@ function auditRepoInner(target, ctx) {
|
|
|
1497
1497
|
if (!ifl.valid) fail(ifl.reason);
|
|
1498
1498
|
}
|
|
1499
1499
|
|
|
1500
|
-
// ---- ci-docs-skip (#570)
|
|
1501
|
-
//
|
|
1502
|
-
//
|
|
1503
|
-
//
|
|
1500
|
+
// ---- ci-docs-skip (#570, #606) ---------------------------------------------
|
|
1501
|
+
// The docs-only path list (tools/lib/docs-only.js parseCiDocsSkip). ON BY DEFAULT (#606): absent
|
|
1502
|
+
// = on, a list = on with those paths excluded (a change to one is not docs-only), `off` = off.
|
|
1503
|
+
// `colab ship` reads it to decide a docs-only change needs no CI; the CI templates' legacy guard
|
|
1504
|
+
// reads the same list. Reported as the exception list (`[]` when absent), `"off"`, or null when
|
|
1505
|
+
// invalid. An invalid value fails: every reader takes it as "not docs-only", so it silently
|
|
1506
|
+
// opts the repo out.
|
|
1504
1507
|
{
|
|
1505
1508
|
const ds = docsOnlyLib.parseCiDocsSkip(cfg);
|
|
1506
|
-
info.ciDocsSkip = ds.
|
|
1509
|
+
info.ciDocsSkip = !ds.valid ? null : ds.on ? ds.exclude : "off";
|
|
1507
1510
|
if (!ds.valid) fail(ds.reason);
|
|
1508
1511
|
}
|
|
1509
1512
|
|
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -70,6 +70,7 @@ 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 secretScan = require('./lib/secret-scan'); // #606
|
|
73
74
|
const configSet = require('./lib/config-set'); // #561
|
|
74
75
|
const cureDiff = require('./lib/cure-diff');
|
|
75
76
|
const codeowners = require('./lib/codeowners');
|
|
@@ -10595,7 +10596,7 @@ function ciCureTrailerLine(cureVerdict, branch, trunk) {
|
|
|
10595
10596
|
}
|
|
10596
10597
|
|
|
10597
10598
|
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]
|
|
10598
|
-
colab ship --batch <b1,b2[@<handoff-url>][,…]> [--split] [--repo <path>] [--keep-worktree] [--delete-branch | --keep-branch] [--session <id>] [--session-name <s>] [--dry]
|
|
10599
|
+
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]]
|
|
10599
10600
|
|
|
10600
10601
|
The ONE sanctioned door for code-wrap Phase B: squash-merge a session branch into the BASE IT WAS
|
|
10601
10602
|
CUT FROM — trunk for an ordinary session, or the declared integration line recorded on its worktree
|
|
@@ -10884,7 +10885,20 @@ The batch also holds the trunk LANE (#581): while a ship-batch/<trunk-sha7> ref
|
|
|
10884
10885
|
combined run in flight — or green within ${shipBatch.LANE_GRACE_SEC / 60}m, so its lander can land it — a serial
|
|
10885
10886
|
\`colab ship --branch\` into trunk pauses with exit 3 (⏸ BATCH-IN-FLIGHT; its --dry --json row
|
|
10886
10887
|
'no batch in flight (#581)' reads self-clearing) instead of moving trunk under it and discarding the run.
|
|
10887
|
-
A red batch, or one with no run / not landed past that grace, holds nothing.
|
|
10888
|
+
A red batch, or one with no run / not landed past that grace, holds nothing. A TRUNK RED: cure is never held.
|
|
10889
|
+
SPECULATIVE CHAIN (#605): --onto ship-batch/<sha7> builds the batch on that in-flight batch's HEAD
|
|
10890
|
+
instead of trunk's tip, named ship-batch/<parent-head-sha7> (one batch per base still holds). The chain
|
|
10891
|
+
is read from ls-remote alone: a ref's parent is the ref whose head its name starts with, and it is kept
|
|
10892
|
+
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,
|
|
10893
|
+
or whose root trunk moved past, is deleted by the next --batch call (its run cancelled if still going).
|
|
10894
|
+
- refused (1): the named ref has no combined run in flight or green, is not rooted at trunk's tip,
|
|
10895
|
+
or is already ${shipBatch.MAX_CHAIN_DEPTH} deep; a member the chain below already carries does not join (✗, the rest go on);
|
|
10896
|
+
- lands in order: green and its parent not landed yet → ⏸ BATCH-CHAINED (exit 3); once trunk's tip IS
|
|
10897
|
+
the parent's head, the same command (with or without --onto) lands it — no second build, no second run;
|
|
10898
|
+
- declined (4): the parent is red, gone, or trunk moved some other way — the child is deleted, → SERIAL.
|
|
10899
|
+
Every ref of a chain rooted at trunk's tip holds the lane, exactly as one batch does.
|
|
10900
|
+
--dry --json: one JSON document on stdout ({ batch: { ref, parentRef, rootSha, base, depth, step, exit,
|
|
10901
|
+
members: [{ branch, sha, eligible, inBatch, why }] } }), the prose on stderr.
|
|
10888
10902
|
A member that conflicts with the members already in is dropped to the next batch; the rest go on —
|
|
10889
10903
|
unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
|
|
10890
10904
|
regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
|
|
@@ -11457,6 +11471,13 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
11457
11471
|
via = `${trunk} (by commit — the branch-filtered read was empty)`;
|
|
11458
11472
|
}
|
|
11459
11473
|
}
|
|
11474
|
+
// #606: trunk's tip has no FINISHED run and is a docs-only commit (an adopter's CI `paths-ignore`s
|
|
11475
|
+
// docs, or the run is simply not done) — docs change no code, so trunk's CI is the verdict of the
|
|
11476
|
+
// newest trunk commit that is NOT docs-only. A finished red run at the tip is never overridden.
|
|
11477
|
+
if (target === trunk && (run.status === 'none' || run.status !== 'completed')) {
|
|
11478
|
+
const door = docsOnlyTipDoor(repoAbs, trunk, run.sha, readOpts);
|
|
11479
|
+
if (door) return door;
|
|
11480
|
+
}
|
|
11460
11481
|
const at = `${via}@${shortSha(run.sha)}`;
|
|
11461
11482
|
let verdict = classifyCiRun(repoAbs, run, at);
|
|
11462
11483
|
// #413: still no run anywhere at a trunk sha committed minutes ago — the run may not exist YET
|
|
@@ -11635,6 +11656,75 @@ function baseCiAdvisory(repoAbs, gh, base, branch) {
|
|
|
11635
11656
|
};
|
|
11636
11657
|
}
|
|
11637
11658
|
|
|
11659
|
+
/**
|
|
11660
|
+
* #606: trunk's tip is docs-only and has no finished run — read trunk CI at the newest first-parent
|
|
11661
|
+
* ancestor that is NOT docs-only (tools/lib/docs-only.js commitChanges, narrowed by trunk's
|
|
11662
|
+
* `ci-docs-skip`). Returns a readCiVerdict result, or null when the door does not apply: the repo
|
|
11663
|
+
* declared `ci-docs-skip: off` (or an invalid value), the tip is not local or not docs-only, no code
|
|
11664
|
+
* commit within DOCS_TIP_WALK commits, or that commit's runs are unreadable. A null keeps every
|
|
11665
|
+
* existing reading of the tip unchanged — the door only ever answers for a docs-only tip.
|
|
11666
|
+
*/
|
|
11667
|
+
const DOCS_TIP_WALK = 50;
|
|
11668
|
+
function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
|
|
11669
|
+
if (!tipSha) return null;
|
|
11670
|
+
const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
|
|
11671
|
+
if (!setting.on) return null;
|
|
11672
|
+
const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
|
|
11673
|
+
if (!list.ok) return null;
|
|
11674
|
+
let skipped = 0;
|
|
11675
|
+
let code = null;
|
|
11676
|
+
for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
|
|
11677
|
+
const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude });
|
|
11678
|
+
if (!c.docsOnly) { code = sha; break; }
|
|
11679
|
+
skipped++;
|
|
11680
|
+
}
|
|
11681
|
+
if (!code || skipped === 0) return null;
|
|
11682
|
+
const run = git.ghRunForCommitAnyRef(repoAbs, code, undefined, readOpts);
|
|
11683
|
+
if (!run) return null;
|
|
11684
|
+
const at = `${trunk}@${shortSha(code)}`;
|
|
11685
|
+
const v = classifyCiRun(repoAbs, run, at);
|
|
11686
|
+
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 — `;
|
|
11687
|
+
const verdict = { ...v, detail: note + v.detail, docsOnlyTip: { tip: tipSha, read: code, skipped } };
|
|
11688
|
+
return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
|
|
11689
|
+
}
|
|
11690
|
+
|
|
11691
|
+
/**
|
|
11692
|
+
* #606: is this branch DOCS-ONLY for CI purposes — so `colab ship` lands it without waiting for CI?
|
|
11693
|
+
* tools/lib/docs-only.js shipDocsOnly (the #345 rule, narrowed by `ci-docs-skip`, off by `off`),
|
|
11694
|
+
* measured on the ref ship would land. When it applies, the secret check runs too
|
|
11695
|
+
* (tools/lib/secret-scan.js) — the suite's own secret scan may never see this change.
|
|
11696
|
+
* Returns `{ applies, files, reason, scan }`; `scan` only when `applies`.
|
|
11697
|
+
*/
|
|
11698
|
+
function shipDocsOnlyCi(repoAbs, doc, target, branch) {
|
|
11699
|
+
const ref = shipRefFor(repoAbs, branch);
|
|
11700
|
+
const d = docsOnly.shipDocsOnly(git, repoAbs, target, ref, doc);
|
|
11701
|
+
if (!d.docsOnly) return { applies: false, files: d.files, reason: d.reason, scan: null };
|
|
11702
|
+
return { applies: true, files: d.files, reason: d.reason, scan: secretScan.scanBranch(git, repoAbs, target, ref) };
|
|
11703
|
+
}
|
|
11704
|
+
|
|
11705
|
+
/** #606: the 🚢 comment's evidence clause for a docs-only ship — files, and the trunk sha CI was read at. */
|
|
11706
|
+
function docsOnlyEvidence(dc, ci) {
|
|
11707
|
+
if (!dc || !dc.applies) return '';
|
|
11708
|
+
const tip = ci && ci.docsOnlyTip;
|
|
11709
|
+
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';
|
|
11710
|
+
return ` — docs-only: CI not required (${dc.files} files)${read}; secret check clean`;
|
|
11711
|
+
}
|
|
11712
|
+
|
|
11713
|
+
/**
|
|
11714
|
+
* #606: the branch-run row for a docs-only branch, in place of #395's stale-base row. CI is not
|
|
11715
|
+
* required, so no run, a run in flight, or a run measured on an older base is fine — but a run that
|
|
11716
|
+
* EXISTS at the pushed head and finished red still refuses: ship never overrides a red verdict.
|
|
11717
|
+
*/
|
|
11718
|
+
function docsOnlyBranchRow(dc, stale) {
|
|
11719
|
+
const run = stale && stale.run;
|
|
11720
|
+
const red = !!run && run.status === 'completed' && run.conclusion !== 'success' && run.conclusion !== 'cancelled' && run.conclusion !== 'skipped';
|
|
11721
|
+
if (red) {
|
|
11722
|
+
return { ok: false, class: HUMAN_GATED,
|
|
11723
|
+
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)` };
|
|
11724
|
+
}
|
|
11725
|
+
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'})` };
|
|
11726
|
+
}
|
|
11727
|
+
|
|
11638
11728
|
/**
|
|
11639
11729
|
* #395: does the branch's CI verdict cover the CURRENT `base`? A PRECONDITION, unlike
|
|
11640
11730
|
* `baseCiAdvisory` above: serial ship syncs the base in locally (B0) and squashes without the synced
|
|
@@ -11663,7 +11753,8 @@ function shipStaleBaseCheck(repoAbs, gh, base, branch) {
|
|
|
11663
11753
|
if (contains === false && git.git(['diff', '--quiet', `${baseTip}...${headSha}`], repoAbs).code === 0) contains = 'no-change';
|
|
11664
11754
|
}
|
|
11665
11755
|
if (headSha && gh) run = git.ghRunForCommit(repoAbs, branch, headSha);
|
|
11666
|
-
|
|
11756
|
+
// #606: `run`/`headSha` are additive — the docs-only row reads whether that run finished red.
|
|
11757
|
+
return { ...staleBase.staleBaseVerdict({ headSha, run, baseTip, contains, behind, base, ghUsable: !!gh }), run, headSha };
|
|
11667
11758
|
}
|
|
11668
11759
|
|
|
11669
11760
|
/**
|
|
@@ -12468,7 +12559,14 @@ function cmdShipDryJson(opts) {
|
|
|
12468
12559
|
// read is exempt: the batch grades the COMBINED head (trunk + every member), which is exactly the
|
|
12469
12560
|
// re-run this row demands of a serial land, so a member behind trunk is the ordinary case there.
|
|
12470
12561
|
const staleJson = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
|
|
12471
|
-
|
|
12562
|
+
// #606: a docs-only branch needs no CI of its own — its row replaces the stale-base one, and the
|
|
12563
|
+
// secret check stands in for the suite's secret scan. Same producers as the prose path.
|
|
12564
|
+
const docsCiJson = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
|
|
12565
|
+
if (docsCiJson.applies) {
|
|
12566
|
+
const row = docsOnlyBranchRow(docsCiJson, staleJson);
|
|
12567
|
+
checks.push({ name: 'branch CI (docs-only, #606)', ok: row.ok, class: row.class, verdict: staleJson.verdict, detail: row.detail });
|
|
12568
|
+
checks.push({ name: 'docs-only secret check (#606)', ok: docsCiJson.scan.ok, class: docsCiJson.scan.ok ? null : HUMAN_GATED, detail: docsCiJson.scan.reason });
|
|
12569
|
+
} else if (opts._batchMember) {
|
|
12472
12570
|
checks.push({ name: 'branch run contains current base (#395)', ok: true, class: null, verdict: staleJson.verdict,
|
|
12473
12571
|
detail: `batch member — the combined run grades it (${staleJson.detail})` });
|
|
12474
12572
|
} else {
|
|
@@ -12560,7 +12658,7 @@ function cmdShipDryJson(opts) {
|
|
|
12560
12658
|
// lane would discard the batch's run. SELF_CLEARING: the batch lands or is declined on its own.
|
|
12561
12659
|
// Never for a batch member read (the batch IS the lane) nor for evidence-close (trunk does not move).
|
|
12562
12660
|
if (!dryMode.evidenceClose && !opts._batchMember) {
|
|
12563
|
-
const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
12661
|
+
const laneJson = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResultJson);
|
|
12564
12662
|
if (laneJson) {
|
|
12565
12663
|
checks.push({ name: 'no batch in flight (#581)', ok: !laneJson.held, class: laneJson.held ? SELF_CLEARING : null,
|
|
12566
12664
|
detail: laneJson.detail, ...(laneJson.held ? { batchRef: laneJson.ref } : {}) });
|
|
@@ -13435,7 +13533,7 @@ function shipRefFor(repoAbs, branch) {
|
|
|
13435
13533
|
|
|
13436
13534
|
function cmdShip(argv) {
|
|
13437
13535
|
const opts = parseArgs(argv, {
|
|
13438
|
-
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff' },
|
|
13536
|
+
values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--message': 'message', '--session': 'session', '--session-name': 'sessionName', '--batch': 'batch', '--answered-by': 'answeredBy', '--handoff': 'handoff', '--onto': 'onto' },
|
|
13439
13537
|
// #479: a repeated --refs used to keep only its LAST value, and every dropped issue then became a
|
|
13440
13538
|
// `Closes` line on trunk — an issue meant to stay open, auto-closed by the push. --refs now
|
|
13441
13539
|
// accumulates (a repeat is the same as one comma list); every OTHER value flag to ship refuses a
|
|
@@ -13455,6 +13553,9 @@ function cmdShip(argv) {
|
|
|
13455
13553
|
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`)');
|
|
13456
13554
|
if (opts.handoff && opts.direct) throw new UserError('--handoff applies to one --branch ship — not to --direct (see `colab ship --help`)');
|
|
13457
13555
|
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');
|
|
13556
|
+
if (opts.onto && !opts.batch) throw new UserError('--onto applies to --batch only (#605) — run `colab ship --batch <b1,b2,…> --onto ship-batch/<sha7>`');
|
|
13557
|
+
if (opts.onto && !shipBatch.parseBatchRef(opts.onto)) throw new UserError(`--onto ${opts.onto}: not a batch ref — expected ship-batch/<sha7> (#605)`);
|
|
13558
|
+
if (opts.batch && opts.json) return cmdShipBatchJson(opts); // #605: the batch's facts as JSON, prose on stderr
|
|
13458
13559
|
if (opts.batch) return cmdShipBatch(opts); // #373 — its own re-entrant path; nothing below changes
|
|
13459
13560
|
// A fully separate code path, deliberately: the prose/table path below is unchanged by this
|
|
13460
13561
|
// feature (CONVENTIONS/#77 requires it stay byte-identical), so --dry --json does its own
|
|
@@ -13646,7 +13747,18 @@ function cmdShip(argv) {
|
|
|
13646
13747
|
// #395: the branch's run must have been measured on a head that contains the base's CURRENT tip —
|
|
13647
13748
|
// B0 below syncs locally and never re-runs CI, so this is the only place a stale verdict is caught.
|
|
13648
13749
|
const staleResult = shipStaleBaseCheck(repoAbs, gh, target, sess.branch);
|
|
13649
|
-
|
|
13750
|
+
// #606: a docs-only branch needs no CI of its own — this row replaces the stale-base one (a red
|
|
13751
|
+
// run that exists still refuses), and the secret check stands in for the suite's secret scan.
|
|
13752
|
+
const docsCi = shipDocsOnlyCi(repoAbs, doc, target, sess.branch);
|
|
13753
|
+
let docsRowOk = true;
|
|
13754
|
+
if (docsCi.applies) {
|
|
13755
|
+
const row = docsOnlyBranchRow(docsCi, staleResult);
|
|
13756
|
+
checks.push([row.ok ? '✓' : '✗', 'branch CI (docs-only, #606)', row.detail]);
|
|
13757
|
+
checks.push([docsCi.scan.ok ? '✓' : '✗', 'docs-only secret check (#606)', docsCi.scan.reason]);
|
|
13758
|
+
docsRowOk = row.ok && docsCi.scan.ok;
|
|
13759
|
+
} else {
|
|
13760
|
+
checks.push([staleResult.ok ? '✓' : '✗', 'branch run contains current base (#395)', staleResult.detail]);
|
|
13761
|
+
}
|
|
13650
13762
|
|
|
13651
13763
|
// #350: the core-path review. A 'pending' verdict is not a failed precondition — it is the pause,
|
|
13652
13764
|
// taken below once every real precondition has passed, so it is the ONLY thing between the branch
|
|
@@ -13657,7 +13769,7 @@ function cmdShip(argv) {
|
|
|
13657
13769
|
|
|
13658
13770
|
// #581: a batch in flight at trunk's tip holds the lane. Like the core-path review's 'pending', a
|
|
13659
13771
|
// hold is not a failed precondition — it is a pause, taken below once every real one has passed.
|
|
13660
|
-
const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh);
|
|
13772
|
+
const lane = shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult);
|
|
13661
13773
|
if (lane) checks.push([lane.held ? '⏸' : '✓', 'no batch in flight (#581)', lane.detail]);
|
|
13662
13774
|
for (const w of coreReview.warnings) warn(`${coreReview.codeownersPath}: ${w}`);
|
|
13663
13775
|
|
|
@@ -13672,7 +13784,7 @@ function cmdShip(argv) {
|
|
|
13672
13784
|
// issue can be reopened, but the false claim stays in trunk's immutable history, and GitHub will
|
|
13673
13785
|
// have closed it the instant trunk was pushed. #263: gateOk joins the same list — an unticked
|
|
13674
13786
|
// checklist with no declared remainder is exactly as unrecoverable once `Closes #N` ships.
|
|
13675
|
-
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && staleResult.ok && coreOk && recOk;
|
|
13787
|
+
const preOk = ciOk && migOk && treeOk && corr.ok && gateOk && syncResult.ok && (docsCi.applies ? docsRowOk : staleResult.ok) && coreOk && recOk;
|
|
13676
13788
|
|
|
13677
13789
|
// ---- report the table ----
|
|
13678
13790
|
print(`ship ${shortRepo(repoAbs)} · branch ${sess.branch} → ${target}` +
|
|
@@ -14037,6 +14149,18 @@ function cmdShip(argv) {
|
|
|
14037
14149
|
return 1;
|
|
14038
14150
|
}
|
|
14039
14151
|
}
|
|
14152
|
+
// #606: the same for the docs-only CI path — B0 may have made the change something CI must see,
|
|
14153
|
+
// or added a line the secret check has not read. Re-measured on the synced branch.
|
|
14154
|
+
if (docsCi.applies) {
|
|
14155
|
+
const again = docsOnly.shipDocsOnly(git, repoAbs, mergeRef, sess.branch, doc);
|
|
14156
|
+
const rescan = again.docsOnly ? secretScan.scanBranch(git, repoAbs, mergeRef, sess.branch) : null;
|
|
14157
|
+
if (!again.docsOnly || !rescan.ok) {
|
|
14158
|
+
cleanupEphemeral();
|
|
14159
|
+
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`);
|
|
14160
|
+
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`);
|
|
14161
|
+
return 1;
|
|
14162
|
+
}
|
|
14163
|
+
}
|
|
14040
14164
|
if (autonomyGate.via === 'tuning') {
|
|
14041
14165
|
const again = configSet.branchTuning(git, repoAbs, mergeRef, sess.branch);
|
|
14042
14166
|
if (!again.tuning) {
|
|
@@ -14110,7 +14234,7 @@ function cmdShip(argv) {
|
|
|
14110
14234
|
}
|
|
14111
14235
|
// #581: re-read the lane right before the merge — B0 sits between the table and here, and a batch
|
|
14112
14236
|
// built in that window is exactly as live as one the table saw.
|
|
14113
|
-
const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) : null;
|
|
14237
|
+
const laneB1 = lane ? shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciCureForTrailer ? { cureVerdict: ciCureForTrailer } : null) : null;
|
|
14114
14238
|
if (laneB1 && laneB1.held) { cleanupEphemeral(); printBatchLanePause(laneB1, trunk); return 3; }
|
|
14115
14239
|
// WHERE the squash happens. Into trunk it is the main checkout, which is on trunk by invariant
|
|
14116
14240
|
// (and was just verified to be). Into a declared line it must NOT be: checking the main checkout
|
|
@@ -14473,7 +14597,7 @@ function cmdShip(argv) {
|
|
|
14473
14597
|
// same block, and re-assigning the collector here would silently discard them.
|
|
14474
14598
|
shipLandedTail({ repoAbs, sess, target, trunk, gh, sha, closeIssues, refsIssues, refsSet, integration, opts,
|
|
14475
14599
|
skipPrs: reviewPrHandled ? [reviewPrHandled] : [],
|
|
14476
|
-
evidenceExtra: (opts.humanDoorEvidence || '') + handoffEvidence(sess.handoff) }); // #525, #578
|
|
14600
|
+
evidenceExtra: (opts.humanDoorEvidence || '') + docsOnlyEvidence(docsCi, ciResult) + handoffEvidence(sess.handoff) }); // #525, #578, #606
|
|
14477
14601
|
|
|
14478
14602
|
print('');
|
|
14479
14603
|
print(`✓ Shipped ${sess.branch} → ${target} @ ${sha}${sess.issues.length ? ' (' + sess.issues.map((n) => '#' + n).join(' ') + ')' : ''}`);
|
|
@@ -14684,21 +14808,29 @@ function shipDryJsonReport(opts) {
|
|
|
14684
14808
|
* Inert (null, no git or gh call) unless project.yml declares ship-batch > 1, the merge target is
|
|
14685
14809
|
* trunk, and gh is usable. Out: null, or `{ held, ref, why, released, detail }`.
|
|
14686
14810
|
*/
|
|
14687
|
-
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh) {
|
|
14811
|
+
function shipBatchLaneCheck(repoAbs, doc, trunk, target, gh, ciResult = null) {
|
|
14688
14812
|
if (target !== trunk || !gh || shipBatch.parseShipBatch(doc).n <= 1) return null;
|
|
14813
|
+
// #605: a TRUNK RED: cure is never held by a batch (or a chain) — trunk is red, and the cure is the
|
|
14814
|
+
// way out; no batch can land on a red trunk anyway.
|
|
14815
|
+
if (ciResult && ciResult.cureVerdict && ciResult.cureVerdict.ok) {
|
|
14816
|
+
return { held: false, released: [], detail: 'a TRUNK RED: cure is never held by a batch (#605)' };
|
|
14817
|
+
}
|
|
14689
14818
|
const remote = git.remoteFor(repoAbs);
|
|
14690
14819
|
const ls = git.git(['ls-remote', remote, `refs/heads/${trunk}`, 'refs/heads/ship-batch/*'], repoAbs);
|
|
14691
14820
|
if (!ls.ok) return { held: false, released: [], detail: `could not read ${remote} — no batch provably in flight` };
|
|
14692
14821
|
const rows = ls.stdout.split('\n').map((l) => l.split('\t')).filter(([sha, ref]) => sha && ref);
|
|
14693
14822
|
const trunkNow = ((rows.find(([, ref]) => ref.trim() === `refs/heads/${trunk}`) || [])[0] || '').trim();
|
|
14694
|
-
|
|
14695
|
-
|
|
14823
|
+
// #605: the lane holder is the CHAIN rooted at trunk's tip — a batch built --onto another batch's head
|
|
14824
|
+
// reaches trunk only through it, so its run holds the lane exactly as the root's does.
|
|
14825
|
+
const refs = rows.map(([sha, ref]) => ({ sha: sha.trim(), parsed: shipBatch.parseBatchRef(ref.trim()) })).filter((x) => x.parsed);
|
|
14826
|
+
const chains = shipBatch.batchChains({ refs: refs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
|
|
14827
|
+
const atTip = refs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
14696
14828
|
const batches = atTip.map((x) => {
|
|
14697
14829
|
const runs = git.ghRunsForRef(repoAbs, x.parsed.ref, x.sha);
|
|
14698
14830
|
let t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs);
|
|
14699
14831
|
if (!t.ok) { git.git(['fetch', '-q', remote, `refs/heads/${x.parsed.ref}`], repoAbs); t = git.git(['log', '-1', '--format=%cI', x.sha], repoAbs); }
|
|
14700
14832
|
const built = t.ok ? Date.parse(t.stdout.trim()) : NaN;
|
|
14701
|
-
return { ref: x.parsed.ref, base7: x.parsed.base7, verdict: shipBatch.combinedVerdict(runs),
|
|
14833
|
+
return { ref: x.parsed.ref, base7: x.parsed.base7, rooted: true, verdict: shipBatch.combinedVerdict(runs),
|
|
14702
14834
|
builtAtMs: Number.isFinite(built) ? built : null, settledAtMs: shipBatch.settledAt(runs) };
|
|
14703
14835
|
});
|
|
14704
14836
|
const r = shipBatch.laneHold({ batches, trunkNow, nowMs: Date.now() });
|
|
@@ -14715,8 +14847,32 @@ function printBatchLanePause(lane, trunk) {
|
|
|
14715
14847
|
print(' or be declined (bounded, B1a — the same wait as any CI run), then run this command again.');
|
|
14716
14848
|
}
|
|
14717
14849
|
|
|
14850
|
+
/**
|
|
14851
|
+
* #605: `colab ship --batch … --dry --json` — the same single step as the prose path (it IS the prose
|
|
14852
|
+
* path, with its prose moved to stderr), plus one JSON document on stdout carrying the facts a caller
|
|
14853
|
+
* keys on: the batch ref, the ref it is chained onto, the trunk sha its chain is rooted at, the step
|
|
14854
|
+
* taken and the exit class, and one row per member. A caller never parses prose for the chain.
|
|
14855
|
+
*/
|
|
14856
|
+
function cmdShipBatchJson(opts) {
|
|
14857
|
+
const batch = { trunk: null, trunkSha: null, ref: null, parentRef: null, rootSha: null, base: null, depth: null, step: null, exit: null, error: null, members: [] };
|
|
14858
|
+
const was = PRINT_TO_STDERR;
|
|
14859
|
+
PRINT_TO_STDERR = true;
|
|
14860
|
+
let code;
|
|
14861
|
+
try { code = cmdShipBatch({ ...opts, _json: batch }); }
|
|
14862
|
+
catch (e) {
|
|
14863
|
+
if (!(e instanceof UserError)) throw e;
|
|
14864
|
+
process.stderr.write(`✗ ${e.message}\n`);
|
|
14865
|
+
batch.error = e.message;
|
|
14866
|
+
batch.step = batch.step || 'refused';
|
|
14867
|
+
code = 1;
|
|
14868
|
+
} finally { PRINT_TO_STDERR = was; }
|
|
14869
|
+
batch.exit = code;
|
|
14870
|
+
process.stdout.write(`${JSON.stringify({ batch }, null, 2)}\n`);
|
|
14871
|
+
return code;
|
|
14872
|
+
}
|
|
14873
|
+
|
|
14718
14874
|
function cmdShipBatch(opts) {
|
|
14719
|
-
for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ['json', '--json']]) {
|
|
14875
|
+
for (const [key, flag] of [['direct', '--direct'], ['worktree', '--worktree'], ['branch', '--branch'], ['message', '--message'], ['refs', '--refs'], ['adopt', '--adopt'], ...(opts._json ? [] : [['json', '--json']])]) {
|
|
14720
14876
|
if (opts[key]) throw new UserError(`--batch does not combine with ${flag} — each member ships with its own recorded claims and composed message (#373)`);
|
|
14721
14877
|
}
|
|
14722
14878
|
const repoAbs = resolveRepo(opts);
|
|
@@ -14730,7 +14886,12 @@ function cmdShipBatch(opts) {
|
|
|
14730
14886
|
const members = entries.members;
|
|
14731
14887
|
const handoffs = entries.handoffs;
|
|
14732
14888
|
if (members.includes(trunk)) throw new UserError(`Refusing: ${trunk} is the trunk itself — it cannot be a batch member`);
|
|
14889
|
+
const J = opts._json || {}; // #605: the --dry --json report, filled as the facts are read
|
|
14890
|
+
J.trunk = trunk;
|
|
14733
14891
|
const serial = (why, list = members) => {
|
|
14892
|
+
J.step = J.step && J.step !== 'build' ? J.step : 'serial';
|
|
14893
|
+
J.reason = why;
|
|
14894
|
+
if (!J.members || !J.members.length) J.members = list.map((b) => ({ branch: b, sha: null, eligible: null, inBatch: false, why }));
|
|
14734
14895
|
print(`✗ ship-batch: ${why}`);
|
|
14735
14896
|
print(shipBatch.serialLine(list));
|
|
14736
14897
|
return 4;
|
|
@@ -14791,6 +14952,7 @@ function cmdShipBatch(opts) {
|
|
|
14791
14952
|
const lsTrunk = git.git(['ls-remote', remote, `refs/heads/${trunk}`], repoAbs);
|
|
14792
14953
|
const trunkNow = lsTrunk.ok ? (lsTrunk.stdout.split('\t')[0] || '').trim() : '';
|
|
14793
14954
|
if (!trunkNow) throw new UserError(`could not read ${trunk} on ${remote}`);
|
|
14955
|
+
J.trunkSha = trunkNow;
|
|
14794
14956
|
const lsBatch = git.git(['ls-remote', remote, 'refs/heads/ship-batch/*'], repoAbs);
|
|
14795
14957
|
const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
|
|
14796
14958
|
.map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
|
|
@@ -14802,14 +14964,102 @@ function cmdShipBatch(opts) {
|
|
|
14802
14964
|
if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
|
|
14803
14965
|
return d.ok;
|
|
14804
14966
|
};
|
|
14805
|
-
|
|
14806
|
-
|
|
14967
|
+
// #605: the sweep is chain-aware. A ref built `--onto` another batch's head is kept while its chain
|
|
14968
|
+
// ends at a batch on trunk's tip (lib/ship-batch.js batchChains, read from ls-remote alone); a ref
|
|
14969
|
+
// whose parent is gone, or whose root trunk has moved past, is deleted. Without any chained ref this
|
|
14970
|
+
// is exactly the old sweep: every ref not built on trunk's tip goes.
|
|
14971
|
+
const chains = shipBatch.batchChains({ refs: batchRefs.map((x) => ({ ref: x.parsed.ref, base7: x.parsed.base7, sha: x.sha })), trunkNow });
|
|
14972
|
+
const carriedBy = (ref, from, sha) => {
|
|
14973
|
+
const lg = git.git(['log', '--format=%B%x00', `${from}..${sha}`], repoAbs);
|
|
14974
|
+
return shipBatch.parseMemberTrailers(lg.ok ? lg.stdout.split('\0') : []).filter((m) => m.ref === ref).reverse();
|
|
14975
|
+
};
|
|
14976
|
+
const swept = [];
|
|
14977
|
+
for (const b of batchRefs.filter((x) => !chains.get(x.parsed.ref).rooted)) {
|
|
14978
|
+
const c = chains.get(b.parsed.ref);
|
|
14979
|
+
// A ref built on a head trunk never reached (an orphaned chain link) may still have its run going;
|
|
14980
|
+
// nothing can ever land it, so cancel that run. A ref on an OLD trunk tip is today's case, untouched.
|
|
14981
|
+
const baseFull = git.git(['rev-parse', '--verify', '-q', `${b.parsed.base7}^{commit}`], repoAbs);
|
|
14982
|
+
const offTrunk = !baseFull.ok || !git.git(['merge-base', '--is-ancestor', baseFull.stdout.trim(), trunkNow], repoAbs).ok;
|
|
14983
|
+
if (offTrunk) {
|
|
14984
|
+
print(` ${b.parsed.ref} is not rooted at ${trunk}'s tip — ${c.why}; nothing landed from it; deleting it`);
|
|
14985
|
+
for (const r of (git.ghRunsForRef(repoAbs, b.parsed.ref, b.sha) || []).filter((x) => x.status !== 'completed' && x.databaseId)) {
|
|
14986
|
+
if (opts.dry) { print(` [dry] would cancel run ${r.databaseId} on ${b.parsed.ref}`); continue; }
|
|
14987
|
+
const cx = git.ghRunCancel(repoAbs, r.databaseId);
|
|
14988
|
+
if (!cx.ok) warn(`could not cancel run ${r.databaseId} on ${b.parsed.ref} — it will finish on a ref that is gone`);
|
|
14989
|
+
}
|
|
14990
|
+
} else {
|
|
14991
|
+
print(` trunk moved since ${b.parsed.ref} was built (${b.parsed.base7} → ${shortSha(trunkNow)}) — nothing landed; rebuilding`);
|
|
14992
|
+
}
|
|
14993
|
+
swept.push({ ref: b.parsed.ref, members: offTrunk ? carriedBy(b.parsed.ref, trunkNow, b.sha) : [] });
|
|
14807
14994
|
deleteRef(b.parsed.ref);
|
|
14808
14995
|
}
|
|
14809
|
-
const
|
|
14996
|
+
const rooted = batchRefs.filter((x) => chains.get(x.parsed.ref).rooted);
|
|
14997
|
+
// Every member the chain up to `sha` carries (branch → the ref carrying it), read from its trailers.
|
|
14998
|
+
const carriedByChain = (sha) => new Map(shipBatch.parseMemberTrailers((() => {
|
|
14999
|
+
const lg = git.git(['log', '--format=%B%x00', `${trunkNow}..${sha}`], repoAbs);
|
|
15000
|
+
return lg.ok ? lg.stdout.split('\0') : [];
|
|
15001
|
+
})()).map((m) => [m.branch, m.ref]));
|
|
15002
|
+
|
|
15003
|
+
// #605: --onto <ship-batch ref> builds on that ref's HEAD instead of trunk's tip. `base` is what the
|
|
15004
|
+
// batch sits on from here on; without --onto it is trunk's tip, and nothing below changes.
|
|
15005
|
+
let base = trunkNow;
|
|
15006
|
+
let parent = null; // { ref, sha, chain, verdict } while the parent has not landed
|
|
15007
|
+
if (opts.onto) {
|
|
15008
|
+
const want = shipBatch.parseBatchRef(opts.onto).ref;
|
|
15009
|
+
const p = batchRefs.find((x) => x.parsed.ref === want) || null;
|
|
15010
|
+
const ours = swept.find((x) => x.members.some((m) => members.includes(m.branch)));
|
|
15011
|
+
if (p && p.sha === trunkNow) {
|
|
15012
|
+
print(` ${want} has landed — ${trunk} is at its head ${shortSha(trunkNow)}; this batch sits on ${trunk}'s tip`);
|
|
15013
|
+
} else if (!p || !chains.get(want).rooted) {
|
|
15014
|
+
if (ours) {
|
|
15015
|
+
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.`);
|
|
15016
|
+
J.step = 'chained-decline';
|
|
15017
|
+
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));
|
|
15018
|
+
}
|
|
15019
|
+
// The parent landed and its lander deleted the ref: our batch (if staged) now sits on trunk's tip.
|
|
15020
|
+
const atTip = rooted.find((x) => trunkNow.startsWith(x.parsed.base7));
|
|
15021
|
+
const landedParent = !p && atTip && carriedBy(atTip.parsed.ref, trunkNow, atTip.sha).some((m) => members.includes(m.branch));
|
|
15022
|
+
if (!landedParent && p) {
|
|
15023
|
+
throw new UserError(`--onto ${want}: it is not rooted at ${trunk}'s tip (${chains.get(want).why}) — build on ${trunk} instead (drop --onto)`);
|
|
15024
|
+
}
|
|
15025
|
+
if (!landedParent) {
|
|
15026
|
+
// ls-remote cannot tell "never existed" from "discarded" or "trunk moved some other way" — and
|
|
15027
|
+
// for the last two the issue's rule is a decline. So a missing parent declines: nothing of
|
|
15028
|
+
// this chain can land in order, and the members go back to the queue (#605).
|
|
15029
|
+
J.step = 'chained-decline';
|
|
15030
|
+
print(`✗ ship-batch: --onto ${want}: no such batch ref on ${remote} — it was discarded, landed under other members, or never existed.`);
|
|
15031
|
+
return serial(`nothing to chain onto — build on ${trunk} instead (the same command without --onto)`);
|
|
15032
|
+
}
|
|
15033
|
+
print(` ${want} is gone and ${atTip.parsed.ref} at ${trunk}'s tip carries this batch — its parent landed; resuming on ${trunk}'s tip`);
|
|
15034
|
+
} else {
|
|
15035
|
+
const pc = chains.get(want);
|
|
15036
|
+
const verdict = shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, want, p.sha));
|
|
15037
|
+
const child = rooted.find((x) => x !== p && p.sha.startsWith(x.parsed.base7)) || null;
|
|
15038
|
+
if (verdict.state === 'red') {
|
|
15039
|
+
if (child) {
|
|
15040
|
+
const carried = carriedBy(child.parsed.ref, p.sha, child.sha);
|
|
15041
|
+
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.`);
|
|
15042
|
+
deleteRef(child.parsed.ref);
|
|
15043
|
+
J.step = 'chained-decline';
|
|
15044
|
+
return serial(`its parent ${want} was declined — rebuild on ${trunk} once it is settled`, carried.length ? carried.map((m) => m.branch) : members);
|
|
15045
|
+
}
|
|
15046
|
+
throw new UserError(`--onto ${want}: its combined run is red (${verdict.why}) — nothing to chain onto; build on ${trunk} instead (drop --onto)`);
|
|
15047
|
+
}
|
|
15048
|
+
if (verdict.state === 'none' && !child) {
|
|
15049
|
+
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`);
|
|
15050
|
+
}
|
|
15051
|
+
if (!child && pc.depth >= shipBatch.MAX_CHAIN_DEPTH) {
|
|
15052
|
+
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`);
|
|
15053
|
+
}
|
|
15054
|
+
base = p.sha;
|
|
15055
|
+
parent = { ref: want, sha: p.sha, chain: pc, verdict };
|
|
15056
|
+
}
|
|
15057
|
+
}
|
|
15058
|
+
Object.assign(J, { base, parentRef: parent ? parent.ref : null, rootSha: trunkNow, depth: parent ? parent.chain.depth + 1 : 1, ref: shipBatch.batchRefName(base) });
|
|
15059
|
+
const atBase = rooted.find((x) => (!parent || x.parsed.ref !== parent.ref) && base.startsWith(x.parsed.base7)) || null;
|
|
14810
15060
|
let existing = null;
|
|
14811
15061
|
if (atBase) {
|
|
14812
|
-
const log = git.git(['log', '--format=%B%x00', `${
|
|
15062
|
+
const log = git.git(['log', '--format=%B%x00', `${base}..${atBase.sha}`], repoAbs);
|
|
14813
15063
|
const inBatch = shipBatch.parseMemberTrailers(log.ok ? log.stdout.split('\0') : []).reverse();
|
|
14814
15064
|
const foreign = inBatch.filter((m) => !members.includes(m.branch));
|
|
14815
15065
|
// #391: a DECLINED batch (combined run red) is not in flight — clear it and build the one asked for.
|
|
@@ -14839,7 +15089,10 @@ function cmdShipBatch(opts) {
|
|
|
14839
15089
|
}
|
|
14840
15090
|
}
|
|
14841
15091
|
const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
|
|
14842
|
-
|
|
15092
|
+
// #605: a chained batch is measured against its own base (the parent's head), not trunk's tip.
|
|
15093
|
+
let step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: members.length, existing, trunkNow: base, verdict, split: !!opts.split });
|
|
15094
|
+
J.step = step.step;
|
|
15095
|
+
if (existing) J.members = existing.members.map((m) => ({ branch: m.branch, sha: m.sha, eligible: true, inBatch: true, why: `staged in ${existing.ref}` }));
|
|
14843
15096
|
if (opts.split && !(verdict && verdict.state === 'red')) {
|
|
14844
15097
|
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)`);
|
|
14845
15098
|
}
|
|
@@ -14888,15 +15141,33 @@ function cmdShipBatch(opts) {
|
|
|
14888
15141
|
print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
|
|
14889
15142
|
return 4;
|
|
14890
15143
|
}
|
|
15144
|
+
if (step.step === 'land' && parent) {
|
|
15145
|
+
// #605: land in order — only once trunk's tip IS the parent's head. Until then the parent is in
|
|
15146
|
+
// flight (wait, exit 3); a parent that is red will never land at that sha (delete, exit 4).
|
|
15147
|
+
const ls = shipBatch.chainedLandStep({ parent: parent.chain, parentVerdict: parent.verdict });
|
|
15148
|
+
J.step = ls.step === 'wait' ? 'chained-wait' : 'chained-decline';
|
|
15149
|
+
J.reason = ls.why;
|
|
15150
|
+
if (ls.step === 'wait') {
|
|
15151
|
+
print(`⏸ BATCH-CHAINED ${existing.ref}@${shortSha(existing.sha)} — combined run green; it lands after ${parent.ref}: ${ls.why}. Nothing landed.`);
|
|
15152
|
+
print(` Wait for ${parent.ref} to land (bounded, B1a), then run this command again — it lands with no second run.`);
|
|
15153
|
+
return 3;
|
|
15154
|
+
}
|
|
15155
|
+
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.`);
|
|
15156
|
+
deleteRef(existing.ref);
|
|
15157
|
+
return serial('its parent batch was discarded', existing.members.map((m) => m.branch));
|
|
15158
|
+
}
|
|
14891
15159
|
if (step.step === 'land') return shipBatchLand(repoAbs, doc, trunk, remote, trunkNow, existing, verdict, opts);
|
|
14892
15160
|
|
|
14893
15161
|
// ---- (d) pick the members — each through its OWN ship gates ----
|
|
14894
15162
|
const st = state.loadState();
|
|
14895
15163
|
const evaluated = [];
|
|
15164
|
+
// #605: a member the chain below already carries lands with that batch — it never joins a second one.
|
|
15165
|
+
const inChain = parent ? carriedByChain(parent.sha) : new Map();
|
|
14896
15166
|
for (const b of members) {
|
|
14897
15167
|
const refs = git.branchRefs(repoAbs, b, remote);
|
|
14898
15168
|
let why = null, report = null, ciClass = null, files = [];
|
|
14899
15169
|
if (!refs.remoteSha) why = `not on ${remote} — push it first; its CI has never seen it`;
|
|
15170
|
+
else if (inChain.has(b)) why = `already in ${inChain.get(b)} — it lands with that batch, not this one`;
|
|
14900
15171
|
else if (refs.localSha && refs.localSha !== refs.remoteSha) why = `local ${shortSha(refs.localSha)} ≠ ${remote} ${shortSha(refs.remoteSha)} — its CI never saw this head`;
|
|
14901
15172
|
if (!why) {
|
|
14902
15173
|
// #591: a hand-off member is read through the SAME door a single --handoff ship uses
|
|
@@ -14929,12 +15200,13 @@ function cmdShipBatch(opts) {
|
|
|
14929
15200
|
return { selected: sel, overflow: eligible.filter((e) => !sel.includes(e)) };
|
|
14930
15201
|
})()
|
|
14931
15202
|
: shipBatch.selectMembers(eligible, size, { isGenerated: (f) => isGeneratedPath(f, generated) });
|
|
14932
|
-
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]' : ''}`);
|
|
15203
|
+
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]' : ''}`);
|
|
14933
15204
|
print(table(evaluated.map((e) => [e.ok ? (selected.includes(e) ? '✓' : '·') : '✗', e.branch,
|
|
14934
15205
|
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']));
|
|
14935
15206
|
const notJoining = evaluated.filter((e) => !selected.includes(e)).map((e) => e.branch);
|
|
15207
|
+
J.members = evaluated.map((e) => ({ branch: e.branch, sha: e.sha || null, eligible: e.ok, inBatch: selected.includes(e), why: e.why }));
|
|
14936
15208
|
step = shipBatch.nextStep({ enabled: true, wired: true, trunkCi, eligibleCount: selected.length, existing: null, trunkNow });
|
|
14937
|
-
if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf) {
|
|
15209
|
+
if (step.step === 'build' && selected.length === 1 && waitCfg.sec > 0 && !splitHalf && !parent) {
|
|
14938
15210
|
// #555: the lane is idle here (trunk's run finished, no batch in flight at this base), and one
|
|
14939
15211
|
// member is ready. Wait for a partner until the repo's window, counted from when it became ready.
|
|
14940
15212
|
const lone = selected[0];
|
|
@@ -14953,10 +15225,11 @@ function cmdShipBatch(opts) {
|
|
|
14953
15225
|
if (step.step === 'serial') return serial('no member can join — each one above says why');
|
|
14954
15226
|
|
|
14955
15227
|
// ---- (e) build: trunk head + one squash commit per member, in an ephemeral detached worktree ----
|
|
14956
|
-
|
|
15228
|
+
// #605: on a chain, the batch is built on the parent's head and named after it — one batch per base.
|
|
15229
|
+
const ref = shipBatch.batchRefName(base);
|
|
14957
15230
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'colab-ship-batch-'));
|
|
14958
|
-
const add = git.git(['worktree', 'add', '--detach', dir,
|
|
14959
|
-
if (!add.ok) { try { fs.rmdirSync(dir); } catch (_) {} throw new UserError(`could not check out ${shortSha(
|
|
15231
|
+
const add = git.git(['worktree', 'add', '--detach', dir, base], repoAbs);
|
|
15232
|
+
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)}`); }
|
|
14960
15233
|
const cleanup = () => git.git(['worktree', 'remove', '--force', dir], repoAbs);
|
|
14961
15234
|
const machineLine = shipMachineTrailerDecision(repoAbs, doc).line;
|
|
14962
15235
|
const built = [];
|
|
@@ -15024,6 +15297,8 @@ function cmdShipBatch(opts) {
|
|
|
15024
15297
|
built.push({ ...m, regenerated, commit: git.git(['rev-parse', 'HEAD'], dir).stdout });
|
|
15025
15298
|
}
|
|
15026
15299
|
for (const d of dropped) print(` ✗ ${d.branch}: ${d.why}`);
|
|
15300
|
+
for (const d of dropped) Object.assign(J.members.find((r) => r.branch === d.branch) || {}, { inBatch: false, why: d.why });
|
|
15301
|
+
J.step = 'build';
|
|
15027
15302
|
// #554: a drop leaves a durable trace — one Ship-Batch-Dropped trailer per dropped member on the
|
|
15028
15303
|
// batch head, so it reaches trunk with a landed batch and rides a red combined run's head message.
|
|
15029
15304
|
// Only when the batch is built (≥1 member, #562): a build that collapses to serial pushes nothing.
|
|
@@ -15049,8 +15324,10 @@ function cmdShipBatch(opts) {
|
|
|
15049
15324
|
}
|
|
15050
15325
|
if (opts.dry) {
|
|
15051
15326
|
cleanup();
|
|
15052
|
-
print(`→ READY: would push ${ref} = ${shortSha(
|
|
15053
|
-
print(
|
|
15327
|
+
print(`→ READY: would push ${ref} = ${shortSha(base)} + ${built.length} squash commit(s): ${built.map((b) => b.branch).join(', ')}`);
|
|
15328
|
+
print(parent
|
|
15329
|
+
? ` then wait on ONE combined run, and fast-forward trunk to it only once ${parent.ref} has landed at ${shortSha(parent.sha)} (#605).`
|
|
15330
|
+
: ' then wait on ONE combined run, and fast-forward trunk to it only if trunk has not moved.');
|
|
15054
15331
|
if (notJoining.length || dropped.length) print(` not in this batch: ${[...new Set([...notJoining, ...dropped.map((d) => d.branch)])].join(', ')}`);
|
|
15055
15332
|
return 0;
|
|
15056
15333
|
}
|
|
@@ -15058,7 +15335,7 @@ function cmdShipBatch(opts) {
|
|
|
15058
15335
|
const push = git.run('git', ['push', '--force', remote, `${head}:refs/heads/${ref}`], { cwd: repoAbs });
|
|
15059
15336
|
cleanup();
|
|
15060
15337
|
if (!push.ok) throw new UserError(`could not push ${ref}: ${git.gitFailureLine(push.stderr)} — nothing landed`);
|
|
15061
|
-
print(` pushed ${ref} = ${shortSha(
|
|
15338
|
+
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` : ''}`);
|
|
15062
15339
|
if (overflow.length) print(` eligible but ${splitHalf ? 'held by the split' : 'over the cap'} (next batch): ${overflow.map((o) => o.branch).join(', ')}`);
|
|
15063
15340
|
print(`⏸ BATCH-PENDING ${ref}@${shortSha(head)} — wait on the combined run (bounded, B1a), then run this command again. Nothing landed yet.`);
|
|
15064
15341
|
return 3;
|
|
@@ -16854,7 +17131,9 @@ re-running install.sh; \`colab update\` reports it when it is behind. \`colab --
|
|
|
16854
17131
|
which of the two you are talking to.
|
|
16855
17132
|
`;
|
|
16856
17133
|
|
|
16857
|
-
|
|
17134
|
+
// #605: `ship --batch --dry --json` keeps stdout for its one JSON document; the prose goes to stderr.
|
|
17135
|
+
let PRINT_TO_STDERR = false;
|
|
17136
|
+
function print(s) { (PRINT_TO_STDERR ? process.stderr : process.stdout).write(s.endsWith('\n') ? s : s + '\n'); return 0; }
|
|
16858
17137
|
function warn(s) { process.stderr.write(`! ${s}\n`); }
|
|
16859
17138
|
/**
|
|
16860
17139
|
* `colab ship` sets this to an array while it runs B3 (worktree teardown) through B4 (per-issue
|
package/tools/lib/docs-only.js
CHANGED
|
@@ -8,15 +8,33 @@
|
|
|
8
8
|
* caller. Nothing here takes a list, a flag, an env var or a project.yml field. The allowlist and the
|
|
9
9
|
* exclusions below are constants, so widening them is a handbook change reviewed in a commit.
|
|
10
10
|
*
|
|
11
|
-
* Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary
|
|
12
|
-
*
|
|
13
|
-
* approved.
|
|
11
|
+
* Every doubt resolves to "not docs-only": an empty diff, a git read that failed, a binary (other
|
|
12
|
+
* than a design artifact under `docs/`, below), a symlink, a submodule pointer. A false "no" costs a
|
|
13
|
+
* human click. A false "yes" merges code nobody approved.
|
|
14
|
+
*
|
|
15
|
+
* #606: the same rule also decides when `colab ship` lands a change WITHOUT WAITING FOR CI
|
|
16
|
+
* (shipDocsOnly, below — on by default, narrowed by `ci-docs-skip`). So widening anything here
|
|
17
|
+
* widens BOTH at once — the binary design-artifact rule below did exactly that: a PNG mockup under
|
|
18
|
+
* `docs/design/` is now docs-only for the autonomy exception too (CONVENTIONS.md §2).
|
|
14
19
|
*/
|
|
15
20
|
|
|
16
21
|
/** Extensions that count as documentation. Compared exactly (`README.MD` does not match). */
|
|
17
22
|
const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
|
|
18
23
|
/** A path under this top-level directory counts as documentation whatever its extension. */
|
|
19
24
|
const DOCS_DIR = 'docs/';
|
|
25
|
+
/**
|
|
26
|
+
* #606: a BINARY under `docs/` with one of these extensions is a design artifact (a mockup, a
|
|
27
|
+
* diagram, a printed spec) and counts as documentation. Case-insensitive (`Mock.PNG` matches). Any
|
|
28
|
+
* other binary under `docs/`, and every binary outside it, is still not docs-only.
|
|
29
|
+
*/
|
|
30
|
+
const DOCS_BINARY_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.pdf']);
|
|
31
|
+
function docsBinaryOk(p) {
|
|
32
|
+
const s = String(p);
|
|
33
|
+
if (!s.startsWith(DOCS_DIR)) return false;
|
|
34
|
+
const base = s.slice(s.lastIndexOf('/') + 1);
|
|
35
|
+
const dot = base.lastIndexOf('.');
|
|
36
|
+
return dot > 0 && DOCS_BINARY_EXTENSIONS.includes(base.slice(dot).toLowerCase());
|
|
37
|
+
}
|
|
20
38
|
/** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
|
|
21
39
|
const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
|
|
22
40
|
/**
|
|
@@ -77,15 +95,18 @@ function pathReason(p) {
|
|
|
77
95
|
* Returns `{ docsOnly, files, offenders: [{ path, reason }], reason }`. `files` counts distinct paths.
|
|
78
96
|
* `reason` is one line for a human, set on both outcomes.
|
|
79
97
|
*/
|
|
80
|
-
function classify(entries) {
|
|
98
|
+
function classify(entries, { exclude = [] } = {}) {
|
|
81
99
|
const paths = new Map();
|
|
82
100
|
for (const e of entries || []) {
|
|
83
101
|
const why = [];
|
|
84
102
|
const nameWhy = pathReason(e.path);
|
|
85
103
|
if (nameWhy) why.push(nameWhy);
|
|
104
|
+
// #606: a path the repo's suite reads, listed in `ci-docs-skip` — documentation, but it needs CI.
|
|
105
|
+
const listed = excludedBy(e.path, exclude);
|
|
106
|
+
if (!nameWhy && listed) why.push(`listed in ci-docs-skip (${listed}) — the suite reads it`);
|
|
86
107
|
if (e.oldMode === MODE_SYMLINK || e.newMode === MODE_SYMLINK) why.push('symlink change');
|
|
87
108
|
if (e.oldMode === MODE_GITLINK || e.newMode === MODE_GITLINK) why.push('submodule change');
|
|
88
|
-
if (e.binary) why.push('binary change');
|
|
109
|
+
if (e.binary && !docsBinaryOk(e.path)) why.push('binary change');
|
|
89
110
|
const prev = paths.get(e.path) || [];
|
|
90
111
|
paths.set(e.path, [...new Set([...prev, ...why])]);
|
|
91
112
|
}
|
|
@@ -101,6 +122,12 @@ function classify(entries) {
|
|
|
101
122
|
return { docsOnly: true, files, offenders: [], reason: `docs-only (${files} files)` };
|
|
102
123
|
}
|
|
103
124
|
|
|
125
|
+
/** The `ci-docs-skip` member `p` is, or sits under — a path prefix, never a string prefix. */
|
|
126
|
+
function excludedBy(p, exclude) {
|
|
127
|
+
const s = String(p);
|
|
128
|
+
return (exclude || []).find((x) => s === x || s.startsWith(`${x}/`)) || null;
|
|
129
|
+
}
|
|
130
|
+
|
|
104
131
|
/**
|
|
105
132
|
* Parse `git diff --raw -z --no-renames --no-abbrev` output into
|
|
106
133
|
* `[{ path, oldMode, newMode, oldSha, newSha, status }]`. The sha/status fields are additive
|
|
@@ -151,10 +178,30 @@ function readEntries(git, repo, cmd, range) {
|
|
|
151
178
|
* The branch shape: what `branch` changes relative to its merge base with `base` — the same three-dot
|
|
152
179
|
* diff the squash would land.
|
|
153
180
|
*/
|
|
154
|
-
function branchChanges(git, repo, base, branch) {
|
|
181
|
+
function branchChanges(git, repo, base, branch, opts = {}) {
|
|
155
182
|
const entries = readEntries(git, repo, 'diff', [`${base}...${branch}`, '--']);
|
|
156
183
|
if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read the diff ${base}...${branch}` };
|
|
157
|
-
return classify(entries);
|
|
184
|
+
return classify(entries, opts);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** One commit's own change (against its parent(s), `diff-tree -m`) — the shape a trunk squash has. */
|
|
188
|
+
function commitChanges(git, repo, sha, opts = {}) {
|
|
189
|
+
const entries = readEntries(git, repo, 'diff-tree', [sha]);
|
|
190
|
+
if (!entries) return { docsOnly: false, files: 0, offenders: [], reason: `could not read commit ${String(sha).slice(0, 7)}` };
|
|
191
|
+
return classify(entries, opts);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* #606: does `colab ship` treat this branch as needing no CI? The SAME classification as the
|
|
196
|
+
* autonomy exception (#345), narrowed by the repo's `ci-docs-skip` list — a path the suite reads is
|
|
197
|
+
* documentation but still needs CI — and switched off entirely by `ci-docs-skip: off`. An invalid
|
|
198
|
+
* value reads as off (every reader takes doubt as "CI required"); the audit fails it.
|
|
199
|
+
* Returns the classify() shape plus `{ setting }` (parseCiDocsSkip's verdict).
|
|
200
|
+
*/
|
|
201
|
+
function shipDocsOnly(git, repo, base, branch, doc) {
|
|
202
|
+
const setting = parseCiDocsSkip(doc);
|
|
203
|
+
if (!setting.on) return { docsOnly: false, files: 0, offenders: [], reason: setting.reason, setting };
|
|
204
|
+
return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude }), setting };
|
|
158
205
|
}
|
|
159
206
|
|
|
160
207
|
/**
|
|
@@ -179,24 +226,32 @@ function directChanges(git, repo, trunk, since) {
|
|
|
179
226
|
}
|
|
180
227
|
|
|
181
228
|
/**
|
|
182
|
-
* #570: `ci-docs-skip:` in project.yml —
|
|
183
|
-
*
|
|
184
|
-
*
|
|
229
|
+
* #570/#606: `ci-docs-skip:` in project.yml — which changes `colab ship` may land without waiting for
|
|
230
|
+
* CI (#606), and the paths the CI templates' legacy guard (#570) excludes. ON BY DEFAULT for ship:
|
|
231
|
+
* absent = on, nothing excluded. A list = on, and each member is a repo path whose changes always run
|
|
232
|
+
* the suite even though this module calls them documentation (`docs/api/` feeding a generator, a
|
|
233
|
+
* README a link checker reads). `[]` = on, nothing excluded. `off` = the one opt-out, for a repo whose
|
|
234
|
+
* suite reads most of its docs (YAML 1.1 readers turn a bare `off` into boolean false; both spell it).
|
|
185
235
|
*
|
|
186
|
-
* The CI guard parses the same
|
|
187
|
-
*
|
|
188
|
-
*
|
|
189
|
-
*
|
|
236
|
+
* The legacy CI guard parses the same list in shell, but stays opt-in until its follow-up removes it:
|
|
237
|
+
* there `off` and absent both mean "run the full suite". Both readers take anything else — an empty
|
|
238
|
+
* `ci-docs-skip:` included — as "CI required", the stricter direction. So an invalid value here is a finding:
|
|
239
|
+
* a declaration that silently opts the repo out. Members are plain paths (the guard matches `p == x`
|
|
240
|
+
* or `p` under `x/`): no glob, no `..` or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
|
|
190
241
|
*/
|
|
191
242
|
const CI_DOCS_SKIP_KEY = 'ci-docs-skip';
|
|
192
243
|
function parseCiDocsSkip(doc) {
|
|
193
244
|
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, CI_DOCS_SKIP_KEY);
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
245
|
+
if (!has) {
|
|
246
|
+
return { declared: false, valid: true, on: true, exclude: [], reason: 'ci-docs-skip absent — on by default (#606): colab ship lands a docs-only change without waiting for CI' };
|
|
247
|
+
}
|
|
248
|
+
const v = doc[CI_DOCS_SKIP_KEY];
|
|
249
|
+
if (v === 'off' || v === false) {
|
|
250
|
+
return { declared: true, valid: true, on: false, exclude: null, reason: 'ci-docs-skip: off — colab ship requires CI for every change' };
|
|
197
251
|
}
|
|
198
252
|
const bad = (why) => ({ declared: true, valid: false, on: false, exclude: null,
|
|
199
|
-
reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none)
|
|
253
|
+
reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none) or \`off\`; every reader takes anything else as "CI required", so the declaration silently opts this repo out of the docs-only path` });
|
|
254
|
+
if (v === null || v === undefined) return bad('is empty');
|
|
200
255
|
if (!Array.isArray(v)) return bad(`is ${JSON.stringify(v)}`);
|
|
201
256
|
const exclude = [];
|
|
202
257
|
for (const m of v) {
|
|
@@ -207,11 +262,11 @@ function parseCiDocsSkip(doc) {
|
|
|
207
262
|
exclude.push(s);
|
|
208
263
|
}
|
|
209
264
|
return { declared: true, valid: true, on: true, exclude,
|
|
210
|
-
reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — a docs-only change
|
|
265
|
+
reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — colab ship lands a docs-only change without waiting for CI' };
|
|
211
266
|
}
|
|
212
267
|
|
|
213
268
|
module.exports = {
|
|
214
|
-
DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
|
|
269
|
+
DOC_EXTENSIONS, DOCS_DIR, DOCS_BINARY_EXTENSIONS, docsBinaryOk, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
|
|
215
270
|
pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
|
|
216
|
-
CI_DOCS_SKIP_KEY, parseCiDocsSkip,
|
|
271
|
+
CI_DOCS_SKIP_KEY, parseCiDocsSkip, excludedBy, commitChanges, shipDocsOnly,
|
|
217
272
|
};
|
package/tools/lib/git.js
CHANGED
|
@@ -755,6 +755,11 @@ function ghPrClose(repo, num, comment) {
|
|
|
755
755
|
return gh(['pr', 'close', String(num), '--comment', comment], { cwd: repo });
|
|
756
756
|
}
|
|
757
757
|
|
|
758
|
+
/** #605: cancel one workflow run (a deleted batch ref's run still in flight). The run result, ok or not. */
|
|
759
|
+
function ghRunCancel(repo, id) {
|
|
760
|
+
return gh(['run', 'cancel', String(id)], { cwd: repo });
|
|
761
|
+
}
|
|
762
|
+
|
|
758
763
|
function ghIssueComment(repo, issueNum, body) {
|
|
759
764
|
const r = gh(['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
|
|
760
765
|
if (r.ok || !isGraphqlRateLimit(r.stderr)) return r;
|
|
@@ -1441,5 +1446,5 @@ module.exports = {
|
|
|
1441
1446
|
ghRunJobCount, ghRunJobs, ghWorkflowDispatch,
|
|
1442
1447
|
ghIssueListByLabel, ghLabelDelete, ghLabelCreate, ghListLabelsDetailed, ghLabelEditDescription,
|
|
1443
1448
|
ghApi, isGraphqlRateLimit, ghIssueRelease, ghClaimHolder, ghIssueLabelEvents, ghIssueLabelActors,
|
|
1444
|
-
ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility,
|
|
1449
|
+
ghPrForBranch, ghOpenPrsForBranch, ghOpenPrs, ghPrCreate, ghPrClose, ghRepoVisibility, ghRunCancel,
|
|
1445
1450
|
};
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* #606 — the secret check `colab ship` runs on a DOCS-ONLY change before it merges.
|
|
4
|
+
*
|
|
5
|
+
* A docs-only change lands without waiting for CI (tools/lib/docs-only.js shipDocsOnly), so the CI
|
|
6
|
+
* suite's own secret scan (gitleaks in the templates) may never see it. This is the cheap stand-in:
|
|
7
|
+
* the lines the change ADDS — `git diff -U0 <base>...<branch>`, text files only (git prints no lines
|
|
8
|
+
* for a binary) — matched against generic credential shapes, plus the repo's own forbidden terms
|
|
9
|
+
* when it keeps a file at TERMS_PATH. Seconds, no dependency, no network.
|
|
10
|
+
*
|
|
11
|
+
* A finding is reported as `file:line (rule)`, never with the matched text: the refusal is printed
|
|
12
|
+
* to a terminal and may be pasted onto an Issue, and a public repo's Issues are public.
|
|
13
|
+
*
|
|
14
|
+
* It is a backstop, not gitleaks: generic shapes only, added lines only. A shape it misses is
|
|
15
|
+
* missed; nothing here claims the change is clean beyond these rules.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** The repo-local forbidden-terms file (project.schema.md "ci-docs-skip"), read at the TARGET's tip. */
|
|
19
|
+
const TERMS_PATH = '.github/secret-scan-terms';
|
|
20
|
+
|
|
21
|
+
/** Generic credential shapes. `test` gets one added line. */
|
|
22
|
+
const RULES = Object.freeze([
|
|
23
|
+
{ rule: 'private key', re: /-----BEGIN ([A-Z0-9]+ )*PRIVATE KEY( BLOCK)?-----/ },
|
|
24
|
+
{ rule: 'AWS access key', re: /(^|[^A-Z0-9])(AKIA|ASIA)[A-Z0-9]{16}([^A-Z0-9]|$)/ },
|
|
25
|
+
{ rule: 'GitHub token', re: /(gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{60,})/ },
|
|
26
|
+
{ rule: 'Slack token', re: /xox[abposr]-[A-Za-z0-9-]{10,}/ },
|
|
27
|
+
{ rule: 'Google API key', re: /AIza[0-9A-Za-z_-]{35}/ },
|
|
28
|
+
{ rule: 'Stripe live key', re: /(sk|rk)_live_[0-9A-Za-z]{20,}/ },
|
|
29
|
+
{ rule: 'LLM API key', re: /sk-(ant|proj)-[A-Za-z0-9_-]{20,}/ },
|
|
30
|
+
]);
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* `password=…` and its kin. The value must hold a lower-case letter AND a digit, so a documented
|
|
34
|
+
* placeholder (`YOUR_API_KEY`, `changeme`, `$PASSWORD`, `<secret>`, `${{ secrets.X }}`) is not a
|
|
35
|
+
* finding while `password=hunter22` is.
|
|
36
|
+
*/
|
|
37
|
+
const ASSIGN = /(password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)["']?\s*[:=]\s*["']?([^"'\s<>{}$]{8,})/i;
|
|
38
|
+
function assignment(line) {
|
|
39
|
+
const m = ASSIGN.exec(line);
|
|
40
|
+
return !!m && /[0-9]/.test(m[2]) && /[a-z]/.test(m[2]);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Parse a forbidden-terms file — the format of templates/identity-vocabulary.example: one term per
|
|
45
|
+
* line, trimmed; blank and `#` lines are comments; a plain term matches case-insensitively as a
|
|
46
|
+
* substring; `re:<ERE>` is a regular expression matched against the lower-cased line; a term
|
|
47
|
+
* shorter than 3 characters is refused as a mistake. Returns `{ terms: [{line, test}], problems }`.
|
|
48
|
+
*/
|
|
49
|
+
function parseTerms(text) {
|
|
50
|
+
const terms = [];
|
|
51
|
+
const problems = [];
|
|
52
|
+
String(text || '').split(/\r?\n/).forEach((raw, i) => {
|
|
53
|
+
const t = raw.trim();
|
|
54
|
+
if (!t || t.startsWith('#')) return;
|
|
55
|
+
const line = i + 1;
|
|
56
|
+
if (t.startsWith('re:')) {
|
|
57
|
+
try {
|
|
58
|
+
const re = new RegExp(t.slice(3));
|
|
59
|
+
terms.push({ line, test: (s) => re.test(s.toLowerCase()) });
|
|
60
|
+
} catch (_) {
|
|
61
|
+
problems.push(`${TERMS_PATH} line ${line} is not a valid regular expression`);
|
|
62
|
+
}
|
|
63
|
+
return;
|
|
64
|
+
}
|
|
65
|
+
if (t.length < 3) { problems.push(`${TERMS_PATH} line ${line} is shorter than 3 characters`); return; }
|
|
66
|
+
const want = t.toLowerCase();
|
|
67
|
+
terms.push({ line, test: (s) => s.toLowerCase().includes(want) });
|
|
68
|
+
});
|
|
69
|
+
return { terms, problems };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The added lines of a `git diff -U0 --no-renames --no-color` patch: `[{ file, line, text }]`.
|
|
74
|
+
* `line` is the line number in the new file.
|
|
75
|
+
*/
|
|
76
|
+
function addedLines(patch) {
|
|
77
|
+
const out = [];
|
|
78
|
+
let file = null;
|
|
79
|
+
let ln = 0;
|
|
80
|
+
let inHunk = false;
|
|
81
|
+
for (const l of String(patch || '').split('\n')) {
|
|
82
|
+
// A file header only outside a hunk: an added line `++ x` prints as `+++ x` inside one.
|
|
83
|
+
if (l.startsWith('diff --git ')) { inHunk = false; file = null; continue; }
|
|
84
|
+
if (!inHunk && l.startsWith('+++ ')) { const f = l.slice(4); file = f === '/dev/null' ? null : f.replace(/^b\//, ''); continue; }
|
|
85
|
+
const h = /^@@ -\S+ \+(\d+)(?:,\d+)? @@/.exec(l);
|
|
86
|
+
if (h) { ln = Number(h[1]); inHunk = true; continue; }
|
|
87
|
+
if (inHunk && l.startsWith('+') && file) { out.push({ file, line: ln, text: l.slice(1) }); ln++; }
|
|
88
|
+
}
|
|
89
|
+
return out;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Pure: findings `[{ file, line, rule }]` over added lines, against RULES + assignment + `terms`. */
|
|
93
|
+
function scanLines(lines, terms = []) {
|
|
94
|
+
const findings = [];
|
|
95
|
+
for (const { file, line, text } of lines) {
|
|
96
|
+
for (const r of RULES) if (r.re.test(text)) findings.push({ file, line, rule: r.rule });
|
|
97
|
+
if (assignment(text)) findings.push({ file, line, rule: 'credential assignment' });
|
|
98
|
+
for (const t of terms) if (t.test(text)) findings.push({ file, line, rule: `forbidden term, line ${t.line} of ${TERMS_PATH}` });
|
|
99
|
+
}
|
|
100
|
+
return findings;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Scan what `branch` adds relative to its merge base with `base`, with the forbidden terms read from
|
|
105
|
+
* `base`'s tree (the branch cannot edit them and stay docs-only: `.github/` is never documentation).
|
|
106
|
+
* Returns `{ ok, findings, files, reason }`; `ok: false` with no findings means the scan could not
|
|
107
|
+
* run — a caller refuses on that too, it never reads it as clean.
|
|
108
|
+
*/
|
|
109
|
+
function scanBranch(git, repo, base, branch) {
|
|
110
|
+
const d = git.git(['diff', '-U0', '--no-renames', '--no-color', '--no-ext-diff', `${base}...${branch}`, '--'], repo);
|
|
111
|
+
if (!d.ok) return { ok: false, findings: [], reason: `could not read the diff ${base}...${branch}` };
|
|
112
|
+
let terms = [];
|
|
113
|
+
if (git.git(['cat-file', '-e', `${base}:${TERMS_PATH}`], repo).ok) {
|
|
114
|
+
const t = git.git(['show', `${base}:${TERMS_PATH}`], repo);
|
|
115
|
+
if (!t.ok) return { ok: false, findings: [], reason: `could not read ${TERMS_PATH} at ${base}` };
|
|
116
|
+
const parsed = parseTerms(t.stdout);
|
|
117
|
+
if (parsed.problems.length) return { ok: false, findings: [], reason: parsed.problems.join('; ') };
|
|
118
|
+
terms = parsed.terms;
|
|
119
|
+
}
|
|
120
|
+
const lines = addedLines(d.stdout);
|
|
121
|
+
const findings = scanLines(lines, terms);
|
|
122
|
+
const files = new Set(lines.map((l) => l.file)).size;
|
|
123
|
+
const extra = terms.length ? ` and ${terms.length} forbidden term(s)` : '';
|
|
124
|
+
if (findings.length) {
|
|
125
|
+
const shown = findings.slice(0, 5).map((f) => `${f.file}:${f.line} (${f.rule})`).join('; ');
|
|
126
|
+
const more = findings.length > 5 ? `; +${findings.length - 5} more` : '';
|
|
127
|
+
return { ok: false, findings, files, reason: `${findings.length} finding(s): ${shown}${more}` };
|
|
128
|
+
}
|
|
129
|
+
return { ok: true, findings, files, reason: `${lines.length} added line(s) in ${files} file(s) clean against the credential shapes${extra}` };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
module.exports = { TERMS_PATH, RULES, parseTerms, addedLines, scanLines, scanBranch, assignment };
|
package/tools/lib/ship-batch.js
CHANGED
|
@@ -513,7 +513,10 @@ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {})
|
|
|
513
513
|
const fresh = (atMs) => Number.isFinite(atMs) && Number.isFinite(nowMs) && (nowMs - atMs) < graceSec * 1000;
|
|
514
514
|
const mins = (atMs) => `${Math.max(0, Math.round((nowMs - atMs) / 60000))}m ago`;
|
|
515
515
|
for (const b of (Array.isArray(batches) ? batches : [])) {
|
|
516
|
-
|
|
516
|
+
// #605: a chained batch (`rooted`, from batchChains) is part of the one holder its root is —
|
|
517
|
+
// built on another batch's head, so it reaches trunk only through that chain. Without the flag,
|
|
518
|
+
// only a batch built on trunk's tip counts, exactly as before.
|
|
519
|
+
if (!b || !b.base7 || !(b.rooted === undefined ? now.startsWith(b.base7) : b.rooted)) continue;
|
|
517
520
|
const v = b.verdict || { state: 'pending', why: 'the run list could not be read' };
|
|
518
521
|
if (v.state === 'red') { released.push({ ref: b.ref, why: `declined — ${v.why}` }); continue; }
|
|
519
522
|
if (v.state === 'pending') return { held: true, ref: b.ref, why: `combined run in flight (${v.why})` };
|
|
@@ -532,6 +535,72 @@ function laneHold({ batches, trunkNow, nowMs, graceSec = LANE_GRACE_SEC } = {})
|
|
|
532
535
|
return { held: false, released };
|
|
533
536
|
}
|
|
534
537
|
|
|
538
|
+
/**
|
|
539
|
+
* #605: speculative chains. A batch built with `--onto <ship-batch ref>` sits on that ref's HEAD, and
|
|
540
|
+
* its name already says so: `ship-batch/<parent-head-sha7>`. So the whole chain is read from
|
|
541
|
+
* `ls-remote` alone — a ref's parent is the ref whose head sha starts with its base7, and a ref is
|
|
542
|
+
* ROOTED when following parents ends at a ref built on trunk's tip. No chain state is kept anywhere.
|
|
543
|
+
*
|
|
544
|
+
* In: refs `[{ ref, base7, sha }]` (every ship-batch/* on the remote), `trunkNow`.
|
|
545
|
+
* Out: Map ref → `{ ref, base7, sha, parentRef, rootRef, rootSha, depth, rooted, why }`:
|
|
546
|
+
* - parentRef null for a batch built on trunk's tip, else the ref it was built on (null too
|
|
547
|
+
* when that ref is gone — then `rooted` is false);
|
|
548
|
+
* - rootSha trunk's tip when rooted, else null;
|
|
549
|
+
* - depth 1 at trunk's tip, 2 for its child, …;
|
|
550
|
+
* - why for an unrooted ref, the reason it is (the sweep deletes it, and says this).
|
|
551
|
+
* A chain deeper than MAX_CHAIN_DEPTH is not rooted: every link pins trunk for one more combined run,
|
|
552
|
+
* and a wrong guess low in the chain throws away every run above it.
|
|
553
|
+
*/
|
|
554
|
+
const MAX_CHAIN_DEPTH = 3;
|
|
555
|
+
|
|
556
|
+
function batchChains({ refs, trunkNow } = {}) {
|
|
557
|
+
const now = String(trunkNow || '');
|
|
558
|
+
const all = (Array.isArray(refs) ? refs : []).filter((r) => r && r.ref && r.base7 && r.sha);
|
|
559
|
+
const parentOf = (r) => all.find((p) => p !== r && String(p.sha).startsWith(r.base7)) || null;
|
|
560
|
+
const out = new Map();
|
|
561
|
+
for (const r of all) {
|
|
562
|
+
const atTip = !!now && now.startsWith(r.base7);
|
|
563
|
+
const parent = atTip ? null : parentOf(r);
|
|
564
|
+
let cur = r, depth = 1, why = null, root = null;
|
|
565
|
+
const seen = new Set([r.ref]);
|
|
566
|
+
while (true) {
|
|
567
|
+
if (now && now.startsWith(cur.base7)) { root = cur; break; }
|
|
568
|
+
const p = parentOf(cur);
|
|
569
|
+
if (!p) {
|
|
570
|
+
why = cur === r ? `its base ${r.base7} is neither trunk's tip nor the head of another batch ref — trunk moved, or its parent was rebuilt or deleted`
|
|
571
|
+
: `its chain breaks at ${cur.ref}, whose base ${cur.base7} is neither trunk's tip nor another batch's head`;
|
|
572
|
+
break;
|
|
573
|
+
}
|
|
574
|
+
if (seen.has(p.ref)) { why = `its chain loops at ${p.ref}`; break; }
|
|
575
|
+
seen.add(p.ref);
|
|
576
|
+
cur = p;
|
|
577
|
+
depth += 1;
|
|
578
|
+
if (depth > MAX_CHAIN_DEPTH) { why = `its chain is deeper than ${MAX_CHAIN_DEPTH}`; break; }
|
|
579
|
+
}
|
|
580
|
+
out.set(r.ref, {
|
|
581
|
+
ref: r.ref, base7: r.base7, sha: r.sha, parentRef: parent ? parent.ref : null,
|
|
582
|
+
rootRef: root ? root.ref : null, rootSha: root ? now : null, depth, rooted: !!root, why,
|
|
583
|
+
});
|
|
584
|
+
}
|
|
585
|
+
return out;
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
/**
|
|
589
|
+
* #605: what a chained batch (built `--onto` a parent) does when it is ready to land but its parent
|
|
590
|
+
* has not landed yet — trunk's tip is not its base. Facts: the parent's chain entry (null = gone)
|
|
591
|
+
* and the parent's combined verdict.
|
|
592
|
+
* wait the parent is rooted and its run is in flight, not yet run, or green → exit 3
|
|
593
|
+
* decline the parent is gone, unrooted, or red → nothing of this chain can land in order: delete
|
|
594
|
+
* this batch and decline it (exit 4)
|
|
595
|
+
*/
|
|
596
|
+
function chainedLandStep({ parent, parentVerdict } = {}) {
|
|
597
|
+
if (!parent) return { step: 'decline', why: 'its parent batch is gone — discarded, or rebuilt on another head' };
|
|
598
|
+
if (!parent.rooted) return { step: 'decline', why: `its parent ${parent.ref} is no longer rooted at trunk's tip (${parent.why})` };
|
|
599
|
+
const v = parentVerdict || { state: 'pending', why: 'the run list could not be read' };
|
|
600
|
+
if (v.state === 'red') return { step: 'decline', why: `its parent ${parent.ref} is red (${v.why}) — it will not land at the sha this batch was built on` };
|
|
601
|
+
return { step: 'wait', why: `its parent ${parent.ref} has not landed yet (${v.state === 'green' ? 'green, waiting for its lander' : (v.why || v.state)})` };
|
|
602
|
+
}
|
|
603
|
+
|
|
535
604
|
/** #581: when a batch's combined run settled — the newest `updatedAt` among its finished rows, else null. */
|
|
536
605
|
function settledAt(rows) {
|
|
537
606
|
const t = (Array.isArray(rows) ? rows : []).filter((r) => r && r.status === 'completed')
|
|
@@ -599,5 +668,5 @@ module.exports = {
|
|
|
599
668
|
droppedTrailer, parseDroppedTrailers, appendTrailers,
|
|
600
669
|
branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
|
|
601
670
|
batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged, landPushFailure,
|
|
602
|
-
LANE_GRACE_SEC, laneHold, settledAt,
|
|
671
|
+
LANE_GRACE_SEC, laneHold, settledAt, MAX_CHAIN_DEPTH, batchChains, chainedLandStep,
|
|
603
672
|
};
|