Skip to content

A visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.

45.7 KB
Raw Blame
"""Tests for the static website builder."""

from __future__ import annotations

import hashlib
import json
import logging
import re
import shutil
import subprocess
import sys
from pathlib import Path

import pytest
from bs4 import BeautifulSoup

sys.path.insert(0, str(Path(__file__).parent.parent))

import check_cross_references
from build_website import (
    BuildState,
    PageInfo,
    WebsiteConfig,
    _disambiguate_url,
    build_website,
    collect_folder_markdown,
    collect_pages,
    derive_page_title,
    heading_to_anchor,
    is_excluded_dir,
    is_excluded_top_level_markdown,
    relative_link,
    render_markdown,
    replace_mermaid_blocks,
    rewrite_links,
    source_to_site_url,
)

# Invisible characters, spelled as escapes so editors can't strip them silently.
ZWNJ = "\u200c"  # zero-width non-joiner (Persian, kept in GitHub heading ids)
ZWJ = "\u200d"  # zero-width joiner (stripped)

# =============================================================================
# Fixtures
# =============================================================================


@pytest.fixture
def site_root(tmp_path: Path) -> Path:
    """Create a minimal repo-like tree the builder can render."""
    (tmp_path / "README.md").write_text(
        "<picture>\n"
        '  <source media="(prefers-color-scheme: dark)" '
        'srcset="resources/logos/claude-howto-logo-dark.svg">\n'
        '  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">\n'
        "</picture>\n\n"
        "# Home Page\n\nWelcome. See [Slash Commands](01-slash-commands/README.md).\n"
        "Also check [script](scripts/build.sh) and the [logo](resources/logos/logo.svg).\n"
    )
    (tmp_path / "LEARNING-ROADMAP.md").write_text(
        "# Learning Roadmap\n\nLink back to [Home](README.md#home-page).\n"
    )
    (tmp_path / "CONTRIBUTING.md").write_text("# Contributing\n\nHelp improve docs.")
    (tmp_path / "CLAUDE.md").write_text("# Internal Agent Notes\n")
    (tmp_path / "update-plan-2026-05-02.md").write_text("# Temporary Plan\n")

    sc = tmp_path / "01-slash-commands"
    sc.mkdir()
    (sc / "README.md").write_text(
        "# Slash Commands\n\n## Advanced Usage\n\nMermaid time:\n\n```mermaid\nflowchart LR\nA-->B\n```\n\n"
        "See [example](example.md).\n"
    )
    (sc / "example.md").write_text("# Example\n\nGo back to [overview](README.md).\n")

    # Non-markdown repo files
    scripts_dir = tmp_path / "scripts"
    scripts_dir.mkdir()
    (scripts_dir / "build.sh").write_text("#!/bin/bash\necho hi\n")

    logos = tmp_path / "resources" / "logos"
    logos.mkdir(parents=True)
    (logos / "logo.svg").write_text("<svg></svg>")
    (logos / "claude-howto-logo.svg").write_text("<svg></svg>")
    (logos / "claude-howto-logo-dark.svg").write_text("<svg></svg>")

    return tmp_path


@pytest.fixture
def logger() -> logging.Logger:
    return logging.getLogger("test_build_website")


# =============================================================================
# heading_to_anchor parity with check_cross_references
# =============================================================================


class TestHeadingToAnchor:
    def test_simple_title(self) -> None:
        assert heading_to_anchor("Hello World") == "hello-world"

    def test_punctuation_removed(self) -> None:
        assert heading_to_anchor("What's Next?") == "whats-next"

    def test_unicode_preserved(self) -> None:
        assert heading_to_anchor("Hướng dẫn") == "hướng-dẫn"

    def test_emoji_stripped(self) -> None:
        # The validator strips emoji; we mirror that exactly.
        assert heading_to_anchor("🔥 Trending") == "-trending"

    def test_zero_width_non_joiner_preserved(self) -> None:
        # Persian uses U+200C inside words; GitHub keeps it in heading ids.
        assert (
            heading_to_anchor(f"نام{ZWNJ}گذاری فایل و پوشه")
            == f"نام{ZWNJ}گذاری-فایل-و-پوشه"
        )

    @pytest.mark.parametrize(
        "heading",
        [
            f"نام{ZWNJ}گذاری فایل و پوشه",
            "[v2.1.245] — 2026-08-25",
            f"A{ZWJ}B test",
            "Hướng dẫn bắt đầu nhanh",
        ],
    )
    def test_matches_validator(self, heading: str) -> None:
        assert heading_to_anchor(heading) == check_cross_references.heading_to_anchor(
            heading
        )


# =============================================================================
# source_to_site_url
# =============================================================================


class TestSourceToSiteUrl:
    def test_root_readme_maps_to_index(self) -> None:
        assert source_to_site_url("README.md") == "index.html"

    def test_folder_readme_maps_to_folder_index(self) -> None:
        assert (
            source_to_site_url("01-slash-commands/README.md")
            == "01-slash-commands/index.html"
        )

    def test_other_markdown_uses_html_extension(self) -> None:
        assert (
            source_to_site_url("01-slash-commands/example.md")
            == "01-slash-commands/example.html"
        )


class TestDisambiguateUrl:
    def test_no_collision_passes_through(self) -> None:
        used: set[str] = {"foo.html"}
        assert _disambiguate_url("bar.html", used, "bar.md") == "bar.html"

    def test_case_insensitive_collision_disambiguated(self) -> None:
        # README → index.html lands first; INDEX.md (case-insensitive collision)
        # must get a suffix on macOS / Windows filesystems.
        used: set[str] = {"index.html"}
        result = _disambiguate_url("INDEX.html", used, "INDEX.md")
        assert result.lower() != "index.html"
        assert result.endswith(".html")


