@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 +1 -1
- package/tools/colab +52 -12
- package/tools/lib/blocked-by.js +3 -1
- package/tools/lib/codec/labels.d.ts +1 -1
- package/tools/lib/codec/labels.js +5 -2
package/package.json
CHANGED
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
|
|
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
|
-
|
|
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
|
-
|
|
3760
|
-
|
|
3761
|
-
|
|
3762
|
-
|
|
3763
|
-
|
|
3764
|
-
|
|
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\`
|
|
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
|
-
|
|
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)
|
|
3859
|
-
|
|
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
|
/**
|
package/tools/lib/blocked-by.js
CHANGED
|
@@ -116,7 +116,7 @@ function foreignEdges(edges, thisRepo) {
|
|
|
116
116
|
}
|
|
117
117
|
|
|
118
118
|
/**
|
|
119
|
-
* #388: what 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
|
-
|
|
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;
|