@futurelastic/colab-handbook 1.12.0-rc.57 → 1.12.0-rc.58

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,10 @@
17
17
  "tools/colab",
18
18
  "tools/lib/*.js",
19
19
  "!tools/lib/*.test.js",
20
+ "tools/lib/codec/*.js",
21
+ "tools/lib/codec/*.d.ts",
22
+ "tools/lib/codec/samples.json",
23
+ "!tools/lib/codec/*.test.js",
20
24
  "templates/",
21
25
  "audit/audit.mjs"
22
26
  ],
@@ -27,5 +31,5 @@
27
31
  "engines": {
28
32
  "node": ">=18"
29
33
  },
30
- "version": "1.12.0-rc.57"
34
+ "version": "1.12.0-rc.58"
31
35
  }
package/tools/colab CHANGED
@@ -57,6 +57,7 @@ const axisAuthority = require('./lib/axis-authority');
57
57
  const writesAuthority = require('./lib/writes-authority');
58
58
  const claimIdentity = require('./lib/claim-identity');
59
59
  const claimComments = require('./lib/claim-comments');
60
+ const codec = require('./lib/codec');
60
61
  const machine = require('./lib/machine');
61
62
  const targetSync = require('./lib/ship-target-sync');
62
63
  const shipBatch = require('./lib/ship-batch');
