@futurelastic/colab-handbook 1.13.0-rc.34 → 1.13.0-rc.36
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/README.md +14 -2
- package/templates/ci-laravel.yml +61 -17
- package/templates/ci-node.yml +17 -9
- package/templates/ci-python.yml +17 -9
- 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/README.md
CHANGED
|
@@ -67,8 +67,11 @@ notice back and print the run they relied on. Three things to keep in a copy:
|
|
|
67
67
|
|
|
68
68
|
- **It needs `contents: read`** on top of `actions: read`, to read the descriptor and the
|
|
69
69
|
commit objects.
|
|
70
|
-
- **The trunk refs in its `if:` mirror `concurrency`'s list.**
|
|
71
|
-
|
|
70
|
+
- **The trunk refs in its `if:` mirror `concurrency`'s list.** The list appears three times in a
|
|
71
|
+
copy: the `group:`, `cancel-in-progress:`, and this `if:` (#512 gave the trunk its own
|
|
72
|
+
per-run group, so a pending trunk run is never replaced). On a repo whose trunk has another
|
|
73
|
+
name, edit all three. Until you do, the guard simply never fires on trunk — nothing breaks;
|
|
74
|
+
but a trunk left out of `group:` and `cancel-in-progress:` has its runs cancelled.
|
|
72
75
|
- **Never put a trunk-only job behind it.** Publish, deploy and release jobs must run whatever
|
|
73
76
|
the guard says. Give them their own `if:` that does not read `needs.dedupe`.
|
|
74
77
|
|
|
@@ -302,3 +305,12 @@ runner is infrastructure, not a throwaway VM.
|
|
|
302
305
|
service context (`job.services.mysql.ports['3306']`), threading it through your
|
|
303
306
|
env. A fixed `3306:3306` works exactly until the first job lands on a runner
|
|
304
307
|
that already listens there.
|
|
308
|
+
|
|
309
|
+
### One run per commit — why the CI templates have no `pull_request` trigger (#512)
|
|
310
|
+
|
|
311
|
+
The three `ci-*` templates trigger on `push: ['**']` and `workflow_dispatch`. A same-repo PR
|
|
312
|
+
commit gets the push run and nothing else; a `pull_request` trigger beside it ran the suite twice
|
|
313
|
+
and let the later run, which tests the merge ref, decide the verdict. Two edits belong to a copy:
|
|
314
|
+
a repo that goes back to trunk-only push restores `pull_request: branches: [<trunk>]`, and a repo
|
|
315
|
+
that accepts fork PRs keeps one (a fork's push never runs a workflow here). Detail:
|
|
316
|
+
`CONVENTIONS.md` §4, *Branch CI*.
|
package/templates/ci-laravel.yml
CHANGED
|
@@ -67,31 +67,40 @@ on:
|
|
|
67
67
|
# dev is the trunk, so a main-only trigger runs zero checks on the branch you
|
|
68
68
|
# merge into, and nothing looks broken (CONVENTIONS.md §7).
|
|
69
69
|
branches: ['**']
|
|
70
|
-
pull_request
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
70
|
+
# No `pull_request:` here (#512). A branch with an open PR in this repository already
|
|
71
|
+
# has a push run at the same head, and a `pull_request` run beside it doubled the CI
|
|
72
|
+
# per commit while testing a merge ref instead of the sha that lands. Readers keep only
|
|
73
|
+
# the newest run per workflow at a sha, so that second run also decided the verdict.
|
|
74
|
+
# EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
|
|
75
|
+
# has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
|
|
76
|
+
# only branch run (CONVENTIONS.md §4, "Branch CI").
|
|
74
77
|
# A promotion pushed by the release workflow's token triggers no push run, so that workflow
|
|
75
78
|
# dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
|
|
76
79
|
workflow_dispatch:
|
|
77
80
|
|
|
78
81
|
# One live run per branch: a new push cancels the superseded run on the same ref.
|
|
79
82
|
# Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
|
|
80
|
-
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI").
|
|
81
|
-
# group
|
|
82
|
-
#
|
|
83
|
-
#
|
|
83
|
+
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
|
|
84
|
+
# group of its own (the run id): GitHub cancels an older run that is still PENDING in a
|
|
85
|
+
# group even when cancel-in-progress is false, so a third quick merge would otherwise
|
|
86
|
+
# drop the second one's run before it ever started (#512).
|
|
87
|
+
# EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
|
|
88
|
+
# cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
|
|
89
|
+
# name; one left off this list gets its trunk runs cancelled.
|
|
84
90
|
concurrency:
|
|
85
|
-
group: ci-${{ github.ref }}
|
|
91
|
+
group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
|
|
86
92
|
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
87
93
|
|
|
88
94
|
env:
|
|
89
|
-
#
|
|
90
|
-
#
|
|
91
|
-
#
|
|
92
|
-
#
|
|
93
|
-
#
|
|
94
|
-
|
|
95
|
+
# Whether the Pest suite runs. 'auto' is decided by the "Decide the test tier" step in
|
|
96
|
+
# `build` (#512). Light CI on a dev trunk and its branches (does it build at all,
|
|
97
|
+
# ~2 min); heavy CI on main, where the Pest suite gates a release. On Tier C main IS
|
|
98
|
+
# production — promotion is the deploy — so this suite is the last gate before users,
|
|
99
|
+
# not a release formality. When main is the trunk (Tier B) every branch push runs the
|
|
100
|
+
# suite too: this workflow has no `pull_request` run any more, and that run used to be
|
|
101
|
+
# the only place a Tier B branch got its tests.
|
|
102
|
+
# EDIT: set to a literal 'true' to always run the suite, 'false' to never run it.
|
|
103
|
+
RUN_TESTS: auto
|
|
95
104
|
# EDIT: bump deliberately, not automatically.
|
|
96
105
|
GITLEAKS_VERSION: "8.30.1"
|
|
97
106
|
# EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
|
|
@@ -139,6 +148,7 @@ jobs:
|
|
|
139
148
|
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
140
149
|
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
141
150
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
151
|
+
timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
|
|
142
152
|
permissions:
|
|
143
153
|
actions: read
|
|
144
154
|
contents: read
|
|
@@ -207,6 +217,7 @@ jobs:
|
|
|
207
217
|
needs: dedupe
|
|
208
218
|
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
209
219
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
220
|
+
timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
|
|
210
221
|
steps:
|
|
211
222
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
212
223
|
with:
|
|
@@ -256,6 +267,37 @@ jobs:
|
|
|
256
267
|
with:
|
|
257
268
|
persist-credentials: false
|
|
258
269
|
|
|
270
|
+
# Decide the test tier (#512). Not an `env:` expression, because the answer depends on
|
|
271
|
+
# the repo's trunk (.github/project.yml), which only exists once the tree is checked out.
|
|
272
|
+
# RUN_TESTS 'true' / 'false' → used as written.
|
|
273
|
+
# 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
|
|
274
|
+
# 'auto', push or dispatch → on for main, and for every branch when trunk is main
|
|
275
|
+
# (Tier B); off for a dev trunk and its branches (Tier C).
|
|
276
|
+
- name: Decide the test tier
|
|
277
|
+
id: tier
|
|
278
|
+
env:
|
|
279
|
+
DECLARED: ${{ env.RUN_TESTS }}
|
|
280
|
+
EVENT: ${{ github.event_name }}
|
|
281
|
+
REF: ${{ github.ref }}
|
|
282
|
+
BASE_REF: ${{ github.base_ref }}
|
|
283
|
+
DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
|
|
284
|
+
run: |
|
|
285
|
+
case "$DECLARED" in
|
|
286
|
+
true|false) run="$DECLARED" ;;
|
|
287
|
+
*)
|
|
288
|
+
trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
|
|
289
|
+
[ -n "$trunk" ] || trunk="$DEFAULT_BRANCH"
|
|
290
|
+
if [ "$EVENT" = "pull_request" ]; then
|
|
291
|
+
[ "$BASE_REF" = "main" ] && run=true || run=false
|
|
292
|
+
elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
|
|
293
|
+
run=true
|
|
294
|
+
else
|
|
295
|
+
run=false
|
|
296
|
+
fi ;;
|
|
297
|
+
esac
|
|
298
|
+
echo "run_tests=$run" >> "$GITHUB_OUTPUT"
|
|
299
|
+
echo "::notice::Pest suite: $run (RUN_TESTS=$DECLARED, event=$EVENT, ref=$REF)"
|
|
300
|
+
|
|
259
301
|
# ---------------------------------------------------------------------------
|
|
260
302
|
# Descriptor check (#416). A value `colab ship` cannot use does not fail there —
|
|
261
303
|
# it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
|
|
@@ -464,6 +506,8 @@ jobs:
|
|
|
464
506
|
coverage: none
|
|
465
507
|
|
|
466
508
|
- name: Composer install
|
|
509
|
+
env:
|
|
510
|
+
RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
|
|
467
511
|
run: |
|
|
468
512
|
# --no-scripts: the post-autoload-dump hook runs `package:discover`, which
|
|
469
513
|
# boots the app — and the app cannot boot until the .env below exists.
|
|
@@ -505,14 +549,14 @@ jobs:
|
|
|
505
549
|
npm run build
|
|
506
550
|
|
|
507
551
|
- name: Run migrations against sqlite
|
|
508
|
-
if:
|
|
552
|
+
if: steps.tier.outputs.run_tests == 'true'
|
|
509
553
|
run: |
|
|
510
554
|
# Migrations must apply cleanly from zero. This is the cheapest way to catch
|
|
511
555
|
# a migration that only works against an already-populated database.
|
|
512
556
|
php artisan migrate --force
|
|
513
557
|
|
|
514
558
|
- name: Test (Pest)
|
|
515
|
-
if:
|
|
559
|
+
if: steps.tier.outputs.run_tests == 'true'
|
|
516
560
|
run: |
|
|
517
561
|
if [ -f vendor/bin/pest ]; then
|
|
518
562
|
vendor/bin/pest --ci
|
package/templates/ci-node.yml
CHANGED
|
@@ -41,22 +41,28 @@ on:
|
|
|
41
41
|
# dev is the trunk, so a main-only trigger runs zero checks on the branch you
|
|
42
42
|
# merge into, and nothing looks broken (CONVENTIONS.md §7).
|
|
43
43
|
branches: ['**']
|
|
44
|
-
pull_request
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
44
|
+
# No `pull_request:` here (#512). A branch with an open PR in this repository already
|
|
45
|
+
# has a push run at the same head, and a `pull_request` run beside it doubled the CI
|
|
46
|
+
# per commit while testing a merge ref instead of the sha that lands. Readers keep only
|
|
47
|
+
# the newest run per workflow at a sha, so that second run also decided the verdict.
|
|
48
|
+
# EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
|
|
49
|
+
# has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
|
|
50
|
+
# only branch run (CONVENTIONS.md §4, "Branch CI").
|
|
48
51
|
# A promotion pushed by the release workflow's token triggers no push run, so that workflow
|
|
49
52
|
# dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
|
|
50
53
|
workflow_dispatch:
|
|
51
54
|
|
|
52
55
|
# One live run per branch: a new push cancels the superseded run on the same ref.
|
|
53
56
|
# Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
|
|
54
|
-
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI").
|
|
55
|
-
# group
|
|
56
|
-
#
|
|
57
|
-
#
|
|
57
|
+
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
|
|
58
|
+
# group of its own (the run id): GitHub cancels an older run that is still PENDING in a
|
|
59
|
+
# group even when cancel-in-progress is false, so a third quick merge would otherwise
|
|
60
|
+
# drop the second one's run before it ever started (#512).
|
|
61
|
+
# EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
|
|
62
|
+
# cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
|
|
63
|
+
# name; one left off this list gets its trunk runs cancelled.
|
|
58
64
|
concurrency:
|
|
59
|
-
group: ci-${{ github.ref }}
|
|
65
|
+
group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
|
|
60
66
|
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
61
67
|
|
|
62
68
|
env:
|
|
@@ -105,6 +111,7 @@ jobs:
|
|
|
105
111
|
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
106
112
|
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
107
113
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
114
|
+
timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
|
|
108
115
|
permissions:
|
|
109
116
|
actions: read
|
|
110
117
|
contents: read
|
|
@@ -173,6 +180,7 @@ jobs:
|
|
|
173
180
|
needs: dedupe
|
|
174
181
|
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
175
182
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
183
|
+
timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
|
|
176
184
|
steps:
|
|
177
185
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
178
186
|
with:
|
package/templates/ci-python.yml
CHANGED
|
@@ -55,22 +55,28 @@ on:
|
|
|
55
55
|
# dev is the trunk, so a main-only trigger runs zero checks on the branch you
|
|
56
56
|
# merge into, and nothing looks broken (CONVENTIONS.md §7).
|
|
57
57
|
branches: ['**']
|
|
58
|
-
pull_request
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
58
|
+
# No `pull_request:` here (#512). A branch with an open PR in this repository already
|
|
59
|
+
# has a push run at the same head, and a `pull_request` run beside it doubled the CI
|
|
60
|
+
# per commit while testing a merge ref instead of the sha that lands. Readers keep only
|
|
61
|
+
# the newest run per workflow at a sha, so that second run also decided the verdict.
|
|
62
|
+
# EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
|
|
63
|
+
# has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
|
|
64
|
+
# only branch run (CONVENTIONS.md §4, "Branch CI").
|
|
62
65
|
# A promotion pushed by the release workflow's token triggers no push run, so that workflow
|
|
63
66
|
# dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
|
|
64
67
|
workflow_dispatch:
|
|
65
68
|
|
|
66
69
|
# One live run per branch: a new push cancels the superseded run on the same ref.
|
|
67
70
|
# Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
|
|
68
|
-
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI").
|
|
69
|
-
# group
|
|
70
|
-
#
|
|
71
|
-
#
|
|
71
|
+
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
|
|
72
|
+
# group of its own (the run id): GitHub cancels an older run that is still PENDING in a
|
|
73
|
+
# group even when cancel-in-progress is false, so a third quick merge would otherwise
|
|
74
|
+
# drop the second one's run before it ever started (#512).
|
|
75
|
+
# EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
|
|
76
|
+
# cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
|
|
77
|
+
# name; one left off this list gets its trunk runs cancelled.
|
|
72
78
|
concurrency:
|
|
73
|
-
group: ci-${{ github.ref }}
|
|
79
|
+
group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
|
|
74
80
|
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
75
81
|
|
|
76
82
|
env:
|
|
@@ -119,6 +125,7 @@ jobs:
|
|
|
119
125
|
# EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
|
|
120
126
|
if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
|
|
121
127
|
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
128
|
+
timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
|
|
122
129
|
permissions:
|
|
123
130
|
actions: read
|
|
124
131
|
contents: read
|
|
@@ -187,6 +194,7 @@ jobs:
|
|
|
187
194
|
needs: dedupe
|
|
188
195
|
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
189
196
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
197
|
+
timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
|
|
190
198
|
steps:
|
|
191
199
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
192
200
|
with:
|
|
@@ -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": [
|