Test: Isolate generated docs and settings fixtures

config/dot/quickshell/scripts/panama-settings-docs

@@ -264,7 +264,14 @@ def main():
     parser = argparse.ArgumentParser()
     parser.add_argument("--check", action="store_true")
     parser.add_argument("--stdout", action="store_true")
+    parser.add_argument("--output", type=pathlib.Path, default=OUTPUT)
     args = parser.parse_args()
+    output = (args.output if args.output.is_absolute()
+              else (pathlib.Path.cwd() / args.output).resolve())
+    try:
+        displayed_output = output.relative_to(ROOT)
+    except ValueError:
+        displayed_output = output
 
     try:
         rendered = render(read_entries(), read_routes(), read_titles())
@@ -279,19 +286,19 @@ def main():
         return 0
 
     if args.check:
-        if not OUTPUT.exists():
+        if not output.exists():
-            print("panama-settings-docs: docs/settings.md has never been generated",
+            print(f"panama-settings-docs: {displayed_output} has never been generated",
                   file=sys.stderr)
             return 1
-        if OUTPUT.read_text() != rendered:
+        if output.read_text() != rendered:
-            print("panama-settings-docs: docs/settings.md is stale; re-run this "
+            print(f"panama-settings-docs: {displayed_output} is stale; re-run this "
                   "script and commit the result", file=sys.stderr)
             return 1
         return 0
 
-    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    output.parent.mkdir(parents=True, exist_ok=True)
-    OUTPUT.write_text(rendered)
+    output.write_text(rendered)
-    print(f"wrote {OUTPUT.relative_to(ROOT)}")
+    print(f"wrote {displayed_output}")
     return 0
 
 

tests/quickshell/settings-docs-contract

@@ -49,12 +49,24 @@ grep -q 'cursor:zoom_factor' "$doc" \
 # 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' >>"$doc"
+printf '\n<!-- drift -->\n' >>"$scratch/settings.md"
-if "$generator" --check >/dev/null 2>&1; then
+if "$generator" --check --output "$scratch/settings.md" >/dev/null 2>&1; then
-    cp "$scratch/settings.md" "$doc"
     fail '--check reported success on a modified file, so staleness would never be caught'
 fi
-cp "$scratch/settings.md" "$doc"
+
+# An explicit relative destination belongs to the caller's working directory,
+# not the repository root.
+(
+    cd "$scratch" || exit 1
+    "$generator" --output generated.md >/dev/null
+) || fail 'a relative --output path did not resolve from the current directory'
+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"

tests/quickshell/settings-sync-contract

@@ -29,8 +29,8 @@
 #      instead of being handed whole to a Text element and to anybody reading
 #      over a shoulder.
 #
-# Runs entirely against a temporary config home. The real settings store is read
+# Runs entirely against temporary config homes: one explicit source fixture and
-# for the export and never written.
+# one isolated import destination. The real settings store is never consulted.
 
 set -uo pipefail
 
@@ -52,6 +52,29 @@ trap 'rm -rf "$work"' EXIT
 bundle="$work/export.json"
 field() { python3 -c "import json,sys; print(json.load(sys.stdin)$1)"; }
 
+export XDG_CONFIG_HOME="$work/source-config"
+source_settings="$XDG_CONFIG_HOME/panama/settings.json"
+mkdir -p "$(dirname "$source_settings")"
+python3 - "$source_settings" <<'PY'
+import json, sys
+
+# A representative source store: every value that should travel is valid for
+# its schema type, while the machine-only and unknown values prove the allow
+# list does not export whatever else happens to be present.
+fixture = {
+    "blurEnabled": False,                 # boolean
+    "gapsIn": 7,                          # integer
+    "vrrPolicy": 2,                       # numeric enum
+    "weatherLocation": "Fixture Harbor", # string
+    "displays": {"DP-9": "source-only"},
+    "lastPage": "appearance",
+    "schemaVersion": 1,
+    "someFutureToken": "Bearer fixture-secret",
+}
+with open(sys.argv[1], "w", encoding="utf-8") as target:
+    json.dump(fixture, target)
+PY
+
 # ── 1 & 2. Export carries taste, not hardware ───────────────────────────────
 
 "$helper" export "$bundle" >"$work/export-result.json" || fail 'export failed'
@@ -61,7 +84,7 @@ reason="$(field "['error']" <"$work/export-result.json")"
 [[ "$(stat -c '%a' "$bundle")" == "600" ]] \
     || fail 'the export is readable by other accounts'
 
-python3 - "$bundle" "$schema" "${XDG_CONFIG_HOME:-$HOME/.config}/panama/settings.json" <<'PY' || fail 'the export carried the wrong things, in one direction or the other'
+python3 - "$bundle" "$schema" "$source_settings" <<'PY' || fail 'the export carried the wrong things, in one direction or the other'
 import json, re, sys
 bundle = json.load(open(sys.argv[1]))
 schema = open(sys.argv[2]).read()
@@ -105,6 +128,16 @@ PY
 # ── 3, 4. Arrival is validated per key, and the types are all covered ───────
 
 export XDG_CONFIG_HOME="$work/config"
+destination_settings="$XDG_CONFIG_HOME/panama/settings.json"
+mkdir -p "$(dirname "$destination_settings")"
+python3 - "$destination_settings" <<'PY'
+import json, sys
+
+# This valid preference is deliberately absent from the source fixture and
+# therefore from the bundle. Import must merge around it rather than replace it.
+with open(sys.argv[1], "w", encoding="utf-8") as target:
+    json.dump({"borderSize": 4}, target)
+PY
 
 python3 - "$bundle" "$work/tampered.json" <<'PY'
 import json, sys
@@ -208,18 +241,15 @@ PY
 
 # ── 5. Import merges rather than replaces ───────────────────────────────────
 
-python3 - "$work/config/panama/settings.json" <<'PY'
-import json, sys
-store = json.load(open(sys.argv[1]))
-store["aSettingTheBundleNeverMentions"] = "kept"
-json.dump(store, open(sys.argv[1], "w"))
-PY
 "$helper" import "$bundle" >/dev/null || fail 'second import failed'
-python3 - "$work/config/panama/settings.json" <<'PY' || fail 'import replaced the store instead of merging into it'
+python3 - "$bundle" "$destination_settings" <<'PY' || fail 'import replaced the store instead of merging into it'
 import json, sys
-store = json.load(open(sys.argv[1]))
+bundle = json.load(open(sys.argv[1]))["settings"]
-if store.get("aSettingTheBundleNeverMentions") != "kept":
+store = json.load(open(sys.argv[2]))
-    raise SystemExit('a setting the bundle did not mention was removed')
+if "borderSize" in bundle:
+    raise SystemExit('the merge sentinel unexpectedly appeared in the import bundle')
+if store.get("borderSize") != 4:
+    raise SystemExit('a schema-valid setting the bundle did not mention was removed')
 PY
 
 applied="$("$helper" import "$bundle" | field "['applied']")"