build_demo_bundle.py

#!/usr/bin/env python3
"""Build the browser demo's deterministic, offline-safe data bundle.

The JSON files remain canonical. ``data/demo-data.js`` is a generated
JavaScript assignment so ``index.html`` can be opened directly from disk
without browser-blocked ``file://`` fetches.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import sys
from pathlib import Path


ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "src"))

from permit_pathways.explanations import load_explanations  # noqa: E402
from permit_pathways.screening import load_rules  # noqa: E402

OUTPUT = ROOT / "data" / "demo-data.js"
INPUTS = {
    "statewide_rules": Path("data/rules/statewide.json"),
    "davis_rules": Path("data/rules/davis.json"),
    "woodland_rules": Path("data/rules/woodland.json"),
    "golden": Path("data/golden/example.json"),
    "sources": Path("data/sources.json"),
    "checks": Path("data/conformance/checks.json"),
    "registry": Path("data/jurisdictions/registry.json"),
    "letters": Path("data/jurisdictions/hcd-letters.json"),
    "scans": Path("data/conformance/results/index.json"),
    "plain_language": Path("data/explanations/plain-language.json"),
}


def build_bundle(root: Path = ROOT) -> str:
    """Return the generated bundle text from canonical JSON inputs."""

    rules = load_rules(root / "data" / "rules")
    load_explanations(
        root / "data" / "explanations" / "plain-language.json",
        rules,
    )

    payload: dict[str, object] = {}
    digests: dict[str, str] = {}
    for key, relative_path in INPUTS.items():
        raw = (root / relative_path).read_bytes()
        payload[key] = json.loads(raw)
        digests[relative_path.as_posix()] = hashlib.sha256(raw).hexdigest()

    payload["_meta"] = {
        "format_version": 1,
        "generated_from": digests,
    }
    encoded = json.dumps(
        payload,
        ensure_ascii=True,
        separators=(",", ":"),
        sort_keys=True,
    )
    return (
        "/* Generated by scripts/build_demo_bundle.py; do not edit by hand. */\n"
        f"globalThis.PERMIT_PATHWAYS_DEMO_DATA={encoded};\n"
    )


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--check",
        action="store_true",
        help="fail if the committed bundle differs from the canonical JSON",
    )
    args = parser.parse_args()
    expected = build_bundle()

    if args.check:
        if not OUTPUT.exists() or OUTPUT.read_text(encoding="utf-8") != expected:
            print(
                "data/demo-data.js is out of date; "
                "run python3 scripts/build_demo_bundle.py"
            )
            return 1
        print("data/demo-data.js is in sync")
        return 0

    OUTPUT.write_text(expected, encoding="utf-8")
    print(f"wrote {OUTPUT.relative_to(ROOT)}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())