@futurelastic/colab-handbook 1.13.0-rc.33 → 1.13.0-rc.35
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/templates/ci-laravel.yml +14 -0
- package/templates/ci-node.yml +15 -1
- package/templates/ci-python.yml +15 -1
- package/tools/lib/codec/hold.d.ts +8 -1
- package/tools/lib/codec/hold.js +42 -8
- package/tools/lib/codec/samples.json +33 -0
package/package.json
CHANGED
package/templates/ci-laravel.yml
CHANGED
|
@@ -265,6 +265,7 @@ jobs:
|
|
|
265
265
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
266
266
|
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
267
267
|
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
268
|
+
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
268
269
|
# ---------------------------------------------------------------------------
|
|
269
270
|
- name: Descriptor check (.github/project.yml)
|
|
270
271
|
working-directory: ${{ github.workspace }}
|
|
@@ -296,6 +297,19 @@ jobs:
|
|
|
296
297
|
exit 1
|
|
297
298
|
fi ;;
|
|
298
299
|
esac
|
|
300
|
+
# ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
|
|
301
|
+
# Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
|
|
302
|
+
f="$(field ci-wait-factor)"
|
|
303
|
+
case "$f" in
|
|
304
|
+
''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
|
|
305
|
+
*)
|
|
306
|
+
if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
|
|
307
|
+
echo "ci-wait-factor: $f — ok"
|
|
308
|
+
else
|
|
309
|
+
echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
|
|
310
|
+
exit 1
|
|
311
|
+
fi ;;
|
|
312
|
+
esac
|
|
299
313
|
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
300
314
|
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
301
315
|
# which a test holds this list to.
|
package/templates/ci-node.yml
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
#
|
|
15
15
|
# What it does:
|
|
16
16
|
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
|
|
17
|
-
# ship-batch-wait, #555).
|
|
17
|
+
# ship-batch-wait, #555; ci-wait-factor, #564).
|
|
18
18
|
# 1. Resolve the Node version from declared sources — never a hardcoded default.
|
|
19
19
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
20
20
|
# 3. Install dependencies with the package manager the lockfile implies.
|
|
@@ -260,6 +260,7 @@ jobs:
|
|
|
260
260
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
261
261
|
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
262
262
|
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
263
|
+
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
263
264
|
# ---------------------------------------------------------------------------
|
|
264
265
|
- name: Descriptor check (.github/project.yml)
|
|
265
266
|
working-directory: ${{ github.workspace }}
|
|
@@ -291,6 +292,19 @@ jobs:
|
|
|
291
292
|
exit 1
|
|
292
293
|
fi ;;
|
|
293
294
|
esac
|
|
295
|
+
# ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
|
|
296
|
+
# Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
|
|
297
|
+
f="$(field ci-wait-factor)"
|
|
298
|
+
case "$f" in
|
|
299
|
+
''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
|
|
300
|
+
*)
|
|
301
|
+
if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
|
|
302
|
+
echo "ci-wait-factor: $f — ok"
|
|
303
|
+
else
|
|
304
|
+
echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
|
|
305
|
+
exit 1
|
|
306
|
+
fi ;;
|
|
307
|
+
esac
|
|
294
308
|
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
295
309
|
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
296
310
|
# which a test holds this list to.
|
package/templates/ci-python.yml
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
#
|
|
29
29
|
# What it does:
|
|
30
30
|
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416;
|
|
31
|
-
# ship-batch-wait, #555).
|
|
31
|
+
# ship-batch-wait, #555; ci-wait-factor, #564).
|
|
32
32
|
# 1. Resolve the Python version from declared sources — never a hardcoded default.
|
|
33
33
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
34
34
|
# 3. Install dependencies from whichever manifest the repo actually has.
|
|
@@ -251,6 +251,7 @@ jobs:
|
|
|
251
251
|
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
252
252
|
# cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
|
|
253
253
|
# (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
|
|
254
|
+
# `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
|
|
254
255
|
# ---------------------------------------------------------------------------
|
|
255
256
|
- name: Descriptor check (.github/project.yml)
|
|
256
257
|
working-directory: ${{ github.workspace }}
|
|
@@ -282,6 +283,19 @@ jobs:
|
|
|
282
283
|
exit 1
|
|
283
284
|
fi ;;
|
|
284
285
|
esac
|
|
286
|
+
# ci-wait-factor (#559): a number >= 1 — a multiple of the repo's measured CI duration. No ceiling.
|
|
287
|
+
# Same reading as tools/lib/ci-profile.js parseFactor on the raw scalar the audit hands it.
|
|
288
|
+
f="$(field ci-wait-factor)"
|
|
289
|
+
case "$f" in
|
|
290
|
+
''|'~'|null) echo "ci-wait-factor: absent — ok (default 2)" ;;
|
|
291
|
+
*)
|
|
292
|
+
if printf '%s\n' "$f" | grep -Eq '^[0-9]+(\.[0-9]+)?$' && awk -v n="$f" 'BEGIN { exit !(n + 0 >= 1) }'; then
|
|
293
|
+
echo "ci-wait-factor: $f — ok"
|
|
294
|
+
else
|
|
295
|
+
echo "::error file=.github/project.yml::ci-wait-factor is '$f', expected a number >= 1 (a multiple of the measured CI duration; omit for 2). colab ship and colab ci-wait ignore any other value and use 2. See project.schema.md, ci-wait-factor."
|
|
296
|
+
exit 1
|
|
297
|
+
fi ;;
|
|
298
|
+
esac
|
|
285
299
|
# thresholds (#560): one level of `name: whole number`, each name known and at or above its
|
|
286
300
|
# floor (and, for a percent, at most 100) — the table in tools/lib/thresholds.js (SPEC),
|
|
287
301
|
# which a test holds this list to.
|
|
@@ -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
|
};
|
|
@@ -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": [
|