serato-doctor/docs/design/configuration.md

Scan Configuration

Problem

The prototype recognized crate paths by matching one developer's historical OneDrive path. That made otherwise valid libraries invisible to the parser.

Architecture

ScanConfig owns the paths for a read-only scan. The CLI accepts repeatable --reference-root options for roots embedded in crates before a migration. The parser uses those roots as record boundaries. Without explicit roots, it recognizes generic macOS home and mounted-volume paths without embedding a username.

Edge Cases

• A library may have references from more than one historical root.
• Root paths may contain spaces or have leading/trailing separators.
• Existing /Users/... and /Volumes/... crates must work without new flags.
• A record without a recognized terminator remains ignored.

Verification

Tests cover default root discovery, a custom migrated root, the CLI option, and the existing synthetic sample library. The scanner remains read-only.