@futurelastic/colab-handbook 1.13.0-rc.42 → 1.13.0-rc.43

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/audit/audit.mjs CHANGED
@@ -123,6 +123,8 @@ const trustHumansLib = require("../tools/lib/trust-humans.js");
123
123
  const hermeticLib = require("../tools/lib/hermetic.js");
124
124
  // #493: the `tree-reuse:` opt-out — read through the same module `colab ship` reads citations with.
125
125
  const treeGreenLib = require("../tools/lib/tree-green.js");
126
+ // #570: the `ci-docs-skip:` opt-in — read through the same module whose rule the CI guard mirrors.
127
+ const docsOnlyLib = require("../tools/lib/docs-only.js");
126
128
  // #503: `ship-gate-workflows:` / `ship-ignore-workflows:` — read through the same module ship's CI gate uses.
127
129
  const verifyRunsLib = require("../tools/lib/verify-runs.js");
128
130
  // #410: the optional `gate:` block — read through the same module the skills name.
@@ -1436,6 +1438,16 @@ function auditRepo(target, ctx) {
1436
1438
  if (!tr.valid) fail(tr.reason);
1437
1439
  }
1438
1440
 
1441
+ // ---- ci-docs-skip (#570) ----------------------------------------------------
1442
+ // Opts the CI templates' guard into docs-only mode: a change whose every path is documentation
1443
+ // (tools/lib/docs-only.js, the rule colab ship applies), from a green base, skips the suite.
1444
+ // An invalid value fails: the guard reads it as not opted in, so it silently does nothing.
1445
+ {
1446
+ const ds = docsOnlyLib.parseCiDocsSkip(cfg);
1447
+ info.ciDocsSkip = ds.declared && ds.valid ? ds.exclude : null;
1448
+ if (!ds.valid) fail(ds.reason);
1449
+ }
1450
+
1439
1451
  // ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
1440
1452
  // Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
1441
1453
  // the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.42"
36
+ "version": "1.13.0-rc.43"
37
37
  }
@@ -157,6 +157,19 @@ jobs:
157
157
  # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
158
158
  # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
159
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).
160
173
  dedupe:
161
174
  name: Already tested at this sha or tree?
162
175
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -167,7 +180,7 @@ jobs:
167
180
  actions: read
168
181
  contents: read
169
182
  outputs:
170
- tested: ${{ steps.check.outputs.tested }}
183
+ tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
171
184
  cited: ${{ steps.check.outputs.cited }}
172
185
  steps:
173
186
  - name: Look for a green run of this workflow at this sha or tree
@@ -249,6 +262,160 @@ jobs:
249
262
  fi
