llm-ingestion-okf/tests/test_docs_promises.py

"""The published format promise, asserted rather than trusted.

`README.md` told consumers that `docx` and `xlsx` ship no parser and always
fail fast. That was true when it was written and became false the moment the
converter seam landed -- silently, because prose has no test.

This library already learned that lesson once: a published promise without a
test goes false without anyone noticing, and a guarantee made publicly is a
test obligation. So the README's claimed format list is compared against the
registries it describes. Adding a format without touching the README, or
describing one that does not exist, fails here.
"""

from __future__ import annotations

import re
from pathlib import Path

from llm_ingestion_okf.extract import (
    _CORE_EXTRACTORS,
    _EVIDENCE,
    _OPTIONAL_EXTRACTORS,
    _PANDOC_FORMATS,
)

PROJECT_ROOT = Path(__file__).resolve().parents[1]
README = PROJECT_ROOT / "README.md"

# The line the README carries, and the one place this list is written in prose.
_FORMAT_LINE = re.compile(r"^<!-- extract-formats: (.+) -->$", re.MULTILINE)


def _declared_formats() -> set[str]:
    match = _FORMAT_LINE.search(README.read_text(encoding="utf-8"))
    assert match is not None, (
        "README.md carries no `<!-- extract-formats: ... -->` marker; without "
        "it this test cannot check the promise and the promise can drift"
    )
    return {token.strip() for token in match.group(1).split(",")}


def test_the_readme_names_exactly_the_formats_that_exist() -> None:
    assert _declared_formats() == set(_CORE_EXTRACTORS) | set(_OPTIONAL_EXTRACTORS)


def test_the_readme_no_longer_claims_docx_and_xlsx_fail_fast() -> None:
    """The specific false sentence, pinned so it cannot come back.

    Written as a search for the claim rather than for its exact wording: the
    sentence could be rephrased and stay just as wrong.
    """
    text = README.read_text(encoding="utf-8").lower()
    for claim in (
        "docx` and `xlsx` ship no parser",
        "docx`/`xlsx` remain\nunimplemented",
        "docx`/`xlsx` are still unimplemented",
    ):
        assert claim.lower() not in text, f"README still claims: {claim}"


def test_the_readme_states_which_rows_are_unmeasured() -> None:
    """An unmeasured row must not read as a supported one.

    Three of the five office formats have denominator ZERO in the corpus this
    work was measured on. A consumer reading the README should be able to see
    that without reading the source.
    """
    text = README.read_text(encoding="utf-8")
    unmeasured = {s.lstrip(".") for s, e in _EVIDENCE.items() if e == "unmeasured"}
    assert unmeasured, "the evidence table lists no unmeasured rows"
    for suffix in unmeasured:
        assert suffix in text, f"README does not mention the unmeasured row {suffix}"
    assert "unmeasured" in text.lower()


def test_the_readme_still_states_what_stays_out() -> None:
    """`.doc` (Word 97) and rastered PDFs are out, and stay named.

    A format list that grows without also saying what it excludes reads as a
    promise to handle anything office-shaped.
    """
    text = README.read_text(encoding="utf-8")
    assert ".doc`" in text or "Word 97" in text
    assert ".doc" not in set(_PANDOC_FORMATS)


def test_the_readme_recursion_claim_matches_the_door() -> None:
    """The README says the drop directory is walked recursively. A sentence is
    not a mechanism, so both halves are asserted here: the claim is in the
    prose, and the door actually does it. Either one alone can go stale --
    prose that outlived the code is the failure this whole module exists for.
    """
    import tempfile

    text = README.read_text(encoding="utf-8")
    assert "walked **recursively**" in text

    from llm_ingestion_okf.inbox import GateDecision, process_inbox

    with tempfile.TemporaryDirectory() as workspace:
        inbox = Path(workspace) / "inbox" / "sub"
        inbox.mkdir(parents=True)
        (inbox / "deep.md").write_text("Body\n", encoding="utf-8")
        result = process_inbox(
            Path(workspace) / "inbox",
            Path(workspace) / "bundle",
            "2026-09-07T08:00:00Z",
            okf_type="reference",
            gate=lambda body: GateDecision(sanitized_text=body, disposition="warn", reasons=()),
        )
    assert [item.source_file for item in result.persisted] == ["sub/deep.md"]