@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 +1 -1
- package/tools/colab +26 -3
- package/tools/lib/codec/decision.d.ts +7 -0
- package/tools/lib/codec/decision.js +54 -0
- package/tools/lib/decision-record.js +42 -0
package/package.json
CHANGED
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
|
|
4189
|
-
|
|
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
|
|
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
|
};
|