serato-doctor/docs/design/duplicate-filenames.md

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.