@futurelastic/colab-handbook 1.12.0-rc.11 → 1.12.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/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.11"
30
+ "version": "1.12.0-rc.12"
31
31
  }
package/tools/colab CHANGED
@@ -57,6 +57,7 @@ const claimComments = require('./lib/claim-comments');
57
57
  const machine = require('./lib/machine');
58
58
  const targetSync = require('./lib/ship-target-sync');
59
59
  const shipBatch = require('./lib/ship-batch');
60
+ const conflictMarkers = require('./lib/conflict-markers');
60
61
  const docsOnly = require('./lib/docs-only');
61
62
  const cureDiff = require('./lib/cure-diff');
62
63
  const codeowners = require('./lib/codeowners');
@@ -4872,6 +4873,19 @@ function worktreeSubdir(config) { return config.worktreeSubdir || '.worktrees';
4872
4873
  // slow-but-working. Overridable per-machine/per-repo for a legitimately slow teardown.
4873
4874
  const TEARDOWN_TIMEOUT_MS = Number(process.env.COLAB_TEARDOWN_TIMEOUT_MS) || 5 * 60 * 1000;
4874
4875
 
4876
+ /**
4877
+ * #436: after a pre-ship hook exits 0, which of the paths it was handed still carry conflict markers
4878
+ * in the index — i.e. would be committed with `<<<<<<<` in them. Untrimmed git output, so the line
4879
+ * numbers in the message are the file's own.
4880
+ */
4881
+ function stagedConflictMarkers(dir, paths) {
4882
+ const rawGit = (args, cwd) => {
4883
+ const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
4884
+ return { ok: r.status === 0, stdout: r.stdout || '' };
4885
+ };
4886
+ return conflictMarkers.stagedMarkerPaths(rawGit, dir, paths);
4887
+ }
4888
+
4875
4889
  function runHook(repoAbs, name, ctx) {
4876
4890
  const hook = path.join(repoAbs, '.colab', 'hooks', name);
4877
4891
  try {
@@ -9439,8 +9453,12 @@ for is built in its place, so the survivors of a decline can batch without landi
9439
9453
  A member that conflicts with the members already in is dropped to the next batch; the rest go on —
9440
9454
  unless every conflicting path is generated (defaults + project.yml generated:): then .colab/hooks/pre-ship
9441
9455
  regenerates them on the combined head and the member stays in (#387). No hook, or a failing one → dropped.
9442
- --dry builds the batch locally and prints it, pushing nothing. Consumer CI must opt in: add
9443
- 'ship-batch/**' to a CI workflow's push: branches:.
9456
+ A hook that exits 0 but leaves a <<<<<<< / >>>>>>> line staged in a path it was handed counts as failing (#436).
9457
+ Resuming a staged batch: a branch you name that the staged batch does not carry (over the cap, dropped
9458
+ at build, added since) is NOT landed with it — the command names both lists and says so (#415).
9459
+ --dry pushes, deletes, lands, comments and releases nothing on EVERY path (#415): a fresh batch is built
9460
+ locally and printed; a staged green batch prints what would land (members, combined run, target sha).
9461
+ Consumer CI must opt in: add 'ship-batch/**' to a CI workflow's push: branches:.
9444
9462
 
9445
9463
  B3 KEEPS the branch by default. Deleting refs from a shared remote is not something this command
9446
9464
  does unasked, however certain it is that the content landed: reporting is safe and reversible,
@@ -11849,6 +11867,14 @@ function cmdShip(argv) {
11849
11867
  }
11850
11868
  if (hasPreShip) {
11851
11869
  const hk = runHook(repoAbs, 'pre-ship', { wtPath: branchDir, name: sess.name || sess.branch, branch: sess.branch, ports: [], trunk, base: target, issues: sess.issues });
11870
+ // #436: exit 0 is the hook's claim; the index is the proof. Markers left in a path it was
11871
+ // handed make it a failing hook, checked BEFORE the commit so nothing carrying them is pushed.
11872
+ const markers = hk.ran && hk.ok ? stagedConflictMarkers(branchDir, uf) : [];
11873
+ if (markers.length) {
11874
+ git.git(['merge', '--abort'], branchDir); cleanupEphemeral();
11875
+ process.stderr.write(`✗ B0: pre-ship hook exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} — treated as a failing hook. Nothing pushed.\n`);
11876
+ return 1;
11877
+ }
11852
11878
  const committed = hk.ran && hk.ok && git.git(['commit', '--no-edit'], branchDir).ok;
11853
11879
  if (!committed) {
11854
11880
  git.git(['merge', '--abort'], branchDir); cleanupEphemeral();
@@ -12493,7 +12519,9 @@ function cmdShipBatch(opts) {
12493
12519
  const batchRefs = (lsBatch.ok ? lsBatch.stdout.split('\n') : []).map((l) => l.split('\t'))
12494
12520
  .map(([sha, ref]) => ({ sha: (sha || '').trim(), parsed: shipBatch.parseBatchRef((ref || '').trim()) }))
12495
12521
  .filter((x) => x.sha && x.parsed);
12522
+ // #415: every write on the resume path goes through here or shipBatchLand — under --dry, neither writes.
12496
12523
  const deleteRef = (ref) => {
12524
+ if (opts.dry) { print(` [dry] would delete ${remote}/${ref}`); return true; }
12497
12525
  const d = git.git(['push', remote, '--delete', ref], repoAbs);
12498
12526
  if (!d.ok) warn(`could not delete ${remote}/${ref}: ${git.gitFailureLine(d.stderr)} — delete it by hand`);
12499
12527
  return d.ok;
@@ -12523,6 +12551,14 @@ function cmdShipBatch(opts) {
12523
12551
  const heads = inBatch.map((m) => ({ ...m, now: git.branchRefs(repoAbs, m.branch, remote).remoteSha }));
12524
12552
  const matches = heads.length >= 2 && heads.every((m) => m.now && m.now.startsWith(m.sha));
12525
12553
  existing = { ref: atBase.parsed.ref, base7: atBase.parsed.base7, sha: atBase.sha, members: inBatch, matches };
12554
+ // #415: the command line and the staged batch can name different sets. A requested branch the
12555
+ // staged batch does not carry (over the cap, dropped at build, or added since) does NOT ride
12556
+ // along — say so, naming both lists, instead of resuming as if the two were the same.
12557
+ const notStaged = shipBatch.notStaged(members, inBatch);
12558
+ if (notStaged.length) {
12559
+ print(` ! ${atBase.parsed.ref} was staged with ${inBatch.map((m) => m.branch).join(', ')}; this command named ${members.join(', ')}.`);
12560
+ print(` NOT in the staged batch, so it does not land with it: ${notStaged.join(', ')} — ship it after this batch (next batch, or colab ship --branch <b>).`);
12561
+ }
12526
12562
  }
12527
12563
  }
12528
12564
  const verdict = existing && existing.matches ? shipBatch.combinedVerdict(git.ghRunsForRef(repoAbs, existing.ref, existing.sha)) : null;
@@ -12549,7 +12585,7 @@ function cmdShipBatch(opts) {
12549
12585
  return 4;
12550
12586
  }
12551
12587
  if (step.step === 'red-serial') {
12552
- print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} deleted.`);
12588
+ print(`✗ ship-batch: the combined run is red again after its one re-run (${verdict.why}) — nothing landed; ${existing.ref} ${opts.dry ? 'would be deleted [DRY RUN]' : 'deleted'}.`);
12553
12589
  deleteRef(existing.ref);
12554
12590
  print(shipBatch.serialLine(existing.members.map((m) => m.branch)));
12555
12591
  return 4;
@@ -12616,8 +12652,13 @@ function cmdShipBatch(opts) {
12616
12652
  issues: (m.report && m.report.closeIssues) || [],
12617
12653
  });
12618
12654
  const left = hk.ran ? unmergedIn() : unmerged;
12655
+ // #436: a hook that exits 0 and `git add`s a path still holding markers clears the unmerged
12656
+ // state, so `left` reads empty — read the staged content itself before trusting it.
12657
+ const markers = hk.ran && hk.ok && !left.length ? stagedConflictMarkers(dir, unmerged) : [];
12619
12658
  if (!hk.ran || !hk.ok || left.length) {
12620
12659
  why = `.colab/hooks/pre-ship could not regenerate ${unmerged.join(', ')} on the combined head${left.length && hk.ok ? ` (still unmerged: ${left.join(', ')})` : ''} — next batch`;
12660
+ } else if (markers.length) {
12661
+ why = `.colab/hooks/pre-ship exited 0 but left conflict markers staged in ${conflictMarkers.describe(markers)} on the combined head — treated as a failing hook, next batch`;
12621
12662
  } else regenerated = unmerged;
12622
12663
  }
12623
12664
  if (why) {
@@ -12684,6 +12725,14 @@ function cmdShipBatch(opts) {
12684
12725
  */
12685
12726
  function shipBatchLand(repoAbs, doc, trunk, remote, base, existing, verdict, opts) {
12686
12727
  const head = existing.sha;
12728
+ // #415: a staged green batch reached under --dry is a read: what WOULD land, and nothing else —
12729
+ // no fast-forward, no push, no ref delete, no hook, no worktree teardown, no claim, no comment.
12730
+ if (opts.dry) {
12731
+ print(`ship --batch ${shortRepo(repoAbs)} → ${trunk} @ ${shortSha(base)} [DRY RUN]`);
12732
+ print(`→ READY: would fast-forward ${trunk} ${shortSha(base)} → ${shortSha(head)} — ${existing.ref}, combined run ${(verdict.runIds || []).join(', ') || '(id unread)'} ${verdict.why || verdict.state}`);
12733
+ print(` would land ${existing.members.length} member(s), one squash each: ${existing.members.map((m) => m.branch).join(', ')}`);
12734
+ return 0;
12735
+ }
12687
12736
  const headBranch = git.git(['rev-parse', '--abbrev-ref', 'HEAD'], repoAbs).stdout;
12688
12737
  if (headBranch !== trunk || git.dirtyTracked(repoAbs)) {
12689
12738
  throw new UserError(`the main checkout is not on a clean ${trunk} ("${headBranch}"${git.dirtyTracked(repoAbs) ? ', dirty' : ''}) — the batch is green and waiting; fix the checkout and run this command again`);
@@ -0,0 +1,47 @@
1
+ 'use strict';
2
+ /**
3
+ * #436: a pre-ship hook's exit code is a claim ("ZERO means every conflicted path was resolved"),
4
+ * not proof. A hook that regenerates a path's NEW layout and then `git add`s an OLD path still full
5
+ * of conflict markers exits 0 and stages the markers — git clears the unmerged state on `add`, so
6
+ * `git diff --diff-filter=U` reads clean. This reads what would actually be committed.
7
+ *
8
+ * Detection is deliberately `<<<<<<<` / `>>>>>>>` at column 0 (followed by a space or end of line).
9
+ * A bare `=======` line is NOT a marker on its own: it is also a legitimate Markdown setext-heading
10
+ * underline, and generated docs are exactly the files this check reads. Every real conflict block
11
+ * carries the two outer markers, so nothing is missed by not counting the middle one alone.
12
+ */
13
+
14
+ const MARKER = /^(<{7}|>{7})(?:[ \t]|$)/;
15
+
16
+ /** Pure: 1-based line numbers of conflict-marker lines in `text`. */
17
+ function markerLines(text) {
18
+ const out = [];
19
+ String(text == null ? '' : text).split('\n').forEach((line, i) => {
20
+ if (MARKER.test(line.replace(/\r$/, ''))) out.push(i + 1);
21
+ });
22
+ return out;
23
+ }
24
+
25
+ /**
26
+ * Which of `paths` still hold conflict markers in the INDEX (stage 0 — what `git commit` takes) at
27
+ * `cwd`. `gitFn(args, cwd)` → `{ ok, stdout }`. A path absent from the index (deleted, or still
28
+ * unmerged at stages 1-3) is skipped here: deletion is a resolution, and an unmerged path is the
29
+ * caller's existing `--diff-filter=U` check. Returns `[{ path, lines }]`.
30
+ */
31
+ function stagedMarkerPaths(gitFn, cwd, paths) {
32
+ const hits = [];
33
+ for (const p of [...new Set(paths || [])]) {
34
+ const r = gitFn(['show', `:0:${p}`], cwd);
35
+ if (!r || !r.ok) continue;
36
+ const lines = markerLines(r.stdout);
37
+ if (lines.length) hits.push({ path: p, lines });
38
+ }
39
+ return hits;
40
+ }
41
+
42
+ /** One line naming each path and its first marker lines. */
43
+ function describe(hits) {
44
+ return (hits || []).map((h) => `${h.path}:${h.lines.slice(0, 3).join(',')}${h.lines.length > 3 ? ',…' : ''}`).join(', ');
45
+ }
46
+
47
+ module.exports = { markerLines, stagedMarkerPaths, describe };
@@ -257,6 +257,16 @@ function batchGreenCoversTrunk({ trunkRows, batchRows, trunkFires, batchFires })
257
257
  return (batchRows || []).length >= a.length;
258
258
  }
259
259
 
260
+ /**
261
+ * #415: branches the command line names that a staged batch does not carry, in command-line order.
262
+ * `staged` is parseMemberTrailers' `[{ branch }]`. Not a refusal on its own: a branch over the cap or
263
+ * dropped at build is EXPECTED to be missing on resume — the caller must say so, never stay silent.
264
+ */
265
+ function notStaged(requested, staged) {
266
+ const have = new Set((staged || []).map((m) => m && m.branch).filter(Boolean));
267
+ return [...new Set(requested || [])].filter((b) => b && !have.has(b));
268
+ }
269
+
260
270
  /** The clause each member's 🚢 evidence comment gains: which combined run graded it. */
261
271
  function evidenceSuffix({ n, ref, headSha, runIds }) {
262
272
  const runs = (runIds || []).length ? (runIds || []).join(', ') : '(id unread)';
@@ -273,5 +283,5 @@ module.exports = {
273
283
  MAX_BATCH, REF_PREFIX, PROBE_REF, TRAILER_KEY,
274
284
  parseShipBatch, batchRefName, parseBatchRef, memberTrailer, parseMemberTrailers,
275
285
  branchCiClass, memberEligibility, selectMembers, wiring, combinedVerdict, nextStep, foreignBatchStep,
276
- batchGreenCoversTrunk, evidenceSuffix, serialLine,
286
+ batchGreenCoversTrunk, evidenceSuffix, serialLine, notStaged,
277
287
  };