@@ -243,9 +244,10 @@ function ghUnusableWhy(repoAbs) {
243
244
  // GitHub offers no atomic check-and-set on labels/assignees.
244
245
  // ---------------------------------------------------------------------------
245
246
 
246
- // The claim/release comment markers and parsers live in tools/lib/claim-comments.js (#369/#375) —
247
+ // The claim/release comment markers and their encode/decode pairs live in tools/lib/codec/claim.js
248
+ // (#497); the readers built on them (liveness, tie-break) in tools/lib/claim-comments.js (#369/#375) —
247
249
  // a STABLE WIRE FORMAT the refusal path, the tie-break and dashboards grep. Do not reword casually.
248
- const { CLAIM_MARK, RELEASE_MARK, liveClaimComments, tieBreakVerdict } = claimComments;
250
+ const { liveClaimComments, tieBreakVerdict } = claimComments; // the format itself: codec/claim.js (#497)
249
251
 
250
252
  /**
251
253
  * #369: may a comment colab posts to THIS repo's tracker name the host in its `host` field? The
@@ -436,14 +438,6 @@ function identityLegend(entries) {
436
438
  print(' Repair: colab worktree tag <worktree> --session <url>');
437
439
  }
438
440
 
439
- /** The ` · session …` comment suffix, or '' — keeps the no-identity comment byte-stable. */
440
- function sessionCommentSuffix(session, sessionName) {
441
- if (sessionName && session) return ` · session [${sessionName}](${session})`; // both → markdown link
442
- if (session) return ` · session ${session}`; // url only → legacy form
443
- if (sessionName) return ` · session ${sessionName}`; // name only
444
- return '';
445
- }
446
-
447
441
  /**
448
442
  * Worktree lifecycle status, backfilled-on-read: entries created before this field existed (or by
449
443
  * an older colab) render as `running`. Values: `running` (default, at create) → `merged` (branch
@@ -452,17 +446,18 @@ function sessionCommentSuffix(session, sessionName) {
452
446
  */
453
447
  function wtStatus(wt) { return (wt && wt.status) || 'running'; }
454
448
 
455
- /** The exact claim-comment body. Keep in lockstep with CLAIM_RE/parseSessionField and the README. */
449
+ /**
450
+ * The exact claim-comment body. The format itself is codec/claim.js `encodeClaim` (#497); this
451
+ * supplies what the codec deliberately does not hold — the clock and the machine digest. `-` stands
452
+ * for "no branch"/"no worktree" (#53, it used to be the word `trunk`). `host` is the raw hostname
453
+ * where the destination may name it, the `h:` token where it may not (#369, `commentHost`); the
454
+ * comparable identity is the machine digest beside it (#327), omitted when no id resolved.
455
+ */
456
456
  function claimCommentBody(wtName, branch, session, sessionName, host = HOST) {
457
- // `-` for "no branch", matching the worktree field beside it. It used to be the word `trunk`,
458
- // which read as a branch name that never existed (#53).
459
- const base = `${CLAIM_MARK} — worktree \`${wtName || '-'}\` · branch \`${branch || '-'}\` · host \`${host}\` · ${nowISO()}`;
460
- // #327: `host` is the raw hostname where the destination may name it, the `h:` token where it
461
- // may not (#369, `commentHost`); the comparable identity is the machine digest beside it.
462
- // Omitted when no id resolved.
463
- const token = machine.machineToken(myMachineId());
464
- const mach = token ? ` · machine \`${token}\`` : '';
465
- return base + mach + sessionCommentSuffix(session, sessionName);
457
+ return codec.encodeClaim({
458
+ worktree: wtName, branch, host, at: nowISO(),
459
+ machine: machine.machineToken(myMachineId()) || '', session, sessionName,
460
+ });
466
461
  }
467
462
 
468
463
  /** Issues whose EXISTING local claim sits on a different worktree than the one we're claiming onto. */
@@ -716,7 +711,7 @@ function postClaimComment(repoAbs, num, wtName, branch, session, sessionName) {
716
711
  function postReleaseComment(repoAbs, num) {
717
712
  const info = git.ghIssueView(repoAbs, num, ['state']);
718
713
  if (info && info.state === 'CLOSED') return true; // don't chatter on a closed issue
719
- const r = git.ghIssueComment(repoAbs, num, RELEASE_MARK);
714
+ const r = git.ghIssueComment(repoAbs, num, codec.encodeRelease());
720
715
  if (!r.ok) { warnDeferred(`could not post release comment on #${num} (${r.stderr.split('\n')[0] || r.code})`); return false; }
721
716
  return true;
722
717
  }
@@ -14,62 +14,15 @@
14
14
  const claimIdentity = require('./claim-identity');
15
15
  const machine = require('./machine');
16
16
 
17
- const CLAIM_MARK = '🔒 Claimed';
18
- const RELEASE_MARK = '✅ Released';
17
+ // The wire format itself — markers, regexes, the session/identity fields and the claim/release
18
+ // encode/decode pairs — lives in codec/claim.js (#497). Re-exported below under the names this
19
+ // module always had, so no caller breaks.
20
+ const codec = require('./codec/claim');
21
+ const { CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, YIELD_RE, parseSessionField, parseIdentity } = codec;
19
22
  // #378: how far BEFORE our own claim a rival's live claim can be and still count as "simultaneous".
20
23
  // Racers post within seconds of each other; 10 minutes is deliberately generous so a slow `gh` never
21
24
  // splits a real race, while a claim weeks old — abandoned, or released only in prose — is not a race.
22
25
  const RACE_WINDOW_MS = 10 * 60 * 1000;
23
- // Parses a claim comment body back into {worktree, branch, host, date}. The `· <host>` field is
24
- // what lets the tie-break tell two machines of the SAME GitHub user apart. On a public destination
25
- // it carries an opaque `h:` token instead of the raw name (#369, machine.js `hostToken`) — same
26
- // field, same position, so this regex and every older parser read both shapes. The optional
27
- // trailing `· session <value>` (added 2026-07) is captured separately by SESSION_RE so this regex
28
- // stays byte-stable for session-less comments.
29
- const CLAIM_RE = /🔒 Claimed — worktree `([^`]*)` · branch `([^`]*)` · host `([^`]*)` · (\S+)/;
30
- // The `· session <field>` tail, captured as the rest of the line. parseSessionField() then decodes
31
- // the THREE shapes it can take — `[name](url)`, a bare URL, or a bare name — plus the legacy
32
- // plain-URL form written before sessionName existed.
33
- const SESSION_RE = /· session (.+)$/;
34
- // #327: the claimant's machine, as the public `m:` digest (tools/lib/machine.js `machineToken`),
35
- // written AFTER the timestamp and BEFORE the session suffix — so CLAIM_RE's four groups and
36
- // SESSION_RE's end anchor both parse a new comment exactly as they parse a legacy one, and a legacy
37
- // comment (no such field) simply has no machine and is compared by host.
38
- const MACHINE_RE = /· machine `(m:[0-9a-f]{12})`/;
39
- // A yield: the loser of a race releases, naming the winner by its identity string
40
- // (`claimIdentity.identityString` — `login@host`, or `login@host#session` under the fine setting).
41
- const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
42
-
43
- /**
44
- * Decode the `· session <field>` tail of a claim comment into { sessionName, session }. Accepts:
45
- * `[name](url)` → both; bare `https://…`/`session_…` → url only; any other bare token → name.
46
- * The bare-URL branch is exactly the LEGACY format written before sessionName existed, so old
47
- * comments keep parsing. Returns empty strings when there is no session tail.
48
- */
49
- function parseSessionField(body) {
50
- const m = String(body).match(SESSION_RE);
51
- if (!m) return { sessionName: '', session: '' };
52
- const v = m[1].trim();
53
- const link = v.match(/^\[([^\]]*)\]\((.*)\)$/);
54
- if (link) return { sessionName: link[1], session: link[2] };
55
- // #306: the shape test lives in claimIdentity.looksLikeSessionId — one copy of the rule.
56
- if (claimIdentity.looksLikeSessionId(v)) return { sessionName: '', session: v };
57
- return { sessionName: v, session: '' };
58
- }
59
-
60
- /** `login@host[#session]` → its parts. Logins cannot contain `@`, hosts cannot contain `#`. */
61
- function parseIdentity(s) {
62
- const str = String(s || '').trim();
63
- const at = str.indexOf('@');
64
- if (at <= 0) return null;
65
- const rest = str.slice(at + 1);
66
- const hash = rest.indexOf('#');
67
- return {
68
- login: str.slice(0, at),
69
- host: hash === -1 ? rest : rest.slice(0, hash),
70
- session: hash === -1 ? '' : rest.slice(hash + 1),
71
- };
72
- }
73
26
 
