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

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 (44) hide show
  1. package/README.md +2 -2
  2. package/README.vi.md +2 -2
  3. package/audit/audit.mjs +218 -53
  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/templates/release-auto.yml +16 -3
  14. package/tools/colab +884 -98
  15. package/tools/lib/adopt.js +1 -1
  16. package/tools/lib/audit-cache.js +277 -0
  17. package/tools/lib/batch-stats.js +66 -43
  18. package/tools/lib/ci-cure.js +10 -1
  19. package/tools/lib/claim-comments.js +3 -2
  20. package/tools/lib/codec/decision.d.ts +7 -0
  21. package/tools/lib/codec/decision.js +54 -0
  22. package/tools/lib/codec/hold.d.ts +8 -1
  23. package/tools/lib/codec/hold.js +42 -8
  24. package/tools/lib/codec/release.js +6 -3
  25. package/tools/lib/codec/samples.json +45 -0
  26. package/tools/lib/config-set.js +4 -3
  27. package/tools/lib/cure-diff.js +27 -1
  28. package/tools/lib/decision-record.js +42 -0
  29. package/tools/lib/docs-only.js +47 -0
  30. package/tools/lib/git.js +57 -8
  31. package/tools/lib/grant-policy.js +133 -0
  32. package/tools/lib/instruction-file.js +75 -0
  33. package/tools/lib/instruction-gate.js +179 -0
  34. package/tools/lib/landed-prs.js +58 -0
  35. package/tools/lib/migration-grant.js +29 -5
  36. package/tools/lib/owner-policy.js +110 -0
  37. package/tools/lib/release-cut.js +127 -10
  38. package/tools/lib/release-finalize.js +66 -5
  39. package/tools/lib/ship-batch.js +188 -14
  40. package/tools/lib/ship-handoff.js +212 -0
  41. package/tools/lib/stamp.js +6 -2
  42. package/tools/lib/template-trunk.js +80 -0
  43. package/tools/lib/tree-green.js +21 -4
  44. package/tools/lib/workflow-triggers.js +57 -0
@@ -20,7 +20,8 @@
20
20
  # 3. Install dependencies with the package manager the lockfile implies.
21
21
  # 4. Run typecheck / lint / test only if package.json declares those scripts, so a
22
22
  # repo without them is not forced to add placeholders to keep CI green.
23
- # 5. Build.
23
+ # 5. Build, if package.json declares the BUILD_COMMAND script.
24
+ # 6. Opt-in, commented: a Migration round-trip for `migration-grant: reviewer` (#494).
24
25
 
25
26
  name: CI
26
27
 
@@ -41,28 +42,45 @@ on:
41
42
  # dev is the trunk, so a main-only trigger runs zero checks on the branch you
42
43
  # merge into, and nothing looks broken (CONVENTIONS.md §7).
43
44
  branches: ['**']
44
- pull_request:
45
- # EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
46
- # trunk, main the release; Tier B: main only).
47
- branches: [main, dev]
45
+ # No `pull_request:` here (#512). A branch with an open PR in this repository already
46
+ # has a push run at the same head, and a `pull_request` run beside it doubled the CI
47
+ # per commit while testing a merge ref instead of the sha that lands. Readers keep only
48
+ # the newest run per workflow at a sha, so that second run also decided the verdict.
49
+ # EDIT: a copy that went back to trunk-only push (above) has no run on a branch until it
50
+ # has a PR — restore `pull_request: branches: [<trunk>]` there; that PR run is then its
51
+ # only branch run (CONVENTIONS.md §4, "Branch CI"), so also delete the fork-PR term
52
+ # (`github.event_name != 'pull_request' || …`) from every job's `if:` below, or it skips that run.
53
+ # EDIT: fork PRs (#514). A push to a fork never runs a workflow here, so a repo that takes
54
+ # PRs from forks needs `pull_request`. Uncomment it there. Every suite job below already
55
+ # carries `github.event.pull_request.head.repo.full_name != github.repository` for a PR
56
+ # event, so a same-repo PR's run skips every job (its push run is the one that tests) and a
57
+ # fork PR's run tests. A skipped run never stands for a workflow that has a run that ran
58
+ # (CONVENTIONS.md §4, "Branch CI"). Check every reader of your CI agrees before you uncomment.
59
+ # pull_request:
60
+ # branches: ['**']
48
61
  # A promotion pushed by the release workflow's token triggers no push run, so that workflow
49
62
  # dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
50
63
  workflow_dispatch:
51
64
 
52
65
  # One live run per branch: a new push cancels the superseded run on the same ref.