# =============================================================================
# relative_link
# =============================================================================


class TestRelativeLink:
    def test_same_directory(self) -> None:
        assert relative_link("01/index.html", "01/example.html") == "example.html"

    def test_anchor_appended(self) -> None:
        assert (
            relative_link("01/index.html", "02/index.html", "#intro")
            == "../02/index.html#intro"
        )

    def test_self_link_returns_anchor_only(self) -> None:
        assert relative_link("01/index.html", "01/index.html", "#section") == "#section"

    def test_parent_directory(self) -> None:
        assert relative_link("01/index.html", "index.html") == "../index.html"


# =============================================================================
# is_excluded_dir
# =============================================================================


class TestIsExcludedDir:
    def test_hidden_dirs_excluded(self) -> None:
        assert is_excluded_dir(".git") is True

    def test_known_dir_excluded(self) -> None:
        assert is_excluded_dir("node_modules") is True

    def test_chapter_dir_kept(self) -> None:
        assert is_excluded_dir("01-slash-commands") is False


class TestIsExcludedTopLevelMarkdown:
    def test_internal_agent_file_excluded(self) -> None:
        assert is_excluded_top_level_markdown("CLAUDE.md") is True

    def test_temporary_update_plan_excluded(self) -> None:
        assert is_excluded_top_level_markdown("update-plan-2026-05-02.md") is True

    def test_project_doc_included(self) -> None:
        assert is_excluded_top_level_markdown("CONTRIBUTING.md") is False


# =============================================================================
# collect_folder_markdown
# =============================================================================


class TestCollectFolderMarkdown:
    def test_readme_first(self, tmp_path: Path) -> None:
        (tmp_path / "b.md").write_text("# B")
        (tmp_path / "README.md").write_text("# Readme")
        (tmp_path / "a.md").write_text("# A")
        files = collect_folder_markdown(tmp_path)
        assert [f.name for f in files] == ["README.md", "a.md", "b.md"]

    def test_skips_hidden_subdirs(self, tmp_path: Path) -> None:
        (tmp_path / "README.md").write_text("# R")
        hidden = tmp_path / ".cache"
        hidden.mkdir()
        (hidden / "junk.md").write_text("# junk")
        files = collect_folder_markdown(tmp_path)
        assert [f.name for f in files] == ["README.md"]


class TestCollectPages:
    def test_additional_top_level_docs_are_collected(
        self, site_root: Path, logger: logging.Logger
    ) -> None:
        state = collect_pages(
            WebsiteConfig(root_path=site_root, output_path=site_root / "site"), logger
        )
        assert "CONTRIBUTING.md" in state.source_to_url
        assert state.source_to_url["CONTRIBUTING.md"] == "CONTRIBUTING.html"
        assert "CLAUDE.md" not in state.source_to_url
        assert "update-plan-2026-05-02.md" not in state.source_to_url


# =============================================================================
# derive_page_title
# =============================================================================


class TestDerivePageTitle:
    def test_uses_h1(self, tmp_path: Path) -> None:
        f = tmp_path / "f.md"
        f.write_text("Some intro\n# The Title\nBody")
        assert derive_page_title(f, "Default") == "The Title"

    def test_falls_back_when_no_h1(self, tmp_path: Path) -> None:
        f = tmp_path / "f.md"
        f.write_text("No heading here")
        assert derive_page_title(f, "Default") == "Default"


# =============================================================================
# replace_mermaid_blocks
# =============================================================================


class TestReplaceMermaidBlocks:
    def test_replaces_fence(self) -> None:
        md = "Before\n\n```mermaid\nflowchart LR\nA-->B\n```\n\nAfter"
        out = replace_mermaid_blocks(md)
        assert '<pre class="mermaid">' in out
        assert "flowchart LR" in out
        assert "```mermaid" not in out

    def test_escapes_html(self) -> None:
        md = "```mermaid\nA --> B<C>\n```\n"
        out = replace_mermaid_blocks(md)
        assert "&lt;C&gt;" in out


# =============================================================================
# render_markdown
# =============================================================================


class TestRenderMarkdown:
    def test_heading_gets_github_anchor(self) -> None:
        html_content = render_markdown("# Hello World\n\nBody")
        assert 'id="hello-world"' in html_content

    def test_duplicate_headings_get_suffix(self) -> None:
        html_content = render_markdown("# Hi\n\n# Hi\n")
        assert 'id="hi"' in html_content
        assert 'id="hi-1"' in html_content


# =============================================================================
# rewrite_links
# =============================================================================


