test(deonboard): pin the de-onboard script to the lockfile schemas it is tested on

.github/workflows/code-hygiene-self-test.yml

@@ -85,7 +85,9 @@
           run: "bash tests/lock-transitive-closure.sh",
         },
         {
-          run: "bash tests/deonboard-estate-audit.sh",
+          # scripts/deonboard-estate-audit.sh against every actions.lock schema it
+          # claims to support; an untested schema must fail closed.
+          run: "bash tests/deonboard-lock-schemas.sh",
         },
       ],
     },

README.adoc

@@ -171,7 +171,9 @@ every consuming repository at once.
 `+actions.lock+`. Onboarded, a cross-repository reusable-workflow call
 startup-fails with zero jobs. `+scripts/deonboard-estate-audit.sh <repo>+`
 removes the entry and prunes the dependencies only it reached. It needs
-mikefarah `+yq+` v4, and it is idempotent.
+mikefarah `+yq+` v4, and it is idempotent. It refuses any `+actions.lock+`
+schema it has not been tested on; `+tests/deonboard-lock-schemas.sh+` holds
+one fixture per supported schema (v0.0.2, v0.0.3).
 . `+templates/track-estate-audit.yml+` becomes
 `+.github/workflows/track-estate-audit.yml+`. Weekly, it opens a PR that
 moves the pin to cicd-suite HEAD; that PR's own audit run is the check.

scripts/deonboard-estate-audit.sh

@@ -16,6 +16,7 @@
 # .github/workflows/main-estate-audit.yml records the evidence.
 #
 # Idempotent: a lock that does not list the workflow is left untouched.
+# Fails closed (exit 3) on an actions.lock schema it has not been tested on.
 set -euo pipefail
 
 repo="${1:?usage: deonboard-estate-audit.sh <repo-dir>}"
@@ -35,6 +36,17 @@ if ! w="$wf" yq -e '.workflows | has(strenv(w))' "$lock" >/dev/null 2>&1; then
   exit 0
 fi
 
+# Lockfile schemas this script is tested against, one fixture each in
+# tests/fixtures/actions-lock/ (tests/deonboard-lock-schemas.sh). An untested
+# schema fails closed: add its fixture first, then its version here.
+known_versions="v0.0.2 v0.0.3"
+ver=$(yq '.version' "$lock")
+case " $known_versions " in
+  *" $ver "*) ;;
+  *) echo "$repo: actions.lock schema '$ver' is untested by this script (tested: $known_versions); see tests/deonboard-lock-schemas.sh" >&2
+     exit 3 ;;
+esac
+
 w="$wf" yq -i -I4 'del(.workflows[strenv(w)])' "$lock"
 
 # owner/repo@ref -> lower-case owner/repo, ref as written. GitHub owner and

