@futurelastic/colab-handbook 1.21.0-rc.2 → 1.21.0-rc.3

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
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.21.0-rc.2"
36
+ "version": "1.21.0-rc.3"
37
37
  }
package/tools/colab CHANGED
@@ -3673,7 +3673,8 @@ or an external party has its own carrier — see "Disposition" (CONVENTIONS.md
3673
3673
  (#69). It never touches deps-checked, and deps-checked never touches graph-empty: the two
3674
3674
  claims must stay distinguishable, because a mechanical read cannot see a blocker described
3675
3675
  only in prose. It re-derives its own evidence rather than trusting the caller — it reads
3676
- \`blockedBy\` via \`gh issue view\` on every run — and REFUSES rather than write the label if
3676
+ \`blockedBy\` via the REST \`issues/<N>/dependencies/blocked_by\` endpoint on every run (never
3677
+ \`gh issue view --json blockedBy\`, a field some gh versions lack, #727) — and REFUSES rather than write the label if
3677
3678
  that read comes back non-empty or unreadable. On a successful ADD it also posts a receipt
3678
3679
  comment naming exactly what was read and when, so the claim is auditable rather than
3679
3680
  assumed. graph-empty is opt-in per repo (create the label yourself; adoption/sync/the audit
@@ -3718,7 +3719,10 @@ function cmdReadiness(argv) {
3718
3719
  // --mechanical makes — REPORTED, never gated on: under §5 (#279) an open edge carries the
3719
3720
  // block by itself, and deps-checked only records that a reasoning session reviewed the deps.
3720
3721
  // A failed read is reported as "unread", never as zero; the label above has already landed.
3721
- const summary = blockedBy.openBlockerSummary(git.ghIssueView(repoAbs, num, ['blockedBy']));
3722
+ // #727: through the REST dependencies endpoint (readBlockedByEdges), never `gh issue view
3723
+ // --json blockedBy` — that JSON field is absent from some supported gh versions (2.85.0
3724
+ // measured), which made this line read "unread" on every issue there.
3725
+ const summary = blockedBy.openBlockerSummary(readBlockedByEdges(repoAbs, num));
3722
3726
  print(labels.readinessMarkedMessage({ num, repo: shortRepo(repoAbs), summary }));
3723
3727
  }
3724
3728
 
@@ -3756,12 +3760,17 @@ function cmdReadinessMechanical(repoAbs, num, opts) {
3756
3760
 
3757
3761
  // Re-derive the evidence ourselves — the whole point of #69's resolution is that this marker
3758
3762
  // may never be written on a caller's say-so, only on what the API says right now.
3759
- const info = git.ghIssueView(repoAbs, num, ['blockedBy']);
3760
- if (!info || !info.blockedBy || typeof info.blockedBy.totalCount !== 'number') {
3763
+ // #727: the read is the REST dependencies endpoint (readBlockedByEdges, the same read `colab
3764
+ // blocked` makes), not `gh issue view --json blockedBy`: that JSON field does not exist on some
3765
+ // supported gh versions (2.85.0 measured), so the old read was null there and this lane refused
3766
+ // on every issue. A failed read is still a refusal, never an empty graph.
3767
+ const graph = blockedBy.openBlockerSummary(readBlockedByEdges(repoAbs, num));
3768
+ if (!graph.ok) {
3761
3769
  throw new UserError(`could not read #${num}'s blockedBy graph — refusing to write ${labels.MECHANICAL_READINESS_LABEL} on an unmeasured read`);
3762
3770
  }
3763
- if (info.blockedBy.totalCount > 0) {
3764
- throw new UserError(`#${num} has ${info.blockedBy.totalCount} recorded blocker(s) — ${labels.MECHANICAL_READINESS_LABEL} asserts an EMPTY graph, so this read does not qualify`);
3771
+ if (graph.total > 0) {
3772
+ throw new UserError(`#${num} has ${graph.total} recorded blocker(s), ${graph.open} open — ${labels.MECHANICAL_READINESS_LABEL} asserts an EMPTY graph, so this read does not qualify. `
3773
+ + `Review those edges and record the review instead: \`colab readiness ${num}\` (deps-checked — an open edge still carries its block)`);
3765
3774
  }
3766
3775
 
3767
3776
  const r = git.ghIssueEdit(repoAbs, num, labels.mechanicalReadinessLabelArgs({ clear: false }));
@@ -3778,7 +3787,7 @@ function cmdReadinessMechanical(repoAbs, num, opts) {
3778
3787
  // command marks (#296: 21/21 identical on one backlog, 40% of it).
3779
3788
  const ts = new Date().toISOString();
3780
3789
  git.ghIssueComment(repoAbs, num,
3781
- `Mechanical readiness: \`blockedBy\` totalCount = 0, read ${ts}. Applied \`${labels.MECHANICAL_READINESS_LABEL}\` `
3790
+ `Mechanical readiness: \`blockedBy\` reads 0 edges (\`dependencies/blocked_by\`), read ${ts}. Applied \`${labels.MECHANICAL_READINESS_LABEL}\` `
3782
3791
  + `(CONVENTIONS.md §5, Mechanical readiness — not \`${labels.READINESS_LABEL}\`).`);
3783
3792
 
3784
3793
  print(`Marked #${num} in ${shortRepo(repoAbs)} ${labels.MECHANICAL_READINESS_LABEL} — blockedBy reads empty (receipt posted)`);
@@ -3852,7 +3861,9 @@ Options:
3852
3861
  */
3853
3862
  function readBlockedByEdges(repoAbs, num) {
3854
3863
  const r = git.ghApi(repoAbs, [
3855
- `repos/{owner}/{repo}/issues/${num}/dependencies/blocked_by`,
3864
+ // per_page=100: the endpoint pages at 30 by default, and GitHub allows up to 50 blockers per
3865
+ // issue — a default-size page would undercount (#727's readiness summary reads this too).
3866
+ `repos/{owner}/{repo}/issues/${num}/dependencies/blocked_by?per_page=100`,
3856
3867
  '-q', '[.[] | {id: .id, number: .number, state: .state, repository_url: .repository_url}]',
3857
3868
  ]);
3858
3869
  if (!r.ok) return null;
@@ -116,7 +116,7 @@ function foreignEdges(edges, thisRepo) {
116
116
  }
117
117
 
118
118
  /**
119
- * #388: what a `gh issue view --json blockedBy` read says about OPEN blockers — a report, never a
119
+ * #388: what a blockedBy read says about OPEN blockers — a report, never a
120
120
  * gate. `colab readiness <N>` (the deps-checked path) reads this once so its success line can say
121
121
  * what the graph holds instead of asserting "no open blocker" it never checked; it does NOT refuse
122
122
  * on a non-empty count (that is `--mechanical`'s job): under §5 (#279) an open edge carries the
@@ -125,6 +125,8 @@ function foreignEdges(edges, thisRepo) {
125
125
  * Returns `{ ok:false }` for an unreadable/malformed read (null means "could not read", never
126
126
  * "empty" — the same contract as normaliseEdges), else
127
127
  * { ok:true, total, read, open, unknownState }
128
+ * The readiness callers pass the REST list (#727: `gh issue view --json blockedBy` is absent on
129
+ * some gh versions); the connection shape is still accepted for a caller that has one.
128
130
  * `total` is the connection's totalCount when present (falls back to the nodes read); `read` is
129
131
  * how many nodes came back — fewer than `total` means the page was truncated, so `open` is a floor.
130
132
  * `unknownState` counts nodes with no `state` field: they are neither open nor closed as far as