NaviWatcher/docs/plans/2026-07-27-verify-scanner-wiring.md

Verify and Document Scanner Wiring Implementation

Overview

Verify that the scanner engine properly wires the ignore_singles and ignore_compilations toggles from artist_settings through both the MusicBrainz sync path and the scanner path. Ensure proper test coverage and document the data flow for clarity.

Context (from discovery)

• Files/components involved:
  • cmd/naviwatcher/main.go (syncAndScan function)
  • internal/scanner/scan.go (ScanArtist, ScanAll functions)
  • internal/musicbrainz/sync.go (SyncArtistDiscography function)
  • internal/musicbrainz/filter.go (ApplyTypeToggles functions)
  • internal/database/artist_settings.go (GetArtistSettings, GetAllArtistSettings functions)
• Related patterns found: Filter centralization pattern mentioned in CLAUDE.md
• Dependencies identified: database package for artist settings access

Development Approach

• Testing approach: TDD (tests first)
• Complete each task fully before moving to the next
• Make small, focused changes
• CRITICAL: every task MUST include new/updated tests for code changes in that task
  • tests are not optional - they are a required part of the checklist
  • write unit tests for new functions/methods
  • write unit tests for modified functions/methods
  • add new test cases for new code paths
  • update existing test cases if behavior changes
  • tests cover both success and error scenarios
• CRITICAL: all tests must pass before starting next task - no exceptions
• CRITICAL: update this plan file when scope changes during implementation
• Run tests after each change
• Maintain backward compatibility

Solution Overview

The implementation flow is:

1. navidrome.SyncArtists populates artist_settings table
2. musicbrainz.SyncAll calls SyncArtistDiscography which:
   • Retrieves artist settings via getArtistFilterOptions
   • Applies ignore_singles/ignore_compilations filters via ApplyTypeToggles
   • Stores filtered results in external_releases table
3. scanner.ScanAll iterates artists and calls ScanArtist which:
   • Retrieves current artist settings via GetArtistSettings
   • Applies ignore_singles/ignore_compilations filters via TypeFilter
   • Compares local albums vs filtered external releases

This creates two filtering points:

• Storage-level filtering during MusicBrainz sync (optimizes storage)
• Runtime filtering during scanning (ensures real-time responsiveness to setting changes)

Technical Details

• Data flow: Navidrome artist sync → MusicBrainz discography sync (with filtering) → Navidrome album sync → Scanner (with filtering)
• Key functions:
  • GetArtistSettings/GetAllArtistSettings (database layer)
  • getArtistFilterOptions/ApplyTypeToggles (musicbrainz filtering)
  • ScanArtist/ScanAll with TypeFilter (scanner filtering)
• Data structures: ArtistSettings, TypeFilter, ExternalRelease, LocalAlbum, MissingRelease

What Goes Where

• Implementation Steps ([ ] checkboxes): tasks achievable within this codebase - code changes, tests, documentation updates
• Post-Completion (no checkboxes): items requiring external action - manual testing, changes in consuming projects, deployment configs, third-party verifications

Implementation Steps

Task 1: Verify Current Implementation

• Review cmd/naviwatcher/main.go syncAndScan function to confirm full pipeline execution
• Review internal/scanner/scan.go ScanArtist function for proper settings retrieval and filtering
• Review internal/scanner/scan.go ScanAll function for proper iteration and filtering application
• Review internal/musicbrainz/sync.go SyncArtistDiscography for proper settings retrieval and filtering
• Review internal/musicbrainz/filter.go ApplyTypeToggles functions for correct filtering logic
• Review internal/database/artist_settings.go for proper settings retrieval functions
• Write unit tests to verify the filtering logic works correctly in both paths
• Run existing test suite to ensure no regressions
• Must pass before next task

Task 2: Enhance Test Coverage

• Create comprehensive test cases for scanner filtering with various ignore_singles/ignore_compilations combinations
• Create comprehensive test cases for scanner filtering with various ignore_singles/ignore_compilations combinations
• Create test cases for MusicBrainz sync filtering with various scenarios
• Add integration tests that verify the full flow from settings change to filtered scan results
• Test edge cases: empty settings, null values, default behavior
• Write tests for error conditions and fallback behaviors
• Run tests to ensure they pass
• Must pass before next task

Task 3: Document the Data Flow

• Update documentation to clearly explain how ignore_singles/ignore_compilations settings propagate through the system
• Add comments to key functions explaining the filtering flow
• Ensure CLAUDE.md accurately reflects the current implementation
• Create diagrams or flowcharts if helpful for understanding
• Must pass before next task

Task 4: Final Verification

• Run full test suite to ensure all changes work correctly
• Verify no breaking changes were introduced
• Confirm that the implementation handles the use case described in the memory file
• Update this plan with completion status

Post-Completion

Items requiring manual intervention or external systems - no checkboxes, informational only

Manual verification:

• Manual testing of the end-to-end flow with toggles enabled/disabled
• Verification that changes to ignore_singles/ignore_compilations take effect in a timely manner
• Performance testing to ensure filtering doesn't introduce significant overhead

External system updates:

• None required for this verification task