Clarify diagnostic language and explanations

docs/design/plain-language-diagnostics.md

@@ -0,0 +1,25 @@
+# Plain-language Diagnostics
+
+## Problem
+
+“Broken references” combined crate occurrences with Serato's own missing-track
+concept. DJs naturally compared that number with orange/unmapped tracks in Serato,
+even though the two counts describe different layers.
+
+## Language
+
+- **Missing tracks in Serato** means database entries whose saved file location no
+  longer exists. This corresponds most closely to orange or unmapped tracks.
+- **Old crate references** means saved appearances in regular crates whose exact
+  filename was not found in the selected music folder. One track can appear in
+  several crates, so both appearances and unique filenames are shown.
+
+Every health card and diagnostic row has an accessible information button. Hover
+shows its explanation on desktop; click or tap keeps it open; Escape or clicking
+elsewhere closes it. Explanations describe uncertainty and avoid implying repair.
+
+## Verification
+
+Health tests verify database missing-path and unique-filename counts. Browser tests
+cover the two separate metrics, hover/click explanations, keyboard dismissal, and
+mobile layout.

samples/small-library/generate.py

@@ -60,7 +60,7 @@ def build_sample(output: Optional[Path] = None) -> Path:
     ]
     for relative_path in manifest["tracks"]:
         fields = database_record(
-            b"pfil", f"{SERATO_PATH_PREFIX}{relative_path}".encode("utf-16-be")
+            b"pfil", str(music_root / relative_path).encode("utf-16-be")
         )
         database_records.append(database_record(b"otrk", fields))
     (serato_root / "database V2").write_bytes(b"".join(database_records))

serato_doctor/cli.py

@@ -106,6 +106,11 @@ def main():
         print(f"Database Entries: {health.database_entries}")
         print(f"Database / Library Matches: {health.database_library_matches}")
         print(f"Database Entries Outside Scan: {health.database_unmatched_entries}")
+        print(f"Missing Tracks in Serato: {health.database_missing_paths}")
+        print(
+            "Unique Missing Tracks in Serato: "
+            f"{health.database_missing_unique_filenames}"
+        )
         print(f"Tracks Missing From Database: {health.tracks_missing_from_database}")
         print(f"Duplicate Database Paths: {health.duplicate_database_paths}")
     else:

serato_doctor/health.py

@@ -52,6 +52,9 @@ def analyze_health(library: Library) -> HealthReport:
     database_path_counts = Counter(
         normalize(str(track.path)) for track in database_tracks
     )
+    missing_database_tracks = [
+        track for track in database_tracks if not track.path.exists()
+    ]
 
     return HealthReport(
         score=score,
@@ -99,9 +102,13 @@ def analyze_health(library: Library) -> HealthReport:
         database_unmatched_entries=sum(
             normalize(track.filename) not in library_names for track in database_tracks
         ),
+        database_missing_paths=len(missing_database_tracks),
+        database_missing_unique_filenames=len(
+            {normalize(track.filename) for track in missing_database_tracks}
+        ),
         tracks_missing_from_database=sum(
             normalize(track.filename) not in database_names for track in library.tracks
-        ),
+        ) if library.database else 0,
         duplicate_database_paths=sum(
             count - 1 for count in database_path_counts.values() if count > 1
         ),

serato_doctor/models/health.py

@@ -29,6 +29,8 @@ class HealthReport:
     database_entries: int
     database_library_matches: int
     database_unmatched_entries: int
+    database_missing_paths: int
+    database_missing_unique_filenames: int
     tracks_missing_from_database: int
     duplicate_database_paths: int
 

serato_doctor/webui/app.js

@@ -2,6 +2,7 @@ const form = document.querySelector('#analysis-form');
 const button = document.querySelector('#analyze-button');
 const errorBox = document.querySelector('#error-message');
 const results = document.querySelector('#dashboard');
+const infoButtons = document.querySelectorAll('.info-button');
 
 function expandHome(path) {
   return path.trim();
@@ -24,6 +25,30 @@ function render(data) {
   results.scrollIntoView({behavior: 'smooth', block: 'start'});
 }
 
+function closeInfoButtons(except = null) {
+  infoButtons.forEach((infoButton) => {
+    if (infoButton !== except) {
+      infoButton.classList.remove('open');
+      infoButton.setAttribute('aria-expanded', 'false');
+    }
+  });
+}
+
+infoButtons.forEach((infoButton) => {
+  infoButton.addEventListener('click', (event) => {
+    event.stopPropagation();
+    const willOpen = !infoButton.classList.contains('open');
+    closeInfoButtons(infoButton);
+    infoButton.classList.toggle('open', willOpen);
+    infoButton.setAttribute('aria-expanded', String(willOpen));
+  });
+});
+
+document.addEventListener('click', () => closeInfoButtons());
+document.addEventListener('keydown', (event) => {
+  if (event.key === 'Escape') closeInfoButtons();
+});
+
 form.addEventListener('submit', async (event) => {
   event.preventDefault();
   errorBox.hidden = true;

serato_doctor/webui/index.html

@@ -59,26 +59,27 @@
         <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">
+            <button class="info-button" type="button" aria-label="About library health" aria-expanded="false" data-info="Your health score is the percentage of saved, non-smart crate entries whose filenames were found in the selected music folder. Smart crates are left out because Serato rebuilds them from rules.">i</button>
             <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>
+            <article class="metric panel"><button class="info-button" type="button" aria-label="About tracks" aria-expanded="false" data-info="Audio files found inside the music folder you selected. This is the collection Serato Doctor compared with your crates and database.">i</button><span>Tracks scanned</span><strong data-field="disk_tracks">—</strong><small>audio files found</small></article>
+            <article class="metric panel warning"><button class="info-button" type="button" aria-label="About missing tracks in Serato" aria-expanded="false" data-info="Tracks in Serato's database whose saved file location no longer exists. This should be close to the orange or unmapped track count you see in Serato.">i</button><span>Missing tracks in Serato</span><strong data-field="database_missing_paths">—</strong><small><b data-field="database_missing_unique_filenames">—</b> unique filenames</small></article>
+            <article class="metric panel"><button class="info-button" type="button" aria-label="About unused tracks" aria-expanded="false" data-info="Files in the selected music folder whose filename is not used by any loaded crate. They may still be valid library tracks; this is informational, not a deletion recommendation.">i</button><span>Unused tracks</span><strong data-field="unused_tracks">—</strong><small>not referenced by crates</small></article>
+            <article class="metric panel"><button class="info-button" type="button" aria-label="About suggested matches" aria-expanded="false" data-info="Missing crate entries with a filename-related candidate, such as an added OneDrive conflict number. Suggestions are evidence for review, never automatic repairs.">i</button><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><span class="diag-icon violet">▦</span><p><strong>Serato database V2</strong><small><b data-field="database_entries">—</b> entries · <b data-field="database_library_matches">—</b> match scanned filenames · <b data-field="tracks_missing_from_database">—</b> scanned tracks absent</small></p></div>
-            <div><span class="diag-icon amber">⌕</span><p><strong>Database review</strong><small><b data-field="database_unmatched_entries">—</b> entries outside this music scan · <b data-field="duplicate_database_paths">—</b> duplicate paths</small></p></div>
+            <div><span class="diag-icon violet">◇</span><p><strong>Crates</strong><small><b data-field="static_crates">—</b> regular · <b data-field="smart_crates">—</b> smart · <b data-field="smart_crate_containers">—</b> dynamic containers</small></p><button class="info-button" type="button" aria-label="About crates" aria-expanded="false" data-info="Regular crates are lists you maintain by hand. Smart crates are rebuilt by Serato from rules, so their generated references are not scored as broken.">i</button></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><button class="info-button" type="button" aria-label="About duplicate filenames" aria-expanded="false" data-info="Different files with the same filename after case and Unicode cleanup. They need review, but matching names alone do not mean either file should be deleted.">i</button></div>
+            <div><span class="diag-icon blue">⌁</span><p><strong>Possible cloud conflicts</strong><small><b data-field="suspected_cloud_conflict_groups">—</b> groups · <b data-field="suspected_cloud_conflict_files">—</b> extra files</small></p><button class="info-button" type="button" aria-label="About cloud conflicts" aria-expanded="false" data-info="Filename families such as Track.mp3 and Track 2.mp3. OneDrive often creates these during sync conflicts, but numbered song titles can also be legitimate.">i</button></div>
+            <div><span class="diag-icon red">↗</span><p><strong>Broken shortcuts</strong><small><b data-field="broken_symlinks">—</b> unresolved symbolic links</small></p><button class="info-button" type="button" aria-label="About broken shortcuts" aria-expanded="false" data-info="Shortcut-style symbolic links whose destination no longer exists. Serato Doctor reports them but never removes or recreates them automatically.">i</button></div>
+            <div><span class="diag-icon violet">▦</span><p><strong>Old crate references</strong><small><b data-field="missing_references">—</b> appearances · <b data-field="unique_missing_filenames">—</b> unique filenames</small></p><button class="info-button" type="button" aria-label="About old crate references" aria-expanded="false" data-info="Saved spots in regular crates whose exact filename was not found in the selected music folder. The same track can appear in several crates, so appearances are higher than unique filenames. These are separate from Serato's unmapped-track count.">i</button></div>
+            <div><span class="diag-icon amber">⌕</span><p><strong>Database coverage</strong><small><b data-field="database_entries">—</b> Serato entries · <b data-field="tracks_missing_from_database">—</b> scanned tracks absent</small></p><button class="info-button" type="button" aria-label="About database coverage" aria-expanded="false" data-info="Compares filenames in Serato's database with the selected music folder. A scanned track absent from the database may not have been imported, or may be represented under another filename.">i</button></div>
           </div>
         </div>
       </section>

tests/test_health.py

@@ -58,6 +58,8 @@ def test_empty_library_has_no_health_score():
     assert report.score is None
     assert report.total_references == 0
     assert report.scored_references == 0
+    assert not report.database_present
+    assert report.tracks_missing_from_database == 0
 
 
 def test_smart_crate_references_are_reported_but_not_scored():

tests/test_web.py

@@ -23,6 +23,8 @@ def test_web_analysis_uses_production_health_pipeline(tmp_path):
     assert result["smart_crates"] == 2
     assert result["database_entries"] == 10
     assert result["database_library_matches"] == 10
+    assert result["database_missing_paths"] == 0
+    assert result["database_missing_unique_filenames"] == 0
     assert result["tracks_missing_from_database"] == 0
 
 
@@ -36,3 +38,7 @@ def test_web_static_assets_are_declared_and_packaged():
 
     assert set(STATIC_FILES) == {"/", "/app.css", "/app.js"}
     assert all((asset_root / filename).is_file() for filename, _ in STATIC_FILES.values())
+    html = (asset_root / "index.html").read_text(encoding="utf-8")
+    assert "Missing tracks in Serato" in html
+    assert "Old crate references" in html
+    assert html.count('class="info-button"') >= 10