fix: improve error handling in compare_srd; add count test; document missing items runner

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: augustjohnson

api_v2/management/commands/compare_srd.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 import os
 import time
+import traceback
 import concurrent.futures
 from dataclasses import dataclass
 from typing import Any
@@ -222,6 +223,8 @@ def _run_magic_item_comparison(pdf_path: str, document: str) -> ComparisonResult
     return compare_records("magic_items", pdf_records, db_records, SKIP_FIELDS["magic_items"])
 
 
+# "items" (adventuring gear) is not in _RUNNERS because the SRD adventuring gear
+# items do not have a dedicated model in api_v2 that maps cleanly to PDF records.
 _RUNNERS = {
     "spells": _run_spell_comparison,
     "creatures": _run_creature_comparison,
@@ -239,7 +242,10 @@ def _run_magic_item_comparison(pdf_path: str, document: str) -> ComparisonResult
 def _render_results(results: dict[str, ComparisonResult], elapsed: float) -> None:
     console = Console()
 
-    summary = Table(title=f"SRD 5.2 PDF vs Database  (completed in {elapsed:.1f}s)")
+    def _fmt(n):
+        return "[green]0[/green]" if n == 0 else str(n)
+
+    summary = Table(title=f"SRD 5.2 PDF vs Database (completed in {elapsed:.1f}s)")
     summary.add_column("Entity type", style="bold")
     summary.add_column("In PDF", justify="right")
     summary.add_column("In DB", justify="right")
@@ -248,8 +254,6 @@ def _render_results(results: dict[str, ComparisonResult], elapsed: float) -> Non
     summary.add_column("Mismatches", justify="right")
 
     for name, result in results.items():
-        def _fmt(n):
-            return f"[green]0[/green]" if n == 0 else str(n)
         summary.add_row(
             name,
             str(result.pdf_count),
@@ -328,6 +332,8 @@ def handle(self, *args, **options):
         start = time.monotonic()
         results: dict[str, ComparisonResult] = {}
 
+        failed: list[str] = []
+
         with concurrent.futures.ThreadPoolExecutor() as executor:
             futures = {
                 executor.submit(_RUNNERS[etype], pdf_path, document): etype
@@ -339,6 +345,11 @@ def handle(self, *args, **options):
                     results[etype] = future.result()
                 except Exception as exc:
                     self.stderr.write(f"  ERROR comparing {etype}: {exc}")
+                    traceback.print_exc()
+                    failed.append(etype)
+
+        if failed:
+            raise CommandError(f"Comparisons failed for: {', '.join(failed)}")
 
         elapsed = time.monotonic() - start
         _render_results(

api_v2/tests/test_compare_srd.py

@@ -87,6 +87,26 @@ def test_case_insensitive_string_comparison(self):
         result = compare_records("spells", pdf, db, skip_fields=SKIP)
         assert result.mismatches == []
 
+    def test_pdf_and_db_counts(self):
+        pdf = [_make_spell("Fireball"), _make_spell("Acid Arrow")]
+        db = [
+            {"name": "Fireball", "level": 1, "school__name": "evocation",
+             "casting_time": "Action", "range_text": "60 feet",
+             "verbal": True, "somatic": True, "material": False,
+             "duration": "Instantaneous", "concentration": False, "ritual": False},
+            {"name": "Acid Arrow", "level": 2, "school__name": "evocation",
+             "casting_time": "Action", "range_text": "90 feet",
+             "verbal": True, "somatic": True, "material": True,
+             "duration": "Instantaneous", "concentration": False, "ritual": False},
+            {"name": "Extra Spell", "level": 1, "school__name": "evocation",
+             "casting_time": "Action", "range_text": "60 feet",
+             "verbal": True, "somatic": True, "material": False,
+             "duration": "Instantaneous", "concentration": False, "ritual": False},
+        ]
+        result = compare_records("spells", pdf, db, skip_fields=SKIP)
+        assert result.pdf_count == 2
+        assert result.db_count == 3
+
     def test_float_comparison_within_tolerance(self):
         """Challenge rating 0.25 vs 0.25000001 should not mismatch."""
         from data.raw_sources.srd_5_2.parsers.creatures import CreatureRecord

data/raw_sources/srd_5_2/parsers/items.py

@@ -171,7 +171,7 @@ def extract_weapons(full_text: str) -> list[WeaponRecord]:
 
 def extract_weapons_from_pdf(pdf_path: str) -> list[WeaponRecord]:
     """Extract weapons from the real SRD PDF. Raises ValueError if fewer than 30 found."""
-    from .base import extract_full_text  # avoid circular at module load time
+    from .base import extract_full_text  # deferred import
     full_text = extract_full_text(pdf_path)
     records = extract_weapons(full_text)
     if len(records) < 30:
@@ -286,7 +286,7 @@ def extract_armor(full_text: str) -> list[ArmorRecord]:
 
 def extract_armor_from_pdf(pdf_path: str) -> list[ArmorRecord]:
     """Extract armor from the real SRD PDF. Raises ValueError if fewer than 10 found."""
-    from .base import extract_full_text  # avoid circular at module load time
+    from .base import extract_full_text  # deferred import
     full_text = extract_full_text(pdf_path)
     records = extract_armor(full_text)
     if len(records) < 10: