Add transparent library health engine

ROADMAP.md

@@ -11,6 +11,9 @@
 - [x] Test suite
 - [x] Sample library fixtures
 - [ ] Database V2 read-only parser
+- [x] Configuration
+- [x] Logging
+- [x] Matching engine
 
 ## v0.2 — Diagnostics
 
@@ -20,7 +23,7 @@
 - [ ] Orphaned audio detection
 - [ ] OneDrive rename detection
 - [ ] Crate classification: static vs smart/dynamic
-- [ ] Library health score
+- [x] Library health score
 
 ## v0.3 — Safe Repair
 

docs/design/configuration.md

@@ -0,0 +1,25 @@
+# Scan Configuration
+
+## Problem
+
+The prototype recognized crate paths by matching one developer's historical
+OneDrive path. That made otherwise valid libraries invisible to the parser.
+
+## Architecture
+
+`ScanConfig` owns the paths for a read-only scan. The CLI accepts repeatable
+`--reference-root` options for roots embedded in crates before a migration. The
+parser uses those roots as record boundaries. Without explicit roots, it recognizes
+generic macOS home and mounted-volume paths without embedding a username.
+
+## Edge Cases
+
+- A library may have references from more than one historical root.
+- Root paths may contain spaces or have leading/trailing separators.
+- Existing `/Users/...` and `/Volumes/...` crates must work without new flags.
+- A record without a recognized terminator remains ignored.
+
+## Verification
+
+Tests cover default root discovery, a custom migrated root, the CLI option, and
+the existing synthetic sample library. The scanner remains read-only.

docs/design/health-engine.md

@@ -0,0 +1,31 @@
+# Library Health Engine
+
+## Problem
+
+Raw missing-reference counts do not provide a compact view of library integrity,
+but an opaque blended score would imply confidence the current data cannot support.
+
+## Architecture
+
+The health engine produces an immutable report from the core `Library`. Its score
+is only the percentage of crate references resolved by exact filename. The report
+also exposes missing references, unique missing filenames, duplicate filename
+groups, extra duplicate files, unused tracks, and missing references with matching
+candidates.
+
+Duplicate, unused, and candidate counts are informational. They do not affect the
+score until the project has a documented and validated weighting policy. An empty
+library has no score rather than a misleading 0% or 100%.
+
+## Edge Cases
+
+- The same missing filename referenced by several crates.
+- Several disk files sharing a filename.
+- Conflict-suffixed files that are unused but may be match candidates.
+- Libraries with no crate references.
+- Tracks referenced by filename from more than one crate.
+
+## Verification
+
+Tests assert every metric, the disclosed score basis, candidate integration, and
+empty-library behavior. Analysis remains entirely read-only.

docs/design/logging.md

@@ -0,0 +1,25 @@
+# Application Logging
+
+## Problem
+
+The CLI reports final counts but provides no diagnostic trail when a scan behaves
+unexpectedly. Troubleshooting should not require adding print statements or expose
+library contents by default.
+
+## Architecture
+
+The project uses an isolated standard-library logger. It has no visible output by
+default. `--verbose` writes progress to standard error, while `--log-file PATH`
+writes an informational audit trail. Normal result lines remain on standard output.
+
+## Edge Cases
+
+- Reconfiguring logging in the same process must not duplicate handlers.
+- Console and file logging may be enabled together.
+- Log messages contain aggregate counts, not track names or crate contents.
+- A default scan must remain quiet except for its established result output.
+
+## Verification
+
+Tests verify quiet defaults, file output, handler replacement, and unchanged CLI
+result lines. The full sample-library scan remains read-only.

docs/design/matching-engine.md

@@ -0,0 +1,29 @@
+# Explainable Matching Engine
+
+## Problem
+
+Missing references need ranked candidate files, but a filename-only yes/no check
+cannot explain ambiguity or cloud-provider conflict names.
+
+## Architecture
+
+The read-only matching engine indexes normalized filenames and scores only related
+candidates. Every score contains evidence for filename, extension, and parent
+folder. Exact filenames earn 60 points, normalized names 55, numeric conflict-name
+matches 50, extensions 10, and parent folders 20.
+
+The displayed percentage is an evidence score, not a statistical probability.
+Metadata, duration, hashes, and fingerprints can add stronger evidence later.
+
+## Edge Cases
+
+- Unicode and case differences.
+- OneDrive-style names such as `Track 2.mp3`.
+- Duplicate candidates in different folders.
+- Legitimate numbered song titles, which remain candidates but are never repaired.
+- Unrelated names, which are not emitted as candidates.
+
+## Verification
+
+Tests cover exact, normalized, conflict-suffix, ambiguous, and unrelated filenames.
+Candidate ordering is deterministic. The engine never changes a track or reference.

samples/small-library/generate.py

@@ -7,7 +7,7 @@ from typing import Optional
 
 
 SAMPLE_ROOT = Path(__file__).parent
-SERATO_PATH_PREFIX = "Users/djsplice/OneDrive/Jukebox/"
+SERATO_PATH_PREFIX = "Users/sample-user/OneDrive/Jukebox/"
 
 
 def load_manifest() -> dict:

serato_doctor/cli.py

@@ -1,7 +1,9 @@
 from pathlib import Path
 import argparse
 
+from serato_doctor.config import ScanConfig
 from serato_doctor.crate_parser import parse_crates
+from serato_doctor.logging import configure_logging
 from serato_doctor.models.library import Library
 from serato_doctor.scanner import scan_audio
 from serato_doctor.report import write_csv, write_missing_report
@@ -13,28 +15,53 @@ def main():
     parser.add_argument("--music", default=str(Path.home() / "Library/CloudStorage/OneDrive-Personal/Jukebox"))
     parser.add_argument("--out", default=str(Path.home() / "Desktop/serato_doctor_scan.csv"))
     parser.add_argument("--report", default=str(Path.home() / "Desktop/serato_doctor_missing_report.txt"))
+    parser.add_argument(
+        "--reference-root",
+        action="append",
+        default=[],
+        help="Old library root stored in crates; may be supplied more than once",
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", help="Write diagnostic progress to stderr"
+    )
+    parser.add_argument("--log-file", help="Write scan progress to a log file")
     args = parser.parse_args()
 
-    serato = Path(args.serato)
-    music = Path(args.music)
-    out = Path(args.out)
-    report = Path(args.report)
+    config = ScanConfig.build(
+        serato=Path(args.serato),
+        music=Path(args.music),
+        out=Path(args.out),
+        report=Path(args.report),
+        reference_roots=(Path(root) for root in args.reference_root),
+        verbose=args.verbose,
+        log_file=Path(args.log_file) if args.log_file else None,
+    )
+    logger = configure_logging(config.verbose, config.log_file)
+    logger.info("Starting read-only library scan")
+    logger.debug("Serato directory: %s", config.serato)
+    logger.debug("Music directory: %s", config.music)
 
     library = Library.build(
-        references=parse_crates(serato / "Subcrates"),
-        tracks=scan_audio(music),
+        references=parse_crates(
+            config.serato / "Subcrates", config.reference_roots
+        ),
+        tracks=scan_audio(config.music),
     )
     results = library.reconcile_by_filename()
     missing_count = sum(1 for result in results if not result.exists_by_filename)
+    logger.info("Parsed %d crate references", len(library.references))
+    logger.info("Scanned %d disk tracks", len(library.tracks))
+    logger.info("Found %d references missing by filename", missing_count)
 
-    write_csv(results, out)
-    write_missing_report(results, report)
+    write_csv(results, config.out)
+    write_missing_report(results, config.report)
+    logger.info("Wrote CSV and missing-reference reports")
 
     print(f"Crate references: {len(library.references)}")
     print(f"Disk tracks: {len(library.tracks)}")
     print(f"Missing by filename: {missing_count}")
-    print(f"CSV: {out}")
-    print(f"Report: {report}")
+    print(f"CSV: {config.out}")
+    print(f"Report: {config.report}")
 
 
 if __name__ == "__main__":

serato_doctor/config.py

