serato-doctor/docs/design/analyze-command.md

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.