@futurelastic/colab-handbook 1.13.0 → 1.14.0-rc.2

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.
Files changed (37) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +101 -11
  4. package/package.json +1 -1
  5. package/templates/README.md +18 -3
  6. package/templates/ci-laravel.yml +360 -40
  7. package/templates/ci-node.yml +491 -35
  8. package/templates/ci-python.yml +301 -32
  9. package/templates/deploy-container-run.mjs +17 -3
  10. package/templates/deploy-xserver.yml +12 -0
  11. package/templates/instruction-files.yml +16 -0
  12. package/templates/pre-commit-instruction-files +55 -0
  13. package/tools/colab +750 -67
  14. package/tools/lib/batch-stats.js +66 -43
  15. package/tools/lib/claim-comments.js +3 -2
  16. package/tools/lib/codec/decision.d.ts +7 -0
  17. package/tools/lib/codec/decision.js +54 -0
  18. package/tools/lib/codec/hold.d.ts +8 -1
  19. package/tools/lib/codec/hold.js +42 -8
  20. package/tools/lib/codec/release.js +6 -3
  21. package/tools/lib/codec/samples.json +45 -0
  22. package/tools/lib/config-set.js +4 -3
  23. package/tools/lib/decision-record.js +42 -0
  24. package/tools/lib/docs-only.js +47 -0
  25. package/tools/lib/git.js +57 -8
  26. package/tools/lib/instruction-file.js +49 -0
  27. package/tools/lib/instruction-gate.js +150 -0
  28. package/tools/lib/landed-prs.js +58 -0
  29. package/tools/lib/migration-grant.js +29 -5
  30. package/tools/lib/owner-policy.js +133 -0
  31. package/tools/lib/release-finalize.js +66 -5
  32. package/tools/lib/ship-batch.js +188 -14
  33. package/tools/lib/ship-handoff.js +174 -0
  34. package/tools/lib/stamp.js +6 -2
  35. package/tools/lib/template-trunk.js +80 -0
  36. package/tools/lib/tree-green.js +21 -4
  37. package/tools/lib/workflow-triggers.js +57 -0
@@ -67,31 +67,50 @@ 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
- # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
72
- # trunk, main the release; Tier B: main only).
73
- branches: [main, dev]
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"), so also delete the fork-PR term
77
+ # (`github.event_name != 'pull_request' || …`) from every job's `if:` below, or it skips that run.
78
+ # EDIT: fork PRs (#514). A push to a fork never runs a workflow here, so a repo that takes
79
+ # PRs from forks needs `pull_request`. Uncomment it there. Every suite job below already
80
+ # carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
81
+ # event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
82
+ # fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
83
+ # (CONVENTIONS.md §4, "Branch CI"). Check every reader of your CI agrees before you uncomment.
84
+ # pull_request:
85
+ # branches: ['**']
74
86
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
75
87
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
76
88
  workflow_dispatch:
77
89
 
78
90
  # One live run per branch: a new push cancels the superseded run on the same ref.
79
91
  # 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"). Pull-request runs
81
- # group under refs/pull/<n>/merge, apart from the branch's push runs.
82
- # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
83
- # may carry any name; one left off this list gets its trunk runs cancelled.
92
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
93
+ # group of its own (the run id): GitHub cancels an older run that is still PENDING in a
94
+ # group even when cancel-in-progress is false, so a third quick merge would otherwise
95
+ # drop the second one's run before it ever started (#512).
96
+ # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
97
+ # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
98
+ # name; one left off this list gets its trunk runs cancelled. `colab template` writes these
99
+ # from the `trunk:` in .github/project.yml and prints what it wrote (#526).
84
100
  concurrency:
85
- group: ci-${{ github.ref }}
101
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
86
102
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
87
103
 
88
104
  env:
89
- # Light CI on the dev trunk (does it build at all, ~2 min); heavy CI on main, where
90
- # the Pest suite gates a release. On Tier C main IS production — promotion is the
91
- # deploy — so this suite is the last gate before users, not a release formality.
92
- # EDIT: set to a literal 'true' if this repo is Tier B (main is trunk) and you
93
- # always want the suite.
94
- RUN_TESTS: ${{ github.ref == 'refs/heads/main' || github.base_ref == 'main' }}
105
+ # Whether the Pest suite runs. 'auto' is decided by the "Decide the test tier" step in
106
+ # `build` (#512). Light CI on a dev trunk and its branches (does it build at all,
107
+ # ~2 min); heavy CI on main, where the Pest suite gates a release. On Tier C main IS
108
+ # production — promotion is the deploy — so this suite is the last gate before users,
109
+ # not a release formality. When main is the trunk (Tier B) every branch push runs the
110
+ # suite too: this workflow has no `pull_request` run any more, and that run used to be
111
+ # the only place a Tier B branch got its tests.
112
+ # EDIT: set to a literal 'true' to always run the suite, 'false' to never run it.
113
+ RUN_TESTS: auto
95
114
  # EDIT: bump deliberately, not automatically.
96
115
  GITLEAKS_VERSION: "8.30.1"
97
116
  # EDIT: match the app's APP_NAME. Leave empty if the build does not read it.
@@ -133,17 +152,35 @@ jobs:
133
152
  # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
134
153
  # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
135
154
  # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
136
- # Never put a trunk-only job (publish, deploy, release) behind this gate.
155
+ # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
156
+ # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
157
+ # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
158
+ # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
159
+ # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
160
+ #
161
+ # Only documentation changed? (#570) — opt-in, `ci-docs-skip:` in .github/project.yml.
162
+ # When the two modes above find nothing, a repo that declared `ci-docs-skip` at THIS sha
163
+ # asks a third question: is every path changed since the base documentation, by the rule
164
+ # `colab ship` applies (CONVENTIONS.md §2, the docs-only exception: .md/.mdx/.txt or under
165
+ # docs/, never agent rules, config, a build input like requirements*.txt, a symlink, a
166
+ # submodule or a binary), and does the base
167
+ # have a green run of this workflow? The base is the merge base with trunk on a ref-creating
168
+ # push, and the previous tip on a push to trunk. Yes → the suite is skipped and the run
169
+ # leaves a `docs-only-skip` notice naming the base and its green run. A path the suite reads
170
+ # (docs/api/ feeding a generator) is listed in `ci-docs-skip` and always runs the suite. Any
171
+ # doubt (no opt-in, a red or unrun base, an API or fetch failure) runs the full suite. A run
172
+ # skipped this way is never cited as tree-reuse proof: it skipped every job (#511).
137
173
  dedupe:
138
174
  name: Already tested at this sha or tree?
139
175
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
140
176
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
141
177
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
178
+ timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
142
179
  permissions:
143
180
  actions: read
144
181
  contents: read
145
182
  outputs:
146
- tested: ${{ steps.check.outputs.tested }}
183
+ tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
147
184
  cited: ${{ steps.check.outputs.cited }}
148
185
  steps:
149
186
  - name: Look for a green run of this workflow at this sha or tree
@@ -155,9 +192,58 @@ jobs:
155
192
  SHA: ${{ github.sha }}
156
193
  CREATED: ${{ github.event.created }}
157
194
  REF_NAME: ${{ github.ref_name }}
195
+ GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
158
196
  run: |
159
197
  tested=false
160
198
  cited=