250
263
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
251
264
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
265
+ # Docs-only (#570) — the two steps below run only when the step above found nothing.
266
+ - name: Find the base a docs-only change would rely on
267
+ id: docs_base
268
+ if: steps.check.outputs.tested != 'true'
269
+ env:
270
+ GH_TOKEN: ${{ github.token }}
271
+ REPO: ${{ github.repository }}
272
+ RUN_ID: ${{ github.run_id }}
273
+ SHA: ${{ github.sha }}
274
+ BEFORE: ${{ github.event.before }}
275
+ CREATED: ${{ github.event.created }}
276
+ REF: ${{ github.ref }}
277
+ REF_NAME: ${{ github.ref_name }}
278
+ run: |
279
+ base=
280
+ # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
281
+ # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
282
+ optin() {
283
+ local v items
284
+ v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
285
+ if [ -z "$v" ]; then
286
+ 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}')"
287
+ [ -n "$items" ] || return 1
288
+ elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
289
+ v="${v#[}"; v="${v%]}"
290
+ items="$(printf '%s' "$v" | tr ',' '\n')"
291
+ else
292
+ return 1
293
+ fi
294
+ EXCLUDE=
295
+ while IFS= read -r it; do
296
+ it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
297
+ [ -n "$it" ] || continue
298
+ case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
299
+ printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
300
+ EXCLUDE="$EXCLUDE ${it%/}"
301
+ done <<< "$items"
302
+ }
303
+ if ! command -v gh >/dev/null 2>&1; then
304
+ echo "gh is not installed on this runner — docs-only mode is off (#570)."
305
+ elif [ "${REF#refs/heads/}" = "$REF" ]; then
306
+ echo "$REF is not a branch — docs-only mode is off (#570)."
307
+ elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
308
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
309
+ elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
310
+ echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
311
+ elif ! optin; then
312
+ echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
313
+ else
314
+ TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
315
+ if [ -z "$TRUNK" ]; then
316
+ echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
317
+ elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
318
+ # A new branch: the change is everything since it left trunk (the diff the squash lands).
319
+ base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
320
+ [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
321
+ elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
322
+ base="$BEFORE" # a push to trunk: the change is what this push added
323
+ else
324
+ echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
325
+ fi
326
+ # The base must itself be green: a docs-only change cannot make a red suite green. The base
327
+ # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
328
+ # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
329
+ # skipped on the branch, #511). Still running, red, or none: the full suite.
330
+ if [ -n "$base" ]; then
331
+ if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
332
+ || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
333
+ --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
334
+ echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
335
+ base=
336
+ elif [ -z "$URL" ]; then
337
+ echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
338
+ base=
339
+ fi
340
+ fi
341
+ fi
342
+ if [ -n "$base" ]; then
343
+ echo "base=$base" >> "$GITHUB_OUTPUT"
344
+ echo "base_run=$URL" >> "$GITHUB_OUTPUT"
345
+ echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
346
+ fi
347
+ - name: Is every changed path documentation?
348
+ id: docs
349
+ if: steps.docs_base.outputs.base != ''
350
+ env:
351
+ GH_TOKEN: ${{ github.token }}
352
+ SERVER_URL: ${{ github.server_url }}
353
+ REPO: ${{ github.repository }}
354
+ SHA: ${{ github.sha }}
355
+ BASE: ${{ steps.docs_base.outputs.base }}
356
+ BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
357
+ EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
358
+ run: |
359
+ tested=false
360
+ # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
361
+ # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
362
+ # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
363
+ reason() {
364
+ local p="$1" base dir x
365
+ base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
366
+ case "$p" in \"*) echo "quoted path"; return ;; esac
367
+ for x in $EXCLUDE; do
368
+ case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
369
+ done
370
+ case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
371
+ # A build input despite the extension: the cure rule's Python manifest (any case), a pip
372
+ # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
373
+ lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
374
+ case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
375
+ case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
376
+ [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
377
+ case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
378
+ case "$p" in docs/*) return ;; esac
379
+ case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
380
+ echo "not .md/.mdx/.txt and not under docs/"
381
+ }
382
+ # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
383
+ G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
384
+ AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
385
+ if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
386
+ && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
387
+ && git -C "$G" config http.extraheader "$AUTH" \
388
+ && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
389
+ echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
390
+ elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
391
+ || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
392
+ echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
393
+ elif [ -z "$RAW" ]; then
394
+ echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
395
+ else
396
+ bad=; n=0
397
+ while IFS= read -r line; do
398
+ meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
399
+ why="$(reason "$p")"
400
+ set -- $meta
401
+ case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
402
+ case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
403
+ [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
404
+ done <<< "$RAW"
405
+ while IFS=$'\t' read -r a d p; do
406
+ if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
407
+ done <<< "$NUM"
408
+ if [ -n "$bad" ]; then
409
+ echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
410
+ else
411
+ tested=true
412
+ echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
413
+ echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
414
+ echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
415
+ fi
416
+ fi
417
+ rm -rf "$G"
418
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
252
419
 
253
420
  gitleaks:
254
421
  name: Secret scan (gitleaks)
@@ -122,6 +122,19 @@ jobs:
122
122
  # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
123
123
  # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
124
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).
125
138
  dedupe:
126
139
  name: Already tested at this sha or tree?
127
140
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -132,7 +145,7 @@ jobs:
132
145
  actions: read
133
146
  contents: read
134
147
  outputs:
135
- tested: ${{ steps.check.outputs.tested }}
148
+ tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
136
149
  cited: ${{ steps.check.outputs.cited }}
137
150
  steps:
138
151
  - name: Look for a green run of this workflow at this sha or tree
@@ -214,6 +227,160 @@ jobs:
214
227
  fi
215
228
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
216
229
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
230
+ # Docs-only (#570) — the two steps below run only when the step above found nothing.
231
+ - name: Find the base a docs-only change would rely on
232
+ id: docs_base
233
+ if: steps.check.outputs.tested != 'true'
234
+ env:
235
+ GH_TOKEN: ${{ github.token }}
236
+ REPO: ${{ github.repository }}
237
+ RUN_ID: ${{ github.run_id }}
238
+ SHA: ${{ github.sha }}
239
+ BEFORE: ${{ github.event.before }}
240
+ CREATED: ${{ github.event.created }}
241
+ REF: ${{ github.ref }}
242
+ REF_NAME: ${{ github.ref_name }}
243
+ run: |
244
+ base=
245
+ # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
246
+ # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
247
+ optin() {
248
+ local v items
249
+ v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
250
+ if [ -z "$v" ]; then
251
+ 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}')"
252
+ [ -n "$items" ] || return 1
253
+ elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
254
+ v="${v#[}"; v="${v%]}"
255
+ items="$(printf '%s' "$v" | tr ',' '\n')"
256
+ else
257
+ return 1
258
+ fi
259
+ EXCLUDE=
260
+ while IFS= read -r it; do
261
+ it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
262
+ [ -n "$it" ] || continue
263
+ case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
264
+ printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
265
+ EXCLUDE="$EXCLUDE ${it%/}"
266
+ done <<< "$items"
267
+ }
268
+ if ! command -v gh >/dev/null 2>&1; then
269
+ echo "gh is not installed on this runner — docs-only mode is off (#570)."
270
+ elif [ "${REF#refs/heads/}" = "$REF" ]; then
271
+ echo "$REF is not a branch — docs-only mode is off (#570)."
272
+ elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
273
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
274
+ elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
275
+ echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
276
+ elif ! optin; then
277
+ echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
278
+ else
279
+ TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
280
+ if [ -z "$TRUNK" ]; then
281
+ echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
282
+ elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
283
+ # A new branch: the change is everything since it left trunk (the diff the squash lands).
284
+ base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
285
+ [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
286
+ elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
287
+ base="$BEFORE" # a push to trunk: the change is what this push added
288
+ else
289
+ echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
290
+ fi
291
+ # The base must itself be green: a docs-only change cannot make a red suite green. The base
292
+ # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
293
+ # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
294
+ # skipped on the branch, #511). Still running, red, or none: the full suite.
295
+ if [ -n "$base" ]; then
296
+ if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
297
+ || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
298
+ --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
299
+ echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
300
+ base=
301
+ elif [ -z "$URL" ]; then
302
+ echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
303
+ base=
304
+ fi
305
+ fi
306
+ fi
307
+ if [ -n "$base" ]; then
308
+ echo "base=$base" >> "$GITHUB_OUTPUT"
309
+ echo "base_run=$URL" >> "$GITHUB_OUTPUT"
310
+ echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
311
+ fi
312
+ - name: Is every changed path documentation?
313
+ id: docs
314
+ if: steps.docs_base.outputs.base != ''
315
+ env:
316
+ GH_TOKEN: ${{ github.token }}
317
+ SERVER_URL: ${{ github.server_url }}
318
+ REPO: ${{ github.repository }}
319
+ SHA: ${{ github.sha }}
320
+ BASE: ${{ steps.docs_base.outputs.base }}
321
+ BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
322
+ EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
323
+ run: |
324
+ tested=false
325
+ # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
326
+ # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
327
+ # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
328
+ reason() {
329
+ local p="$1" base dir x
330
+ base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
331
+ case "$p" in \"*) echo "quoted path"; return ;; esac
332
+ for x in $EXCLUDE; do
333
+ case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
334
+ done
335
+ case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
336
+ # A build input despite the extension: the cure rule's Python manifest (any case), a pip
337
+ # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
338
+ lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
339
+ case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
340
+ case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
341
+ [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
342
+ case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
343
+ case "$p" in docs/*) return ;; esac
344
+ case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
345
+ echo "not .md/.mdx/.txt and not under docs/"
346
+ }
347
+ # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
348
+ G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
349
+ AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
350
+ if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
351
+ && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
352
+ && git -C "$G" config http.extraheader "$AUTH" \
353
+ && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
354
+ echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
355
+ elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
356
+ || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
357
+ echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
358
+ elif [ -z "$RAW" ]; then
359
+ echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
360
+ else
361
+ bad=; n=0
362
+ while IFS= read -r line; do
363
+ meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
364
+ why="$(reason "$p")"
365
+ set -- $meta
366
+ case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
367
+ case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
368
+ [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
369
+ done <<< "$RAW"
370
+ while IFS=$'\t' read -r a d p; do
371
+ if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
372
+ done <<< "$NUM"
373
+ if [ -n "$bad" ]; then
374
+ echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
375
+ else
376
+ tested=true
377
+ echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
378
+ echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
379
+ echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
380
+ fi
381
+ fi
382
+ rm -rf "$G"
383
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
217
384
 
218
385
  gitleaks:
219
386
  name: Secret scan (gitleaks)
@@ -134,6 +134,19 @@ jobs:
134
134
  # A cited run is reused only if it skipped no job but this one: a job gated on the trunk
135
135
  # ref is `skipped` on every branch push, and reusing that run would skip it on trunk too
136
136
  # (#511). Never put a trunk-only job (publish, deploy, release) behind this gate.
137
+ #
138
+ # Only documentation changed? (#570) — opt-in, `ci-docs-skip:` in .github/project.yml.
139
+ # When the two modes above find nothing, a repo that declared `ci-docs-skip` at THIS sha
140
+ # asks a third question: is every path changed since the base documentation, by the rule
141
+ # `colab ship` applies (CONVENTIONS.md §2, the docs-only exception: .md/.mdx/.txt or under
142
+ # docs/, never agent rules, config, a build input like requirements*.txt, a symlink, a
143
+ # submodule or a binary), and does the base
144
+ # have a green run of this workflow? The base is the merge base with trunk on a ref-creating
145
+ # push, and the previous tip on a push to trunk. Yes → the suite is skipped and the run
146
+ # leaves a `docs-only-skip` notice naming the base and its green run. A path the suite reads
147
+ # (docs/api/ feeding a generator) is listed in `ci-docs-skip` and always runs the suite. Any
148
+ # doubt (no opt-in, a red or unrun base, an API or fetch failure) runs the full suite. A run
149
+ # skipped this way is never cited as tree-reuse proof: it skipped every job (#511).
137
150
  dedupe:
138
151
  name: Already tested at this sha or tree?
139
152
  # EDIT: the trunk refs here mirror `concurrency`'s list above (#493).
@@ -144,7 +157,7 @@ jobs:
144
157
  actions: read
145
158
  contents: read
146
159
  outputs:
147
- tested: ${{ steps.check.outputs.tested }}
160
+ tested: ${{ steps.docs.outputs.tested == 'true' && 'true' || steps.check.outputs.tested }}
148
161
  cited: ${{ steps.check.outputs.cited }}
149
162
  steps:
150
163
  - name: Look for a green run of this workflow at this sha or tree
@@ -226,6 +239,160 @@ jobs:
226
239
  fi
227
240
  echo "tested=$tested" >> "$GITHUB_OUTPUT"
228
241
  [ -z "$cited" ] || echo "cited=$cited" >> "$GITHUB_OUTPUT"
242
+ # Docs-only (#570) — the two steps below run only when the step above found nothing.
243
+ - name: Find the base a docs-only change would rely on
244
+ id: docs_base
245
+ if: steps.check.outputs.tested != 'true'
246
+ env:
247
+ GH_TOKEN: ${{ github.token }}
248
+ REPO: ${{ github.repository }}
249
+ RUN_ID: ${{ github.run_id }}
250
+ SHA: ${{ github.sha }}
251
+ BEFORE: ${{ github.event.before }}
252
+ CREATED: ${{ github.event.created }}
253
+ REF: ${{ github.ref }}
254
+ REF_NAME: ${{ github.ref_name }}
255
+ run: |
256
+ base=
257
+ # The opt-in at THIS sha (project.schema.md "ci-docs-skip"). A list, flow or block; any
258
+ # doubt about it reads as "not opted in". Adding the key is itself not a docs-only change.
259
+ optin() {
260
+ local v items
261
+ v="$(printf '%s\n' "$DESC" | sed -nE 's/^ci-docs-skip[[:space:]]*:[[:space:]]*//p' | head -n 1 | sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//')"
262
+ if [ -z "$v" ]; then
263
+ 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}')"
264
+ [ -n "$items" ] || return 1
265
+ elif [ "${v#[}" != "$v" ] && [ "${v%]}" != "$v" ]; then
266
+ v="${v#[}"; v="${v%]}"
267
+ items="$(printf '%s' "$v" | tr ',' '\n')"
268
+ else
269
+ return 1
270
+ fi
271
+ EXCLUDE=
272
+ while IFS= read -r it; do
273
+ it="$(printf '%s' "$it" | sed -E "s/^[[:space:]]*[\"']?//; s/[\"']?[[:space:]]*$//")"
274
+ [ -n "$it" ] || continue
275
+ case "/$it/" in */../*|*/./*|//*) return 1 ;; esac
276
+ printf '%s' "$it" | grep -Eq '^[A-Za-z0-9._/-]+$' || return 1
277
+ EXCLUDE="$EXCLUDE ${it%/}"
278
+ done <<< "$items"
279
+ }
280
+ if ! command -v gh >/dev/null 2>&1; then
281
+ echo "gh is not installed on this runner — docs-only mode is off (#570)."
282
+ elif [ "${REF#refs/heads/}" = "$REF" ]; then
283
+ echo "$REF is not a branch — docs-only mode is off (#570)."
284
+ elif ! DESC="$(gh api "repos/$REPO/contents/.github/project.yml?ref=$SHA" -H 'Accept: application/vnd.github.raw' 2>/dev/null)" || [ -z "$DESC" ]; then
285
+ echo "::notice::Could not read .github/project.yml at $SHA — running the full suite (#570)."
286
+ elif ! grep -Eq '^ci-docs-skip[[:space:]]*:' <<< "$DESC"; then
287
+ echo "ci-docs-skip is not declared in .github/project.yml — docs-only mode is off (#570)."
288
+ elif ! optin; then
289
+ echo "::notice::ci-docs-skip in .github/project.yml is not a list of repo paths — running the full suite (#570)."
290
+ else
291
+ TRUNK="$(printf '%s\n' "$DESC" | sed -nE "s/^trunk:[[:space:]]*[\"']?([A-Za-z0-9._/-]+).*/\\1/p" | head -n 1)"
292
+ if [ -z "$TRUNK" ]; then
293
+ echo "::notice::.github/project.yml declares no trunk — running the full suite (#570)."
294
+ elif [ "${CREATED:-}" = "true" ] && [ "$REF_NAME" != "$TRUNK" ]; then
295
+ # A new branch: the change is everything since it left trunk (the diff the squash lands).
296
+ base="$(gh api "repos/$REPO/compare/$TRUNK...$SHA" --jq .merge_base_commit.sha 2>/dev/null)" || base=
297
+ [ -n "$base" ] || echo "::notice::Could not read the merge base of $SHA with $TRUNK — running the full suite (#570)."
298
+ elif [ "${CREATED:-}" = "false" ] && [ "$REF_NAME" = "$TRUNK" ] && [ -n "${BEFORE//0/}" ]; then
299
+ base="$BEFORE" # a push to trunk: the change is what this push added
300
+ else
301
+ echo "Not a new branch and not a push to trunk — docs-only mode is off (#570)."
302
+ fi
303
+ # The base must itself be green: a docs-only change cannot make a red suite green. The base
304
+ # is a trunk commit, so the run that counts is TRUNK's own newest push run there — never a
305
+ # branch run at the same sha, which may be green beside a red trunk run (a trunk-only job
306
+ # skipped on the branch, #511). Still running, red, or none: the full suite.
307
+ if [ -n "$base" ]; then
308
+ if ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ] \
309
+ || ! URL="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$base&event=push&per_page=20" \
310
+ --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
311
+ echo "::notice::Could not list this workflow's runs at $base — running the full suite (#570)."
312
+ base=
313
+ elif [ -z "$URL" ]; then
314
+ echo "Trunk's newest run of this workflow at $base is not green, or there is none — running the full suite (#570)."
315
+ base=
316
+ fi
317
+ fi
318
+ fi
319
+ if [ -n "$base" ]; then
320
+ echo "base=$base" >> "$GITHUB_OUTPUT"
321
+ echo "base_run=$URL" >> "$GITHUB_OUTPUT"
322
+ echo "exclude=${EXCLUDE# }" >> "$GITHUB_OUTPUT"
323
+ fi
324
+ - name: Is every changed path documentation?
325
+ id: docs
326
+ if: steps.docs_base.outputs.base != ''
327
+ env:
328
+ GH_TOKEN: ${{ github.token }}
329
+ SERVER_URL: ${{ github.server_url }}
330
+ REPO: ${{ github.repository }}
331
+ SHA: ${{ github.sha }}
332
+ BASE: ${{ steps.docs_base.outputs.base }}
333
+ BASE_RUN: ${{ steps.docs_base.outputs.base_run }}
334
+ EXCLUDE: ${{ steps.docs_base.outputs.exclude }}
335
+ run: |
336
+ tested=false
337
+ # Mirrors tools/lib/docs-only.js pathReason — the rule `colab ship` applies (CONVENTIONS.md
338
+ # §2, the docs-only exception). Prints why a path is NOT documentation; nothing if it is.
339
+ # Kept equal to that module by tools/lib/ci-template-docs-only.test.js; edit both or neither.
340
+ reason() {
341
+ local p="$1" base dir x
342
+ base="${p##*/}"; dir=; [ "$base" = "$p" ] || dir="${p%/*}"
343
+ case "$p" in \"*) echo "quoted path"; return ;; esac
344
+ for x in $EXCLUDE; do
345
+ case "$p" in "$x"|"$x"/*) echo "listed in ci-docs-skip"; return ;; esac
346
+ done
347
+ case "$base" in CLAUDE.md|CLAUDE.local.md|AGENTS.md) echo "agent rules"; return ;; esac
348
+ # A build input despite the extension: the cure rule's Python manifest (any case), a pip
349
+ # constraints file, CMakeLists.txt. A -r/-c include under another name: list it in ci-docs-skip.
350
+ lp="$(printf '%s' "$p" | tr 'A-Z' 'a-z')"
351
+ case "/$lp" in */requirements/*.txt|*/requirements/*.in) echo "a build input"; return ;; esac
352
+ case "${lp##*/}" in *requirements*.txt|*requirements*.in|*constraints*.txt) echo "a build input"; return ;; esac
353
+ [ "$base" != CMakeLists.txt ] || { echo "a build input"; return; }
354
+ case "/$dir/" in */.claude/*|*/.github/*|*/.githooks/*) echo "config"; return ;; */.colab/skills/*) echo "skill local policy"; return ;; esac
355
+ case "$p" in docs/*) return ;; esac
356
+ case "$base" in ?*.md|?*.mdx|?*.txt) return ;; esac
357
+ echo "not .md/.mdx/.txt and not under docs/"
358
+ }
359
+ # Both commits, trees only; blobs come on demand for the binary check. No checkout (#418).
360
+ G="$RUNNER_TEMP/docs-only-$GITHUB_RUN_ID"
361
+ AUTH="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$GH_TOKEN" | base64 | tr -d '\n')"
362
+ if ! { git init -q "$G" && git -C "$G" remote add origin "$SERVER_URL/$REPO" \
363
+ && git -C "$G" config remote.origin.promisor true && git -C "$G" config remote.origin.partialclonefilter blob:none \
364
+ && git -C "$G" config http.extraheader "$AUTH" \
365
+ && git -C "$G" fetch -q --no-tags --depth=1 --filter=blob:none origin "$BASE" "$SHA"; } >/dev/null 2>&1; then
366
+ echo "::notice::Could not fetch $BASE and $SHA — running the full suite (#570)."
367
+ elif ! RAW="$(git -C "$G" diff --raw --no-renames --no-abbrev "$BASE" "$SHA" 2>/dev/null)" \
368
+ || ! NUM="$(git -C "$G" diff --numstat --no-renames "$BASE" "$SHA" 2>/dev/null)"; then
369
+ echo "::notice::Could not diff $BASE..$SHA — running the full suite (#570)."
370
+ elif [ -z "$RAW" ]; then
371
+ echo "Empty diff from $BASE — nothing to call documentation; running the full suite (#570)."
372
+ else
373
+ bad=; n=0
374
+ while IFS= read -r line; do
375
+ meta="${line%%$'\t'*}"; p="${line#*$'\t'}"; n=$((n + 1))
376
+ why="$(reason "$p")"
377
+ set -- $meta
378
+ case "${1#:} $2" in *120000*) why="${why:+$why, }symlink change" ;; esac
379
+ case "${1#:} $2" in *160000*) why="${why:+$why, }submodule change" ;; esac
380
+ [ -z "$why" ] || bad="${bad:+$bad; }$p ($why)"
381
+ done <<< "$RAW"
382
+ while IFS=$'\t' read -r a d p; do
383
+ if [ "$a" = "-" ] && [ "$d" = "-" ]; then bad="${bad:+$bad; }$p (binary change)"; fi
384
+ done <<< "$NUM"
385
+ if [ -n "$bad" ]; then
386
+ echo "Not docs-only since $BASE: $bad — running the full suite (#570)."
387
+ else
388
+ tested=true
389
+ echo "::notice title=docs-only-skip::base=$BASE files=$n run=$BASE_RUN"
390
+ echo "Every one of $n changed path(s) since $BASE is documentation, and $BASE is green ($BASE_RUN) — skipping the suite (#570)."
391
+ echo "Docs-only: $n path(s) since \`$BASE\`, which [passed this workflow]($BASE_RUN); suite skipped (#570)." >> "$GITHUB_STEP_SUMMARY"
392
+ fi
393
+ fi
394
+ rm -rf "$G"
395
+ echo "tested=$tested" >> "$GITHUB_OUTPUT"
229
396
 
230
397
  gitleaks:
231
398
  name: Secret scan (gitleaks)
package/tools/colab CHANGED
@@ -11133,6 +11133,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
11133
11133
  const ids = treeGreen.treeSkipCheckRuns(checks);
11134
11134
  if (!ids || !ids.length) return verdict;
11135
11135
  const cites = [];
11136
+ const docs = [];
11136
11137
  let unreadable = 0;
11137
11138
  const treeOf = (sha) => {
11138
11139
  const r = git.git(['rev-parse', '--verify', '--quiet', `${sha}^{tree}`], repoAbs);
@@ -11140,7 +11141,11 @@ function treeGreenVerdict(repoAbs, run, verdict) {
11140
11141
  };
11141
11142
  const ours = treeOf(run.sha);
11142
11143
  for (const id of ids) {
11143
- const cite = treeGreen.parseCitation(git.ghCheckRunAnnotations(repoAbs, id));
11144
+ const annotations = git.ghCheckRunAnnotations(repoAbs, id);
11145
+ // #570: a docs-only skip — the guard found every changed path documentation from a green base.
11146
+ const docsSkip = treeGreen.parseDocsSkip(annotations);
11147
+ if (docsSkip) { docs.push(docsSkip); continue; }
11148
+ const cite = treeGreen.parseCitation(annotations);
11144
11149
  if (!cite) { unreadable++; continue; }
11145
11150
  const theirs = treeOf(cite.head);
11146
11151
  if (ours && theirs && ours !== theirs) {
@@ -11149,7 +11154,7 @@ function treeGreenVerdict(repoAbs, run, verdict) {
11149
11154
  }
11150
11155
  cites.push({ ...cite, proof: ours && theirs ? 'verified' : 'unverified' });
11151
11156
  }
11152
- return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable), treeGreen: cites.map((c) => c.url) };
11157
+ return { ...verdict, detail: verdict.detail + treeGreen.citationNote(cites, unreadable, docs), treeGreen: cites.map((c) => c.url) };
11153
11158
  }
11154
11159
 
11155
11160
  /**
@@ -19,6 +19,19 @@ const DOC_EXTENSIONS = Object.freeze(['.md', '.mdx', '.txt']);
19
19
  const DOCS_DIR = 'docs/';
20
20
  /** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
21
21
  const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
22
+ /**
23
+ * #570: build inputs that happen to end in `.txt` — a suite installs or compiles from them, so a change
24
+ * to one changes behaviour. Never documentation, at any depth: a Python dependency manifest exactly as
25
+ * the cure rule names one (cure-diff.js isPythonManifest — a name containing `requirements`, or under a
26
+ * `requirements/` directory, any case), a pip constraints file, and `CMakeLists.txt`. A `.txt` pulled
27
+ * in by `-r`/`-c` under some other name is NOT caught by name — a repo with one lists it in
28
+ * `ci-docs-skip`.
29
+ */
30
+ function buildInput(p, base) {
31
+ // Lazy: cure-diff.js requires this module at load time.
32
+ if (require('./cure-diff').isPythonManifest(p)) return true;
33
+ return /constraints.*\.txt$/i.test(base) || base === 'CMakeLists.txt';
34
+ }
22
35
  /** Config directories: nothing under them is documentation, at any depth. */
