feat: Hierarchy-Aware Categorization

[gilmanb1]

Summary

This PR implements Hierarchy-Aware Categorization as specified in HIERARCHY_AWARE_CATEGORIZATION.md.

Key Changes

Phase 1: Data Models & Scanning

• Add ScannedFolder struct for folders that move as complete units
• Add ScanUnit enum for unified folder/file handling
• Add HierarchyScanResult with folders and loose files separated
• Add scanWithHierarchy() method to FilenameScanner
• Add configuration: respectHierarchy, minDepthForFolder, minFilesForFolder

Phase 2: Folder Categorization

• Add FolderCategorizer actor with LLM-based categorization
• Add FolderCategoryAssignment struct with confidence and alternatives
• Add quickCategorize() for rule-based fallback (no LLM needed)

Phase 3: Organization Planning & Execution

• Add FolderOrganizationOperation for moving folders as units
• Add HierarchyAwareOrganizationPlan separating folder and file operations
• Add planHierarchyOrganization() in OrganizationEngine
• Add moveFolder() and moveFolders() in SafeFileOrganizer

Phase 4: Configuration

• Add hierarchy settings to OrganizationConfiguration
• New settings: respectHierarchy, minFilesForFolder, allowUserFlatten, folderReviewThreshold

Phase 5: UI Preview

• Add OrganizationPreviewView showing folder units and loose files
• Add FolderPreviewRow with confidence indicators and actions
• Add CategoryPickerSheet for reassigning folder categories

Phase 6: Tests

• 15 hierarchy-related tests, all passing

Files Changed

• Sources/SortAI/Core/Taxonomy/FilenameScanner.swift - Hierarchy scanning
• Sources/SortAI/Core/Taxonomy/FolderCategorizer.swift - New file
• Sources/SortAI/Core/Organizer/OrganizationEngine.swift - Hierarchy planning
• Sources/SortAI/Core/Organizer/SafeFileOrganizer.swift - Folder moves
• Sources/SortAI/Core/Configuration/AppConfiguration.swift - Settings
• Sources/SortAI/App/OrganizationPreviewView.swift - New file
• Tests/SortAITests/TaxonomyTests.swift - Hierarchy tests
• Tests/SortAITests/OrganizationTests.swift - Integration tests

Testing

swift test --filter "Hierarchy"  # 15 tests pass

[claude]

Claude finished @gilmanb1's task —— View job

---

Code Review: Hierarchy-Aware Categorization

Review Progress

• Read repository guidelines (CLAUDE.md)
• Review core data models and scanning logic
• Review folder categorization implementation
• Review organization planning and execution
• Review configuration changes
• Review UI preview implementation
• Review test coverage and quality
• Check Swift 6 concurrency patterns
• Check memory safety and actor isolation
• Provide final recommendation

Code Review Analysis

This PR implements Hierarchy-Aware Categorization across 8 files with ~2,700 lines of code. Here's my detailed analysis:

🟢 Strengths

Swift 6 Concurrency Excellence

• Perfect actor usage for FilenameScanner and FolderCategorizer
• All data models properly marked Sendable
• Clean async/await patterns without data races
• Proper actor isolation maintained throughout

Architecture & Design

• Excellent separation of concerns: scanning → categorization → planning → execution
• Protocol-oriented design maintains consistency with existing codebase
• Comprehensive error handling with custom error types
• Clean hierarchical configuration system

Memory Safety

• No retain cycles detected - all actors properly isolated
• Resource management handled correctly with FileManager operations
• Proper cleanup patterns in enumeration loops

Test Coverage

• 15 comprehensive hierarchy tests covering all major functionality
• Good edge case coverage (empty folders, threshold behaviors)
• Integration tests verify end-to-end workflows

🟡 Minor Observations

FilenameScanner.swift:412 - Safe force unwrap

if latestModification == nil || modDate > latestModification! {

While safe due to nil check, could use optional binding for Swift 6 best practices.

FolderCategorizer.swift:95-98 - Clean JSON parsing
Well-structured LLM response parsing with proper error handling.

OrganizationEngine.swift - Excellent hierarchy planning logic
The dual-path planning (folders vs files) is well-architected and maintains data integrity.

🔵 Implementation Quality

Configuration Integration: Perfect integration with existing AppConfiguration system

• respectHierarchy, minFilesForFolder properly added
• Backward compatibility maintained with .flat configuration

UI Architecture: OrganizationPreviewView follows SwiftUI best practices

• Proper state management with @State
• Clean separation of concerns with callback patterns
• Sheet-based navigation for category reassignment

LLM Integration: FolderCategorizer properly integrates with existing LLM infrastructure

• Reuses existing LLMProvider protocol
• Proper JSON parsing with fallback mechanisms
• Batch processing with progress callbacks

🟢 Custom SQLite Compatibility

• No direct SQLite usage in new code ✅
• Maintains compatibility with existing GRDB patterns
• Custom build flags preserved

🟢 Error Handling

• Comprehensive custom error types (ScanError, FolderCategorizationError)
• Proper fallback mechanisms for LLM failures
• Graceful degradation when files can't be categorized

Final Assessment

This is exceptionally well-crafted code that:

• Follows Swift 6 concurrency patterns perfectly
• Maintains architectural consistency with the existing codebase
• Includes comprehensive test coverage
• Implements complex functionality with clean, readable code
• Properly handles edge cases and error conditions

The implementation demonstrates deep understanding of the SortAI architecture and Swift 6 best practices.

✅ APPROVE - Ready to merge

This PR represents high-quality Swift development with excellent attention to concurrency, architecture, and testing. The hierarchy-aware categorization is a significant feature addition that's been implemented thoughtfully and thoroughly.

---