53
66
  # 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"). Pull-request runs
55
- # group under refs/pull/<n>/merge, apart from the branch's push runs.
56
- # EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
57
- # may carry any name; one left off this list gets its trunk runs cancelled.
67
+ # is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). A trunk run also gets a
68
+ # group of its own (the run id): GitHub cancels an older run that is still PENDING in a
69
+ # group even when cancel-in-progress is false, so a third quick merge would otherwise
70
+ # drop the second one's run before it ever started (#512).
71
+ # EDIT: name exactly this repo's trunk (and release branch) here — in the group, in
72
+ # cancel-in-progress, and in the `dedupe` job's `if:`. A Tier C trunk may carry any
73
+ # name; one left off this list gets its trunk runs cancelled. `colab template` writes these
74
+ # from the `trunk:` in .github/project.yml and prints what it wrote (#526).
58
75
  concurrency:
59
- group: ci-${{ github.ref }}
76
+ group: ci-${{ github.ref }}${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && format('-{0}', github.run_id) || '' }}
60
77
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
61
78
 
62
79
  env:
63
80
  # EDIT: bump deliberately, not automatically.
64
81
  GITLEAKS_VERSION: "8.30.1"
65
- # EDIT: npm script to build. Change for monorepos or non-standard scripts.
82
+ # EDIT: npm script to build. Change for monorepos or non-standard scripts. Empty, or a
83
+ # script package.json does not declare, skips the build with a notice (#526).
66
84
  BUILD_COMMAND: "build"
67
85
 
68
86
  # Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
@@ -99,17 +117,35 @@ jobs:
99
117
  # depends on those declares `tree-reuse: off` in .github/project.yml. Trunk only (the
100
118
  # descriptor's `trunk:`, read at this sha), never a release branch, never a dispatch;
101
119
  # any doubt (no descriptor, opt-out, an API error, no exact match) runs the full suite.
102
- # Never put a trunk-only job (publish, deploy, release) behind this gate.
120
+ # A green run at THIS sha on another ref (a `ship-batch/*` run trunk fast-forwarded to) is
121
+ # asked for first, by an exact query, so a busy repo's 50-run listing cannot miss it (#552).
122
+ # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
123
+ # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
124
+ # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
125
+ #
126
+ # Only documentation changed? (#570) — opt-in, `ci-docs-skip:` in .github/project.yml.
127
+ # When the two modes above find nothing, a repo that declared `ci-docs-skip` at THIS sha
128
+ # asks a third question: is every path changed since the base documentation, by the rule
129
+ # `colab ship` applies (CONVENTIONS.md §2, the docs-only exception: .md/.mdx/.txt or under
130
+ # docs/, never agent rules, config, a build input like requirements*.txt, a symlink, a
131
+ # submodule or a binary), and does the base
132
+ # have a green run of this workflow? The base is the merge base with trunk on a ref-creating
133
+ # push, and the previous tip on a push to trunk. Yes → the suite is skipped and the run
134
+ # leaves a `docs-only-skip` notice naming the base and its green run. A path the suite reads
135
+ # (docs/api/ feeding a generator) is listed in `ci-docs-skip` and always runs the suite. Any
136
+ # doubt (no opt-in, a red or unrun base, an API or fetch failure) runs the full suite. A run
137
+ # skipped this way is never cited as tree-reuse proof: it skipped every job (#511).
103
138
  dedupe:
104
139
  name: Already tested at this sha or tree?