class TestRewriteLinks:
    def _state(self) -> BuildState:
        state = BuildState()
        state.source_to_url = {
            "README.md": "index.html",
            "01-slash-commands/README.md": "01-slash-commands/index.html",
        }
        return state

    def _config(self, root: Path) -> WebsiteConfig:
        return WebsiteConfig(
            root_path=root,
            output_path=root / "out",
            repo_url="https://github.com/example/repo",
            branch="main",
        )

    def test_internal_markdown_link_rewritten(
        self, tmp_path: Path, logger: logging.Logger
    ) -> None:
        (tmp_path / "README.md").write_text("# Home")
        (tmp_path / "01-slash-commands").mkdir()
        (tmp_path / "01-slash-commands" / "README.md").write_text("# Slash")
        page = PageInfo(
            source=tmp_path / "README.md",
            rel_source="README.md",
            output_url="index.html",
            title="Home",
            section="Introduction",
            is_section_index=True,
        )
        html_in = '<a href="01-slash-commands/README.md">go</a>'
        out = rewrite_links(
            html_in, page, self._state(), self._config(tmp_path), logger
        )
        assert "01-slash-commands/index.html" in out
        assert ".md" not in out

    def test_anchor_preserved(self, tmp_path: Path, logger: logging.Logger) -> None:
        (tmp_path / "README.md").write_text("# Home")
        (tmp_path / "01-slash-commands").mkdir()
        (tmp_path / "01-slash-commands" / "README.md").write_text("# Slash")
        page = PageInfo(
            source=tmp_path / "README.md",
            rel_source="README.md",
            output_url="index.html",
            title="Home",
            section="Introduction",
            is_section_index=True,
        )
        html_in = '<a href="01-slash-commands/README.md#run">go</a>'
        out = rewrite_links(
            html_in, page, self._state(), self._config(tmp_path), logger
        )
        assert "#run" in out

    def test_non_markdown_link_uses_github_blob(
        self, tmp_path: Path, logger: logging.Logger
    ) -> None:
        (tmp_path / "scripts").mkdir()
        (tmp_path / "scripts" / "build.sh").write_text("#!/bin/bash")
        (tmp_path / "README.md").write_text("# Home")
        page = PageInfo(
            source=tmp_path / "README.md",
            rel_source="README.md",
            output_url="index.html",
            title="Home",
            section="Introduction",
            is_section_index=True,
        )
        html_in = '<a href="scripts/build.sh">script</a>'
        out = rewrite_links(
            html_in, page, self._state(), self._config(tmp_path), logger
        )
        assert "github.com/example/repo/blob/main/scripts/build.sh" in out
        assert 'target="_blank"' in out

    def test_repo_directory_link_uses_github_tree(
        self, tmp_path: Path, logger: logging.Logger
    ) -> None:
        (tmp_path / "scripts").mkdir()
        (tmp_path / "README.md").write_text("# Home")
        page = PageInfo(
            source=tmp_path / "README.md",
            rel_source="README.md",
            output_url="index.html",
            title="Home",
            section="Introduction",
            is_section_index=True,
        )
        html_in = '<a href="scripts/">scripts</a>'
        out = rewrite_links(
            html_in, page, self._state(), self._config(tmp_path), logger
        )
        assert "github.com/example/repo/tree/main/scripts" in out
        assert "github.com/example/repo/blob/main/scripts" not in out

    def test_repo_root_link_uses_github_tree(
        self, tmp_path: Path, logger: logging.Logger
    ) -> None:
        (tmp_path / "README.md").write_text("# Home")
        page = PageInfo(
            source=tmp_path / "README.md",
            rel_source="README.md",
            output_url="index.html",
            title="Home",
            section="Introduction",
            is_section_index=True,
        )
        html_in = '<a href=".">repo root</a>'
        out = rewrite_links(
            html_in, page, self._state(), self._config(tmp_path), logger
        )
        assert "github.com/example/repo/tree/main" in out
        assert "github.com/example/repo/blob/main/." not in out

    def test_external_link_left_alone(
        self, tmp_path: Path, logger: logging.Logger
    ) -> None:
        page = PageInfo(
            source=tmp_path / "README.md",
            rel_source="README.md",
            output_url="index.html",
            title="Home",
            section="Introduction",
            is_section_index=True,
        )
        (tmp_path / "README.md").write_text("# Home")
        html_in = '<a href="https://anthropic.com">site</a>'
        out = rewrite_links(
            html_in, page, self._state(), self._config(tmp_path), logger
        )
        assert 'href="https://anthropic.com"' in out


# =============================================================================
# Full build smoke test
# =============================================================================


class TestBuildWebsite:
    def test_smoke_build(self, site_root: Path, logger: logging.Logger) -> None:
        out_dir = site_root / "site"
        config = WebsiteConfig(
            root_path=site_root,
            output_path=out_dir,
            repo_url="https://github.com/example/repo",
            branch="main",
        )

        build_website(config, logger, skip_vendor=True)

        # Index page rendered
        index = out_dir / "index.html"
        assert index.exists()
        index_html = index.read_text(encoding="utf-8")
        assert "Home Page" in index_html
        assert "01-slash-commands/index.html" in index_html
        assert "CONTRIBUTING.html" in index_html
        # Non-markdown link rewritten to GitHub
        assert "github.com/example/repo/blob/main/scripts/build.sh" in index_html
        # <source srcset> inside <picture> rewritten to point at assets/
        assert 'srcset="assets/resources/logos/' in index_html

        # Additional top-level docs rendered
        assert (out_dir / "CONTRIBUTING.html").exists()
        assert not (out_dir / "CLAUDE.html").exists()
        assert not (out_dir / "update-plan-2026-05-02.html").exists()

        # Folder index rendered
        sc_index = out_dir / "01-slash-commands" / "index.html"
        assert sc_index.exists()
        sc_html = sc_index.read_text(encoding="utf-8")
        # Mermaid block became a <pre class="mermaid"> block
        assert '<pre class="mermaid">' in sc_html
        # Sibling markdown link rewritten
        assert "example.html" in sc_html

        # Example page rendered
        example_page = out_dir / "01-slash-commands" / "example.html"
        assert example_page.exists()
        example_html = example_page.read_text(encoding="utf-8")
        # Back-link to README rewrites to index.html
        assert "index.html" in example_html

        # Diagrams render with the self-hosted Pele bundle, not Mermaid.js.
        assert "vendor/pele/pele.global.js" in sc_html
        assert "pele.mount(" in sc_html
        assert "vendor/mermaid/" not in sc_html
        # A diagram Pele rejects (reported on m.error, not thrown) gets its
        # source back instead of a bare error message.
        assert "m.error !== undefined" in sc_html
        assert "container.replaceWith(pre)" in sc_html
        # Zoom stays on, and zoom makes a shrunk diagram a tab stop: every
        # <svg> Pele draws (it draws a new one on resize and font load) is
        # named in onRender after the nearest heading.
        assert "zoom: 'auto'" in sc_html
        assert "onRender: nameDiagram" in sc_html
        assert "svg.setAttribute('aria-label'" in sc_html
        assert "svg.hasAttribute('aria-labelledby')" in sc_html

        # Stylesheet copied into assets
        assert (out_dir / "assets" / "site.css").exists()
        # Logo copied into assets
        assert (out_dir / "assets" / "resources" / "logos" / "logo.svg").exists()
        # Template no longer references third-party CDNs.
        for hostile in (
            "cdn.tailwindcss.com",
            "cdn.jsdelivr.net",
            "fonts.googleapis.com",
        ):
            assert hostile not in index_html, (
                f"Built HTML still references {hostile} — CDN should be self-hosted"
            )


