From 71f4f0d24bc32462b4c80fced90e84763b625fc2 Mon Sep 17 00:00:00 2001
From: Gabriel Brown <gbrown@ksensetech.com>
Date: Wed, 26 Aug 2026 23:05:14 -0400
Subject: [PATCH] Test: Guard settings docs contract cleanup

---
 .../quickshell/scripts/panama-settings-docs   |  4 +++
 tests/quickshell/settings-docs-contract       | 36 +++++++++++++++----
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/config/dot/quickshell/scripts/panama-settings-docs b/config/dot/quickshell/scripts/panama-settings-docs
index a6eb30d..18ab0ad 100755
--- a/config/dot/quickshell/scripts/panama-settings-docs
+++ b/config/dot/quickshell/scripts/panama-settings-docs
@@ -14,7 +14,11 @@ takes to run the suite.
 
 Usage:
   panama-settings-docs            write docs/settings.md
+  panama-settings-docs --output PATH
+                                  write PATH instead
   panama-settings-docs --check    exit 1 if the committed copy is stale
+  panama-settings-docs --check --output PATH
+                                  exit 1 if PATH is stale
   panama-settings-docs --stdout   print without writing
 
 Where each group of settings lives comes from SettingsSearch.qml's routing and
diff --git a/tests/quickshell/settings-docs-contract b/tests/quickshell/settings-docs-contract
index 81caf73..bca614d 100755
--- a/tests/quickshell/settings-docs-contract
+++ b/tests/quickshell/settings-docs-contract
@@ -25,7 +25,34 @@ fail() {
 
 [[ -x "$generator" ]] || fail 'the generator is missing or not executable'
 
+scratch="$(mktemp -d /tmp/panama-docs.XXXXXX)"
+trap 'rm -rf "$scratch"' EXIT
+git -C "$repo_dir" diff -- docs/settings.md >"$scratch/docs.diff.before" \
+    || fail 'could not capture the initial docs/settings.md state'
+
+assert_doc_unchanged() {
+    git -C "$repo_dir" diff -- docs/settings.md >"$scratch/docs.diff.after" \
+        && cmp -s "$scratch/docs.diff.before" "$scratch/docs.diff.after"
+}
+
+cleanup() {
+    status=$?
+    trap - EXIT HUP INT TERM
+    if ! assert_doc_unchanged; then
+        printf 'settings docs contract: the contract changed tracked docs/settings.md\n' >&2
+        status=1
+    fi
+    rm -rf "$scratch"
+    exit "$status"
+}
+
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+
 "$generator" --check || fail 'docs/settings.md is stale -- run quickshell/scripts/panama-settings-docs and commit the result'
+assert_doc_unchanged || fail 'the default --check changed tracked docs/settings.md'
 
 # A generator that silently emitted nothing would also pass --check against an
 # equally empty file, so the output is checked for substance too.
@@ -47,14 +74,12 @@ grep -q 'cursor:zoom_factor' "$doc" \
 
 # A stale copy must be detectable, not merely regenerable. Prove the check
 # actually compares content rather than always returning success.
-scratch="$(mktemp -d /tmp/panama-docs.XXXXXX)"
-trap 'rm -rf "$scratch"' EXIT
-git -C "$repo_dir" diff -- docs/settings.md >"$scratch/docs.diff.before"
 cp "$doc" "$scratch/settings.md"
 printf '\n<!-- drift -->\n' >>"$scratch/settings.md"
 if "$generator" --check --output "$scratch/settings.md" >/dev/null 2>&1; then
     fail '--check reported success on a modified file, so staleness would never be caught'
 fi
+assert_doc_unchanged || fail '--check --output changed tracked docs/settings.md'
 
 # An explicit relative destination belongs to the caller's working directory,
 # not the repository root.
@@ -62,11 +87,8 @@ fi
     cd "$scratch" || exit 1
     "$generator" --output generated.md >/dev/null
 ) || fail 'a relative --output path did not resolve from the current directory'
+assert_doc_unchanged || fail '--output changed tracked docs/settings.md'
 cmp -s "$doc" "$scratch/generated.md" \
     || fail 'generation through a relative --output path produced different documentation'
 
-git -C "$repo_dir" diff -- docs/settings.md >"$scratch/docs.diff.after"
-cmp -s "$scratch/docs.diff.before" "$scratch/docs.diff.after" \
-    || fail 'the contract changed tracked docs/settings.md'
-
 printf 'settings docs contract: PASS (%d settings documented)\n' "$settings"