"""Documentation gates — assert the user-facing docs keep their key content.

Pure pathlib; no Qt or solver imports so this stays part of the fast unit
suite.
"""

from __future__ import annotations

from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[2]
DOCS_DIR = REPO_ROOT / "docs"


def _text(path: Path) -> str:
    """Return a file's UTF-8 text with normalized line endings."""
    return path.read_text(encoding="utf-8").replace("\r\n", "\n")


def test_quick_guide_exists_and_covers_core_topics() -> None:
    quick_guide = DOCS_DIR / "QUICK_GUIDE.md"
    assert quick_guide.is_file(), "docs/QUICK_GUIDE.md is missing"

    lowered = _text(quick_guide).lower()
    for topic in ("cantilever", "report", "modal", "units", "undo"):
        assert topic in lowered, f"QUICK_GUIDE.md is missing {topic!r}"


def test_contributing_describes_this_repo() -> None:
    text = _text(REPO_ROOT / "CONTRIBUTING.md")

    for required in (
        "views",
        "viewmodels",
        "services",
        "core",
        "commands",
        "Conventional Commits",
        "feat:",
        "main",
        "pre-commit install",
        'pip install -e ".[gui,dev]"',
        "python -m otko",
        'pytest -m "not slow"',
    ):
        assert required in text, f"CONTRIBUTING.md is missing {required!r}"


def test_readme_links_quick_guide() -> None:
    readme = _text(REPO_ROOT / "README.md")
    assert "docs/QUICK_GUIDE.md" in readme