Add transparent library health engine

serato_doctor/models/__init__.py

@@ -1,4 +1,5 @@
 from serato_doctor.models.crate import Crate
+from serato_doctor.models.health import HealthReport
 from serato_doctor.models.library import Library
 from serato_doctor.models.match import MatchEvidence, TrackMatch
 from serato_doctor.models.reference import ReferenceResult, TrackReference
@@ -7,6 +8,7 @@ from serato_doctor.models.track import DiskTrack
 __all__ = [
     "Crate",
     "DiskTrack",
+    "HealthReport",
     "Library",
     "MatchEvidence",
     "ReferenceResult",

serato_doctor/models/health.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class HealthReport:
+    """Transparent aggregate findings from a read-only library analysis."""
+
+    score: Optional[float]
+    total_references: int
+    healthy_references: int
+    missing_references: int
+    unique_missing_filenames: int
+    disk_tracks: int
+    duplicate_filename_groups: int
+    duplicate_files: int
+    unused_tracks: int
+    suggested_matches: int
+
+    @property
+    def score_basis(self) -> str:
+        return "Resolved crate references / total crate references"