199
+ # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
200
+ # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
201
+ # run, so citing that run would skip the trunk-only job on trunk a second time.
202
+ reusable() {
203
+ if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
204
+ --jq 'if .total_count > (.jobs | length) then "(more than 100 jobs)" else [.jobs[] | select(.conclusion == "skipped" and .name != env.GUARD_NAME) | .name] | join(", ") end' 2>/dev/null)"; then
205
+ echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
206
+ return 1
207
+ elif [ -n "$SK" ]; then
208
+ echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
209
+ return 1
210
+ fi
211
+ }
212
+ # The candidate runs, one per line as "<id> <head sha> <url> <branch>", newest first: green
213
+ # push runs of this workflow on another ref of this repo. #552: those at THIS sha first (a
214
+ # `ship-batch/*` run trunk fast-forwarded to), an exact query; then those whose commit has
215
+ # THIS tree (#493). The query's own per_page bounds the walk (#592).
216
+ same_sha() {
217
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
218
+ --jq ".workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\"" 2>/dev/null
219
+ }
220
+ same_tree() {
221
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
222
+ --jq ".workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.id) \\(.head_sha) \\(.html_url) \\(.head_branch)\"" 2>/dev/null
223
+ }
224
+ # #592: cite the newest candidate on stdin that passes every check. One that fails a check
225
+ # is passed over, not the end of the search: the newest green run can be a skip-chained one
226
+ # (#511) while an older run at the same sha or tree ran every job. A run already tried (the
227
+ # sha query's runs reappear in the tree listing) is not tried twice.
228
+ cite() {
229
+ local CID CSHA URL BR CTREE
230
+ while read -r CID CSHA URL BR; do
231
+ [ -n "$CID" ] || continue
232
+ case " $TRIED " in *" $CID "*) continue ;; esac
233
+ TRIED="$TRIED $CID"
234
+ if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
235
+ echo "::notice::Could not confirm the tree of $CSHA — passing over run $CID (#493)."
236
+ elif reusable "$CID"; then
237
+ tested=true
238
+ cited="$URL"
239
+ echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
240
+ echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
241
+ echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
242
+ return 0
243
+ fi
244
+ done
245
+ return 1
246
+ }
161
247
  if ! command -v gh >/dev/null 2>&1; then
162
248
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
163
249
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
@@ -172,21 +258,17 @@ jobs:
172
258
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
173
259
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
174
260
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
175
- elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
176
- --jq "first(.workflow_runs[] | select(.id != $RUN_ID and .head_branch != \"$REF_NAME\" and .head_repository.full_name == \"$REPO\" and .head_commit.tree_id == \"$OURS\") | \"\\(.head_sha) \\(.html_url) \\(.head_branch)\") // empty" 2>/dev/null)"; then
177
- echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
178
- elif [ -z "$CAND" ]; then
179
- echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
180
261
  else
181
- read -r CSHA URL BR <<< "$CAND"
182
- if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
183
- echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
184
- else
185
- tested=true
186
- cited="$URL"
187
- echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
188
- echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
189
- echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
262
+ TRIED=
263
+ SC="$(same_sha)" || SC= # the sha query failing falls through to the tree listing (#552)
264
+ if [ -n "$SC" ] && cite <<< "$SC"; then
265
+ :
266
+ elif ! TC="$(same_tree)"; then
267
+ echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
268
+ elif [ -z "$SC$TC" ]; then
269
+ echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
270
+ elif ! cite <<< "$TC"; then
271
+ echo "No green run of this workflow at sha $SHA or tree $OURS can be cited — running the full suite (#592)."
190
272
  fi
191
273
  fi
192
274
  elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
@@ -201,12 +283,167 @@ jobs:
201
283
  fi