# =============================================================================
# vendor_assets module smoke test
# =============================================================================


class TestVendorAssets:
    def test_module_exports(self) -> None:
        """vendor_assets exposes the API build_website depends on."""
        import vendor_assets

        for attr in (
            "build_tailwind_css",
            "fetch_pele",
            "ensure_pele_bundle",
            "fetch_fonts",
            "write_vendor_manifest",
            "ensure_tailwind_binary",
            "TAILWIND_VERSION",
            "PELE_VERSION",
        ):
            assert hasattr(vendor_assets, attr), f"missing {attr}"
        for gone in ("fetch_mermaid", "MERMAID_VERSION", "MERMAID_URL"):
            assert not hasattr(vendor_assets, gone), f"{gone} should be removed"

    def test_pele_version_is_pinned_exactly(self) -> None:
        """The Pele bundle is pinned to an exact X.Y.Z with a digest per file."""
        import re

        import vendor_assets

        assert re.fullmatch(r"\d+\.\d+\.\d+", vendor_assets.PELE_VERSION)
        assert f"pele@{vendor_assets.PELE_VERSION}" in vendor_assets.PELE_BASE_URL
        assert set(vendor_assets.PELE_FILES) == {
            "dist/pele.js",
            "dist/pele.global.js",
            "LICENSE",
        }
        for digest in vendor_assets.PELE_FILES.values():
            assert re.fullmatch(r"[0-9a-f]{64}", digest)

    def test_detect_tailwind_asset_name(self) -> None:
        """Platform detection returns one of the known asset names."""
        from vendor_assets import _detect_tailwind_asset_name

        known = {
            "tailwindcss-macos-arm64",
            "tailwindcss-macos-x64",
            "tailwindcss-linux-arm64",
            "tailwindcss-linux-armv7",
            "tailwindcss-linux-x64",
            "tailwindcss-windows-x64.exe",
        }
        assert _detect_tailwind_asset_name() in known

    def test_download_rejects_non_http_scheme(self, tmp_path: Path) -> None:
        """The _download helper refuses file:/ftp:/etc. — defense-in-depth."""
        from vendor_assets import _download

        with pytest.raises(ValueError, match="non-HTTP URL"):
            _download("file:///etc/passwd", tmp_path / "out.bin")

    def test_font_css_cache_uses_sha256_url_key(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, logger: logging.Logger
    ) -> None:
        """Font CSS variants get distinct ten-character SHA-256 cache keys."""
        import vendor_assets

        cache_dir = tmp_path / "vendor-cache"
        monkeypatch.setattr(vendor_assets, "_vendor_cache_dir", lambda: cache_dir)
        urls = [
            vendor_assets.GOOGLE_FONTS_CSS_URL,
            vendor_assets.GOOGLE_FONTS_CSS_URL + "&variant=regression",
        ]
        downloads: list[str] = []

        def fake_download(
            url: str, dest: Path, headers: dict[str, str] | None = None
        ) -> None:
            del headers
            downloads.append(url)
            dest.parent.mkdir(parents=True, exist_ok=True)
            dest.write_text(f"/* {url} */", encoding="utf-8")

        monkeypatch.setattr(vendor_assets, "_download", fake_download)

        keys: list[str] = []
        for index, url in enumerate(urls):
            monkeypatch.setattr(vendor_assets, "GOOGLE_FONTS_CSS_URL", url)
            vendor_assets.fetch_fonts(tmp_path / f"output-{index}", logger)
            key = hashlib.sha256(url.encode("utf-8")).hexdigest()[:10]
            keys.append(key)
            assert len(key) == 10
            assert (cache_dir / "fonts" / f"fonts-{key}.css").is_file()

        assert keys[0] != keys[1]
        assert downloads == urls


# =============================================================================
# Pele bundle: pinned, sha256-verified on every use
# =============================================================================


_FAKE_PELE = {
    "dist/pele.js": b"export function render() {}\n",
    "dist/pele.global.js": b"var pele = (() => ({}))();\n",
    "LICENSE": b"MIT License\n",
}


