@futurelastic/colab-handbook 1.13.0-rc.51 → 1.13.0-rc.52

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
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.51"
36
+ "version": "1.13.0-rc.52"
37
37
  }
package/tools/colab CHANGED
@@ -4185,8 +4185,14 @@ TRUSTED_ASSOCIATIONS, checked on read. Same principle, a different mechanism, be
4185
4185
  command TRANSCRIBES a decision made elsewhere rather than AUTHORIZING a write that did not exist
4186
4186
  before it ran — the flag would assert nothing here that \`--ruled-by\` does not already.
4187
4187
 
4188
- \`--answers <ref>\` names the \`<!-- decision:options -->\` comment (id or URL) this decision
4189
- resolves, when one exists — omit it when there was no options block.
4188
+ \`--answers <ref>\` names the question this decision resolves: an ASK ID (the \`id=\` of an open
4189
+ \`<!-- <tool>:ask id=<id> v=<n> -->\` record a dashboard that tracks asks wrote on the issue), or the
4190
+ \`<!-- decision:options -->\` comment (id or URL). Omit it only when there is neither. --record
4191
+ reads the issue's open asks first (#582) — an ask with no answer record, and no ⚖ record
4192
+ naming it, after its latest version: with ONE open ask and no --answers it prints the ask id
4193
+ and the exact re-run line, and says the ruling will be read as answering that ask; with TWO OR
4194
+ MORE it REFUSES before any write and lists every id, because a nameless ruling cannot say which
4195
+ one it settles.
4190
4196
 
4191
4197
  Reopening removes \`${labels.DECISION_RECORDED_LABEL}\`, re-applies \`${labels.NEEDS_DECISION_LABEL}\`,
4192
4198
  and posts a \`${decisionRecord.REOPEN_MARK}\` receipt — every decision on that issue up to this
@@ -4215,7 +4221,7 @@ Options:
4215
4221
  and an issue number is present, for the common one-shot case)
4216
4222
  --reopen reopen an existing decision instead of recording a new one
4217
4223
  --ruled-by <name> required for --record/--reopen — who made this call, never the typist
4218
- --answers <ref> (--record only) the decision:options comment this answers, if any
4224
+ --answers <ref> (--record only) the open ask id, or the decision:options comment, this answers
4219
4225
  --body-file <f> ruling prose (or reopen reason) to append below the marker line
4220
4226
  --list list every issue with a live decision right now, instead of recording
4221
4227
  --json (with --list) machine-readable output
@@ -4307,6 +4313,23 @@ function cmdDecisionRecord(repoAbs, num, opts, body) {
4307
4313
  ${pair.fix}`);
4308
4314
  }
4309
4315
 
