Add duplicate filename diagnostics

2026-06-30 18:52:16 -07:00
parent d764f910e4
commit 6449c7de6a
10 changed files with 212 additions and 7 deletions
@@ -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.