test_build_site.py

"""The deployed Pages artifact is minimal, traceable, and privacy-safe."""

from __future__ import annotations

import hashlib
import json
import os
import subprocess
import sys
from html.parser import HTMLParser
from pathlib import Path

import pytest
import tools.build_site as build_site_module
from tools.build_site import build_site

SHA = "a" * 40
PROJECT_ROOT = Path(__file__).resolve().parents[1]
NATIONAL_ROUTE = "/fars/national/"
NATIONAL_MANIFEST_PATH = "fars/national/index.html"
NATIONAL_CANONICAL = "https://nearmiss.chelseakr.com/fars/national/"
APEX_CANONICAL = "https://nearmiss.chelseakr.com/"
STUDIO_CANONICAL = "https://nearmiss.chelseakr.com/studio/"
DOSSIER_CANONICAL = "https://nearmiss.chelseakr.com/dossier/"


class _ApexDocument(HTMLParser):
    def __init__(self) -> None:
        super().__init__()
        self.refreshes: list[str] = []
        self.canonicals: list[str] = []
        self.meta_names: dict[str, list[str]] = {}
        self.meta_properties: dict[str, list[str]] = {}
        self.links: list[str] = []
        self.main_landmarks = 0
        self.redirect_scripts: list[str] = []
        self._script_parts: list[str] | None = None

    def handle_starttag(self, tag: str, attrs_list: list[tuple[str, str | None]]) -> None:
        attrs = {key.casefold(): value or "" for key, value in attrs_list}
        normalized_tag = tag.casefold()
        if normalized_tag == "meta":
            name = attrs.get("name", "").casefold()
            property_name = attrs.get("property", "").casefold()
            if name:
                self.meta_names.setdefault(name, []).append(attrs.get("content", ""))
            if property_name:
                self.meta_properties.setdefault(property_name, []).append(attrs.get("content", ""))
            if attrs.get("http-equiv", "").casefold() == "refresh":
                self.refreshes.append(attrs.get("content", ""))
        elif normalized_tag == "link" and "canonical" in attrs.get("rel", "").casefold().split():
            self.canonicals.append(attrs.get("href", ""))
        elif normalized_tag == "a":
            self.links.append(attrs.get("href", ""))
        elif normalized_tag == "main":
            self.main_landmarks += 1
        elif normalized_tag == "script" and "data-apex-redirect" in attrs:
            self._script_parts = []

    def handle_data(self, data: str) -> None:
        if self._script_parts is not None:
            self._script_parts.append(data)

    def handle_endtag(self, tag: str) -> None:
        if tag.casefold() == "script" and self._script_parts is not None:
            self.redirect_scripts.append("".join(self._script_parts))
            self._script_parts = None


def _assert_product_apex(html: str) -> None:
    document = _ApexDocument()
    document.feed(html)
    document.close()

    assert document.refreshes == []
    assert document.canonicals == [APEX_CANONICAL]
    assert document.main_landmarks == 1
    assert document.redirect_scripts == []
    assert NATIONAL_ROUTE in document.links
    assert f"{NATIONAL_ROUTE}?lang=es" in document.links
    assert "/studio/" in document.links
    assert "/dossier/" in document.links
    assert "/web/index.html" not in document.links
    assert any("DECISION-DOSSIER-TEMPLATE.md" in link for link in document.links)
    assert any("PRODUCT-EXPANSION-PLAN.md" in link for link in document.links)


def test_site_artifact_contains_only_public_surfaces(tmp_path: Path) -> None:
    out = tmp_path / "site"
    manifest = build_site(out, SHA)
    files = set(manifest["files"])

    expected = {
        ".nojekyll",
        "404.html",
        "CNAME",
        "deployment.json",
        "dossier/index.html",
        "index.html",
        NATIONAL_MANIFEST_PATH,
        "studio/index.html",
        "web/index.html",
        "web/us-coverage.html",
        "web/us-coverage.js",
        "web/i18n.js",
        "web/brand.css",
        "web/dossier.js",
        "web/interface.css",
        "web/landing.css",
        "web/style.css",
        "web/studio.js",
        "web/us-coverage.css",
        "web/us-coverage-studio.css",
        "web/workflow.css",
        "web/locales/en.json",
        "web/locales/es.json",
        "web/vendor/brand/clearance-mark.svg",
        "web/vendor/fonts/LICENSE-atkinson-hyperlegible-next.txt",
        "web/vendor/fonts/LICENSE-fragment-mono.txt",
        "web/vendor/fonts/LICENSE-overpass.txt",
        "web/vendor/fonts/atkinson-hyperlegible-next-latin-ext-wght-normal.woff2",
        "web/vendor/fonts/atkinson-hyperlegible-next-latin-wght-normal.woff2",
        "web/vendor/fonts/fragment-mono-latin-400-normal.woff2",
        "web/vendor/fonts/fragment-mono-latin-ext-400-normal.woff2",
        "web/vendor/fonts/overpass-latin-ext-wght-normal.woff2",
        "web/vendor/fonts/overpass-latin-wght-normal.woff2",
        "data/published/fars-state-mode-index.json",
        "data/published/fars-state-mode-index-v2.json",
        "data/published/fars-release-corrections.json",
        "data/published/fars-2020-state-mode.json",
        "data/published/fars-2021-state-mode.json",
        "data/published/fars-2022-state-mode.json",
        "data/published/fars-2023-state-mode.json",
        "data/published/fars-2024-state-mode.json",
        "data/published/fars-2024-state-mode-r2.json",
        "data/published/us-state-boundaries-2024.json",
    }
    assert files == expected

    retired = {
        "web/app.js",
        "web/davis-demo.html",
        "web/embed.css",
        "web/embed.html",
        "web/embed.js",
        "web/nearmiss-embed.js",
        "web/share-card.js",
        "web/submit.html",
        "web/submit.js",
        "web/vendor/leaflet/images/layers-2x.png",
        "web/vendor/leaflet/images/layers.png",
        "web/vendor/leaflet/images/marker-icon-2x.png",
        "web/vendor/leaflet/images/marker-icon.png",
        "web/vendor/leaflet/images/marker-shadow.png",
        "web/vendor/leaflet/leaflet.css",
        "web/vendor/leaflet/leaflet.js",
        "data/published/davis.geojson",
        "data/published/davis.corridors.geojson",
        "data/published/davis.metadata.json",
        "data/published/davis-rates.svg",
        "data/published/davis-ranked.md",
        "data/published/davis-sensitivity.md",
        "data/published/riverside.geojson",
        "data/published/riverside.corridors.geojson",
        "data/published/riverside.metadata.json",
        "data/published/riverside-rates.svg",
        "data/published/riverside-ranked.md",
        "data/published/riverside-sensitivity.md",
        "data/published/preregistration/README.md",
    }
    assert retired.isdisjoint(files)
    assert not any(path.startswith("data/raw/") for path in files)
    assert not any(path.startswith("config/") for path in files)
    assert not any(path.startswith("src/") for path in files)
    assert not any("node_modules" in path for path in files)
    assert not any(path.endswith(".run.json") for path in files)


def test_source_and_built_apex_promote_evidence_to_action_gateway(tmp_path: Path) -> None:
    out = tmp_path / "site"
    build_site(out, SHA)
    source = (build_site_module.ROOT / "index.html").read_text(encoding="utf-8")
    built = (out / "index.html").read_text(encoding="utf-8")

    assert built == source
    _assert_product_apex(source)
    _assert_product_apex(built)


def test_public_catalogs_contain_only_national_messages(tmp_path: Path) -> None:
    out = tmp_path / "site"
    build_site(out, SHA)
    built_catalogs: dict[str, dict[str, str]] = {}

    for locale in build_site_module.PUBLIC_WEB_LOCALES:
        source = json.loads((PROJECT_ROOT / "web" / "locales" / locale).read_text(encoding="utf-8"))
        built = json.loads((out / "web" / "locales" / locale).read_text(encoding="utf-8"))
        expected = {
            key: value
            for key, value in source.items()
            if key.startswith(build_site_module.PUBLIC_WEB_MESSAGE_PREFIX)
        }
        assert built == expected
        assert built
        assert all(key.startswith(build_site_module.PUBLIC_WEB_MESSAGE_PREFIX) for key in built)
        assert any(
            not key.startswith(build_site_module.PUBLIC_WEB_MESSAGE_PREFIX) for key in source
        )
        built_catalogs[locale] = built

    assert set(built_catalogs["en.json"]) == set(built_catalogs["es.json"])


def test_reviewed_not_found_document_is_exact_and_branded(tmp_path: Path) -> None:
    out = tmp_path / "site"
    build_site(out, SHA)
    source = (build_site_module.ROOT / "404.html").read_bytes()
    built = (out / "404.html").read_bytes()

    assert built == source
    html = built.decode("utf-8")
    assert 'content="noindex"' in html
    assert 'rel="canonical"' not in html
    assert 'property="og:url"' not in html
    assert 'href="/web/brand.css"' in html
    assert 'href="/fars/national/"' in html
    assert "Private inputs, working files, and" in html


def test_indexable_pages_publish_canonical_social_metadata(tmp_path: Path) -> None:
    out = tmp_path / "site"
    build_site(out, SHA)
    expected = {
        "index.html": (APEX_CANONICAL, "NearMiss"),
        "dossier/index.html": (DOSSIER_CANONICAL, "NearMiss"),
        "studio/index.html": (STUDIO_CANONICAL, "NearMiss"),
        "web/us-coverage.html": (NATIONAL_CANONICAL, "NearMiss Conflict Atlas"),
        NATIONAL_MANIFEST_PATH: (NATIONAL_CANONICAL, "NearMiss Conflict Atlas"),
    }

    for relative, (canonical, site_name) in expected.items():
        document = _ApexDocument()
        document.feed((out / relative).read_text(encoding="utf-8"))
        document.close()

        assert document.canonicals == [canonical], relative
        assert document.meta_names["description"] and all(document.meta_names["description"]), (
            relative
        )
        assert document.meta_names["twitter:card"] == ["summary"], relative
        assert document.meta_names["twitter:title"] and all(document.meta_names["twitter:title"]), (
            relative
        )
        assert document.meta_names["twitter:description"] and all(
            document.meta_names["twitter:description"]
        ), relative
        assert document.meta_properties["og:type"] == ["website"], relative
        assert document.meta_properties["og:site_name"] == [site_name], relative
        assert document.meta_properties["og:title"] and all(document.meta_properties["og:title"]), (
            relative
        )
        assert document.meta_properties["og:description"] and all(
            document.meta_properties["og:description"]
        ), relative
        assert document.meta_properties["og:url"] == [canonical], relative


def test_legacy_web_index_is_a_noindex_national_redirect(tmp_path: Path) -> None:
    out = tmp_path / "site"
    build_site(out, SHA)
    html = (out / "web/index.html").read_text(encoding="utf-8")
    document = _ApexDocument()
    document.feed(html)
    document.close()

    assert document.canonicals == [NATIONAL_CANONICAL]
    assert len(document.meta_names["robots"]) == 1
    assert "noindex" in document.meta_names["robots"][0].casefold()
    assert len(document.refreshes) == 1
    assert document.refreshes[0].casefold().startswith("0;")
    assert NATIONAL_ROUTE in document.refreshes[0]
    assert NATIONAL_ROUTE in document.links
    assert "riverside" not in html.casefold()


def test_source_only_html_prototypes_are_noindex_and_noncanonical() -> None:
    for relative in ("web/davis-demo.html", "web/submit.html", "web/embed.html"):
        document = _ApexDocument()
        document.feed((PROJECT_ROOT / relative).read_text(encoding="utf-8"))
        document.close()

        assert len(document.meta_names["robots"]) == 1, relative
        assert "noindex" in document.meta_names["robots"][0].casefold(), relative
        assert document.canonicals == [], relative
        assert "og:url" not in document.meta_properties, relative


def test_canonical_national_route_is_a_byte_identical_real_page(tmp_path: Path) -> None:
    out = tmp_path / "site"
    manifest = build_site(out, SHA)
    legacy = out / "web" / "us-coverage.html"
    canonical = out / NATIONAL_MANIFEST_PATH

    assert canonical.read_bytes() == legacy.read_bytes()
    html = canonical.read_text(encoding="utf-8")
    document = _ApexDocument()
    document.feed(html)
    document.close()
    assert document.canonicals == [NATIONAL_CANONICAL]
    assert "<base" not in html.casefold()
    assert 'class="skip-link" href="#main"' in html

    dependencies = {
        "web/brand.css",
        "web/style.css",
        "web/us-coverage.css",
        "web/i18n.js",
        "web/us-coverage.js",
        "web/vendor/brand/clearance-mark.svg",
        "data/published/fars-2024-state-mode-r2.json",
        "data/published/fars-state-mode-index-v2.json",
        "data/published/fars-release-corrections.json",
        "deployment.json",
    }
    assert dependencies <= set(manifest["files"])
    for path in dependencies:
        assert f'="/{path}"' in html

    font_dependencies = {
        "web/vendor/fonts/overpass-latin-wght-normal.woff2",
        "web/vendor/fonts/overpass-latin-ext-wght-normal.woff2",
        "web/vendor/fonts/atkinson-hyperlegible-next-latin-wght-normal.woff2",
        "web/vendor/fonts/atkinson-hyperlegible-next-latin-ext-wght-normal.woff2",
        "web/vendor/fonts/fragment-mono-latin-400-normal.woff2",
        "web/vendor/fonts/fragment-mono-latin-ext-400-normal.woff2",
    }
    assert font_dependencies <= set(manifest["files"])
    brand_css = (out / "web" / "brand.css").read_text(encoding="utf-8")
    for path in font_dependencies:
        assert f'url("/{path}")' in brand_css


def test_deployment_stamp_and_manifest_hashes_are_exact(tmp_path: Path) -> None:
    out = tmp_path / "site"
    manifest = build_site(out, SHA)
    deployment = json.loads((out / "deployment.json").read_text(encoding="utf-8"))
    assert deployment["source_sha"] == SHA
    assert deployment["source_url"].endswith(SHA)

    for relative, expected in manifest["files"].items():
        assert hashlib.sha256((out / relative).read_bytes()).hexdigest() == expected

    artifact_files = {path.relative_to(out).as_posix() for path in out.rglob("*") if path.is_file()}
    assert set(manifest["files"]) == artifact_files - {"site-manifest.json"}
    assert "site-manifest.json" in artifact_files


def test_deploy_verifier_hash_binds_every_national_runtime_dependency() -> None:
    workflow = (PROJECT_ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
    required_specs = {
        "index.html|",
        "404.html|404.html",
        "deployment.json|deployment.json",
        "web/index.html|web/index.html",
        "web/us-coverage.html|web/us-coverage.html",
        "fars/national/index.html|fars/national/",
        "dossier/index.html|dossier/",
        "studio/index.html|studio/",
        "web/dossier.js|web/dossier.js",
        "web/studio.js|web/studio.js",
        "web/workflow.css|web/workflow.css",
        "web/interface.css|web/interface.css",
        "web/us-coverage.js|web/us-coverage.js",
        "web/i18n.js|web/i18n.js",
        "web/locales/en.json|web/locales/en.json",
        "web/locales/es.json|web/locales/es.json",
        "web/us-coverage.css|web/us-coverage.css",
        "web/us-coverage-studio.css|web/us-coverage-studio.css",
        "web/style.css|web/style.css",
        "data/published/fars-state-mode-index.json|data/published/fars-state-mode-index.json",
        "data/published/fars-2024-state-mode.json|data/published/fars-2024-state-mode.json",
        "data/published/fars-state-mode-index-v2.json|data/published/fars-state-mode-index-v2.json",
        "data/published/fars-release-corrections.json|data/published/fars-release-corrections.json",
        "data/published/us-state-boundaries-2024.json|data/published/us-state-boundaries-2024.json",
    }
    for spec in required_specs:
        assert f"'{spec}'" in workflow
    assert "'data/published/davis.geojson|data/published/davis.geojson'" not in workflow
    assert "'data/published/riverside.geojson|data/published/riverside.geojson'" not in workflow
    assert "'web/app.js|web/app.js'" not in workflow
    assert "'web/embed.html|web/embed.html'" not in workflow
    assert "'web/submit.html|web/submit.html'" not in workflow
    assert "'web/vendor/leaflet/leaflet.js|web/vendor/leaflet/leaflet.js'" not in workflow
    assert '[ "$live_sha" != "$expected_sha" ]' in workflow
    assert '[ "$live_sha" != "$manifest_artifact_sha" ]' in workflow
    assert (
        'boundary_sha256="705219b3339077f1d03466391bb286fe7f1841298fc0bcce948de1d8c66df25d"'
        in workflow
    )
    rebuild = workflow.index("Rebuild and byte-verify before obtaining deploy authority")
    authenticate = workflow.index("Authenticate to AWS with GitHub OIDC")
    publish = workflow.index("Publish the exact artifact to the private origin")
    assert rebuild < authenticate < publish
    assert "diff --recursive --brief _expected-site _site" in workflow
    assert workflow.count("for host_control in .nojekyll CNAME") == 2
    assert "--delete --exclude '.nojekyll' --exclude 'CNAME'" in workflow
    assert "public, max-age=0, must-revalidate" in workflow
    for mime_spec in (
        "*.html|text/html; charset=utf-8",
        "*.js|application/javascript; charset=utf-8",
        "*.css|text/css; charset=utf-8",
        "*.json|application/json; charset=utf-8",
        "*.geojson|application/geo+json",
        "*.svg|image/svg+xml",
        "*.woff2|font/woff2",
        "*.png|image/png",
    ):
        assert f"'{mime_spec}'" in workflow


def test_cloudfront_origin_fails_closed_before_dns_cutover() -> None:
    template = (PROJECT_ROOT / "infra" / "aws-static-site.yml").read_text(encoding="utf-8")
    runbook = (PROJECT_ROOT / "infra" / "README.md").read_text(encoding="utf-8")

    assert 'Default: "false"' in template
    assert "Condition: PublishDnsRecords" in template
    assert "ResponsePagePath: /404.html" in template
    assert "ErrorCode: 403" in template
    assert "ErrorCode: 404" in template
    assert "BucketOwnerEnforced" in template
    assert "BlockPublicPolicy: true" in template
    assert "environment:production" in template
    assert "Header: Cache-Control" in template
    assert "Value: public, max-age=0, must-revalidate" in template
    assert "QueryStringBehavior: whitelist" in template
    assert "- verify" in template
    assert "CachePolicyId: !Ref SiteCachePolicy" in template
    assert "us-east-1" in runbook
    assert "exact `main` branch policy" in runbook


def test_build_is_byte_stable_for_same_commit(tmp_path: Path) -> None:
    first = tmp_path / "first"
    second = tmp_path / "second"
    build_site(first, SHA)
    build_site(second, SHA)
    assert (first / "site-manifest.json").read_bytes() == (
        second / "site-manifest.json"
    ).read_bytes()


def test_pages_builder_runs_without_site_packages(tmp_path: Path) -> None:
    """The clean Pages job must not depend on packages preinstalled on its runner."""
    out = tmp_path / "isolated-site"
    result = subprocess.run(
        [
            sys.executable,
            "-S",
            str(PROJECT_ROOT / "tools" / "build_site.py"),
            "--out",
            str(out),
            "--sha",
            SHA,
        ],
        cwd=PROJECT_ROOT,
        check=False,
        capture_output=True,
        text=True,
    )

    assert result.returncode == 0, result.stderr
    manifest = json.loads((out / "site-manifest.json").read_text(encoding="utf-8"))
    assert manifest["source_sha"] == SHA


def _minimal_site_source(root: Path) -> None:
    (root / "data" / "published").mkdir(parents=True)
    (root / "index.html").write_text("index", encoding="utf-8")
    (root / "404.html").write_text("not found", encoding="utf-8")
    (root / "CNAME").write_text("example.test\n", encoding="utf-8")
    for relative in build_site_module.PUBLIC_WEB_FILES:
        destination = root / "web" / relative
        destination.parent.mkdir(parents=True, exist_ok=True)
        content = "{}" if destination.suffix == ".json" else "public"
        destination.write_text(content, encoding="utf-8")
    for relative in ("studio.html", "dossier.html"):
        (root / "web" / relative).write_text("public workflow", encoding="utf-8")
    for locale in build_site_module.PUBLIC_WEB_LOCALES:
        destination = root / "web" / "locales" / locale
        destination.parent.mkdir(parents=True, exist_ok=True)
        destination.write_text('{"web.coverage.title":"National evidence"}', encoding="utf-8")


def _copy_current_fars_release_set(destination: Path) -> None:
    source = PROJECT_ROOT / "data" / "published"
    for name in build_site_module.PUBLIC_FARS_FILES:
        (destination / name).write_bytes((source / name).read_bytes())


@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks unavailable")
def test_build_ignores_unallowlisted_published_symlink_escape(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    root = tmp_path / "repo"
    _minimal_site_source(root)
    private = root / "data" / "raw" / "precise.json"
    private.parent.mkdir(parents=True)
    private.write_text('{"precise": true}', encoding="utf-8")
    (root / "data" / "published" / "escape.json").symlink_to(private)
    _copy_current_fars_release_set(root / "data" / "published")
    monkeypatch.setattr(build_site_module, "ROOT", root)

    out = tmp_path / "site"
    manifest = build_site_module.build_site(out, SHA)

    assert "data/published/escape.json" not in manifest["files"]
    assert not (out / "data" / "published" / "escape.json").exists()


@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks unavailable")
def test_build_rejects_symlink_for_allowlisted_published_file(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    root = tmp_path / "repo"
    _minimal_site_source(root)
    published = root / "data" / "published"
    _copy_current_fars_release_set(published)
    boundary = published / "us-state-boundaries-2024.json"
    private = root / "data" / "raw" / "precise.json"
    private.parent.mkdir(parents=True)
    private.write_text('{"precise": true}', encoding="utf-8")
    boundary.unlink()
    boundary.symlink_to(private)
    monkeypatch.setattr(build_site_module, "ROOT", root)

    with pytest.raises(ValueError, match="refusing symlink"):
        build_site_module.build_site(tmp_path / "site", SHA)


@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks unavailable")
def test_build_rejects_symlink_for_allowlisted_web_file(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    root = tmp_path / "repo"
    _minimal_site_source(root)
    private = root / "private.js"
    private.write_text("private", encoding="utf-8")
    public_script = root / "web" / "us-coverage.js"
    public_script.unlink()
    public_script.symlink_to(private)
    _copy_current_fars_release_set(root / "data" / "published")
    monkeypatch.setattr(build_site_module, "ROOT", root)

    with pytest.raises(ValueError, match="refusing symlink"):
        build_site_module.build_site(tmp_path / "site", SHA)


def test_copy_rejects_lexical_path_that_resolves_outside_root(tmp_path: Path) -> None:
    allowed = tmp_path / "public"
    allowed.mkdir()
    private = tmp_path / "private.json"
    private.write_text('{"precise": true}', encoding="utf-8")

    with pytest.raises(ValueError, match="escapes"):
        build_site_module._copy_file(
            allowed / ".." / private.name,
            tmp_path / "site" / "leak.json",
            allowed_root=allowed,
        )


def test_build_rejects_unindexed_fars_json_before_published_copy(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    root = tmp_path / "repo"
    _minimal_site_source(root)
    published = root / "data" / "published"
    _copy_current_fars_release_set(published)
    (published / "fars-2023-debug.json").write_text(
        '{"raw_case_ids":["private-case-id"]}\n',
        encoding="utf-8",
    )
    monkeypatch.setattr(build_site_module, "ROOT", root)

    out = tmp_path / "site"
    with pytest.raises(ValueError, match="FARS namespace"):
        build_site_module.build_site(out, SHA)
    assert not (out / "data" / "published").exists()