@@ -0,0 +1,37 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class ScanConfig:
+    """Read-only paths used for one library scan."""
+
+    serato: Path
+    music: Path
+    out: Path
+    report: Path
+    reference_roots: Tuple[Path, ...] = ()
+    verbose: bool = False
+    log_file: Optional[Path] = None
+
+    @classmethod
+    def build(
+        cls,
+        serato: Path,
+        music: Path,
+        out: Path,
+        report: Path,
+        reference_roots: Iterable[Path] = (),
+        verbose: bool = False,
+        log_file: Optional[Path] = None,
+    ) -> "ScanConfig":
+        return cls(
+            serato,
+            music,
+            out,
+            report,
+            tuple(reference_roots),
+            verbose,
+            log_file,
+        )

serato_doctor/crate_parser.py

@@ -1,4 +1,5 @@
 from pathlib import Path
+from typing import Iterable, Tuple
 
 from serato_doctor.models.crate import Crate
 from serato_doctor.models.reference import TrackReference
@@ -21,45 +22,63 @@ def clean_path(raw: str) -> str:
     return raw.strip()
 
 
-def load_crate(crate_path: Path) -> Crate:
+DEFAULT_PATH_MARKERS = ("Users/", "Volumes/")
+
+
+def path_markers(reference_roots: Iterable[Path]) -> Tuple[str, ...]:
+    configured = tuple(
+        root.expanduser().as_posix().strip("/") + "/" for root in reference_roots
+    )
+    return configured or DEFAULT_PATH_MARKERS
+
+
+def load_crate(crate_path: Path, reference_roots: Iterable[Path] = ()) -> Crate:
     text = read_crate_text(crate_path)
     refs = []
 
-    marker = "Users/djsplice/OneDrive/Jukebox/"
-
     # Serato record markers seen after paths in UTF-16-LE decoded crate data.
     stop_markers = ["牴k", "otrk", "ptrk", "tvcn", "ovct"]
 
-    for part in text.split(marker)[1:]:
-        candidate = marker + part
+    for marker in path_markers(reference_roots):
+        for part in text.split(marker)[1:]:
+            candidate = marker + part
 
-        stops = [candidate.find(m) for m in stop_markers if candidate.find(m) != -1]
-        if not stops:
-            continue
+            stops = [
+                candidate.find(stop)
+                for stop in stop_markers
+                if candidate.find(stop) != -1
+            ]
+            if not stops:
+                continue
 
-        raw_path = "/" + candidate[: min(stops)]
-        raw_path = clean_path(raw_path)
+            raw_path = "/" + candidate[: min(stops)]
+            raw_path = clean_path(raw_path)
 
