Add project roadmap and architecture docs

.gitignore

@@ -11,3 +11,6 @@ reports/
 # Never commit personal Serato data
 database V2
 *.crate
+
+# macOS
+.DS_Store

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# 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.

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
+- [ ] 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

pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "serato-doctor"
+version = "0.1.0"
+description = "Inspect, diagnose, repair, and migrate DJ libraries."
+requires-python = ">=3.9"
+dependencies = []
+
+[project.scripts]
+serato-doctor = "serato_doctor.cli:main"

serato_doctor/cli.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+import argparse
+
+from serato_doctor.crate_parser import parse_crates
+from serato_doctor.scanner import scan_audio
+from serato_doctor.report import write_csv, write_missing_report
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="serato-doctor")
+    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")
+    disk = scan_audio(music)
+
+    disk_names = {t.filename for t in disk}
+
+    rows = []
+    for ref in refs:
+        rows.append({
+            "crate": str(ref.source),
+            "serato_path": str(ref.path),
+            "filename": ref.filename,
+            "exists_by_filename": ref.filename in disk_names,
+        })
+
+    missing_count = sum(1 for r in rows if not r["exists_by_filename"])
+
+    write_csv(rows, out)
+    write_missing_report(rows, report)
+
+    print(f"Crate references: {len(refs)}")
+    print(f"Disk tracks: {len(disk)}")
+    print(f"Missing by filename: {missing_count}")
+    print(f"CSV: {out}")
+    print(f"Report: {report}")
+
+
+if __name__ == "__main__":
+    main()

serato_doctor/crate_parser.py

@@ -0,0 +1,58 @@
+from pathlib import Path
+
+from serato_doctor.models import TrackReference
+
+
+def read_crate_text(crate_path: Path) -> str:
+    return crate_path.read_bytes().decode("utf-16-le", errors="ignore").replace("\x00", "")
+
+
+def clean_path(raw: str) -> str:
+    # Common Serato decode artifacts where final extension char gets merged.
+    raw = raw.replace(".mp漳", ".mp3")
+    raw = raw.replace(".MP漳", ".MP3")
+    raw = raw.replace(".m4愠", ".m4a")
+    raw = raw.replace(".M4愠", ".M4A")
+    raw = raw.replace(".wa瘠", ".wav")
+    raw = raw.replace(".WA瘠", ".WAV")
+    raw = raw.replace(".ai映", ".aif")
+    raw = raw.replace(".AI映", ".AIF")
+    return raw.strip()
+
+
+def parse_crate(crate_path: Path) -> list[TrackReference]:
+    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
+
+        stops = [candidate.find(m) for m in stop_markers if candidate.find(m) != -1]
+        if not stops:
+            continue
+
+        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,
+            )
+        )
+
+    return refs
+
+
+def parse_crates(root: Path) -> list[TrackReference]:
+    refs = []
+    for crate in root.rglob("*.crate"):
+        refs.extend(parse_crate(crate))
+    return refs

serato_doctor/models.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class TrackReference:
+    source: Path
+    path: Path
+    filename: str
+
+
+@dataclass(frozen=True)
+class DiskTrack:
+    path: Path
+    filename: str
+    size: int
+    suffix: str

serato_doctor/report.py

@@ -0,0 +1,42 @@
+from collections import Counter, defaultdict
+from pathlib import Path
+import csv
+
+
+def write_missing_report(rows: list[dict], out: Path) -> None:
+    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(rows: list[dict], out: Path) -> None:
+    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

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from serato_doctor.models import DiskTrack
+
+AUDIO_SUFFIXES = {".mp3", ".m4a", ".wav", ".aif", ".aiff", ".flac"}
+
+
+def scan_audio(folder: Path) -> list[DiskTrack]:
+    tracks = []
+
+    for path in folder.rglob("*"):
+        if not path.is_file():
+            continue
+        if path.suffix.lower() not in AUDIO_SUFFIXES:
+            continue
+
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+
+        tracks.append(
+            DiskTrack(
+                path=path,
+                filename=path.name,
+                size=stat.st_size,
+                suffix=path.suffix.lower(),
+            )
+        )
+
+    return tracks