202
284
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
203
285
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
286
+ # Docs-only (#570) — the two steps below run only when the step above found nothing.
287
+ - name: Find the base a docs-only change would rely on
288
+ id: docs_base
289
+ if: steps.check.outputs.tested != 'true'
290
+ env:
291
+ GH_TOKEN: ${{ github.token }}
292
+ REPO: ${{ github.repository }}
293
+ RUN_ID: ${{ github.run_id }}
294
+ SHA: ${{ github.sha }}
295
+ BEFORE: ${{ github.event.before }}
296
+ CREATED: ${{ github.event.created }}
297
+ REF: ${{ github.ref }}
298
+ REF_NAME: ${{ github.ref_name }}
299
+ run: |
300
+ base=
301
+ # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
302
+ # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
303
+ optin() {
304
+ local v items
305
+ v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
306
+ if [ -z "$v" ]; then
307
+ items="$(printf '%s\n' "$DESC" | awk '/^ci-docs-skip[[:space:]]*:/{f=1;next} f&&/^[[:space:]]+-/{sub(/^[[:space:]]+-[[:space:]]*/,"");sub(/[[:space:]]+#.*$/,"");print;next} f&&/^[[:space:]]*(#.*)?$/{next} {f=0}')"
308
+ [ -n "$items" ] || return 1
309
+ elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
310
+ v="${v#[}"; v="${v%]}"
311
+ items="$(printf '%s' "$v" | tr ',' '\n')"
312
+ else
313
+ return 1
314
+ fi
315
+ EXCLUDE=
316
+ while IFS= read -r it; do
317
+ it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
318
+ [ -n "$it" ] || continue
319
+ case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
320
+ printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
321
+ EXCLUDE="$EXCLUDE ${it%/}"
322
+ done <<< "$items"
323
+ }
324
+ if ! command -v gh >/dev/null 2>&1; then
325
+ echo "gh is not installed on this runner — docs-only mode is off (#570)."
326
+ elif [ "${REF#refs/heads/}" = "$REF" ]; then
327
+ echo "$REF is not a branch — docs-only mode is off (#570)."
328
+ elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
329
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
330
+ elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
331
+ echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
332
+ elif ! optin; then
333
+ echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
334
+ else
335
+ TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
336
+ if [ -z "$TRUNK" ]; then
337
+ echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
338
+ elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
339
+ # A new branch: the change is everything since it left trunk (the diff the squash lands).
340
+ base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
341
+ [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
342
+ elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
343
+ base="$BEFORE" # a push to trunk: the change is what this push added
344
+ else
345
+ echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
346
+ fi
347
+ # The base must itself be green: a docs-only change cannot make a red suite green. The base
348
+ # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
349
+ # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
350
+ # skipped on the branch, #511). Still running, red, or none: the full suite.
351
+ if [ -n "$base" ]; then
352
+ if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
353
+ || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
354
+ --jq "[.workflow_runs[] | select(.id != $RUN_ID and .head_branch == \"$TRUNK\" and .head_repository.full_name == \"$REPO\")] | sort_by(.created_at) | last | if . != null and .status == \"completed\" and .conclusion == \"success\" then .html_url else empty end" 2>/dev/null)"; then
355
+ echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
356
+ base=
357
+ elif [ -z "$URL" ]; then
358
+ echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
359
+ base=
360
+ fi
361
+ fi
362
+ fi
363
+ if [ -n "$base" ]; then
364
+ echo "base=$base" >> "$GITHUB_OUTPUT"
365
+ echo "base_run=$URL" >> "$GITHUB_OUTPUT"
366
+ echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
367
+ fi
368
+ - name: Is every changed path documentation?
369
+ id: docs
370
+ if: steps.docs_base.outputs.base != ''
371
+ env:
372
+ GH_TOKEN: ${{ github.token }}
373
+ SERVER_URL: ${{ github.server_url }}
374
+ REPO: ${{ github.repository }}
375
+ SHA: ${{ github.sha }}
376
+ BASE: ${{ steps.docs_base.outputs.base }}
377
+ BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
378
+ EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
379
+ run: |
380
+ tested=false
381
+ # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
382
+ # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
383
+ # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
384
+ reason() {
385
+ local p="$1" base dir x
386
+ base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
387
+ case "$p" in \"*) echo "quoted path"; return ;; esac
388
+ for x in $EXCLUDE; do
389
+ case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
390
+ done
391
+ case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
392
+ # A build input despite the extension: the cure rule's Python manifest (any case), a pip
393
+ # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
394
+ lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
395
+ case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
396
+ case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
397
+ [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
398
+ case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
399
+ case "$p" in docs/*) return ;; esac
400
+ case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
401
+ echo "not .md/.mdx/.txt and not under docs/"
402
+ }
403
+ # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
404
+ G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
405
+ AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
406
+ if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
407
+ && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
408
+ && git -C "$G" config http.extraheader "$AUTH" \
409
+ && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
410
+ echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
411
+ elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
412
+ || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
413
+ echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
414
+ elif [ -z "$RAW" ]; then
415
+ echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
416
+ else
417
+ bad=; n=0
418
+ while IFS= read -r line; do
419
+ meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
420
+ why="$(reason "$p")"
421
+ set -- $meta
422
+ case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
423
+ case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
424
+ [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
425
+ done <<< "$RAW"
426
+ while IFS=$'\t' read -r a d p; do
427
+ if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
428
+ done <<< "$NUM"
429
+ if [ -n "$bad" ]; then
430
+ echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
431
+ else
432
+ tested=true
433
+ echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
434
+ echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
435
+ echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
436
+ fi
437
+ fi
438
+ rm -rf "$G"
439
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
204
440
 
205
441
  gitleaks:
206
442
  name: Secret scan (gitleaks)
207
443
  needs: dedupe
208
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
444
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
209
445
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
446
+ timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
210
447
  steps:
211
448
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
212
449
  with:
@@ -246,8 +483,11 @@ jobs:
246
483
  build:
247
484
  name: Build (Laravel + Vite)
248
485
  needs: dedupe
249
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
486
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
250
487
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
488
+ timeout-minutes: 45 # a hung build must not hold the runner for the 360-minute default (#572).
489
+ # EDIT: measured (#572): the slowest Laravel adopter's build ran p99 20 / max 26 min. Keep this
490
+ # well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
251
491
  # Re-exported so the migrations job below resolves PHP exactly once, here.
252
492
  outputs:
253
493
  php-version: ${{ steps.toolchain.outputs.php-version }}
@@ -256,15 +496,48 @@ jobs:
256
496
  with:
257
497
  persist-credentials: false
258
498
 
499
+ # Decide the test tier (#512). Not an `env:` expression, because the answer depends on
500
+ # the repo's trunk (.github/project.yml), which only exists once the tree is checked out.
501
+ # RUN_TESTS 'true' / 'false' → used as written.
502
+ # 'auto', a pull_request run → on when the PR targets main (copies that restore PRs).
503
+ # 'auto', push or dispatch → on for main, and for every branch when trunk is main
504
+ # (Tier B); off for a dev trunk and its branches (Tier C).
505
+ - name: Decide the test tier
506
+ id: tier
507
+ env:
508
+ DECLARED: ${{ env.RUN_TESTS }}
509
+ EVENT: ${{ github.event_name }}
510
+ REF: ${{ github.ref }}
511
+ BASE_REF: ${{ github.base_ref }}
512
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
513
+ run: |
514
+ case "$DECLARED" in
515
+ true|false) run="$DECLARED" ;;
516
+ *)
517
+ trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
518
+ [ -n "$trunk" ] || trunk="$DEFAULT_BRANCH"
519
+ if [ "$EVENT" = "pull_request" ]; then
520
+ [ "$BASE_REF" = "main" ] && run=true || run=false
521
+ elif [ "$REF" = "refs/heads/main" ] || [ "$trunk" = "main" ]; then
522
+ run=true
523
+ else
524
+ run=false
525
+ fi ;;
526
+ esac
527
+ echo "run_tests=$run" >> "$GITHUB_OUTPUT"
528
+ echo "::notice::Pest suite: $run (RUN_TESTS=$DECLARED, event=$EVENT, ref=$REF)"
529
+
259
530
  # ---------------------------------------------------------------------------
260
531
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
261
- # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
532
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
262
533
  # once turned every landing in a busy repo back to serial while this CI stayed
263
534
  # green; only a ship dry run noticed. So the value fails HERE, where the person
264
535
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
265
- # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
266
- # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
536
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
537
+ # cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
267
538
  # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
539
+ # `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
540
+ # whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
268
541
  # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
269
542
  # ---------------------------------------------------------------------------
270
543
  - name: Descriptor check (.github/project.yml)
@@ -280,11 +553,26 @@ jobs:
280
553
  }
281
554
  v="$(field ship-batch)"
282
555
  case "$v" in
283
- ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
556
+ ''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
284
557
  *)
285
- echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
558
+ echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-8 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 8: project.schema.md, ship-batch."
286
559
  exit 1 ;;
287
560
  esac
561
+ # ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
562
+ s="$(field ship-batch-steps)"
563
+ case "$s" in
564
+ ''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
565
+ *)
566
+ case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
567
+ list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
568
+ if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
569
+ && printf '%s\n' "$list" | tr ',' '\n' | awk -v n="$ceil" '{ if ($1 + 0 <= p || $1 + 0 > n + 0) bad = 1; p = $1 + 0 } END { exit bad }'; then
570
+ echo "ship-batch-steps: $list — ok"
571
+ else
572
+ echo "::error file=.github/project.yml::ship-batch-steps is '$s', expected strictly ascending whole numbers within ship-batch ($ceil), like 2,4,8 (omit for a fixed size). colab ship ignores any other value and uses the fixed size. See project.schema.md, ship-batch-steps."
573
+ exit 1
574
+ fi ;;
575
+ esac
288
576
  # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
289
577
  w="$(field ship-batch-wait)"
290
578
  case "$w" in
@@ -463,7 +751,31 @@ jobs:
463
751
  extensions: mbstring, sqlite3, pdo_sqlite, bcmath, intl # EDIT: add what this app needs.
464
752
  coverage: none
465
753
 
754
+ # Package cache (#571): Composer's download cache, on only on a GitHub-hosted runner AND
755
+ # with composer.lock present. Both halves are load-bearing:
756
+ # - No composer.lock → nothing stable to key on; every run would save a fresh entry.
757
+ # - Self-hosted → off. A persistent runner already keeps Composer's cache dir between
758
+ # jobs; a remote cache on top was measured as a loss, not a saving (#512).
759
+ # Two NEW steps, both skipped where the gate is off. "Composer install" keeps its name
760
+ # and its body: `colab ship`'s cure rule matches steps by exact name.
761
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, delete these
762
+ # two steps.
763
+ - name: Locate Composer cache
764
+ id: composer-cache
765
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
766
+ run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
767
+
768
+ - name: Restore Composer cache
769
+ if: runner.environment == 'github-hosted' && hashFiles('composer.lock') != ''
770
+ uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
771
+ with:
772
+ path: ${{ steps.composer-cache.outputs.dir }}
773
+ key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
774
+ restore-keys: composer-${{ runner.os }}-
775
+
466
776
  - name: Composer install
777
+ env:
778
+ RUN_TESTS: ${{ steps.tier.outputs.run_tests }}
467
779
  run: |
468
780
  # --no-scripts: the post-autoload-dump hook runs `package:discover`, which
469
781
  # boots the app — and the app cannot boot until the .env below exists.
@@ -495,9 +807,15 @@ jobs:
495
807
  # stderr and reports only "Command failed".
496
808
  php artisan wayfinder:generate $WAYFINDER_ARGS
497
809
 
810
+ # npm cache (#571): the same gate as the Composer cache above — GitHub-hosted AND
811
+ # package-lock.json present (`cache: npm` fails the step without one). The automatic
812
+ # `packageManager` cache is pinned to the same condition so it cannot override it.
813
+ # EDIT: to turn it off everywhere, replace both expressions with '' and false.
498
814
  - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
499
815
  with:
500
816
  node-version: ${{ steps.toolchain.outputs.node-version }}
817
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
818
+ package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
501
819
 
502
820
  - name: Build frontend assets (Vite)
503
821
  run: |
@@ -505,14 +823,14 @@ jobs:
505
823
  npm run build
506
824
 
507
825
  - name: Run migrations against sqlite
508
- if: env.RUN_TESTS == 'true'
826
+ if: steps.tier.outputs.run_tests == 'true'
509
827
  run: |
510
828
  # Migrations must apply cleanly from zero. This is the cheapest way to catch
511
829
  # a migration that only works against an already-populated database.
512
830
  php artisan migrate --force
513
831
 
514
832
  - name: Test (Pest)
515
- if: env.RUN_TESTS == 'true'
833
+ if: steps.tier.outputs.run_tests == 'true'
516
834
  run: |
517
835
  if [ -f vendor/bin/pest ]; then
518
836
  vendor/bin/pest --ci
@@ -555,6 +873,8 @@ jobs:
555
873
  # form would skip this job on exactly the runs it exists for (#418).
556
874
  if: ${{ !cancelled() && needs.build.result == 'success' }}
557
875
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
876
+ timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
877
+ # EDIT: measured (#572): p99 under 4 min / max 5 min on every adopter. Keep it well above your own p99.
558
878
  strategy:
559
879
  fail-fast: false
560
880
  matrix: