@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 +12 -0
- package/package.json +1 -1
- package/templates/ci-laravel.yml +168 -1
- package/templates/ci-node.yml +168 -1
- package/templates/ci-python.yml +168 -1
- package/tools/colab +7 -2
- package/tools/lib/docs-only.js +47 -0
- package/tools/lib/tree-green.js +21 -4
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
package/templates/ci-laravel.yml
CHANGED
|
@@ -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)
|
package/templates/ci-node.yml
CHANGED
|
@@ -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)
|
package/templates/ci-python.yml
CHANGED
|
@@ -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
|
|
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
|
/**
|
package/tools/lib/docs-only.js
CHANGED
|
@@ -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
|
};
|
package/tools/lib/tree-green.js
CHANGED
|
@@ -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
|
-
|
|
85
|
-
|
|
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 };
|