-        path = Path(raw_path)
-        refs.append(
-            TrackReference(
-                source=crate_path,
-                path=path,
-                filename=path.name,
+            path = Path(raw_path)
+            refs.append(
+                TrackReference(
+                    source=crate_path,
+                    path=path,
+                    filename=path.name,
+                )
             )
-        )
 
     return Crate(path=crate_path, references=tuple(refs))
 
 
-def parse_crate(crate_path: Path) -> list[TrackReference]:
+def parse_crate(
+    crate_path: Path, reference_roots: Iterable[Path] = ()
+) -> list[TrackReference]:
     """Parse references from one crate, preserving the prototype API."""
 
-    return list(load_crate(crate_path).references)
+    return list(load_crate(crate_path, reference_roots).references)
 
 
-def parse_crates(root: Path) -> list[TrackReference]:
+def parse_crates(
+    root: Path, reference_roots: Iterable[Path] = ()
+) -> list[TrackReference]:
     refs = []
+    reference_roots = tuple(reference_roots)
     for crate in root.rglob("*.crate"):
-        refs.extend(parse_crate(crate))
+        refs.extend(parse_crate(crate, reference_roots))
     return refs

serato_doctor/health.py

@@ -0,0 +1,43 @@
+from collections import Counter
+
+from serato_doctor.matching import MatchingEngine
+from serato_doctor.models.health import HealthReport
+from serato_doctor.models.library import Library
+
+
+def analyze_health(library: Library) -> HealthReport:
+    """Calculate defensible health metrics without changing the library."""
+
+    results = library.reconcile_by_filename()
+    missing = [result for result in results if not result.exists_by_filename]
+    healthy_count = len(results) - len(missing)
+    score = (
+        round(healthy_count / len(results) * 100, 1) if results else None
+    )
+
+    disk_name_counts = Counter(track.filename for track in library.tracks)
+    duplicate_counts = [count for count in disk_name_counts.values() if count > 1]
+    referenced_names = {reference.filename for reference in library.references}
+    unused_count = sum(
+        1 for track in library.tracks if track.filename not in referenced_names
+    )
+
+    matcher = MatchingEngine(library.tracks)
+    suggested_count = sum(
+        bool(matcher.candidates_for(result.reference)) for result in missing
+    )
+
+    return HealthReport(
+        score=score,
+        total_references=len(results),
+        healthy_references=healthy_count,
+        missing_references=len(missing),
+        unique_missing_filenames=len(
+            {result.reference.filename for result in missing}
+        ),
+        disk_tracks=len(library.tracks),
+        duplicate_filename_groups=len(duplicate_counts),
+        duplicate_files=sum(count - 1 for count in duplicate_counts),
+        unused_tracks=unused_count,
+        suggested_matches=suggested_count,
+    )

serato_doctor/logging.py

@@ -0,0 +1,40 @@
+import logging
+from pathlib import Path
+from typing import Optional
+
+
+LOGGER_NAME = "serato_doctor"
+LOG_FORMAT = "%(asctime)s %(levelname)s %(message)s"
+
+
+def configure_logging(
+    verbose: bool = False, log_file: Optional[Path] = None
+) -> logging.Logger:
+    """Configure isolated application logging and return the project logger."""
+
+    logger = logging.getLogger(LOGGER_NAME)
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+
+    for handler in logger.handlers[:]:
+        handler.close()
+        logger.removeHandler(handler)
+
+    formatter = logging.Formatter(LOG_FORMAT)
+
+    if verbose:
+        console = logging.StreamHandler()
+        console.setLevel(logging.DEBUG)
+        console.setFormatter(formatter)
+        logger.addHandler(console)
+
+    if log_file is not None:
+        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+        file_handler.setLevel(logging.INFO)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    if not logger.handlers:
+        logger.addHandler(logging.NullHandler())
+
+    return logger

serato_doctor/matching.py

@@ -0,0 +1,86 @@
+import re
+import unicodedata
+from collections import defaultdict
+from pathlib import Path
+from typing import DefaultDict, Iterable, List, Tuple
+
+from serato_doctor.models.match import MatchEvidence, TrackMatch
+from serato_doctor.models.reference import TrackReference
+from serato_doctor.models.track import DiskTrack
+
+
+def normalize(value: str) -> str:
+    return unicodedata.normalize("NFKC", value).casefold()
+
+
+def cloud_conflict_name(filename: str) -> str:
+    """Remove a trailing numeric cloud-conflict suffix from a filename stem."""
+
+    path = Path(filename)
+    stem = re.sub(r" \d+$", "", path.stem)
+    return normalize(stem + path.suffix)
+
+
+def score_candidate(reference: TrackReference, track: DiskTrack) -> TrackMatch:
+    reference_name = reference.filename
+    track_name = track.filename
+
+    if reference_name == track_name:
+        filename_points = 60
+        filename_reason = "Filename is identical"
+    elif normalize(reference_name) == normalize(track_name):
+        filename_points = 55
+        filename_reason = "Filename matches after case and Unicode normalization"
+    elif cloud_conflict_name(reference_name) == cloud_conflict_name(track_name):
+        filename_points = 50
+        filename_reason = "Filename matches after removing a numeric conflict suffix"
+    else:
+        filename_points = 0
+        filename_reason = "Filename does not match"
+
+    same_extension = normalize(reference.path.suffix) == normalize(track.suffix)
+    same_parent = normalize(reference.path.parent.name) == normalize(
+        track.path.parent.name
+    )
+    evidence = (
+        MatchEvidence(
+            "filename",
+            filename_points > 0,
+            filename_points,
+            60,
+            filename_reason,
+        ),
+        MatchEvidence(
+            "extension",
+            same_extension,
+            10 if same_extension else 0,
+            10,
+            "File extension matches" if same_extension else "File extension differs",
+        ),
+        MatchEvidence(
+            "parent_folder",
+            same_parent,
+            20 if same_parent else 0,
+            20,
+            "Parent folder matches" if same_parent else "Parent folder differs",
+        ),
+    )
+    return TrackMatch(reference, track, evidence)
+
+
+class MatchingEngine:
+    """Find and rank filename-related disk candidates without modifying files."""
+
+    def __init__(self, tracks: Iterable[DiskTrack]):
+        self._by_conflict_name: DefaultDict[str, List[DiskTrack]] = defaultdict(list)
+        for track in tracks:
+            self._by_conflict_name[cloud_conflict_name(track.filename)].append(track)
+
+    def candidates_for(self, reference: TrackReference) -> Tuple[TrackMatch, ...]:
+        candidates = self._by_conflict_name.get(
+            cloud_conflict_name(reference.filename), []
+        )
+        matches = [score_candidate(reference, track) for track in candidates]
+        return tuple(
+            sorted(matches, key=lambda match: (-match.score, str(match.track.path)))
+        )

serato_doctor/models/__init__.py

@@ -1,6 +1,17 @@
 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
 from serato_doctor.models.track import DiskTrack
 
-__all__ = ["Crate", "DiskTrack", "Library", "ReferenceResult", "TrackReference"]
+__all__ = [
+    "Crate",
+    "DiskTrack",
+    "HealthReport",
+    "Library",
+    "MatchEvidence",
+    "ReferenceResult",
+    "TrackMatch",
+    "TrackReference",
+]

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"

serato_doctor/models/match.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from typing import Tuple
+
+from serato_doctor.models.reference import TrackReference
+from serato_doctor.models.track import DiskTrack
+
+
+@dataclass(frozen=True)
+class MatchEvidence:
+    """One explainable scoring decision for a candidate track."""
+
+    field: str
+    matched: bool
+    points: int
+    max_points: int
+    explanation: str
+
+
+@dataclass(frozen=True)
+class TrackMatch:
+    """A ranked candidate backed by explicit, inspectable evidence."""
+
+    reference: TrackReference
+    track: DiskTrack
+    evidence: Tuple[MatchEvidence, ...]
+
+    @property
+    def score(self) -> int:
+        return sum(item.points for item in self.evidence)
+
+    @property
+    def max_score(self) -> int:
+        return sum(item.max_points for item in self.evidence)
+
+    @property
+    def score_percent(self) -> float:
+        if not self.max_score:
+            return 0.0
+        return round(self.score / self.max_score * 100, 1)

tests/test_cli.py

@@ -12,8 +12,8 @@ def test_cli_writes_reports_and_prints_counts(tmp_path, monkeypatch, capsys):
     music.mkdir()
 
     crate_text = (
-        "Users/djsplice/OneDrive/Jukebox/Found.mp漳牴k"
-        "Users/djsplice/OneDrive/Jukebox/Missing.mp漳牴k"
+        "Users/sample-user/OneDrive/Jukebox/Found.mp漳牴k"
+        "Users/sample-user/OneDrive/Jukebox/Missing.mp漳牴k"
     )
     (subcrates / "Test.crate").write_bytes(crate_text.encode("utf-16-le"))
     (music / "Found.mp3").write_bytes(b"synthetic audio")
@@ -37,7 +37,9 @@ def test_cli_writes_reports_and_prints_counts(tmp_path, monkeypatch, capsys):
 
     main()
 
-    output = capsys.readouterr().out
+    captured = capsys.readouterr()
+    output = captured.out
+    assert captured.err == ""
     assert "Crate references: 2" in output
     assert "Disk tracks: 1" in output
     assert "Missing by filename: 1" in output
@@ -47,3 +49,38 @@ def test_cli_writes_reports_and_prints_counts(tmp_path, monkeypatch, capsys):
         rows = list(csv.DictReader(csv_file))
     assert [row["exists_by_filename"] for row in rows] == ["True", "False"]
     assert "Total missing references: 1" in report_path.read_text(encoding="utf-8")
+
+
+def test_cli_accepts_old_reference_root(tmp_path, monkeypatch, capsys):
+    serato = tmp_path / "serato"
+    subcrates = serato / "Subcrates"
+    music = tmp_path / "music"
+    subcrates.mkdir(parents=True)
+    music.mkdir()
+    (subcrates / "Test.crate").write_bytes(
+        "Archive/Jukebox/Found.mp3otrk".encode("utf-16-le")
+    )
+    (music / "Found.mp3").write_bytes(b"synthetic audio")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "serato-doctor",
+            "--serato",
+            str(serato),
+            "--music",
+            str(music),
+            "--out",
+            str(tmp_path / "scan.csv"),
+            "--report",
+            str(tmp_path / "report.txt"),
+            "--reference-root",
+            "/Archive/Jukebox",
+        ],
+    )
+
+    main()
+
+    output = capsys.readouterr().out
+    assert "Crate references: 1" in output
+    assert "Missing by filename: 0" in output

