#!/usr/bin/env bash

# The settings reference is generated, and must not be stale.
#
# Every other kind of documentation here has drifted at least once: routing that
# pointed at a page not containing the setting, contracts that pinned the bug
# they were meant to prevent, a comment that failed to stop the person who read
# it from making the exact mistake it described. Prose describing 127 settings
# would drift the day after it was written.
#
# So docs/settings.md is generated from the schema, and this fails the moment
# the committed copy stops matching. That is the whole mechanism: the document
# cannot be wrong for longer than it takes to run the suite.

set -uo pipefail

repo_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
generator="$repo_dir/config/dot/quickshell/scripts/panama-settings-docs"
doc="$repo_dir/docs/settings.md"

fail() {
    printf 'settings docs contract: %s\n' "$1" >&2
    exit 1
}

[[ -x "$generator" ]] || fail 'the generator is missing or not executable'

"$generator" --check || fail 'docs/settings.md is stale -- run quickshell/scripts/panama-settings-docs and commit the result'

# A generator that silently emitted nothing would also pass --check against an
# equally empty file, so the output is checked for substance too.
[[ -s "$doc" ]] || fail 'docs/settings.md is empty'

settings="$(grep -c '^| \*\*' "$doc")"
schema_keys="$(grep -c 'key: "' "$repo_dir/config/dot/quickshell/config/PreferenceSchema.qml")"

# Internal keys are deliberately omitted, so the document is smaller than the
# schema -- but not by much. A large gap means the reader stopped recognising
# entries and quietly documented a fraction of them.
(( settings > schema_keys * 8 / 10 )) \
    || fail "the reference documents only $settings of $schema_keys schema keys, which suggests the generator stopped parsing partway"

# The compositor-backed settings are the ones worth naming precisely, since
# that is the string someone would search the Hyprland docs for.
grep -q 'cursor:zoom_factor' "$doc" \
    || fail 'compositor option names are missing from the reference'

# 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
cp "$doc" "$scratch/settings.md"
printf '\n<!-- drift -->\n' >>"$doc"
if "$generator" --check >/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"

printf 'settings docs contract: PASS (%d settings documented)\n' "$settings"