@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.1
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/README.md +2 -2
- package/README.vi.md +2 -2
- package/audit/audit.mjs +90 -10
- package/package.json +1 -1
- package/templates/README.md +18 -3
- package/templates/ci-laravel.yml +360 -40
- package/templates/ci-node.yml +491 -35
- package/templates/ci-python.yml +301 -32
- package/templates/deploy-container-run.mjs +17 -3
- package/templates/deploy-xserver.yml +12 -0
- package/templates/instruction-files.yml +11 -0
- package/templates/pre-commit-instruction-files +55 -0
- package/tools/colab +750 -67
- package/tools/lib/batch-stats.js +66 -43
- package/tools/lib/claim-comments.js +3 -2
- package/tools/lib/codec/decision.d.ts +7 -0
- package/tools/lib/codec/decision.js +54 -0
- package/tools/lib/codec/hold.d.ts +8 -1
- package/tools/lib/codec/hold.js +42 -8
- package/tools/lib/codec/release.js +6 -3
- package/tools/lib/codec/samples.json +45 -0
- package/tools/lib/config-set.js +4 -3
- package/tools/lib/decision-record.js +42 -0
- package/tools/lib/docs-only.js +47 -0
- package/tools/lib/git.js +57 -8
- package/tools/lib/instruction-file.js +49 -0
- package/tools/lib/instruction-gate.js +150 -0
- package/tools/lib/landed-prs.js +58 -0
- package/tools/lib/migration-grant.js +29 -5
- package/tools/lib/owner-policy.js +133 -0
- package/tools/lib/release-finalize.js +66 -5
- package/tools/lib/ship-batch.js +188 -14
- package/tools/lib/ship-handoff.js +174 -0
- package/tools/lib/stamp.js +6 -2
- package/tools/lib/template-trunk.js +80 -0
- package/tools/lib/tree-green.js +21 -4
package/tools/lib/batch-stats.js
CHANGED
|
@@ -20,12 +20,18 @@
|
|
|
20
20
|
* What it measures, per window:
|
|
21
21
|
* batches landed and their fill; every combined-run build, first-attempt green, green after
|
|
22
22
|
* the one re-run, red, still pending
|
|
23
|
-
* red red builds and how many of their members then landed serially
|
|
23
|
+
* red red builds and how many of their members then landed alone — serially, or as a
|
|
24
|
+
* batch of one (#580) — the fallback
|
|
24
25
|
* dropped members dropped at build, by class, and the eviction rate among attempted members
|
|
25
26
|
* serial serial landings, and MISSED PARTNERS: another candidate that landed later but was
|
|
26
27
|
* already green when this one landed alone (could have joined), or turned green
|
|
27
28
|
* within this landing's trunk-CI cycle (a partner wait of `waitSec` would have caught
|
|
28
|
-
* it — the number `ship-batch-wait` is tuned from)
|
|
29
|
+
* it — the number `ship-batch-wait` is tuned from). `serial` means landed through the
|
|
30
|
+
* SERIAL PATH (no Ship-Batch trailer), and only that
|
|
31
|
+
* alone the same partner scan over every change that LANDED ALONE: a serial landing, or a
|
|
32
|
+
* batch of one (#580). Since #562 a lone ready candidate on a ship-batch repo lands as
|
|
33
|
+
* a fill-1 batch, so on such a repo `serial` reads zero whether partners were missed or
|
|
34
|
+
* not; `alone` is the signal `ship-batch-wait` is tuned from there
|
|
29
35
|
* queueWait per landed change, green-at-head → landing
|
|
30
36
|
*/
|
|
31
37
|
|
|
@@ -175,16 +181,21 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
|
|
|
175
181
|
const rerunGreen = buildRows.filter((b) => b.state === 'green' && b.attempt > 1).length;
|
|
176
182
|
const redBuilds = buildRows.filter((b) => b.state === 'red');
|
|
177
183
|
|
|
178
|
-
// ---- red builds → did their members then land serially? ----
|
|
184
|
+
// ---- red builds → did their members then land alone (serially, or as a batch of one)? ----
|
|
179
185
|
const serialChanges = changes.filter((c) => c.landing.kind === 'serial');
|
|
180
|
-
|
|
186
|
+
// #580: a fill-1 batch landed alone exactly as a serial landing did — only its path differs.
|
|
187
|
+
const isBatchOfOne = (c) => c.landing.kind === 'batch' && c.landing.members.length === 1;
|
|
188
|
+
const aloneChanges = changes.filter((c) => c.landing.kind === 'serial' || isBatchOfOne(c));
|
|
189
|
+
let redMembers = 0, relanded = 0, relandedAlone = 0, redMembersUnread = 0;
|
|
181
190
|
for (const b of redBuilds) {
|
|
182
191
|
const members = b.messages && b.messages.length ? shipBatch.parseMemberTrailers(b.messages) : [];
|
|
183
192
|
if (!members.length) { redMembersUnread++; continue; }
|
|
184
193
|
for (const m of members) {
|
|
185
194
|
redMembers++;
|
|
186
195
|
const nums = branchName.branchIssueNumbers(m.branch);
|
|
187
|
-
|
|
196
|
+
const isMember = (c) => c.atMs >= b.createdMs && (c.branch === m.branch || c.issues.some((n) => nums.includes(n)));
|
|
197
|
+
if (serialChanges.some(isMember)) relanded++;
|
|
198
|
+
if (aloneChanges.some(isMember)) relandedAlone++;
|
|
188
199
|
}
|
|
189
200
|
}
|
|
190
201
|
if (redMembersUnread) notes.push(`${redMembersUnread} red build(s) whose members could not be read (the ref is gone and its commits were not readable)`);
|
|
@@ -205,42 +216,57 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
|
|
|
205
216
|
const byClass = {};
|
|
206
217
|
for (const d of dropped) byClass[d.cls] = (byClass[d.cls] || 0) + 1;
|
|
207
218
|
|
|
208
|
-
// ---- missed partners:
|
|
209
|
-
const pairs = [];
|
|
210
|
-
let withMissed = 0, withNear = 0, cyclesUnread = 0, overlapped = 0;
|
|
219
|
+
// ---- missed partners: landings that went alone while a partner was (nearly) ready ----
|
|
211
220
|
// A partner is judged by ITS state at this landing's moment, never by the head it finally landed
|
|
212
221
|
// with: a serial ship syncs the other branches, so their final heads all post-date it. The cycle
|
|
213
222
|
// ends when this landing's trunk run finishes — or at the next landing, whichever is first (a
|
|
214
223
|
// re-run moves a run's updated_at hours later, and the next landing moves trunk anyway).
|
|
215
224
|
const landingTimes = landings.map((l) => l.atMs).sort((a, b) => a - b);
|
|
216
|
-
|
|
217
|
-
const
|
|
218
|
-
let
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
const
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
225
|
+
const scanPartners = (lone, tagVia) => {
|
|
226
|
+
const pairs = [];
|
|
227
|
+
let withMissed = 0, withNear = 0, cyclesUnread = 0, overlapped = 0;
|
|
228
|
+
for (const c of lone) {
|
|
229
|
+
const next = landingTimes.find((t) => t > c.atMs);
|
|
230
|
+
let end = cycleEnd(c.landing.sha);
|
|
231
|
+
if (end === null) cyclesUnread++;
|
|
232
|
+
else if (next !== undefined) end = Math.min(end, next);
|
|
233
|
+
let missed = false, near = false;
|
|
234
|
+
const label = c.branch || c.landing.sha.slice(0, 7);
|
|
235
|
+
const via = tagVia ? { via: c.landing.kind === 'serial' ? 'serial' : 'batch-of-one' } : {};
|
|
236
|
+
for (const o of changes) {
|
|
237
|
+
if (o === c || o.landing === c.landing || o.atMs <= c.atMs || !o.branch || o.branch === c.branch) continue;
|
|
238
|
+
const gNow = greenAt(runsByBranch, o.branch, c.atMs);
|
|
239
|
+
if (gNow !== null) {
|
|
240
|
+
missed = true;
|
|
241
|
+
pairs.push({ kind: 'missed', landed: label, partner: o.branch, ...via });
|
|
242
|
+
continue;
|
|
243
|
+
}
|
|
244
|
+
if (end === null) continue;
|
|
245
|
+
const gEnd = greenAt(runsByBranch, o.branch, end);
|
|
246
|
+
if (gEnd !== null && gEnd > c.atMs) {
|
|
247
|
+
near = true;
|
|
248
|
+
const from = c.greenMs !== null ? c.greenMs : c.atMs;
|
|
249
|
+
pairs.push({ kind: 'near', landed: label, partner: o.branch, waitSec: Math.round((gEnd - from) / 1000), ...via });
|
|
250
|
+
}
|
|
237
251
|
}
|
|
252
|
+
if (missed) withMissed++;
|
|
253
|
+
else if (near) withNear++;
|
|
254
|
+
if (end !== null && (missed || near)) overlapped++;
|
|
238
255
|
}
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
256
|
+
return {
|
|
257
|
+
landings: lone.length, withMissedPartner: withMissed, withNearMiss: withNear,
|
|
258
|
+
// #556: the overlap rate's honest denominator — only a landing whose trunk-CI cycle was read
|
|
259
|
+
// could have been judged for a partner inside it; `overlapped` counts those that had one.
|
|
260
|
+
cyclesRead: lone.length - cyclesUnread, overlapped,
|
|
261
|
+
nearMissWait: summary(pairs.filter((p) => p.kind === 'near').map((p) => p.waitSec)),
|
|
262
|
+
pairs,
|
|
263
|
+
};
|
|
264
|
+
};
|
|
265
|
+
const serial = scanPartners(serialChanges, false);
|
|
266
|
+
const alone = scanPartners(aloneChanges, true);
|
|
267
|
+
// The alone set contains the serial one, so its unread count is the one note (never two).
|
|
268
|
+
const aloneUnread = alone.landings - alone.cyclesRead;
|
|
269
|
+
if (aloneUnread) notes.push(`${aloneUnread} lone landing(s) (serial or a batch of one) with no finished trunk run in the window — near misses not judged for them`);
|
|
244
270
|
const unknownGreen = changes.filter((c) => c.greenMs === null).length;
|
|
245
271
|
if (unknownGreen) notes.push(`${unknownGreen} landed change(s) with no readable green-at-head run — left out of queue wait and partner matching`);
|
|
246
272
|
|
|
@@ -259,16 +285,13 @@ function derive({ commits = [], runs = [], builds = {}, trunk = 'main', config =
|
|
|
259
285
|
pending: buildRows.length - finished.length,
|
|
260
286
|
firstAttemptGreenRate: rate(firstGreen, finished.length),
|
|
261
287
|
},
|
|
262
|
-
|
|
288
|
+
// relandedSerially: through the serial path only; relandedAlone: serially OR as a batch of one (#580).
|
|
289
|
+
red: { builds: redBuilds.length, members: redMembers, relandedSerially: relanded, relandedAlone },
|
|
263
290
|
dropped: { count: dropped.length, attempted: builtMembers + dropped.length, rate: rate(dropped.length, builtMembers + dropped.length), byClass, members: dropped },
|
|
264
|
-
serial
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
cyclesRead: serialChanges.length - cyclesUnread, overlapped,
|
|
269
|
-
nearMissWait: summary(pairs.filter((p) => p.kind === 'near').map((p) => p.waitSec)),
|
|
270
|
-
pairs,
|
|
271
|
-
},
|
|
291
|
+
// `serial`: landed through the serial path. `alone`: landed alone by either path — a serial
|
|
292
|
+
// landing or a batch of one (#580); its pairs carry `via: 'serial' | 'batch-of-one'`.
|
|
293
|
+
serial,
|
|
294
|
+
alone: { ...alone, batchOfOne: aloneChanges.filter(isBatchOfOne).length },
|
|
272
295
|
queueWait,
|
|
273
296
|
notes,
|
|
274
297
|
};
|
|
@@ -55,7 +55,7 @@ function releaseComments(sorted) {
|
|
|
55
55
|
|
|
56
56
|
/**
|
|
57
57
|
* Live claim comments on an issue. Returns [{login, host, machine, session, sessionName, at,
|
|
58
|
-
* identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
|
|
58
|
+
* branch, worktree, identity}], `at` = the comment's real GitHub createdAt (authoritative, sub-second). `identity`
|
|
59
59
|
* is built from `comps` (claim-identity.js `components()`, #267); the raw fields are returned too
|
|
60
60
|
* for callers that need `sameClaimant`'s degrade-on-missing comparison.
|
|
61
61
|
*
|
|
@@ -91,7 +91,8 @@ function liveClaimComments(comments, comps) {
|
|
|
91
91
|
const { host, session, sessionName } = claim;
|
|
92
92
|
const machineTok = claim.machine; // #327 — '' on a legacy comment: compared by host
|
|
93
93
|
const at = c.createdAt;
|
|
94
|
-
|
|
94
|
+
// #578: branch/worktree ride along so a reader can ask WHICH branch a live claim holds.
|
|
95
|
+
const entry = { login, host, machine: machineTok, session, sessionName, at, branch: claim.branch, worktree: claim.worktree };
|
|
95
96
|
const cancelled = releases.some((r) => r.at > at && (r.kind === 'release'
|
|
96
97
|
|| (r.login === login && !isNamedWinner(entry, r.winner))));
|
|
97
98
|
if (!cancelled) live.push({ ...entry, identity: claimIdentity.identityString({ login, host, session }, comps) });
|
|
@@ -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
|
};
|
|
@@ -14,13 +14,20 @@ export function parseQualifiedIssueRef(arg: unknown): { slug: string; number: nu
|
|
|
14
14
|
|
|
15
15
|
export const HOLD_RE: RegExp;
|
|
16
16
|
export const BECAUSE_RE: RegExp;
|
|
17
|
+
export type HoldShape = 'ask' | 'task' | 'wait';
|
|
18
|
+
export const HOLD_SHAPES: ReadonlyArray<HoldShape>;
|
|
17
19
|
export interface DecodedHold {
|
|
18
20
|
label: string;
|
|
19
21
|
owner: string;
|
|
22
|
+
/** The declared `shape:` as written (#569) — present only when the line carries one. */
|
|
23
|
+
shape?: string;
|
|
20
24
|
/** The `wake:` field as written — `parseWakeLine` decides whether it names a wake. */
|
|
21
25
|
wake: string;
|
|
22
26
|
/** The `Because:` line's text, or null when the comment is the `Hold:` line alone. */
|
|
23
27
|
because: string | null;
|
|
24
28
|
}
|
|
25
|
-
export function encodeHold(h?: { label: string; owner: string; wake: string | string[]; because?: string | null }): string;
|
|
29
|
+
export function encodeHold(h?: { label: string; owner: string; shape?: HoldShape | null; wake: string | string[]; because?: string | null }): string;
|
|
26
30
|
export function decodeHold(body: string | null | undefined): DecodedHold | null;
|
|
31
|
+
/** Declared shape when in the closed set, else inferred from the wake (`ruling` → ask, else wait). */
|
|
32
|
+
export function holdShape(decoded: Partial<DecodedHold> | null | undefined):
|
|
33
|
+
{ shape: HoldShape; declared: boolean; invalid: string | null };
|
package/tools/lib/codec/hold.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* CODEC (#498, epic #496): the HOLD wire format — the two-line comment that parks an issue
|
|
4
4
|
* (CONVENTIONS.md §5, *Holds*):
|
|
5
5
|
*
|
|
6
|
-
* Hold: <label> — owner: <who clears it> — wake: <condition>[, <condition>…]
|
|
6
|
+
* Hold: <label> — owner: <who clears it>[ — shape: ask|task|wait] — wake: <condition>[, <condition>…]
|
|
7
7
|
* Because: <what is left>
|
|
8
8
|
*
|
|
9
9
|
* — and the closed `wake:` vocabulary that line's last field is drawn from (#382). Pure and
|
|
@@ -114,17 +114,47 @@ function parseQualifiedIssueRef(arg) {
|
|
|
114
114
|
|
|
115
115
|
// ── the Hold: / Because: lines ───────────────────────────────────────────────────────────────
|
|
116
116
|
|
|
117
|
-
|
|
117
|
+
// `shape:` (#569) sits BETWEEN owner and wake on purpose. An older reader's pattern is
|
|
118
|
+
// `owner: (.+?) — wake: (.+)$`: placed there, the field folds into that reader's owner text and
|
|
119
|
+
// its wake still parses whole. Placed after wake: it would corrupt the wake, and the older reader
|
|
120
|
+
// would report a perfectly good hold as a stall. Never move it.
|
|
121
|
+
const HOLD_RE = /^Hold: (\S+) — owner: (.+?)(?: — shape: (\S+))? — wake: (.+)$/;
|
|
118
122
|
const BECAUSE_RE = /^Because: (.*)$/;
|
|
119
123
|
|
|
124
|
+
/**
|
|
125
|
+
* What the owner is being asked for (#569) — closed, read by equality:
|
|
126
|
+
* ask — a choice between ways forward. Posted as a structured ask (`needs-decision` + a
|
|
127
|
+
* `decision:options` block with a recommended default), never as a bare hold.
|
|
128
|
+
* task — an act only a person can perform: verify by hand, run a privileged script, sign,
|
|
129
|
+
* supply a credential.
|
|
130
|
+
* wait — on a third party, another issue, a ref or a date.
|
|
131
|
+
*/
|
|
132
|
+
const HOLD_SHAPES = Object.freeze(['ask', 'task', 'wait']);
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* The shape a reader acts on: the declared `shape:` when it is in the closed set, otherwise the
|
|
136
|
+
* inference that predates the field — a `ruling` anywhere in the wake reads as `ask`, anything
|
|
137
|
+
* else as `wait`. `declared` says which. An unknown declared value is not trusted (`invalid` names
|
|
138
|
+
* it) and falls back to the inference, so a typo never silently re-routes a hold.
|
|
139
|
+
* @returns {{shape:'ask'|'task'|'wait', declared:boolean, invalid:string|null}}
|
|
140
|
+
*/
|
|
141
|
+
function holdShape(decoded) {
|
|
142
|
+
const d = decoded || {};
|
|
143
|
+
if (d.shape != null && HOLD_SHAPES.includes(d.shape)) return { shape: d.shape, declared: true, invalid: null };
|
|
144
|
+
const parsed = parseWakeLine(d.wake);
|
|
145
|
+
const ruling = parsed.ok && parsed.conditions.some((c) => c.kind === 'ruling');
|
|
146
|
+
return { shape: ruling ? 'ask' : 'wait', declared: false, invalid: d.shape != null ? String(d.shape) : null };
|
|
147
|
+
}
|
|
148
|
+
|
|
120
149
|
/**
|
|
121
150
|
* `{label, owner, wake, because?}` → the hold comment. `wake` is the field as written (conditions
|
|
122
151
|
* joined by `, `); pass an array to have it joined. `because` null/absent → the `Hold:` line alone.
|
|
123
152
|
* The codec writes what it is given — checking `wake` against the vocabulary is `parseWakeLine`'s job.
|
|
124
153
|
*/
|
|
125
|
-
function encodeHold({ label, owner, wake, because } = {}) {
|
|
154
|
+
function encodeHold({ label, owner, shape, wake, because } = {}) {
|
|
126
155
|
const w = Array.isArray(wake) ? wake.join(', ') : wake;
|
|
127
|
-
const
|
|
156
|
+
const sh = shape == null ? '' : ` — shape: ${shape}`;
|
|
157
|
+
const line = `Hold: ${label} — owner: ${owner}${sh} — wake: ${w}`;
|
|
128
158
|
return because == null ? line : `${line}\nBecause: ${because}`;
|
|
129
159
|
}
|
|
130
160
|
|
|
@@ -133,20 +163,24 @@ function encodeHold({ label, owner, wake, because } = {}) {
|
|
|
133
163
|
* line in the canonical shape. `because` is the second line's text when that line is `Because: …`
|
|
134
164
|
* and nothing follows it; anything else after the `Hold:` line makes the comment not a hold record
|
|
135
165
|
* (null) rather than a partially-read one. `wake` is the raw field — `parseWakeLine(wake)` decides
|
|
136
|
-
* whether it names a wake at all.
|
|
166
|
+
* whether it names a wake at all. `shape` is present ONLY when the line declares one (#569), as
|
|
167
|
+
* written — `holdShape` decides whether it is in the closed set; absent means "infer from wake".
|
|
137
168
|
*/
|
|
138
169
|
function decodeHold(body) {
|
|
139
170
|
const lines = String(body == null ? '' : body).replace(/\r\n/g, '\n').trim().split('\n');
|
|
140
171
|
const h = HOLD_RE.exec(lines[0]);
|
|
141
172
|
if (!h) return null;
|
|
142
|
-
|
|
173
|
+
const head = h[3] == null
|
|
174
|
+
? { label: h[1], owner: h[2], wake: h[4] }
|
|
175
|
+
: { label: h[1], owner: h[2], shape: h[3], wake: h[4] };
|
|
176
|
+
if (lines.length === 1) return { ...head, because: null };
|
|
143
177
|
const b = lines.length === 2 ? BECAUSE_RE.exec(lines[1]) : null;
|
|
144
178
|
if (!b) return null;
|
|
145
|
-
return {
|
|
179
|
+
return { ...head, because: b[1] };
|
|
146
180
|
}
|
|
147
181
|
|
|
148
182
|
module.exports = {
|
|
149
183
|
WAKE_KINDS, CHECKABLE_KINDS, WAKE_KINDS_TEXT,
|
|
150
184
|
parseWake, parseWakeLine, parseQualifiedIssueRef,
|
|
151
|
-
HOLD_RE, BECAUSE_RE, encodeHold, decodeHold,
|
|
185
|
+
HOLD_RE, BECAUSE_RE, HOLD_SHAPES, encodeHold, decodeHold, holdShape,
|
|
152
186
|
};
|
|
@@ -4,7 +4,10 @@
|
|
|
4
4
|
* (CONVENTIONS.md §6, *The release rung*), as encode/decode pairs. Pure and synchronous.
|
|
5
5
|
*
|
|
6
6
|
* tracking marker — `<!-- colab:release version=vX.Y.Z -->`, the first line of a tracking
|
|
7
|
-
* issue's body. Only the marker identifies the version, never the title
|
|
7
|
+
* issue's body. Only the marker identifies the version, never the title —
|
|
8
|
+
* and only at the START of the body (leading whitespace tolerated): a body
|
|
9
|
+
* that merely MENTIONS the marker further down is talking about releases,
|
|
10
|
+
* not recording one, and is never adopted as the record (#575).
|
|
8
11
|
* event marker — `<!-- colab:release-event k=v … -->`, one per thing announced on the
|
|
9
12
|
* tracking issue, keys in the order written. Its exact presence is what makes
|
|
10
13
|
* a re-run post nothing twice, so key order is part of the wire format.
|
|
@@ -16,7 +19,7 @@
|
|
|
16
19
|
*/
|
|
17
20
|
|
|
18
21
|
const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
|
|
19
|
-
const TRACKING_MARKER_RE =
|
|
22
|
+
const TRACKING_MARKER_RE = /^\s*<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
|
|
20
23
|
const RELEASE_EVENT_RE = /^<!-- colab:release-event((?: [^\s=]+=\S*)+) -->$/;
|
|
21
24
|
const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.$/;
|
|
22
25
|
|
|
@@ -24,7 +27,7 @@ const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nRelea
|
|
|
24
27
|
function encodeTrackingMarker(version) { return `<!-- colab:release version=${version} -->`; }
|
|
25
28
|
|
|
26
29
|
/** The version a body's tracking marker declares, or null — a marker naming a non-canonical
|
|
27
|
-
* version (a leading zero) declares nothing. */
|
|
30
|
+
* version (a leading zero) declares nothing, and neither does one anywhere but the body's start. */
|
|
28
31
|
function decodeTrackingMarker(body) {
|
|
29
32
|
const m = TRACKING_MARKER_RE.exec(String(body || ''));
|
|
30
33
|
return m && VERSION_RE.test(m[1]) ? m[1] : null;
|
|
@@ -656,6 +656,39 @@
|
|
|
656
656
|
"because": null
|
|
657
657
|
},
|
|
658
658
|
"note": "synthetic: a Hold line with no Because line"
|
|
659
|
+
},
|
|
660
|
+
{
|
|
661
|
+
"wire": "Hold: blocked:needs-maintainer — owner: maintainer — shape: task — wake: ruling\nBecause: run the signing script on the release machine; only the maintainer holds the key.",
|
|
662
|
+
"decoded": {
|
|
663
|
+
"label": "blocked:needs-maintainer",
|
|
664
|
+
"owner": "maintainer",
|
|
665
|
+
"shape": "task",
|
|
666
|
+
"wake": "ruling",
|
|
667
|
+
"because": "run the signing script on the release machine; only the maintainer holds the key."
|
|
668
|
+
},
|
|
669
|
+
"note": "synthetic (#569): a chore declared as a task — without shape: its `ruling` wake would read as a choice"
|
|
670
|
+
},
|
|
671
|
+
{
|
|
672
|
+
"wire": "Hold: deferred:external-party — owner: upstream maintainers — shape: wait — wake: issueClosed:OWNER/REPO#22, review-by:2026-11-02\nBecause: the design mirrors one still open upstream.",
|
|
673
|
+
"decoded": {
|
|
674
|
+
"label": "deferred:external-party",
|
|
675
|
+
"owner": "upstream maintainers",
|
|
676
|
+
"shape": "wait",
|
|
677
|
+
"wake": "issueClosed:OWNER/REPO#22, review-by:2026-11-02",
|
|
678
|
+
"because": "the design mirrors one still open upstream."
|
|
679
|
+
},
|
|
680
|
+
"note": "synthetic (#569): a declared wait"
|
|
681
|
+
},
|
|
682
|
+
{
|
|
683
|
+
"wire": "Hold: needs-decision — owner: @maintainer — shape: ask — wake: ruling\nBecause: pick the import model; the options block in the body recommends A.",
|
|
684
|
+
"decoded": {
|
|
685
|
+
"label": "needs-decision",
|
|
686
|
+
"owner": "@maintainer",
|
|
687
|
+
"shape": "ask",
|
|
688
|
+
"wake": "ruling",
|
|
689
|
+
"because": "pick the import model; the options block in the body recommends A."
|
|
690
|
+
},
|
|
691
|
+
"note": "synthetic (#569): a declared ask — the choice itself lives in the issue's decision:options block"
|
|
659
692
|
}
|
|
660
693
|
],
|
|
661
694
|
"notHolds": [
|
|
@@ -677,6 +710,18 @@
|
|
|
677
710
|
"decoded": "v0.1.6"
|
|
678
711
|
}
|
|
679
712
|
],
|
|
713
|
+
"notTracking": [
|
|
714
|
+
{
|
|
715
|
+
"wire": "Finalize keeps one tracking issue per version; its body starts <!-- colab:release version=v0.1.6 --> and nothing else counts.",
|
|
716
|
+
"decoded": null,
|
|
717
|
+
"note": "synthetic (#575): an issue ABOUT releases that mentions the marker mid-body — never adopted as the record"
|
|
718
|
+
},
|
|
719
|
+
{
|
|
720
|
+
"wire": "fix: release lookup\n\n```\n<!-- colab:release version=v0.1.6 -->\n```",
|
|
721
|
+
"decoded": null,
|
|
722
|
+
"note": "synthetic (#575): the marker quoted on a later line, not the body's first"
|
|
723
|
+
}
|
|
724
|
+
],
|
|
680
725
|
"events": [
|
|
681
726
|
{
|
|
682
727
|
"wire": "<!-- colab:release-event candidate=v0.1.6-rc.1 -->",
|
package/tools/lib/config-set.js
CHANGED
|
@@ -35,6 +35,7 @@ const DESCRIPTOR = '.github/project.yml';
|
|
|
35
35
|
const TUNING = Object.freeze({
|
|
36
36
|
'ship-batch': (doc) => { const r = shipBatch.parseShipBatch(doc); return r.valid ? null : r.reason; },
|
|
37
37
|
'ship-batch-wait': (doc) => { const r = shipBatch.parseShipBatchWait(doc); return r.valid ? null : r.reason; },
|
|
38
|
+
[shipBatch.STEPS_KEY]: (doc) => { const r = shipBatch.parseShipBatchSteps(doc); return r.valid ? null : r.reason; },
|
|
38
39
|
'ci-wait-factor': (doc) => { const r = ciProfile.parseFactor(doc); return r.valid ? null : r.reason; },
|
|
39
40
|
[thresholds.KEY]: (doc) => { const r = thresholds.parseThresholds(doc); return r.problems.length ? r.problems.join('; ') : null; },
|
|
40
41
|
});
|
|
@@ -49,8 +50,8 @@ const AUTHORITY_KEYS = Object.freeze([
|
|
|
49
50
|
'exposure', 'tier', 'trunk', 'deploy', 'release', 'production',
|
|
50
51
|
]);
|
|
51
52
|
|
|
52
|
-
/** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`). */
|
|
53
|
-
const VALUE_RE = /^[A-Za-z0-9._
|
|
53
|
+
/** A value is a plain YAML scalar — every tuning value is one (`2`, `6m`, `1.5`, `2,4,8`). */
|
|
54
|
+
const VALUE_RE = /^[A-Za-z0-9._,-]+$/;
|
|
54
55
|
|
|
55
56
|
/**
|
|
56
57
|
* `ship-batch` → `{ top: 'ship-batch', sub: null }`; `thresholds.hot-file-count` → `{ top:
|
|
@@ -89,7 +90,7 @@ function replaceValue(line, value) {
|
|
|
89
90
|
* old }` (`old` is the previous raw value, or null when the key was absent), or `{ problem }`.
|
|
90
91
|
*/
|
|
91
92
|
function editText(text, keyPath, value) {
|
|
92
|
-
if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ -)` };
|
|
93
|
+
if (!VALUE_RE.test(String(value))) return { problem: `value ${JSON.stringify(value)} is not a plain scalar (letters, digits, . _ , -)` };
|
|
93
94
|
const src = String(text);
|
|
94
95
|
const eol = src.endsWith('\n') ? '' : '\n';
|
|
95
96
|
const lines = src.split('\n');
|
|
@@ -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
|
};
|
package/tools/lib/docs-only.js
CHANGED
|
@@ -19,6 +19,19 @@ const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
|
|
|
19
19
|
const DOCS_DIR = 'docs/';
|
|
20
20
|
/** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
|
|
21
21
|
const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
|
|
22
|
+
/**
|
|
23
|
+
* #570: build inputs that happen to end in `.txt` — a suite installs or compiles from them, so a change
|
|
24
|
+
* to one changes behaviour. Never documentation, at any depth: a Python dependency manifest exactly as
|
|
25
|
+
* the cure rule names one (cure-diff.js isPythonManifest — a name containing `requirements`, or under a
|
|
26
|
+
* `requirements/` directory, any case), a pip constraints file, and `CMakeLists.txt`. A `.txt` pulled
|
|
27
|
+
* in by `-r`/`-c` under some other name is NOT caught by name — a repo with one lists it in
|
|
28
|
+
* `ci-docs-skip`.
|
|
29
|
+
*/
|
|
30
|
+
function buildInput(p, base) {
|
|
31
|
+
// Lazy: cure-diff.js requires this module at load time.
|
|
32
|
+
if (require('./cure-diff').isPythonManifest(p)) return true;
|
|
33
|
+
return /constraints.*\.txt$/i.test(base) || base === 'CMakeLists.txt';
|
|
34
|
+
}
|
|
22
35
|
/** Config directories: nothing under them is documentation, at any depth. */
|
|
23
36
|
const NEVER_DIRS = Object.freeze(['.claude', '.github', '.githooks']);
|
|
24
37
|
/**
|
|
@@ -40,6 +53,7 @@ function pathReason(p) {
|
|
|
40
53
|
const segs = String(p).split('/');
|
|
41
54
|
const base = segs[segs.length - 1];
|
|
42
55
|
if (NEVER_BASENAMES.includes(base)) return `${base} is agent rules, not documentation`;
|
|
56
|
+
if (buildInput(String(p), base)) return `${base} is a build input, not documentation`;
|
|
43
57
|
const dir = segs.slice(0, -1).find((s) => NEVER_DIRS.includes(s));
|
|
44
58
|
if (dir) return `under ${dir}/ (config)`;
|
|
45
59
|
const dirs = segs.slice(0, -1);
|
|
@@ -164,7 +178,40 @@ function directChanges(git, repo, trunk, since) {
|
|
|
164
178
|
return { ...verdict, commits: shas.length };
|
|
165
179
|
}
|
|
166
180
|
|
|
181
|
+
/**
|
|
182
|
+
* #570: `ci-docs-skip:` in project.yml — the opt-in to the CI templates' docs-only mode. Absent (or
|
|
183
|
+
* null) = off. A list = on; each member is a repo path whose changes always run the suite even though
|
|
184
|
+
* this module calls them documentation (`docs/api/` feeding a generator). `[]` = on, nothing excluded.
|
|
185
|
+
*
|
|
186
|
+
* The CI guard parses the same shape in shell and reads anything else as "not opted in" — the
|
|
187
|
+
* stricter direction — so an invalid value here is a finding: a declaration that silently does
|
|
188
|
+
* nothing. Members are plain paths (the guard matches `p == x` or `p` under `x/`): no glob, no `..`
|
|
189
|
+
* or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
|
|
190
|
+
*/
|
|
191
|
+
const CI_DOCS_SKIP_KEY = 'ci-docs-skip';
|
|
192
|
+
function parseCiDocsSkip(doc) {
|
|
193
|
+
const has = !!doc && Object.prototype.hasOwnProperty.call(doc, CI_DOCS_SKIP_KEY);
|
|
194
|
+
const v = has ? doc[CI_DOCS_SKIP_KEY] : null;
|
|
195
|
+
if (v === null || v === undefined) {
|
|
196
|
+
return { declared: false, valid: true, on: false, exclude: null, reason: 'ci-docs-skip absent — a docs-only change runs the full CI suite (#570)' };
|
|
197
|
+
}
|
|
198
|
+
const bad = (why) => ({ declared: true, valid: false, on: false, exclude: null,
|
|
199
|
+
reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none); the CI guard reads anything else as not opted in, so docs-only changes run the full suite` });
|
|
200
|
+
if (!Array.isArray(v)) return bad(`is ${JSON.stringify(v)}`);
|
|
201
|
+
const exclude = [];
|
|
202
|
+
for (const m of v) {
|
|
203
|
+
const s = typeof m === 'string' ? m.replace(/\/+$/, '') : null;
|
|
204
|
+
if (!s || !/^[A-Za-z0-9._/-]+$/.test(s) || s.startsWith('/') || s.split('/').some((x) => x === '..' || x === '.' || x === '')) {
|
|
205
|
+
return bad(`lists ${JSON.stringify(m)}, which is not a plain repo path`);
|
|
206
|
+
}
|
|
207
|
+
exclude.push(s);
|
|
208
|
+
}
|
|
209
|
+
return { declared: true, valid: true, on: true, exclude,
|
|
210
|
+
reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — a docs-only change skips the CI suite' };
|
|
211
|
+
}
|
|
212
|
+
|
|
167
213
|
module.exports = {
|
|
168
214
|
DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
|
|
169
215
|
pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
|
|
216
|
+
CI_DOCS_SKIP_KEY, parseCiDocsSkip,
|
|
170
217
|
};
|