Establish automated test foundation

.gitignore

@@ -2,6 +2,7 @@ __pycache__/
 *.pyc
 .env
 .venv/
+*.egg-info/
 reports/
 *.sqlite
 *.db

CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+## Branching
+
+- `main` is stable.
+- `develop` is the integration branch.
+- Feature branches use: `feature/<name>`.
+
+## Safety Rules
+
+Never commit personal music library files, Serato databases, or crates.
+
+Never write repair code without dry-run mode, backup plan, and rollback log.
+
+## Testing
+
+Install development dependencies with `python3 -m pip install -e '.[dev]'`.
+
+Run `pytest` before committing. Tests and fixtures must use synthetic library data.

ROADMAP.md

@@ -0,0 +1,48 @@
+# Serato Doctor Roadmap
+
+## v0.1 — Library Inspector
+
+- [x] Project repository
+- [x] Filesystem scanner
+- [x] Serato crate parser
+- [x] Missing reference CSV report
+- [x] Grouped missing reference report
+- [ ] HTML health dashboard
+- [x] Test suite
+- [ ] Sample library fixtures
+- [ ] Database V2 read-only parser
+
+## v0.2 — Diagnostics
+
+- [ ] Duplicate filename detection
+- [ ] Duplicate audio hash detection
+- [ ] Broken symlink detection
+- [ ] Orphaned audio detection
+- [ ] OneDrive rename detection
+- [ ] Crate classification: static vs smart/dynamic
+- [ ] Library health score
+
+## v0.3 — Safe Repair
+
+- [ ] Dry-run repair plan
+- [ ] Backup before repair
+- [ ] Compatibility symlink creation
+- [ ] Compatibility copy creation
+- [ ] Rename repair
+- [ ] Rollback log
+
+## v0.4 — Migration Wizard
+
+- [ ] Move library root
+- [ ] Cloud provider migration
+- [ ] External drive migration
+- [ ] Verify moved library
+- [ ] Update application references
+
+## v1.0 — DJ Library Doctor
+
+- [ ] Desktop UI
+- [ ] Serato support
+- [ ] Rekordbox support
+- [ ] VirtualDJ support
+- [ ] Engine DJ support

docs/ARCHITECTURE.md

@@ -0,0 +1,11 @@
+# Architecture
+
+Serato Doctor is designed as a DJ library inspection, repair, and migration platform.
+
+## Design Principles
+
+1. Read-only by default.
+2. Every repair must support preview/dry-run.
+3. Every repair must create a backup or rollback path.
+4. Application-specific logic lives in engines.
+5. Core matching and scanning logic should be application-agnostic.

docs/case-studies/onedrive-mac-migration.md

@@ -0,0 +1,26 @@
+# Case Study: OneDrive Mac Migration
+
+## Scenario
+
+A large Serato DJ library was migrated from an older Mac to a newer Mac using OneDrive.
+
+## Symptoms
+
+- OneDrive client stuck syncing
+- Duplicate OneDrive folders
+- Thousands of files renamed with trailing ` 2`
+- Serato reported many tracks as missing
+- Some files existed on disk but still appeared orange in Serato
+
+## Findings
+
+- OneDrive sync state was rebuilt successfully
+- Thousands of orphaned filename conflicts were repaired
+- Some Serato references were stale database objects, not missing files
+- Smart/dynamic crates should be classified separately from static user crates
+
+## Lessons
+
+- Filesystem health and Serato database health are separate problems
+- Smart crates should not be treated the same as static crates
+- Repair tools must be read-only by default and generate a plan before changing anything

docs/design/test-foundation.md

@@ -0,0 +1,24 @@
+# Test Foundation
+
+## Problem
+
+The crate parser handles unusual binary text and known extension artifacts. Without
+automated tests, a small refactor could silently change library counts or reports.
+
+## Architecture
+
+Tests cover the read-only pipeline from crate and filesystem inputs through the
+core library model to CSV, text, and CLI output. All test data is synthetic and is
+created in temporary directories.
+
+## Edge Cases
+
+- Known MP3, M4A, WAV, and AIF decode artifacts.
+- Crate records without a recognized stop marker.
+- Supported extensions with mixed case and unsupported files.
+- References that exist by filename and references that remain missing.
+
+## Verification
+
+Run `pytest`. No test reads a real Serato library or writes outside pytest's
+temporary directory.

pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "serato-doctor"
+version = "0.1.0"
+description = "Inspect, diagnose, repair, and migrate DJ libraries."
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<9"]
+
+[project.scripts]
+serato-doctor = "serato_doctor.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+include = ["serato_doctor*"]

serato_doctor/cli.py

@@ -1,9 +1,10 @@
 from pathlib import Path
 import argparse
-import csv
 
 from serato_doctor.crate_parser import parse_crates
+from serato_doctor.models.library import Library
 from serato_doctor.scanner import scan_audio
+from serato_doctor.report import write_csv, write_missing_report
 
 
 def main():
@@ -11,35 +12,29 @@ def main():
     parser.add_argument("--serato", default=str(Path.home() / "Music/_Serato_"))
     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"))
     args = parser.parse_args()
 
     serato = Path(args.serato)
     music = Path(args.music)
     out = Path(args.out)
+    report = Path(args.report)
 
-    refs = parse_crates(serato / "Subcrates")
+    library = Library.build(
-    disk = scan_audio(music)
+        references=parse_crates(serato / "Subcrates"),
+        tracks=scan_audio(music),
+    )
+    results = library.reconcile_by_filename()
+    missing_count = sum(1 for result in results if not result.exists_by_filename)
 
-    disk_names = {t.filename for t in disk}
+    write_csv(results, out)
+    write_missing_report(results, report)
 
-    rows = []
+    print(f"Crate references: {len(library.references)}")
-    for ref in refs:
+    print(f"Disk tracks: {len(library.tracks)}")
-        rows.append({
+    print(f"Missing by filename: {missing_count}")
-            "crate": str(ref.source),
+    print(f"CSV: {out}")
-            "serato_path": str(ref.path),
+    print(f"Report: {report}")
-            "filename": ref.filename,
-            "exists_by_filename": ref.filename in disk_names,
-        })
-
-    with out.open("w", newline="", encoding="utf-8") as f:
-        writer = csv.DictWriter(f, fieldnames=["crate", "serato_path", "filename", "exists_by_filename"])
-        writer.writeheader()
-        writer.writerows(rows)
-
-    print(f"Crate references: {len(refs)}")
-    print(f"Disk tracks: {len(disk)}")
-    print(f"Missing by filename: {sum(1 for r in rows if not r['exists_by_filename'])}")
-    print(f"Wrote: {out}")
 
 
 if __name__ == "__main__":

serato_doctor/crate_parser.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
-from serato_doctor.models import TrackReference
+from serato_doctor.models.crate import Crate
+from serato_doctor.models.reference import TrackReference
 
 
 def read_crate_text(crate_path: Path) -> str:
@@ -20,7 +21,7 @@ def clean_path(raw: str) -> str:
     return raw.strip()
 
 
-def parse_crate(crate_path: Path) -> list[TrackReference]:
+def load_crate(crate_path: Path) -> Crate:
     text = read_crate_text(crate_path)
     refs = []
 
@@ -48,7 +49,13 @@ def parse_crate(crate_path: Path) -> list[TrackReference]:
             )
         )
 
-    return refs
+    return Crate(path=crate_path, references=tuple(refs))
+
+
+def parse_crate(crate_path: Path) -> list[TrackReference]:
+    """Parse references from one crate, preserving the prototype API."""
+
+    return list(load_crate(crate_path).references)
 
 
 def parse_crates(root: Path) -> list[TrackReference]:

serato_doctor/models/__init__.py

@@ -0,0 +1,6 @@
+from serato_doctor.models.crate import Crate
+from serato_doctor.models.library import Library
+from serato_doctor.models.reference import ReferenceResult, TrackReference
+from serato_doctor.models.track import DiskTrack
+
+__all__ = ["Crate", "DiskTrack", "Library", "ReferenceResult", "TrackReference"]

serato_doctor/models/crate.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Tuple
+
+from serato_doctor.models.reference import TrackReference
+
+
+@dataclass(frozen=True)
+class Crate:
+    """A Serato crate and the track references parsed from it."""
+
+    path: Path
+    references: Tuple[TrackReference, ...]

