@futurelastic/colab-handbook 1.12.0-rc.60 → 1.12.0-rc.62
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/audit/audit.mjs +12 -0
- package/package.json +2 -1
- package/tools/colab +28 -10
- package/tools/lib/git.js +22 -8
- package/tools/lib/tracker-fake.js +195 -0
- package/tools/lib/tracker-scenarios.json +206 -0
- package/tools/lib/tracker.js +7 -4
- package/tools/lib/verify-runs.js +104 -0
package/audit/audit.mjs
CHANGED
|
@@ -109,6 +109,8 @@ const trustHumansLib = require("../tools/lib/trust-humans.js");
|
|
|
109
109
|
const hermeticLib = require("../tools/lib/hermetic.js");
|
|
110
110
|
// #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
|
|
111
111
|
const treeGreenLib = require("../tools/lib/tree-green.js");
|
|
112
|
+
// #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
|
|
113
|
+
const verifyRunsLib = require("../tools/lib/verify-runs.js");
|
|
112
114
|
// #410: the optional `gate:` block — read through the same module the skills name.
|
|
113
115
|
const gateLib = require("../tools/lib/gate.js");
|
|
114
116
|
// #417: CLAUDE.md as a thin shell over AGENTS.md — the @-import resolver and the tool-block table,
|
|
@@ -1363,6 +1365,16 @@ function auditRepo(target, ctx) {
|
|
|
1363
1365
|
if (!tr.valid) fail(tr.reason);
|
|
1364
1366
|
}
|
|
1365
1367
|
|
|
1368
|
+
// ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
|
|
1369
|
+
// Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
|
|
1370
|
+
// the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
|
|
1371
|
+
// list fails: the reader ignores it and applies the default, so the declaration does nothing.
|
|
1372
|
+
{
|
|
1373
|
+
const vp = verifyRunsLib.parsePolicy(cfg);
|
|
1374
|
+
info.shipCiWorkflows = vp.gate || vp.ignore.length ? { gate: vp.gate, ignore: vp.ignore } : null;
|
|
1375
|
+
for (const why of vp.problems) fail(why);
|
|
1376
|
+
}
|
|
1377
|
+
|
|
1366
1378
|
// ---- gate (#410) ----------------------------------------------------------
|
|
1367
1379
|
// Local = a fast smoke check, branch CI = the one authoritative gate. tools/lib/gate.js
|
|
1368
1380
|
// parseGate is the one reading. An invalid block fails: the reader falls back to the local full
|
package/package.json
CHANGED
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
"tools/colab",
|
|
18
18
|
"tools/lib/*.js",
|
|
19
19
|
"!tools/lib/*.test.js",
|
|
20
|
+
"tools/lib/tracker-scenarios.json",
|
|
20
21
|
"tools/lib/codec/*.js",
|
|
21
22
|
"tools/lib/codec/*.d.ts",
|
|
22
23
|
"tools/lib/codec/samples.json",
|
|
@@ -31,5 +32,5 @@
|
|
|
31
32
|
"engines": {
|
|
32
33
|
"node": ">=18"
|
|
33
34
|
},
|
|
34
|
-
"version": "1.12.0-rc.
|
|
35
|
+
"version": "1.12.0-rc.62"
|
|
35
36
|
}
|
package/tools/colab
CHANGED
|
@@ -47,6 +47,7 @@ const ciCure = require('./lib/ci-cure');
|
|
|
47
47
|
const ciVerdict = require('./lib/ci-verdict');
|
|
48
48
|
const baseCiVerdict = require('./lib/base-ci-verdict');
|
|
49
49
|
const treeGreen = require('./lib/tree-green');
|
|
50
|
+
const verifyRuns = require('./lib/verify-runs');
|
|
50
51
|
const ciWait = require('./lib/ci-wait'); // #495
|
|
51
52
|
const staleBase = require('./lib/stale-base');
|
|
52
53
|
const dirtyOwner = require('./lib/dirty-owner');
|
|
@@ -10422,10 +10423,13 @@ function trunkWorkflowFiles(repoAbs, sha) {
|
|
|
10422
10423
|
*/
|
|
10423
10424
|
function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
10424
10425
|
if (!gh) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: `gh not usable (${ghUnusableWhy(repoAbs)}) — cannot confirm CI` } };
|
|
10425
|
-
|
|
10426
|
+
// #503: only runs that VERIFY the code count — a post-CI release/deploy run at the same sha is set
|
|
10427
|
+
// aside and named, never a red and never a reason to wait (tools/lib/verify-runs.js).
|
|
10428
|
+
const readOpts = { verifying: verifyRuns.parsePolicy(projectDoc(repoAbs)) };
|
|
10429
|
+
let run = git.ghRunForSha(repoAbs, target, undefined, undefined, readOpts);
|
|
10426
10430
|
let via = target;
|
|
10427
10431
|
if (run && run.status === 'none' && target !== trunk) {
|
|
10428
|
-
run = git.ghRunForSha(repoAbs, trunk);
|
|
10432
|
+
run = git.ghRunForSha(repoAbs, trunk, undefined, undefined, readOpts);
|
|
10429
10433
|
via = `${trunk} (line "${target}" has no runs — ungated, advisory)`;
|
|
10430
10434
|
}
|
|
10431
10435
|
if (!run) return { run: null, final: true, verdict: { ok: false, class: SELF_CLEARING, detail: 'gh run list failed' } };
|
|
@@ -10435,7 +10439,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
10435
10439
|
// Re-read the same sha by commit (the read `release finalize` already trusts, #339) before
|
|
10436
10440
|
// believing it. A failed re-read changes nothing: the branch read's `none` stands.
|
|
10437
10441
|
if (run.status === 'none' && target === trunk) {
|
|
10438
|
-
const byCommit = git.ghRunForCommitAnyRef(repoAbs, run.sha);
|
|
10442
|
+
const byCommit = git.ghRunForCommitAnyRef(repoAbs, run.sha, undefined, readOpts);
|
|
10439
10443
|
if (byCommit && byCommit.status !== 'none') {
|
|
10440
10444
|
run = byCommit;
|
|
10441
10445
|
via = `${trunk} (by commit — the branch-filtered read was empty)`;
|
|
@@ -10450,7 +10454,7 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
|
|
|
10450
10454
|
const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha));
|
|
10451
10455
|
if (fresh.fresh) {
|
|
10452
10456
|
verdict = { ok: false, class: SELF_CLEARING,
|
|
10453
|
-
detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${ciVerdict.EMPTY_READ_GRACE_MINUTES}m grace; retry later${excludedRunsNote(run)}` };
|
|
10457
|
+
detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${ciVerdict.EMPTY_READ_GRACE_MINUTES}m grace; retry later${excludedRunsNote(run)}${verifyRuns.setAsideNote(run.setAside)}` };
|
|
10454
10458
|
}
|
|
10455
10459
|
}
|
|
10456
10460
|
// #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
|
|
@@ -10521,7 +10525,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
|
|
|
10521
10525
|
*/
|
|
10522
10526
|
function classifyCiRun(repoAbs, run, at) {
|
|
10523
10527
|
const v = classifyCiRunRaw(repoAbs, run, at);
|
|
10524
|
-
return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) };
|
|
10528
|
+
return { ...v, detail: v.detail + excludedRunsNote(run) + supersededRunsNote(run) + verifyRuns.setAsideNote(run && run.setAside) };
|
|
10525
10529
|
}
|
|
10526
10530
|
|
|
10527
10531
|
/**
|
|
@@ -13648,6 +13652,13 @@ the same read (shipCiCheck's readCiVerdict): by branch, re-read by commit when e
|
|
|
13648
13652
|
workflows the repo does not own dropped (#451), each workflow judged by its newest run (#461).
|
|
13649
13653
|
Read-only: no claim, no label, no write.
|
|
13650
13654
|
|
|
13655
|
+
Only runs that VERIFY the code are judged (#503): push / pull_request / merge_group triggered.
|
|
13656
|
+
A run of any other trigger at the same sha — a workflow_run release (release-auto.yml), a
|
|
13657
|
+
scheduled finalize, a dispatch, a deploy — comes after the verdict and is set aside and named in
|
|
13658
|
+
the detail (--json: setAside). Override in .github/project.yml, by workflow name:
|
|
13659
|
+
ship-gate-workflows: [CI] exactly these workflows count, whatever their trigger
|
|
13660
|
+
ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered
|
|
13661
|
+
|
|
13651
13662
|
The first output word is one verdict:
|
|
13652
13663
|
GREEN every judged workflow's newest run at the sha succeeded — ship's row would pass
|
|
13653
13664
|
RED a judged run completed and did not succeed — trunk is red
|
|
@@ -13711,7 +13722,9 @@ function cmdTrunkCi(argv) {
|
|
|
13711
13722
|
const sha = r.run ? r.run.sha || null : null;
|
|
13712
13723
|
let detail = r.verdict.detail;
|
|
13713
13724
|
if (verdict === 'UNREADABLE' && gh && !git.ghState().ok) detail += ` (${ghUnusableWhy(repoAbs)})`;
|
|
13714
|
-
out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail,
|
|
13725
|
+
out = { verdict, trunk, sha, ok: r.verdict.ok, class: r.verdict.class || null, detail,
|
|
13726
|
+
...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}),
|
|
13727
|
+
...(r.run && Array.isArray(r.run.setAside) && r.run.setAside.length ? { setAside: r.run.setAside } : {}) };
|
|
13715
13728
|
if (key && verdict !== 'UNREADABLE' && sha === headSha) cache.put(key, out);
|
|
13716
13729
|
}
|
|
13717
13730
|
if (opts.json) {
|
|
@@ -13775,8 +13788,9 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
|
|
|
13775
13788
|
|
|
13776
13789
|
<run-id> wait for one workflow run (actions/runs/<id>)
|
|
13777
13790
|
--sha <sha> wait for EVERY repo-owned workflow at the sha (the verdict colab ship reads:
|
|
13778
|
-
newest run per workflow, dynamic workflows dropped — #451/#461
|
|
13779
|
-
run
|
|
13791
|
+
newest run per workflow, dynamic workflows dropped — #451/#461; only runs that
|
|
13792
|
+
verify the code, so a post-CI release/deploy run is set aside — #503); a sha
|
|
13793
|
+
with no run yet counts as pending until the deadline
|
|
13780
13794
|
--branch <b> narrow --sha to runs on that branch
|
|
13781
13795
|
--timeout <d> deadline: 45m (default), 90s, 1h, or seconds
|
|
13782
13796
|
|
|
@@ -13824,6 +13838,7 @@ function cmdCiWait(argv) {
|
|
|
13824
13838
|
return ciWait.EXIT.ALREADY_WAITING;
|
|
13825
13839
|
}
|
|
13826
13840
|
|
|
13841
|
+
const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
|
|
13827
13842
|
const poll = (etag) => {
|
|
13828
13843
|
const r = git.ghApiConditional(repoAbs, apiPath, etag);
|
|
13829
13844
|
if (r.kind !== 'ok') return r;
|
|
@@ -13833,7 +13848,9 @@ function cmdCiWait(argv) {
|
|
|
13833
13848
|
} else {
|
|
13834
13849
|
const rows = Array.isArray(r.json.workflow_runs) ? r.json.workflow_runs.map(ciWait.restRow).filter((x) => x.headSha === opts.sha) : null;
|
|
13835
13850
|
if (!rows) return { kind: 'error', status: r.status, detail: 'response has no workflow_runs' };
|
|
13836
|
-
|
|
13851
|
+
// #503: the same verifying-runs policy ship reads — a wait on trunk's head ends when the CI
|
|
13852
|
+
// that verifies the code ends, not when the post-CI release run does.
|
|
13853
|
+
summary = git.summarizeRunsForCommit(rows, opts.sha, { verifying: verifyPolicy });
|
|
13837
13854
|
const pick = rows.find((x) => x.databaseId === summary.databaseId);
|
|
13838
13855
|
summary = { ...summary, url: pick ? pick.url : null };
|
|
13839
13856
|
}
|
|
@@ -13856,11 +13873,12 @@ function cmdCiWait(argv) {
|
|
|
13856
13873
|
outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified,
|
|
13857
13874
|
waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
|
|
13858
13875
|
status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
|
|
13876
|
+
...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
|
|
13859
13877
|
};
|
|
13860
13878
|
if (opts.json) print(JSON.stringify(out, null, 2));
|
|
13861
13879
|
else {
|
|
13862
13880
|
print(`${res.outcome} ${target} — waited ${ciWait.fmtDuration(res.waitedMs)}, ${res.polls} poll(s), ${res.notModified} of them 304` +
|
|
13863
|
-
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}`);
|
|
13881
|
+
`${s.status ? ` · ${s.status}${s.conclusion ? `/${s.conclusion}` : ''}` : ''}${s.url ? ` · ${s.url}` : ''}${res.detail ? ` — ${res.detail}` : ''}${verifyRuns.setAsideNote(s.setAside)}`);
|
|
13864
13882
|
}
|
|
13865
13883
|
return code;
|
|
13866
13884
|
}
|
package/tools/lib/git.js
CHANGED
|
@@ -823,12 +823,12 @@ function ghLabelEditDescription(repo, name, description) {
|
|
|
823
823
|
* when tools/lib/ci-verdict.js finds the run WEDGED rather than merely slow. Nothing here waits or
|
|
824
824
|
* polls — it reports what is true at read time and lets the caller decide.
|
|
825
825
|
*/
|
|
826
|
-
function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin') {
|
|
826
|
+
function ghRunForSha(repo, branch, limit = 10, remote = remoteInfo(repo).name || 'origin', opts = {}) {
|
|
827
827
|
const head = run('git', ['ls-remote', remote, `refs/heads/${branch}`], { cwd: repo });
|
|
828
828
|
if (!head.ok) return null;
|
|
829
829
|
const sha = (head.stdout.split('\n')[0] || '').split('\t')[0].trim();
|
|
830
830
|
if (!sha) return null; // branch does not exist on the remote
|
|
831
|
-
return ghRunForCommit(repo, branch, sha, limit);
|
|
831
|
+
return ghRunForCommit(repo, branch, sha, limit, opts);
|
|
832
832
|
}
|
|
833
833
|
|
|
834
834
|
/**
|
|
@@ -955,8 +955,8 @@ function ghRunsForRef(repo, ref, sha, limit = 20) {
|
|
|
955
955
|
return runs.filter((x) => x && x.headSha === sha);
|
|
956
956
|
}
|
|
957
957
|
|
|
958
|
-
function ghRunForCommit(repo, branch, sha, limit = 10) {
|
|
959
|
-
return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha);
|
|
958
|
+
function ghRunForCommit(repo, branch, sha, limit = 10, opts = {}) {
|
|
959
|
+
return summarizeRunsForCommit(ghRunsForCommit(repo, branch, sha, limit), sha, opts);
|
|
960
960
|
}
|
|
961
961
|
|
|
962
962
|
/**
|
|
@@ -981,8 +981,8 @@ function ghRunsAtCommit(repo, sha, limit = 100) {
|
|
|
981
981
|
* empty trunk read `none`: the branch-filtered list was measured returning nothing for a trunk sha
|
|
982
982
|
* whose green run existed, and clearing on its own a minute later. Null on failure, as elsewhere.
|
|
983
983
|
*/
|
|
984
|
-
function ghRunForCommitAnyRef(repo, sha, limit = 50) {
|
|
985
|
-
return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha);
|
|
984
|
+
function ghRunForCommitAnyRef(repo, sha, limit = 50, opts = {}) {
|
|
985
|
+
return summarizeRunsForCommit(ghRunsAtCommit(repo, sha, limit), sha, opts);
|
|
986
986
|
}
|
|
987
987
|
|
|
988
988
|
/**
|
|
@@ -1029,6 +1029,7 @@ function excludedRunSummary(rows) {
|
|
|
1029
1029
|
return rows.map((x) => ({
|
|
1030
1030
|
workflowName: x.workflowName || null, status: x.status || null,
|
|
1031
1031
|
conclusion: x.conclusion || null, databaseId: x.databaseId || null,
|
|
1032
|
+
...(x.setAsideWhy ? { why: x.setAsideWhy } : {}),
|
|
1032
1033
|
}));
|
|
1033
1034
|
}
|
|
1034
1035
|
|
|
@@ -1043,15 +1044,28 @@ function excludedRunSummary(rows) {
|
|
|
1043
1044
|
* #461: the repo-owned rows are then reduced to the newest run per workflow (newestRunPerWorkflow,
|
|
1044
1045
|
* below); the rows that reduction set aside ride along as an additive `superseded` list, same shape
|
|
1045
1046
|
* as `excluded`, present only when non-empty. Every quantifier below runs over the reduced set.
|
|
1047
|
+
*
|
|
1048
|
+
* #503: `opts.verifying` (a tools/lib/verify-runs.js policy, `{gate, ignore}`) narrows the owned rows
|
|
1049
|
+
* to the runs that VERIFY the code — push / pull-request triggered, or the declared set — BEFORE the
|
|
1050
|
+
* per-workflow reduction; the rest (a `workflow_run` release, a scheduled finalize, a deploy) ride
|
|
1051
|
+
* along as `setAside`, each with its reason. Opt-in: without `opts.verifying` nothing changes, so
|
|
1052
|
+
* readers that never asked (release finalize, the base-ci advisory, ci-grant) read exactly as before.
|
|
1046
1053
|
*/
|
|
1047
|
-
function summarizeRunsForCommit(allForSha, sha) {
|
|
1054
|
+
function summarizeRunsForCommit(allForSha, sha, opts = {}) {
|
|
1048
1055
|
if (allForSha === null) return null;
|
|
1049
1056
|
const dropped = allForSha.filter((x) => !isRepoOwnedRun(x));
|
|
1050
|
-
|
|
1057
|
+
let owned = dropped.length ? allForSha.filter(isRepoOwnedRun) : allForSha;
|
|
1058
|
+
let setAside = [];
|
|
1059
|
+
if (opts && opts.verifying) {
|
|
1060
|
+
const split = require('./verify-runs').splitVerifying(owned, opts.verifying);
|
|
1061
|
+
owned = split.counted;
|
|
1062
|
+
setAside = split.setAside;
|
|
1063
|
+
}
|
|
1051
1064
|
const { heads, superseded } = newestRunPerWorkflow(owned);
|
|
1052
1065
|
const extra = {
|
|
1053
1066
|
...(dropped.length ? { excluded: excludedRunSummary(dropped) } : {}),
|
|
1054
1067
|
...(superseded.length ? { superseded: excludedRunSummary(superseded) } : {}),
|
|
1068
|
+
...(setAside.length ? { setAside: excludedRunSummary(setAside) } : {}),
|
|
1055
1069
|
};
|
|
1056
1070
|
const r = summarizeRepoOwnedRuns(heads, sha);
|
|
1057
1071
|
return { ...r, ...extra };
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* tools/lib/tracker-fake.js — an in-memory implementation of the tracker contract (#501).
|
|
4
|
+
*
|
|
5
|
+
* It exists for two readers:
|
|
6
|
+
* - tools/lib/tracker-contract.test.js runs every scenario in tools/lib/tracker-scenarios.json
|
|
7
|
+
* against it, next to the GitHub adapter. When both pass the same scenarios, the scenarios
|
|
8
|
+
* describe the contract rather than one implementation's habits.
|
|
9
|
+
* - a consumer of this package that wants a tracker in a test without a network.
|
|
10
|
+
*
|
|
11
|
+
* `create(repoAbs, given)` seeds it from a scenario's `given` block (the shape is documented in
|
|
12
|
+
* tracker-scenarios.json's `given` key). Semantics follow tools/lib/tracker.js: synchronous,
|
|
13
|
+
* bound to one repo, never throws on an "environment" failure — `given.offline: true` makes every
|
|
14
|
+
* read come back as "could not read" (null, or `data: null`) and every write as `ok: false`.
|
|
15
|
+
*
|
|
16
|
+
* Fidelity points that a scenario pins, because GitHub behaves this way and a caller relies on it:
|
|
17
|
+
* - issues and pull requests share one number sequence;
|
|
18
|
+
* - a closed issue carries `stateReason` COMPLETED or NOT_PLANNED;
|
|
19
|
+
* - the claimer of an issue is the actor of the LATEST `labeled in-progress` event (tools/lib/git.js
|
|
20
|
+
* ghClaimHolder), and release unassigns the caller plus that claimer unless `selfOnly`;
|
|
21
|
+
* - list reads come back newest first.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
function result(ok, extra = {}) {
|
|
25
|
+
return { ok, code: ok ? 0 : 1, stdout: '', stderr: ok ? '' : 'tracker unavailable (fake: offline)',
|
|
26
|
+
error: null, timedOut: false, ...extra };
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function fail(stderr) {
|
|
30
|
+
return { ok: false, code: 1, stdout: '', stderr, error: null, timedOut: false };
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
|
|
34
|
+
const pick = (obj, fields) => Object.fromEntries(fields.filter((f) => f in obj).map((f) => [f, obj[f]]));
|
|
35
|
+
|
|
36
|
+
function create(repoAbs, given = {}) {
|
|
37
|
+
const login = given.login === undefined ? 'fake-user' : given.login;
|
|
38
|
+
const offline = Boolean(given.offline);
|
|
39
|
+
const labels = clone(given.labels || []);
|
|
40
|
+
const issues = new Map();
|
|
41
|
+
const prs = new Map();
|
|
42
|
+
const runs = clone(given.runs || []);
|
|
43
|
+
const releases = new Map((given.releases || []).map((r) => [r.tag, clone(r)]));
|
|
44
|
+
const base = `https://tracker.invalid/${String(repoAbs).replace(/^\/+/, '')}`;
|
|
45
|
+
|
|
46
|
+
for (const i of given.issues || []) {
|
|
47
|
+
issues.set(i.number, {
|
|
48
|
+
number: i.number, title: i.title || '', body: i.body || '', state: i.state || 'OPEN',
|
|
49
|
+
stateReason: i.stateReason || (i.state === 'CLOSED' ? 'COMPLETED' : ''),
|
|
50
|
+
createdAt: i.createdAt || null, closedAt: i.closedAt || null,
|
|
51
|
+
labels: clone(i.labels || []), assignees: clone(i.assignees || []),
|
|
52
|
+
comments: (i.comments || []).map((c) => ({ author: c.author, body: c.body })),
|
|
53
|
+
events: clone(i.events || []),
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
for (const p of given.prs || []) {
|
|
57
|
+
prs.set(p.number, { reviews: [], body: '', state: 'OPEN', headRefOid: null, mergedAt: null, ...clone(p) });
|
|
58
|
+
}
|
|
59
|
+
const nextNumber = () => Math.max(0, ...issues.keys(), ...prs.keys()) + 1;
|
|
60
|
+
|
|
61
|
+
/** The issue as `gh issue view --json` shapes it: label/assignee/comment objects, not strings. */
|
|
62
|
+
function issueShape(i) {
|
|
63
|
+
return {
|
|
64
|
+
number: i.number, title: i.title, body: i.body, state: i.state, stateReason: i.stateReason,
|
|
65
|
+
createdAt: i.createdAt, closedAt: i.closedAt, url: `${base}/issues/${i.number}`,
|
|
66
|
+
labels: i.labels.map((name) => ({ name })),
|
|
67
|
+
assignees: i.assignees.map((l) => ({ login: l })),
|
|
68
|
+
comments: i.comments.map((c) => ({ author: { login: c.author }, body: c.body })),
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
function prShape(p) {
|
|
72
|
+
return {
|
|
73
|
+
number: p.number, title: p.title, body: p.body, state: p.state, headRefName: p.head,
|
|
74
|
+
baseRefName: p.base, headRefOid: p.headRefOid, mergedAt: p.mergedAt, reviews: clone(p.reviews),
|
|
75
|
+
author: { login: p.author }, url: `${base}/pull/${p.number}`,
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
function claimHolder(num) {
|
|
79
|
+
const i = issues.get(num);
|
|
80
|
+
if (offline || !i) return { assignees: null, claimer: null };
|
|
81
|
+
const actors = i.events.filter((e) => e.event === 'labeled' && e.label === 'in-progress').map((e) => e.actor);
|
|
82
|
+
return { assignees: [...i.assignees], claimer: actors.length ? actors[actors.length - 1] : null };
|
|
83
|
+
}
|
|
84
|
+
const withList = (data) => (offline ? result(false, { data: null }) : result(true, { stdout: JSON.stringify(data), data }));
|
|
85
|
+
|
|
86
|
+
return {
|
|
87
|
+
kind: 'fake',
|
|
88
|
+
repo: repoAbs,
|
|
89
|
+
|
|
90
|
+
state: () => (offline ? { ok: false, reason: 'missing' } : { ok: true, reason: null }),
|
|
91
|
+
currentLogin: () => (offline ? null : login),
|
|
92
|
+
|
|
93
|
+
issueView: (num, fields) => {
|
|
94
|
+
const i = issues.get(Number(num));
|
|
95
|
+
return offline || !i ? null : pick(issueShape(i), fields);
|
|
96
|
+
},
|
|
97
|
+
issueListAll: ({ limit, fields } = {}) => withList([...issues.values()]
|
|
98
|
+
.sort((a, b) => b.number - a.number).slice(0, limit).map((i) => pick(issueShape(i), fields))),
|
|
99
|
+
issueCreate: ({ title, body }) => {
|
|
100
|
+
if (offline) return { ...result(false), number: null, url: null };
|
|
101
|
+
const number = nextNumber();
|
|
102
|
+
issues.set(number, { number, title, body, state: 'OPEN', stateReason: '', createdAt: null, closedAt: null,
|
|
103
|
+
labels: [], assignees: [], comments: [], events: [] });
|
|
104
|
+
const url = `${base}/issues/${number}`;
|
|
105
|
+
return { ...result(true, { stdout: url }), number, url };
|
|
106
|
+
},
|
|
107
|
+
issueComment: (num, body) => {
|
|
108
|
+
const i = issues.get(Number(num));
|
|
109
|
+
if (offline) return result(false);
|
|
110
|
+
if (!i) return fail(`issue #${num} not found`);
|
|
111
|
+
i.comments.push({ author: login, body });
|
|
112
|
+
return result(true, { stdout: `${base}/issues/${num}#issuecomment-${i.comments.length}` });
|
|
113
|
+
},
|
|
114
|
+
issueClose: (num, { reason } = {}) => {
|
|
115
|
+
const i = issues.get(Number(num));
|
|
116
|
+
if (offline) return result(false);
|
|
117
|
+
if (!i) return fail(`issue #${num} not found`);
|
|
118
|
+
i.state = 'CLOSED';
|
|
119
|
+
i.stateReason = reason === 'not planned' ? 'NOT_PLANNED' : 'COMPLETED';
|
|
120
|
+
return result(true);
|
|
121
|
+
},
|
|
122
|
+
issueRelease: (num, opts = {}) => {
|
|
123
|
+
const caller = offline ? null : login;
|
|
124
|
+
if (offline) return { ...result(false), others: [], caller, note: '' };
|
|
125
|
+
const i = issues.get(Number(num));
|
|
126
|
+
if (!i) return { ...fail(`issue #${num} not found`), others: [], caller, note: '' };
|
|
127
|
+
let others = [];
|
|
128
|
+
let note = '';
|
|
129
|
+
if (!opts.selfOnly) {
|
|
130
|
+
const h = claimHolder(Number(num));
|
|
131
|
+
if (h.claimer && h.claimer !== caller && (h.assignees === null || h.assignees.includes(h.claimer))) others = [h.claimer];
|
|
132
|
+
else if (!h.claimer && h.assignees === null) note = 'could not read who holds the claim — unassigned @me only';
|
|
133
|
+
}
|
|
134
|
+
const drop = new Set([caller, ...others]);
|
|
135
|
+
i.assignees = i.assignees.filter((l) => !drop.has(l));
|
|
136
|
+
i.labels = i.labels.filter((l) => l !== 'in-progress');
|
|
137
|
+
return { ...result(true), others, caller, note };
|
|
138
|
+
},
|
|
139
|
+
claimHolder: (num) => claimHolder(Number(num)),
|
|
140
|
+
|
|
141
|
+
labelList: () => (offline ? null : [...labels]),
|
|
142
|
+
|
|
143
|
+
prForBranch: (branch) => {
|
|
144
|
+
if (offline) return { error: 'tracker unavailable (fake: offline)' };
|
|
145
|
+
const open = [...prs.values()].filter((p) => p.head === branch && p.state === 'OPEN').sort((a, b) => b.number - a.number);
|
|
146
|
+
if (!open.length) return { pr: null };
|
|
147
|
+
return { pr: pick(prShape(open[0]), ['number', 'url', 'state', 'author', 'headRefOid', 'reviews']) };
|
|
148
|
+
},
|
|
149
|
+
prCreate: ({ base: into, head, title, body }) => {
|
|
150
|
+
if (offline) return { ok: false, url: null, stderr: 'tracker unavailable (fake: offline)' };
|
|
151
|
+
if ([...prs.values()].some((p) => p.head === head && p.base === into && p.state === 'OPEN')) {
|
|
152
|
+
return { ok: false, url: null, stderr: `a pull request for branch "${head}" into branch "${into}" already exists` };
|
|
153
|
+
}
|
|
154
|
+
const number = nextNumber();
|
|
155
|
+
prs.set(number, { number, base: into, head, title, body, state: 'OPEN', author: login, headRefOid: null, mergedAt: null, reviews: [] });
|
|
156
|
+
return { ok: true, url: `${base}/pull/${number}`, stderr: '' };
|
|
157
|
+
},
|
|
158
|
+
prClose: (num, comment) => {
|
|
159
|
+
const p = prs.get(Number(num));
|
|
160
|
+
if (offline) return result(false);
|
|
161
|
+
if (!p) return fail(`pull request #${num} not found`);
|
|
162
|
+
p.state = 'CLOSED';
|
|
163
|
+
if (comment) (p.comments = p.comments || []).push({ author: login, body: comment });
|
|
164
|
+
return result(true);
|
|
165
|
+
},
|
|
166
|
+
prList: ({ base: into, head, state, limit, fields }) => withList([...prs.values()]
|
|
167
|
+
.filter((p) => p.base === into && p.head === head && (state === 'all' || p.state === String(state).toUpperCase()))
|
|
168
|
+
.sort((a, b) => b.number - a.number).slice(0, limit).map((p) => pick(prShape(p), fields))),
|
|
169
|
+
prEdit: (num, { title, body }) => {
|
|
170
|
+
const p = prs.get(Number(num));
|
|
171
|
+
if (offline) return result(false);
|
|
172
|
+
if (!p) return fail(`pull request #${num} not found`);
|
|
173
|
+
Object.assign(p, { title, body });
|
|
174
|
+
return result(true);
|
|
175
|
+
},
|
|
176
|
+
|
|
177
|
+
runList: ({ branch, commit, limit, fields }) => withList(runs
|
|
178
|
+
.filter((r) => r.headBranch === branch && (!commit || r.headSha === commit))
|
|
179
|
+
.sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
|
|
180
|
+
.slice(0, limit).map((r) => pick(r, fields))),
|
|
181
|
+
|
|
182
|
+
releaseView: (tag) => {
|
|
183
|
+
if (offline) return result(false);
|
|
184
|
+
return releases.has(tag) ? result(true, { stdout: JSON.stringify({ tagName: tag }) }) : fail('release not found');
|
|
185
|
+
},
|
|
186
|
+
releaseCreate: (tag, { final = false } = {}) => {
|
|
187
|
+
if (offline) return result(false);
|
|
188
|
+
if (releases.has(tag)) return fail(`a release with tag ${tag} already exists`);
|
|
189
|
+
releases.set(tag, { tag, prerelease: !final });
|
|
190
|
+
return result(true, { stdout: `${base}/releases/tag/${tag}` });
|
|
191
|
+
},
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
module.exports = { create };
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$comment": "Tracker contract scenarios (#501) — the language-neutral spec of what an implementation of the tracker contract (tools/lib/tracker.js METHODS) must do. Each scenario: seed a tracker from `given`, run `steps` in order against that ONE tracker (state carries from step to step), and compare each step's return value to `expect`. This repo runs every scenario against its in-memory fake (tools/lib/tracker-fake.js) and against its GitHub adapter (tools/lib/tracker-github.js, gh replies replayed from recorded transcripts) — tools/lib/tracker-contract.test.js. A consumer with its own adapter, in any language, runs the same file with its own runner; see `match` for the comparison rules and `given` for the seed shape.",
|
|
3
|
+
"version": 1,
|
|
4
|
+
"match": {
|
|
5
|
+
"$comment": "How `expect` is compared with a step's actual return value. Partial by design: an implementation may return MORE than a scenario pins, never less or different.",
|
|
6
|
+
"null": "`expect: null` requires the value to be exactly null.",
|
|
7
|
+
"scalar": "a string, number or boolean must be strictly equal.",
|
|
8
|
+
"object": "every key in `expect` must be present in the actual object and match recursively; extra actual keys are ignored.",
|
|
9
|
+
"array": "the actual array must have the same length, and element i must match expect[i] recursively (order matters).",
|
|
10
|
+
"$re": "an object {\"$re\": \"<pattern>\"} matches a string the regular expression (ECMAScript syntax, unanchored) finds a match in.",
|
|
11
|
+
"$type": "an object {\"$type\": \"string\" | \"number\" | \"boolean\" | \"array\" | \"object\"} matches any value of that type (array is not object)."
|
|
12
|
+
},
|
|
13
|
+
"given": {
|
|
14
|
+
"$comment": "The seed. Every key is optional. Logins and label names are plain strings here; how an implementation stores them is its own business.",
|
|
15
|
+
"login": "the account the tracker is authenticated as (what currentLogin returns, and the author of anything this tracker writes).",
|
|
16
|
+
"offline": "true = the tracker cannot be reached: reads return their `could not read` value (null, or `data: null`), writes return ok:false. Never a throw.",
|
|
17
|
+
"labels": "the label names defined on the repo, in the order labelList returns them.",
|
|
18
|
+
"issues": "[{number, title, body, state: OPEN|CLOSED, stateReason, labels: [name], assignees: [login], comments: [{author, body}], events: [{event: \"labeled\", label, actor}]}] — `events` is the label timeline claimHolder reads; the claimer is the actor of the LATEST labeled in-progress event.",
|
|
19
|
+
"prs": "[{number, head, base, title, body, state: OPEN|CLOSED|MERGED, author}] — issues and pull requests share ONE number sequence, as on GitHub.",
|
|
20
|
+
"runs": "[{headBranch, headSha, status, conclusion, event, workflowName, createdAt}] — CI runs; runList returns them newest first by createdAt.",
|
|
21
|
+
"releases": "[{tag, prerelease}]"
|
|
22
|
+
},
|
|
23
|
+
"scenarios": [
|
|
24
|
+
{
|
|
25
|
+
"id": "identity",
|
|
26
|
+
"description": "An available tracker reports itself available and names the account it acts as.",
|
|
27
|
+
"given": { "login": "alice" },
|
|
28
|
+
"steps": [
|
|
29
|
+
{ "call": "state", "args": [], "expect": { "ok": true, "reason": null } },
|
|
30
|
+
{ "call": "currentLogin", "args": [], "expect": "alice" }
|
|
31
|
+
]
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"id": "issue-view",
|
|
35
|
+
"description": "issueView returns the requested fields of an issue, labels and assignees as objects; an issue that does not exist reads as null, never as an empty object.",
|
|
36
|
+
"given": {
|
|
37
|
+
"login": "alice",
|
|
38
|
+
"issues": [{ "number": 7, "title": "fix: the importer drops rows", "body": "Repro attached.", "state": "OPEN", "labels": ["bug", "in-progress"], "assignees": ["bob"] }]
|
|
39
|
+
},
|
|
40
|
+
"steps": [
|
|
41
|
+
{ "call": "issueView", "args": [7, ["number", "title", "state", "labels", "assignees"]],
|
|
42
|
+
"expect": { "number": 7, "title": "fix: the importer drops rows", "state": "OPEN", "labels": [{ "name": "bug" }, { "name": "in-progress" }], "assignees": [{ "login": "bob" }] } },
|
|
43
|
+
{ "call": "issueView", "args": [99, ["number"]], "expect": null }
|
|
44
|
+
]
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
"id": "issue-create",
|
|
48
|
+
"description": "issueCreate takes the next number in the sequence issues and pull requests share, returns it with the issue's URL, and the new issue is open with nothing on it.",
|
|
49
|
+
"given": {
|
|
50
|
+
"login": "alice",
|
|
51
|
+
"issues": [{ "number": 7, "title": "an older issue", "state": "OPEN" }],
|
|
52
|
+
"prs": [{ "number": 8, "head": "fix/older-7", "base": "main", "title": "fix: older", "state": "MERGED", "author": "bob" }]
|
|
53
|
+
},
|
|
54
|
+
"steps": [
|
|
55
|
+
{ "call": "issueCreate", "args": [{ "title": "feat: export as CSV", "body": "## Goal\nExport." }],
|
|
56
|
+
"expect": { "ok": true, "number": 9, "url": { "$re": "/issues/9$" } } },
|
|
57
|
+
{ "call": "issueView", "args": [9, ["title", "body", "state", "labels", "assignees", "comments"]],
|
|
58
|
+
"expect": { "title": "feat: export as CSV", "body": "## Goal\nExport.", "state": "OPEN", "labels": [], "assignees": [], "comments": [] } }
|
|
59
|
+
]
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
"id": "issue-comment",
|
|
63
|
+
"description": "A comment lands on the issue, authored by the tracker's account; commenting on an issue that does not exist fails as data.",
|
|
64
|
+
"given": { "login": "alice", "issues": [{ "number": 3, "title": "t", "state": "OPEN" }] },
|
|
65
|
+
"steps": [
|
|
66
|
+
{ "call": "issueComment", "args": [3, "Progress: the parser is done."], "expect": { "ok": true } },
|
|
67
|
+
{ "call": "issueView", "args": [3, ["comments"]],
|
|
68
|
+
"expect": { "comments": [{ "author": { "login": "alice" }, "body": "Progress: the parser is done." }] } },
|
|
69
|
+
{ "call": "issueComment", "args": [404, "nobody home"], "expect": { "ok": false } }
|
|
70
|
+
]
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"id": "issue-close-reasons",
|
|
74
|
+
"description": "Closing with no reason records COMPLETED; closing with reason `not planned` records NOT_PLANNED.",
|
|
75
|
+
"given": { "login": "alice", "issues": [{ "number": 4, "title": "done", "state": "OPEN" }, { "number": 5, "title": "dropped", "state": "OPEN" }] },
|
|
76
|
+
"steps": [
|
|
77
|
+
{ "call": "issueClose", "args": [4], "expect": { "ok": true } },
|
|
78
|
+
{ "call": "issueClose", "args": [5, { "reason": "not planned" }], "expect": { "ok": true } },
|
|
79
|
+
{ "call": "issueView", "args": [4, ["state", "stateReason"]], "expect": { "state": "CLOSED", "stateReason": "COMPLETED" } },
|
|
80
|
+
{ "call": "issueView", "args": [5, ["state", "stateReason"]], "expect": { "state": "CLOSED", "stateReason": "NOT_PLANNED" } }
|
|
81
|
+
]
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
"id": "claim-holder",
|
|
85
|
+
"description": "The claimer is the actor of the LATEST labeled-in-progress event, not the first; no event means no claimer; an issue that cannot be read gives null for both, never `nobody`.",
|
|
86
|
+
"given": {
|
|
87
|
+
"login": "alice",
|
|
88
|
+
"issues": [
|
|
89
|
+
{ "number": 11, "title": "re-claimed", "state": "OPEN", "labels": ["in-progress"], "assignees": ["bob"],
|
|
90
|
+
"events": [{ "event": "labeled", "label": "in-progress", "actor": "carol" }, { "event": "labeled", "label": "in-progress", "actor": "bob" }] },
|
|
91
|
+
{ "number": 12, "title": "never claimed", "state": "OPEN" }
|
|
92
|
+
]
|
|
93
|
+
},
|
|
94
|
+
"steps": [
|
|
95
|
+
{ "call": "claimHolder", "args": [11], "expect": { "assignees": ["bob"], "claimer": "bob" } },
|
|
96
|
+
{ "call": "claimHolder", "args": [12], "expect": { "assignees": [], "claimer": null } },
|
|
97
|
+
{ "call": "claimHolder", "args": [404], "expect": { "assignees": null, "claimer": null } }
|
|
98
|
+
]
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
"id": "release-another-accounts-claim",
|
|
102
|
+
"description": "A claim taken under one account and released under another drops BOTH halves: the in-progress label and the claimer's assignee, and says whose assignee it removed.",
|
|
103
|
+
"given": {
|
|
104
|
+
"login": "alice",
|
|
105
|
+
"issues": [{ "number": 20, "title": "claimed by bob", "state": "OPEN", "labels": ["in-progress", "bug"], "assignees": ["bob"],
|
|
106
|
+
"events": [{ "event": "labeled", "label": "in-progress", "actor": "bob" }] }]
|
|
107
|
+
},
|
|
108
|
+
"steps": [
|
|
109
|
+
{ "call": "issueRelease", "args": [20], "expect": { "ok": true, "caller": "alice", "others": ["bob"], "note": "" } },
|
|
110
|
+
{ "call": "issueView", "args": [20, ["labels", "assignees"]], "expect": { "labels": [{ "name": "bug" }], "assignees": [] } }
|
|
111
|
+
]
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
"id": "release-self-only",
|
|
115
|
+
"description": "selfOnly releases only the caller's half: the label goes, the latest labeler keeps its assignee (the yield path, where that labeler may be the winner of a race).",
|
|
116
|
+
"given": {
|
|
117
|
+
"login": "alice",
|
|
118
|
+
"issues": [{ "number": 21, "title": "raced", "state": "OPEN", "labels": ["in-progress"], "assignees": ["alice", "bob"],
|
|
119
|
+
"events": [{ "event": "labeled", "label": "in-progress", "actor": "bob" }] }]
|
|
120
|
+
},
|
|
121
|
+
"steps": [
|
|
122
|
+
{ "call": "issueRelease", "args": [21, { "selfOnly": true }], "expect": { "ok": true, "caller": "alice", "others": [] } },
|
|
123
|
+
{ "call": "issueView", "args": [21, ["labels", "assignees"]], "expect": { "labels": [], "assignees": [{ "login": "bob" }] } }
|
|
124
|
+
]
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
"id": "labels-and-issue-list",
|
|
128
|
+
"description": "labelList returns the repo's label names; issueListAll returns every issue, open and closed, newest first, with the requested fields.",
|
|
129
|
+
"given": {
|
|
130
|
+
"login": "alice",
|
|
131
|
+
"labels": ["bug", "in-progress", "needs-plan"],
|
|
132
|
+
"issues": [{ "number": 1, "title": "open one", "state": "OPEN", "labels": ["bug"] }, { "number": 2, "title": "closed one", "state": "CLOSED", "stateReason": "COMPLETED" }]
|
|
133
|
+
},
|
|
134
|
+
"steps": [
|
|
135
|
+
{ "call": "labelList", "args": [], "expect": ["bug", "in-progress", "needs-plan"] },
|
|
136
|
+
{ "call": "issueListAll", "args": [{ "limit": 100, "fields": ["number", "state", "labels"] }],
|
|
137
|
+
"expect": { "ok": true, "data": [{ "number": 2, "state": "CLOSED", "labels": [] }, { "number": 1, "state": "OPEN", "labels": [{ "name": "bug" }] }] } }
|
|
138
|
+
]
|
|
139
|
+
},
|
|
140
|
+
{
|
|
141
|
+
"id": "pull-request-lifecycle",
|
|
142
|
+
"description": "No open PR for a branch reads as {pr: null}; a created PR takes the shared next number, is found by its branch, can be retitled, and once closed is no longer the branch's open PR while prList with state all still lists it.",
|
|
143
|
+
"given": { "login": "alice", "issues": [{ "number": 30, "title": "feat: x", "state": "OPEN" }] },
|
|
144
|
+
"steps": [
|
|
145
|
+
{ "call": "prForBranch", "args": ["feat/x-30"], "expect": { "pr": null } },
|
|
146
|
+
{ "call": "prCreate", "args": [{ "base": "main", "head": "feat/x-30", "title": "feat: x", "body": "Closes #30" }],
|
|
147
|
+
"expect": { "ok": true, "url": { "$re": "/pull/31$" } } },
|
|
148
|
+
{ "call": "prForBranch", "args": ["feat/x-30"],
|
|
149
|
+
"expect": { "pr": { "number": 31, "state": "OPEN", "author": { "login": "alice" }, "reviews": [] } } },
|
|
150
|
+
{ "call": "prEdit", "args": [31, { "title": "feat: x, retitled", "body": "Closes #30" }], "expect": { "ok": true } },
|
|
151
|
+
{ "call": "prList", "args": [{ "base": "main", "head": "feat/x-30", "state": "all", "limit": 50, "fields": ["number", "state", "title"] }],
|
|
152
|
+
"expect": { "ok": true, "data": [{ "number": 31, "state": "OPEN", "title": "feat: x, retitled" }] } },
|
|
153
|
+
{ "call": "prClose", "args": [31, "Landed by squash on main."], "expect": { "ok": true } },
|
|
154
|
+
{ "call": "prForBranch", "args": ["feat/x-30"], "expect": { "pr": null } },
|
|
155
|
+
{ "call": "prList", "args": [{ "base": "main", "head": "feat/x-30", "state": "all", "limit": 50, "fields": ["number", "state"] }],
|
|
156
|
+
"expect": { "ok": true, "data": [{ "number": 31, "state": "CLOSED" }] } }
|
|
157
|
+
]
|
|
158
|
+
},
|
|
159
|
+
{
|
|
160
|
+
"id": "ci-runs",
|
|
161
|
+
"description": "runList returns one branch's runs newest first, honours the limit, and narrows to one commit when asked.",
|
|
162
|
+
"given": {
|
|
163
|
+
"login": "alice",
|
|
164
|
+
"runs": [
|
|
165
|
+
{ "headBranch": "main", "headSha": "aaa1111", "status": "completed", "conclusion": "success", "event": "push", "workflowName": "CI", "createdAt": "2026-10-01T10:00:00Z" },
|
|
166
|
+
{ "headBranch": "main", "headSha": "bbb2222", "status": "in_progress", "conclusion": "", "event": "push", "workflowName": "CI", "createdAt": "2026-10-01T11:00:00Z" },
|
|
167
|
+
{ "headBranch": "feat/y-40", "headSha": "ccc3333", "status": "completed", "conclusion": "failure", "event": "push", "workflowName": "CI", "createdAt": "2026-10-01T12:00:00Z" }
|
|
168
|
+
]
|
|
169
|
+
},
|
|
170
|
+
"steps": [
|
|
171
|
+
{ "call": "runList", "args": [{ "branch": "main", "limit": 10, "fields": ["headSha", "status", "conclusion"] }],
|
|
172
|
+
"expect": { "ok": true, "data": [{ "headSha": "bbb2222", "status": "in_progress", "conclusion": "" }, { "headSha": "aaa1111", "status": "completed", "conclusion": "success" }] } },
|
|
173
|
+
{ "call": "runList", "args": [{ "branch": "main", "limit": 1, "fields": ["headSha"] }],
|
|
174
|
+
"expect": { "ok": true, "data": [{ "headSha": "bbb2222" }] } },
|
|
175
|
+
{ "call": "runList", "args": [{ "branch": "main", "commit": "aaa1111", "limit": 10, "fields": ["headSha", "conclusion"] }],
|
|
176
|
+
"expect": { "ok": true, "data": [{ "headSha": "aaa1111", "conclusion": "success" }] } }
|
|
177
|
+
]
|
|
178
|
+
},
|
|
179
|
+
{
|
|
180
|
+
"id": "releases",
|
|
181
|
+
"description": "A release that does not exist reads as a failed view; once created it reads back; creating the same tag twice fails as data.",
|
|
182
|
+
"given": { "login": "alice", "releases": [{ "tag": "v1.0.0", "prerelease": false }] },
|
|
183
|
+
"steps": [
|
|
184
|
+
{ "call": "releaseView", "args": ["v1.1.0-rc.1"], "expect": { "ok": false } },
|
|
185
|
+
{ "call": "releaseCreate", "args": ["v1.1.0-rc.1", { "notesFile": "notes.md" }], "expect": { "ok": true } },
|
|
186
|
+
{ "call": "releaseView", "args": ["v1.1.0-rc.1"], "expect": { "ok": true } },
|
|
187
|
+
{ "call": "releaseView", "args": ["v1.0.0"], "expect": { "ok": true } },
|
|
188
|
+
{ "call": "releaseCreate", "args": ["v1.1.0-rc.1", { "notesFile": "notes.md" }], "expect": { "ok": false } }
|
|
189
|
+
]
|
|
190
|
+
},
|
|
191
|
+
{
|
|
192
|
+
"id": "offline",
|
|
193
|
+
"description": "An unreachable tracker never throws: every read is `could not read` (null, data: null, or an error), every write is ok:false — and none of them is mistaken for `none`.",
|
|
194
|
+
"given": { "login": "alice", "offline": true, "issues": [{ "number": 1, "title": "exists, unreachable", "state": "OPEN", "labels": ["bug"] }] },
|
|
195
|
+
"steps": [
|
|
196
|
+
{ "call": "issueView", "args": [1, ["number"]], "expect": null },
|
|
197
|
+
{ "call": "issueListAll", "args": [{ "limit": 10, "fields": ["number"] }], "expect": { "ok": false, "data": null } },
|
|
198
|
+
{ "call": "labelList", "args": [], "expect": null },
|
|
199
|
+
{ "call": "claimHolder", "args": [1], "expect": { "assignees": null, "claimer": null } },
|
|
200
|
+
{ "call": "issueComment", "args": [1, "lost"], "expect": { "ok": false } },
|
|
201
|
+
{ "call": "runList", "args": [{ "branch": "main", "limit": 5, "fields": ["headSha"] }], "expect": { "ok": false, "data": null } },
|
|
202
|
+
{ "call": "prForBranch", "args": ["feat/x-1"], "expect": { "error": { "$type": "string" } } }
|
|
203
|
+
]
|
|
204
|
+
}
|
|
205
|
+
]
|
|
206
|
+
}
|
package/tools/lib/tracker.js
CHANGED
|
@@ -4,8 +4,10 @@
|
|
|
4
4
|
* once, so an implementation other than GitHub (and #501's in-memory fake) has a method set to
|
|
5
5
|
* satisfy instead of a scatter of `gh` argv to imitate.
|
|
6
6
|
*
|
|
7
|
-
* The only implementation today is tools/lib/tracker-github.js.
|
|
8
|
-
*
|
|
7
|
+
* The only real implementation today is tools/lib/tracker-github.js; tools/lib/tracker-fake.js is an
|
|
8
|
+
* in-memory one (#501). What every implementation must do is specified as data, in
|
|
9
|
+
* tools/lib/tracker-scenarios.json, and tools/lib/tracker-contract.test.js runs those scenarios
|
|
10
|
+
* against both. Semantics every implementation keeps:
|
|
9
11
|
* - synchronous — the CLI is spawnSync throughout;
|
|
10
12
|
* - bound to one repo — `forRepo(repoAbs)` fixes it, so no method takes a repo argument;
|
|
11
13
|
* - never throws on an environment failure (no tracker binary, no remote, offline): results are
|
|
@@ -13,7 +15,8 @@
|
|
|
13
15
|
* "could not read" and never "none"; the read helpers keep their existing null-on-failure
|
|
14
16
|
* contract.
|
|
15
17
|
*
|
|
16
|
-
* Deliberately NOT in the contract yet (
|
|
18
|
+
* Deliberately NOT in the contract yet (#501 left it so: no scenario needs them, and each would
|
|
19
|
+
* pin a GitHub-only shape into a spec other trackers must satisfy): the CI-run
|
|
17
20
|
* summarisers and REST probes, label create/delete/edit, raw `issue edit` flags and raw `api`
|
|
18
21
|
* access. They still reach `gh` only through the adapter's `exec`.
|
|
19
22
|
*/
|
|
@@ -46,7 +49,7 @@ function assertImplements(impl, label = 'tracker') {
|
|
|
46
49
|
return impl;
|
|
47
50
|
}
|
|
48
51
|
|
|
49
|
-
const KINDS = { github: () => require('./tracker-github') };
|
|
52
|
+
const KINDS = { github: () => require('./tracker-github'), fake: () => require('./tracker-fake') };
|
|
50
53
|
const _checked = new Set();
|
|
51
54
|
|
|
52
55
|
/** The tracker for one repo. `kind` defaults to the one implementation, `github`. */
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
/**
|
|
3
|
+
* Which workflow runs at a sha VERIFY the code there (#503) — the pure half of the rule `colab
|
|
4
|
+
* ship`'s CI gate, `colab trunk-ci` and `colab ci-wait` read. No gh, no git, no I/O.
|
|
5
|
+
*
|
|
6
|
+
* THE RULE. A run counts toward "is this sha green" when its trigger is a push or a pull request
|
|
7
|
+
* (`push`, `pull_request`, `pull_request_target`, `merge_group`) — the triggers that run a suite
|
|
8
|
+
* against the code. A run of any OTHER trigger is set aside and named: `workflow_run` (the
|
|
9
|
+
* handbook's own `release-auto.yml` fires on CI's completion, cuts a candidate, publishes, deploys
|
|
10
|
+
* to staging — 20–30 min after the verifying run already finished), `schedule` (the same template's
|
|
11
|
+
* daily finalize lands on trunk's head too), `workflow_dispatch`, `release`, `deployment`, … Those
|
|
12
|
+
* runs come AFTER the verdict and act on it; their failure belongs to the release lane, so they
|
|
13
|
+
* must neither turn trunk red for ship nor make ship wait for them.
|
|
14
|
+
*
|
|
15
|
+
* Measured (one adopted fork, 2026-10-05): CI green at 15:18Z, `Release (auto)` then in progress at
|
|
16
|
+
* the same trunk sha, and four green, graded candidates parked behind it — every landing cost one
|
|
17
|
+
* CI cycle plus one release cycle.
|
|
18
|
+
*
|
|
19
|
+
* A row with no `event` field (an older read, a hand-built fixture) is counted: absence of the field
|
|
20
|
+
* never excludes anything, so every verdict computable before #503 without it is computed the same.
|
|
21
|
+
*
|
|
22
|
+
* OVERRIDES (project.yml), matched against the run's workflow `name:` — the only workflow identity
|
|
23
|
+
* every run read carries (`gh run list` has no file path):
|
|
24
|
+
* ship-gate-workflows: [CI, Lint] the explicit set: exactly these workflows count, whatever
|
|
25
|
+
* their trigger; every other workflow is set aside.
|
|
26
|
+
* ship-ignore-workflows: [Deploy] set these aside too, even when push-triggered (a deploy
|
|
27
|
+
* workflow that fires on a push to trunk). Wins over the gate
|
|
28
|
+
* list for a name in both.
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
const VERIFYING_EVENTS = Object.freeze(['push', 'pull_request', 'pull_request_target', 'merge_group']);
|
|
32
|
+
const GATE_KEY = 'ship-gate-workflows';
|
|
33
|
+
const IGNORE_KEY = 'ship-ignore-workflows';
|
|
34
|
+
|
|
35
|
+
/** One list key: absent → null; a non-empty list of non-empty strings → the names; else invalid. */
|
|
36
|
+
function parseNameList(doc, key) {
|
|
37
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, key);
|
|
38
|
+
if (!has || doc[key] === null || doc[key] === undefined) return { declared: false, valid: true, names: null };
|
|
39
|
+
let v = doc[key];
|
|
40
|
+
if (typeof v === 'string') v = [v];
|
|
41
|
+
if (!Array.isArray(v) || v.length === 0) {
|
|
42
|
+
return { declared: true, valid: false, names: null, reason: `${key} must be a non-empty list of workflow names (the workflow's \`name:\`), got ${JSON.stringify(doc[key])}` };
|
|
43
|
+
}
|
|
44
|
+
const bad = v.filter((x) => typeof x !== 'string' || !x.trim());
|
|
45
|
+
if (bad.length) {
|
|
46
|
+
return { declared: true, valid: false, names: null, reason: `${key} has ${bad.length} entr${bad.length === 1 ? 'y' : 'ies'} that ${bad.length === 1 ? 'is' : 'are'} not a workflow name: ${JSON.stringify(bad)}` };
|
|
47
|
+
}
|
|
48
|
+
return { declared: true, valid: true, names: v.map((x) => x.trim()) };
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* The policy from a parsed project.yml doc: `{ gate: string[]|null, ignore: string[], valid,
|
|
53
|
+
* problems: string[] }`. An invalid key is IGNORED by the reader (the default rule applies) and
|
|
54
|
+
* reported by the audit — a malformed override must not silently widen what ship counts as green
|
|
55
|
+
* in either direction, and the default is the measured-safe reading.
|
|
56
|
+
*/
|
|
57
|
+
function parsePolicy(doc) {
|
|
58
|
+
const g = parseNameList(doc, GATE_KEY);
|
|
59
|
+
const i = parseNameList(doc, IGNORE_KEY);
|
|
60
|
+
const problems = [g, i].filter((x) => !x.valid).map((x) => x.reason);
|
|
61
|
+
return {
|
|
62
|
+
gate: g.valid ? g.names : null,
|
|
63
|
+
ignore: i.valid && i.names ? i.names : [],
|
|
64
|
+
valid: problems.length === 0,
|
|
65
|
+
problems,
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Why one row is set aside, or null when it counts. */
|
|
70
|
+
function setAsideReason(row, policy) {
|
|
71
|
+
const p = policy || { gate: null, ignore: [] };
|
|
72
|
+
const name = row && row.workflowName;
|
|
73
|
+
if (name && p.ignore && p.ignore.includes(name)) return `${IGNORE_KEY}`;
|
|
74
|
+
if (p.gate) return name && p.gate.includes(name) ? null : `not in ${GATE_KEY}`;
|
|
75
|
+
const ev = row && row.event;
|
|
76
|
+
if (ev === undefined || ev === null || ev === '') return null;
|
|
77
|
+
return VERIFYING_EVENTS.includes(ev) ? null : `event: ${ev}`;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Split rows into `{ counted, setAside }`; each set-aside row carries `setAsideWhy`. Null in → null out. */
|
|
81
|
+
function splitVerifying(rows, policy) {
|
|
82
|
+
if (!Array.isArray(rows)) return null;
|
|
83
|
+
const counted = [];
|
|
84
|
+
const setAside = [];
|
|
85
|
+
for (const r of rows) {
|
|
86
|
+
const why = setAsideReason(r, policy);
|
|
87
|
+
if (why) setAside.push({ ...r, setAsideWhy: why });
|
|
88
|
+
else counted.push(r);
|
|
89
|
+
}
|
|
90
|
+
return { counted, setAside };
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The verdict-detail suffix naming what was set aside — '' when nothing was. `rows` is the compact
|
|
95
|
+
* summary shape (`{workflowName, status, conclusion, databaseId, why}`).
|
|
96
|
+
*/
|
|
97
|
+
function setAsideNote(rows) {
|
|
98
|
+
const list = Array.isArray(rows) ? rows : [];
|
|
99
|
+
if (!list.length) return '';
|
|
100
|
+
const names = list.map((x) => `${x.workflowName || 'unnamed'} (${x.conclusion || x.status || '?'}${x.databaseId ? `, run ${x.databaseId}` : ''}${x.why ? `; ${x.why}` : ''})`);
|
|
101
|
+
return ` — set aside ${list.length} run${list.length === 1 ? '' : 's'} that do${list.length === 1 ? 'es' : ''} not verify the code (post-CI release/deploy lane, #503): ${names.join(', ')}`;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
module.exports = { VERIFYING_EVENTS, GATE_KEY, IGNORE_KEY, parsePolicy, setAsideReason, splitVerifying, setAsideNote };
|