Kjell Tore Guttormsen
0170c526ad
The README told consumers that `docx` and `xlsx` ship no parser and always fail fast. True when written; false the moment the converter seam landed -- and false SILENTLY, because prose has no test. This repository has been bitten by that exact shape before: a published guarantee is a test obligation. So the correction comes with `tests/test_docs_promises.py`, which compares the README's declared format list against the registries it describes and fails on a format added without touching the README, on the old claim reappearing in any wording, on an unmeasured row going unnamed, and on the exclusions being dropped. Negative control: removing one format from the README's marker turns it red. The README now states which rows are measured and which are not. Three of the five office rows have denominator ZERO in the corpus -- they work by construction and have never met a document anyone wrote. They are not known to be broken and not known to be right, and a reader should not have to open the source to learn which. The CHANGELOG's shipped entry is left as written, because a changelog records what a release did; the correction is stated at that line instead so a reader arriving there is not misled. Suite 913 -> 917. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
84 lines
3.2 KiB
Python
84 lines
3.2 KiB
Python
"""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)
|