@futurelastic/colab-handbook 1.12.0 → 1.13.0-rc.10

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.
Files changed (74) hide show
  1. package/README.md +248 -213
  2. package/README.vi.md +252 -186
  3. package/audit/audit.mjs +193 -10
  4. package/package.json +7 -1
  5. package/templates/README.md +30 -2
  6. package/templates/ci-laravel.yml +102 -21
  7. package/templates/ci-node.yml +61 -3
  8. package/templates/ci-python.yml +52 -3
  9. package/templates/deploy-adapter-portainer.mjs +206 -0
  10. package/templates/deploy-container-run.mjs +368 -0
  11. package/templates/deploy-container.yml +219 -0
  12. package/templates/dist-refs.yml +6 -0
  13. package/templates/docs-lint.mjs +1 -1
  14. package/templates/npx-launcher.mjs +118 -20
  15. package/templates/npx-service.mjs +828 -0
  16. package/templates/release-auto.yml +341 -32
  17. package/tools/colab +1902 -278
  18. package/tools/lib/adopt.js +373 -14
  19. package/tools/lib/branch-name.js +29 -1
  20. package/tools/lib/ci-cure.js +522 -31
  21. package/tools/lib/ci-grant.js +289 -22
  22. package/tools/lib/ci-wait.js +223 -0
  23. package/tools/lib/claim-comments.js +13 -64
  24. package/tools/lib/claim-identity.js +42 -7
  25. package/tools/lib/codec/claim.d.ts +41 -0
  26. package/tools/lib/codec/claim.js +153 -0
  27. package/tools/lib/codec/decision.d.ts +29 -0
  28. package/tools/lib/codec/decision.js +81 -0
  29. package/tools/lib/codec/grants.d.ts +82 -0
  30. package/tools/lib/codec/grants.js +268 -0
  31. package/tools/lib/codec/hold.d.ts +26 -0
  32. package/tools/lib/codec/hold.js +152 -0
  33. package/tools/lib/codec/index.d.ts +21 -0
  34. package/tools/lib/codec/index.js +32 -0
  35. package/tools/lib/codec/labels.d.ts +65 -0
  36. package/tools/lib/codec/labels.js +723 -0
  37. package/tools/lib/codec/markers.d.ts +35 -0
  38. package/tools/lib/codec/markers.js +138 -0
  39. package/tools/lib/codec/release.d.ts +17 -0
  40. package/tools/lib/codec/release.js +69 -0
  41. package/tools/lib/codec/samples.json +778 -0
  42. package/tools/lib/codeowners.js +68 -4
  43. package/tools/lib/container-close.js +38 -0
  44. package/tools/lib/cure-diff.js +198 -9
  45. package/tools/lib/decision-record.js +15 -39
  46. package/tools/lib/docs-only.js +15 -1
  47. package/tools/lib/exposure-shape.js +42 -8
  48. package/tools/lib/git.js +324 -42
  49. package/tools/lib/group-labels.js +65 -0
  50. package/tools/lib/install-check.js +14 -8
  51. package/tools/lib/install-route.js +139 -0
  52. package/tools/lib/instruction-file.js +1 -0
  53. package/tools/lib/labels.js +22 -647
  54. package/tools/lib/local-adopt.js +8 -4
  55. package/tools/lib/migration-grant.js +206 -104
  56. package/tools/lib/place.js +2 -2
  57. package/tools/lib/release-cut.js +199 -25
  58. package/tools/lib/release-finalize.js +111 -23
  59. package/tools/lib/release-policy.js +130 -22
  60. package/tools/lib/release-runner.js +125 -0
  61. package/tools/lib/release-tag.js +3 -1
  62. package/tools/lib/scratch-dirs.js +118 -0
  63. package/tools/lib/ship-batch.js +36 -1
  64. package/tools/lib/ship-human-door.js +76 -0
  65. package/tools/lib/stamp.js +7 -0
  66. package/tools/lib/tracker-fake.js +195 -0
  67. package/tools/lib/tracker-github.js +106 -0
  68. package/tools/lib/tracker-scenarios.json +206 -0
  69. package/tools/lib/tracker.js +64 -0
  70. package/tools/lib/tree-green.js +88 -0
  71. package/tools/lib/util.js +17 -1
  72. package/tools/lib/verify-runs.js +104 -0
  73. package/tools/lib/wake.js +8 -90
  74. package/tools/lib/workflow-triggers.js +48 -0
