"""Content checks on the shipped documentation prose.

These tests read the actual docs files from the repo and assert on their
prose, so a doc edit that drifts from the contract is caught the same way a
code regression is. All offline, no network.
"""

from pathlib import Path

import pytest

DOCS = Path(__file__).resolve().parent.parent / "docs"


@pytest.fixture(scope="module")
def api_doc() -> str:
    doc = DOCS / "api.md"
    assert doc.exists(), f"docs/api.md not found at {doc}"
    return doc.read_text(encoding="utf-8")


def test_api_doc_documents_conversation_header_name(api_doc: str) -> None:
    """The conversation header must be named in the API reference."""
    assert "X-Router-Conversation" in api_doc
    assert "X-Router-Agent" in api_doc
    assert "X-Router-Parent" in api_doc


def test_api_doc_documents_conversation_id_charset_rule(api_doc: str) -> None:
    """The charset and length contract for the conversation id must appear."""
    assert "1-128" in api_doc
    assert "^[A-Za-z0-9._:-]+$" in api_doc


def test_api_doc_documents_fallback_behavior(api_doc: str) -> None:
    """Absent or invalid headers must be documented as falling back to absent,
    and an absent conversation header as falling back to the fingerprint."""
    assert "treated as absent" in api_doc
    assert "fingerprint" in api_doc