Merge feature/smart-crate-discovery into develop

.gitignore

@@ -9,6 +9,7 @@ samples/small-library/generated/
 *.db
 *.csv
 *.html
+!serato_doctor/webui/*.html
 
 # Never commit personal Serato data
 database V2

README.md

@@ -0,0 +1,48 @@
+# Serato Doctor
+
+Serato Doctor is a read-only-first toolkit for inspecting and eventually repairing
+DJ libraries. Serato is the first supported engine.
+
+## Analyze a Library
+
+```shell
+serato-doctor analyze \
+  --serato ~/Music/_Serato_ \
+  --music ~/Music/Jukebox
+```
+
+Analysis prints a transparent reference-integrity score plus broken references,
+duplicate filenames, unused tracks, and suggested filename matches. It does not
+modify the library or create report files.
+
+If crates contain an older library root, supply it explicitly:
+
+```shell
+serato-doctor analyze --reference-root /Users/old-user/OneDrive/Jukebox
+```
+
+## Generate Detailed Reports
+
+Running without a command preserves the original scanner behavior and writes CSV
+and text reports:
+
+```shell
+serato-doctor --serato ~/Music/_Serato_ --music ~/Music/Jukebox
+```
+
+Use `--verbose` for progress on standard error or `--log-file PATH` for an
+aggregate diagnostic log.
+
+Serato Doctor never repairs files without an explicit future repair workflow,
+preview, backup, and rollback path.
+
+## Local Web Interface
+
+Launch the responsive, local-only dashboard with:
+
+```shell
+serato-doctor-web
+```
+
+Then open `http://127.0.0.1:8765`. The interface exposes the same read-only health
+analysis and never sends library paths or results to an external service.

ROADMAP.md

@@ -7,7 +7,7 @@
 - [x] Serato crate parser
 - [x] Missing reference CSV report
 - [x] Grouped missing reference report
-- [ ] HTML health dashboard
+- [x] HTML health dashboard
 - [x] Test suite
 - [x] Sample library fixtures
 - [ ] Database V2 read-only parser
@@ -17,13 +17,14 @@
 
 ## v0.2 — Diagnostics
 
-- [ ] Duplicate filename detection
+- [x] `serato-doctor analyze` command
+- [x] Duplicate filename detection
 - [ ] Duplicate audio hash detection
-- [ ] Broken symlink detection
+- [x] Broken symlink detection
 - [ ] Orphaned audio detection
 - [ ] OneDrive rename detection
-- [ ] Crate classification: static vs smart/dynamic
+- [x] Crate classification: static vs smart/dynamic
-- [ ] Library health score
+- [x] Library health score
 
 ## v0.3 — Safe Repair
 

docs/design/analyze-command.md

@@ -0,0 +1,27 @@
+# Analyze Command
+
+## Problem
+
+The health and matching engines are only Python APIs. Users need one safe command
+that summarizes library integrity without first interpreting CSV files.
+
+## Architecture
+
+`serato-doctor analyze` reuses the existing configured crate parser and filesystem
+scanner, then prints the immutable health report. The original no-command mode is
+retained as the report-producing scan workflow.
+
+Analyze mode does not create CSV or text reports. Both modes remain read-only with
+respect to Serato crates, databases, and music files.
+
+## Edge Cases
+
+- A library with no references displays `Not assessed` rather than a false score.
+- Historical roots continue to work through repeatable `--reference-root` flags.
+- Normal output remains separate from optional diagnostic logging.
+- Existing scripts that invoke the CLI without a subcommand remain compatible.
+
+## Verification
+
+Tests prove the legacy five-line output and reports remain unchanged, while analyze
+prints health metrics and does not create output files.

docs/design/broken-symlinks.md

@@ -0,0 +1,27 @@
+# Broken Symlink Detection
+
+## Problem
+
+Library migrations may leave symbolic links pointing to files or folders that no
+longer exist. The filesystem scanner previously skipped those links silently.
+
+## Architecture
+
+One read-only filesystem traversal now returns audio tracks and broken symbolic
+links. Each finding preserves the link path and its raw target when the operating
+system can read it. The library and health report retain only immutable findings.
+
+Broken links are reported separately and do not affect the reference-integrity
+score. The detector does not follow, recreate, remove, or rewrite any link.
+
+## Edge Cases
+
+- Relative and absolute link targets.
+- Links to missing files and missing directories.
+- Link targets that cannot be read due to an operating-system error.
+- Valid symlinks, which remain eligible for ordinary audio scanning.
+
+## Verification
+
+Tests create synthetic valid and broken links in temporary directories, verify the
+raw target, and confirm health integration. Existing scanner behavior is preserved.

docs/design/crate-classification.md

@@ -0,0 +1,38 @@
+# Crate Classification
+
+## Problem
+
+Static crates are manually maintained track lists. Smart crates are dynamic views
+generated from rules, so stale-looking entries in them should not be presented as
+broken manual references or given the same health-score weight.
+
+## Architecture
+
+Crates carry a `static`, `smart`, or `unknown` kind. Folder provenance is the
+primary signal: Serato stores regular `.crate` files in `Subcrates` and smart
+`.scrate` definitions in `SmartCrates`. `Compatible by key.crate` is also treated as smart
+when encountered in `Subcrates`, based on the original migration case study.
+
+Smart crate names use `≫≫` to encode hierarchy. The model preserves those segments,
+so `Compatible by key≫≫10A.scrate` has a parent of `Compatible by key` and a display
+name of `10A`. Smart definitions and dynamic `.crate` containers are counted
+separately.
+
+The library loader reads both folders. Health analysis reports all references but
+scores only non-smart references. Unknown crates remain scoreable so incomplete
+classification cannot silently hide potential problems.
+
+Serato documents the folder distinction in [What is in the _Serato_ folder?](https://support.serato.com/hc/en-us/articles/204022904-What-is-in-the-Serato-folder)
+and explains that smart crates are populated from rules in [Crates in Serato DJ](https://support.serato.com/hc/en-us/articles/227561407-Crates-in-Serato-DJ-Pro-Serato-DJ-Lite).
+
+## Edge Cases
+
+- The known `Compatible by key` dynamic crate in the `Subcrates` folder.
+- Crate fixtures outside a recognized Serato folder.
+- Libraries containing both static and smart references to the same track.
+- Dynamic references whose current materialized paths appear missing.
+
+## Verification
+
+Tests cover all three kinds, both Serato folders, the known dynamic fallback, the
+synthetic five-static/two-smart library, and exclusion from health scoring.

docs/design/duplicate-filenames.md

@@ -0,0 +1,32 @@
+# Duplicate Filename Detection
+
+## Problem
+
+Two files with the same filename may be ordinary copies, while names such as
+`Track.mp3` and `Track 2.mp3` may indicate a OneDrive conflict. These cases need
+review, but neither is sufficient evidence for deletion.
+
+## Architecture
+
+The duplicate detector emits immutable groups of two kinds:
+
+- `exact_name` groups filenames after case and Unicode normalization.
+- `cloud_conflict` groups names after additionally removing a trailing numeric
+  suffix from the stem.
+
+Groups contain every path, a stable comparison key, a display name, and the number
+of files beyond the first. Health analysis reports exact and suspected-conflict
+counts separately. Neither category changes the health score.
+
+## Edge Cases
+
+- Same filename in different folders.
+- Case-only and Unicode representation differences.
+- Multiple conflict suffixes such as `Track 2.mp3` and `Track 3.mp3`.
+- Legitimate numbered titles, which remain explicitly labeled as suspected.
+- A single file, which is never reported as a duplicate.
+
+## Verification
+
+Tests cover exact, normalized, conflict-family, unrelated, and deterministic-order
+behavior, plus integration with health analysis. Detection is read-only.

docs/design/health-engine.md

@@ -0,0 +1,32 @@
+# 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 non-dynamic crate references resolved by exact filename.
+Smart-crate references are counted but excluded because their contents are derived
+from rules. 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/smart-crate-discovery.md

@@ -0,0 +1,19 @@
+# Smart Crate Discovery Correction
+
+## Problem
+
+The first classifier searched `SmartCrates` for `*.crate`. Real Serato smart-crate
+definitions use `.scrate`, so a library with 26 definitions displayed only the
+single name-based `Compatible by key.crate` fallback.
+
+## Correction
+
+Library discovery now reads `.scrate` definitions case-insensitively from the
+`SmartCrates` folder. Dynamic `.crate` containers remain excluded from manual
+reference scoring but are reported separately. The `≫≫` filename separator is
+preserved as smart-crate hierarchy metadata.
+
+## Verification
+
+Synthetic tests cover `.scrate` discovery, case-correct folder names, hierarchy,
+definition/container counts, and the existing five-static/two-smart sample.

docs/design/web-interface.md

@@ -0,0 +1,37 @@
+# Local Web Interface
+
+![Approved Serato Doctor dashboard concept](web-dashboard-concept.png)
+
+The generated concept above is the approved visual direction. The implemented UI
+keeps its hierarchy, palette, safety emphasis, health ring, diagnostic cards, and
+responsive behavior. Product truth takes precedence over mockup copy: a 77.8%
+library is labeled for review rather than described as healthy.
+
+## Problem
+
+The command line is useful for automation but makes the growing diagnostic set
+harder to explore. A visual dashboard lets users test analysis safely and understand
+which findings affect health.
+
+## Architecture
+
+`serato-doctor-web` binds to `127.0.0.1:8765` by default and serves package-owned
+HTML, CSS, and JavaScript with Python's standard library. A same-origin JSON endpoint
+runs the existing read-only parser, scanner, matcher, duplicate detector, crate
+classifier, and health engine. No web framework or external service is required.
+
+The UI clearly labels read-only mode, separates scored health from informational
+diagnostics, and adapts from a full sidebar layout to compact mobile navigation.
+
+## Edge Cases
+
+- Missing or invalid Serato and music directories.
+- Empty libraries with no assessable health score.
+- Large or malformed requests, capped at 64 KiB.
+- HTML injection, avoided by rendering all results through `textContent`.
+- Network exposure, avoided by a loopback-only default binding.
+
+## Verification
+
+Tests exercise the web analysis adapter and static package assets. Browser checks
+cover real form submission, result rendering, error display, and responsive layout.

pyproject.toml

@@ -14,9 +14,13 @@ dev = ["pytest>=8,<9"]
 
 [project.scripts]
 serato-doctor = "serato_doctor.cli:main"
+serato-doctor-web = "serato_doctor.web:main"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
 [tool.setuptools.packages.find]
 include = ["serato_doctor*"]
+
+[tool.setuptools.package-data]
+"serato_doctor.webui" = ["*.html", "*.css", "*.js"]

samples/small-library/generate.py

@@ -18,8 +18,7 @@ def build_sample(output: Optional[Path] = None) -> Path:
     root = output or SAMPLE_ROOT / "generated"
     manifest = load_manifest()
     music_root = root / "Music"
-    crate_root = root / "Serato" / "_Serato_" / "Subcrates"
+    serato_root = root / "Serato" / "_Serato_"
-    crate_root.mkdir(parents=True, exist_ok=True)
 
     for relative_path in manifest["tracks"]:
         track_path = music_root / relative_path
@@ -29,11 +28,28 @@ def build_sample(output: Optional[Path] = None) -> Path:
         )
 
     for crate in manifest["crates"]:
+        is_smart = crate["type"] == "smart"
+        folder_name = "SmartCrates" if is_smart else "Subcrates"
+        crate_root = serato_root / folder_name
+        crate_root.mkdir(parents=True, exist_ok=True)
+        output_name = (
+            Path(crate["name"]).with_suffix(".scrate").name
+            if is_smart
+            else crate["name"]
+        )
+        for other_folder in ("Subcrates", "Smartcrates", "SmartCrates"):
+            for stale_name in (
+                crate["name"],
+                Path(crate["name"]).with_suffix(".scrate").name,
+            ):
+                stale_path = serato_root / other_folder / stale_name
+                if stale_path.exists() and stale_path != crate_root / output_name:
+                    stale_path.unlink()
         records = "".join(
             f"{SERATO_PATH_PREFIX}{relative_path}otrk"
             for relative_path in crate["references"]
         )
-        (crate_root / crate["name"]).write_bytes(records.encode("utf-16-le"))
+        (crate_root / output_name).write_bytes(records.encode("utf-16-le"))
 
     return root
 

serato_doctor/cli.py

@@ -2,19 +2,33 @@ from pathlib import Path
 import argparse
 
 from serato_doctor.config import ScanConfig
-from serato_doctor.crate_parser import parse_crates
+from serato_doctor.crate_parser import load_library_crates
+from serato_doctor.health import analyze_health
 from serato_doctor.logging import configure_logging
 from serato_doctor.models.library import Library
-from serato_doctor.scanner import scan_audio
+from serato_doctor.scanner import scan_filesystem
 from serato_doctor.report import write_csv, write_missing_report
 
 
 def main():
     parser = argparse.ArgumentParser(prog="serato-doctor")
+    parser.add_argument(
+        "command", nargs="?", choices=("scan", "analyze"), default="scan"
+    )
     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(
-    parser.add_argument("--out", default=str(Path.home() / "Desktop/serato_doctor_scan.csv"))
+        "--music",
-    parser.add_argument("--report", default=str(Path.home() / "Desktop/serato_doctor_missing_report.txt"))
+        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",
@@ -37,15 +51,16 @@ def main():
         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.info("Starting read-only library inspection")
     logger.debug("Serato directory: %s", config.serato)
     logger.debug("Music directory: %s", config.music)
 
-    library = Library.build(
+    crates = load_library_crates(config.serato, config.reference_roots)
-        references=parse_crates(
+    filesystem = scan_filesystem(config.music)
-            config.serato / "Subcrates", config.reference_roots
+    library = Library.from_crates(
-        ),
+        crates=crates,
-        tracks=scan_audio(config.music),
+        tracks=filesystem.tracks,
+        broken_symlinks=filesystem.broken_symlinks,
     )
     results = library.reconcile_by_filename()
     missing_count = sum(1 for result in results if not result.exists_by_filename)
@@ -53,15 +68,46 @@ def main():
     logger.info("Scanned %d disk tracks", len(library.tracks))
     logger.info("Found %d references missing by filename", missing_count)
 
-    write_csv(results, config.out)
+    if args.command == "analyze":
-    write_missing_report(results, config.report)
+        health = analyze_health(library)
-    logger.info("Wrote CSV and missing-reference reports")
+        score = f"{health.score:.1f}%" if health.score is not None else "Not assessed"
-
+        logger.info("Calculated library health: %s", score)
-    print(f"Crate references: {len(library.references)}")
+        print(f"Overall Health: {score}")
-    print(f"Disk tracks: {len(library.tracks)}")
+        print(f"Score Basis: {health.score_basis}")
-    print(f"Missing by filename: {missing_count}")
+        print(f"Tracks: {health.disk_tracks}")
-    print(f"CSV: {config.out}")
+        print(f"Crate References: {health.total_references}")
-    print(f"Report: {config.report}")
+        print(f"References Scored: {health.scored_references}")
+        print(f"Healthy References: {health.healthy_references}")
+        print(f"Broken References: {health.missing_references}")
+        print(f"Unique Missing Filenames: {health.unique_missing_filenames}")
+        print(f"Duplicate Filename Groups: {health.duplicate_filename_groups}")
+        print(f"Duplicate Files: {health.duplicate_files}")
+        print(
+            "Suspected Cloud Conflict Groups: "
+            f"{health.suspected_cloud_conflict_groups}"
+        )
+        print(
+            "Suspected Cloud Conflict Files: "
+            f"{health.suspected_cloud_conflict_files}"
+        )
+        print(f"Unused Tracks: {health.unused_tracks}")
+        print(f"Suggested Matches: {health.suggested_matches}")
+        print(f"Broken Symlinks: {health.broken_symlinks}")
+        print(f"Static Crates: {health.static_crates}")
+        print(f"Smart Crates: {health.smart_crates}")
+        print(f"Smart Crate Containers: {health.smart_crate_containers}")
+        print(
+            f"Dynamic References Excluded: {health.dynamic_references_excluded}"
+        )
+    else:
+        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: {config.out}")
+        print(f"Report: {config.report}")
 
 
 if __name__ == "__main__":

serato_doctor/crate_parser.py

@@ -1,7 +1,7 @@
 from pathlib import Path
 from typing import Iterable, Tuple
 
-from serato_doctor.models.crate import Crate
+from serato_doctor.models.crate import Crate, CrateKind
 from serato_doctor.models.reference import TrackReference
 
 
@@ -32,6 +32,17 @@ def path_markers(reference_roots: Iterable[Path]) -> Tuple[str, ...]:
     return configured or DEFAULT_PATH_MARKERS
 
 
+def classify_crate(crate_path: Path) -> CrateKind:
+    parent_names = {parent.name.casefold() for parent in crate_path.parents}
+    if "smartcrates" in parent_names:
+        return CrateKind.SMART
+    if crate_path.name.casefold() == "compatible by key.crate":
+        return CrateKind.SMART
+    if "subcrates" in parent_names:
+        return CrateKind.STATIC
+    return CrateKind.UNKNOWN
+
+
 def load_crate(crate_path: Path, reference_roots: Iterable[Path] = ()) -> Crate:
     text = read_crate_text(crate_path)
     refs = []
@@ -63,7 +74,11 @@ def load_crate(crate_path: Path, reference_roots: Iterable[Path] = ()) -> Crate:
                 )
             )
 
-    return Crate(path=crate_path, references=tuple(refs))
+    return Crate(
+        path=crate_path,
+        references=tuple(refs),
+        kind=classify_crate(crate_path),
+    )
 
 
 def parse_crate(
@@ -82,3 +97,25 @@ def parse_crates(
     for crate in root.rglob("*.crate"):
         refs.extend(parse_crate(crate, reference_roots))
     return refs
+
+
+def load_library_crates(
+    serato_root: Path, reference_roots: Iterable[Path] = ()
+) -> Tuple[Crate, ...]:
+    reference_roots = tuple(reference_roots)
+    if not serato_root.is_dir():
+        return ()
+
+    crates = []
+    folder_patterns = {
+        "subcrates": ("*.crate",),
+        "smartcrates": ("*.scrate", "*.crate"),
+    }
+    for folder in serato_root.iterdir():
+        patterns = folder_patterns.get(folder.name.casefold())
+        if patterns is None or not folder.is_dir():
+            continue
+        for pattern in patterns:
+            for crate_path in folder.rglob(pattern):
+                crates.append(load_crate(crate_path, reference_roots))
+    return tuple(sorted(crates, key=lambda crate: str(crate.path)))

serato_doctor/duplicates.py

@@ -0,0 +1,41 @@
+from collections import defaultdict
+from typing import DefaultDict, Iterable, List, Tuple
+
+from serato_doctor.matching import cloud_conflict_name, normalize
+from serato_doctor.models.duplicate import DuplicateGroup, DuplicateKind
+from serato_doctor.models.track import DiskTrack
+
+
+def find_duplicate_groups(
+    tracks: Iterable[DiskTrack],
+) -> Tuple[DuplicateGroup, ...]:
+    """Find exact-name duplicates and suspected numeric conflict copies."""
+
+    track_tuple = tuple(tracks)
+    by_name: DefaultDict[str, List[DiskTrack]] = defaultdict(list)
+    by_conflict_name: DefaultDict[str, List[DiskTrack]] = defaultdict(list)
+
+    for track in track_tuple:
+        by_name[normalize(track.filename)].append(track)
+        by_conflict_name[cloud_conflict_name(track.filename)].append(track)
+
+    groups = []
+    for key, matches in by_name.items():
+        if len(matches) > 1:
+            groups.append(_group(DuplicateKind.EXACT_NAME, key, matches))
+
+    for key, matches in by_conflict_name.items():
+        distinct_names = {normalize(track.filename) for track in matches}
+        if len(distinct_names) > 1:
+            groups.append(_group(DuplicateKind.CLOUD_CONFLICT, key, matches))
+
+    return tuple(
+        sorted(groups, key=lambda group: (group.kind.value, group.comparison_key))
+    )
+
+
+def _group(
+    kind: DuplicateKind, key: str, tracks: Iterable[DiskTrack]
+) -> DuplicateGroup:
+    ordered = tuple(sorted(tracks, key=lambda track: str(track.path)))
+    return DuplicateGroup(kind, key, ordered)

serato_doctor/health.py

@@ -0,0 +1,85 @@
+from serato_doctor.duplicates import find_duplicate_groups
+from serato_doctor.matching import MatchingEngine
+from serato_doctor.models.crate import CrateKind
+from serato_doctor.models.duplicate import DuplicateKind
+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."""
+
+    dynamic_sources = {
+        crate.path for crate in library.crates if crate.kind is CrateKind.SMART
+    }
+    results = tuple(
+        result
+        for result in library.reconcile_by_filename()
+        if result.reference.source not in dynamic_sources
+    )
+    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
+    )
+
+    duplicate_groups = find_duplicate_groups(library.tracks)
+    exact_duplicates = [
+        group
+        for group in duplicate_groups
+        if group.kind is DuplicateKind.EXACT_NAME
+    ]
+    cloud_conflicts = [
+        group
+        for group in duplicate_groups
+        if group.kind is DuplicateKind.CLOUD_CONFLICT
+    ]
+    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(library.references),
+        scored_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(exact_duplicates),
+        duplicate_files=sum(group.extra_files for group in exact_duplicates),
+        suspected_cloud_conflict_groups=len(cloud_conflicts),
+        suspected_cloud_conflict_files=sum(
+            group.extra_files for group in cloud_conflicts
+        ),
+        unused_tracks=unused_count,
+        suggested_matches=suggested_count,
+        broken_symlinks=len(library.broken_symlinks),
+        static_crates=sum(
+            crate.kind is CrateKind.STATIC for crate in library.crates
+        ),
+        smart_crates=sum(
+            crate.kind is CrateKind.SMART and crate.is_smart_definition
+            for crate in library.crates
+        ),
+        smart_crate_containers=sum(
+            crate.kind is CrateKind.SMART and not crate.is_smart_definition
+            for crate in library.crates
+        ),
+        unknown_crates=sum(
+            crate.kind is CrateKind.UNKNOWN for crate in library.crates
+        ),
+        dynamic_references_excluded=sum(
+            len(crate.references)
+            for crate in library.crates
+            if crate.kind is CrateKind.SMART
+        ),
+    )

serato_doctor/models/__init__.py

@@ -1,4 +1,7 @@
-from serato_doctor.models.crate import Crate
+from serato_doctor.models.crate import Crate, CrateKind
+from serato_doctor.models.duplicate import DuplicateGroup, DuplicateKind
+from serato_doctor.models.filesystem import BrokenSymlink, FilesystemScan
+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
@@ -6,7 +9,13 @@ from serato_doctor.models.track import DiskTrack
 
 __all__ = [
     "Crate",
+    "CrateKind",
     "DiskTrack",
+    "DuplicateGroup",
+    "DuplicateKind",
+    "BrokenSymlink",
+    "FilesystemScan",
+    "HealthReport",
     "Library",
     "MatchEvidence",
     "ReferenceResult",

serato_doctor/models/crate.py

@@ -1,13 +1,33 @@
 from dataclasses import dataclass
+from enum import Enum
 from pathlib import Path
 from typing import Tuple
 
 from serato_doctor.models.reference import TrackReference
 
 
+class CrateKind(str, Enum):
+    STATIC = "static"
+    SMART = "smart"
+    UNKNOWN = "unknown"
+
+
 @dataclass(frozen=True)
 class Crate:
     """A Serato crate and the track references parsed from it."""
 
     path: Path
     references: Tuple[TrackReference, ...]
+    kind: CrateKind = CrateKind.UNKNOWN
+
+    @property
+    def hierarchy(self) -> Tuple[str, ...]:
+        return tuple(self.path.stem.split("≫≫"))
+
+    @property
+    def display_name(self) -> str:
+        return self.hierarchy[-1]
+
+    @property
+    def is_smart_definition(self) -> bool:
+        return self.path.suffix.casefold() == ".scrate"

serato_doctor/models/duplicate.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from enum import Enum
+from typing import Tuple
+
+from serato_doctor.models.track import DiskTrack
+
+
+class DuplicateKind(str, Enum):
+    EXACT_NAME = "exact_name"
+    CLOUD_CONFLICT = "cloud_conflict"
+
+
+@dataclass(frozen=True)
+class DuplicateGroup:
+    """A deterministic group of files that warrants duplicate review."""
+
+    kind: DuplicateKind
+    comparison_key: str
+    tracks: Tuple[DiskTrack, ...]
+
+    @property
+    def extra_files(self) -> int:
+        return max(0, len(self.tracks) - 1)
+
+    @property
+    def display_name(self) -> str:
+        return min(
+            (track.filename for track in self.tracks),
+            key=lambda name: (len(name), name.casefold()),
+        )

serato_doctor/models/filesystem.py

@@ -0,0 +1,21 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Tuple
+
+from serato_doctor.models.track import DiskTrack
+
+
+@dataclass(frozen=True)
+class BrokenSymlink:
+    """A symbolic link whose target cannot be resolved."""
+
+    path: Path
+    target: Optional[Path]
+
+
+@dataclass(frozen=True)
+class FilesystemScan:
+    """Read-only findings from one traversal of a music folder."""
+
+    tracks: Tuple[DiskTrack, ...]
+    broken_symlinks: Tuple[BrokenSymlink, ...]

serato_doctor/models/health.py

@@ -0,0 +1,31 @@
+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
+    scored_references: int
+    healthy_references: int
+    missing_references: int
+    unique_missing_filenames: int
+    disk_tracks: int
+    duplicate_filename_groups: int
+    duplicate_files: int
+    suspected_cloud_conflict_groups: int
+    suspected_cloud_conflict_files: int
+    unused_tracks: int
+    suggested_matches: int
+    broken_symlinks: int
+    static_crates: int
+    smart_crates: int
+    smart_crate_containers: int
+    unknown_crates: int
+    dynamic_references_excluded: int
+
+    @property
+    def score_basis(self) -> str:
+        return "Resolved non-dynamic references / non-dynamic references scored"

serato_doctor/models/library.py

@@ -1,6 +1,8 @@
 from dataclasses import dataclass
 from typing import Iterable, Tuple
 
+from serato_doctor.models.crate import Crate
+from serato_doctor.models.filesystem import BrokenSymlink
 from serato_doctor.models.reference import ReferenceResult, TrackReference
 from serato_doctor.models.track import DiskTrack
 
@@ -11,14 +13,41 @@ class Library:
 
     references: Tuple[TrackReference, ...]
     tracks: Tuple[DiskTrack, ...]
+    crates: Tuple[Crate, ...] = ()
+    broken_symlinks: Tuple[BrokenSymlink, ...] = ()
 
     @classmethod
     def build(
         cls,
         references: Iterable[TrackReference],
         tracks: Iterable[DiskTrack],
+        broken_symlinks: Iterable[BrokenSymlink] = (),
     ) -> "Library":
-        return cls(tuple(references), tuple(tracks))
+        return cls(
+            tuple(references),
+            tuple(tracks),
+            broken_symlinks=tuple(broken_symlinks),
+        )
+
+    @classmethod
+    def from_crates(
+        cls,
+        crates: Iterable[Crate],
+        tracks: Iterable[DiskTrack],
+        broken_symlinks: Iterable[BrokenSymlink] = (),
+    ) -> "Library":
+        crate_tuple = tuple(crates)
+        references = tuple(
+            reference
+            for crate in crate_tuple
+            for reference in crate.references
+        )
+        return cls(
+            references,
+            tuple(tracks),
+            crate_tuple,
+            tuple(broken_symlinks),
+        )
 
     def reconcile_by_filename(self) -> Tuple[ReferenceResult, ...]:
         disk_names = {track.filename for track in self.tracks}

serato_doctor/scanner.py

@@ -1,14 +1,23 @@
 from pathlib import Path
 
+from serato_doctor.models.filesystem import BrokenSymlink, FilesystemScan
 from serato_doctor.models.track import DiskTrack
 
 AUDIO_SUFFIXES = {".mp3", ".m4a", ".wav", ".aif", ".aiff", ".flac"}
 
 
-def scan_audio(folder: Path) -> list[DiskTrack]:
+def scan_filesystem(folder: Path) -> FilesystemScan:
     tracks = []
+    broken_symlinks = []
 
     for path in folder.rglob("*"):
+        if path.is_symlink() and not path.exists():
+            try:
+                target = path.readlink()
+            except OSError:
+                target = None
+            broken_symlinks.append(BrokenSymlink(path=path, target=target))
+            continue
         if not path.is_file():
             continue
         if path.suffix.lower() not in AUDIO_SUFFIXES:
@@ -28,4 +37,13 @@ def scan_audio(folder: Path) -> list[DiskTrack]:
             )
         )
 
-    return tracks
+    return FilesystemScan(
+        tracks=tuple(tracks),
+        broken_symlinks=tuple(broken_symlinks),
+    )
+
+
+def scan_audio(folder: Path) -> list[DiskTrack]:
+    """Scan audio files while preserving the prototype API."""
+
+    return list(scan_filesystem(folder).tracks)

serato_doctor/web.py

@@ -0,0 +1,110 @@
+import argparse
+import json
+from dataclasses import asdict
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from importlib import resources
+from pathlib import Path
+from typing import Iterable
+
+from serato_doctor.crate_parser import load_library_crates
+from serato_doctor.health import analyze_health
+from serato_doctor.models.library import Library
+from serato_doctor.scanner import scan_filesystem
+
+
+MAX_REQUEST_BYTES = 64 * 1024
+STATIC_FILES = {
+    "/": ("index.html", "text/html; charset=utf-8"),
+    "/app.css": ("app.css", "text/css; charset=utf-8"),
+    "/app.js": ("app.js", "text/javascript; charset=utf-8"),
+}
+
+
+def analyze_paths(
+    serato: Path, music: Path, reference_roots: Iterable[Path] = ()
+) -> dict:
+    serato = serato.expanduser()
+    music = music.expanduser()
+    reference_roots = tuple(root.expanduser() for root in reference_roots)
+    if not serato.is_dir():
+        raise ValueError(f"Serato folder does not exist: {serato}")
+    if not music.is_dir():
+        raise ValueError(f"Music folder does not exist: {music}")
+
+    crates = load_library_crates(serato, reference_roots)
+    filesystem = scan_filesystem(music)
+    library = Library.from_crates(
+        crates,
+        filesystem.tracks,
+        filesystem.broken_symlinks,
+    )
+    report = analyze_health(library)
+    result = asdict(report)
+    result["score_basis"] = report.score_basis
+    return result
+
+
+class SeratoDoctorHandler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        asset = STATIC_FILES.get(self.path)
+        if asset is None:
+            self._json_response(404, {"error": "Not found"})
+            return
+        filename, content_type = asset
+        content = (
+            resources.files("serato_doctor.webui")
+            .joinpath(filename)
+            .read_bytes()
+        )
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def do_POST(self) -> None:
+        if self.path != "/api/analyze":
+            self._json_response(404, {"error": "Not found"})
+            return
+        try:
+            length = int(self.headers.get("Content-Length", "0"))
+            if length <= 0 or length > MAX_REQUEST_BYTES:
+                raise ValueError("Invalid request size")
+            payload = json.loads(self.rfile.read(length))
+            if not isinstance(payload, dict):
+                raise ValueError("Request body must be a JSON object")
+            roots = [Path(value) for value in payload.get("reference_roots", [])]
+            result = analyze_paths(
+                Path(payload["serato"]), Path(payload["music"]), roots
+            )
+        except (KeyError, TypeError, json.JSONDecodeError, ValueError) as error:
+            self._json_response(400, {"error": str(error)})
+            return
+        self._json_response(200, result)
+
+    def _json_response(self, status: int, payload: dict) -> None:
+        content = json.dumps(payload).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def log_message(self, format: str, *args: object) -> None:
+        return
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="serato-doctor-web")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args()
+    server = ThreadingHTTPServer((args.host, args.port), SeratoDoctorHandler)
+    print(f"Serato Doctor web interface: http://{args.host}:{args.port}")
+    print("Press Ctrl+C to stop.")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()

serato_doctor/webui/__init__.py

@@ -0,0 +1 @@
+"""Static assets for the local Serato Doctor web interface."""

serato_doctor/webui/app.js

@@ -0,0 +1,54 @@
+const form = document.querySelector('#analysis-form');
+const button = document.querySelector('#analyze-button');
+const errorBox = document.querySelector('#error-message');
+const results = document.querySelector('#dashboard');
+
+function expandHome(path) {
+  return path.trim();
+}
+
+function render(data) {
+  document.querySelectorAll('[data-field]').forEach((element) => {
+    const value = data[element.dataset.field];
+    element.textContent = value ?? '—';
+  });
+  const score = data.score;
+  document.querySelector('#health-score').textContent = score == null ? '—' : `${score}%`;
+  document.querySelector('#score-ring').style.setProperty('--score', score ?? 0);
+  document.querySelector('#health-message').textContent = score == null
+    ? 'Not enough data yet'
+    : score >= 95 ? 'Looking excellent' : score >= 80 ? 'A few things need attention' : 'Review recommended';
+  document.querySelector('#score-basis').textContent = data.score_basis;
+  document.querySelector('#analysis-time').textContent = `Completed ${new Date().toLocaleTimeString([], {hour: '2-digit', minute: '2-digit'})}`;
+  results.hidden = false;
+  results.scrollIntoView({behavior: 'smooth', block: 'start'});
+}
+
+form.addEventListener('submit', async (event) => {
+  event.preventDefault();
+  errorBox.hidden = true;
+  button.disabled = true;
+  button.querySelector('span').textContent = 'Analyzing safely…';
+  const roots = document.querySelector('#reference-roots').value
+    .split('\n').map((value) => value.trim()).filter(Boolean);
+  try {
+    const response = await fetch('/api/analyze', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({
+        serato: expandHome(document.querySelector('#serato-path').value),
+        music: expandHome(document.querySelector('#music-path').value),
+        reference_roots: roots,
+      }),
+    });
+    const data = await response.json();
+    if (!response.ok) throw new Error(data.error || 'Analysis failed');
+    render(data);
+  } catch (error) {
+    errorBox.textContent = error.message;
+    errorBox.hidden = false;
+  } finally {
+    button.disabled = false;
+    button.querySelector('span').textContent = 'Analyze library';
+  }
+});

serato_doctor/webui/index.html

@@ -0,0 +1,87 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="dark">
+  <title>Serato Doctor</title>
+  <link rel="stylesheet" href="/app.css">
+</head>
+<body>
+  <div class="ambient ambient-one"></div>
+  <div class="ambient ambient-two"></div>
+  <div class="shell">
+    <aside class="sidebar">
+      <a class="brand" href="/" aria-label="Serato Doctor home">
+        <span class="brand-mark">SD</span>
+        <span><strong>Serato</strong><small>Doctor</small></span>
+      </a>
+      <nav aria-label="Primary navigation">
+        <a class="nav-item active" href="#dashboard"><span>⌁</span> Dashboard</a>
+        <a class="nav-item" href="#scan"><span>◎</span> New analysis</a>
+        <a class="nav-item" href="#diagnostics"><span>◇</span> Diagnostics</a>
+      </nav>
+      <div class="safety-card">
+        <span class="safety-icon">✓</span>
+        <div><strong>Read-only mode</strong><p>Your library will not be modified.</p></div>
+      </div>
+      <div class="sidebar-foot">Local interface · v0.1</div>
+    </aside>
+
+    <main>
+      <header class="topbar">
+        <div><p class="eyebrow">Library intelligence</p><h1>Good evening.</h1></div>
+        <div class="status-pill"><span></span> Local &amp; private</div>
+      </header>
+
+      <section id="scan" class="scan-panel panel">
+        <div class="panel-copy">
+          <p class="eyebrow">Start here</p>
+          <h2>Analyze your library</h2>
+          <p>Point Serato Doctor at your Serato and music folders. We inspect references, duplicates, smart crates, and symlinks without changing a thing.</p>
+        </div>
+        <form id="analysis-form">
+          <label>Serato folder
+            <input id="serato-path" name="serato" value="~/Music/_Serato_" required>
+          </label>
+          <label>Music folder
+            <input id="music-path" name="music" value="~/Music/Jukebox" required>
+          </label>
+          <label class="wide">Historical reference roots <span>optional · one per line</span>
+            <textarea id="reference-roots" rows="2" placeholder="/Users/old-user/OneDrive/Jukebox"></textarea>
+          </label>
+          <button id="analyze-button" type="submit"><span>Analyze library</span><b>→</b></button>
+        </form>
+        <div id="error-message" class="error" role="alert" hidden></div>
+      </section>
+
+      <section id="dashboard" class="results" aria-live="polite" hidden>
+        <div class="section-heading"><div><p class="eyebrow">Latest analysis</p><h2>Library health</h2></div><span id="analysis-time"></span></div>
+        <div class="hero-grid">
+          <article class="score-card panel">
+            <div class="score-ring" id="score-ring"><div><strong id="health-score">—</strong><span>health</span></div></div>
+            <div><p class="score-label">Reference integrity</p><h3 id="health-message">Ready to analyze</h3><p id="score-basis">We only score evidence we can defend.</p></div>
+          </article>
+          <div class="metrics-grid">
+            <article class="metric panel"><span>Tracks</span><strong data-field="disk_tracks">—</strong><small>audio files found</small></article>
+            <article class="metric panel warning"><span>Broken references</span><strong data-field="missing_references">—</strong><small>static crate entries</small></article>
+            <article class="metric panel"><span>Unused tracks</span><strong data-field="unused_tracks">—</strong><small>not referenced by crates</small></article>
+            <article class="metric panel"><span>Suggested matches</span><strong data-field="suggested_matches">—</strong><small>explainable candidates</small></article>
+          </div>
+        </div>
+
+        <div id="diagnostics" class="diagnostics panel">
+          <div class="section-heading"><div><p class="eyebrow">Full picture</p><h2>Diagnostics</h2></div><span class="read-only-tag">No changes made</span></div>
+          <div class="diagnostic-list">
+            <div><span class="diag-icon violet">◇</span><p><strong>Crates</strong><small><b data-field="static_crates">—</b> static · <b data-field="smart_crates">—</b> smart · <b data-field="smart_crate_containers">—</b> dynamic containers · <b data-field="dynamic_references_excluded">—</b> references excluded</small></p></div>
+            <div><span class="diag-icon amber">≋</span><p><strong>Duplicate filenames</strong><small><b data-field="duplicate_filename_groups">—</b> exact groups · <b data-field="duplicate_files">—</b> extra files</small></p></div>
+            <div><span class="diag-icon blue">⌁</span><p><strong>Cloud conflicts</strong><small><b data-field="suspected_cloud_conflict_groups">—</b> suspected groups · <b data-field="suspected_cloud_conflict_files">—</b> extra files</small></p></div>
+            <div><span class="diag-icon red">↗</span><p><strong>Broken symlinks</strong><small><b data-field="broken_symlinks">—</b> unresolved links</small></p></div>
+          </div>
+        </div>
+      </section>
+    </main>
+  </div>
+  <script src="/app.js" defer></script>
+</body>
+</html>

tests/test_cli.py

@@ -84,3 +84,48 @@ def test_cli_accepts_old_reference_root(tmp_path, monkeypatch, capsys):
     output = capsys.readouterr().out
     assert "Crate references: 1" in output
     assert "Missing by filename: 0" in output
+
+
+def test_analyze_prints_health_without_writing_reports(tmp_path, monkeypatch, capsys):
+    serato = tmp_path / "serato"
+    subcrates = serato / "Subcrates"
+    music = tmp_path / "music"
+    subcrates.mkdir(parents=True)
+    music.mkdir()
+    crate_text = (
+        "Users/sample-user/Jukebox/Found.mp3otrk"
+        "Users/sample-user/Jukebox/Missing.mp3otrk"
+    )
+    (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",
+            "analyze",
+            "--serato",
+            str(serato),
+            "--music",
+            str(music),
+            "--out",
+            str(csv_path),
+            "--report",
+            str(report_path),
+        ],
+    )
+
+    main()
+
+    output = capsys.readouterr().out
+    assert "Overall Health: 50.0%" in output
+    assert "Tracks: 1" in output
+    assert "Crate References: 2" in output
+    assert "References Scored: 2" in output
+    assert "Healthy References: 1" in output
+    assert "Broken References: 1" in output
+    assert "Unused Tracks: 0" in output
+    assert not csv_path.exists()
+    assert not report_path.exists()

tests/test_crates.py

@@ -3,12 +3,15 @@ from pathlib import Path
 import pytest
 
 from serato_doctor.crate_parser import (
+    classify_crate,
     clean_path,
     load_crate,
+    load_library_crates,
     parse_crate,
     parse_crates,
     path_markers,
 )
+from serato_doctor.models.crate import CrateKind
 
 
 @pytest.mark.parametrize(
@@ -84,3 +87,50 @@ def test_parse_crates_reuses_configured_roots_for_every_crate(tmp_path):
         "First.mp3",
         "Second.mp3",
     }
+
+
+@pytest.mark.parametrize(
+    ("relative_path", "expected"),
+    [
+        ("_Serato_/Subcrates/House.crate", CrateKind.STATIC),
+        ("_Serato_/SmartCrates/Warmup.scrate", CrateKind.SMART),
+        ("_Serato_/Subcrates/Compatible by key.crate", CrateKind.SMART),
+        ("fixtures/Unknown.crate", CrateKind.UNKNOWN),
+    ],
+)
+def test_classify_crate_uses_provenance_and_known_dynamic_name(
+    tmp_path, relative_path, expected
+):
+    assert classify_crate(tmp_path / relative_path) is expected
+
+
+def test_smart_crate_preserves_encoded_hierarchy(tmp_path):
+    crate_path = (
+        tmp_path / "_Serato_" / "SmartCrates" / "Compatible by key≫≫10A.scrate"
+    )
+    crate_path.parent.mkdir(parents=True)
+    crate_path.write_bytes(b"")
+    crate = load_crate(crate_path)
+
+    assert crate.kind is CrateKind.SMART
+    assert crate.hierarchy == ("Compatible by key", "10A")
+    assert crate.display_name == "10A"
+    assert crate.is_smart_definition
+
+
+def test_load_library_crates_discovers_scrate_definitions(tmp_path):
+    smart_folder = tmp_path / "SmartCrates"
+    static_folder = tmp_path / "Subcrates"
+    smart_folder.mkdir()
+    static_folder.mkdir()
+    (smart_folder / "New EDM.scrate").write_bytes(b"")
+    (smart_folder / "Re-Drums.scrate").write_bytes(b"")
+    (static_folder / "House.crate").write_bytes(b"")
+
+    crates = load_library_crates(tmp_path)
+
+    assert [(crate.path.name, crate.kind) for crate in crates] == [
+        ("New EDM.scrate", CrateKind.SMART),
+        ("Re-Drums.scrate", CrateKind.SMART),
+        ("House.crate", CrateKind.STATIC),
+    ]

tests/test_duplicates.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+
+from serato_doctor.duplicates import find_duplicate_groups
+from serato_doctor.models.duplicate import DuplicateKind
+from serato_doctor.models.track import DiskTrack
+
+
+def track(path):
+    path = Path(path)
+    return DiskTrack(path, path.name, 100, path.suffix.lower())
+
+
+def test_exact_names_in_different_folders_form_a_group():
+    groups = find_duplicate_groups(
+        [track("/A/Song.mp3"), track("/B/Song.mp3")]
+    )
+
+    assert len(groups) == 1
+    assert groups[0].kind is DuplicateKind.EXACT_NAME
+    assert groups[0].display_name == "Song.mp3"
+    assert groups[0].extra_files == 1
+
+
+def test_case_only_difference_is_an_exact_name_duplicate():
+    groups = find_duplicate_groups(
+        [track("/A/SONG.MP3"), track("/B/song.mp3")]
+    )
+
+    assert groups[0].kind is DuplicateKind.EXACT_NAME
+
+
+def test_numeric_suffixes_form_a_suspected_cloud_conflict_group():
+    groups = find_duplicate_groups(
+        [
+            track("/A/Track.mp3"),
+            track("/B/Track 2.mp3"),
+            track("/C/Track 3.mp3"),
+        ]
+    )
+
+    assert len(groups) == 1
+    assert groups[0].kind is DuplicateKind.CLOUD_CONFLICT
+    assert groups[0].display_name == "Track.mp3"
+    assert groups[0].extra_files == 2
+    assert [item.path for item in groups[0].tracks] == [
+        Path("/A/Track.mp3"),
+        Path("/B/Track 2.mp3"),
+        Path("/C/Track 3.mp3"),
+    ]
+
+
+def test_unrelated_and_single_files_are_not_reported():
+    groups = find_duplicate_groups(
+        [track("/A/First.mp3"), track("/B/Second.mp3")]
+    )
+
+    assert groups == ()

tests/test_health.py

@@ -0,0 +1,121 @@
+from pathlib import Path
+
+from serato_doctor.health import analyze_health
+from serato_doctor.models.crate import Crate, CrateKind
+from serato_doctor.models.filesystem import BrokenSymlink
+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 non-dynamic references / non-dynamic references scored"
+    )
+    assert report.total_references == 3
+    assert report.scored_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
+    assert report.scored_references == 0
+
+
+def test_smart_crate_references_are_reported_but_not_scored():
+    static_reference = reference("Found.mp3")
+    smart_reference = TrackReference(
+        Path("SmartCrates/Dynamic.scrate"),
+        Path("/old/House/Dynamic.mp3"),
+        "Dynamic.mp3",
+    )
+    crates = [
+        Crate(Path("Subcrates/Static.crate"), (static_reference,), CrateKind.STATIC),
+        Crate(
+            Path("SmartCrates/Dynamic.scrate"),
+            (smart_reference,),
+            CrateKind.SMART,
+        ),
+    ]
+    library = Library.from_crates(crates, [track("Found.mp3")])
+
+    report = analyze_health(library)
+
+    assert report.score == 100.0
+    assert report.total_references == 2
+    assert report.scored_references == 1
+    assert report.missing_references == 0
+    assert report.static_crates == 1
+    assert report.smart_crates == 1
+    assert report.smart_crate_containers == 0
+    assert report.dynamic_references_excluded == 1
+
+
+def test_health_reports_cloud_conflicts_separately_from_exact_duplicates():
+    library = Library.build(
+        [],
+        [
+            track("Track.mp3", "Original"),
+            track("Track 2.mp3", "Conflict"),
+            track("Copy.mp3", "First"),
+            track("Copy.mp3", "Second"),
+        ],
+    )
+
+    report = analyze_health(library)
+
+    assert report.duplicate_filename_groups == 1
+    assert report.duplicate_files == 1
+    assert report.suspected_cloud_conflict_groups == 1
+    assert report.suspected_cloud_conflict_files == 1
+
+
+def test_health_reports_broken_symlinks_without_changing_score():
+    library = Library.build(
+        [reference("Found.mp3")],
+        [track("Found.mp3")],
+        [BrokenSymlink(Path("/music/Broken.mp3"), Path("missing.mp3"))],
+    )
+
+    report = analyze_health(library)
+
+    assert report.score == 100.0
+    assert report.broken_symlinks == 1

tests/test_sample_library.py

@@ -1,7 +1,8 @@
 import runpy
 from pathlib import Path
 
-from serato_doctor.crate_parser import parse_crates
+from serato_doctor.crate_parser import load_library_crates
+from serato_doctor.models.crate import CrateKind
 from serato_doctor.models.library import Library
 from serato_doctor.scanner import scan_audio
 
@@ -13,16 +14,21 @@ def test_generated_sample_library_has_expected_scenario(tmp_path):
     build_sample = runpy.run_path(str(generator_path))["build_sample"]
     sample_root = build_sample(tmp_path / "sample")
 
-    references = parse_crates(sample_root / "Serato" / "_Serato_" / "Subcrates")
+    crates = load_library_crates(sample_root / "Serato" / "_Serato_")
     tracks = scan_audio(sample_root / "Music")
-    results = Library.build(references, tracks).reconcile_by_filename()
+    library = Library.from_crates(crates, tracks)
+    results = library.reconcile_by_filename()
     missing = {
         result.reference.filename
         for result in results
         if not result.exists_by_filename
     }
 
-    assert len(list((sample_root / "Serato").rglob("*.crate"))) == 7
+    crate_files = list((sample_root / "Serato").rglob("*.crate"))
-    assert len(references) == 13
+    smart_files = list((sample_root / "Serato").rglob("*.scrate"))
+    assert len(crate_files) + len(smart_files) == 7
+    assert len(library.references) == 13
     assert len(tracks) == 10
     assert missing == {"Missing.mp3", "Old Name.mp3"}
+    assert sum(crate.kind is CrateKind.STATIC for crate in crates) == 5
+    assert sum(crate.kind is CrateKind.SMART for crate in crates) == 2

tests/test_scanner.py

@@ -1,4 +1,6 @@
-from serato_doctor.scanner import scan_audio
+from pathlib import Path
+
+from serato_doctor.scanner import scan_audio, scan_filesystem
 
 
 def test_scan_audio_finds_supported_files(tmp_path):
@@ -15,3 +17,34 @@ def test_scan_audio_finds_supported_files(tmp_path):
     first = next(track for track in tracks if track.filename == "First.MP3")
     assert first.suffix == ".mp3"
     assert first.size == len(b"synthetic audio")
+
+
+def test_scan_filesystem_reports_broken_symlink(tmp_path):
+    music = tmp_path / "music"
+    music.mkdir()
+    link = music / "Missing.mp3"
+    link.symlink_to("not-there.mp3")
+
+    result = scan_filesystem(music)
+
+    assert result.tracks == ()
+    assert len(result.broken_symlinks) == 1
+    assert result.broken_symlinks[0].path == link
+    assert result.broken_symlinks[0].target == Path("not-there.mp3")
+
+
+def test_valid_audio_symlink_is_scanned_normally(tmp_path):
+    music = tmp_path / "music"
+    music.mkdir()
+    target = music / "Target.mp3"
+    target.write_bytes(b"synthetic audio")
+    link = music / "Linked.mp3"
+    link.symlink_to(target)
+
+    result = scan_filesystem(music)
+
+    assert {track.filename for track in result.tracks} == {
+        "Linked.mp3",
+        "Target.mp3",
+    }
+    assert result.broken_symlinks == ()

tests/test_web.py

@@ -0,0 +1,35 @@
+import runpy
+from pathlib import Path
+
+import pytest
+
+from serato_doctor.web import STATIC_FILES, analyze_paths
+
+
+def test_web_analysis_uses_production_health_pipeline(tmp_path):
+    generator = runpy.run_path(
+        str(Path(__file__).parents[1] / "samples/small-library/generate.py")
+    )
+    sample = generator["build_sample"](tmp_path / "sample")
+
+    result = analyze_paths(
+        sample / "Serato" / "_Serato_", sample / "Music"
+    )
+
+    assert result["score"] == 77.8
+    assert result["disk_tracks"] == 10
+    assert result["missing_references"] == 2
+    assert result["static_crates"] == 5
+    assert result["smart_crates"] == 2
+
+
+def test_web_analysis_rejects_missing_folders(tmp_path):
+    with pytest.raises(ValueError, match="Serato folder does not exist"):
+        analyze_paths(tmp_path / "missing", tmp_path)
+
+
+def test_web_static_assets_are_declared_and_packaged():
+    asset_root = Path(__file__).parents[1] / "serato_doctor" / "webui"
+
+    assert set(STATIC_FILES) == {"/", "/app.css", "/app.js"}
+    assert all((asset_root / filename).is_file() for filename, _ in STATIC_FILES.values())