23
36
  const NEVER_DIRS = Object.freeze(['.claude', '.github', '.githooks']);
24
37
  /**
@@ -40,6 +53,7 @@ function pathReason(p) {
40
53
  const segs = String(p).split('/');
41
54
  const base = segs[segs.length - 1];
42
55
  if (NEVER_BASENAMES.includes(base)) return `${base} is agent rules, not documentation`;
56
+ if (buildInput(String(p), base)) return `${base} is a build input, not documentation`;
43
57
  const dir = segs.slice(0, -1).find((s) => NEVER_DIRS.includes(s));
44
58
  if (dir) return `under ${dir}/ (config)`;
45
59
  const dirs = segs.slice(0, -1);
@@ -164,7 +178,40 @@ function directChanges(git, repo, trunk, since) {
164
178
  return { ...verdict, commits: shas.length };
165
179
  }
166
180
 
181
+ /**
182
+ * #570: `ci-docs-skip:` in project.yml — the opt-in to the CI templates' docs-only mode. Absent (or
183
+ * null) = off. A list = on; each member is a repo path whose changes always run the suite even though
184
+ * this module calls them documentation (`docs/api/` feeding a generator). `[]` = on, nothing excluded.
185
+ *
186
+ * The CI guard parses the same shape in shell and reads anything else as "not opted in" — the
187
+ * stricter direction — so an invalid value here is a finding: a declaration that silently does
188
+ * nothing. Members are plain paths (the guard matches `p == x` or `p` under `x/`): no glob, no `..`
189
+ * or `.` segment, not absolute, only `[A-Za-z0-9._/-]`.
190
+ */
191
+ const CI_DOCS_SKIP_KEY = 'ci-docs-skip';
192
+ function parseCiDocsSkip(doc) {
193
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, CI_DOCS_SKIP_KEY);
194
+ const v = has ? doc[CI_DOCS_SKIP_KEY] : null;
195
+ if (v === null || v === undefined) {
196
+ return { declared: false, valid: true, on: false, exclude: null, reason: 'ci-docs-skip absent — a docs-only change runs the full CI suite (#570)' };
197
+ }
198
+ const bad = (why) => ({ declared: true, valid: false, on: false, exclude: null,
199
+ reason: `ci-docs-skip ${why} — it must be a list of repo paths (\`[]\` for none); the CI guard reads anything else as not opted in, so docs-only changes run the full suite` });
200
+ if (!Array.isArray(v)) return bad(`is ${JSON.stringify(v)}`);
201
+ const exclude = [];
202
+ for (const m of v) {
203
+ const s = typeof m === 'string' ? m.replace(/\/+$/, '') : null;
204
+ if (!s || !/^[A-Za-z0-9._/-]+$/.test(s) || s.startsWith('/') || s.split('/').some((x) => x === '..' || x === '.' || x === '')) {
205
+ return bad(`lists ${JSON.stringify(m)}, which is not a plain repo path`);
206
+ }
207
+ exclude.push(s);
208
+ }
209
+ return { declared: true, valid: true, on: true, exclude,
210
+ reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — a docs-only change skips the CI suite' };
211
+ }
212
+
167
213
  module.exports = {
168
214
  DOC_EXTENSIONS, DOCS_DIR, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
169
215
  pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
216
+ CI_DOCS_SKIP_KEY, parseCiDocsSkip,
170
217
  };