tests/deonboard-lock-schemas.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+#
+# scripts/deonboard-estate-audit.sh against every actions.lock schema it
+# claims to support.
+#
+# The de-onboard script edits a lockfile that gh-actions-lock owns. When
+# gh-actions-lock moved from schema v0.0.2 to v0.0.3 (v0.2.0, "Upgraded
+# lockfile schema v0.0.2 → v0.0.3"), nothing but a hand check showed the script
+# still worked. This test makes that check permanent:
+#
+#   * the script fails closed (exit 3) on any schema not in its
+#     `known_versions` list, so a future schema is a loud error, not a silent
+#     corruption of 199 lockfiles;
+#   * every version in that list must have a fixture here, so the list cannot
+#     grow without a test;
+#   * every fixture is de-onboarded, and the result must be pure removals with
+#     the same version line, closed (every reference resolves), orphan-free,
+#     and idempotent;
+#   * all fixtures are the same lock in different schemas, so all must prune
+#     the same dependency keys.
+#
+# The fixtures were also parsed, before and after, by the canonical parser
+# (github.com/github/actions-lockfile/go v0.0.6, the one gh-actions-lock v0.2.0
+# uses). That parser rejects unknown fields and future versions, so it is the
+# authority on validity; this test checks the structural properties above
+# without needing Go in CI.
+#
+# Two negative controls keep the test honest: an unknown schema must be
+# refused with the lock untouched, and a mutant script that skips the prune
+# must FAIL the orphan check.
+#
+# Usage: deonboard-lock-schemas.sh [script]   (a path lets the mutant run)
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="${1:-$ROOT/scripts/deonboard-estate-audit.sh}"
+FIXTURES="$ROOT/tests/fixtures/actions-lock"
+WF=".github/workflows/main-estate-audit.yml"
+PASS=0; FAIL=0
+ok()  { printf '  ok   %s\n' "$1"; PASS=$((PASS+1)); }
+bad() { printf '  FAIL %s\n' "$1"; FAIL=$((FAIL+1)); }
+
+yq --version 2>/dev/null | grep -q mikefarah || { echo "mikefarah yq v4 is required"; exit 2; }
+[ -f "$SCRIPT" ] || { echo "no script at $SCRIPT"; exit 2; }
+
+work=$(mktemp -d); trap 'rm -rf "$work"' EXIT
+
+# A throwaway repo holding <fixture> as its actions.lock; prints the repo dir.
+stage() { # <fixture> <name>
+  local r="$work/$2"
+  rm -rf "$r"; mkdir -p "$r/.github/workflows"
+  cp "$1" "$r/.github/workflows/actions.lock"
+  printf '%s\n' "$r"
+}
+
+# References that do not resolve to a dependency key (expect none).
+dangling() { # <lock>
+  { yq '.workflows[][]' "$1"
+    yq '.dependencies[] | select(has("uses")) | .uses[]' "$1"
+  } | sort -u | grep -vxF -f <(yq '.dependencies | keys | .[]' "$1") || true
+}
+
+# Dependency keys nothing references (expect none).
+orphans() { # <lock>
+  yq '.dependencies | keys | .[]' "$1" \
+    | grep -vxF -f <({ yq '.workflows[][]' "$1"
+                       yq '.dependencies[] | select(has("uses")) | .uses[]' "$1"
+                     } | sort -u) || true
+}
+
+# Newline-separated list to one line, for messages.
+oneline() { tr "\n" " " <<<"$1" | sed "s/ $//"; }
+
+removed_keys() { # <before> <after>
+  comm -23 <(yq '.dependencies | keys | .[]' "$1" | sort) \
+           <(yq '.dependencies | keys | .[]' "$2" | sort)
+}
+
+echo "== every supported schema has a fixture"
+known=$(sed -n 's/^known_versions="\(.*\)"$/\1/p' "$SCRIPT")
+[ -n "$known" ] && ok "script declares known_versions: $known" || bad "script declares no known_versions"
+for v in $known; do
+  [ -f "$FIXTURES/$v.lock" ] && ok "fixture for $v" || bad "no fixture $FIXTURES/$v.lock for supported schema $v"
+done
+
+reference=""
+for fx in "$FIXTURES"/*.lock; do
+  name=$(basename "$fx" .lock)
+  echo "== $name"
+  before_ver=$(yq '.version' "$fx")
+  w="$WF" yq -e '.workflows | has(strenv(w))' "$fx" >/dev/null \
+    && ok "fixture onboards $WF" || bad "fixture does not onboard $WF, so it tests nothing"
+
+  r=$(stage "$fx" "$name")
+  lock="$r/.github/workflows/actions.lock"
+  if out=$(bash "$SCRIPT" "$r" 2>&1); then ok "script exits 0"; else bad "script failed: $out"; continue; fi
+
+  w="$WF" yq -e '.workflows | has(strenv(w)) | not' "$lock" >/dev/null \
+    && ok "$WF entry removed" || bad "$WF entry still present"
+  [ "$(yq '.version' "$lock")" = "$before_ver" ] \
+    && ok "version line kept ($before_ver)" || bad "version changed to $(yq '.version' "$lock")"
+  added=$(diff "$fx" "$lock" | grep -c '^>' || true)
+  [ "$added" -eq 0 ] && ok "pure removals" || bad "$added line(s) added or rewritten"
+  d=$(dangling "$lock"); [ -z "$d" ] && ok "every reference resolves" || bad "dangling: $d"
+  o=$(orphans "$lock");  [ -z "$o" ] && ok "no orphaned dependencies" || bad "orphaned: $o"
+
+  cp "$lock" "$work/once"
+  bash "$SCRIPT" "$r" >/dev/null 2>&1
+  cmp -s "$work/once" "$lock" && ok "idempotent" || bad "second run changed the lock"
+
+  keys=$(removed_keys "$fx" "$lock")
+  if [ -z "$reference" ]; then
+    reference="$keys"
+    [ -n "$keys" ] && ok "pruned: $(oneline "$keys")" || bad "pruned nothing"
+  else
+    [ "$keys" = "$reference" ] && ok "same keys pruned as the first fixture" \
+      || bad "pruned set differs: $(oneline "$keys")"
+  fi
+done
+
+echo "== negative control: an untested schema is refused, lock untouched"
+r=$(stage "$FIXTURES/v0.0.2.lock" future)
+lock="$r/.github/workflows/actions.lock"
+sed -i "s/^version: 'v0\.0\.2'$/version: 'v9.9.9'/" "$lock"
+cp "$lock" "$work/future-before"
+bash "$SCRIPT" "$r" >/dev/null 2>&1; rc=$?
+[ "$rc" -eq 3 ] && ok "exit 3 on schema v9.9.9" || bad "exit $rc on schema v9.9.9 (want 3)"
+cmp -s "$work/future-before" "$lock" && ok "lock untouched" || bad "lock modified despite refusal"
+
+echo "== negative control: a mutant that skips the prune fails the orphan check"
+if [ "$SCRIPT" = "$ROOT/scripts/deonboard-estate-audit.sh" ]; then
+  mutant="$work/mutant.sh"
+  sed 's/^  \[ -n "\$unused" \] || break$/  break/' "$SCRIPT" > "$mutant"
+  if cmp -s "$SCRIPT" "$mutant"; then
+    bad "mutation did not apply; the prune loop changed shape, update this control"
+  else
+    r=$(stage "$FIXTURES/v0.0.3.lock" mutant)
+    bash "$mutant" "$r" >/dev/null 2>&1
+    o=$(orphans "$r/.github/workflows/actions.lock")
+    [ -n "$o" ] && ok "mutant leaves orphans, and the check sees them: $(oneline "$o")" \
+      || bad "orphan check passed a mutant that does not prune"
+  fi
+fi
+
+echo
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

tests/fixtures/actions-lock/v0.0.2.lock

@@ -0,0 +1,81 @@
+# Fixture for tests/deonboard-lock-schemas.sh: schema v0.0.2, verbatim.
+# Source: hyperpolymath/marches .github/workflows/actions.lock at e2f71fe,
+# before the estate-audit caller was de-onboarded.
+# This file is machine-generated by `gh actions-lock`.
+# Do not edit by hand; run `gh actions-lock` to update.
+# Docs: https://gh.io/actions-lockfile
+version: 'v0.0.2'
+workflows:
+    '.github/workflows/ci.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'leanprover/lean-action@v1.6.0'
+    '.github/workflows/codeql.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'github/codeql-action@v4.38.0'
+    '.github/workflows/label-triage.yml': []
+    '.github/workflows/labels.yml': []
+    '.github/workflows/main-estate-audit.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'hyperpolymath/cicd-suite@main'
+    '.github/workflows/pages.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/deploy-pages@v5.0.1'
+        - 'actions/upload-pages-artifact@v5.0.0'
+dependencies:
+    'actions/cache@v5':
+        ref: 'v5'
+        commit: 'sha1-caa296126883cff596d87d8935842f9db880ef25'
+        owner_id: 44036562
+        repo_id: 215566462
+    'actions/checkout@v7.0.1':
+        ref: 'v7.0.1'
+        commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
+        owner_id: 44036562
+        repo_id: 197814629
+    'actions/deploy-pages@v5.0.1':
+        ref: 'v5.0.1'
+        commit: 'sha1-368f82528645a54fb793d4d04e342629a3f51346'
+        owner_id: 44036562
+        repo_id: 438112499
+    'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f':
+        ref: 'v7.0.0'
+        commit: 'sha1-bbbca2ddaa5d8feaa63e36b76fdaad77386f024f'
+        owner_id: 44036562
+        repo_id: 192625955
+    'actions/upload-pages-artifact@v5.0.0':
+        ref: 'v5.0.0'
+        commit: 'sha1-fc324d3547104276b827a68afc52ff2a11cc49c9'
+        owner_id: 44036562
+        repo_id: 496012378
+        uses:
+            - 'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f'
+    'github/codeql-action@v4.38.0':
+        ref: 'v4.38.0'
+        commit: 'sha1-b96794f015dfd88f77b49b1c93e0fa7110f94c63'
+        owner_id: 9919
+        repo_id: 259445878
+    'hyperpolymath/cicd-suite@main':
+        ref: 'main'
+        commit: 'sha1-5a10b72e574ef63855fafd4568a4c178657f3294'
+        owner_id: 6759885
+        repo_id: 1326697643
+        uses:
+            - 'hyperpolymath/deed-ecosystem@f9d999b60cb5f383679ea19912bcdc49c944973a'
+            - 'hyperpolymath/k9-ecosystem@2155aa26a21758f2ba119f61bc7e0e1981c106fb'
+    'hyperpolymath/deed-ecosystem@f9d999b60cb5f383679ea19912bcdc49c944973a':
+        ref: 'main'
+        commit: 'sha1-f9d999b60cb5f383679ea19912bcdc49c944973a'
+        owner_id: 6759885
+        repo_id: 1275649586
+    'hyperpolymath/k9-ecosystem@2155aa26a21758f2ba119f61bc7e0e1981c106fb':
+        ref: 'main'
+        commit: 'sha1-2155aa26a21758f2ba119f61bc7e0e1981c106fb'
+        owner_id: 6759885
+        repo_id: 1275650185
+    'leanprover/lean-action@v1.6.0':
+        ref: 'v1.6.0'
+        commit: 'sha1-50fcf42d2e460296f1a34b402e990d1b24f8b596'
+        owner_id: 7233018
+        repo_id: 795738301
+        uses:
+            - 'actions/cache@v5'

tests/fixtures/actions-lock/v0.0.3-hostname.lock

@@ -0,0 +1,85 @@
+# Fixture for tests/deonboard-lock-schemas.sh: schema v0.0.3 with the
+# optional per-dependency hostname, as written for github.com pins on a
+# GHE.com tenant. One sits on a pruned dependency, one on a kept one.
+# Source: hyperpolymath/marches .github/workflows/actions.lock at e2f71fe,
+# before the estate-audit caller was de-onboarded.
+# This file is machine-generated by `gh actions-lock`.
+# Do not edit by hand; run `gh actions-lock` to update.
+# Docs: https://gh.io/actions-lockfile
+version: 'v0.0.3'
+workflows:
+    '.github/workflows/ci.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'leanprover/lean-action@v1.6.0'
+    '.github/workflows/codeql.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'github/codeql-action@v4.38.0'
+    '.github/workflows/label-triage.yml': []
+    '.github/workflows/labels.yml': []
+    '.github/workflows/main-estate-audit.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'hyperpolymath/cicd-suite@main'
+    '.github/workflows/pages.yml':
+        - 'actions/checkout@v7.0.1'
+        - 'actions/deploy-pages@v5.0.1'
+        - 'actions/upload-pages-artifact@v5.0.0'
+dependencies:
+    'actions/cache@v5':
+        ref: 'v5'
+        commit: 'sha1-caa296126883cff596d87d8935842f9db880ef25'
+        owner_id: 44036562
+        repo_id: 215566462
+    'actions/checkout@v7.0.1':
+        ref: 'v7.0.1'
+        commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
+        owner_id: 44036562
+        repo_id: 197814629
+    'actions/deploy-pages@v5.0.1':
+        ref: 'v5.0.1'
+        commit: 'sha1-368f82528645a54fb793d4d04e342629a3f51346'
+        owner_id: 44036562
+        repo_id: 438112499
+    'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f':
+        ref: 'v7.0.0'
+        commit: 'sha1-bbbca2ddaa5d8feaa63e36b76fdaad77386f024f'
+        owner_id: 44036562
+        repo_id: 192625955
+    'actions/upload-pages-artifact@v5.0.0':
+        ref: 'v5.0.0'
+        commit: 'sha1-fc324d3547104276b827a68afc52ff2a11cc49c9'
+        owner_id: 44036562
+        repo_id: 496012378
+        uses:
+            - 'actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f'
+    'github/codeql-action@v4.38.0':
+        ref: 'v4.38.0'
+        commit: 'sha1-b96794f015dfd88f77b49b1c93e0fa7110f94c63'
+        owner_id: 9919
+        repo_id: 259445878
+    'hyperpolymath/cicd-suite@main':
+        ref: 'main'
+        commit: 'sha1-5a10b72e574ef63855fafd4568a4c178657f3294'
+        owner_id: 6759885
+        repo_id: 1326697643
+        uses:
+            - 'hyperpolymath/deed-ecosystem@f9d999b60cb5f383679ea19912bcdc49c944973a'
+            - 'hyperpolymath/k9-ecosystem@2155aa26a21758f2ba119f61bc7e0e1981c106fb'
+    'hyperpolymath/deed-ecosystem@f9d999b60cb5f383679ea19912bcdc49c944973a':
+        hostname: 'github.com'
+        ref: 'main'
+        commit: 'sha1-f9d999b60cb5f383679ea19912bcdc49c944973a'
+        owner_id: 6759885
+        repo_id: 1275649586
+    'hyperpolymath/k9-ecosystem@2155aa26a21758f2ba119f61bc7e0e1981c106fb':
+        ref: 'main'
+        commit: 'sha1-2155aa26a21758f2ba119f61bc7e0e1981c106fb'
+        owner_id: 6759885
+        repo_id: 1275650185
+    'leanprover/lean-action@v1.6.0':
+        hostname: 'github.com'
+        ref: 'v1.6.0'
+        commit: 'sha1-50fcf42d2e460296f1a34b402e990d1b24f8b596'
+        owner_id: 7233018
+        repo_id: 795738301
+        uses:
+            - 'actions/cache@v5'