@futurelastic/colab-handbook 1.12.0-rc.59 → 1.12.0-rc.61

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 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
@@ -31,5 +31,5 @@
31
31
  "engines": {
32
32
  "node": ">=18"
33
33
  },
34
- "version": "1.12.0-rc.59"
34
+ "version": "1.12.0-rc.61"
35
35
  }
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
- let run = git.ghRunForSha(repoAbs, target);
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, ...(r.verdict.treeGreen ? { cited: r.verdict.treeGreen } : {}) };
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); a sha with no
13779
- run yet counts as pending until the deadline
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
- summary = git.summarizeRunsForCommit(rows, opts.sha);
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
  }
@@ -68,32 +68,28 @@
68
68
  * `COLAB_HUMAN=1`, the same bar `cmdPromote` and `cmdMigrationGrant` already hold.
69
69
  */
70
70
 
71
- /** The two comment markers. STABLE WIRE FORMAT — do not reword casually; `tools/colab` and any
72
- * vendored reader parse these verbatim. Deliberately a DIFFERENT leading emoji from BOTH
73
- * migration-grant's marks (🛢/🚫) AND each other, so no regex here or in migration-grant.js can
74
- * ever cross-match — a four-way collision test in ci-grant.test.js pins this. */
75
- const GRANT_MARK = '🚨 Red-trunk CI grant';
76
- const REVOKE_MARK = '🧯 Red-trunk CI grant revoked';
71
+ // The wire format — both marks (a leading emoji distinct from migration-grant's 🛢/🚫 AND from
72
+ // each other; ci-grant.test.js's four-way collision test pins it), both regexes, and the
73
+ // encode/decode pairs — lives in codec/grants.js (#498, epic #496). Re-exported below under the
74
+ // names this module always had.
75
+ const codec = require('./codec/grants');
76
+ const GRANT_MARK = codec.CI_GRANT_MARK;
77
+ const REVOKE_MARK = codec.CI_REVOKE_MARK;
78
+ const GRANT_RE = codec.CI_GRANT_RE;
79
+ const REVOKE_RE = codec.CI_REVOKE_RE;
77
80
 
78
- const GRANT_RE = /^🚨 Red-trunk CI grant — branch `([^`]*)` · red `([^`]*)`@`([^`]*)` · evidence `([^`]*)` · host `([^`]*)` · (\S+)/;
79
- const REVOKE_RE = /^🧯 Red-trunk CI grant revoked — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
80
-
81
- /** The exact grant-comment body. Keep in lockstep with GRANT_RE. Carries strictly more than
81
+ /** The exact grant-comment body (codec `encodeCiGrant`, canonical tail). Carries strictly more than
82
82
  * migration-grant's equivalent: the TRUNK NAME + RED SHA it was reviewed against, and the
83
83
  * EVIDENCE RUN sha that proved the branch's own head green — both are read back and re-checked
84
84
  * by evaluateIssue, not merely stored for audit. */
85
85
  function grantCommentBody(branch, trunk, redSha, evidenceSha, host, iso) {
86
- return `${GRANT_MARK} — branch \`${branch}\` · red \`${trunk}\`@\`${redSha}\` · evidence \`${evidenceSha}\` · host \`${host}\` · ${iso}`
87
- + ` — this exempts THIS BRANCH from the trunk-CI-green precondition ONLY, only while \`${trunk}\``
88
- + ` is still at \`${redSha}\`, and expires when this issue closes.`;
86
+ return codec.encodeCiGrant({ branch, trunk, redSha, evidenceSha, host, at: iso });
89
87
  }
90
88
 
91
- /** The exact revoke-comment body. Keep in lockstep with REVOKE_RE. `branch` is the branch named in
92
- * the record for the audit trail — revocation itself is NOT branch-scoped (see evaluateIssue doc
93
- * in migration-grant.js; identical reasoning applies here). */
89
+ /** The exact revoke-comment body (codec `encodeCiRevoke`). `branch` is for the audit trail —
90
+ * revocation itself is NOT branch-scoped (see evaluateIssue doc in migration-grant.js). */
94
91
  function revokeCommentBody(branch, host, iso) {
95
- return `${REVOKE_MARK} — branch \`${branch}\` · host \`${host}\` · ${iso}`
96
- + ' — every grant on this issue up to this point is cancelled.';
92
+ return codec.encodeCiRevoke({ branch, host, at: iso });
97
93
  }
98
94
 
99
95
  /**
@@ -0,0 +1,29 @@
1
+ // Types for tools/lib/codec/decision.js (#498) — see index.d.ts.
2
+
3
+ export const DECISION_MARK: '⚖ Decision recorded';
4
+ export const REOPEN_MARK: '↩ Decision reopened';
5
+ export const DECISION_RE: RegExp;
6
+ export const REOPEN_RE: RegExp;
7
+
8
+ export interface DecodedDecision {
9
+ /** The human whose call it is — never the typist. */
10
+ ruledBy: string;
11
+ /** The options block this answers, or `-`. */
12
+ answers: string;
13
+ host: string; at: string;
14
+ /** Rest of the marker line; null = canonical (nothing). */
15
+ tail: string | null;
16
+ /** The ruling prose after one blank line, or null. */
17
+ body: string | null;
18
+ }
19
+ export function encodeDecision(d?: Partial<DecodedDecision>): string;
20
+ export function decodeDecision(text: string | null | undefined): DecodedDecision | null;
21
+
22
+ export interface DecodedReopen { ruledBy: string; host: string; at: string; tail: string | null; body: string | null; }
23
+ export function encodeReopen(r?: Partial<DecodedReopen>): string;
24
+ export function decodeReopen(text: string | null | undefined): DecodedReopen | null;
25
+
26
+ export const OPTIONS_RE: RegExp;
27
+ export const MOCKUP_RE: RegExp;
28
+ export function encodeMockup(url: string): string;
29
+ export function mockupUrls(body: unknown): string[];
@@ -0,0 +1,81 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#498, epic #496): the DECISION wire formats as encode/decode pairs — the `⚖ Decision
4
+ * recorded` record and its `↩ Decision reopened` counterpart, plus the two question-side markers a
5
+ * reader looks for on a `needs-decision` issue (the `<!-- decision:options` block and the `Mockup:`
6
+ * body line). Pure and synchronous: no I/O, no clock, no requires.
7
+ *
8
+ * Which decisions are live, whose are trusted, and whether a label pair is an open question or an
9
+ * interrupted write stay in tools/lib/decision-record.js, which re-exports these under its old names.
10
+ *
11
+ * STABLE WIRE FORMAT. The two marks lead with DIFFERENT glyphs, so a reopen can never parse as a
12
+ * fresh decision. Round trip: a decoded record carries `tail` (rest of the marker line; null = the
13
+ * canonical text) and `body` (the prose after one blank line; null = none), so any comment the
14
+ * regex matches re-encodes byte for byte.
15
+ */
16
+
17
+ const DECISION_MARK = '⚖ Decision recorded';
18
+ const REOPEN_MARK = '↩ Decision reopened';
19
+ const DECISION_RE = /^⚖ Decision recorded — ruled-by `([^`]*)` · answers `([^`]*)` · host `([^`]*)` · (\S+)/;
20
+ const REOPEN_RE = /^↩ Decision reopened — ruled-by `([^`]*)` · host `([^`]*)` · (\S+)/;
21
+ const DECISION_TAIL = '';
22
+ const REOPEN_TAIL = ' — every decision on this issue up to this point is superseded.';
23
+
24
+ /** The question-side options block (CONVENTIONS.md §5, *Decision options*, #126) — presence only. */
25
+ const OPTIONS_RE = /<!--\s*decision:options\b/;
26
+ /** The design-approval ask (#379): `Mockup: <url>` at the START of a body line, nothing after it. */
27
+ const MOCKUP_RE = /^Mockup:[ \t]*(\S+)[ \t]*$/gm;
28
+
29
+ // Split what follows the timestamp into the marker line's tail and the body after a blank line.
30
+ // Anything that is not "<line>\n\n<body>" stays whole in the tail, so nothing is ever dropped.
31
+ function splitRest(rest, canonical) {
32
+ const m = /^([^\n]*)\n\n([\s\S]*)$/.exec(rest);
33
+ const tail = m ? m[1] : rest;
34
+ return { tail: tail === canonical ? null : tail, body: m ? m[2] : null };
35
+ }
36
+ function joinRest(tail, body, canonical) {
37
+ return (tail == null ? canonical : tail) + (body != null && body !== '' ? `\n\n${body}` : '');
38
+ }
39
+
40
+ /**
41
+ * `{ruledBy, answers, host, at, tail?, body?}` → the decision comment. `ruledBy` names the human
42
+ * whose call it is, never the typist; `answers` is the options block this resolves, or `-`.
43
+ */
44
+ function encodeDecision({ ruledBy, answers, host, at, tail, body } = {}) {
45
+ return `${DECISION_MARK} — ruled-by \`${ruledBy}\` · answers \`${answers || '-'}\` · host \`${host}\` · ${at}`
46
+ + joinRest(tail, body, DECISION_TAIL);
47
+ }
48
+ /** A decision comment → `{ruledBy, answers, host, at, tail, body}`, or null. */
49
+ function decodeDecision(text) {
50
+ const s = String(text == null ? '' : text).trim();
51
+ const m = s.match(DECISION_RE);
52
+ if (!m) return null;
53
+ return { ruledBy: m[1], answers: m[2], host: m[3], at: m[4], ...splitRest(s.slice(m[0].length), DECISION_TAIL) };
54
+ }
55
+
56
+ /** `{ruledBy, host, at, tail?, body?}` → the reopen comment; `body` is the reason, if any. */
57
+ function encodeReopen({ ruledBy, host, at, tail, body } = {}) {
58
+ return `${REOPEN_MARK} — ruled-by \`${ruledBy}\` · host \`${host}\` · ${at}` + joinRest(tail, body, REOPEN_TAIL);
59
+ }
60
+ function decodeReopen(text) {
61
+ const s = String(text == null ? '' : text).trim();
62
+ const m = s.match(REOPEN_RE);
63
+ if (!m) return null;
64
+ return { ruledBy: m[1], host: m[2], at: m[3], ...splitRest(s.slice(m[0].length), REOPEN_TAIL) };
65
+ }
66
+
67
+ /** `url` → the `Mockup:` body line. */
68
+ function encodeMockup(url) { return `Mockup: ${url}`; }
69
+ /** Every `Mockup:` URL declared in an issue body, in order. Empty when none (or no body). */
70
+ function mockupUrls(body) {
71
+ if (typeof body !== 'string' || body === '') return [];
72
+ const out = [];
73
+ for (const m of body.replace(/\r\n/g, '\n').matchAll(MOCKUP_RE)) out.push(m[1]);
74
+ return out;
75
+ }
76
+
77
+ module.exports = {
78
+ DECISION_MARK, REOPEN_MARK, DECISION_RE, REOPEN_RE,
79
+ encodeDecision, decodeDecision, encodeReopen, decodeReopen,
80
+ OPTIONS_RE, MOCKUP_RE, encodeMockup, mockupUrls,
81
+ };
@@ -0,0 +1,54 @@
1
+ // Types for tools/lib/codec/grants.js (#498) — see index.d.ts.
2
+ // `tail` on every decoded grant: null = the canonical sentence this toolkit writes; any other string
3
+ // is kept literally so a hand-edited comment re-encodes byte for byte.
4
+
5
+ // ── human migration grant / revoke ───────────────────────────────────────────────────────────
6
+
7
+ export const MIGRATION_GRANT_MARK: '🛢 Migration grant';
8
+ export const MIGRATION_REVOKE_MARK: '🚫 Migration grant revoked';
9
+ export const MIGRATION_GRANT_RE: RegExp;
10
+ export const MIGRATION_REVOKE_RE: RegExp;
11
+
12
+ export interface DecodedMigrationGrant { branch: string; host: string; at: string; tail: string | null; }
13
+ export function encodeMigrationGrant(g?: { branch: string; host: string; at: string; tail?: string | null }): string;
14
+ export function decodeMigrationGrant(body: string | null | undefined): DecodedMigrationGrant | null;
15
+ export function encodeMigrationRevoke(r?: { branch: string; host: string; at: string; tail?: string | null }): string;
16
+ export function decodeMigrationRevoke(body: string | null | undefined): DecodedMigrationGrant | null;
17
+
18
+ // ── reviewer migration grant ─────────────────────────────────────────────────────────────────
19
+
20
+ export const REVIEW_GRANT_MARK: '🔎 Migration review grant';
21
+ export const REVIEW_GRANT_RE: RegExp;
22
+ export const REVIEWER_ROLE: 'migration-reviewer';
23
+ export const REVIEW_RECORD_FENCE: 'migration-review';
24
+ export const REVIEW_RECORD_VERSION: '1';
25
+ export interface ReviewRecordField { key: string; required: boolean; values?: string[]; re?: RegExp; hint?: string; }
26
+ export const REVIEW_RECORD_FIELDS: ReadonlyArray<ReviewRecordField>;
27
+
28
+ export interface DecodedReviewGrant {
29
+ role: string; reviewer: string; branch: string;
30
+ /** Full 40-hex sha the review covers, as written (validity is the caller's check). */
31
+ head: string;
32
+ host: string; at: string; tail: string | null;
33
+ /** The fenced record's `key: value` lines, or null when the comment has no record block. */
34
+ record: Record<string, string> | null;
35
+ /** SYNTAX findings only — never whether the review passes. */
36
+ problems: string[];
37
+ }
38
+ export function encodeReviewGrant(g?: Partial<Omit<DecodedReviewGrant, 'problems' | 'record'>> & { record?: Record<string, unknown> }): string;
39
+ export function decodeReviewGrant(body: string | null | undefined): DecodedReviewGrant | null;
40
+
41
+ // ── red-trunk CI grant / revoke ───────────────────────────────────────────────────────────────
42
+
43
+ export const CI_GRANT_MARK: '🚨 Red-trunk CI grant';
44
+ export const CI_REVOKE_MARK: '🧯 Red-trunk CI grant revoked';
45
+ export const CI_GRANT_RE: RegExp;
46
+ export const CI_REVOKE_RE: RegExp;
47
+
48
+ export interface DecodedCiGrant {
49
+ branch: string; trunk: string; redSha: string; evidenceSha: string; host: string; at: string; tail: string | null;
50
+ }
51
+ export function encodeCiGrant(g?: Omit<DecodedCiGrant, 'tail'> & { tail?: string | null }): string;
52
+ export function decodeCiGrant(body: string | null | undefined): DecodedCiGrant | null;
53
+ export function encodeCiRevoke(r?: { branch: string; host: string; at: string; tail?: string | null }): string;
54
+ export function decodeCiRevoke(body: string | null | undefined): DecodedMigrationGrant | null;
@@ -0,0 +1,184 @@
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, and the
5
+ * red-trunk CI grant and its revoke. Pure and synchronous: no I/O, no clock, no requires.
6
+ *
7
+ * What stays OUT of here is everything that JUDGES a grant: which grants are live, whose comment is
8
+ * trusted, whether a record passes review, whether a grant still binds a HEAD. That lives in
9
+ * tools/lib/migration-grant.js and tools/lib/ci-grant.js, which re-export the names below under the
10
+ * names they always had.
11
+ *
12
+ * STABLE WIRE FORMAT. `tools/colab` and any vendored reader parse these verbatim, and an older CLI on
13
+ * another machine reads what this one writes. Every mark has a DIFFERENT leading emoji from every
14
+ * other (🛢 🚫 🔎 🚨 🧯), so no regex here can match another mark's body — a revoke that merely
15
+ * suffixed its grant would parse as a fresh grant and reopen the door it was posted to close.
16
+ *
17
+ * Round-trip rule shared by every pair below: a decoded comment carries `tail`, the text after the
18
+ * timestamp on the marker line. `tail: null` means "exactly the sentence this toolkit writes", so a
19
+ * canonical comment decodes compactly; any other tail is kept literally, so a hand-edited comment
20
+ * still re-encodes byte for byte.
21
+ */
22
+
23
+ // ── human migration grant / revoke ───────────────────────────────────────────────────────────
24
+
25
+ const MIGRATION_GRANT_MARK = '🛢 Migration grant';
26
+ const MIGRATION_REVOKE_MARK = '🚫 Migration grant revoked';
27
+ const MIGRATION_GRANT_RE = /^🛢 Migration grant — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
28
+ const MIGRATION_REVOKE_RE = /^🚫 Migration grant revoked — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
29
+ const MIGRATION_GRANT_TAIL = ' — this exempts THIS BRANCH only, and expires when this issue closes.';
30
+ const REVOKE_TAIL = ' — every grant on this issue up to this point is cancelled.';
31
+
32
+ function str(body) { return String(body == null ? '' : body).trim(); }
33
+ function tailOf(s, m, canonical) { const t = s.slice(m[0].length); return t === canonical ? null : t; }
34
+ function withTail(head, tail, canonical) { return head + (tail == null ? canonical : tail); }
35
+
36
+ /** `{branch, host, at, tail?}` → the grant comment. `host` is the raw name or its `h:` token. */
37
+ function encodeMigrationGrant({ branch, host, at, tail } = {}) {
38
+ return withTail(`${MIGRATION_GRANT_MARK} — branch \`${branch}\` · host \`${host}\` · ${at}`, tail, MIGRATION_GRANT_TAIL);
39
+ }
40
+ /** A grant comment → `{branch, host, at, tail}`, or null when the body is not one. */
41
+ function decodeMigrationGrant(body) {
42
+ const s = str(body);
43
+ const m = s.match(MIGRATION_GRANT_RE);
44
+ return m ? { branch: m[1], host: m[2], at: m[3], tail: tailOf(s, m, MIGRATION_GRANT_TAIL) } : null;
45
+ }
46
+ /** `{branch, host, at, tail?}` → the revoke comment. The branch is for the audit trail only. */
47
+ function encodeMigrationRevoke({ branch, host, at, tail } = {}) {
48
+ return withTail(`${MIGRATION_REVOKE_MARK} — branch \`${branch}\` · host \`${host}\` · ${at}`, tail, REVOKE_TAIL);
49
+ }
50
+ function decodeMigrationRevoke(body) {
51
+ const s = str(body);
52
+ const m = s.match(MIGRATION_REVOKE_RE);
53
+ return m ? { branch: m[1], host: m[2], at: m[3], tail: tailOf(s, m, REVOKE_TAIL) } : null;
54
+ }
55
+
56
+ // ── reviewer migration grant (#457 era): a marker line plus a fenced `migration-review` record ──
57
+
58
+ const REVIEW_GRANT_MARK = '🔎 Migration review grant';
59
+ const REVIEWER_ROLE = 'migration-reviewer';
60
+ const REVIEW_GRANT_RE = /^🔎 Migration review grant — role `([^`]*)` · reviewer `([^`]*)` · branch `([^`]*)` · head `([^`]*)` · host `([^`]*)` · (\S+)/;
61
+ const REVIEW_GRANT_TAIL = ' — bound to this HEAD: any new commit voids it; expires when this issue closes.';
62
+ /** The fenced block's info string — the record is found by it, never by position. */
63
+ const REVIEW_RECORD_FENCE = 'migration-review';
64
+ const REVIEW_RECORD_VERSION = '1';
65
+
66
+ const SHA40_RE = /^[0-9a-f]{40}$/;
67
+ const REVIEWER_ID_RE = /^[A-Za-z0-9._@-]+$/;
68
+ const CONDITION_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
69
+
70
+ /** Every key a v1 record may carry, and what each accepts. `required: false` keys may be absent.
71
+ * Order here is the order `encodeReviewGrant` writes them in — part of the wire format. */
72
+ const REVIEW_RECORD_FIELDS = Object.freeze([
73
+ { key: 'v', required: true, values: [REVIEW_RECORD_VERSION] },
74
+ { key: 'role', required: true, values: [REVIEWER_ROLE] },
75
+ { key: 'reviewer', required: true, re: REVIEWER_ID_RE, hint: 'letters, digits, . _ @ -' },
76
+ { key: 'head', required: true, re: SHA40_RE, hint: 'a full 40-hex commit sha' },
77
+ { key: 'verdict', required: true, values: ['approve', 'reject'] },
78
+ { key: 'checklist', required: true, values: ['pass', 'fail'] },
79
+ { key: 'checklist-items', required: false, re: /^\d+\/\d+$/, hint: 'N/M, e.g. 7/7' },
80
+ { key: 'escalation', required: true, re: CONDITION_ID_RE, hint: 'a condition id, lowercase-hyphenated' },
81
+ { key: 'escalation-result', required: true, values: ['clear', 'escalated'] },
82
+ { key: 'ci-roundtrip', required: true, values: ['pass', 'fail', 'pending'] },
83
+ { key: 'ci-run', required: false, re: /^\S+$/, hint: 'a run id or URL, no spaces' },
84
+ ]);
85
+
86
+ /**
87
+ * `{role, reviewer, branch, head, host, at, tail?, record}` → marker line, blank line, fenced
88
+ * record. Record keys are written in REVIEW_RECORD_FIELDS order, then any other key in the object's
89
+ * own order; an empty/absent value is omitted. Validating the record is the caller's job
90
+ * (migration-grant.js `validateReviewRecord`) — the codec writes what it is given.
91
+ */
92
+ function encodeReviewGrant({ role, reviewer, branch, head, host, at, tail, record } = {}) {
93
+ const marker = withTail(`${REVIEW_GRANT_MARK} — role \`${role}\` · reviewer \`${reviewer}\` · branch \`${branch}\``
94
+ + ` · head \`${head}\` · host \`${host}\` · ${at}`, tail, REVIEW_GRANT_TAIL);
95
+ const rec = record || {};
96
+ const known = REVIEW_RECORD_FIELDS.map((f) => f.key);
97
+ const keys = [...known.filter((k) => Object.prototype.hasOwnProperty.call(rec, k)),
98
+ ...Object.keys(rec).filter((k) => !known.includes(k))];
99
+ const lines = [];
100
+ for (const k of keys) {
101
+ const v = rec[k];
102
+ if (v === undefined || v === null || String(v) === '') continue;
103
+ lines.push(`${k}: ${v}`);
104
+ }
105
+ return `${marker}\n\n\`\`\`${REVIEW_RECORD_FENCE}\n${lines.join('\n')}\n\`\`\``;
106
+ }
107
+
108
+ /**
109
+ * A reviewer-grant comment → `{role, reviewer, branch, head, host, at, tail, record, problems}`, or
110
+ * null when the first line is not a reviewer-grant marker. The record is the FIRST fenced block whose
111
+ * info string is exactly `migration-review`; text outside it is ignored. `problems` holds SYNTAX
112
+ * findings only (no block, a line that is not `key: value`, a duplicate key) — whether the record's
113
+ * values are acceptable is migration-grant.js's `validateReviewRecord`, never the codec's.
114
+ */
115
+ function decodeReviewGrant(body) {
116
+ const text = String(body == null ? '' : body).replace(/\r\n/g, '\n').trim();
117
+ const m = text.match(REVIEW_GRANT_RE);
118
+ if (!m) return null;
119
+ const nl = text.indexOf('\n');
120
+ const line = nl === -1 ? text : text.slice(0, nl);
121
+ const t = line.slice(m[0].length);
122
+ const out = { role: m[1], reviewer: m[2], branch: m[3], head: m[4], host: m[5], at: m[6],
123
+ tail: t === REVIEW_GRANT_TAIL ? null : t, record: null, problems: [] };
124
+ const fence = new RegExp('^```' + REVIEW_RECORD_FENCE + '[ \\t]*\\n([\\s\\S]*?)^```[ \\t]*$', 'm');
125
+ const fm = text.match(fence);
126
+ if (!fm) {
127
+ out.problems.push(`no \`\`\`${REVIEW_RECORD_FENCE} block — a reviewer grant without its review record is not a grant`);
128
+ return out;
129
+ }
130
+ const record = {};
131
+ for (const raw of fm[1].split('\n')) {
132
+ const l = raw.trim();
133
+ if (l === '') continue;
134
+ const kv = l.match(/^([a-z][a-z-]*):\s*(.*)$/);
135
+ if (!kv) { out.problems.push(`record line ${JSON.stringify(l)} is not "key: value"`); continue; }
136
+ if (Object.prototype.hasOwnProperty.call(record, kv[1])) { out.problems.push(`"${kv[1]}" appears twice`); continue; }
137
+ record[kv[1]] = kv[2].trim();
138
+ }
139
+ out.record = record;
140
+ return out;
141
+ }
142
+
143
+ // ── red-trunk CI grant / revoke ───────────────────────────────────────────────────────────────
144
+
145
+ const CI_GRANT_MARK = '🚨 Red-trunk CI grant';
146
+ const CI_REVOKE_MARK = '🧯 Red-trunk CI grant revoked';
147
+ const CI_GRANT_RE = /^🚨 Red-trunk CI grant — branch `([^`]*)` · red `([^`]*)`@`([^`]*)` · evidence `([^`]*)` · host `([^`]*)` · (\S+)/;
148
+ const CI_REVOKE_RE = /^🧯 Red-trunk CI grant revoked — branch `([^`]*)` · host `([^`]*)` · (\S+)/;
149
+
150
+ /** The CI grant's canonical tail names the trunk and the red sha it was reviewed against. */
151
+ function ciGrantTail(trunk, redSha) {
152
+ return ` — this exempts THIS BRANCH from the trunk-CI-green precondition ONLY, only while \`${trunk}\``
153
+ + ` is still at \`${redSha}\`, and expires when this issue closes.`;
154
+ }
155
+
156
+ /** `{branch, trunk, redSha, evidenceSha, host, at, tail?}` → the CI grant comment. */
157
+ function encodeCiGrant({ branch, trunk, redSha, evidenceSha, host, at, tail } = {}) {
158
+ return withTail(`${CI_GRANT_MARK} — branch \`${branch}\` · red \`${trunk}\`@\`${redSha}\` · evidence \`${evidenceSha}\``
159
+ + ` · host \`${host}\` · ${at}`, tail, ciGrantTail(trunk, redSha));
160
+ }
161
+ function decodeCiGrant(body) {
162
+ const s = str(body);
163
+ const m = s.match(CI_GRANT_RE);
164
+ if (!m) return null;
165
+ return { branch: m[1], trunk: m[2], redSha: m[3], evidenceSha: m[4], host: m[5], at: m[6],
166
+ tail: tailOf(s, m, ciGrantTail(m[2], m[3])) };
167
+ }
168
+ function encodeCiRevoke({ branch, host, at, tail } = {}) {
169
+ return withTail(`${CI_REVOKE_MARK} — branch \`${branch}\` · host \`${host}\` · ${at}`, tail, REVOKE_TAIL);
170
+ }
171
+ function decodeCiRevoke(body) {
172
+ const s = str(body);
173
+ const m = s.match(CI_REVOKE_RE);
174
+ return m ? { branch: m[1], host: m[2], at: m[3], tail: tailOf(s, m, REVOKE_TAIL) } : null;
175
+ }
176
+
177
+ module.exports = {
178
+ MIGRATION_GRANT_MARK, MIGRATION_REVOKE_MARK, MIGRATION_GRANT_RE, MIGRATION_REVOKE_RE,
179
+ encodeMigrationGrant, decodeMigrationGrant, encodeMigrationRevoke, decodeMigrationRevoke,
180
+ REVIEW_GRANT_MARK, REVIEW_GRANT_RE, REVIEWER_ROLE, REVIEW_RECORD_FENCE, REVIEW_RECORD_VERSION, REVIEW_RECORD_FIELDS,
181
+ encodeReviewGrant, decodeReviewGrant,
182
+ CI_GRANT_MARK, CI_REVOKE_MARK, CI_GRANT_RE, CI_REVOKE_RE,
183
+ encodeCiGrant, decodeCiGrant, encodeCiRevoke, decodeCiRevoke,
184
+ };
@@ -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;