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

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.4"
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 = readBlockerSummary(repoAbs, num);
3722
3726
  print(labels.readinessMarkedMessage({ num, repo: shortRepo(repoAbs), summary }));
3723
3727
  }
3724
3728
 
@@ -3756,12 +3760,20 @@ 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') {
3761
- throw new UserError(`could not read #${num}'s blockedBy graph — refusing to write ${labels.MECHANICAL_READINESS_LABEL} on an unmeasured read`);
3762
- }
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`);
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
+ // #728: the refusal names the underlying error and the command that re-measures it, so a triage
3768
+ // pass can tell an auth or API failure from a parser bug without re-deriving the call by hand.
3769
+ const graph = readBlockerSummary(repoAbs, num);
3770
+ if (!graph.ok) {
3771
+ throw new UserError(`could not read #${num}'s blockedBy graph (${graph.error}) — refusing to write ${labels.MECHANICAL_READINESS_LABEL} on an unmeasured read. `
3772
+ + `Re-run the read by hand to see the full error: \`gh api repos/{owner}/{repo}/issues/${num}/dependencies/blocked_by\` (run it in this repo), then \`colab readiness ${num} --mechanical\` once it reads`);
3773
+ }
3774
+ if (graph.total > 0) {
3775
+ 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. `
3776
+ + `Review those edges and record the review instead: \`colab readiness ${num}\` (deps-checked — an open edge still carries its block)`);
3765
3777
  }
3766
3778
 
3767
3779
  const r = git.ghIssueEdit(repoAbs, num, labels.mechanicalReadinessLabelArgs({ clear: false }));
@@ -3778,7 +3790,7 @@ function cmdReadinessMechanical(repoAbs, num, opts) {
3778
3790
  // command marks (#296: 21/21 identical on one backlog, 40% of it).
3779
3791
  const ts = new Date().toISOString();
3780
3792
  git.ghIssueComment(repoAbs, num,
3781
- `Mechanical readiness: \`blockedBy\` totalCount = 0, read ${ts}. Applied \`${labels.MECHANICAL_READINESS_LABEL}\` `
3793
+ `Mechanical readiness: \`blockedBy\` reads 0 edges (\`dependencies/blocked_by\`), read ${ts}. Applied \`${labels.MECHANICAL_READINESS_LABEL}\` `
3782
3794
  + `(CONVENTIONS.md §5, Mechanical readiness — not \`${labels.READINESS_LABEL}\`).`);
3783
3795
 
3784
3796
  print(`Marked #${num} in ${shortRepo(repoAbs)} ${labels.MECHANICAL_READINESS_LABEL} — blockedBy reads empty (receipt posted)`);
@@ -3851,12 +3863,40 @@ Options:
3851
3863
  * read (mirrors ghIssueView's own null-means-unreadable contract).
3852
3864
  */
3853
3865
  function readBlockedByEdges(repoAbs, num) {
3866
+ return readBlockedByEdgesDetailed(repoAbs, num).raw;
3867
+ }
3868
+
3869
+ /**
3870
+ * The same read, keeping WHY it failed (#728): `{ raw, error }`, where `error` is one short line —
3871
+ * gh's exit code plus the first line of its stderr, or the parse failure — and null on success.
3872
+ * The refusal that reads it can then tell an auth/API failure (`exit 1: HTTP 401 …`) from a
3873
+ * response this module could not parse; a bare "could not read" sent a triage pass guessing.
3874
+ */
3875
+ function readBlockedByEdgesDetailed(repoAbs, num) {
3854
3876
  const r = git.ghApi(repoAbs, [
3855
- `repos/{owner}/{repo}/issues/${num}/dependencies/blocked_by`,
3877
+ // per_page=100: the endpoint pages at 30 by default, and GitHub allows up to 50 blockers per
3878
+ // issue — a default-size page would undercount (#727's readiness summary reads this too).
3879
+ `repos/{owner}/{repo}/issues/${num}/dependencies/blocked_by?per_page=100`,
3856
3880
  '-q', '[.[] | {id: .id, number: .number, state: .state, repository_url: .repository_url}]',
3857
3881
  ]);
3858
- if (!r.ok) return null;
3859
- try { return JSON.parse(r.stdout); } catch (_) { return null; }
3882
+ if (!r.ok) {
3883
+ const line = String(r.stderr || '').split('\n').map((l) => l.trim()).find(Boolean);
3884
+ return { raw: null, error: `\`gh api …/dependencies/blocked_by\` exit ${r.code == null ? '?' : r.code}: ${line || 'no stderr'}` };
3885
+ }
3886
+ try { return { raw: JSON.parse(r.stdout), error: null }; } catch (e) {
3887
+ return { raw: null, error: `unparseable response from \`gh api …/dependencies/blocked_by\` (${e.message})` };
3888
+ }
3889
+ }
3890
+
3891
+ /**
3892
+ * `readBlockedByEdgesDetailed` folded through `openBlockerSummary`, with a reason whenever the
3893
+ * summary is not ok — including a read that parsed but did not have the edge shape (#728).
3894
+ */
3895
+ function readBlockerSummary(repoAbs, num) {
3896
+ const read = readBlockedByEdgesDetailed(repoAbs, num);
3897
+ const summary = blockedBy.openBlockerSummary(read.raw);
3898
+ if (summary.ok) return summary;
3899
+ return { ...summary, error: read.error || 'the response was not a list of issues (unexpected shape)' };
3860
3900
  }
3861
3901
 
3862
3902
  /**
@@ -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
@@ -39,7 +39,7 @@ export function readinessLabelArgs(opts?: { clear?: boolean }): string[];
39
39
  export function readinessMissingLabelHint(present: LabelLike[] | null | undefined): string | null;
40
40
  export function readinessMarkedMessage(opts?: {
41
41
  num?: number | string; repo?: string;
42
- summary?: { ok: boolean; total: number; read: number; open: number; unknownState: number } | null;
42
+ summary?: { ok: boolean; total: number; read: number; open: number; unknownState: number; error?: string } | null;
43
43
  }): string;
44
44
  export const TRACKING_LABEL: 'tracking';
45
45
  export const MECHANICAL_READINESS_LABEL: 'graph-empty';
@@ -515,12 +515,15 @@ function readinessLabelArgs({ clear } = {}) {
515
515
  // --mechanical reads blockedBy), printed verbatim even on issues with open blockers, and the one
516
516
  // line operators copy into reports. It now says what was DONE (the review was recorded) and what
517
517
  // the graph holds, from one blockedBy read (`summary` = blocked-by.js openBlockerSummary, or
518
- // null/{ok:false} when the read failed). It never says "verified" and never "no open blocker":
518
+ // null/{ok:false[, error]} when the read failed). It never says "verified" and never "no open blocker":
519
519
  // deps-checked is a review record, and an open edge carries the block on its own (§5, #279).
520
520
  function readinessMarkedMessage({ num, repo, summary } = {}) {
521
521
  const head = `Marked #${num} in ${repo} ${READINESS_LABEL} — dependencies reviewed`;
522
522
  if (!summary || !summary.ok) {
523
- return `${head}; blockedBy: unread (the label records your review, not a graph read)`;
523
+ // #728: name why the read failed when the caller knows (`summary.error`, one line), so an
524
+ // auth/API failure reads differently from a parser bug. The label has landed either way.
525
+ const why = summary && typeof summary.error === 'string' && summary.error.trim() ? `${summary.error.trim()}; ` : '';
526
+ return `${head}; blockedBy: unread (${why}the label records your review, not a graph read)`;
524
527
  }
525
528
  const { total, read, open, unknownState } = summary;
526
529
  const truncated = read < total;