@futurelastic/colab-handbook 1.12.0-rc.61 → 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/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.61"
35
+ "version": "1.12.0-rc.62"
35
36
  }
@@ -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
+ }
@@ -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. Semantics every implementation
8
- * keeps:
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 (a question for #501, not this module): the CI-run
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`. */