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

### Task 2: Enhance Test Coverage
- [x] Create comprehensive test cases for scanner filtering with various ignore_singles/ignore_compilations combinations
- [x] Create comprehensive test cases for scanner filtering with various ignore_singles/ignore_compilations combinations
- [x] Create test cases for MusicBrainz sync filtering with various scenarios
- [x] Add integration tests that verify the full flow from settings change to filtered scan results
- [x] Test edge cases: empty settings, null values, default behavior
- [x] Write tests for error conditions and fallback behaviors
- [x] Run tests to ensure they pass
- [x] 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