serato_doctor/models/library.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+from typing import Iterable, Tuple
+
+from serato_doctor.models.reference import ReferenceResult, TrackReference
+from serato_doctor.models.track import DiskTrack
+
+
+@dataclass(frozen=True)
+class Library:
+    """The read-only view of crate references and audio found on disk."""
+
+    references: Tuple[TrackReference, ...]
+    tracks: Tuple[DiskTrack, ...]
+
+    @classmethod
+    def build(
+        cls,
+        references: Iterable[TrackReference],
+        tracks: Iterable[DiskTrack],
+    ) -> "Library":
+        return cls(tuple(references), tuple(tracks))
+
+    def reconcile_by_filename(self) -> Tuple[ReferenceResult, ...]:
+        disk_names = {track.filename for track in self.tracks}
+        return tuple(
+            ReferenceResult(
+                reference=reference,
+                exists_by_filename=reference.filename in disk_names,
+            )
+            for reference in self.references
+        )

serato_doctor/models/reference.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class TrackReference:
+    """A track path referenced by a Serato crate."""
+
+    source: Path
+    path: Path
+    filename: str
+
+
+@dataclass(frozen=True)
+class ReferenceResult:
+    """The filename-level reconciliation result for a crate reference."""
+
+    reference: TrackReference
+    exists_by_filename: bool
+
+    def as_row(self) -> dict:
+        return {
+            "crate": str(self.reference.source),
+            "serato_path": str(self.reference.path),
+            "filename": self.reference.filename,
+            "exists_by_filename": self.exists_by_filename,
+        }

serato_doctor/models/track.py

@@ -2,15 +2,10 @@ from dataclasses import dataclass
 from pathlib import Path
 
 
-@dataclass(frozen=True)
-class TrackReference:
-    source: Path
-    path: Path
-    filename: str
-
-
 @dataclass(frozen=True)
 class DiskTrack:
+    """An audio file discovered on disk."""
+
     path: Path
     filename: str
     size: int

serato_doctor/report.py

@@ -0,0 +1,47 @@
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Iterable
+import csv
+
+from serato_doctor.models.reference import ReferenceResult
+
+
+def write_missing_report(results: Iterable[ReferenceResult], out: Path) -> None:
+    rows = [result.as_row() for result in results]
+    missing = [r for r in rows if not r["exists_by_filename"]]
+
+    crate_counts = Counter(r["crate"] for r in missing)
+    filename_counts = Counter(r["filename"] for r in missing)
+
+    with out.open("w", encoding="utf-8") as f:
+        f.write("# Serato Doctor Missing Report\n\n")
+        f.write(f"Total missing references: {len(missing)}\n\n")
+
+        f.write("## Missing by crate\n\n")
+        for crate, count in crate_counts.most_common():
+            f.write(f"{count:5}  {crate}\n")
+
+        f.write("\n## Most common missing filenames\n\n")
+        for filename, count in filename_counts.most_common(100):
+            f.write(f"{count:5}  {filename}\n")
+
+        f.write("\n## Detail\n\n")
+        by_crate = defaultdict(list)
+        for r in missing:
+            by_crate[r["crate"]].append(r["filename"])
+
+        for crate, names in sorted(by_crate.items()):
+            f.write(f"\n### {crate}\n")
+            for name in sorted(set(names)):
+                f.write(f"- {name}\n")
+
+
+def write_csv(results: Iterable[ReferenceResult], out: Path) -> None:
+    rows = [result.as_row() for result in results]
+    with out.open("w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(
+            f,
+            fieldnames=["crate", "serato_path", "filename", "exists_by_filename"],
+        )
+        writer.writeheader()
+        writer.writerows(rows)

serato_doctor/scanner.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from serato_doctor.models import DiskTrack
+from serato_doctor.models.track import DiskTrack
 
 AUDIO_SUFFIXES = {".mp3", ".m4a", ".wav", ".aif", ".aiff", ".flac"}
 

tests/test_cli.py