@@ -18,6 +18,8 @@
18
18
  */
19
19
 
20
20
  const NOTICE_TITLE = 'tree-already-green';
21
+ /** #570: the CI guard's docs-only mode leaves this notice instead — same run shape, a different reason. */
22
+ const DOCS_NOTICE_TITLE = 'docs-only-skip';
21
23
 
22
24
  /** `tree-reuse:` in project.yml. Absent = reuse on. `off` = the one legal value. */
23
25
  function parseTreeReuse(doc) {
@@ -72,17 +74,32 @@ function parseCitation(annotations) {
72
74
  return { url: m[1], runId, tree: m[2], head: m[3], branch: m[4] };
73
75
  }
74
76
 
77
+ /**
78
+ * #570: the docs-only notice in a check run's annotations (`base=<sha> files=<n> run=<url>`), or null.
79
+ * A docs-only skip has the same shape as a tree skip (the guard green, the rest skipped), so the
80
+ * reader must recognise it — otherwise it reads as a tree citation nobody can parse.
81
+ */
82
+ function parseDocsSkip(annotations) {
83
+ if (!Array.isArray(annotations)) return null;
84
+ const a = annotations.find((x) => x && x.title === DOCS_NOTICE_TITLE && typeof x.message === 'string');
85
+ if (!a) return null;
86
+ const m = a.message.trim().match(/^base=([0-9a-f]+)\s+files=(\d+)\s+run=(\S+)$/i);
87
+ if (!m) return null;
88
+ return { base: m[1], files: Number(m[2]), url: m[3] };
89
+ }
90
+
75
91
  /**
76
92
  * The verdict suffix for a green trunk read that relied on cited runs. `cites`: [{url, branch,
77
93
  * head, proof}] where proof is 'verified' | 'unverified'; `unreadable`: count of skip-runs whose
78
94
  * citation could not be read. '' when there is nothing to say (an ordinary green run).
79
95
  */
80
- function citationNote(cites, unreadable = 0) {
96
+ function citationNote(cites, unreadable = 0, docs = []) {
81
97
  const parts = (cites || []).map((c) =>
82
98
  `relied on ${c.url} (${c.branch}@${String(c.head).slice(0, 7)}${c.proof === 'verified' ? ', tree verified locally' : ', tree not verified locally'})`);
83
99
  for (let i = 0; i < unreadable; i++) parts.push('cited run unreadable');
84
- if (!parts.length) return '';
85
- return ` — tree already green (#493): suite skipped, ${parts.join('; ')}`;
100
+ const tree = parts.length ? ` — tree already green (#493): suite skipped, ${parts.join('; ')}` : '';
101
+ const doc = (docs || []).map((d) => `${d.files} path(s) since ${String(d.base).slice(0, 7)}, whose green run is ${d.url}`);
102
+ return tree + (doc.length ? ` — docs-only (#570): suite skipped, ${doc.join('; ')}` : '');
86
103
  }
87
104
 
88
- module.exports = { NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, citationNote };
105
+ module.exports = { NOTICE_TITLE, DOCS_NOTICE_TITLE, parseTreeReuse, treeSkipCheckRuns, parseCitation, parseDocsSkip, citationNote };