class TestPeleBundle:
    @pytest.fixture
    def fake_pele(
        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
    ) -> tuple[Path, list[str], dict[str, bytes]]:
        """Point the vendor cache at tmp_path and serve fake bundle bytes."""
        import vendor_assets

        cache_root = tmp_path / "vendor-cache"
        monkeypatch.setattr(vendor_assets, "_vendor_cache_dir", lambda: cache_root)
        monkeypatch.setattr(
            vendor_assets,
            "PELE_FILES",
            {rel: hashlib.sha256(data).hexdigest() for rel, data in _FAKE_PELE.items()},
        )
        served = dict(_FAKE_PELE)
        downloads: list[str] = []

        def fake_download(
            url: str, dest: Path, headers: dict[str, str] | None = None
        ) -> None:
            del headers
            rel = url.removeprefix(vendor_assets.PELE_BASE_URL + "/")
            downloads.append(rel)
            dest.parent.mkdir(parents=True, exist_ok=True)
            dest.write_bytes(served[rel])

        monkeypatch.setattr(vendor_assets, "_download", fake_download)
        cache = cache_root / "pele" / vendor_assets.PELE_VERSION
        return cache, downloads, served

    def test_good_bytes_cached_and_not_redownloaded(
        self,
        fake_pele: tuple[Path, list[str], dict[str, bytes]],
        logger: logging.Logger,
    ) -> None:
        import vendor_assets

        cache, downloads, _ = fake_pele
        assert vendor_assets.ensure_pele_bundle(logger) == cache
        assert sorted(downloads) == sorted(_FAKE_PELE)
        assert (cache / "pele.mjs").read_bytes() == _FAKE_PELE["dist/pele.js"]
        assert (cache / "LICENSE").read_bytes() == _FAKE_PELE["LICENSE"]

        downloads.clear()
        vendor_assets.ensure_pele_bundle(logger)
        assert downloads == [], "verified cache must not be downloaded again"

    def test_corrupted_cache_is_redownloaded(
        self,
        fake_pele: tuple[Path, list[str], dict[str, bytes]],
        logger: logging.Logger,
    ) -> None:
        import vendor_assets

        cache, downloads, _ = fake_pele
        vendor_assets.ensure_pele_bundle(logger)
        (cache / "pele.mjs").write_bytes(b"tampered")
        downloads.clear()

        vendor_assets.ensure_pele_bundle(logger)

        assert downloads == ["dist/pele.js"]
        assert (cache / "pele.mjs").read_bytes() == _FAKE_PELE["dist/pele.js"]

    def test_esm_bundle_is_cached_under_an_mjs_name(
        self,
        fake_pele: tuple[Path, list[str], dict[str, bytes]],
        logger: logging.Logger,
    ) -> None:
        # Node.js 20.0-20.18 and 22.0-22.6 load a bare .js file with no
        # "type": "module" beside it as CommonJS and fail on `export`.
        import vendor_assets

        cache, downloads, _ = fake_pele
        cache.mkdir(parents=True)
        # A cache written before the rename holds only pele.js.
        (cache / "pele.js").write_bytes(_FAKE_PELE["dist/pele.js"])

        vendor_assets.ensure_pele_bundle(logger)

        assert vendor_assets.PELE_ESM_BUNDLE == "pele.mjs"
        assert "dist/pele.js" in downloads
        assert (cache / "pele.mjs").read_bytes() == _FAKE_PELE["dist/pele.js"]

    def test_mismatching_download_raises_and_leaves_no_file(
        self,
        fake_pele: tuple[Path, list[str], dict[str, bytes]],
        logger: logging.Logger,
    ) -> None:
        import vendor_assets

        cache, _, served = fake_pele
        served["dist/pele.global.js"] = b"not the pinned bundle"

        with pytest.raises(RuntimeError, match="Checksum mismatch"):
            vendor_assets.ensure_pele_bundle(logger)

        assert not (cache / "pele.global.js").exists()
        assert not (cache / "pele.global.js.part").exists()

    def test_fetch_pele_copies_bundle_and_license(
        self,
        fake_pele: tuple[Path, list[str], dict[str, bytes]],
        tmp_path: Path,
        logger: logging.Logger,
    ) -> None:
        import vendor_assets

        target = tmp_path / "site" / "assets" / "vendor" / "pele"
        script = vendor_assets.fetch_pele(target, logger)

        assert script == target / "pele.global.js"
        assert script.read_bytes() == _FAKE_PELE["dist/pele.global.js"]
        assert (target / "LICENSE").read_bytes() == _FAKE_PELE["LICENSE"]

    def test_manifest_records_pele_not_mermaid(self, tmp_path: Path) -> None:
        import vendor_assets

        vendor_assets.write_vendor_manifest(tmp_path, fonts_count=3)
        manifest = json.loads((tmp_path / "manifest.json").read_text("utf-8"))
        assert manifest["pele"] == vendor_assets.PELE_VERSION
        assert "mermaid" not in manifest


# =============================================================================
# Diagram styles (site.css)
# =============================================================================

SITE_CSS = Path(__file__).parent.parent / "website_templates" / "site.css"
# Light fills that site lessons set on nodes without a text colour.
SOURCE_NODE_FILLS = ("#e1f5ff", "#e1f5fe", "#fff9c4")


def _css_rule(css: str, selector: str) -> str:
    match = re.search(rf"^{re.escape(selector)}\s*\{{(.*?)\}}", css, re.M | re.S)
    assert match, f"no rule for {selector!r} in site.css"
    return match.group(1)


def _css_color(rule: str, prop: str) -> str:
    match = re.search(rf"(?<![\w-]){re.escape(prop)}:\s*(#[0-9a-fA-F]{{6}})", rule)
    assert match, f"no {prop} colour in rule"
    return match.group(1)