105
140
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
106
141
  if: github.event_name == 'push' && (github.event.created || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
107
142
  runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
143
+ timeout-minutes: 5 # one `gh api` listing, a hung call must not hold the slot. EDIT: the default is 360.
108
144
  permissions:
109
145
  actions: read
110
146
  contents: read
111
147
  outputs:
112
- tested: ${{ steps.check.outputs.tested }}
148
+ tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
113
149
  cited: ${{ steps.check.outputs.cited }}
114
150
  steps:
115
151
  - name: Look for a green run of this workflow at this sha or tree
@@ -121,9 +157,58 @@ jobs:
121
157
  SHA: ${{ github.sha }}
122
158
  CREATED: ${{ github.event.created }}
123
159
  REF_NAME: ${{ github.ref_name }}
160
+ GUARD_NAME: Already tested at this sha or tree? # EDIT: this job's `name:`, if you rename it (#511).
124
161
  run: |
125
162
  tested=false
126
163
  cited=
164
+ # #511: a cited run is reusable only if it skipped no job but this guard. A job gated on
165
+ # the trunk ref is `skipped` on every branch push and a skipped job does not fail the
166
+ # run, so citing that run would skip the trunk-only job on trunk a second time.
167
+ reusable() {
168
+ if ! SK="$(gh api "repos/$REPO/actions/runs/$1/jobs?per_page=100" \
169
+ --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
170
+ echo "::notice::Could not list the jobs of run $1 — running the full suite (#511)."
171
+ return 1
172
+ elif [ -n "$SK" ]; then
173
+ echo "::notice::Run $1 skipped $SK, which this push may run — running the full suite (#511)."
174
+ return 1
175
+ fi
176
+ }
177
+ # The candidate runs, one per line as "<id> <head sha> <url> <branch>", newest first: green
178
+ # push runs of this workflow on another ref of this repo. #552: those at THIS sha first (a
179
+ # `ship-batch/*` run trunk fast-forwarded to), an exact query; then those whose commit has
180
+ # THIS tree (#493). The query's own per_page bounds the walk (#592).
181
+ same_sha() {
182
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&event=push&status=success&per_page=20" \
183
+ --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
184
+ }
185
+ same_tree() {
186
+ gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
187
+ --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
188
+ }
189
+ # #592: cite the newest candidate on stdin that passes every check. One that fails a check
190
+ # is passed over, not the end of the search: the newest green run can be a skip-chained one
191
+ # (#511) while an older run at the same sha or tree ran every job. A run already tried (the
192
+ # sha query's runs reappear in the tree listing) is not tried twice.
193
+ cite() {
194
+ local CID CSHA URL BR CTREE
195
+ while read -r CID CSHA URL BR; do
196
+ [ -n "$CID" ] || continue
197
+ case " $TRIED " in *" $CID "*) continue ;; esac
198
+ TRIED="$TRIED $CID"
199
+ if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
200
+ echo "::notice::Could not confirm the tree of $CSHA — passing over run $CID (#493)."
201
+ elif reusable "$CID"; then
202
+ tested=true
203
+ cited="$URL"
204
+ echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
205
+ echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
206
+ echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
207
+ return 0
208
+ fi
209
+ done
210
+ return 1
211
+ }
127
212
  if ! command -v gh >/dev/null 2>&1; then
128
213
  echo "::notice::gh is not installed on this runner — running the full suite (#418)."
129
214
  elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
@@ -138,21 +223,17 @@ jobs:
138
223
  echo "::notice::$REF_NAME is not this repo's trunk — running the full suite (#493)."
139
224
  elif ! OURS="$(gh api "repos/$REPO/git/commits/$SHA" --jq .tree.sha 2>/dev/null)" || [ -z "$OURS" ]; then
140
225
  echo "::notice::Could not read the tree of $SHA — running the full suite (#493)."
141
- elif ! CAND="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?event=push&status=success&per_page=50" \
142
- --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
143
- echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
144
- elif [ -z "$CAND" ]; then
145
- echo "No green run of this workflow on another ref has tree $OURS — running the full suite."
146
226
  else
147
- read -r CSHA URL BR <<< "$CAND"
148
- if ! CTREE="$(gh api "repos/$REPO/git/commits/$CSHA" --jq .tree.sha 2>/dev/null)" || [ "$CTREE" != "$OURS" ]; then
149
- echo "::notice::Could not confirm the tree of $CSHA — running the full suite (#493)."
150
- else
151
- tested=true
152
- cited="$URL"
153
- echo "::notice title=tree-already-green::$URL tree=$OURS head=$CSHA branch=$BR"
154
- echo "Tree $OURS already passed this workflow at $CSHA on $BR ($URL) — skipping the suite (#493)."
155
- echo "Already tested: tree \`$OURS\` passed this workflow on \`$BR\` — [the run relied on]($URL); suite skipped (#493)." >> "$GITHUB_STEP_SUMMARY"
227
+ TRIED=
228
+ SC="$(same_sha)" || SC= # the sha query failing falls through to the tree listing (#552)
229
+ if [ -n "$SC" ] && cite <<< "$SC"; then
230
+ :
231
+ elif ! TC="$(same_tree)"; then
232
+ echo "::notice::Could not list this workflow's green runs — running the full suite (#493)."
233
+ elif [ -z "$SC$TC" ]; then
234
+ echo "No green run of this workflow on another ref has sha $SHA or tree $OURS — running the full suite."
235
+ elif ! cite <<< "$TC"; then
236
+ echo "No green run of this workflow at sha $SHA or tree $OURS can be cited — running the full suite (#592)."
156
237
  fi
157
238
  fi
158
239
  elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
