@futurelastic/colab-handbook 1.12.0-rc.58 → 1.12.0-rc.59
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 +37 -40
- package/tools/lib/git.js +41 -32
- package/tools/lib/tracker-github.js +106 -0
- package/tools/lib/tracker.js +61 -0
package/package.json
CHANGED
package/tools/colab
CHANGED
|
@@ -15,6 +15,7 @@ const { spawnSync } = require('child_process');
|
|
|
15
15
|
|
|
16
16
|
const state = require('./lib/state');
|
|
17
17
|
const git = require('./lib/git');
|
|
18
|
+
const tracker = require('./lib/tracker'); // every gh call goes through tracker-github.js (#500)
|
|
18
19
|
const ports = require('./lib/ports');
|
|
19
20
|
const stamp = require('./lib/stamp');
|
|
20
21
|
const releaseTag = require('./lib/release-tag');
|
|
@@ -1323,16 +1324,13 @@ no-op; 1 when refused.
|
|
|
1323
1324
|
function readAllIssuesForSwitches(repoAbs) {
|
|
1324
1325
|
const LIMIT = 5000;
|
|
1325
1326
|
// title/labels/createdAt/url are additive (#339): `release finalize` finds its tracking issue in the same read.
|
|
1326
|
-
const r =
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
|
|
1332
|
-
|
|
1333
|
-
} catch (_) {
|
|
1334
|
-
return null;
|
|
1335
|
-
}
|
|
1327
|
+
const r = tracker.forRepo(repoAbs).issueListAll({
|
|
1328
|
+
limit: LIMIT, fields: ['number', 'state', 'stateReason', 'body', 'title', 'labels', 'createdAt', 'closedAt', 'url'],
|
|
1329
|
+
maxBuffer: 512 * 1024 * 1024,
|
|
1330
|
+
});
|
|
1331
|
+
const list = r.data; // null: the read failed or was unparseable
|
|
1332
|
+
// A full page may be a truncated one — an unread marker is not a cleared one.
|
|
1333
|
+
return Array.isArray(list) && list.length < LIMIT ? list : null;
|
|
1336
1334
|
}
|
|
1337
1335
|
|
|
1338
1336
|
/** [{status, path, content}] for every path changed between `from` (null = the empty tree) and `sha`; null on a git failure. */
|
|
@@ -1673,15 +1671,14 @@ function cmdReleaseCut(argv) {
|
|
|
1673
1671
|
announced = announceCarried(repoAbs, { tagNames: [...tags, verdict.tag], exclude, version: verdict.tag, sha });
|
|
1674
1672
|
if (fastFacts.tracking) {
|
|
1675
1673
|
commentOnce(repoAbs, fastFacts.tracking.number, { state: 'finalized', tag: verdict.tag }, `**${verdict.tag}** tagged final on \`${shortSha(sha)}\` by route deploy-tag-fast — the release workflow deploys it in this run.`);
|
|
1676
|
-
const r =
|
|
1677
|
-
if (r.
|
|
1674
|
+
const r = tracker.forRepo(repoAbs).issueClose(fastFacts.tracking.number);
|
|
1675
|
+
if (!r.ok) warn(`could not close #${fastFacts.tracking.number}: ${String(r.stderr || '').split('\n')[0]}`);
|
|
1678
1676
|
}
|
|
1679
1677
|
} else if (handoff && verdict.version) {
|
|
1680
1678
|
let num = fastFacts.tracking ? fastFacts.tracking.number : null;
|
|
1681
1679
|
if (!num && issues !== null) {
|
|
1682
|
-
const c =
|
|
1683
|
-
|
|
1684
|
-
if (m) num = Number(m[1]);
|
|
1680
|
+
const c = tracker.forRepo(repoAbs).issueCreate({ title: releaseFinalize.trackingTitle(verdict.version), body: releaseCut.handoffTrackingBody(verdict.version) });
|
|
1681
|
+
if (c.number) num = c.number;
|
|
1685
1682
|
else warn(`could not open the tracking issue for ${verdict.version} (${String(c.stderr || '').split('\n')[0] || 'no issue URL returned'}) — the hand-off is printed here only`);
|
|
1686
1683
|
}
|
|
1687
1684
|
if (num) {
|
|
@@ -1757,8 +1754,8 @@ function publishPrerelease(repoAbs, { tag, lastFinal, message, final = false })
|
|
|
1757
1754
|
// #446: a deploy-tag-fast final is published as a full release, marked latest.
|
|
1758
1755
|
const kind = final ? 'release' : 'pre-release';
|
|
1759
1756
|
if (!isGhUsable(repoAbs)) return { ok: false, detail: `${kind} NOT published: gh not usable (${ghUnusableWhy(repoAbs)})` };
|
|
1760
|
-
const view =
|
|
1761
|
-
if (view.
|
|
1757
|
+
const view = tracker.forRepo(repoAbs).releaseView(tag);
|
|
1758
|
+
if (view.ok) return { ok: true, detail: `${tag} already has a GitHub Release — left as it is` };
|
|
1762
1759
|
let notes;
|
|
1763
1760
|
try {
|
|
1764
1761
|
notes = lastFinal ? buildReleaseNotes(repoAbs, `${lastFinal}..${tag}`, lastFinal).out : `## ${tag}\n\nFirst release.\n`;
|
|
@@ -1769,8 +1766,8 @@ function publishPrerelease(repoAbs, { tag, lastFinal, message, final = false })
|
|
|
1769
1766
|
const file = path.join(os.tmpdir(), `colab-release-notes-${process.pid}-${tag}.md`);
|
|
1770
1767
|
fs.writeFileSync(file, notes);
|
|
1771
1768
|
try {
|
|
1772
|
-
const r =
|
|
1773
|
-
if (r.
|
|
1769
|
+
const r = tracker.forRepo(repoAbs).releaseCreate(tag, { notesFile: file, final });
|
|
1770
|
+
if (!r.ok) return { ok: false, detail: `${kind} NOT published: gh release create ${tag} failed (${(r.stderr || '').split('\n')[0] || r.code})` };
|
|
1774
1771
|
return { ok: true, detail: `published the GitHub ${kind} ${tag}` };
|
|
1775
1772
|
} finally {
|
|
1776
1773
|
try { fs.unlinkSync(file); } catch (_) { /* best-effort */ }
|
|
@@ -1963,10 +1960,9 @@ function cmdReleaseFinalize(argv) {
|
|
|
1963
1960
|
const t0 = version0 ? trackings.get(version0) : null;
|
|
1964
1961
|
if (newest && t0 && !t0.error && !t0.number && !opts.dry) {
|
|
1965
1962
|
const body = releaseFinalize.trackingBody({ version: version0, row: policy.derived.row, final: policy.effective.final, testPeriodDays: policy.effective.testPeriodDays });
|
|
1966
|
-
const c =
|
|
1967
|
-
|
|
1968
|
-
|
|
1969
|
-
else { trackings.set(version0, { number: Number(m[1]), url: (c.stdout || '').trim(), createdAt: now, held: false }); trackingCreated = true; }
|
|
1963
|
+
const c = tracker.forRepo(repoAbs).issueCreate({ title: releaseFinalize.trackingTitle(version0), body });
|
|
1964
|
+
if (!c.number) trackings.set(version0, { error: `could not open the tracking issue for ${version0} (${String(c.stderr || '').split('\n')[0] || 'no issue URL returned'})` });
|
|
1965
|
+
else { trackings.set(version0, { number: c.number, url: c.url, createdAt: now, held: false }); trackingCreated = true; }
|
|
1970
1966
|
}
|
|
1971
1967
|
|
|
1972
1968
|
// #441: an operator-granted automatic final — the decision it names is resolved once per run, from
|
|
@@ -2069,8 +2065,8 @@ function cmdReleaseFinalize(argv) {
|
|
|
2069
2065
|
if (!r.ok) warn(`could not comment on #${num}: ${String(r.stderr || '').split('\n')[0]}`);
|
|
2070
2066
|
};
|
|
2071
2067
|
const close = (num) => {
|
|
2072
|
-
const r =
|
|
2073
|
-
if (r.
|
|
2068
|
+
const r = tracker.forRepo(repoAbs).issueClose(num);
|
|
2069
|
+
if (!r.ok) warn(`could not close #${num}: ${String(r.stderr || '').split('\n')[0]}`);
|
|
2074
2070
|
};
|
|
2075
2071
|
// #426: one "Released in vX.Y.Z" comment on every issue the version carries (release-finalize.js
|
|
2076
2072
|
// carriedIssues — the closing references in (previous final, sha]). Idempotent by event marker.
|
|
@@ -2470,7 +2466,7 @@ function cmdClose(argv) {
|
|
|
2470
2466
|
if (already) {
|
|
2471
2467
|
print(` #${num} is already closed — skipping the close; releasing and notifying anyway`);
|
|
2472
2468
|
} else {
|
|
2473
|
-
const r =
|
|
2469
|
+
const r = tracker.forRepo(repoAbs).issueClose(num, { reason: ghReason });
|
|
2474
2470
|
if (!r.ok) {
|
|
2475
2471
|
process.stderr.write(`✗ gh issue close #${num} failed (${(r.stderr || '').split('\n')[0] || r.code}) — claim untouched.\n`);
|
|
2476
2472
|
return 1;
|
|
@@ -4463,11 +4459,10 @@ function computeAntiStacking(repoAbs, trunk, trunkIsRed) {
|
|
|
4463
4459
|
// local offset is positive (tools/lib/ci-grant.js's wentGreenSince doc comment has the full
|
|
4464
4460
|
// failure).
|
|
4465
4461
|
let wentGreen = false;
|
|
4466
|
-
const runsR =
|
|
4467
|
-
|
|
4468
|
-
if (runsR.ok) {
|
|
4462
|
+
const runsR = tracker.forRepo(repoAbs).runList({ branch: trunk, limit: 100, fields: ['conclusion', 'status', 'createdAt'] });
|
|
4463
|
+
if (runsR.data) {
|
|
4469
4464
|
try {
|
|
4470
|
-
wentGreen = ciGrant.wentGreenSince(
|
|
4465
|
+
wentGreen = ciGrant.wentGreenSince(runsR.data, priorGrantMerge.at);
|
|
4471
4466
|
} catch (_) { /* unparseable — treat conservatively as "cannot prove it went green" */ }
|
|
4472
4467
|
}
|
|
4473
4468
|
redContinuousSincePriorGrant = !wentGreen;
|
|
@@ -6967,9 +6962,10 @@ function measureHeadCandidate(repoAbs, { candidatesAuto, mainRef, lastRelease, o
|
|
|
6967
6962
|
const tagsAtSha = tagsR.ok ? tagsR.stdout.split('\n').map((t) => t.trim()).filter(Boolean) : [];
|
|
6968
6963
|
let runs = null;
|
|
6969
6964
|
if (isGhUsable(repoAbs)) {
|
|
6970
|
-
const r =
|
|
6971
|
-
|
|
6972
|
-
|
|
6965
|
+
const r = tracker.forRepo(repoAbs).runList({
|
|
6966
|
+
branch: 'main', commit: sha, limit: 50, fields: ['status', 'conclusion', 'event', 'createdAt', 'updatedAt', 'workflowName'],
|
|
6967
|
+
});
|
|
6968
|
+
runs = Array.isArray(r.data) ? r.data : null;
|
|
6973
6969
|
}
|
|
6974
6970
|
const promotion = dualTrunk ? measurePromotion(repoAbs, { sha, trunk, remote, fetched: fetchTrunk }) : null;
|
|
6975
6971
|
return releaseCut.headCandidateVerdict({
|
|
@@ -11500,7 +11496,7 @@ function shipCloseSpentContainers(repoAbs, closedIssues, { sha, target } = {}) {
|
|
|
11500
11496
|
const cm = git.ghIssueComment(repoAbs, pnum, body);
|
|
11501
11497
|
if (!cm.ok) warnDeferred(`could not post the container-close comment on #${pnum} — left OPEN`);
|
|
11502
11498
|
if (!cm.ok) break;
|
|
11503
|
-
const r =
|
|
11499
|
+
const r = tracker.forRepo(repoAbs).issueClose(pnum, { reason: 'completed' });
|
|
11504
11500
|
if (!r.ok) { warnDeferred(`could not close container #${pnum}: ${(r.stderr || '').split('\n')[0]}`); break; }
|
|
11505
11501
|
print(` closed container #${pnum} — all ${c.total} sub-issue(s) closed (#371)`);
|
|
11506
11502
|
for (const d of containerClose.containerDeliveryLabels(parent.labels)) warn(`container #${pnum} carried ${d} — a container has no deliverable of its own (#371)`);
|
|
@@ -11606,7 +11602,7 @@ function shipEvidenceClose({ repoAbs, st, sess, target, trunk, gh, closeIssues,
|
|
|
11606
11602
|
`write. The zero-diff fact was measured from git: ${mode.why}.${shipSess}`;
|
|
11607
11603
|
const c = git.ghIssueComment(repoAbs, num, body);
|
|
11608
11604
|
if (!c.ok) warn(`could not post the evidence-close comment on #${num} — closing anyway`);
|
|
11609
|
-
const r =
|
|
11605
|
+
const r = tracker.forRepo(repoAbs).issueClose(num, { reason: 'completed' });
|
|
11610
11606
|
if (!r.ok) { skipped.push({ num, why: `gh issue close failed: ${(r.stderr || '').split('\n')[0]}` }); continue; }
|
|
11611
11607
|
closed.push(num);
|
|
11612
11608
|
print(` #${num} closed with evidence.`);
|
|
@@ -14212,11 +14208,12 @@ function cmdDeliver(argv) {
|
|
|
14212
14208
|
if (!tip || !ownerTip) return fail(`${remote}/${trunk} or ${remote}/${owner.branch} does not resolve after the fetch`);
|
|
14213
14209
|
|
|
14214
14210
|
// 2. every delivery PR, any state
|
|
14215
|
-
const r =
|
|
14216
|
-
'
|
|
14211
|
+
const r = tracker.forRepo(repoAbs).prList({
|
|
14212
|
+
base: owner.branch, head: trunk, state: 'all', limit: 50, fields: ['number', 'url', 'state', 'mergedAt', 'headRefOid', 'title'],
|
|
14213
|
+
});
|
|
14217
14214
|
if (!r.ok) return fail(`could not list pull requests: ${(r.stderr || '').split('\n')[0]}`);
|
|
14218
|
-
|
|
14219
|
-
|
|
14215
|
+
const list = r.stdout ? r.data : []; // an empty reply is no PRs here, as it always was
|
|
14216
|
+
if (list === null) return fail('gh pr list returned unparseable JSON');
|
|
14220
14217
|
const prs = ownerBranch.classifyPrs(list);
|
|
14221
14218
|
|
|
14222
14219
|
// 3. the undelivered range: since the last merged delivery's head when that head is still on
|
|
@@ -14268,7 +14265,7 @@ function cmdDeliver(argv) {
|
|
|
14268
14265
|
return 1;
|
|
14269
14266
|
}
|
|
14270
14267
|
if (d.action === 'refresh') {
|
|
14271
|
-
const e =
|
|
14268
|
+
const e = tracker.forRepo(repoAbs).prEdit(prs.open.number, { title: text.title, body: text.body });
|
|
14272
14269
|
if (!e.ok) return fail(`could not refresh PR #${prs.open.number}: ${(e.stderr || '').split('\n')[0]}`);
|
|
14273
14270
|
out.done = `refreshed PR #${prs.open.number} (${prs.open.url || ''}) — waiting on the owner`;
|
|
14274
14271
|
} else {
|
package/tools/lib/git.js
CHANGED
|
@@ -29,6 +29,15 @@ function run(cmd, args, opts = {}) {
|
|
|
29
29
|
};
|
|
30
30
|
}
|
|
31
31
|
|
|
32
|
+
/**
|
|
33
|
+
* Every `gh` spawn in this module goes through the tracker adapter (#500) — the one place the CLI
|
|
34
|
+
* talks to GitHub. Lazy require, deliberately: `module.exports = {…}` below REPLACES the exports
|
|
35
|
+
* object, so a top-level require cycle would hand tracker-github a stale empty `{}`.
|
|
36
|
+
*/
|
|
37
|
+
function gh(args, opts = {}) {
|
|
38
|
+
return require('./tracker-github').exec(args, opts);
|
|
39
|
+
}
|
|
40
|
+
|
|
32
41
|
function git(args, cwd, opts = {}) {
|
|
33
42
|
return run('git', args, { ...(cwd ? { cwd } : {}), ...opts });
|
|
34
43
|
}
|
|
@@ -453,9 +462,9 @@ function dirtyAny(wtPath) {
|
|
|
453
462
|
let _ghState = null;
|
|
454
463
|
function ghState() {
|
|
455
464
|
if (_ghState) return _ghState;
|
|
456
|
-
if (!
|
|
457
|
-
if (
|
|
458
|
-
const who =
|
|
465
|
+
if (!gh(['--version']).ok) return (_ghState = { ok: false, reason: 'missing' });
|
|
466
|
+
if (gh(['auth', 'status', '--active']).ok) return (_ghState = { ok: true, reason: null });
|
|
467
|
+
const who = gh(['api', 'user', '-q', '.login']);
|
|
459
468
|
if (who.ok && who.stdout) {
|
|
460
469
|
if (_ghLogin === undefined) _ghLogin = who.stdout;
|
|
461
470
|
return (_ghState = { ok: true, reason: null });
|
|
@@ -469,14 +478,14 @@ function ghAvailable() {
|
|
|
469
478
|
|
|
470
479
|
/** gh issue edit — returns {ok, stderr}. cwd must be inside the repo so gh resolves the remote. */
|
|
471
480
|
function ghIssueEdit(repo, issueNum, args) {
|
|
472
|
-
return
|
|
481
|
+
return gh(['issue', 'edit', String(issueNum), ...args], { cwd: repo });
|
|
473
482
|
}
|
|
474
483
|
|
|
475
484
|
/** The current gh user's login (`gh api user`), or null if it can't be determined. Cached. */
|
|
476
485
|
let _ghLogin;
|
|
477
486
|
function ghCurrentLogin() {
|
|
478
487
|
if (_ghLogin !== undefined) return _ghLogin;
|
|
479
|
-
const r =
|
|
488
|
+
const r = gh(['api', 'user', '-q', '.login']);
|
|
480
489
|
_ghLogin = r.ok && r.stdout ? r.stdout : null;
|
|
481
490
|
return _ghLogin;
|
|
482
491
|
}
|
|
@@ -484,7 +493,7 @@ function ghCurrentLogin() {
|
|
|
484
493
|
/** Raw `gh api` call — returns {ok, stdout, stderr, code}. cwd must be inside the repo so `{owner}`
|
|
485
494
|
* / `{repo}` placeholders resolve to the right remote. */
|
|
486
495
|
function ghApi(repo, args) {
|
|
487
|
-
return
|
|
496
|
+
return gh(['api', ...args], { cwd: repo });
|
|
488
497
|
}
|
|
489
498
|
|
|
490
499
|
/**
|
|
@@ -562,7 +571,7 @@ function ghIssueRelease(repo, issueNum, opts = {}) {
|
|
|
562
571
|
note = 'could not read who holds the claim — unassigned @me only';
|
|
563
572
|
}
|
|
564
573
|
}
|
|
565
|
-
const r =
|
|
574
|
+
const r = gh(['issue', 'edit', String(issueNum),
|
|
566
575
|
'--remove-assignee', ['@me', ...others].join(','), '--remove-label', 'in-progress'], { cwd: repo });
|
|
567
576
|
if (r.ok || !isGraphqlRateLimit(r.stderr)) return { ...r, others: r.ok ? others : [], caller, note };
|
|
568
577
|
|
|
@@ -586,7 +595,7 @@ function ghIssueRelease(repo, issueNum, opts = {}) {
|
|
|
586
595
|
* bad repo, network, unparseable). Callers treat null as "couldn't read" — never as "empty".
|
|
587
596
|
*/
|
|
588
597
|
function ghIssueView(repo, issueNum, fields) {
|
|
589
|
-
const r =
|
|
598
|
+
const r = gh(['issue', 'view', String(issueNum), '--json', fields.join(',')], { cwd: repo });
|
|
590
599
|
if (!r.ok) return null;
|
|
591
600
|
try { return JSON.parse(r.stdout); }
|
|
592
601
|
catch (_) { return null; }
|
|
@@ -604,7 +613,7 @@ function ghIssueView(repo, issueNum, fields) {
|
|
|
604
613
|
* someone approved it?", so the core-path pause costs one read on the resume path.
|
|
605
614
|
*/
|
|
606
615
|
function ghPrForBranch(repo, branch) {
|
|
607
|
-
const r =
|
|
616
|
+
const r = gh(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url,state,author,headRefOid,reviews'], { cwd: repo });
|
|
608
617
|
if (!r.ok) return { error: (r.stderr || '').split('\n')[0] || `gh pr list exited ${r.code}` };
|
|
609
618
|
try {
|
|
610
619
|
const list = JSON.parse(r.stdout || '[]');
|
|
@@ -618,7 +627,7 @@ function ghPrForBranch(repo, branch) {
|
|
|
618
627
|
* tools/lib/machine-trailer.js fails closed on it.
|
|
619
628
|
*/
|
|
620
629
|
function ghRepoVisibility(repo) {
|
|
621
|
-
const r =
|
|
630
|
+
const r = gh(['repo', 'view', '--json', 'visibility', '-q', '.visibility'], { cwd: repo });
|
|
622
631
|
if (!r.ok) return null;
|
|
623
632
|
const v = (r.stdout || '').trim().toUpperCase();
|
|
624
633
|
return /^[A-Z]+$/.test(v) ? v : null;
|
|
@@ -626,18 +635,18 @@ function ghRepoVisibility(repo) {
|
|
|
626
635
|
|
|
627
636
|
/** #350: open a PR `head` → `base`. Returns {ok, url, stderr}; `url` is gh's printed PR URL. */
|
|
628
637
|
function ghPrCreate(repo, { base, head, title, body }) {
|
|
629
|
-
const r =
|
|
638
|
+
const r = gh(['pr', 'create', '--base', base, '--head', head, '--title', title, '--body', body], { cwd: repo });
|
|
630
639
|
const url = (r.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean).pop() || null;
|
|
631
640
|
return { ok: r.ok, url, stderr: r.stderr };
|
|
632
641
|
}
|
|
633
642
|
|
|
634
643
|
/** #350: close a PR whose work landed by squash elsewhere, with a comment saying where. */
|
|
635
644
|
function ghPrClose(repo, num, comment) {
|
|
636
|
-
return
|
|
645
|
+
return gh(['pr', 'close', String(num), '--comment', comment], { cwd: repo });
|
|
637
646
|
}
|
|
638
647
|
|
|
639
648
|
function ghIssueComment(repo, issueNum, body) {
|
|
640
|
-
const r =
|
|
649
|
+
const r = gh(['issue', 'comment', String(issueNum), '--body', body], { cwd: repo });
|
|
641
650
|
if (r.ok || !isGraphqlRateLimit(r.stderr)) return r;
|
|
642
651
|
return ghApi(repo, ['-X', 'POST', `repos/{owner}/{repo}/issues/${issueNum}/comments`, '-f', `body=${body}`]);
|
|
643
652
|
}
|
|
@@ -677,7 +686,7 @@ function ghIssueLabelActors(repo, issueNum, label) {
|
|
|
677
686
|
* contract as ghIssueView: a caller must not read absence as proof a label is missing.
|
|
678
687
|
*/
|
|
679
688
|
function ghListLabels(repo) {
|
|
680
|
-
const r =
|
|
689
|
+
const r = gh(['label', 'list', '--limit', '500', '--json', 'name', '-q', '.[].name'], { cwd: repo });
|
|
681
690
|
if (!r.ok) return null;
|
|
682
691
|
return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
|
|
683
692
|
}
|
|
@@ -688,7 +697,7 @@ function ghListLabels(repo) {
|
|
|
688
697
|
* the same contract as ghIssueView; a caller must not read a failed call as "no issues".
|
|
689
698
|
*/
|
|
690
699
|
function ghIssueListByLabel(repo, label, state, fields) {
|
|
691
|
-
const r =
|
|
700
|
+
const r = gh(['issue', 'list', '--label', label, '--state', state,
|
|
692
701
|
'--json', fields.join(','), '--limit', '200'], { cwd: repo });
|
|
693
702
|
if (!r.ok) return null;
|
|
694
703
|
try { return JSON.parse(r.stdout); }
|
|
@@ -721,7 +730,7 @@ function ghOpenIssueNumbersByLabel(repo, label) {
|
|
|
721
730
|
* instead; this is only for tearing down a spent `group:<key>` label (CONVENTIONS.md §5).
|
|
722
731
|
*/
|
|
723
732
|
function ghLabelDelete(repo, name) {
|
|
724
|
-
return
|
|
733
|
+
return gh(['label', 'delete', name, '--yes'], { cwd: repo });
|
|
725
734
|
}
|
|
726
735
|
|
|
727
736
|
/**
|
|
@@ -734,7 +743,7 @@ function ghLabelDelete(repo, name) {
|
|
|
734
743
|
* ghListLabels and only calls this for a name confirmed missing.
|
|
735
744
|
*/
|
|
736
745
|
function ghLabelCreate(repo, name, color, description) {
|
|
737
|
-
return
|
|
746
|
+
return gh(['label', 'create', name, '--color', color, '--description', description], { cwd: repo });
|
|
738
747
|
}
|
|
739
748
|
|
|
740
749
|
/**
|
|
@@ -744,7 +753,7 @@ function ghLabelCreate(repo, name, color, description) {
|
|
|
744
753
|
* description has drifted from the handbook's (#364).
|
|
745
754
|
*/
|
|
746
755
|
function ghListLabelsDetailed(repo) {
|
|
747
|
-
const r =
|
|
756
|
+
const r = gh(['label', 'list', '--limit', '500', '--json', 'name,description'], { cwd: repo });
|
|
748
757
|
if (!r.ok) return null;
|
|
749
758
|
try {
|
|
750
759
|
const rows = JSON.parse(r.stdout);
|
|
@@ -760,7 +769,7 @@ function ghListLabelsDetailed(repo) {
|
|
|
760
769
|
* read with a differing description.
|
|
761
770
|
*/
|
|
762
771
|
function ghLabelEditDescription(repo, name, description) {
|
|
763
|
-
return
|
|
772
|
+
return gh(['label', 'edit', name, '--description', description], { cwd: repo });
|
|
764
773
|
}
|
|
765
774
|
|
|
766
775
|
/**
|
|
@@ -870,7 +879,7 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
|
870
879
|
// judge whether it is merely slow or structurally WEDGED (tools/lib/ci-verdict.js) — createdAt for
|
|
871
880
|
// the age backstop, databaseId to look up its job count (ghRunJobCount, below — a second call, made
|
|
872
881
|
// lazily by the caller, never here: an ordinary green check must not pay for a read it never needs).
|
|
873
|
-
const r =
|
|
882
|
+
const r = gh(['run', 'list', '--branch', branch, '-L', String(limit),
|
|
874
883
|
// workflowName is additive (#338): `colab release cut`'s full-suite condition groups the rows by
|
|
875
884
|
// workflow — a workflow whose only run at the sha was cancelled never ran its suite.
|
|
876
885
|
// event is additive (#451): summarizeRunsForCommit drops `dynamic` rows (workflows the repo
|
|
@@ -902,7 +911,7 @@ function ghRunsForCommit(repo, branch, sha, limit = 10) {
|
|
|
902
911
|
function ghApiConditional(repo, apiPath, etag) {
|
|
903
912
|
const ciWait = require('./ci-wait');
|
|
904
913
|
const args = ['api', '-i', ...(etag ? ['-H', `If-None-Match: ${etag}`] : []), apiPath];
|
|
905
|
-
const r =
|
|
914
|
+
const r = gh(args, { cwd: repo, timeoutMs: 60000 });
|
|
906
915
|
const http = ciWait.parseHttp(r.stdout);
|
|
907
916
|
return ciWait.classifyResponse({ ...http, stderr: r.stderr });
|
|
908
917
|
}
|
|
@@ -926,7 +935,7 @@ function ghRunsAtShaRest(repo, sha, branch) {
|
|
|
926
935
|
* the first real read, not by a probe in front of it (`gh auth status` costs a REST + a GraphQL). */
|
|
927
936
|
let _ghInstalled;
|
|
928
937
|
function ghInstalled() {
|
|
929
|
-
if (_ghInstalled === undefined) _ghInstalled =
|
|
938
|
+
if (_ghInstalled === undefined) _ghInstalled = gh(['--version']).ok;
|
|
930
939
|
return _ghInstalled;
|
|
931
940
|
}
|
|
932
941
|
|
|
@@ -937,7 +946,7 @@ function ghInstalled() {
|
|
|
937
946
|
*/
|
|
938
947
|
function ghRunsForRef(repo, ref, sha, limit = 20) {
|
|
939
948
|
if (!sha) return null;
|
|
940
|
-
const r =
|
|
949
|
+
const r = gh(['run', 'list', '--branch', ref, '-L', String(limit),
|
|
941
950
|
'--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,attempt'], { cwd: repo });
|
|
942
951
|
if (!r.ok) return null;
|
|
943
952
|
let runs;
|
|
@@ -957,7 +966,7 @@ function ghRunForCommit(repo, branch, sha, limit = 10) {
|
|
|
957
966
|
*/
|
|
958
967
|
function ghRunsAtCommit(repo, sha, limit = 100) {
|
|
959
968
|
if (!sha) return null;
|
|
960
|
-
const r =
|
|
969
|
+
const r = gh(['run', 'list', '--commit', sha, '-L', String(limit),
|
|
961
970
|
'--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
|
|
962
971
|
if (!r.ok) return null;
|
|
963
972
|
let runs;
|
|
@@ -995,7 +1004,7 @@ function commitTimeMs(repo, sha) {
|
|
|
995
1004
|
* `truncated` is true when the read filled its limit, which a caller must treat as unread.
|
|
996
1005
|
*/
|
|
997
1006
|
function ghRunsSince(repo, branch, sinceDay, limit = 1000) {
|
|
998
|
-
const r =
|
|
1007
|
+
const r = gh(['run', 'list', '--branch', branch, '--created', `>=${sinceDay}`, '-L', String(limit),
|
|
999
1008
|
'--json', 'headSha,status,conclusion,createdAt,databaseId,workflowName,event'], { cwd: repo });
|
|
1000
1009
|
if (!r.ok) return null;
|
|
1001
1010
|
let runs;
|
|
@@ -1159,7 +1168,7 @@ function summarizeRepoOwnedRuns(forSha, sha) {
|
|
|
1159
1168
|
*/
|
|
1160
1169
|
function ghRunJobCount(repo, runDatabaseId) {
|
|
1161
1170
|
if (runDatabaseId === null || runDatabaseId === undefined) return null;
|
|
1162
|
-
const r =
|
|
1171
|
+
const r = gh(['run', 'view', String(runDatabaseId), '--json', 'jobs', '-q', '.jobs | length'], { cwd: repo });
|
|
1163
1172
|
if (!r.ok) return null;
|
|
1164
1173
|
const n = Number(r.stdout);
|
|
1165
1174
|
return Number.isFinite(n) ? n : null;
|
|
@@ -1186,7 +1195,7 @@ function ghRunJobCount(repo, runDatabaseId) {
|
|
|
1186
1195
|
*/
|
|
1187
1196
|
function ghRunJobs(repo, runDatabaseId) {
|
|
1188
1197
|
if (runDatabaseId === null || runDatabaseId === undefined) return null;
|
|
1189
|
-
const r =
|
|
1198
|
+
const r = gh(['run', 'view', String(runDatabaseId), '--json', 'jobs'], { cwd: repo });
|
|
1190
1199
|
if (!r.ok) return null;
|
|
1191
1200
|
let parsed;
|
|
1192
1201
|
try { parsed = JSON.parse(r.stdout); } catch (_) { return null; }
|
|
@@ -1211,7 +1220,7 @@ function ghRunJobs(repo, runDatabaseId) {
|
|
|
1211
1220
|
*/
|
|
1212
1221
|
function ghCommitCheckRuns(repo, sha) {
|
|
1213
1222
|
if (!sha) return null;
|
|
1214
|
-
const r =
|
|
1223
|
+
const r = gh(['api', `repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100`,
|
|
1215
1224
|
'--jq', '[.check_runs[] | {id, name, status, conclusion, suite: .check_suite.id, annotations: .output.annotations_count}]'], { cwd: repo });
|
|
1216
1225
|
if (!r.ok) return null;
|
|
1217
1226
|
try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
|
|
@@ -1220,7 +1229,7 @@ function ghCommitCheckRuns(repo, sha) {
|
|
|
1220
1229
|
/** One check run's annotations as `[{title, message, level}]`, or null on failure (#493). */
|
|
1221
1230
|
function ghCheckRunAnnotations(repo, checkRunId) {
|
|
1222
1231
|
if (checkRunId === null || checkRunId === undefined) return null;
|
|
1223
|
-
const r =
|
|
1232
|
+
const r = gh(['api', `repos/{owner}/{repo}/check-runs/${checkRunId}/annotations`,
|
|
1224
1233
|
'--jq', '[.[] | {title, message, level: .annotation_level}]'], { cwd: repo });
|
|
1225
1234
|
if (!r.ok) return null;
|
|
1226
1235
|
try { const v = JSON.parse(r.stdout); return Array.isArray(v) ? v : null; } catch (_) { return null; }
|
|
@@ -1237,10 +1246,10 @@ function ghCheckRunAnnotations(repo, checkRunId) {
|
|
|
1237
1246
|
function ghWorkflowDispatch(repo, workflowFile, ref, inputs = {}) {
|
|
1238
1247
|
const flags = [];
|
|
1239
1248
|
for (const [k, v] of Object.entries(inputs)) flags.push('-f', `${k}=${v}`);
|
|
1240
|
-
const first =
|
|
1249
|
+
const first = gh(['workflow', 'run', workflowFile, '--ref', ref, ...flags], { cwd: repo });
|
|
1241
1250
|
if (first.ok) return { ok: true, withInputs: true, detail: '' };
|
|
1242
1251
|
if (!flags.length) return { ok: false, withInputs: false, detail: (first.stderr || first.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
|
|
1243
|
-
const second =
|
|
1252
|
+
const second = gh(['workflow', 'run', workflowFile, '--ref', ref], { cwd: repo });
|
|
1244
1253
|
if (second.ok) return { ok: true, withInputs: false, detail: (first.stderr || '').trim().split('\n')[0] || '' };
|
|
1245
1254
|
return { ok: false, withInputs: false, detail: (second.stderr || second.stdout || '').trim().split('\n')[0] || 'gh workflow run failed' };
|
|
1246
1255
|
}
|
|
@@ -1250,7 +1259,7 @@ function ghWorkflowDispatch(repo, workflowFile, ref, inputs = {}) {
|
|
|
1250
1259
|
* (that pairing is exactly what `colab claim` writes). Returns array of numbers, or null on failure.
|
|
1251
1260
|
*/
|
|
1252
1261
|
function ghAssignedIssues(repo) {
|
|
1253
|
-
const r =
|
|
1262
|
+
const r = gh(['issue', 'list', '--assignee', '@me', '--label', 'in-progress', '--state', 'open',
|
|
1254
1263
|
'--json', 'number', '--limit', '200'], { cwd: repo });
|
|
1255
1264
|
if (!r.ok) return null;
|
|
1256
1265
|
try { return JSON.parse(r.stdout).map((o) => o.number); }
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/tracker-github.js — the GitHub implementation of the tracker contract (#500), and the
|
|
4
|
+
* ONLY place in the CLI that spawns `gh`. Every `gh` call in tools/colab and tools/lib/git.js
|
|
5
|
+
* reaches the binary through `exec` below; the contract it implements is tools/lib/tracker.js.
|
|
6
|
+
*
|
|
7
|
+
* Two layers, on purpose:
|
|
8
|
+
* - `exec(args, opts)` — the raw spawn. git.js's `gh*` helpers call it (through their own lazy
|
|
9
|
+
* `gh()`), so their bodies, exports and callers stay exactly as they were.
|
|
10
|
+
* - `create(repoAbs)` — a repo-bound object carrying the contract's methods (tracker.METHODS).
|
|
11
|
+
* Methods are synchronous, never throw on an environment failure (no gh, no remote, offline —
|
|
12
|
+
* all come back as data), and keep the existing helpers' return shapes: a write returns
|
|
13
|
+
* git.run's `{ ok, code, stdout, stderr, error, timedOut }`; a list read adds `data` (parsed
|
|
14
|
+
* JSON, or `null` when the call failed, printed nothing, or printed something unparseable —
|
|
15
|
+
* `null` is "could not read", never "none").
|
|
16
|
+
*
|
|
17
|
+
* Behaviour-preserving by construction: every method spawns the exact argv and options the call
|
|
18
|
+
* site it replaced spawned (pinned by tools/lib/tracker-github.test.js's argv table).
|
|
19
|
+
*
|
|
20
|
+
* This module must NOT require ./tracker (tracker requires this one), and git.js must never require
|
|
21
|
+
* this module at its top level: git.js ends in `module.exports = {…}`, which REPLACES the exports
|
|
22
|
+
* object, so a load-time cycle would hand this module a stale empty `{}`. `git.run` is therefore
|
|
23
|
+
* looked up at call time, never captured — tests also swap PATH between calls, so the binary is
|
|
24
|
+
* resolved per call, never cached.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
let _runner = null; // test seam only — see withRunner
|
|
28
|
+
|
|
29
|
+
/** Spawn `gh <args>` with `opts` (git.run's options: cwd, timeoutMs, maxBuffer, …). */
|
|
30
|
+
function exec(args, opts = {}) {
|
|
31
|
+
return _runner ? _runner(args, opts) : require('./git').run('gh', args, opts);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Run `fn` with every `gh` spawn — including the ones git.js's helpers make — routed to
|
|
36
|
+
* `runner(args, opts)` instead of the binary. Synchronous only; the previous runner is restored
|
|
37
|
+
* even when `fn` throws.
|
|
38
|
+
*/
|
|
39
|
+
function withRunner(runner, fn) {
|
|
40
|
+
const prev = _runner;
|
|
41
|
+
_runner = runner;
|
|
42
|
+
try { return fn(); } finally { _runner = prev; }
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Parsed stdout as `data`, or null on failure / empty / unparseable output. */
|
|
46
|
+
function withData(r) {
|
|
47
|
+
let data = null;
|
|
48
|
+
if (r.ok && r.stdout) { try { data = JSON.parse(r.stdout); } catch (_) { data = null; } }
|
|
49
|
+
return { ...r, data };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function create(repoAbs) {
|
|
53
|
+
const git = () => require('./git');
|
|
54
|
+
const at = { cwd: repoAbs };
|
|
55
|
+
return {
|
|
56
|
+
kind: 'github',
|
|
57
|
+
repo: repoAbs,
|
|
58
|
+
|
|
59
|
+
// --- identity / availability -------------------------------------------------------------
|
|
60
|
+
state: () => git().ghState(),
|
|
61
|
+
currentLogin: () => git().ghCurrentLogin(),
|
|
62
|
+
|
|
63
|
+
// --- issues ------------------------------------------------------------------------------
|
|
64
|
+
issueView: (num, fields) => git().ghIssueView(repoAbs, num, fields),
|
|
65
|
+
issueListAll: ({ limit, fields, maxBuffer } = {}) => withData(exec(
|
|
66
|
+
['issue', 'list', '--state', 'all', '--limit', String(limit), '--json', fields.join(',')],
|
|
67
|
+
{ ...at, ...(maxBuffer ? { maxBuffer } : {}) })),
|
|
68
|
+
issueCreate: ({ title, body }) => {
|
|
69
|
+
const r = exec(['issue', 'create', '--title', title, '--body', body], at);
|
|
70
|
+
const m = r.ok ? /\/issues\/([0-9]+)/.exec(r.stdout || '') : null;
|
|
71
|
+
return { ...r, number: m ? Number(m[1]) : null, url: m ? (r.stdout || '').trim() : null };
|
|
72
|
+
},
|
|
73
|
+
issueComment: (num, body) => git().ghIssueComment(repoAbs, num, body),
|
|
74
|
+
issueClose: (num, { reason } = {}) =>
|
|
75
|
+
exec(['issue', 'close', String(num), ...(reason ? ['--reason', reason] : [])], at),
|
|
76
|
+
issueRelease: (num, opts) => git().ghIssueRelease(repoAbs, num, opts),
|
|
77
|
+
claimHolder: (num) => git().ghClaimHolder(repoAbs, num),
|
|
78
|
+
|
|
79
|
+
// --- labels ------------------------------------------------------------------------------
|
|
80
|
+
labelList: () => git().ghListLabels(repoAbs),
|
|
81
|
+
|
|
82
|
+
// --- pull requests -----------------------------------------------------------------------
|
|
83
|
+
prForBranch: (branch) => git().ghPrForBranch(repoAbs, branch),
|
|
84
|
+
prCreate: (spec) => git().ghPrCreate(repoAbs, spec),
|
|
85
|
+
prClose: (num, comment) => git().ghPrClose(repoAbs, num, comment),
|
|
86
|
+
prList: ({ base, head, state, limit, fields }) => withData(exec(
|
|
87
|
+
['pr', 'list', '--base', base, '--head', head, '--state', state, '--limit', String(limit),
|
|
88
|
+
'--json', fields.join(',')], at)),
|
|
89
|
+
prEdit: (num, { title, body }) =>
|
|
90
|
+
exec(['pr', 'edit', String(num), '--title', title, '--body', body], at),
|
|
91
|
+
|
|
92
|
+
// --- CI runs -----------------------------------------------------------------------------
|
|
93
|
+
runList: ({ branch, commit, limit, fields }) => withData(exec(
|
|
94
|
+
['run', 'list', '--branch', branch, ...(commit ? ['--commit', commit] : []), '-L', String(limit),
|
|
95
|
+
'--json', fields.join(',')], at)),
|
|
96
|
+
|
|
97
|
+
// --- releases ----------------------------------------------------------------------------
|
|
98
|
+
releaseView: (tag) => exec(['release', 'view', tag, '--json', 'tagName'], at),
|
|
99
|
+
releaseCreate: (tag, { notesFile, final = false }) => {
|
|
100
|
+
const releaseCut = require('./release-cut'); // owns the argv (release-cut.test.js pins it)
|
|
101
|
+
return exec(final ? releaseCut.finalReleaseArgs(tag, notesFile) : releaseCut.prereleaseArgs(tag, notesFile), at);
|
|
102
|
+
},
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
module.exports = { exec, withRunner, create };
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/tracker.js — the tracker contract (#500): what the CLI asks of an issue tracker, named
|
|
4
|
+
* once, so an implementation other than GitHub (and #501's in-memory fake) has a method set to
|
|
5
|
+
* satisfy instead of a scatter of `gh` argv to imitate.
|
|
6
|
+
*
|
|
7
|
+
* The only implementation today is tools/lib/tracker-github.js. Semantics every implementation
|
|
8
|
+
* keeps:
|
|
9
|
+
* - synchronous — the CLI is spawnSync throughout;
|
|
10
|
+
* - bound to one repo — `forRepo(repoAbs)` fixes it, so no method takes a repo argument;
|
|
11
|
+
* - never throws on an environment failure (no tracker binary, no remote, offline): results are
|
|
12
|
+
* data. Writes return `{ ok, code, stdout, stderr, … }`; list reads add `data`, `null` meaning
|
|
13
|
+
* "could not read" and never "none"; the read helpers keep their existing null-on-failure
|
|
14
|
+
* contract.
|
|
15
|
+
*
|
|
16
|
+
* Deliberately NOT in the contract yet (a question for #501, not this module): the CI-run
|
|
17
|
+
* summarisers and REST probes, label create/delete/edit, raw `issue edit` flags and raw `api`
|
|
18
|
+
* access. They still reach `gh` only through the adapter's `exec`.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const METHODS = Object.freeze([
|
|
22
|
+
{ name: 'state', kind: 'read', returns: '{ ok, reason }' },
|
|
23
|
+
{ name: 'currentLogin', kind: 'read', returns: 'login | null' },
|
|
24
|
+
{ name: 'issueView', kind: 'read', returns: 'object | null' },
|
|
25
|
+
{ name: 'issueListAll', kind: 'read', returns: 'result + data: issue[] | null' },
|
|
26
|
+
{ name: 'issueCreate', kind: 'write', returns: 'result + number, url' },
|
|
27
|
+
{ name: 'issueComment', kind: 'write', returns: 'result' },
|
|
28
|
+
{ name: 'issueClose', kind: 'write', returns: 'result' },
|
|
29
|
+
{ name: 'issueRelease', kind: 'write', returns: '{ ok, stderr, code, others, caller, note }' },
|
|
30
|
+
{ name: 'claimHolder', kind: 'read', returns: '{ assignees, claimer }' },
|
|
31
|
+
{ name: 'labelList', kind: 'read', returns: 'name[] | null' },
|
|
32
|
+
{ name: 'prForBranch', kind: 'read', returns: '{ pr } | { error }' },
|
|
33
|
+
{ name: 'prCreate', kind: 'write', returns: '{ ok, url, stderr }' },
|
|
34
|
+
{ name: 'prClose', kind: 'write', returns: 'result' },
|
|
35
|
+
{ name: 'prList', kind: 'read', returns: 'result + data: pr[] | null' },
|
|
36
|
+
{ name: 'prEdit', kind: 'write', returns: 'result' },
|
|
37
|
+
{ name: 'runList', kind: 'read', returns: 'result + data: run[] | null' },
|
|
38
|
+
{ name: 'releaseView', kind: 'read', returns: 'result' },
|
|
39
|
+
{ name: 'releaseCreate', kind: 'write', returns: 'result' },
|
|
40
|
+
].map(Object.freeze));
|
|
41
|
+
|
|
42
|
+
/** Throw, naming every contract method `impl` lacks. Returns `impl` when it is complete. */
|
|
43
|
+
function assertImplements(impl, label = 'tracker') {
|
|
44
|
+
const missing = METHODS.filter((m) => !impl || typeof impl[m.name] !== 'function').map((m) => m.name);
|
|
45
|
+
if (missing.length) throw new Error(`${label} does not implement the tracker contract: missing ${missing.join(', ')}`);
|
|
46
|
+
return impl;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const KINDS = { github: () => require('./tracker-github') };
|
|
50
|
+
const _checked = new Set();
|
|
51
|
+
|
|
52
|
+
/** The tracker for one repo. `kind` defaults to the one implementation, `github`. */
|
|
53
|
+
function forRepo(repoAbs, { kind = 'github' } = {}) {
|
|
54
|
+
const load = KINDS[kind];
|
|
55
|
+
if (!load) throw new Error(`unknown tracker kind "${kind}" (known: ${Object.keys(KINDS).join(', ')})`);
|
|
56
|
+
const impl = load().create(repoAbs);
|
|
57
|
+
if (!_checked.has(kind)) { assertImplements(impl, `tracker "${kind}"`); _checked.add(kind); }
|
|
58
|
+
return impl;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
module.exports = { METHODS, assertImplements, forRepo };
|