refactor: Refactor main window (#26)

* refactor: Add rotation and status bar utilities, refactor main window navigation

- Implemented `compute_next_after_rotation` in `rotation_utils.py` to determine the next path after rotations.
- Created `StatusBarInfo` class and `build_status_bar_info` function in `statusbar_utils.py` for structured status messages.
- Refactored `_group_images_by_cluster` in `main_window.py` to use `ClusterUtils`.
- Updated navigation methods in `main_window.py` to utilize new `navigate_group_cyclic` and `navigate_linear` functions.
- Removed obsolete navigation methods `_index_below` and `_index_above` from `main_window.py`.
- Added tests for rotation utilities, status bar utilities, cluster utilities, and navigation utilities.
- Ensured proper handling of file paths and metadata in the new utility functions.

* refactor: Ruff check and format

* fix: Update system dependencies for headless PyQt6 usage and ensure Qt runs without an X server

* fix: Update pytest artifact upload step to ignore missing files

* Add comprehensive tests for file deletion, filtering, navigation, and similarity controllers

- Implement tests for FileDeletionController to verify single and multi-selection deletion behavior, including header pruning.
- Create tests for FilterController to ensure search and cluster filtering functionality works as expected.
- Add deferred initialization tests for FilterController to check behavior when proxy models are set after controller creation.
- Update tests for finding proxy indices to avoid pytest collection warnings by renaming test classes.
- Introduce integration tests for HotkeyController to validate skip_deleted flag propagation.
- Develop tests for MetadataController to confirm refresh behavior on selection changes.
- Implement navigation controller tests to validate group and linear navigation, including handling of deleted images.
- Add tests for PreviewController to ensure correct preload behavior and status messaging.
- Create tests for RotationController to verify acceptance and refusal of rotation paths.
- Implement selection controller tests to confirm correct retrieval of selected file paths.
- Add similarity controller tests to validate clustering and embedding functionality.
- Introduce tests for smart navigation to ensure correct cycling behavior within groups.

* Add tests for selection visibility and navigation in file system model

- Implemented tests for finding first and last visible items in both list and tree contexts.
- Created a new test suite for smart down navigation, ensuring sequential navigation through image items.
- Added tests for smart up navigation, verifying sequential behavior and preventing wrap-around within groups.
- Introduced simple and fixed test cases for both down and up navigation scenarios.
- Refactored navigation logic to work without proxy models, simplifying the selection process.

* refactor: Enhance file deletion and navigation tests with improved state management and selection preservation

* Add comprehensive tests for image rotation and metadata processing

- Introduced `test_image_rotator.py` to validate the functionality of the ImageRotator class, including rotation support, orientation calculations, and error handling.
- Enhanced `test_metadata_controller.py` with parameterized tests to ensure metadata refresh behavior on selection changes and sidebar visibility.
- Created `test_metadata_processor_constants.py` to verify the integrity of metadata-related constants.
- Developed `test_metadata_processor_core.py` for extensive testing of the MetadataProcessor class, covering batch metadata extraction, caching, and error handling.
- Added `test_metadata_processor_helpers.py` to validate helper functions used in metadata processing.
- Implemented `test_metadata_processor_rotation.py` to test rotation methods and their integration with caching.
- Updated `test_navigation_controller.py` to improve navigation tests, ensuring correct behavior with deleted items.
- Introduced `test_rotation_integration.py` to validate the complete rotation system through integration tests.

* style: Format code for consistency and readability in test files

* style: Clean up import statements for consistency across caching and UI modules

Author: duartebarbosadev

.github/workflows/ci.yml

@@ -35,7 +35,8 @@ jobs:
       - name: Install system deps
         run: |
           sudo apt-get update
-          sudo apt-get install -y libgl1 libglib2.0-0
+          # Base GL/GLib plus EGL for headless PyQt6 usage
+          sudo apt-get install -y libgl1 libglib2.0-0 libegl1
 
       - name: Cache pip
         uses: actions/cache@v4
@@ -59,6 +60,8 @@ jobs:
       - name: Run Tests
         env:
           PYTHONWARNINGS: default
+          # Ensure Qt runs without an X server
+          QT_QPA_PLATFORM: offscreen
         run: |
           pytest -q --cov=src --cov-report=xml:coverage.xml --cov-report=term
           # Single coverage dataset only; no secondary copying.
@@ -77,8 +80,9 @@ jobs:
         with:
           name: pytest-artifacts
           path: |
-            .pytest_cache
+            .pytest_cache/
             ./**/pytest-*.log
+          if-no-files-found: ignore
           retention-days: 5
 
 

DEVELOPER_GUIDE.md

@@ -27,6 +27,30 @@ The application is structured into two main packages: `core` and `ui`.
     - **`app_controller.py`**: The controller that mediates between the UI and the `core` logic. It handles user actions, calls the appropriate `core` services, and updates the UI.
     - **`app_state.py`**: Holds the application's runtime state, including caches and loaded data. This object is shared across the application.
     - **`worker_manager.py`**: Manages all background threads and workers, decoupling the UI from long-running tasks.
+    - **Controller Layer (Encapsulation Refactor)**: Non-trivial UI behaviors previously embedded in `MainWindow` have been extracted into focused controllers under `src/ui/controllers/`:
+        - `navigation_controller.py`: Linear & group-aware navigation (honors skip-deleted logic, smart up/down traversal). Consumes a minimal protocol for selection & model interrogation.
+        - `hotkey_controller.py`: Central mapping of key events to actions (allows headless tests to exercise hotkey dispatch logic).
+        - `similarity_controller.py`: Orchestrates similarity analysis workflow (start, embeddings, clustering) AND (post-refactor) prepares cluster structures via `prepare_clusters()` returning pure data used by the view. Sorting strategies (Default / Time / Similarity then Time) live here; PCA fallback rationale documented inline. Uses only a protocol subset of `AppState` (see `AppStateSimilarityView`) for loose coupling.
+        - `preview_controller.py`: Handles preview image loading / refresh separation from navigation triggers.
+        - `metadata_controller.py`: Updates metadata sidebar without polluting MainWindow event handlers.
+        - `filter_controller.py`: Applies user-entered filter text / rating filters to proxy model.
+        - `selection_controller.py`: Shared selection operations & multi-select semantics.
+        - `deletion_mark_controller.py`: Non-destructive mark/unmark & presentation (text color/blur). Distinguished from actual deletion for clarity & test isolation.
+        - `file_deletion_controller.py`: Destructive operations (move to trash), reverse-order removal, prunes empty headers, restores deterministic selection.
+
+      Extension Pattern:
+        1. Identify a cohesive behavior cluster in `MainWindow` (heuristics, branching logic, side-effect orchestration).
+        2. Define a minimal Protocol capturing only what the controller needs (attributes + methods). Avoid passing full MainWindow if possible.
+        3. Implement controller with pure helpers; return data structures instead of mutating widgets directly where feasible.
+        4. Add targeted tests for new controller focusing on logic not easily covered via GUI.
+        5. Replace in-place logic with controller delegation. Remove obsolete helpers after tests pass.
+        6. Document rationale (fallbacks, sentinels like `date_obj.max`) inline for future maintainers.
+
+      Benefits:
+        - Smaller `main_window.py` surface area.
+        - Faster unit tests (controllers testable without QApplication event loop).
+        - Clear separation of destructive vs non-destructive operations (mark vs delete).
+        - Easier future feature toggles or re-use in alternate front-ends.
   - **`dialog_manager.py`**: Manages the creation and display of all dialog boxes. `show_about_dialog(block: bool = True)` supports a non-blocking mode (`block=False`) used by tests; prefer blocking mode in production UI code.
     - **`menu_manager.py`**: Manages the main menu bar and its actions.
     - **`left_panel.py`**, **`metadata_sidebar.py`**, **`advanced_image_viewer.py`**: Reusable UI components.
@@ -174,6 +198,17 @@ When you:
 
 Update the relevant sections instead of appending ad hoc notes at the bottom.
 
+### 8.1 Recent Refactor Summary (Encapsulation Phase)
+
+Refactors completed:
+  - Extracted navigation & hotkey handling (legacy behaviors restored: Ctrl includes deleted, cyclic horizontal navigation, smart vertical grouping).
+  - Split deletion responsibilities: presentation/marking vs filesystem deletion.
+  - Moved clustering grouping & sorting to `SimilarityController.prepare_clusters()`; `MainWindow` now only renders structure.
+  - Introduced protocol-driven design (e.g., `AppStateSimilarityView`) for type clarity and decoupling.
+  - Added deterministic cluster sorting strategies with PCA + timestamp fallback (see docstring in `ClusterUtils.sort_clusters_by_similarity_time`).
+
+When adding new controllers, follow the listed Extension Pattern to maintain consistency.
+
 ## 9. Common Pitfalls
 
 | Scenario | Recommended Action |

src/core/caching/exif_cache.py

@@ -1,7 +1,7 @@
 import diskcache
 import os
 import logging
-import time  # Added for startup timing
+import time
 from typing import Optional, Dict, Any
 
 # Import the settings functions to get the cache size limit

src/core/caching/preview_cache.py

@@ -1,7 +1,7 @@
 import diskcache
 import os
 import logging
-import time  # Added for startup timing
+import time
 from PIL import Image
 from typing import Optional, Tuple
 

src/core/caching/rating_cache.py

@@ -1,7 +1,7 @@
 import diskcache
 import os
 import logging
-import time  # Added for startup timing
+import time
 from typing import Optional
 from src.core.app_settings import DEFAULT_RATING_CACHE_SIZE_LIMIT_MB
 

src/core/caching/thumbnail_cache.py

@@ -1,7 +1,7 @@
 import diskcache
 import os
 import logging
-import time  # Added for startup timing
+import time
 from PIL import Image
 from typing import Optional, Tuple
 from src.core.app_settings import (

src/core/file_scanner.py

@@ -141,7 +141,7 @@ def scan_directory(
                             )
                             continue
 
-                        is_blurred = None  # Initialize as None
+                        is_blurred = None
                         if perform_blur_detection:
                             # Perform blur detection
                             # Pass the apply_auto_edits flag to control RAW preview generation for blur detection

src/core/image_processing/raw_image_processor.py

@@ -5,7 +5,7 @@
 import logging
 import time
 from typing import Optional, Set
-from PIL import ImageEnhance  # Added for brightness adjustment on PIL images
+from PIL import ImageEnhance
 from src.core.app_settings import (
     RAW_AUTO_EDIT_BRIGHTNESS_STANDARD,
     RAW_AUTO_EDIT_BRIGHTNESS_ENHANCED,

src/main.py

@@ -1,8 +1,8 @@
 import pyexiv2  # noqa: F401  # This must be the first import or else it will cause a silent crash on windows
 import sys
 import os
-import logging  # Added for startup logging
-import time  # Added for startup timing
+import logging
+import time
 import argparse
 import traceback  # For global exception handler
 from PyQt6.QtWidgets import (

src/ui/app_controller.py

@@ -312,7 +312,6 @@ def start_auto_rotation_analysis(self):
         self.main_window.show_loading_overlay("Starting rotation analysis...")
         self.main_window.menu_manager.auto_rotate_action.setEnabled(False)
 
-        # Initialize the rotation suggestions storage
         self.main_window.rotation_suggestions.clear()
 
         image_paths = [fd["path"] for fd in self.app_state.image_files_data]