tests/test_config.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from serato_doctor.config import ScanConfig
+
+
+def test_scan_config_freezes_reference_roots():
+    roots = (Path(root) for root in ["/old/one", "/old/two"])
+
+    config = ScanConfig.build(
+        serato=Path("serato"),
+        music=Path("music"),
+        out=Path("scan.csv"),
+        report=Path("report.txt"),
+        reference_roots=roots,
+    )
+
+    assert config.reference_roots == (Path("/old/one"), Path("/old/two"))

tests/test_crates.py

@@ -2,7 +2,13 @@ from pathlib import Path
 
 import pytest
 
-from serato_doctor.crate_parser import clean_path, load_crate, parse_crate
+from serato_doctor.crate_parser import (
+    clean_path,
+    load_crate,
+    parse_crate,
+    parse_crates,
+    path_markers,
+)
 
 
 @pytest.mark.parametrize(
@@ -22,9 +28,9 @@ def test_parse_crate_extracts_references(tmp_path):
     crate_path = tmp_path / "House.crate"
     crate_text = (
         "header"
-        "Users/djsplice/OneDrive/Jukebox/House/First.mp漳牴k"
+        "Users/sample-user/OneDrive/Jukebox/House/First.mp漳牴k"
         "metadata"
-        "Users/djsplice/OneDrive/Jukebox/House/Second.m4愠otrk"
+        "Users/sample-user/OneDrive/Jukebox/House/Second.m4愠otrk"
     )
     crate_path.write_bytes(crate_text.encode("utf-16-le"))
 
@@ -41,7 +47,40 @@ def test_parse_crate_extracts_references(tmp_path):
 def test_parse_crate_ignores_record_without_stop_marker(tmp_path):
     crate_path = Path(tmp_path) / "Incomplete.crate"
     crate_path.write_bytes(
-        "Users/djsplice/OneDrive/Jukebox/House/Incomplete.mp3".encode("utf-16-le")
+        "Users/sample-user/OneDrive/Jukebox/House/Incomplete.mp3".encode(
+            "utf-16-le"
+        )
     )
 
     assert parse_crate(crate_path) == []
+
+
+def test_parse_crate_uses_configured_reference_root(tmp_path):
+    crate_path = tmp_path / "Migrated.crate"
+    crate_path.write_bytes(
+        "Archive/Old Library/House/Track.mp3otrk".encode("utf-16-le")
+    )
+
+    references = parse_crate(crate_path, [Path("/Archive/Old Library")])
+
+    assert references[0].path == Path("/Archive/Old Library/House/Track.mp3")
+
+
+def test_default_path_markers_do_not_contain_a_username():
+    assert path_markers([]) == ("Users/", "Volumes/")
+
+
+def test_parse_crates_reuses_configured_roots_for_every_crate(tmp_path):
+    for name in ("First", "Second"):
+        (tmp_path / f"{name}.crate").write_bytes(
+            f"Archive/Jukebox/{name}.mp3otrk".encode("utf-16-le")
+        )
+
+    references = parse_crates(
+        tmp_path, (root for root in [Path("/Archive/Jukebox")])
+    )
+
+    assert {reference.filename for reference in references} == {
+        "First.mp3",
+        "Second.mp3",
+    }

tests/test_health.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+from serato_doctor.health import analyze_health
+from serato_doctor.models.library import Library
+from serato_doctor.models.reference import TrackReference
+from serato_doctor.models.track import DiskTrack
+
+
+def reference(filename):
+    return TrackReference(
+        Path("Test.crate"), Path("/old/House") / filename, filename
+    )
+
+
+def track(filename, folder="House"):
+    path = Path("/new") / folder / filename
+    return DiskTrack(path, filename, 100, path.suffix.lower())
+
+
+def test_health_report_exposes_each_metric():
+    library = Library.build(
+        [
+            reference("Found.mp3"),
+            reference("Conflict.mp3"),
+            reference("Absent.mp3"),
+        ],
+        [
+            track("Found.mp3"),
+            track("Conflict 2.mp3"),
+            track("Conflict 2.mp3", "Backup"),
+            track("Unused.mp3"),
+        ],
+    )
+
+    report = analyze_health(library)
+
+    assert report.score == 33.3
+    assert report.score_basis == (
+        "Resolved crate references / total crate references"
+    )
+    assert report.total_references == 3
+    assert report.healthy_references == 1
+    assert report.missing_references == 2
+    assert report.unique_missing_filenames == 2
+    assert report.disk_tracks == 4
+    assert report.duplicate_filename_groups == 1
+    assert report.duplicate_files == 1
+    assert report.unused_tracks == 3
+    assert report.suggested_matches == 1
+
+
+def test_empty_library_has_no_health_score():
+    report = analyze_health(Library.build([], []))
+
+    assert report.score is None
+    assert report.total_references == 0

tests/test_logging.py

@@ -0,0 +1,34 @@
+import logging
+
+from serato_doctor.logging import LOGGER_NAME, configure_logging
+
+
+def test_logging_is_quiet_by_default(capsys):
+    logger = configure_logging()
+
+    logger.info("not visible")
+
+    assert capsys.readouterr().err == ""
+
+
+def test_logging_writes_aggregate_progress_to_file(tmp_path):
+    log_path = tmp_path / "scan.log"
+    logger = configure_logging(log_file=log_path)
+
+    logger.info("Scanned %d disk tracks", 10)
+
+    contents = log_path.read_text(encoding="utf-8")
+    assert "INFO Scanned 10 disk tracks" in contents
+
+
+def test_reconfiguring_logging_replaces_handlers():
+    configure_logging(verbose=True)
+    logger = configure_logging(verbose=True)
+
+    active_handlers = [
+        handler
+        for handler in logger.handlers
+        if not isinstance(handler, logging.NullHandler)
+    ]
+    assert logger.name == LOGGER_NAME
+    assert len(active_handlers) == 1

tests/test_matcher.py

@@ -0,0 +1,62 @@
+from pathlib import Path
+
+from serato_doctor.matching import MatchingEngine, score_candidate
+from serato_doctor.models.reference import TrackReference
+from serato_doctor.models.track import DiskTrack
+
+
+def reference(filename, folder="House"):
+    return TrackReference(
+        Path("Test.crate"), Path("/old") / folder / filename, filename
+    )
+
+
+def track(filename, folder="House"):
+    path = Path("/new") / folder / filename
+    return DiskTrack(path, filename, 100, path.suffix.lower())
+
+
+def test_exact_candidate_has_full_evidence_score():
+    match = score_candidate(reference("Track.mp3"), track("Track.mp3"))
+
+    assert match.score == 90
+    assert match.max_score == 90
+    assert match.score_percent == 100.0
+    assert all(item.matched for item in match.evidence)
+
+
+def test_cloud_conflict_suffix_is_explained():
+    match = score_candidate(reference("Track.mp3"), track("Track 2.mp3"))
+
+    assert match.score == 80
+    assert match.score_percent == 88.9
+    assert match.evidence[0].explanation == (
+        "Filename matches after removing a numeric conflict suffix"
+    )
+
+
+def test_case_normalized_match_scores_below_exact():
+    match = score_candidate(reference("TRACK.MP3"), track("track.mp3"))
+
+    assert match.score == 85
+    assert match.evidence[0].points == 55
+
+
+def test_engine_omits_unrelated_filenames():
+    engine = MatchingEngine([track("Different.mp3")])
+
+    assert engine.candidates_for(reference("Missing.mp3")) == ()
+
+
+def test_ambiguous_candidates_are_ranked_deterministically():
+    engine = MatchingEngine(
+        [track("Track 2.mp3", "Other"), track("Track 3.mp3", "House")]
+    )
+
+    matches = engine.candidates_for(reference("Track.mp3"))
+
+    assert [match.track.filename for match in matches] == [
+        "Track 3.mp3",
+        "Track 2.mp3",
+    ]
+    assert [match.score for match in matches] == [80, 60]