fix(#73): introduce ExtractionWarning type; wire date-propagation and credit-card-skip events

Author: web-flow

packages/parser-core/src/bankstatements_core/domain/models/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from bankstatements_core.domain.models.extraction_result import ExtractionResult
+from bankstatements_core.domain.models.extraction_warning import ExtractionWarning
 from bankstatements_core.domain.models.transaction import Transaction
 
-__all__ = ["Transaction", "ExtractionResult"]
+__all__ = ["Transaction", "ExtractionResult", "ExtractionWarning"]

packages/parser-core/src/bankstatements_core/domain/models/extraction_result.py

@@ -5,6 +5,7 @@
 from dataclasses import dataclass, field
 from pathlib import Path
 
+from bankstatements_core.domain.models.extraction_warning import ExtractionWarning
 from bankstatements_core.domain.models.transaction import Transaction
 
 
@@ -17,12 +18,13 @@ class ExtractionResult:
         page_count: Total number of pages in the source PDF
         iban: IBAN found in the document header, or None if not detected
         source_file: Path to the source PDF file
-        warnings: Document-level non-fatal events (e.g. "credit card detected,
-            skipped"). Distinct from per-row Transaction.extraction_warnings.
+        warnings: Document-level non-fatal events (e.g. credit card detected,
+            skipped). Distinct from per-row Transaction.extraction_warnings.
+            In-memory only — not written to output files.
     """
 
     transactions: list[Transaction]
     page_count: int
     iban: str | None
     source_file: Path
-    warnings: list[str] = field(default_factory=list)
+    warnings: list[ExtractionWarning] = field(default_factory=list)

packages/parser-core/src/bankstatements_core/domain/models/extraction_warning.py

@@ -0,0 +1,43 @@
+"""ExtractionWarning domain model for structured pipeline warning events."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Machine-readable warning codes
+CODE_DATE_PROPAGATED = "DATE_PROPAGATED"
+CODE_CREDIT_CARD_SKIPPED = "CREDIT_CARD_SKIPPED"
+
+
+@dataclass
+class ExtractionWarning:
+    """A structured warning event produced during PDF extraction.
+
+    Attributes:
+        code: Machine-readable identifier (use CODE_* constants).
+        message: Human-readable description of the event.
+        page: Page number the warning relates to, or None if document-level.
+
+    Examples:
+        >>> w = ExtractionWarning(code=CODE_DATE_PROPAGATED,
+        ...     message="date propagated from previous row ('01 Jan 2024')")
+        >>> w.code
+        'DATE_PROPAGATED'
+    """
+
+    code: str
+    message: str
+    page: int | None = field(default=None)
+
+    def to_dict(self) -> dict:
+        """Serialise to a plain dict for JSON encoding."""
+        return {"code": self.code, "message": self.message, "page": self.page}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ExtractionWarning":
+        """Deserialise from a plain dict."""
+        return cls(
+            code=data["code"],
+            message=data["message"],
+            page=data.get("page"),
+        )

packages/parser-core/src/bankstatements_core/domain/models/transaction.py

@@ -10,6 +10,7 @@
 from decimal import Decimal, InvalidOperation
 
 from bankstatements_core.domain.currency import strip_currency_symbols
+from bankstatements_core.domain.models.extraction_warning import ExtractionWarning
 
 
 @dataclass
@@ -52,7 +53,7 @@ class Transaction:
     additional_fields: dict[str, str] = field(default_factory=dict)
     source_page: int | None = None
     confidence_score: float = 1.0
-    extraction_warnings: list[str] = field(default_factory=list)
+    extraction_warnings: list[ExtractionWarning] = field(default_factory=list)
 
     def is_debit(self) -> bool:
         """Check if transaction is a debit (money out).
@@ -246,9 +247,22 @@ def from_dict(cls, data: dict[str, str | None]) -> Transaction:
         raw_confidence = data.get("confidence_score")
         confidence_score = float(raw_confidence) if raw_confidence is not None else 1.0
         raw_warnings = data.get("extraction_warnings")
-        extraction_warnings = (
-            json.loads(raw_warnings) if raw_warnings is not None else []
-        )
+        if raw_warnings is not None:
+            parsed = (
+                json.loads(raw_warnings)
+                if isinstance(raw_warnings, str)
+                else raw_warnings
+            )
+            extraction_warnings = [
+                (
+                    ExtractionWarning.from_dict(w)
+                    if isinstance(w, dict)
+                    else ExtractionWarning(code="UNKNOWN", message=str(w))
+                )
+                for w in parsed
+            ]
+        else:
+            extraction_warnings = []
 
         return cls(
             date=date or "",
@@ -313,7 +327,9 @@ def to_dict(self, currency_symbol: str = "€") -> dict[str, str | None]:
             str(self.source_page) if self.source_page is not None else None
         )
         result["confidence_score"] = str(self.confidence_score)
-        result["extraction_warnings"] = json.dumps(self.extraction_warnings)
+        result["extraction_warnings"] = json.dumps(
+            [w.to_dict() for w in self.extraction_warnings]
+        )
 
         # Add any additional fields
         result.update(self.additional_fields)

packages/parser-core/src/bankstatements_core/extraction/pdf_extractor.py

@@ -15,6 +15,10 @@
 
 from bankstatements_core.domain import ExtractionResult
 from bankstatements_core.domain.converters import dicts_to_transactions
+from bankstatements_core.domain.models.extraction_warning import (
+    CODE_CREDIT_CARD_SKIPPED,
+    ExtractionWarning,
+)
 from bankstatements_core.extraction.iban_extractor import IBANExtractor
 from bankstatements_core.extraction.page_header_analyser import PageHeaderAnalyser
 from bankstatements_core.extraction.row_builder import RowBuilder
@@ -112,7 +116,12 @@ def extract(self, pdf_path: Path) -> ExtractionResult:
                         page_count=len(pdf.pages),
                         iban=None,
                         source_file=pdf_path,
-                        warnings=["credit card statement detected, skipped"],
+                        warnings=[
+                            ExtractionWarning(
+                                code=CODE_CREDIT_CARD_SKIPPED,
+                                message="credit card statement detected, skipped",
+                            )
+                        ],
                     )
 
                 if iban is None and page_num == 1:

packages/parser-core/src/bankstatements_core/extraction/row_post_processor.py

@@ -6,11 +6,16 @@
 
 from __future__ import annotations
 
+import json
 import logging
 import re
 from datetime import datetime
 from typing import TYPE_CHECKING
 
+from bankstatements_core.domain.models.extraction_warning import (
+    CODE_DATE_PROPAGATED,
+    ExtractionWarning,
+)
 from bankstatements_core.extraction.column_identifier import ColumnTypeIdentifier
 
 if TYPE_CHECKING:
@@ -87,6 +92,11 @@ def process(self, row: dict, current_date: str) -> str:
             if not current_date:
                 current_date = fallback_date
             self._last_source = "propagated"
+            warning = ExtractionWarning(
+                code=CODE_DATE_PROPAGATED,
+                message=f"date propagated from previous row ('{fallback_date}')",
+            )
+            row["extraction_warnings"] = json.dumps([warning.to_dict()])
 
         # Metadata tagging
         row["Filename"] = self._filename

packages/parser-core/tests/domain/test_transaction.py

@@ -6,6 +6,10 @@
 
 import pytest
 
+from bankstatements_core.domain.models.extraction_warning import (
+    CODE_DATE_PROPAGATED,
+    ExtractionWarning,
+)
 from bankstatements_core.domain.models.transaction import Transaction
 
 
@@ -602,17 +606,21 @@ def test_extraction_warnings_defaults_to_empty_list(self):
         assert tx.extraction_warnings == []
 
     def test_extraction_warnings_can_be_set(self):
-        """TXEN-02: Transaction(extraction_warnings=['missing balance']) stores value."""
+        """TXEN-02: Transaction(extraction_warnings=[ExtractionWarning(...)]) stores value."""
+        w = ExtractionWarning(
+            code=CODE_DATE_PROPAGATED,
+            message="date propagated from previous row ('01 Jan 2024')",
+        )
         tx = Transaction(
             date="01/01/2024",
             details="Test",
             debit=None,
             credit="10.00",
             balance="100.00",
             filename="test.pdf",
-            extraction_warnings=["missing balance"],
+            extraction_warnings=[w],
         )
-        assert tx.extraction_warnings == ["missing balance"]
+        assert tx.extraction_warnings == [w]
 
     def test_extraction_warnings_no_shared_mutable_default(self):
         """TXEN-02: Two Transaction() instances have separate extraction_warnings lists."""
@@ -632,21 +640,36 @@ def test_extraction_warnings_no_shared_mutable_default(self):
             balance="120.00",
             filename="test.pdf",
         )
-        tx1.extraction_warnings.append("warning")
+        tx1.extraction_warnings.append(
+            ExtractionWarning(code=CODE_DATE_PROPAGATED, message="test")
+        )
         assert tx2.extraction_warnings == []
 
     def test_to_dict_extraction_warnings_serialises_as_json_string(self):
-        """TXEN-02: to_dict() with extraction_warnings=['missing balance'] → JSON string."""
+        """TXEN-02: to_dict() with an ExtractionWarning → JSON string of list of dicts."""
+        w = ExtractionWarning(
+            code=CODE_DATE_PROPAGATED,
+            message="date propagated from previous row ('01 Jan 2024')",
+        )
         tx = Transaction(
             date="01/01/2024",
             details="Test",
             debit=None,
             credit="10.00",
             balance="100.00",
             filename="test.pdf",
-            extraction_warnings=["missing balance"],
+            extraction_warnings=[w],
         )
-        assert tx.to_dict()["extraction_warnings"] == '["missing balance"]'
+        import json
+
+        serialised = json.loads(tx.to_dict()["extraction_warnings"])
+        assert serialised == [
+            {
+                "code": CODE_DATE_PROPAGATED,
+                "message": "date propagated from previous row ('01 Jan 2024')",
+                "page": None,
+            }
+        ]
 
     def test_to_dict_extraction_warnings_empty_serialises_as_json_array(self):
         """TXEN-02: to_dict() with extraction_warnings=[] → '[]'."""
@@ -661,16 +684,25 @@ def test_to_dict_extraction_warnings_empty_serialises_as_json_array(self):
         assert tx.to_dict()["extraction_warnings"] == "[]"
 
     def test_from_dict_extraction_warnings_parses_json_string(self):
-        """TXEN-02: from_dict({'extraction_warnings': '["missing balance"]'}) → list."""
+        """TXEN-02: from_dict with a JSON-encoded ExtractionWarning → list[ExtractionWarning]."""
+        import json
+
+        w = {
+            "code": CODE_DATE_PROPAGATED,
+            "message": "date propagated from previous row ('01 Jan 2024')",
+            "page": None,
+        }
         tx = Transaction.from_dict(
             {
                 "Date": "01/01/2024",
                 "Details": "Test",
                 "Filename": "test.pdf",
-                "extraction_warnings": '["missing balance"]',
+                "extraction_warnings": json.dumps([w]),
             }
         )
-        assert tx.extraction_warnings == ["missing balance"]
+        assert len(tx.extraction_warnings) == 1
+        assert isinstance(tx.extraction_warnings[0], ExtractionWarning)
+        assert tx.extraction_warnings[0].code == CODE_DATE_PROPAGATED
 
     def test_from_dict_extraction_warnings_absent_defaults_to_empty_list(self):
         """TXEN-02: from_dict({}) (key absent) → extraction_warnings == []."""
@@ -684,26 +716,35 @@ def test_from_dict_extraction_warnings_absent_defaults_to_empty_list(self):
 
     def test_extraction_warnings_roundtrip(self):
         """TXEN-02: from_dict(tx.to_dict()) preserves extraction_warnings."""
+        w = ExtractionWarning(
+            code=CODE_DATE_PROPAGATED,
+            message="date propagated from previous row ('01 Jan 2024')",
+        )
         original = Transaction(
             date="01/01/2024",
             details="Test",
             debit=None,
             credit="10.00",
             balance="100.00",
             filename="test.pdf",
-            extraction_warnings=["missing balance"],
+            extraction_warnings=[w],
         )
         restored = Transaction.from_dict(original.to_dict())
-        assert restored.extraction_warnings == ["missing balance"]
+        assert len(restored.extraction_warnings) == 1
+        assert restored.extraction_warnings[0].code == CODE_DATE_PROPAGATED
+        assert restored.extraction_warnings[0].message == w.message
 
     def test_extraction_warnings_not_in_additional_fields(self):
         """TXEN-02: extraction_warnings JSON key is gated by standard_keys — not absorbed into additional_fields."""
+        import json
+
+        w = {"code": CODE_DATE_PROPAGATED, "message": "test", "page": None}
         tx = Transaction.from_dict(
             {
                 "Date": "01/01/2024",
                 "Details": "Test",
                 "Filename": "test.pdf",
-                "extraction_warnings": '["x"]',
+                "extraction_warnings": json.dumps([w]),
             }
         )
         assert "extraction_warnings" not in tx.additional_fields
@@ -822,12 +863,15 @@ def test_full_roundtrip_all_three_enrichment_fields(self):
             filename="statement.pdf",
             source_page=3,
             confidence_score=0.8,
-            extraction_warnings=["missing balance"],
+            extraction_warnings=[
+                ExtractionWarning(code=CODE_DATE_PROPAGATED, message="missing balance")
+            ],
         )
         restored = Transaction.from_dict(original.to_dict())
         assert restored.source_page == 3
         assert restored.confidence_score == 0.8
-        assert restored.extraction_warnings == ["missing balance"]
+        assert len(restored.extraction_warnings) == 1
+        assert restored.extraction_warnings[0].code == CODE_DATE_PROPAGATED
 
     def test_backward_compat_old_dict_without_new_keys(self):
         """TXEN-04: Old dict without new keys → from_dict() succeeds with defaults."""

packages/parser-core/tests/test_credit_card_detection.py

@@ -8,6 +8,10 @@
 import pytest
 
 from bankstatements_core.domain import ExtractionResult
+from bankstatements_core.domain.models.extraction_warning import (
+    CODE_CREDIT_CARD_SKIPPED,
+    ExtractionWarning,
+)
 from bankstatements_core.extraction.pdf_extractor import PDFTableExtractor
 
 # Test columns configuration
@@ -359,4 +363,6 @@ def test_credit_card_early_return_produces_extraction_result_with_warning(
         assert len(result.transactions) == 0
         assert result.iban is None
         assert len(result.warnings) > 0
-        assert "credit card" in result.warnings[0].lower()
+        assert isinstance(result.warnings[0], ExtractionWarning)
+        assert result.warnings[0].code == CODE_CREDIT_CARD_SKIPPED
+        assert "credit card" in result.warnings[0].message.lower()