def _contrast(first: str, second: str) -> float:
    def luminance(color: str) -> float:
        channels = [int(color[i : i + 2], 16) / 255 for i in (1, 3, 5)]
        r, g, b = (
            c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
            for c in channels
        )
        return 0.2126 * r + 0.7152 * g + 0.0722 * b

    high, low = sorted((luminance(first), luminance(second)), reverse=True)
    return (high + 0.05) / (low + 0.05)


class TestDiagramStyles:
    @pytest.mark.parametrize("selector", [".mermaid", ".dark .mermaid"])
    def test_border_has_3_to_1_contrast(self, selector: str) -> None:
        # --pele-bg mirrors the page background (bg-slate-50 / bg-slate-950).
        rule = _css_rule(SITE_CSS.read_text("utf-8"), selector)
        border = _css_color(rule, "--pele-border")
        for surface in ("--pele-bg", "--pele-surface", "--pele-surface-alt"):
            assert _contrast(border, _css_color(rule, surface)) >= 3, surface

    def test_layout_rules_leave_the_source_fallback_alone(self) -> None:
        css = SITE_CSS.read_text("utf-8")
        assert "background" not in _css_rule(css, ".mermaid")
        assert "background: transparent" in _css_rule(css, "div.mermaid")

    def test_diagram_starts_below_the_zoom_buttons(self) -> None:
        # Pele 1.6.0 draws its zoom box 8px below the top of a diagram it
        # shrank to fit (two 24px buttons, 2px gap, 2px padding, 1px border:
        # 56px tall) and sets [hidden] on it when the diagram fits.
        rule = _css_rule(
            SITE_CSS.read_text("utf-8"),
            "div.mermaid:has(> .pele-zoom:not([hidden]))",
        )
        match = re.search(r"padding-top:\s*([^;]+);", rule)
        assert match, "no padding-top in the zoom-box rule"
        value = match.group(1)
        room = sum(float(n) for n in re.findall(r"([\d.]+)px", value))
        room += 16 * sum(float(n) for n in re.findall(r"([\d.]+)rem", value))
        assert room > 8 + 56
        # Side padding would narrow the width Pele lays the diagram out to.
        assert "padding-right" not in rule
        assert "padding-left" not in rule

    def test_dark_labels_on_source_fills_are_readable(self) -> None:
        rule = _css_rule(
            SITE_CSS.read_text("utf-8"),
            '.dark .mermaid .pele-node:has(> [style*="fill:"]) '
            '> .pele-label:not([style*="fill:"])',
        )
        label = _css_color(rule, "fill")
        for fill in SOURCE_NODE_FILLS:
            assert _contrast(label, fill) >= 4.5, fill


# =============================================================================
# Landing page
# =============================================================================


def _write_roadmap(path: Path, modules: list[dict]) -> Path:
    data = {
        "levels": [
            {
                "id": "beginner",
                "name": "Level 1 — Beginner",
                "title": "Getting started",
                "summary": "Start here.",
                "modules": modules,
            }
        ]
    }
    path.write_text(json.dumps(data), encoding="utf-8")
    return path


def _roadmap_module(lessons: list[dict], **overrides) -> dict:
    module = {
        "id": "slash-commands",
        "number": "01",
        "title": "Slash Commands",
        "source": "01-slash-commands/README.md",
        "time": "30 min",
        "tagline": "Commands.",
        "lessons": lessons,
    }
    module.update(overrides)
    return module