@@ -0,0 +1,268 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#498, epic #496): the GRANT comment wire formats as encode/decode pairs — the human
4
+ * migration grant and its revoke, the reviewer migration grant with its fenced record, the
5
+ * red-trunk CI grant and its revoke, and the reviewer red-trunk CI grant with its fenced record
6
+ * (#504). Pure and synchronous: no I/O, no clock, no requires.
7
+ *
8
+ * What stays OUT of here is everything that JUDGES a grant: which grants are live, whose comment is
9
+ * trusted, whether a record passes review, whether a grant still binds a HEAD. That lives in
10
+ * tools/lib/migration-grant.js and tools/lib/ci-grant.js, which re-export the names below under the
11
+ * names they always had.
12
+ *
13
+ * STABLE WIRE FORMAT. `tools/colab` and any vendored reader parse these verbatim, and an older CLI on
14
+ * another machine reads what this one writes. Every mark has a DIFFERENT leading emoji from every
15
+ * other (🛢 🚫 🔎 🚨 🧯 🩹), so no regex here can match another mark's body — a revoke that merely
16
+ * suffixed its grant would parse as a fresh grant and reopen the door it was posted to close.
17
+ *
18
+ * Round-trip rule shared by every pair below: a decoded comment carries `tail`, the text after the
19
+ * timestamp on the marker line. `tail: null` means "exactly the sentence this toolkit writes", so a
20
+ * canonical comment decodes compactly; any other tail is kept literally, so a hand-edited comment
21
+ * still re-encodes byte for byte.
22
+ */
23
+
24
+ // ── human migration grant / revoke ───────────────────────────────────────────────────────────
25
+
26
+ const MIGRATION_GRANT_MARK = '🛢 Migration grant';
27
+ const MIGRATION_REVOKE_MARK = '🚫 Migration grant revoked';
28
+ const MIGRATION_GRANT_RE = /^🛢 Migration grant — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
29
+ const MIGRATION_REVOKE_RE = /^🚫 Migration grant revoked — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
30
+ const MIGRATION_GRANT_TAIL = ' — this exempts THIS BRANCH only, and expires when this issue closes.';
31
+ const REVOKE_TAIL = ' — every grant on this issue up to this point is cancelled.';
32
+
33
+ function str(body) { return String(body == null ? '' : body).trim(); }
34
+ function tailOf(s, m, canonical) { const t = s.slice(m[0].length); return t === canonical ? null : t; }
35
+ function withTail(head, tail, canonical) { return head + (tail == null ? canonical : tail); }
36
+
37
+ /** `{branch, host, at, tail?}` → the grant comment. `host` is the raw name or its `h:` token. */
38
+ function encodeMigrationGrant({ branch, host, at, tail } = {}) {
39
+ return withTail(`${MIGRATION_GRANT_MARK} — branch \`${branch}\` · host \`${host}\` · ${at}`, tail, MIGRATION_GRANT_TAIL);
40
+ }
41
+ /** A grant comment → `{branch, host, at, tail}`, or null when the body is not one. */
42
+ function decodeMigrationGrant(body) {
43
+ const s = str(body);
44
+ const m = s.match(MIGRATION_GRANT_RE);
45
+ return m ? { branch: m[1], host: m[2], at: m[3], tail: tailOf(s, m, MIGRATION_GRANT_TAIL) } : null;
46
+ }
47
+ /** `{branch, host, at, tail?}` → the revoke comment. The branch is for the audit trail only. */
48
+ function encodeMigrationRevoke({ branch, host, at, tail } = {}) {
49
+ return withTail(`${MIGRATION_REVOKE_MARK} — branch \`${branch}\` · host \`${host}\` · ${at}`, tail, REVOKE_TAIL);
50
+ }
51
+ function decodeMigrationRevoke(body) {
52
+ const s = str(body);
53
+ const m = s.match(MIGRATION_REVOKE_RE);
54
+ return m ? { branch: m[1], host: m[2], at: m[3], tail: tailOf(s, m, REVOKE_TAIL) } : null;
55
+ }
56
+
57
+ // ── reviewer migration grant (#457 era): a marker line plus a fenced `migration-review` record ──
58
+
59
+ const REVIEW_GRANT_MARK = '🔎 Migration review grant';
60
+ const REVIEWER_ROLE = 'migration-reviewer';
61
+ const REVIEW_GRANT_RE = /^🔎 Migration review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · host `([^`]*)` · (\S+)/;
62
+ const REVIEW_GRANT_TAIL = ' — bound to this HEAD: any new commit voids it; expires when this issue closes.';
63
+ /** #508 — the canonical tail of a grant whose record carries `migrations` (a content id): it binds
64
+ * what was reviewed, so a commit that leaves the migration files byte-identical keeps it. */
65
+ const REVIEW_GRANT_CONTENT_TAIL = ' — bound to the reviewed migration content: a change to any migration file voids it; expires when this issue closes.';
66
+ /** The tail a record of this shape gets by default — content-bound when it names a content id. */
67
+ function reviewGrantTail(record) {
68
+ return record && record.migrations !== undefined && record.migrations !== null && String(record.migrations) !== ''
69
+ ? REVIEW_GRANT_CONTENT_TAIL : REVIEW_GRANT_TAIL;
70
+ }
71
+ /** The fenced block's info string — the record is found by it, never by position. */
72
+ const REVIEW_RECORD_FENCE = 'migration-review';
73
+ const REVIEW_RECORD_VERSION = '1';
74
+
75
+ const SHA40_RE = /^[0-9a-f]{40}$/;
76
+ const REVIEWER_ID_RE = /^[A-Za-z0-9._@-]+$/;
77
+ const CONDITION_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
78
+ const SHA256_RE = /^[0-9a-f]{64}$/;
79
+
80
+ /** Every key a v1 record may carry, and what each accepts. `required: false` keys may be absent.
81
+ * Order here is the order `encodeReviewGrant` writes them in — part of the wire format. */
82
+ const REVIEW_RECORD_FIELDS = Object.freeze([
83
+ { key: 'v', required: true, values: [REVIEW_RECORD_VERSION] },
84
+ { key: 'role', required: true, values: [REVIEWER_ROLE] },
85
+ { key: 'reviewer', required: true, re: REVIEWER_ID_RE, hint: 'letters, digits, . _ @ -' },
86
+ { key: 'head', required: true, re: SHA40_RE, hint: 'a full 40-hex commit sha' },
87
+ { key: 'verdict', required: true, values: ['approve', 'reject'] },
88
+ { key: 'checklist', required: true, values: ['pass', 'fail'] },
89
+ { key: 'checklist-items', required: false, re: /^\d+\/\d+$/, hint: 'N/M, e.g. 7/7' },
90
+ { key: 'escalation', required: true, re: CONDITION_ID_RE, hint: 'a condition id, lowercase-hyphenated' },
91
+ { key: 'escalation-result', required: true, values: ['clear', 'escalated'] },
92
+ { key: 'ci-roundtrip', required: true, values: ['pass', 'fail', 'pending'] },
93
+ { key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
94
+ // #508 — the content id of the migration files the review covered (migration-grant.js
95
+ // migrationContentId). Optional: a record without it is bound to `head` alone, as before.
96
+ { key: 'migrations', required: false, re: SHA256_RE, hint: 'a 64-hex sha256 content id of the reviewed migration files' },
97
+ ]);
98
+
99
+ /**
100
+ * `{role, reviewer, branch, head, host, at, tail?, record}` → marker line, blank line, fenced
101
+ * record. Record keys are written in REVIEW_RECORD_FIELDS order, then any other key in the object's
102
+ * own order; an empty/absent value is omitted. Validating the record is the caller's job
103
+ * (migration-grant.js `validateReviewRecord`) — the codec writes what it is given.
104
+ */
105
+ function encodeReviewGrant({ role, reviewer, branch, head, host, at, tail, record } = {}) {
106
+ const marker = withTail(`${REVIEW_GRANT_MARK} — role \`${role}\` · reviewer \`${reviewer}\` · branch \`${branch}\``
107
+ + ` · head \`${head}\` · host \`${host}\` · ${at}`, tail, reviewGrantTail(record));
108
+ return `${marker}\n\n${fencedRecord(REVIEW_RECORD_FENCE, REVIEW_RECORD_FIELDS, record)}`;
109
+ }
110
+
111
+ /**
112
+ * A reviewer-grant comment → `{role, reviewer, branch, head, host, at, tail, record, problems}`, or
113
+ * null when the first line is not a reviewer-grant marker. The record is the FIRST fenced block whose
114
+ * info string is exactly `migration-review`; text outside it is ignored. `problems` holds SYNTAX
115
+ * findings only (no block, a line that is not `key: value`, a duplicate key) — whether the record's
116
+ * values are acceptable is migration-grant.js's `validateReviewRecord`, never the codec's.
117
+ */
118
+ function decodeReviewGrant(body) {
119
+ const text = String(body == null ? '' : body).replace(/\r\n/g, '\n').trim();
120
+ const m = text.match(REVIEW_GRANT_RE);
121
+ if (!m) return null;
122
+ const nl = text.indexOf('\n');
123
+ const line = nl === -1 ? text : text.slice(0, nl);
124
+ const t = line.slice(m[0].length);
125
+ const out = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], host: m[5], at: m[6],
126
+ tail: t, record: null, problems: [] };
127
+ readFencedRecord(text, REVIEW_RECORD_FENCE, out);
128
+ // The canonical tail depends on the record's shape (#508), so it is judged once the record is read.
129
+ if (t === reviewGrantTail(out.record)) out.tail = null;
130
+ return out;
131
+ }
132
+
133
+ /** Find the FIRST fenced block whose info string is exactly `fence` and read its `key: value`
134
+ * lines into `out.record`; syntax findings go to `out.problems`. Shared by both reviewer grants. */
135
+ function readFencedRecord(text, fence, out) {
136
+ const re = new RegExp('^```' + fence + '[ \\t]*\\n([\\s\\S]*?)^```[ \\t]*$', 'm');
137
+ const fm = text.match(re);
138
+ if (!fm) {
139
+ out.problems.push(`no \`\`\`${fence} block — a reviewer grant without its review record is not a grant`);
140
+ return out;
141
+ }
142
+ const record = {};
143
+ for (const raw of fm[1].split('\n')) {
144
+ const l = raw.trim();
145
+ if (l === '') continue;
146
+ const kv = l.match(/^([a-z][a-z-]*):\s*(.*)$/);
147
+ if (!kv) { out.problems.push(`record line ${JSON.stringify(l)} is not "key: value"`); continue; }
148
+ if (Object.prototype.hasOwnProperty.call(record, kv[1])) { out.problems.push(`"${kv[1]}" appears twice`); continue; }
149
+ record[kv[1]] = kv[2].trim();
150
+ }
151
+ out.record = record;
152
+ return out;
153
+ }
154
+
155
+ /** Record object → its fenced lines: `fields` order first, then any other key in the object's own
156
+ * order; an empty/absent value is omitted. Shared by both reviewer grants. */
157
+ function fencedRecord(fence, fields, rec) {
158
+ const r = rec || {};
159
+ const known = fields.map((f) => f.key);
160
+ const keys = [...known.filter((k) => Object.prototype.hasOwnProperty.call(r, k)),
161
+ ...Object.keys(r).filter((k) => !known.includes(k))];
162
+ const lines = [];
163
+ for (const k of keys) {
164
+ const v = r[k];
165
+ if (v === undefined || v === null || String(v) === '') continue;
166
+ lines.push(`${k}: ${v}`);
167
+ }
168
+ return `\`\`\`${fence}\n${lines.join('\n')}\n\`\`\``;
169
+ }
170
+
171
+ // ── red-trunk CI grant / revoke ───────────────────────────────────────────────────────────────
172
+
173
+ const CI_GRANT_MARK = '🚨 Red-trunk CI grant';
174
+ const CI_REVOKE_MARK = '🧯 Red-trunk CI grant revoked';
175
+ const CI_GRANT_RE = /^🚨 Red-trunk CI grant — branch `([^`]*)` · red `([^`]*)`@`([^`]*)` · evidence `([^`]*)` · host `([^`]*)` · (\S+)/;
176
+ const CI_REVOKE_RE = /^🧯 Red-trunk CI grant revoked — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
177
+
178
+ /** The CI grant's canonical tail names the trunk and the red sha it was reviewed against. */
179
+ function ciGrantTail(trunk, redSha) {
180
+ return ` — this exempts THIS BRANCH from the trunk-CI-green precondition ONLY, only while \`${trunk}\``
181
+ + ` is still at \`${redSha}\`, and expires when this issue closes.`;
182
+ }
183
+
184
+ /** `{branch, trunk, redSha, evidenceSha, host, at, tail?}` → the CI grant comment. */
185
+ function encodeCiGrant({ branch, trunk, redSha, evidenceSha, host, at, tail } = {}) {
186
+ return withTail(`${CI_GRANT_MARK} — branch \`${branch}\` · red \`${trunk}\`@\`${redSha}\` · evidence \`${evidenceSha}\``
187
+ + ` · host \`${host}\` · ${at}`, tail, ciGrantTail(trunk, redSha));
188
+ }
189
+ function decodeCiGrant(body) {
190
+ const s = str(body);
191
+ const m = s.match(CI_GRANT_RE);
192
+ if (!m) return null;
193
+ return { branch: m[1], trunk: m[2], redSha: m[3], evidenceSha: m[4], host: m[5], at: m[6],
194
+ tail: tailOf(s, m, ciGrantTail(m[2], m[3])) };
195
+ }
196
+ function encodeCiRevoke({ branch, host, at, tail } = {}) {
197
+ return withTail(`${CI_REVOKE_MARK} — branch \`${branch}\` · host \`${host}\` · ${at}`, tail, REVOKE_TAIL);
198
+ }
199
+ function decodeCiRevoke(body) {
200
+ const s = str(body);
201
+ const m = s.match(CI_REVOKE_RE);
202
+ return m ? { branch: m[1], host: m[2], at: m[3], tail: tailOf(s, m, REVOKE_TAIL) } : null;
203
+ }
204
+
205
+ // ── reviewer red-trunk CI grant (#504): a marker line plus a fenced `ci-review` record ─────────
206
+ //
207
+ // The coordinator agent's door through a red trunk the cure rule refuses (maintainer ruling
208
+ // 2026-10-05). Same shape as the reviewer migration grant: a declared reviewer, a review record,
209
+ // bound to one HEAD. It additionally names the red trunk sha it reviewed against (a grant must never
210
+ // survive into a different red) and the red checks it claims to cure. Leading glyph 🩹, distinct from
211
+ // every other mark here.
212
+
213
+ const CI_REVIEW_GRANT_MARK = '🩹 Red-trunk CI review grant';
214
+ const CI_REVIEWER_ROLE = 'ci-reviewer';
215
+ const CI_REVIEW_GRANT_RE = /^🩹 Red-trunk CI review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · red `([^`]*)`@`([^`]*)` · host `([^`]*)` · (\S+)/;
216
+ const CI_REVIEW_GRANT_TAIL = ' — bound to this HEAD and this red trunk sha: a new commit on either voids it; expires when this issue closes.';
217
+ const CI_REVIEW_RECORD_FENCE = 'ci-review';
218
+ const CI_REVIEW_RECORD_VERSION = '1';
219
+ /** `cures:` is a `; `-separated list of red check names (`workflow / job`, or a bare job name) —
220
+ * `;`, not `,`, because matrix job names carry commas (`test (ubuntu, 22)`). */
221
+ const CI_CURES_SEPARATOR = ';';
222
+
223
+ /** Every key a v1 `ci-review` record may carry. Order is the order the encoder writes them in. */
224
+ const CI_REVIEW_RECORD_FIELDS = Object.freeze([
225
+ { key: 'v', required: true, values: [CI_REVIEW_RECORD_VERSION] },
226
+ { key: 'role', required: true, values: [CI_REVIEWER_ROLE] },
227
+ { key: 'reviewer', required: true, re: REVIEWER_ID_RE, hint: 'letters, digits, . _ @ -' },
228
+ { key: 'head', required: true, re: SHA40_RE, hint: 'a full 40-hex commit sha' },
229
+ { key: 'red', required: true, re: SHA40_RE, hint: 'the full 40-hex red trunk sha reviewed against' },
230
+ { key: 'verdict', required: true, values: ['pass', 'fail'] },
231
+ { key: 'cures', required: true, re: /^[^;\s][^;]*(;\s*[^;\s][^;]*)*$/, hint: 'red check names, "; "-separated' },
232
+ { key: 'not-before', required: false, re: /^\d{4}-\d{2}-\d{2}T\S+$/, hint: 'an ISO-8601 instant' },
233
+ { key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
234
+ ]);
235
+
236
+ /** `{role, reviewer, branch, head, trunk, redSha, host, at, tail?, record}` → marker line, blank
237
+ * line, fenced `ci-review` record. Validation is ci-grant.js's job; the codec writes what it gets. */
238
+ function encodeCiReviewGrant({ role, reviewer, branch, head, trunk, redSha, host, at, tail, record } = {}) {
239
+ const marker = withTail(`${CI_REVIEW_GRANT_MARK} — role \`${role}\` · reviewer \`${reviewer}\` · branch \`${branch}\``
240
+ + ` · head \`${head}\` · red \`${trunk}\`@\`${redSha}\` · host \`${host}\` · ${at}`, tail, CI_REVIEW_GRANT_TAIL);
241
+ return `${marker}\n\n${fencedRecord(CI_REVIEW_RECORD_FENCE, CI_REVIEW_RECORD_FIELDS, record)}`;
242
+ }
243
+
244
+ /** A CI review-grant comment → `{role, reviewer, branch, head, trunk, redSha, host, at, tail, record,
245
+ * problems}`, or null when the first line is not one. `problems` holds SYNTAX findings only. */
246
+ function decodeCiReviewGrant(body) {
247
+ const text = String(body == null ? '' : body).replace(/\r\n/g, '\n').trim();
248
+ const m = text.match(CI_REVIEW_GRANT_RE);
249
+ if (!m) return null;
250
+ const nl = text.indexOf('\n');
251
+ const line = nl === -1 ? text : text.slice(0, nl);
252
+ const t = line.slice(m[0].length);
253
+ const out = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], trunk: m[5], redSha: m[6], host: m[7], at: m[8],
254
+ tail: t === CI_REVIEW_GRANT_TAIL ? null : t, record: null, problems: [] };
255
+ return readFencedRecord(text, CI_REVIEW_RECORD_FENCE, out);
256
+ }
257
+
258
+ module.exports = {
259
+ MIGRATION_GRANT_MARK, MIGRATION_REVOKE_MARK, MIGRATION_GRANT_RE, MIGRATION_REVOKE_RE,
260
+ encodeMigrationGrant, decodeMigrationGrant, encodeMigrationRevoke, decodeMigrationRevoke,
261
+ REVIEW_GRANT_MARK, REVIEW_GRANT_RE, REVIEWER_ROLE, REVIEW_RECORD_FENCE, REVIEW_RECORD_VERSION, REVIEW_RECORD_FIELDS,
262
+ REVIEW_GRANT_TAIL, REVIEW_GRANT_CONTENT_TAIL,
263
+ encodeReviewGrant, decodeReviewGrant,
264
+ CI_GRANT_MARK, CI_REVOKE_MARK, CI_GRANT_RE, CI_REVOKE_RE,
265
+ encodeCiGrant, decodeCiGrant, encodeCiRevoke, decodeCiRevoke,
266
+ CI_REVIEW_GRANT_MARK, CI_REVIEW_GRANT_RE, CI_REVIEWER_ROLE, CI_REVIEW_RECORD_FENCE, CI_REVIEW_RECORD_VERSION,
267
+ CI_REVIEW_RECORD_FIELDS, CI_CURES_SEPARATOR, encodeCiReviewGrant, decodeCiReviewGrant,
268
+ };
@@ -0,0 +1,26 @@
1
+ // Types for tools/lib/codec/hold.js (#498) — see index.d.ts.
2
+
3
+ export type WakeKind = 'review-by' | 'edge' | 'ruling' | 'issueClosed' | 'branchLanded' | 'trunkAt' | 'labelPresent' | 'after';
4
+ export const WAKE_KINDS: ReadonlyArray<WakeKind>;
5
+ export const CHECKABLE_KINDS: ReadonlyArray<WakeKind>;
6
+ export const WAKE_KINDS_TEXT: string;
7
+
8
+ export interface WakeCondition { kind: WakeKind; arg: string | null; raw: string; }
9
+ export function parseWake(raw: unknown): WakeCondition | null;
10
+ export function parseWakeLine(value: string | string[] | unknown):
11
+ | { ok: true; conditions: WakeCondition[] }
12
+ | { ok: false; error: string };
13
+ export function parseQualifiedIssueRef(arg: unknown): { slug: string; number: number } | null;
14
+
15
+ export const HOLD_RE: RegExp;
16
+ export const BECAUSE_RE: RegExp;
17
+ export interface DecodedHold {
18
+ label: string;
19
+ owner: string;
20
+ /** The `wake:` field as written — `parseWakeLine` decides whether it names a wake. */
21
+ wake: string;
22
+ /** The `Because:` line's text, or null when the comment is the `Hold:` line alone. */
23
+ because: string | null;
24
+ }
25
+ export function encodeHold(h?: { label: string; owner: string; wake: string | string[]; because?: string | null }): string;
26
+ export function decodeHold(body: string | null | undefined): DecodedHold | null;
@@ -0,0 +1,152 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#498, epic #496): the HOLD wire format — the two-line comment that parks an issue
4
+ * (CONVENTIONS.md §5, *Holds*):
5
+ *
6
+ * Hold: <label> — owner: <who clears it> — wake: <condition>[, <condition>…]
7
+ * Because: <what is left>
8
+ *
9
+ * — and the closed `wake:` vocabulary that line's last field is drawn from (#382). Pure and
10
+ * synchronous: no I/O, no clock, no requires. EVALUATING a wake against facts stays in
11
+ * tools/lib/wake.js, which re-exports the parsers below under the names it always had.
12
+ *
13
+ * Nothing in this toolkit writes a `Hold:` line yet; whoever parks the issue does, and code-triage
14
+ * reads it. The pair exists so every reader parses ONE shape. A line in a looser shape (commas
15
+ * instead of ` — `, a capitalised `Wake:`) is not decoded — it names no machine-readable owner or
16
+ * wake, which is exactly the finding triage reports as a stall. Never loosen the decoder to accept
17
+ * it: a guessed owner or wake is worse than none.
18
+ *
19
+ * ONE SPELLING, NOT TWO (from #382). The checkable wake kinds are spelled name for name the way the
20
+ * one adopting scheduler that already evaluates wakes spells them, argument rules included.
21
+ * wake.test.js pins the list. A line with one unparseable condition is refused WHOLE, never read as
22
+ * its parseable rest — that would wake the hold early on part of its condition.
23
+ */
24
+
25
+ // ── the wake vocabulary ──────────────────────────────────────────────────────────────────────
26
+
27
+ // A cross-repo issue ref: `<owner>/<repo>#<n>`. Same character class the scheduler uses.
28
+ const QUALIFIED_ISSUE_RE = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#(\d+)$/;
29
+ const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
30
+
31
+ function isIsoDate(arg) {
32
+ if (!ISO_DATE_RE.test(arg)) return false;
33
+ const t = Date.parse(`${arg}T00:00:00Z`);
34
+ // Date.parse rolls 2026-02-31 over to March; round-trip it so an impossible date is refused.
35
+ return !Number.isNaN(t) && new Date(t).toISOString().slice(0, 10) === arg;
36
+ }
37
+
38
+ /** The checkable kinds, each with its argument validator. Frozen: this list is the vocabulary. */
39
+ const CHECKABLE = Object.freeze({
40
+ // Bare `<n>` (this repo's own issue) OR qualified `<owner>/<repo>#<n>` (another repo's).
41
+ issueClosed: (arg) => /^\d+$/.test(arg) || QUALIFIED_ISSUE_RE.test(arg),
42
+ branchLanded: (arg) => arg.length > 0 && !/\s/.test(arg),
43
+ trunkAt: (arg) => /^[0-9a-f]{7,40}$/i.test(arg),
44
+ labelPresent: (arg) => arg.length > 0,
45
+ // Epoch-ms digits OR anything Date.parse accepts — permissive on FORMAT only, because this is
46
+ // the one argument a human chooses; the kind itself is still closed.
47
+ after: (arg) => /^\d+$/.test(arg) || !Number.isNaN(Date.parse(arg)),
48
+ });
49
+
50
+ /** The handbook's own three forms, older than the checkable ones and unchanged by #382. */
51
+ const NATIVE = Object.freeze(['review-by', 'edge', 'ruling']);
52
+ /** Every kind a `wake:` may carry, in the order CONVENTIONS lists them. */
53
+ const WAKE_KINDS = Object.freeze([...NATIVE, ...Object.keys(CHECKABLE)]);
54
+ const CHECKABLE_KINDS = Object.freeze(Object.keys(CHECKABLE));
55
+
56
+ const WAKE_KINDS_TEXT = 'review-by:<date> · #N · ruling · issueClosed:<n|owner/repo#n> · ' +
57
+ 'branchLanded:<ref> · trunkAt:<sha> · labelPresent:<label> · after:<date>';
58
+
59
+ /**
60
+ * Parse ONE wake condition → `{kind, arg, raw}`, or `null` for anything outside the closed
61
+ * vocabulary or whose argument fails its kind's validator. A caller treats `null` as "this line
62
+ * names no wake", never as "skip this piece".
63
+ */
64
+ function parseWake(raw) {
65
+ if (typeof raw !== 'string') return null;
66
+ const s = raw.trim();
67
+ if (s === '') return null;
68
+ if (s === 'ruling') return { kind: 'ruling', arg: null, raw: s };
69
+ const edge = /^#(\d+)$/.exec(s);
70
+ if (edge) return { kind: 'edge', arg: edge[1], raw: s };
71
+ const idx = s.indexOf(':');
72
+ if (idx <= 0) return null;
73
+ const kind = s.slice(0, idx);
74
+ const arg = s.slice(idx + 1);
75
+ if (arg === '') return null;
76
+ if (kind === 'review-by') return isIsoDate(arg) ? { kind, arg, raw: s } : null;
77
+ const validate = Object.prototype.hasOwnProperty.call(CHECKABLE, kind) ? CHECKABLE[kind] : null;
78
+ if (!validate || !validate(arg)) return null;
79
+ return { kind, arg, raw: s };
80
+ }
81
+
82
+ /**
83
+ * Parse the value of a `wake:` field — one condition, or several separated by commas, ANDed.
84
+ * Accepts the string as written on the `Hold:` line, or an array of condition strings.
85
+ * @returns {{ok:true, conditions:Array<{kind,arg,raw}>}|{ok:false, error:string}}
86
+ */
87
+ function parseWakeLine(value) {
88
+ const parts = Array.isArray(value)
89
+ ? value
90
+ : (typeof value === 'string' ? value.split(',') : null);
91
+ if (!parts) return { ok: false, error: 'wake: is missing' };
92
+ const pieces = parts.map((p) => (typeof p === 'string' ? p.trim() : p)).filter((p) => p !== '');
93
+ if (pieces.length === 0) return { ok: false, error: 'wake: is empty — a hold must name what ends it' };
94
+ const conditions = [];
95
+ for (const p of pieces) {
96
+ const c = parseWake(p);
97
+ if (!c) {
98
+ return {
99
+ ok: false,
100
+ error: `wake condition ${JSON.stringify(p)} is not in the closed vocabulary — ${WAKE_KINDS_TEXT}. ` +
101
+ 'A wait with no checkable form stays prose in Because: and carries review-by:<date>.',
102
+ };
103
+ }
104
+ conditions.push(c);
105
+ }
106
+ return { ok: true, conditions };
107
+ }
108
+
109
+ /** `<owner>/<repo>#<n>` → `{slug, number}`, or null. */
110
+ function parseQualifiedIssueRef(arg) {
111
+ const m = QUALIFIED_ISSUE_RE.exec(String(arg));
112
+ return m ? { slug: m[1], number: Number(m[2]) } : null;
113
+ }
114
+
115
+ // ── the Hold: / Because: lines ───────────────────────────────────────────────────────────────
116
+
117
+ const HOLD_RE = /^Hold: (\S+) — owner: (.+?) — wake: (.+)$/;
118
+ const BECAUSE_RE = /^Because: (.*)$/;
119
+
120
+ /**
121
+ * `{label, owner, wake, because?}` → the hold comment. `wake` is the field as written (conditions
122
+ * joined by `, `); pass an array to have it joined. `because` null/absent → the `Hold:` line alone.
123
+ * The codec writes what it is given — checking `wake` against the vocabulary is `parseWakeLine`'s job.
124
+ */
125
+ function encodeHold({ label, owner, wake, because } = {}) {
126
+ const w = Array.isArray(wake) ? wake.join(', ') : wake;
127
+ const line = `Hold: ${label} — owner: ${owner} — wake: ${w}`;
128
+ return because == null ? line : `${line}\nBecause: ${because}`;
129
+ }
130
+
131
+ /**
132
+ * A hold comment → `{label, owner, wake, because}`, or null when its FIRST line is not a `Hold:`
133
+ * line in the canonical shape. `because` is the second line's text when that line is `Because: …`
134
+ * and nothing follows it; anything else after the `Hold:` line makes the comment not a hold record
135
+ * (null) rather than a partially-read one. `wake` is the raw field — `parseWakeLine(wake)` decides
136
+ * whether it names a wake at all.
137
+ */
138
+ function decodeHold(body) {
139
+ const lines = String(body == null ? '' : body).replace(/\r\n/g, '\n').trim().split('\n');
140
+ const h = HOLD_RE.exec(lines[0]);
141
+ if (!h) return null;
142
+ if (lines.length === 1) return { label: h[1], owner: h[2], wake: h[3], because: null };
143
+ const b = lines.length === 2 ? BECAUSE_RE.exec(lines[1]) : null;
144
+ if (!b) return null;
145
+ return { label: h[1], owner: h[2], wake: h[3], because: b[1] };
146
+ }
147
+
148
+ module.exports = {
149
+ WAKE_KINDS, CHECKABLE_KINDS, WAKE_KINDS_TEXT,
150
+ parseWake, parseWakeLine, parseQualifiedIssueRef,
151
+ HOLD_RE, BECAUSE_RE, encodeHold, decodeHold,
152
+ };
@@ -0,0 +1,21 @@
1
+ // Types for tools/lib/codec (#497, #498, #499 — epic #496) — the tracker codec. Pure and synchronous:
2
+ // every function here is a string ↔ object transform with no I/O. The wire format's spec is
3
+ // samples.json beside this file; codec.test.js pins that every runtime export is declared.
4
+
5
+ export * from './labels';
6
+ export * from './claim';
7
+ export * from './grants';
8
+ export * from './decision';
9
+ export * from './hold';
10
+ export * from './release';
11
+ export * from './markers';
12
+ import * as labels from './labels';
13
+ import * as claim from './claim';
14
+ import * as grants from './grants';
15
+ import * as decision from './decision';
16
+ import * as hold from './hold';
17
+ import * as release from './release';
18
+ import * as markers from './markers';
19
+ /** Each half, also reachable by name: `codec.labels.decodeLabel`, `codec.grants.decodeCiGrant`, … */
20
+ export { labels, claim };
21
+ export { grants, decision, hold, release, markers };
@@ -0,0 +1,32 @@
1
+ 'use strict';
2
+ /**
3
+ * The tracker codec (#497, epic #496): everything this toolkit writes to an issue tracker with a
4
+ * meaning, as pure, synchronous encode/decode pairs — no I/O, no clock, no requires outside this
5
+ * directory — so a consumer can share it as code instead of keeping a hand copy.
6
+ *
7
+ * labels — the convention label vocabulary, plus `encodeLabel` / `decodeLabel`
8
+ * claim — the `🔒 Claimed` / `✅ Released` comment format, plus `encodeClaim` / `decodeClaim`
9
+ * and `encodeRelease` / `decodeRelease`
10
+ * grants — migration grants (human and reviewer) and red-trunk CI grants, with their revokes (#498)
11
+ * decision — `⚖ Decision recorded` / `↩ Decision reopened`, the options block, `Mockup:` lines (#498)
12
+ * hold — the `Hold:` / `Because:` lines and the closed `wake:` vocabulary's parsers (#498)
13
+ * release — the release rung's tracking marker, event markers and "released in" comment (#498)
14
+ * markers — parent and close-reason markers for trackers with no native field for either (#499)
15
+ *
16
+ * `samples.json` beside this file is the language-neutral spec: real, scrubbed tracker strings that
17
+ * every encode(decode(s)) must reproduce byte for byte. Typed consumers: `index.d.ts`.
18
+ */
19
+ const labels = require('./labels');
20
+ const claim = require('./claim');
21
+ const grants = require('./grants');
22
+ const decision = require('./decision');
23
+ const hold = require('./hold');
24
+ const release = require('./release');
25
+ const markers = require('./markers');
26
+
27
+ // Flat names too. No two halves export the same name (codec.test.js pins it), so the spread below
28
+ // never silently shadows one half's export with another's.
29
+ module.exports = {
30
+ labels, claim, grants, decision, hold, release, markers,
31
+ ...labels, ...claim, ...grants, ...decision, ...hold, ...release, ...markers,
32
+ };
@@ -0,0 +1,65 @@
1
+ // Types for tools/lib/codec/labels.js (#497) — see index.d.ts.
2
+
3
+ // ── labels ───────────────────────────────────────────────────────────────────────────────────
4
+
5
+ export interface ConventionLabel { name: string; color: string; description: string; }
6
+ /** Anything with a `name`, or a bare label name. */
7
+ export type LabelLike = string | { name: string; description?: string } | null | undefined;
8
+
9
+ export type DecodedLabel =
10
+ | { kind: 'delivery'; value: string; known: boolean }
11
+ | { kind: 'deferred'; value: string; known: boolean }
12
+ | { kind: 'review-by'; value: string; known: true }
13
+ | { kind: 'group'; value: string; known: true }
14
+ | { kind: 'convention'; value: string; known: true }
15
+ | { kind: 'other'; value: string; known: false };
16
+ export type LabelKind = DecodedLabel['kind'];
17
+
18
+ export function decodeLabel(name: LabelLike): DecodedLabel;
19
+ export function encodeLabel(label: { kind: LabelKind; value: string }): string;
20
+
21
+ export const CONVENTION_LABELS: ConventionLabel[];
22
+ export function conventionLabelNames(): string[];
23
+ export function missingConventionLabels(present: LabelLike[] | null | undefined): string[];
24
+ export function staleConventionDescriptions(present: LabelLike[] | null | undefined): { name: string; have: string; want: string }[];
25
+ export const MINIMAL_LABEL_NAMES: string[];
26
+ export function minimalConventionLabels(): ConventionLabel[];
27
+
28
+ export const READINESS_LABEL: 'deps-checked';
29
+ export function readinessLabelArgs(opts?: { clear?: boolean }): string[];
30
+ export function readinessMissingLabelHint(present: LabelLike[] | null | undefined): string | null;
31
+ export function readinessMarkedMessage(opts?: {
32
+ num?: number | string; repo?: string;
33
+ summary?: { ok: boolean; total: number; read: number; open: number; unknownState: number } | null;
34
+ }): string;
35
+ export const TRACKING_LABEL: 'tracking';
36
+ export const MECHANICAL_READINESS_LABEL: 'graph-empty';
37
+ export function mechanicalReadinessLabelArgs(opts?: { clear?: boolean }): string[];
38
+ export const MIGRATION_GRANT_LABEL: 'migration-granted';
39
+ export function migrationGrantLabelArgs(opts?: { clear?: boolean }): string[];
40
+ export function migrationGrantMissingLabelHint(present: LabelLike[] | null | undefined): string | null;
41
+ export const CI_GRANT_LABEL: 'ci-granted';
42
+ export function ciGrantLabelArgs(opts?: { clear?: boolean }): string[];
43
+ export function ciGrantMissingLabelHint(present: LabelLike[] | null | undefined): string | null;
44
+ export const NEEDS_DECISION_LABEL: 'needs-decision';
45
+ export const DECISION_RECORDED_LABEL: 'decision-recorded';
46
+ export function decisionRecordedMissingLabelHint(present: LabelLike[] | null | undefined): string | null;
47
+
48
+ export const GROUP_LABEL_PREFIX: 'group:';
49
+ export function isGroupLabel(name: unknown): boolean;
50
+ export function groupLabelNames(present: LabelLike[] | null | undefined): string[];
51
+ export const DELIVERY_LABEL_PREFIX: 'delivery:';
52
+ export const DELIVERY_TYPES: string[];
53
+ export const CODE_LANE_DELIVERY_TYPES: string[];
54
+ export const NON_CODE_DELIVERY_TYPES: string[];
55
+ export function deliveryType(present: LabelLike[] | null | undefined): string | null;
56
+ export function isRouteNotStart(present: LabelLike[] | null | undefined): boolean;
57
+ export const DEFERRED_LABEL_PREFIX: 'deferred:';
58
+ export const DEFERRED_KINDS: string[];
59
+ export function deferredKind(present: LabelLike[] | null | undefined): string | null;
60
+ export function isDeferred(present: LabelLike[] | null | undefined): boolean;
61
+ export const REVIEW_BY_LABEL_PREFIX: 'review-by:';
62
+ export function isReviewByLabel(name: unknown): boolean;
63
+ export function reviewByLabelNames(present: LabelLike[] | null | undefined): string[];
64
+ /** `review-by:YYYY-MM-DD` with a real calendar date → `YYYY-MM-DD`; anything else → null. */
65
+ export function parseReviewByDate(name: LabelLike): string | null;