docs: audit data sources and parser contracts

tests/test_parser_contract.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+import pytest
+
+from app.importer import ImportSourceError, parse_html
+from rf4_research.records import RecordsParseError, parse_records_html
+
+
+FIXTURE = Path(__file__).parent / "fixtures" / "records_ru_sample.html"
+
+
+def _research_contract(html: str) -> list[tuple[object, ...]]:
+    records = parse_records_html(
+        html,
+        region="RU",
+        category="records",
+        source_url="fixture://records",
+    )
+    return [
+        (row.region, row.category, row.player, row.fish, row.weight_g, row.waterbody, row.bait, row.record_date)
+        for row in records
+    ]
+
+
+def _production_contract(html: str) -> list[tuple[object, ...]]:
+    records = parse_html(html, region="RU", category="records")
+    return [
+        (row.region, row.category, row.player, row.fish, row.weight_g, row.waterbody, row.bait, row.record_date)
+        for row in records
+    ]
+
+
+def test_research_and_production_parsers_emit_the_same_contract() -> None:
+    html = FIXTURE.read_text(encoding="utf-8")
+
+    assert _research_contract(html) == _production_contract(html)
+
+
+def test_both_parsers_reject_a_changed_column_contract() -> None:
+    html = FIXTURE.read_text(encoding="utf-8").replace('class="col data"', 'class="col changed"', 1)
+
+    with pytest.raises(RecordsParseError, match="records columns changed"):
+        _research_contract(html)
+    with pytest.raises(ImportSourceError, match="record columns changed"):
+        _production_contract(html)