@futurelastic/colab-handbook 1.12.0-rc.33 → 1.12.0-rc.34

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.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/tools/colab +83 -5
package/package.json CHANGED
@@ -27,5 +27,5 @@
27
27
  "engines": {
28
28
  "node": ">=18"
29
29
  },
30
- "version": "1.12.0-rc.33"
30
+ "version": "1.12.0-rc.34"
31
31
  }
package/tools/colab CHANGED
@@ -10112,14 +10112,34 @@ function descriptorHolds(doc) {
10112
10112
  */
10113
10113
  function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk) {
10114
10114
  const name = `${target === trunk ? 'trunk' : 'line'} CI green`;
10115
- if (!gh) return { name, ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI`, grantVerdict: null, cureVerdict: null };
10115
+ const r = readCiVerdict(repoAbs, gh, target, trunk);
10116
+ if (r.final) return { name, ...r.verdict, grantVerdict: null, cureVerdict: null };
10117
+ return applyRedTrunkExemptions({ name, ...r.verdict }, target, trunk, r.run.sha, grantThunk, cureThunk);
10118
+ }
10119
+
10120
+ /**
10121
+ * The CI read and its classification, BEFORE any exemption door (#463) — the one function both
10122
+ * `shipCiCheck` above and `colab trunk-ci` (cmdTrunkCi) call, so code-triage's "is trunk red?" and
10123
+ * ship's "trunk CI green" precondition can no longer disagree about a sha. They did: triage read
10124
+ * "red only when every run completed and none succeeded" in its own `gh run list` filter, so a sha
10125
+ * with one green workflow beside a red one read GREEN to triage while ship parked every candidate.
10126
+ *
10127
+ * Returns `{ run, verdict, final }`. `verdict` is `{ok, class, detail}`; `run` is the summarized
10128
+ * run (null when gh is unusable or the read failed). `final` is true when no exemption door applies
10129
+ * (green, self-clearing, unreadable, or a batch substitute answered) — the caller returns `verdict`
10130
+ * as is; false means a HUMAN_GATED verdict that `shipCiCheck` still offers to the cure rule and the
10131
+ * ci-grant. `trunk-ci` deliberately reports the pre-exemption verdict: an exemption lets ONE
10132
+ * branch past a red trunk, it does not make the trunk green, and the red still needs an owner.
10133
+ */
10134
+ function readCiVerdict(repoAbs, gh, target, trunk) {
10135
+ if (!gh) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI` } };
10116
10136
  let run = git.ghRunForSha(repoAbs, target);
10117
10137
  let via = target;
10118
10138
  if (run && run.status === 'none' && target !== trunk) {
10119
10139
  run = git.ghRunForSha(repoAbs, trunk);
10120
10140
  via = `${trunk} (line "${target}" has no runs — ungated, advisory)`;
10121
10141
  }
10122
- if (!run) return { name, ok: false, class: SELF_CLEARING, detail: 'gh run list failed', grantVerdict: null, cureVerdict: null };
10142
+ if (!run) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: 'gh run list failed' } };
10123
10143
  // #413: an empty BRANCH-filtered read of trunk's head is a second opinion away from `none`. It was
10124
10144
  // measured coming back empty for a trunk sha whose green run existed, then clearing a minute later
10125
10145
  // — and `none` classes HUMAN_GATED, so a transient read parked a ready candidate for a human.
@@ -10149,10 +10169,9 @@ function shipCiCheck(repoAbs, gh, target, trunk, grantThunk, cureThunk) {
10149
10169
  // Inert (no gh call) unless project.yml declares ship-batch > 1.
10150
10170
  if (!verdict.ok && target === trunk && (run.status === 'none' || verdict.class === SELF_CLEARING)) {
10151
10171
  const sub = shipBatchTrunkSubstitute(repoAbs, trunk, run.sha);
10152
- if (sub) return { name, ...sub, grantVerdict: null, cureVerdict: null };
10172
+ if (sub) return { run, final: true, verdict: sub };
10153
10173
  }
10154
- if (verdict.ok || verdict.class !== HUMAN_GATED) return { name, ...verdict, grantVerdict: null, cureVerdict: null };
10155
- return applyRedTrunkExemptions({ name, ...verdict }, target, trunk, run.sha, grantThunk, cureThunk);
10174
+ return { run, verdict, final: verdict.ok || verdict.class !== HUMAN_GATED };
10156
10175
  }
10157
10176
 
