diff --git a/.github/scripts/vendored-check.sh b/.github/scripts/vendored-check.sh index 126c067..929e4fe 100755 --- a/.github/scripts/vendored-check.sh +++ b/.github/scripts/vendored-check.sh @@ -85,11 +85,22 @@ mapfile -t manifest < <(grep -v '^[[:space:]]*$' "$manifest_file" || true) # work tree root. Fixture trees are plain directories, and asserting # tracked-ness against an enclosing repository would be asserting about the # wrong tree. +# +# When it cannot bind, SAY SO. This guard's whole argument is that a silent +# miss is worse than a loud one, and a guard that quietly stops asserting one +# of its four properties is exactly that shape — so the skip is announced on +# every run, green or red, rather than inferred from the absence of a +# refusal (#251 round 1). tracked_check=no +tracked_note="tracked-ness NOT asserted: $tree is not a git work tree root, so + 'is this file in the tag's tree' cannot be answered about THIS tree. The + other three manifest assertions (regular file, non-empty, no + symlink/dir/escape) still bind." if command -v git >/dev/null 2>&1; then toplevel="$(git -C "$tree" rev-parse --show-toplevel 2>/dev/null || true)" if [ -n "$toplevel" ] && [ "$toplevel" = "$(cd "$tree" && pwd -P)" ]; then tracked_check=yes + tracked_note="" fi fi @@ -211,11 +222,13 @@ if [ "${#problems[@]}" -gt 0 ]; then printf 'vendored-check: %d problem(s) — docs/VENDORED.txt and the tree disagree.\n\n' \ "${#problems[@]}" printf '%s\n\n' "${problems[@]}" + [ -z "$tracked_note" ] || printf 'vendored-check: %s\n' "$tracked_note" } >&2 exit 1 fi printf 'vendored-check: %d manifest entries resolve; %d root docs vendored, %d exempt.\n' \ "${#manifest[@]}" "${#vendored[@]}" "${#exempted[@]}" +[ -z "$tracked_note" ] || printf 'vendored-check: %s\n' "$tracked_note" [ "${#vendored[@]}" -eq 0 ] || printf ' vendored: %s\n' "${vendored[@]}" [ "${#exempted[@]}" -eq 0 ] || printf ' exempt: %s\n' "${exempted[@]}" diff --git a/docs/CONSUMERS.md b/docs/CONSUMERS.md index 17cbc13..bd68963 100644 --- a/docs/CONSUMERS.md +++ b/docs/CONSUMERS.md @@ -603,9 +603,10 @@ copying it ahead of their pinned doctrine set. Anything on the consumer's side that needs to know *which* documents are vendored — a re-vendor script, a `docs-sync` equivalent, the task list of a conversion issue — reads **the pin's `docs/VENDORED.txt`** and never names -the files itself. The manifest is available at the pinned ref from `0.5.0` -and later — it shipped with `actions/docs-sync` itself (ceremony#19) — and -it is one path per line, relative to ceremony's root, blank lines ignored: +the files itself. The manifest is available at the pinned ref from `0.1.0` +and later — it shipped with `actions/docs-sync` itself (ceremony#19), in the +same commit, and that tool has read it rather than a list since — and it is +one path per line, relative to ceremony's root, blank lines ignored: ```sh # the vendored doc set at the ref this repo is pinned to diff --git a/test/vendored.test.sh b/test/vendored.test.sh index e8030a4..50ee65d 100644 --- a/test/vendored.test.sh +++ b/test/vendored.test.sh @@ -199,6 +199,21 @@ git -C "$TMP/untracked" add docs/VENDORED.txt AGENTS.md check "a git tree with an untracked manifest entry reds" 1 "names 'RULES.md', which is not TRACKED" \ run_check untracked +# ...and where it cannot bind, the skip ANNOUNCES ITSELF rather than being +# inferred from the absence of a refusal (#251 round 1). A guard that quietly +# stops asserting one of its four properties is the silent miss this whole +# script argues against, so the degradation is visible on both output paths. +check "a non-git tree says tracked-ness was not asserted" 0 "tracked-ness NOT asserted" \ + run_check ok +check "...and says it on the red path too, beside the refusals" 1 "tracked-ness NOT asserted" \ + run_check newdoc + +# The converse, so the note is not simply always printed: where the tree IS a +# git work tree root the assertion bound, and nothing is announced. +no_skip_note() { ! run_check tracked 2>&1 | grep -qF "tracked-ness NOT asserted"; } +check "a git work tree root announces no skip — the assertion bound" 0 "" \ + no_skip_note + # --- the real tree ----------------------------------------------------------- check "this tree, unmodified, is green" 0 "manifest entries resolve" bash "$CHECK" "$ROOT"