serato-doctor/docs/design/logging.md

Application Logging

Problem

The CLI reports final counts but provides no diagnostic trail when a scan behaves unexpectedly. Troubleshooting should not require adding print statements or expose library contents by default.

Architecture

The project uses an isolated standard-library logger. It has no visible output by default. --verbose writes progress to standard error, while --log-file PATH writes an informational audit trail. Normal result lines remain on standard output.

Edge Cases

• Reconfiguring logging in the same process must not duplicate handlers.
• Console and file logging may be enabled together.
• Log messages contain aggregate counts, not track names or crate contents.
• A default scan must remain quiet except for its established result output.

Verification

Tests verify quiet defaults, file output, handler replacement, and unchanged CLI result lines. The full sample-library scan remains read-only.