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

#!/usr/bin/env python3

"""Generate the settings reference from PreferenceSchema.qml.

Every other form of documentation in this repository 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, and a comment that failed to stop the person
who read it making the exact mistake it warned about. Prose describing 137
settings would drift the day after it was written.

So this is generated, and a contract fails when the committed copy no longer
matches what the schema says. The document cannot be wrong for longer than it
takes to run the suite.

Usage:
  panama-settings-docs            write docs/settings.md
  panama-settings-docs --check    exit 1 if the committed copy is stale
  panama-settings-docs --stdout   print without writing

Parsing rather than importing: the schema is QML, there is no QML interpreter
here, and a regex reader that FAILS LOUDLY when it stops recognising the file is
better than a dependency on a shell that has to start a compositor.
"""

import argparse
import pathlib
import re
import sys

# scripts/ -> quickshell/ -> dot/ -> config/ -> repo root. resolve() first, so
# this still works when invoked through the ~/.config/quickshell symlink.
ROOT = pathlib.Path(__file__).resolve().parents[4]
SCHEMA = ROOT / "config/dot/quickshell/config/PreferenceSchema.qml"
SEARCH = ROOT / "config/dot/quickshell/services/SettingsSearch.qml"
OUTPUT = ROOT / "docs/settings.md"

# Page id -> the name a person sees in the sidebar.
PAGE_TITLES = {
    "home": "Home", "appearance": "Appearance", "displays": "Displays",
    "connectivity": "Network & Devices", "home-phone": "Home & Phone",
    "desktop": "Desktop & Dock", "sound": "Sound",
    "notifications": "Notifications & Focus",
    "screen-intelligence": "Screen Intelligence", "shortcuts": "Keyboard",
    "mouse": "Mouse & Touchpad", "privacy": "Privacy & Security",
    "region": "Region & Language", "accounts": "Online Accounts",
    "accessibility": "Accessibility", "power": "Power & Lock",
    "datetime": "Date & Time", "applications": "Applications",
    "services": "System Health", "about": "About",
}


class SchemaError(RuntimeError):
    """The schema stopped looking the way this reader expects."""


def read_routes():
    """group -> page id, from SettingsSearch."""
    text = SEARCH.read_text()
    block = re.search(r"groupPages:\s*\(\{(.*?)\}\)", text, re.S)
    if not block:
        raise SchemaError("could not find groupPages in SettingsSearch.qml")
    routes = dict(re.findall(r'"([a-zA-Z]+)"\s*:\s*"([a-z-]+)"', block.group(1)))
    if not routes:
        raise SchemaError("groupPages matched but contained no routes")
    return routes


def read_entries():
    """Every schema entry, as dicts, in declaration order."""
    text = SCHEMA.read_text()

    # Each entry begins at `key:` and ends at the closing brace of its block.
    # Nested braces (options, hypr) are skipped by counting depth.
    entries = []
    for match in re.finditer(r'\{\s*\n\s*key:\s*"([^"]+)"', text):
        name = match.group(1)
        start = match.start()
        depth = 0
        end = None
        for index in range(start, len(text)):
            if text[index] == "{":
                depth += 1
            elif text[index] == "}":
                depth -= 1
                if depth == 0:
                    end = index
                    break
        if end is None:
            raise SchemaError(f"entry {name!r} is not brace-balanced")
        body = text[start:end]

        def scalar(field):
            found = re.search(rf'\b{field}:\s*("([^"]*)"|[^,\n]+)', body)
            if not found:
                return None
            return (found.group(2) if found.group(2) is not None
                    else found.group(1).strip())

        entry = {
            "key": name,
            "type": scalar("type"),
            "default": scalar("def"),
            "group": scalar("group"),
            "label": scalar("label"),
            "detail": scalar("detail"),
            "unit": scalar("unit"),
            "min": scalar("min"),
            "max": scalar("max"),
            "internal": scalar("internal") == "true",
            "option": scalar("option"),
            "options": re.findall(r'\{\s*value:\s*("?[^",]+)"?,\s*label:\s*"([^"]+)"', body),
        }
        if not entry["type"] or not entry["group"]:
            raise SchemaError(f"entry {name!r} is missing a type or group")
        entries.append(entry)

    if len(entries) < 50:
        raise SchemaError(
            f"only {len(entries)} entries parsed; the schema has far more, so "
            "this reader no longer recognises the file"
        )
    return entries


def render(entries, routes):
    lines = [
        "# Settings reference",
        "",
        "**Generated from `config/dot/quickshell/config/PreferenceSchema.qml`.**",
        "Do not edit this file. Run `quickshell/scripts/panama-settings-docs`",
        "after changing the schema; a contract fails when this copy is stale.",
        "",
        f"{len([e for e in entries if not e['internal']])} settings across "
        f"{len({e['group'] for e in entries if not e['internal']})} groups. "
        f"{len([e for e in entries if e['option']])} of them are applied to the "
        "compositor and confirmed by reading the value back.",
        "",
    ]

    by_group = {}
    for entry in entries:
        by_group.setdefault(entry["group"], []).append(entry)

    for group in sorted(by_group):
        visible = [e for e in by_group[group] if not e["internal"]]
        if not visible:
            continue
        page = routes.get(group)
        title = PAGE_TITLES.get(page, page or "—")
        lines += [f"## {group}", "", f"Found on **{title}**.", ""]
        lines += ["| Setting | Default | What it does |", "|---|---|---|"]
        for entry in visible:
            default = entry["default"] or "—"
            if entry["unit"]:
                default = f"{default} {entry['unit']}"
            if entry["options"]:
                choices = ", ".join(label for _value, label in entry["options"])
                detail = f"{entry['detail'] or ''} Choices: {choices}."
            else:
                detail = entry["detail"] or ""
            if entry["min"] is not None and entry["max"] is not None:
                # Schema details are written without trailing punctuation, so
                # one is added before appending a second sentence.
                if detail and not detail.rstrip().endswith((".", "!", "?")):
                    detail = detail.rstrip() + "."
                detail += f" Range {entry['min']}–{entry['max']}."
            label = entry["label"] or entry["key"]
            compositor = f" `{entry['option']}`" if entry["option"] else ""
            lines.append(
                f"| **{label}**<br>`{entry['key']}`{compositor} | {default} | "
                f"{detail.strip()} |"
            )
        lines.append("")

    return "\n".join(lines) + "\n"


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--check", action="store_true")
    parser.add_argument("--stdout", action="store_true")
    args = parser.parse_args()

    try:
        rendered = render(read_entries(), read_routes())
    except SchemaError as error:
        # Loudly, and without writing. A partial reference is worse than a stale
        # one: stale is caught by --check, partial reads as complete.
        print(f"panama-settings-docs: {error}", file=sys.stderr)
        return 2

    if args.stdout:
        print(rendered, end="")
        return 0

    if args.check:
        if not OUTPUT.exists():
            print("panama-settings-docs: docs/settings.md has never been generated",
                  file=sys.stderr)
            return 1
        if OUTPUT.read_text() != rendered:
            print("panama-settings-docs: docs/settings.md 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.write_text(rendered)
    print(f"wrote {OUTPUT.relative_to(ROOT)}")
    return 0


if __name__ == "__main__":
    sys.exit(main())