4316
+ // #582: show the recorder the asks still waiting on this issue, so the ruling names the one it
4317
+ // settles. One open ask + no --answers: a consumer reads the ruling as answering it — say so.
4318
+ // Two or more + no --answers: ambiguous, refuse before any write (same posture as the pair
4319
+ // check above) and list the ids.
4320
+ const asks = decisionRecord.openAsks(info.comments);
4321
+ const shellQuote = (v) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(String(v)) ? String(v) : `'${String(v).replace(/'/g, `'\\''`)}'`);
4322
+ if (asks.length > 0 && !opts.answers) {
4323
+ const rerun = (id) => `colab decision ${num} --record --ruled-by ${shellQuote(opts.ruledBy)} --answers ${shellQuote(id)}${opts.bodyFile ? ` --body-file ${shellQuote(opts.bodyFile)}` : ''}`;
4324
+ const rows = asks.map((a) => ` ${a.id} (v${a.version}, asked ${a.at || 'unknown'})\n ${rerun(a.id)}`).join('\n');
4325
+ if (asks.length > 1) {
4326
+ throw new UserError(`#${num} has ${asks.length} open asks and this record names none — a reader cannot tell which one the ruling settles. Re-run with --answers <ask id>:
4327
+ ${rows}`);
4328
+ }
4329
+ warn(`#${num} has one open ask: ${asks[0].id} (v${asks[0].version}, asked ${asks[0].at || 'unknown'}). This ruling will be read as answering it. To name it explicitly, re-run as:
4330
+ ${rerun(asks[0].id)}`);
4331
+ }
4332
+
4310
4333
  const present = git.ghListLabels(repoAbs);
4311
4334
  if (present && !present.includes(labels.DECISION_RECORDED_LABEL)) {
4312
4335
  throw new UserError(labels.decisionRecordedMissingLabelHint(present)
@@ -27,3 +27,10 @@ export const OPTIONS_RE: RegExp;
27
27
  export const MOCKUP_RE: RegExp;
28
28
  export function encodeMockup(url: string): string;
29
29
  export function mockupUrls(body: unknown): string[];
30
+
31
+ /** An ask record a dashboard that tracks asks wrote (#582) — read-only to colab. */
32
+ export interface AskRecord { ns: string; id: string; version: number; index: number; }
33
+ /** An answer record naming an ask by id (#582). */
34
+ export interface AnswerRecord { ns: string; ask: string; version: number | null; index: number; }
35
+ export function askRecords(text: unknown): AskRecord[];
36
+ export function answerRecords(text: unknown): AnswerRecord[];
@@ -74,8 +74,62 @@ function mockupUrls(body) {
74
74
  return out;
75
75
  }
76
76
 
77
+ /**
78
+ * ASK / ANSWER RECORDS (#582) — the structured question a dashboard that tracks asks writes onto an
79
+ * issue, and the answer that settles it. READ-ONLY here: colab never writes either, it only needs to
80
+ * know which asks are still open so `colab decision --record` can name the one a ruling settles.
81
+ *
82
+ * Wire shape, namespaced by whatever tool wrote it (the namespace is not interpreted — any tool
83
+ * writing this shape is read the same way):
84
+ * `<!-- <tool>:ask id=<id> v=<n> [key=value …] -->` + the question below it
85
+ * `<!-- <tool>:answer ask=<id> [v=<n>] [key=value …] -->` (+ optional note)
86
+ * and the same heads as a bare line form `<tool>:ask id=…` at the start of a line. Attribute values
87
+ * are percent-encoded and space-separated. Other kinds naming an ask (a wait, a delegation) are not
88
+ * answers and are not read.
89
+ */
90
+ const RECORD_NS = '[a-z][a-z0-9_-]*';
91
+ function recordHeads(text, kind) {
92
+ if (typeof text !== 'string' || text === '') return [];
93
+ const heads = [];
94
+ const markerRe = new RegExp(`<!--\\s*(${RECORD_NS}):${kind}\\s+([^>]*?)\\s*-->`, 'g');
95
+ const lineRe = new RegExp(`^(${RECORD_NS}):${kind}\\s+([^\\n]*)$`, 'gm');
96
+ for (const re of [markerRe, lineRe]) {
97
+ let m;
98
+ while ((m = re.exec(text))) {
99
+ const attrs = parseRecordAttrs(m[2]);
100
+ if (attrs) heads.push({ index: m.index, ns: m[1], attrs });
101
+ }
102
+ }
103
+ return heads.sort((a, b) => a.index - b.index);
104
+ }
105
+ /** `k=v k2=v2` → `{k: v, k2: v2}` (values percent-decoded), or null when any token is not `k=v`. */
106
+ function parseRecordAttrs(raw) {
107
+ const out = {};
108
+ const toks = String(raw).trim().split(/\s+/).filter(Boolean);
109
+ if (toks.length === 0) return null;
110
+ for (const t of toks) {
111
+ const m = /^([a-z][a-z0-9_-]*)=(\S*)$/i.exec(t);
112
+ if (!m) return null;
113
+ try { out[m[1]] = decodeURIComponent(m[2]); } catch (_) { out[m[1]] = m[2]; }
114
+ }
115
+ return out;
116
+ }
117
+ /** Every ask record in `text`, in order: `{ns, id, version, index}`. Requires `id` and an integer `v >= 1`. */
118
+ function askRecords(text) {
119
+ return recordHeads(text, 'ask')
120
+ .filter((h) => h.attrs.id && /^\d+$/.test(h.attrs.v || '') && Number(h.attrs.v) >= 1)
121
+ .map((h) => ({ ns: h.ns, id: h.attrs.id, version: Number(h.attrs.v), index: h.index }));
122
+ }
123
+ /** Every answer record in `text`, in order: `{ns, ask, version, index}` (`version` null when absent). */
124
+ function answerRecords(text) {
125
+ return recordHeads(text, 'answer')
126
+ .filter((h) => h.attrs.ask)
127
+ .map((h) => ({ ns: h.ns, ask: h.attrs.ask, version: /^\d+$/.test(h.attrs.v || '') ? Number(h.attrs.v) : null, index: h.index }));
128
+ }
129
+
77
130
  module.exports = {
78
131
  DECISION_MARK, REOPEN_MARK, DECISION_RE, REOPEN_RE,
79
132
  encodeDecision, decodeDecision, encodeReopen, decodeReopen,
80
133
  OPTIONS_RE, MOCKUP_RE, encodeMockup, mockupUrls,
134
+ askRecords, answerRecords,
81
135
  };
@@ -300,6 +300,47 @@ function evaluateIssue({ labels, comments, labelEvents = null, body, trust } = {
300
300
  return { recorded, gated, contradiction: recorded && gated, pair, pending, decisions, ask, unshapedAsk };
301
301
  }
302
302
 
303
+ /**
304
+ * #582: the ask records on this issue still waiting on an answer — what `colab decision --record`
305
+ * shows the recorder, so the ruling can name the ask it settles (`--answers <id>`). A consumer that
306
+ * tracks asks reads a nameless ruling as answering the issue's ONLY open ask; with two or more it
307
+ * cannot tell which one the ruling meant.
308
+ *
309
+ * An ask is OPEN when no answer comes AFTER its latest ask record (same id; a re-ask at a higher
310
+ * version reopens it). An answer is either an answer record naming the id, or a live `⚖ Decision
311
+ * recorded` whose `answers` field is that id. Order is by `createdAt`, then position inside one
312
+ * comment. Deliberately NOT trust-filtered: this only decides what to SHOW and whether a nameless
313
+ * record is ambiguous — it gates no start and authorizes nothing.
314
+ *
315
+ * Returns [{id, version, at, ns}], oldest-asked first.
316
+ */
317
+ function openAsks(comments) {
318
+ const list = Array.isArray(comments) ? comments : [];
319
+ const sorted = list
320
+ .map((c, i) => ({ c, i }))
321
+ .sort((a, b) => (a.c.createdAt < b.c.createdAt ? -1 : a.c.createdAt > b.c.createdAt ? 1 : a.i - b.i));
322
+ const asks = new Map(); // id -> {id, version, at, ns, pos}
323
+ const answers = []; // {id, pos}
324
+ sorted.forEach(({ c }, ci) => {
325
+ const body = String(c.body || '');
326
+ for (const a of codec.askRecords(body)) {
327
+ asks.set(a.id, { id: a.id, version: a.version, at: c.createdAt || null, ns: a.ns, pos: [ci, a.index] });
328
+ }
329
+ for (const r of codec.answerRecords(body)) answers.push({ id: r.ask, pos: [ci, r.index] });
330
+ });
331
+ const live = new Set(liveDecisions(list).map((d) => d.at));
332
+ sorted.forEach(({ c }, ci) => {
333
+ if (!live.has(c.createdAt)) return;
334
+ const d = codec.decodeDecision(c.body);
335
+ if (d && d.answers && d.answers !== '-') answers.push({ id: d.answers, pos: [ci, 0] });
336
+ });
337
+ const after = (p, q) => p[0] > q[0] || (p[0] === q[0] && p[1] > q[1]);
338
+ return [...asks.values()]
339
+ .filter((a) => !answers.some((r) => r.id === a.id && after(r.pos, a.pos)))
340
+ .sort((a, b) => (after(a.pos, b.pos) ? 1 : -1))
341
+ .map(({ id, version, at, ns }) => ({ id, version, at, ns }));
342
+ }
343
+
303
344
  module.exports = {
304
345
  DECISION_MARK, REOPEN_MARK, DECISION_RE, REOPEN_RE,
305
346
  decisionCommentBody, reopenCommentBody,
@@ -308,4 +349,5 @@ module.exports = {
308
349
  OPTIONS_RE, PAIR_VERDICTS, pairVerdict,
309
350
  MOCKUP_RE, mockupUrls, ASK_SHAPES, askShape,
310
351
  evaluateIssue,
352
+ openAsks,
311
353
  };