10158
10177
  /**
@@ -13128,6 +13147,62 @@ function shipBatchMemberTail({ repoAbs, doc, trunk, sess, sha, closeIssues, refs
13128
13147
  // decides and deletes is one bug away from deleting on an `unknown`.
13129
13148
  // ---------------------------------------------------------------------------
13130
13149
 
13150
+ // trunk-ci — the trunk-CI verdict `colab ship` computes, read-only (#463). code-triage's §0 "red
13151
+ // trunk nobody owns" check and §5's "Trunk CI is alive" bullet call this instead of keeping a
13152
+ // `gh run list` filter of their own — two rules for one question disagreed, and the red went
13153
+ // unowned (a sha with CI green and a release workflow red read GREEN to triage, not-green to ship).
13154
+ const HELP_TRUNK_CI = `colab trunk-ci [--repo <path>] [--json]
13155
+
13156
+ Print the trunk-CI verdict \`colab ship\` would compute for the trunk's CURRENT remote head —
13157
+ the same read (shipCiCheck's readCiVerdict): by branch, re-read by commit when empty, runs from
13158
+ workflows the repo does not own dropped (#451), each workflow judged by its newest run (#461).
13159
+ Read-only: no claim, no label, no write.
13160
+
13161
+ The first output word is one verdict:
13162
+ GREEN every judged workflow's newest run at the sha succeeded — ship's row would pass
13163
+ RED a judged run completed and did not succeed — trunk is red
13164
+ PENDING a judged run is still in flight (or the sha is minutes old with no run yet)
13165
+ WEDGED a run that will never move on its own (zero jobs / hours unmoving, #155)
13166
+ NONE no repo-owned run exists at the sha — CI not wired or never started
13167
+ UNREADABLE gh unusable or the read failed — never "green"
13168
+
13169
+ Exemption doors (the cure rule, a ci-grant) are NOT applied: they let one branch past a red
13170
+ trunk, they do not make the trunk green, and the red still needs an owner.
13171
+
13172
+ --json { verdict, sha, ok, class, detail, trunk }
13173
+ Exit 0 whenever a verdict was read (whatever it is); 2 on UNREADABLE.`;
13174
+
13175
+ /** Map readCiVerdict's result to the closed trunk-ci vocabulary. Pure — exported for tests. */
13176
+ function trunkCiToken(r) {
13177
+ if (!r || !r.run) return 'UNREADABLE';
13178
+ if (r.verdict.ok) return 'GREEN';
13179
+ const st = r.run.status;
13180
+ if (st === 'none') return r.verdict.class === SELF_CLEARING ? 'PENDING' : 'NONE';
13181
+ if (st === 'completed') return 'RED';
13182
+ return r.verdict.class === HUMAN_GATED ? 'WEDGED' : 'PENDING';
13183
+ }
13184
+
13185
+ function cmdTrunkCi(argv) {
13186
+ const opts = parseArgs(argv, {
13187
+ values: { '--repo': 'repo' },
13188
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
13189
+ });
13190
+ if (opts.help) return print(HELP_TRUNK_CI);
13191
+ const repoAbs = resolveRepo(opts);
13192
+ if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo`);
13193
+ const trunk = resolveTrunk(repoAbs, projectDoc(repoAbs));
13194
+ if (!trunk) throw new UserError('cannot resolve trunk — no `trunk:` in .github/project.yml and no origin/HEAD');
13195
+ const r = readCiVerdict(repoAbs, isGhUsable(repoAbs), trunk, trunk);
13196
+ const verdict = trunkCiToken(r);
13197
+ const sha = r.run ? r.run.sha || null : null;
13198
+ if (opts.json) {
13199
+ print(JSON.stringify({ verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail: r.verdict.detail }, null, 2));
13200
+ } else {
13201
+ print(`${verdict} ${trunk}${sha ? `@${shortSha(sha)}` : ''} — ${r.verdict.detail}`);
13202
+ }
13203
+ return verdict === 'UNREADABLE' ? 2 : 0;
13204
+ }
13205
+
13131
13206
  const HELP_LANDED = `colab landed [--repo <path>] [--worktree <name> | --branch <br>] [--base <br>] [--all] [--json]
13132
13207
 
13133
13208
  Has this branch's work already landed on its base? The shared answer behind code-sweep's buckets
@@ -13951,6 +14026,8 @@ Commands:
13951
14026
  code-wrap Phase B → the branch's recorded base (trunk, or a
13952
14027
  declared line). --json (--dry only): machine-readable
13953
14028
  preconditions with a closed refusal-class vocabulary (#77)
14029
+ trunk-ci [--json] the trunk-CI verdict ship computes, read-only (#463):
14030
+ GREEN | RED | PENDING | WEDGED | NONE | UNREADABLE
13954
14031
  landed [--worktree N | --branch B | --all] [--base B] [--json] has this work already landed?
13955
14032
  (the shared rule behind code-sweep's buckets — correct
13956
14033
  across squash merges, where "commits ahead" is not)
@@ -14038,6 +14115,7 @@ function main(argv) {
14038
14115
  case 'worktrees': return cmdWorktrees(rest);
14039
14116
  case 'ship': return cmdShip(rest);
14040
14117
  case 'landed': return cmdLanded(rest);
14118
+ case 'trunk-ci': return cmdTrunkCi(rest);
14041
14119
  case 'holders': return cmdHolders(rest);
14042
14120
  case 'promote': return cmdPromote(rest);
14043
14121
  case 'deliver': return cmdDeliver(rest);