74
27
  /**
75
28
  * Is claim `c` the one a yield NAMED as its winner? Login exact, host by `sameHostName` (so a
@@ -91,11 +44,10 @@ function isNamedWinner(c, named) {
91
44
  function releaseComments(sorted) {
92
45
  const out = [];
93
46
  for (const c of sorted) {
94
- const body = String(c.body || '').trim();
95
- if (!body.startsWith(RELEASE_MARK)) continue;
47
+ const rel = codec.decodeRelease(c.body || '');
48
+ if (!rel) continue;
96
49
  const login = (c.author && c.author.login) || '';
97
- const y = body.match(YIELD_RE);
98
- if (y) out.push({ kind: 'yield', login, at: c.createdAt, winner: parseIdentity(y[1]) });
50
+ if (rel.kind === 'yield') out.push({ kind: 'yield', login, at: c.createdAt, winner: parseIdentity(rel.winner) });
99
51
  else out.push({ kind: 'release', login, at: c.createdAt });
100
52
  }
101
53
  return out;
@@ -133,14 +85,11 @@ function liveClaimComments(comments, comps) {
133
85
  const releases = releaseComments(sorted);
134
86
  const live = [];
135
87
  for (const c of sorted) {
136
- const body = String(c.body || '').trim();
137
- const m = body.match(CLAIM_RE);
138
- if (!m) continue;
88
+ const claim = codec.decodeClaim(c.body || ''); // [name](url) / url / name / legacy, machine or not
89
+ if (!claim) continue;
139
90
  const login = (c.author && c.author.login) || '';
140
- const host = m[3];
141
- const { session, sessionName } = parseSessionField(body); // handles [name](url) / url / name / legacy
142
- const mm = body.match(MACHINE_RE); // #327 — absent on a legacy comment: compared by host
143
- const machineTok = mm ? mm[1] : '';
91
+ const { host, session, sessionName } = claim;
92
+ const machineTok = claim.machine; // #327 — '' on a legacy comment: compared by host
144
93
  const at = c.createdAt;
145
94
  const entry = { login, host, machine: machineTok, session, sessionName, at };
146
95
  const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
@@ -203,7 +152,7 @@ function yieldReleaseBody(winner, { redact = false } = {}) {
203
152
  const tail = id.startsWith(head) ? id.slice(head.length) : '';
204
153
  id = `${winner.login}@${machine.hostToken(winner.host)}${tail}`;
205
154
  }
206
- return `${RELEASE_MARK} (yielded — earlier claim by ${id} wins)`;
155
+ return codec.encodeRelease({ winner: id });
207
156
  }
208
157
 
209
158
  module.exports = {
@@ -168,8 +168,9 @@ function mergeClaimRecord(existing, incoming, { sameHolder } = {}) {
168
168
 
169
169
  /**
170
170
  * Does `v` look like a session ID a consumer could actually JOIN on — a URL, or a `session_…`
171
- * token embedded in one (#306)? The repo's ONE answer to that question: `parseSessionField`
172
- * (tools/colab) decodes a claim comment's `· session <field>` tail with exactly this test, and
171
+ * token embedded in one (#306)? The repo's ONE answer to that question — defined in codec/claim.js
172
+ * since #497 and re-exported here: `parseSessionField` (codec/claim.js) decodes a claim comment's
173
+ * `· session <field>` tail with exactly this test, and
173
174
  * `warnWeakIdentity` warns with it. Two copies of a shape rule drift, and this one decides
174
175
  * whether a hold can ever be released by its own owner, so there is one.
175
176
  *
@@ -182,11 +183,7 @@ function mergeClaimRecord(existing, incoming, { sameHolder } = {}) {
182
183
  * False for '' / null: absence is `warnWeakIdentity`'s and `requirePlaceIdentity`'s subject
183
184
  * (#11/#242), never this predicate's — callers test blankness first.
184
185
  */
