test_generate_query_docs.py

# Copyright 2026 Joe Harris / BenchBox Project

# Licensed under the MIT License. See LICENSE file in the project root for details.

from __future__ import annotations

import importlib.util
import sys
from pathlib import Path

import pytest

pytestmark = [pytest.mark.unit, pytest.mark.fast]

_REPO_ROOT = Path(__file__).resolve().parents[2]
_SCRIPT = _REPO_ROOT / "scripts" / "generate_query_docs.py"
_FAST_BENCHMARKS = frozenset({"clickbench", "datavault"})


def _load_module():
    spec = importlib.util.spec_from_file_location("generate_query_docs", _SCRIPT)
    module = importlib.util.module_from_spec(spec)
    sys.modules[spec.name] = module
    spec.loader.exec_module(module)
    return module


gqd = _load_module()


@pytest.fixture(scope="module")
def rendered():
    return gqd.render_all(set(_FAST_BENCHMARKS))


class TestSlugsAndLabels:
    def test_numeric_ids_get_q_prefix(self):
        assert gqd._query_slug("1") == "q1"
        assert gqd._query_slug("1.1") == "q1-1"
        assert gqd._query_slug("10v1") == "q10v1"

    def test_named_ids_keep_their_slug(self):
        assert gqd._query_slug("ontime-by-carrier") == "ontime-by-carrier"
        assert gqd._query_slug("SA1") == "sa1"

    def test_labels(self):
        assert gqd._query_label("1") == "Q1"
        assert gqd._query_label("Q1.1") == "Q1.1"
        assert gqd._query_label("ontime-by-carrier") == "ontime-by-carrier"

    def test_fence_escapes_nested_backticks(self):
        fenced = gqd._fence("a ``` b", "text")
        assert fenced.startswith("````text\n")
        assert fenced.endswith("\n````")

    def test_prettify_sql_reformats_and_falls_back(self):
        pretty = gqd._prettify_sql("SELECT a, b FROM t WHERE a = 1", "datafusion")
        assert "\n" in pretty and "SELECT" in pretty
        assert gqd._prettify_sql("-- not sql at all", "default") == "-- not sql at all"

    def test_overview_link_depth_reaches_docs_benchmarks(self):
        assert gqd._overview_link("clickbench") == "../../clickbench.md"
        assert gqd._overview_link("tpch") == "../../tpc-h.md"


class TestRenderAll:
    def test_top_index_present(self, rendered):
        assert "index.md" in rendered
        assert "# Query Templates" in rendered["index.md"]

    def test_one_page_per_query_plus_index(self, rendered):
        from benchbox.core.query_catalog import list_query_ids

        clickbench = {p for p in rendered if p.startswith("clickbench/")}
        assert "clickbench/index.md" in clickbench
        expected = {f"clickbench/{gqd._query_slug(q)}.md" for q in list_query_ids("clickbench")}
        assert expected <= clickbench

    def test_query_page_has_all_sections(self, rendered):
        page = rendered["clickbench/q1.md"]
        assert page.startswith("<!-- Copyright")
        assert "AUTOGENERATED by scripts/generate_query_docs.py" in page
        assert "## Representative SQL" in page
        assert "## Representative DataFrame" in page
        assert "## Get the exact query for your run" in page
        assert "```sql" in page and "```python" in page
        assert "from benchbox import ClickBench" in page

    def test_internal_benchmark_excluded_even_when_requested(self):
        out = gqd.render_all({"joinorder_synthetic", "clickbench"})
        assert not any(p.startswith("joinorder_synthetic/") for p in out)
        assert any(p.startswith("clickbench/") for p in out)

    def test_large_benchmark_gets_group_pages(self, rendered):
        cb = {p for p in rendered if p.startswith("clickbench/")}
        assert any(p.startswith("clickbench/group-") for p in cb)
        assert "clickbench/index.md" in cb

    def test_small_benchmark_has_a_flat_index(self, rendered):
        assert not any(p.startswith("datavault/group-") for p in rendered)

    def test_tpc_derived_pages_carry_the_trademark_notice(self, rendered):
        assert "Transaction Processing Performance Council" in rendered["datavault/index.md"]

    def test_no_page_leaks_raw_template_tokens(self, rendered):
        offenders = [p for p, text in rendered.items() if "Parameter placeholders are shown literally" in text]
        assert offenders == [], offenders


class TestTreeIO:
    def test_check_passes_after_write_and_fails_after_edit(self, tmp_path, rendered):
        target = tmp_path / "queries"
        gqd.write_tree(rendered, target)
        assert gqd.check_tree(rendered, target) == 0

        victim = next(target.rglob("q1.md"))
        victim.write_text(victim.read_text() + "\nedited\n", encoding="utf-8")
        assert gqd.check_tree(rendered, target) == 1

    def test_check_flags_orphan_files(self, tmp_path, rendered):
        target = tmp_path / "queries"
        gqd.write_tree(rendered, target)

        (target / "clickbench" / "zzz-orphan.md").write_text("stale\n", encoding="utf-8")
        assert gqd.check_tree(rendered, target) == 1

    def test_write_tree_prunes_removed_files(self, tmp_path, rendered):
        target = tmp_path / "queries"
        gqd.write_tree(rendered, target)
        assert (target / "datavault").is_dir()

        gqd.write_tree(gqd.render_all({"clickbench"}), target)
        assert not (target / "datavault").exists()