class TestLanding:
    def _config(self, site_root: Path, out_dir: Path, roadmap: Path) -> WebsiteConfig:
        return WebsiteConfig(
            root_path=site_root,
            output_path=out_dir,
            repo_url="https://github.com/example/repo",
            branch="main",
            landing=True,
            roadmap_path=roadmap,
        )

    def test_landing_build(
        self, site_root: Path, tmp_path: Path, logger: logging.Logger
    ) -> None:
        roadmap = _write_roadmap(
            tmp_path / "roadmap.json",
            [
                _roadmap_module(
                    [
                        {
                            "id": "overview",
                            "title": "Overview",
                            "heading": "Slash Commands",
                        },
                        {
                            "id": "advanced",
                            "title": "Advanced usage",
                            "heading": "Advanced Usage",
                        },
                    ]
                )
            ],
        )
        out_dir = site_root / "site"
        build_website(
            self._config(site_root, out_dir, roadmap), logger, skip_vendor=True
        )

        index = out_dir / "index.html"
        assert index.exists()
        index_html = index.read_text(encoding="utf-8")
        soup = BeautifulSoup(index_html, "html.parser")
        # The landing takes index.html
        assert soup.select_one("#roadmap") is not None
        assert soup.select_one('[data-lesson="slash-commands/overview"]') is not None
        # The header CTA and live copy status remain available in the rendered page.
        assert soup.select_one('header .nav-cta[href="#roadmap"]') is not None
        copy_status = soup.select_one("#copy-status")
        assert copy_status is not None
        assert copy_status.get("role") == "status"
        assert copy_status.get("aria-live") == "polite"
        # Lesson anchors resolve into the module page
        assert "01-slash-commands/index.html#advanced-usage" in index_html
        # Landing assets are copied and referenced alongside the site CSS
        assert (out_dir / "assets" / "landing.css").exists()
        assert (out_dir / "assets" / "landing.js").exists()
        assert soup.select_one('link[href="assets/landing.css"]') is not None
        assert soup.select_one('script[src="assets/landing.js"]') is not None
        # The landing must not pull in the docs-page stylesheet or CDNs
        assert "tailwind.css" not in index_html
        for hostile in ("cdn.tailwindcss.com", "fonts.googleapis.com"):
            assert hostile not in index_html

        # The README moved to guide.html
        guide = out_dir / "guide.html"
        assert guide.exists()
        assert "Home Page" in guide.read_text(encoding="utf-8")

        # Links from other pages to README.md now resolve to guide.html
        roadmap_page = (out_dir / "LEARNING-ROADMAP.html").read_text(encoding="utf-8")
        assert "guide.html#home-page" in roadmap_page
        assert "index.html#home-page" not in roadmap_page

    def test_landing_missing_heading(
        self, site_root: Path, tmp_path: Path, logger: logging.Logger
    ) -> None:
        roadmap = _write_roadmap(
            tmp_path / "roadmap.json",
            [
                _roadmap_module(
                    [
                        {
                            "id": "ghost",
                            "title": "Ghost",
                            "heading": "Does Not Exist",
                        }
                    ]
                )
            ],
        )
        with pytest.raises(RuntimeError, match="Does Not Exist"):
            build_website(
                self._config(site_root, site_root / "site", roadmap),
                logger,
                skip_vendor=True,
            )

    def test_landing_missing_source(
        self, site_root: Path, tmp_path: Path, logger: logging.Logger
    ) -> None:
        roadmap = _write_roadmap(
            tmp_path / "roadmap.json",
            [
                _roadmap_module(
                    [{"id": "x", "title": "X", "heading": "X"}],
                    source="99-nope/README.md",
                )
            ],
        )
        with pytest.raises(RuntimeError, match=r"99-nope/README\.md"):
            build_website(
                self._config(site_root, site_root / "site", roadmap),
                logger,
                skip_vendor=True,
            )

    def test_landing_duplicate_ids(
        self, site_root: Path, tmp_path: Path, logger: logging.Logger
    ) -> None:
        lesson = {"id": "overview", "title": "Overview", "heading": "Slash Commands"}
        roadmap = _write_roadmap(
            tmp_path / "roadmap.json",
            [_roadmap_module([lesson, dict(lesson)])],
        )
        with pytest.raises(RuntimeError, match="duplicate lesson id"):
            build_website(
                self._config(site_root, site_root / "site", roadmap),
                logger,
                skip_vendor=True,
            )

    def test_landing_real_repo(self, tmp_path: Path, logger: logging.Logger) -> None:
        """Every heading in the shipped roadmap.json must resolve to an anchor."""
        repo_root = Path(__file__).resolve().parents[2]
        out_dir = tmp_path / "site"
        config = WebsiteConfig(
            root_path=repo_root,
            output_path=out_dir,
            landing=True,
        )
        build_website(config, logger, skip_vendor=True)
        index_html = (out_dir / "index.html").read_text(encoding="utf-8")
        assert 'id="roadmap"' in index_html
        assert 'data-lesson="slash-commands/overview"' in index_html
        assert (out_dir / "guide.html").exists()

    def test_landing_off_keeps_readme_index(
        self, site_root: Path, logger: logging.Logger
    ) -> None:
        out_dir = site_root / "site"
        config = WebsiteConfig(
            root_path=site_root,
            output_path=out_dir,
            landing=False,
        )
        build_website(config, logger, skip_vendor=True)
        index_html = (out_dir / "index.html").read_text(encoding="utf-8")
        assert "Home Page" in index_html
        assert 'id="roadmap"' not in index_html
        assert not (out_dir / "guide.html").exists()


LANDING_JS_NODE_HARNESS = r"""
const assert = require("assert");
const fs = require("fs");
const vm = require("vm");
const source = fs.readFileSync(process.argv[1], "utf8");

function element(id = null, classes = [], attrs = {}) {
  const names = new Set(classes);
  const listeners = {};
  const item = {
    id, attrs, style: {}, hidden: false, textContent: "",
    classList: {
      add(...values) { values.forEach((value) => names.add(value)); },
      remove(...values) { values.forEach((value) => names.delete(value)); },
      contains(value) { return names.has(value); },
      toggle(value, force) {
        const next = force === undefined ? !names.has(value) : force;
        if (next) names.add(value); else names.delete(value);
        return next;
      },
    },
    getAttribute(name) { return name === "id" ? item.id : item.attrs[name] ?? null; },
    setAttribute(name, value) { item.attrs[name] = String(value); },
    addEventListener(name, handler) { (listeners[name] ||= []).push(handler); },
    dispatch(name) { (listeners[name] || []).forEach((handler) => handler({ target: item })); },
    querySelector: () => null,
    querySelectorAll: () => [],
    closest: () => null,
    appendChild: () => {},
    removeChild: () => {},
    select: () => {},
  };
  return item;
}

function makeEnvironment(spec) {
  const ids = new Map();
  const register = (id, classes = []) => {
    const item = element(id, classes);
    ids.set(id, item);
    return item;
  };
  const copy = element(null, [], { "data-copy": "echo copied" });
  const label = element();
  label.classList.add("copy-label");
  label.textContent = "Copy";
  copy.querySelector = (selector) => selector === ".copy-label" ? label : null;
  const document = {
    documentElement: element(null, ["no-js"]),
    body: element(),
    getElementById: (id) => ids.get(id) || null,
    querySelectorAll: (selector) => selector === "[data-copy]" ? [copy] : [],
    createElement: () => element(),
    addEventListener: () => {},
  };
  register("top", ["nav"]);
  register("nav-toggle");
  register("nav-menu");
  register("copy-status");

  let clipboardCalls = 0;
  let execCalls = 0;
  let copiedText = null;
  let resolveClipboard;
  const timers = new Map();
  let nextTimer = 1;
  document.execCommand = () => {
    execCalls += 1;
    if (spec.exec === "throw") throw new Error("copy denied");
    return spec.exec === "true";
  };
  const clipboard = spec.clipboard ? {
    writeText(text) {
      clipboardCalls += 1;
      copiedText = text;
      if (spec.clipboard === "deferred") {
        return new Promise((resolve) => { resolveClipboard = resolve; });
      }
      return spec.clipboard === "reject"
        ? Promise.reject(new Error("clipboard unavailable"))
        : Promise.resolve();
    },
  } : null;
  const navigator = { clipboard };
  const storage = new Map();
  const window = {
    innerHeight: 800,
    localStorage: {
      getItem: (key) => storage.get(key) || null,
      setItem: (key, value) => storage.set(key, value),
    },
    matchMedia: () => ({ matches: false }),
    setTimeout: (fn) => {
      const id = nextTimer++;
      timers.set(id, fn);
      return id;
    },
    clearTimeout: (id) => timers.delete(id),
    addEventListener: () => {},
    requestAnimationFrame: () => {},
    confirm: () => true,
    navigator,
  };
  return {
    copy, document, top: ids.get("top"),
    context: { console, Date, document, navigator, Promise, window },
    counters: () => ({ clipboardCalls, copiedText, execCalls }),
    resolveClipboard: () => resolveClipboard(),
    flushTimers: () => {
      const pending = Array.from(timers.values());
      timers.clear();
      pending.forEach((fn) => fn());
    },
  };
}

function runCase(spec) {
  const env = makeEnvironment(spec);
  vm.runInNewContext(source, env.context, { filename: "landing.js" });
  env.copy.dispatch("click");
  return new Promise((resolve) => setImmediate(() => {
    const label = env.copy.querySelector(".copy-label");
    const status = env.document.getElementById("copy-status");
    resolve({
      name: spec.name, label: label.textContent, status: status.textContent,
      copied: env.copy.classList.contains("copied"),
      navEnhanced: env.top.classList.contains("nav-enhanced"),
      ...env.counters(),
    });
  }));
}

async function runRapidClicks() {
  const spec = { clipboard: null, exec: "true" };
  const env = makeEnvironment(spec);
  vm.runInNewContext(source, env.context, { filename: "landing.js" });
  const label = env.copy.querySelector(".copy-label");
  const status = env.document.getElementById("copy-status");
  env.copy.dispatch("click");
  assert.strictEqual(label.textContent, "Copied");
  spec.exec = "false";
  env.copy.dispatch("click");
  assert.strictEqual(label.textContent, "Copy failed");
  env.flushTimers();
  assert.strictEqual(label.textContent, "Copy");
  assert.strictEqual(status.textContent, "Unable to copy to clipboard");
  assert.strictEqual(env.copy.classList.contains("copied"), false);

  const pending = makeEnvironment({ clipboard: "deferred", exec: "false" });
  vm.runInNewContext(source, pending.context, { filename: "landing.js" });
  pending.copy.dispatch("click");
  pending.context.navigator.clipboard = null;
  pending.copy.dispatch("click");
  pending.resolveClipboard();
  await new Promise((resolve) => setImmediate(resolve));
  assert.strictEqual(pending.copy.querySelector(".copy-label").textContent, "Copy failed");
  assert.strictEqual(pending.document.getElementById("copy-status").textContent, "Unable to copy to clipboard");
  pending.flushTimers();
  assert.strictEqual(pending.copy.querySelector(".copy-label").textContent, "Copy");
  return { name: "rapid-clicks" };
}

const cases = [
  ["clipboard-success", "resolve", "false", "Copied", "Copied to clipboard", true, 0, 1, "echo copied"],
  ["legacy-false", null, "false", "Copy failed", "Unable to copy to clipboard", false, 1, 0, null],
  ["legacy-throw", null, "throw", "Copy failed", "Unable to copy to clipboard", false, 1, 0, null],
  ["rejection-legacy-success", "reject", "true", "Copied", "Copied to clipboard", true, 1, 1, "echo copied"],
  ["rejection-legacy-false", "reject", "false", "Copy failed", "Unable to copy to clipboard", false, 1, 1, "echo copied"],
];
Promise.all([
  ...cases.map(([name, clipboard, exec]) => runCase({ name, clipboard, exec })),
  runRapidClicks(),
])
  .then((results) => {
    results.slice(0, cases.length).forEach((result, index) => {
      const [, , , label, status, copied, execCalls, clipboardCalls, copiedText] = cases[index];
      assert.deepStrictEqual(
        [result.label, result.status, result.copied, result.execCalls, result.clipboardCalls, result.copiedText, result.navEnhanced],
        [label, status, copied, execCalls, clipboardCalls, copiedText, true], result.name,
      );
    });
    process.stdout.write(JSON.stringify(results));
  })
  .catch((error) => {
    console.error(error.stack || error);
    process.exitCode = 1;
  });
"""


class TestLandingJavaScript:
    @pytest.mark.skipif(shutil.which("node") is None, reason="node is required")
    def test_copy_fallbacks_and_mobile_nav_enhancement(self) -> None:
        node = shutil.which("node")
        assert node is not None
        landing_js = Path(__file__).parent.parent / "website_templates" / "landing.js"
        result = subprocess.run(
            [node, "-e", LANDING_JS_NODE_HARNESS, str(landing_js)],
            capture_output=True,
            text=True,
            check=False,
        )
        assert result.returncode == 0, result.stderr
        results = json.loads(result.stdout)
        assert {result["name"] for result in results} == {
            "clipboard-success",
            "legacy-false",
            "legacy-throw",
            "rejection-legacy-success",
            "rejection-legacy-false",
            "rapid-clicks",
        }