@@ -167,12 +248,167 @@ jobs:
167
248
  fi
168
249
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
169
250
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
251
+ # Docs-only (#570) — the two steps below run only when the step above found nothing.
252
+ - name: Find the base a docs-only change would rely on
253
+ id: docs_base
254
+ if: steps.check.outputs.tested != 'true'
255
+ env:
256
+ GH_TOKEN: ${{ github.token }}
257
+ REPO: ${{ github.repository }}
258
+ RUN_ID: ${{ github.run_id }}
259
+ SHA: ${{ github.sha }}
260
+ BEFORE: ${{ github.event.before }}
261
+ CREATED: ${{ github.event.created }}
262
+ REF: ${{ github.ref }}
263
+ REF_NAME: ${{ github.ref_name }}
264
+ run: |
265
+ base=
266
+ # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
267
+ # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
268
+ optin() {
269
+ local v items
270
+ v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
271
+ if [ -z "$v" ]; then
272
+ 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}')"
273
+ [ -n "$items" ] || return 1
274
+ elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
275
+ v="${v#[}"; v="${v%]}"
276
+ items="$(printf '%s' "$v" | tr ',' '\n')"
277
+ else
278
+ return 1
279
+ fi
280
+ EXCLUDE=
281
+ while IFS= read -r it; do
282
+ it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
283
+ [ -n "$it" ] || continue
284
+ case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
285
+ printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
286
+ EXCLUDE="$EXCLUDE ${it%/}"
287
+ done <<< "$items"
288
+ }
289
+ if ! command -v gh >/dev/null 2>&1; then
290
+ echo "gh is not installed on this runner — docs-only mode is off (#570)."
291
+ elif [ "${REF#refs/heads/}" = "$REF" ]; then
292
+ echo "$REF is not a branch — docs-only mode is off (#570)."
293
+ elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
294
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
295
+ elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
296
+ echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
297
+ elif ! optin; then
298
+ echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
299
+ else
300
+ TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
301
+ if [ -z "$TRUNK" ]; then
302
+ echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
303
+ elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
304
+ # A new branch: the change is everything since it left trunk (the diff the squash lands).
305
+ base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
306
+ [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
307
+ elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
308
+ base="$BEFORE" # a push to trunk: the change is what this push added
309
+ else
310
+ echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
311
+ fi
312
+ # The base must itself be green: a docs-only change cannot make a red suite green. The base
313
+ # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
314
+ # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
315
+ # skipped on the branch, #511). Still running, red, or none: the full suite.
316
+ if [ -n "$base" ]; then
317
+ if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
318
+ || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
319
+ --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
320
+ echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
321
+ base=
322
+ elif [ -z "$URL" ]; then
323
+ echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
324
+ base=
325
+ fi
326
+ fi
327
+ fi
328
+ if [ -n "$base" ]; then
329
+ echo "base=$base" >> "$GITHUB_OUTPUT"
330
+ echo "base_run=$URL" >> "$GITHUB_OUTPUT"
331
+ echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
332
+ fi
333
+ - name: Is every changed path documentation?
334
+ id: docs
335
+ if: steps.docs_base.outputs.base != ''
336
+ env:
337
+ GH_TOKEN: ${{ github.token }}
338
+ SERVER_URL: ${{ github.server_url }}
339
+ REPO: ${{ github.repository }}
340
+ SHA: ${{ github.sha }}
341
+ BASE: ${{ steps.docs_base.outputs.base }}
342
+ BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
343
+ EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
344
+ run: |
345
+ tested=false
346
+ # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
347
+ # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
348
+ # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
349
+ reason() {
350
+ local p="$1" base dir x
351
+ base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
352
+ case "$p" in \"*) echo "quoted path"; return ;; esac
353
+ for x in $EXCLUDE; do
354
+ case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
355
+ done
356
+ case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
357
+ # A build input despite the extension: the cure rule's Python manifest (any case), a pip
358
+ # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
359
+ lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
360
+ case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
361
+ case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
362
+ [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
363
+ case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
364
+ case "$p" in docs/*) return ;; esac
365
+ case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
366
+ echo "not .md/.mdx/.txt and not under docs/"
367
+ }
368
+ # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
369
+ G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
370
+ AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
371
+ if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
372
+ && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
373
+ && git -C "$G" config http.extraheader "$AUTH" \
374
+ && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
375
+ echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
376
+ elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
377
+ || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
378
+ echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
379
+ elif [ -z "$RAW" ]; then
380
+ echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
381
+ else
382
+ bad=; n=0
383
+ while IFS= read -r line; do
384
+ meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
385
+ why="$(reason "$p")"
386
+ set -- $meta
387
+ case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
388
+ case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
389
+ [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
390
+ done <<< "$RAW"
391
+ while IFS=$'\t' read -r a d p; do
392
+ if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
393
+ done <<< "$NUM"
394
+ if [ -n "$bad" ]; then
395
+ echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
396
+ else
397
+ tested=true
398
+ echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
399
+ echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
400
+ echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
401
+ fi
402
+ fi
403
+ rm -rf "$G"
404
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
170
405
 
171
406
  gitleaks:
172
407
  name: Secret scan (gitleaks)
173
408
  needs: dedupe
174
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
409
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
175
410
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
411
+ timeout-minutes: 15 # a scan of the checkout. EDIT: the default is 360.
176
412
  steps:
177
413
  - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
178
414
  with:
@@ -217,7 +453,7 @@ jobs:
217
453
  build:
218
454
  name: Build
219
455
  needs: dedupe
220
- if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
456
+ if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository) }}
221
457
  # A repo can adopt this template before it has any application code at all —
222
458
  # a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
223
459
  # else. Unguarded, every step below still runs: "Install dependencies" warns
@@ -242,6 +478,12 @@ jobs:
242
478
  # hashFiles() would have been testing an empty directory even if it were
243
479
  # allowed.
244
480
  runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
481
+ timeout-minutes: 60 # a hung build must not hold the runner for the 360-minute default (#572).
482
+ # EDIT: measured (#572): the slowest Node adopter's build ran p99 37 / max 43 min. Keep this
483
+ # well above YOUR p99 — below it a slow but healthy suite goes red (`gh run view <id>` per job).
484
+ # Re-exported so the opt-in round-trip job below resolves Node exactly once, here.
485
+ outputs:
486
+ node-version: ${{ steps.toolchain.outputs.node-version }}
245
487
  defaults:
246
488
  run:
247
489
  # EDIT: set to the directory holding package.json if the app is not at the root.
@@ -253,13 +495,15 @@ jobs:
253
495
 
254
496
  # ---------------------------------------------------------------------------
255
497
  # Descriptor check (#416). A value `colab ship` cannot use does not fail there —
256
- # it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
498
+ # it fails closed to the safe default, silently. `ship-batch: 5` (the cap was 3)
257
499
  # once turned every landing in a busy repo back to serial while this CI stayed
258
500
  # green; only a ship dry run noticed. So the value fails HERE, where the person
259
501
  # who changed project.yml is looking. Same rule as `colab ship` and the audit
260
- # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
261
- # cap is 3: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
502
+ # (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–8. Why the
503
+ # cap is 8: project.schema.md, `ship-batch`. `ship-batch-wait` (#555) the same way
262
504
  # (parseShipBatchWait): absent/empty/null, or a whole number with a unit (s, m, h).
505
+ # `ship-batch-steps` (#557, parseShipBatchSteps): absent/empty/null, or ascending
506
+ # whole numbers within ship-batch — 2,4,8 or [2, 4, 8].
263
507
  # `ci-wait-factor` (#564) too (tools/lib/ci-profile.js parseFactor): absent, or a number >= 1.
264
508
  # ---------------------------------------------------------------------------
265
509
  - name: Descriptor check (.github/project.yml)
@@ -275,11 +519,26 @@ jobs:
275
519
  }
276
520
  v="$(field ship-batch)"
277
521
  case "$v" in
278
- ''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
522
+ ''|'~'|null|1|2|3|4|5|6|7|8) echo "ship-batch: ${v:-absent} — ok" ;;
279
523
  *)
280
- 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."
524
+ 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."
281
525
  exit 1 ;;
282
526
  esac
527
+ # ship-batch-steps (#557): ascending whole numbers, each within ship-batch (the ceiling read above).
528
+ s="$(field ship-batch-steps)"
529
+ case "$s" in
530
+ ''|'~'|null) echo "ship-batch-steps: absent — ok (fixed size)" ;;
531
+ *)
532
+ case "$v" in ''|'~'|null) ceil=1 ;; *) ceil="$v" ;; esac
533
+ list="$(printf '%s' "$s" | sed -E -e 's/^\[(.*)\]$/\1/' -e 's/^[[:space:]]+//' -e 's/[[:space:]]+$//' -e 's/[[:space:]]*,[[:space:]]*/,/g')"
534
+ if printf '%s\n' "$list" | grep -Eq '^[1-9][0-9]*(,[1-9][0-9]*)*$' \
535
+ && 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
536
+ echo "ship-batch-steps: $list — ok"
537
+ else
538
+ 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."
539
+ exit 1
540
+ fi ;;
541
+ esac
283
542
  # ship-batch-wait (#555): a whole number with a unit — 90s, 6m, 1h. No ceiling: the repo chooses.
284
543
  w="$(field ship-batch-wait)"
285
544
  case "$w" in
@@ -425,11 +684,26 @@ jobs:
425
684
  echo "Node $NODE_VERSION (resolved from: $SOURCE)"
426
685
  echo "Node **$NODE_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
427
686
 
687
+ # Package cache (#571): on only on a GitHub-hosted runner AND with package-lock.json
688
+ # present. Both halves are load-bearing:
689
+ # - No lockfile → setup-node's `cache:` fails the step outright ("Dependencies lock
690
+ # file is not found"), and this template allows a repo without one.
691
+ # - Self-hosted → off. A persistent runner already keeps ~/.npm between jobs; a
692
+ # remote cache on top was measured as a loss, not a saving (#512).
693
+ # npm only: `cache: pnpm` needs pnpm on PATH before this step, and the install step
694
+ # below enables it through corepack afterwards. `package-manager-cache` is pinned to
695
+ # the same condition so setup-node's automatic `packageManager` caching cannot switch
696
+ # it back on where the condition says off.
697
+ # EDIT: self-hosted runners are already off; to turn caching off everywhere, replace
698
+ # both expressions with '' and false. If the app is not at the root, point the
699
+ # hashFiles() and a `cache-dependency-path:` at its package-lock.json.
428
700
  - name: Setup Node
429
701
  uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
430
702
  if: hashFiles('package.json') != ''
431
703
  with:
432
704
  node-version: ${{ steps.toolchain.outputs.node-version }}
705
+ cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
706
+ package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
433
707
 
434
708
  - name: Install dependencies
435
709
  if: hashFiles('package.json') != ''
@@ -491,6 +765,188 @@ jobs:
491
765
  if: steps.scripts.outputs.test == 'true'
492
766
  run: npm test
493
767
 
768
+ # Optional, like the scripts above (#526): a library or a test-only repo has no `build`
769
+ # script, and a template that fails on that turns a new adopter's first trunk run red.
494
770
  - name: Build
495
771
  if: hashFiles('package.json') != ''
496
- run: npm run "$BUILD_COMMAND"
772
+ run: |
773
+ if [ -z "$BUILD_COMMAND" ]; then
774
+ echo "::notice::BUILD_COMMAND is empty — no build."
775
+ elif ! node -e "const s=(require('./package.json').scripts)||{};process.exit(s[process.env.BUILD_COMMAND]?0:1)" 2>/dev/null; then
776
+ echo "::notice::No '$BUILD_COMMAND' script in package.json — skipping the build."
777
+ else
778
+ npm run "$BUILD_COMMAND"
779
+ fi
780
+
781
+ # ---------------------------------------------------------------------------
782
+ # Migration round-trip — OPT-IN (#494). Needed for `migration-grant: reviewer`: condition R
783
+ # reads a passing job named "Migration round-trip…" at the shipped head (CONVENTIONS.md §5),
784
+ # and the audit warns when a repo declares `reviewer` without one. Node has no canonical
785
+ # migration runner, so the job runs YOURS, forward-only, three times — each pass's schema
786
+ # must equal the first:
787
+ #
788
+ # 1. fresh apply every migration to an empty database (schema A)
789
+ # 2. re-apply apply again on the same database — nothing changes (must equal A)
790
+ # 3. on base empty database, apply the BASE's migrations (+ ROUNDTRIP_SEED rows),
791
+ # then this change's on top (must equal A)
792
+ #
793
+ # Pass 3 is the shape of a real deploy: an edit to a migration that is already applied is
794
+ # skipped by the runner there, so its schema differs from pass 1. Pass 3 runs the base's
795
+ # migrations with THIS checkout's code and node_modules — a runner whose migrations import
796
+ # app code may need its own ROUNDTRIP_APPLY for that pass.
797
+ #
798
+ # To adopt: remove the leading `# ` from every line between the two fences, e.g.
799
+ # sed -i '/^ ##>>>/,/^ ##<<</ s/^ # \{0,1\}/ /' .github/workflows/ci.yml
800
+ # then walk its EDIT points. Kept commented, not behind an `if:`: a job skipped on every run
801
+ # would cost every repo trunk tree reuse (#511), and a no-op job that ends green would pass
802
+ # R without testing anything. The branch that uncomments it edits .github/workflows/, so that
803
+ # one branch fails R and ships on a human grant (a branch never grades itself).
804
+ # ---------------------------------------------------------------------------
805
+ ##>>> migration round-trip (opt-in, #494) — uncomment to the closing fence
806
+ # migrations:
807
+ # name: Migration round-trip (${{ matrix.engine }})
808
+ # needs: build
809
+ # # Explicit result check, not the implicit success(): success() reads EVERY ancestor,
810
+ # # including `dedupe`, which is skipped on every ordinary push (#418).
811
+ # if: ${{ !cancelled() && needs.build.result == 'success' }}
812
+ # runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
813
+ # timeout-minutes: 15 # a hung round-trip must not hold the runner for the 360-minute default (#572).
814
+ # # EDIT: measured (#572): p99 under 4 min on every adopter. Keep it well above your own p99.
815
+ # strategy:
816
+ # fail-fast: false
817
+ # matrix:
818
+ # include:
819
+ # - engine: postgres
820
+ # image: postgres:17 # EDIT: the version production runs. A different one proves nothing about it.
821
+ # services:
822
+ # db:
823
+ # image: ${{ matrix.image }}
824
+ # env:
825
+ # # A disposable server inside one job; this password never leaves the runner.
826
+ # POSTGRES_PASSWORD: postgres
827
+ # # Container port only: a shared self-hosted runner may already listen on 5432.
828
+ # ports:
829
+ # - 5432
830
+ # options: >-
831
+ # --health-cmd "pg_isready -U postgres"
832
+ # --health-interval 5s
833
+ # --health-timeout 5s
834
+ # --health-retries 30
835
+ # env:
836
+ # # EDIT: the command that applies every pending migration to $DATABASE_URL — e.g.
837
+ # # `npx knex migrate:latest`, `npx dbmate --no-dump-schema up`, `node scripts/migrate.mjs`.
838
+ # # Required: an enabled round-trip that applies nothing must not pass R.
839
+ # ROUNDTRIP_APPLY: ""
840
+ # # EDIT: the prefixes under `migrations:` in .github/project.yml, space-separated.
841
+ # MIGRATIONS_PATHS: "migrations/"
842
+ # # EDIT: rows that look like OLD data (NULLs, rows a new foreign key would orphan),
843
+ # # written between pass 3's two applies. Empty = no seeding.
844
+ # ROUNDTRIP_SEED: ""
845
+ # # Leave an empty database, and print its schema. The defaults run INSIDE the
846
+ # # service container, so the client always matches the server's version.
847
+ # ROUNDTRIP_RESET: >-
848
+ # docker exec "$DB_CONTAINER" psql -q -U postgres -v ON_ERROR_STOP=1
849
+ # -c 'DROP DATABASE IF EXISTS roundtrip WITH (FORCE)' -c 'CREATE DATABASE roundtrip'
850
+ # ROUNDTRIP_DUMP: >-
851
+ # docker exec "$DB_CONTAINER" pg_dump -U postgres --schema-only --no-owner --no-privileges roundtrip
852
+ # steps:
853
+ # - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
854
+ # with:
855
+ # # Full history: pass 3 reads the migrations as they were at the base.
856
+ # fetch-depth: 0
857
+ # persist-credentials: false
858
+ #
859
+ # - name: Setup Node
860
+ # uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
861
+ # with:
862
+ # node-version: ${{ needs.build.outputs.node-version }}
863
+ # # Same cache gate as the build job's Setup Node (#571): hosted + lockfile only.
864
+ # cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' && 'npm' || '' }}
865
+ # package-manager-cache: ${{ runner.environment == 'github-hosted' && hashFiles('package-lock.json') != '' }}
866
+ #
867
+ # - name: Install dependencies
868
+ # run: |
869
+ # if [ -f pnpm-lock.yaml ]; then corepack enable; pnpm install --frozen-lockfile
870
+ # elif [ -f package-lock.json ]; then npm ci
871
+ # else npm install
872
+ # fi
873
+ #
874
+ # - name: Round-trip
875
+ # env:
876
+ # DB_CONTAINER: ${{ job.services.db.id }}
877
+ # DATABASE_URL: postgres://postgres:postgres@127.0.0.1:${{ job.services.db.ports['5432'] }}/roundtrip
878
+ # DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
879
+ # run: |
880
+ # set -euo pipefail
881
+ # if [ -z "${ROUNDTRIP_APPLY:-}" ]; then
882
+ # echo "::error::ROUNDTRIP_APPLY is empty — set the command that applies every pending migration (#494)."
883
+ # exit 1
884
+ # fi
885
+ # if [ -z "${MIGRATIONS_PATHS:-}" ]; then
886
+ # echo "::error::MIGRATIONS_PATHS is empty — copy the migrations: prefixes from .github/project.yml."
887
+ # exit 1
888
+ # fi
889
+ # # pg_dump 17.6+ writes a random key on its \restrict lines; drop them before comparing.
890
+ # dump() { eval "$ROUNDTRIP_DUMP" | { grep -vE '^\\(un)?restrict ' || true; }; }
891
+ # T="$RUNNER_TEMP"
892
+ #
893
+ # # The base: trunk from .github/project.yml (else the default branch); on trunk itself,
894
+ # # the commit before the one that just landed. A pull request compares against its base.
895
+ # trunk="$(sed -nE 's/^trunk:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml 2>/dev/null | head -1 || true)"
896
+ # base_ref="origin/${GITHUB_BASE_REF:-${trunk:-$DEFAULT_BRANCH}}"
897
+ # base=""
898
+ # if git rev-parse -q --verify "$base_ref" >/dev/null; then
899
+ # base="$(git merge-base HEAD "$base_ref")"
900
+ # [ "$base" != "$(git rev-parse HEAD)" ] || base="$(git rev-parse -q --verify 'HEAD^' || true)"
901
+ # fi
902
+ # if [ -n "$base" ]; then
903
+ # # Added, modified AND renamed (#507): an edit to an applied migration is the trap pass 3 exists for.
904
+ # # shellcheck disable=SC2086
905
+ # touched="$(git diff --name-status --diff-filter=AMR "$base" HEAD -- $MIGRATIONS_PATHS)"
906
+ # if [ -n "$touched" ]; then
907
+ # echo "This change touches migrations (vs $base_ref):"
908
+ # printf '%s\n' "$touched" | awk -F'\t' '{ print " " (substr($1,1,1) == "A" ? "added " : "modified") " " $NF }'
909
+ # else
910
+ # echo "This change adds or modifies no migrations (vs $base_ref)."
911
+ # fi
912
+ # fi
913
+ #
914
+ # # 1. Fresh: every migration applied to an empty database.
915
+ # eval "$ROUNDTRIP_RESET"
916
+ # eval "$ROUNDTRIP_APPLY"
917
+ # dump > "$T/schema-a.sql"
918
+ #
919
+ # # 2. Idempotent: applying again on the same database changes nothing.
920
+ # eval "$ROUNDTRIP_APPLY"
921
+ # dump > "$T/schema-a2.sql"
922
+ # if ! diff -u "$T/schema-a.sql" "$T/schema-a2.sql"; then
923
+ # echo "::error::Pass 2 (re-apply): a second apply changed the schema. The runner re-ran a migration it had already applied."
924
+ # exit 1
925
+ # fi
926
+ #
927
+ # # 3. Deploy-shaped: the base's migrations first (plus old-looking rows), then this change's
928
+ # # on top. A migration that was edited after it was applied is skipped by the runner here,
929
+ # # exactly as on a real database, so the schema differs from pass 1.
930
+ # eval "$ROUNDTRIP_RESET"
931
+ # if [ -n "$base" ]; then
932
+ # for p in $MIGRATIONS_PATHS; do
933
+ # p="${p%/}"; rm -rf "$p"
934
+ # if git cat-file -e "$base:$p" 2>/dev/null; then git archive "$base" "$p" | tar -x; fi
935
+ # done
936
+ # eval "$ROUNDTRIP_APPLY"
937
+ # [ -z "${ROUNDTRIP_SEED:-}" ] || eval "$ROUNDTRIP_SEED"
938
+ # for p in $MIGRATIONS_PATHS; do
939
+ # p="${p%/}"; rm -rf "$p"
940
+ # git checkout -q HEAD -- "$p" 2>/dev/null || true
941
+ # done
942
+ # else
943
+ # echo "::notice::No base to compare against ($base_ref not found) — pass 3 applies from empty."
944
+ # fi
945
+ # eval "$ROUNDTRIP_APPLY"
946
+ # dump > "$T/schema-b.sql"
947
+ # if ! diff -u "$T/schema-a.sql" "$T/schema-b.sql"; then
948
+ # echo "::error::Pass 3 (base, then this change): the schema differs from a fresh apply. A migration already on the base was edited, or the order only works on an empty database."
949
+ # exit 1
950
+ # fi
951
+ # echo "Round-trip passed: fresh, re-applied, and on top of the base all give one schema."
952
+ ##<<< migration round-trip