feat(io): import handler warnings for unregistered platforms (#182)

[IanMayo]

Summary

• Add post-parse validation to the import pipeline that checks extracted platform_id values against the platform registry (Add Tool Library Migration SRD for legacy Java tool discovery #180) and emits deduplicated UNREGISTERED_PLATFORM warnings
• Import always succeeds regardless of registry coverage — warnings are advisory only
• Graceful fallback when registry is unavailable: single REGISTRY_UNAVAILABLE warning, validation skipped
• Part of E10 (NL-Assisted Catalog Discovery), item 3 of 11

Changes

Phase 1: Setup

• Added debrief-data dependency to services/io/pyproject.toml

Phase 2: Foundation — Validation Function

• Implemented _validate_platform_ids() in services/io/src/debrief_io/import_catalog.py
• Extracts unique non-empty platform_id values from parsed features
• Resolves each against the registry (case-sensitive, matching existing behaviour)
• Emits one ImportWarning per unregistered platform per source file
• 9 unit tests in services/io/tests/test_platform_validation.py

Phase 3-5: Pipeline Integration

• Registry loaded once at start of import_legacy_data() with try/except fallback
• Validation called after each file parse (after schema validation, before catalog write)
• 8 integration tests covering REP, DPF, registry unavailable, deduplication, file attribution

Evidence

Test Results

Metric	Value
Total Tests	17
Passed	17
Failed	0
Regression	344 existing tests unaffected

Key scenarios verified:

• Unregistered platform IDs produce UNREGISTERED_PLATFORM warnings with correct file attribution
• Imports always succeed regardless of registry coverage (US2)
• Multiple position records for one platform produce exactly one warning per source file (US3)
• Batch import warnings reference the correct source file (US4)
• Registry load failure produces REGISTRY_UNAVAILABLE warning; validation skipped
• Case-sensitive lookup: "nelson" != "NELSON"
• Empty/whitespace IDs and features without platform_id handled gracefully

Usage Example

from pathlib import Path
from debrief_io.import_catalog import import_legacy_data

result = import_legacy_data(
    source_dir=Path("sample_data"),
    catalog_path=Path("local-store"),
)

# Check for unregistered platform warnings
for w in result.warnings:
    if w.code == "UNREGISTERED_PLATFORM":
        print(f"  [{w.file}] {w.message}")
# Output:
#   [exercise1.rep] Platform 'PHANTOM' is not registered in the platform registry

Sample Warning Output

Click to expand

{
  "warnings": [
    {
      "file": "exercise1.rep",
      "code": "UNREGISTERED_PLATFORM",
      "message": "Platform 'CONTACT_BRAVO' is not registered in the platform registry"
    },
    {
      "file": "exercise1.rep",
      "code": "UNREGISTERED_PLATFORM",
      "message": "Platform 'PHANTOM' is not registered in the platform registry"
    }
  ]
}

Test Plan

• All registered platforms — no UNREGISTERED_PLATFORM warnings
• Unregistered platform — correct warning code, file, message
• Empty/whitespace platform IDs — skipped without warning
• Duplicate IDs — deduplicated to one warning per platform per file
• Case-sensitive lookup — "nelson" vs "NELSON"
• Features without platform_id — skipped gracefully
• REP file integration — warnings emitted, import succeeds
• DPF file integration — warnings emitted, import succeeds
• Registry unavailable — REGISTRY_UNAVAILABLE warning, import succeeds
• All-unregistered file — import succeeds with all tracks present
• Many positions, one platform — exactly one warning
• Batch import — file attribution correct per source file
• 344 existing tests pass (regression check)
• ruff lint clean, pyright typecheck clean

Related

• Spec: specs/182-import-platform-warnings/spec.md
• Tasks: specs/182-import-platform-warnings/tasks.md
• Plan: specs/182-import-platform-warnings/plan.md
• Depends on: Add Tool Library Migration SRD for legacy Java tool discovery #180 (Platform Registry) — complete
• Unlocks: chore(backlog): add item 029 - provider unit tests #183 (Save-time Resolution), feat: Add OpenPlotsService to restore previously-open plots on startup #184 (Catalog Regeneration)

https://claude.ai/code/session_01EYVqLiYdMg7FVjjUfLysJq