@@ -0,0 +1,49 @@
+import csv
+import sys
+
+from serato_doctor.cli import main
+
+
+def test_cli_writes_reports_and_prints_counts(tmp_path, monkeypatch, capsys):
+    serato = tmp_path / "serato"
+    subcrates = serato / "Subcrates"
+    music = tmp_path / "music"
+    subcrates.mkdir(parents=True)
+    music.mkdir()
+
+    crate_text = (
+        "Users/djsplice/OneDrive/Jukebox/Found.mp漳牴k"
+        "Users/djsplice/OneDrive/Jukebox/Missing.mp漳牴k"
+    )
+    (subcrates / "Test.crate").write_bytes(crate_text.encode("utf-16-le"))
+    (music / "Found.mp3").write_bytes(b"synthetic audio")
+    csv_path = tmp_path / "scan.csv"
+    report_path = tmp_path / "report.txt"
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "serato-doctor",
+            "--serato",
+            str(serato),
+            "--music",
+            str(music),
+            "--out",
+            str(csv_path),
+            "--report",
+            str(report_path),
+        ],
+    )
+
+    main()
+
+    output = capsys.readouterr().out
+    assert "Crate references: 2" in output
+    assert "Disk tracks: 1" in output
+    assert "Missing by filename: 1" in output
+    assert f"CSV: {csv_path}" in output
+    assert f"Report: {report_path}" in output
+    with csv_path.open(newline="", encoding="utf-8") as csv_file:
+        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")

tests/test_crates.py

@@ -0,0 +1,47 @@
+from pathlib import Path
+
+import pytest
+
+from serato_doctor.crate_parser import clean_path, load_crate, parse_crate
+
+
+@pytest.mark.parametrize(
+    ("artifact", "expected"),
+    [
+        ("song.mp漳", "song.mp3"),
+        ("song.m4愠", "song.m4a"),
+        ("song.wa瘠", "song.wav"),
+        ("song.ai映", "song.aif"),
+    ],
+)
+def test_clean_path_repairs_known_extension_artifacts(artifact, expected):
+    assert clean_path(artifact) == expected
+
+
+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"
+        "metadata"
+        "Users/djsplice/OneDrive/Jukebox/House/Second.m4愠otrk"
+    )
+    crate_path.write_bytes(crate_text.encode("utf-16-le"))
+
+    crate = load_crate(crate_path)
+
+    assert crate.path == crate_path
+    assert [reference.filename for reference in crate.references] == [
+        "First.mp3",
+        "Second.m4a",
+    ]
+    assert parse_crate(crate_path) == list(crate.references)
+
+
+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")
+    )
+
+    assert parse_crate(crate_path) == []

tests/test_library.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+from serato_doctor.models.library import Library
+from serato_doctor.models.reference import TrackReference
+from serato_doctor.models.track import DiskTrack
+
+
+def test_library_reconciles_references_by_filename():
+    crate = Path("House.crate")
+    references = [
+        TrackReference(crate, Path("/old/Found.mp3"), "Found.mp3"),
+        TrackReference(crate, Path("/old/Missing.mp3"), "Missing.mp3"),
+    ]
+    tracks = [DiskTrack(Path("/new/Found.mp3"), "Found.mp3", 10, ".mp3")]
+
+    results = Library.build(references, tracks).reconcile_by_filename()
+
+    assert [result.exists_by_filename for result in results] == [True, False]
+    assert results[1].as_row() == {
+        "crate": "House.crate",
+        "serato_path": "/old/Missing.mp3",
+        "filename": "Missing.mp3",
+        "exists_by_filename": False,
+    }

tests/test_scanner.py

@@ -0,0 +1,17 @@
+from serato_doctor.scanner import scan_audio
+
+
+def test_scan_audio_finds_supported_files(tmp_path):
+    music = tmp_path / "music"
+    nested = music / "House"
+    nested.mkdir(parents=True)
+    (nested / "First.MP3").write_bytes(b"synthetic audio")
+    (nested / "Second.flac").write_bytes(b"fixture")
+    (nested / "notes.txt").write_text("not audio", encoding="utf-8")
+
+    tracks = scan_audio(music)
+
+    assert {track.filename for track in tracks} == {"First.MP3", "Second.flac"}
+    first = next(track for track in tracks if track.filename == "First.MP3")
+    assert first.suffix == ".mp3"
+    assert first.size == len(b"synthetic audio")