185
- function looksLikeSessionId(v) {
186
- const s = String(v == null ? '' : v).trim();
187
- if (!s) return false;
188
- return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s);
189
- }
186
+ const { looksLikeSessionId } = require('./codec/claim'); // one copy of the rule, in the codec (#497)
190
187
 
191
188
  module.exports = {
192
189
  DEFAULT_COMPONENTS, FINE_COMPONENTS,
@@ -0,0 +1,41 @@
1
+ // Types for tools/lib/codec/claim.js (#497) — see index.d.ts.
2
+
3
+ // ── claim / release comments ─────────────────────────────────────────────────────────────────
4
+
5
+ export const CLAIM_MARK: '🔒 Claimed';
6
+ export const RELEASE_MARK: '✅ Released';
7
+ export const CLAIM_RE: RegExp;
8
+ export const SESSION_RE: RegExp;
9
+ export const MACHINE_RE: RegExp;
10
+ export const YIELD_RE: RegExp;
11
+
12
+ export function looksLikeSessionId(v: unknown): boolean;
13
+
14
+ export interface SessionField { session: string; sessionName: string; }
15
+ export function encodeSessionField(session?: string, sessionName?: string): string;
16
+ export function parseSessionField(body: string): SessionField;
17
+
18
+ export interface Identity { login: string; host: string; session: string; }
19
+ export function encodeIdentity(id?: { login: string; host: string; session?: string }): string;
20
+ export function parseIdentity(s: string | null | undefined): Identity | null;
21
+
22
+ export interface DecodedClaim extends SessionField {
23
+ /** `-` when the claim names no worktree — kept literally so the pair round-trips. */
24
+ worktree: string;
25
+ /** `-` when the claim names no branch (#53). */
26
+ branch: string;
27
+ /** Raw hostname, or its `h:` token on a destination that may not name it (#369). */
28
+ host: string;
29
+ /** ISO timestamp as written. */
30
+ at: string;
31
+ /** `m:` digest (#327), or '' on a legacy comment. */
32
+ machine: string;
33
+ }
34
+ export function encodeClaim(claim?: Partial<DecodedClaim>): string;
35
+ export function decodeClaim(body: string | null | undefined): DecodedClaim | null;
36
+
37
+ export type DecodedRelease =
38
+ | { kind: 'release'; rest: string }
39
+ | { kind: 'yield'; winner: string; rest: string };
40
+ export function encodeRelease(release?: { winner?: string; rest?: string }): string;
41
+ export function decodeRelease(body: string | null | undefined): DecodedRelease | null;
@@ -0,0 +1,151 @@
1
+ 'use strict';
2
+ /**
3
+ * CODEC (#497, epic #496): the claim/release comment WIRE FORMAT as encode/decode pairs. Pure and
4
+ * synchronous — no I/O, no clock, no requires — so it can be shared as code with any consumer that
5
+ * reads or writes the same comments. The readers built on it (which claims still stand, who wins a
6
+ * race) stay in tools/lib/claim-comments.js; the writers that need the clock, the machine id and the
7
+ * tracker stay in tools/colab and call `encodeClaim` / `encodeRelease` here.
8
+ *
9
+ * These strings are a STABLE WIRE FORMAT: the refusal path, the tie-break, and dashboards grep
10
+ * them, and an older colab on another machine parses what this one writes. `codec/samples.json`
11
+ * holds real, scrubbed comments; the test requires every one to survive encode(decode(s)) byte for
12
+ * byte. Change a byte here and that test is what tells you an older reader just broke.
13
+ */
14
+
15
+ const CLAIM_MARK = '🔒 Claimed';
16
+ const RELEASE_MARK = '✅ Released';
17
+ // Parses a claim comment body back into {worktree, branch, host, at}. The `· <host>` field is
18
+ // what lets the tie-break tell two machines of the SAME GitHub user apart. On a public destination
19
+ // it carries an opaque `h:` token instead of the raw name (#369, machine.js `hostToken`) — same
20
+ // field, same position, so this regex and every older parser read both shapes. The optional
21
+ // trailing `· session <value>` (added 2026-07) is captured separately by SESSION_RE so this regex
22
+ // stays byte-stable for session-less comments.
23
+ const CLAIM_RE = /🔒 Claimed — worktree `([^`]*)` · branch `([^`]*)` · host `([^`]*)` · (\S+)/;
24
+ // The `· session <field>` tail, captured as the rest of the line. parseSessionField() then decodes
25
+ // the THREE shapes it can take — `[name](url)`, a bare URL, or a bare name — plus the legacy
26
+ // plain-URL form written before sessionName existed.
27
+ const SESSION_RE = /· session (.+)$/;
28
+ // #327: the claimant's machine, as the public `m:` digest (tools/lib/machine.js `machineToken`),
29
+ // written AFTER the timestamp and BEFORE the session suffix — so CLAIM_RE's four groups and
30
+ // SESSION_RE's end anchor both parse a new comment exactly as they parse a legacy one, and a legacy
31
+ // comment (no such field) simply has no machine and is compared by host.
32
+ const MACHINE_RE = /· machine `(m:[0-9a-f]{12})`/;
33
+ // A yield: the loser of a race releases, naming the winner by its identity string
34
+ // (`claimIdentity.identityString` — `login@host`, or `login@host#session` under the fine setting).
35
+ const YIELD_RE = /^✅ Released \(yielded — earlier claim by (.+?) wins\)/;
36
+
37
+ /**
38
+ * Does `v` look like a session URL / `session_…` id rather than a display name? A SHAPE heuristic
39
+ * (#306), not a gate — claim-identity.js re-exports this one copy of it.
40
+ */
41
+ function looksLikeSessionId(v) {
42
+ const s = String(v == null ? '' : v).trim();
43
+ if (!s) return false;
44
+ return /^https?:\/\//.test(s) || /session_[\w-]+/.test(s);
45
+ }
46
+
47
+ /**
48
+ * Encode the `· session <field>` tail of a claim comment. Both → a markdown link; url only → the
49
+ * legacy bare form; name only → the bare name; neither → nothing.
50
+ */
51
+ function encodeSessionField(session, sessionName) {
52
+ if (sessionName && session) return ` · session [${sessionName}](${session})`;
53
+ if (session) return ` · session ${session}`;
54
+ if (sessionName) return ` · session ${sessionName}`;
55
+ return '';
56
+ }
57
+
58
+ /**
59
+ * Decode the `· session <field>` tail of a claim comment into { sessionName, session }. Accepts:
60
+ * `[name](url)` → both; bare `https://…`/`session_…` → url only; any other bare token → name.
61
+ * The bare-URL branch is exactly the LEGACY format written before sessionName existed, so old
62
+ * comments keep parsing. Returns empty strings when there is no session tail.
63
+ */
64
+ function parseSessionField(body) {
65
+ const m = String(body).match(SESSION_RE);
66
+ if (!m) return { sessionName: '', session: '' };
67
+ const v = m[1].trim();
68
+ const link = v.match(/^\[([^\]]*)\]\((.*)\)$/);
69
+ if (link) return { sessionName: link[1], session: link[2] };
70
+ if (looksLikeSessionId(v)) return { sessionName: '', session: v };
71
+ return { sessionName: v, session: '' };
72
+ }
73
+
74
+ /** `{login, host, session}` → `login@host[#session]` — the identity string a yield names. */
75
+ function encodeIdentity({ login, host, session } = {}) {
76
+ return `${login}@${host}${session ? `#${session}` : ''}`;
77
+ }
78
+
79
+ /** `login@host[#session]` → its parts. Logins cannot contain `@`, hosts cannot contain `#`. */
80
+ function parseIdentity(s) {
81
+ const str = String(s || '').trim();
82
+ const at = str.indexOf('@');
83
+ if (at <= 0) return null;
84
+ const rest = str.slice(at + 1);
85
+ const hash = rest.indexOf('#');
86
+ return {
87
+ login: str.slice(0, at),
88
+ host: hash === -1 ? rest : rest.slice(0, hash),
89
+ session: hash === -1 ? '' : rest.slice(hash + 1),
90
+ };
91
+ }
92
+
93
+ /**
94
+ * The exact claim-comment body. Every field is written as given: `worktree`/`branch` default to `-`
95
+ * ("none" — it used to be the word `trunk`, which read as a branch that never existed, #53); `at`
96
+ * is the caller's ISO timestamp (the codec holds no clock); `machine` is the `m:` digest or empty
97
+ * (#327, the field is then omitted); `host` is the raw hostname or its `h:` token, whichever the
98
+ * destination allows (#369 — deciding that is the caller's job, not the codec's).
99
+ */
100
+ function encodeClaim({ worktree, branch, host, at, machine, session, sessionName } = {}) {
101
+ const base = `${CLAIM_MARK} — worktree \`${worktree || '-'}\` · branch \`${branch || '-'}\` · host \`${host}\` · ${at}`;
102
+ const mach = machine ? ` · machine \`${machine}\`` : '';
103
+ return base + mach + encodeSessionField(session, sessionName);
104
+ }
105
+
106
+ /**
107
+ * A claim comment body → { worktree, branch, host, at, machine, session, sessionName }, or null when
108
+ * the body carries no claim. Lenient exactly where the readers always were (CLAIM_RE is unanchored,
109
+ * a legacy comment simply lacks machine/session), and lossless on what `encodeClaim` writes:
110
+ * `worktree`/`branch` keep a literal `-` rather than mapping it to empty, so the pair round-trips.
111
+ */
112
+ function decodeClaim(body) {
113
+ const str = String(body == null ? '' : body).trim();
114
+ const m = str.match(CLAIM_RE);
115
+ if (!m) return null;
116
+ const mm = str.match(MACHINE_RE);
117
+ const { session, sessionName } = parseSessionField(str);
118
+ return { worktree: m[1], branch: m[2], host: m[3], at: m[4], machine: mm ? mm[1] : '', session, sessionName };
119
+ }
120
+
121
+ /**
122
+ * A release comment body. `{}` → the plain marker (`colab release`, `worktree rm`); `{ winner }` →
123
+ * a yield naming the winner's identity string. `rest` is any text after the marker (or after the
124
+ * yield's closing parenthesis) — a hand-written release keeps its prose through a round trip.
125
+ */
126
+ function encodeRelease({ winner, rest } = {}) {
127
+ const tail = rest || '';
128
+ if (winner) return `${RELEASE_MARK} (yielded — earlier claim by ${winner} wins)${tail}`;
129
+ return RELEASE_MARK + tail;
130
+ }
131
+
132
+ /**
133
+ * A release comment body → { kind: 'yield', winner, rest } | { kind: 'release', rest }, or null when
134
+ * the body is not a release. `winner` is the raw identity string (`parseIdentity` splits it).
135
+ */
136
+ function decodeRelease(body) {
137
+ const str = String(body == null ? '' : body).trim();
138
+ if (!str.startsWith(RELEASE_MARK)) return null;
139
+ const y = str.match(YIELD_RE);
140
+ if (y) return { kind: 'yield', winner: y[1], rest: str.slice(y[0].length) };
141
+ return { kind: 'release', rest: str.slice(RELEASE_MARK.length) };
142
+ }
143
+
144
+ module.exports = {
145
+ CLAIM_MARK, RELEASE_MARK, CLAIM_RE, SESSION_RE, MACHINE_RE, YIELD_RE,
146
+ looksLikeSessionId,
147
+ encodeSessionField, parseSessionField,
148
+ encodeIdentity, parseIdentity,
149
+ encodeClaim, decodeClaim,
150
+ encodeRelease, decodeRelease,
151
+ };
@@ -0,0 +1,10 @@
1
+ // Types for tools/lib/codec (#497, epic #496) — the tracker codec. Pure and synchronous: every
2
+ // 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
+ import * as labels from './labels';
8
+ import * as claim from './claim';
9
+ /** The two halves, also reachable by name: `codec.labels.decodeLabel`, `codec.claim.encodeClaim`. */
10
+ export { labels, claim };
@@ -0,0 +1,17 @@
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
+ *
11
+ * `samples.json` beside this file is the language-neutral spec: real, scrubbed tracker strings that
12
+ * every encode(decode(s)) must reproduce byte for byte. Typed consumers: `index.d.ts`.
13
+ */
14
+ const labels = require('./labels');
15
+ const claim = require('./claim');
16
+
17
+ module.exports = { labels, claim, ...labels, ...claim };
@@ -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;