renamer/REFACTORING_PROGRESS.md

Renamer - Refactoring Roadmap

Version: 0.7.0-dev Last Updated: 2026-01-01

📋 For completed work, see CHANGELOG.md

This document tracks the future refactoring plan for Renamer v0.7.0+.

---

Completed Phases

✅ Phase 1: Critical Bug Fixes (5/5) - See CHANGELOG.md ✅ Phase 2: Architecture Foundation (5/5) - See CHANGELOG.md ✅ Phase 3: Code Quality (5/5) - See CHANGELOG.md

---

Pending Phases

Phase 3.6: Cleanup and Preparation (0/2)

Goal: Clean up remaining issues before major refactoring.

Status: NOT STARTED Priority: HIGH (Must complete before Phase 4)

3.6.1 Refactor ProposedNameFormatter to Use Decorator Pattern

Status: NOT STARTED

Current Issue: ProposedNameFormatter stores extracted values in __init__ as instance variables, creating unnecessary coupling.

Goal: Convert to functional/decorator pattern similar to other formatters.

Current Code:

class ProposedNameFormatter:
    def __init__(self, extractor):
        self.__order = extractor.get('order')
        self.__title = extractor.get('title')
        # ... more instance variables

    def rename_line(self) -> str:
        return f"{self.__order}{self.__title}..."

Target Design:

class ProposedNameFormatter:
    @staticmethod
    def format_proposed_name(extractor) -> str:
        """Generate proposed filename from extractor data"""
        # Direct formatting without storing state
        order = format_order(extractor.get('order'))
        title = format_title(extractor.get('title'))
        return f"{order}{title}..."

    @staticmethod
    def format_proposed_name_with_color(file_path, extractor) -> str:
        """Format proposed name with color highlighting"""
        proposed = ProposedNameFormatter.format_proposed_name(extractor)
        # Color logic here

Benefits:

• Stateless, pure functions
• Easier to test
• Consistent with other formatters
• Can use @cached() decorator if needed
• No coupling to extractor instance

Files to Modify:

• renamer/formatters/proposed_name_formatter.py
• Update all usages in app.py, screens.py, etc.

---

3.6.2 Clean Up Decorators Directory

Status: NOT STARTED

Current Issue: renamer/decorators/ directory contains legacy caching.py file that's no longer used. All cache decorators were moved to renamer/cache/decorators.py in Phase 1.

Current Structure:

renamer/decorators/
├── caching.py          # ⚠️ LEGACY - Remove
└── __init__.py         # Import from renamer.cache

Actions:

1. Verify no direct imports of renamer.decorators.caching
2. Remove caching.py - All functionality now in renamer/cache/decorators.py
3. Keep __init__.py for backward compatibility (imports from renamer.cache)
4. Update any direct imports to use from renamer.cache import cached_method

Verification:

# Check for direct imports of old caching module
grep -r "from renamer.decorators.caching" renamer/
grep -r "import renamer.decorators.caching" renamer/

# Should only find imports from __init__.py that re-export from renamer.cache

Benefits:

• Removes dead code
• Clarifies that all caching is in renamer/cache/
• Maintains backward compatibility via __init__.py

---

Phase 4: Refactor to New Architecture (0/4)

Goal: Migrate existing code to use the new architecture from Phase 2.

Status: NOT STARTED

4.1 Refactor Extractors to Use Protocol

• Update all extractors to explicitly implement DataExtractor Protocol
• Ensure consistent method signatures
• Add missing Protocol methods where needed
• Update type hints to match Protocol

Files to Update:

• filename_extractor.py
• mediainfo_extractor.py
• metadata_extractor.py
• fileinfo_extractor.py
• tmdb_extractor.py

4.2 Refactor Formatters to Use Base Classes

• Update all formatters to inherit from appropriate base classes
• Move to DataFormatter, TextFormatter, or MarkupFormatter
• Ensure consistent interface
• Add missing abstract methods

Files to Update:

• media_formatter.py
• catalog_formatter.py
• track_formatter.py
• proposed_name_formatter.py
• All specialized formatters

4.3 Integrate RenamerApp with Services

• Refactor app.py to use service layer
• Replace direct extractor calls with MetadataService
• Replace direct file operations with RenameService
• Replace direct tree building with FileTreeService
• Remove business logic from UI layer

Expected Benefits:

• Cleaner separation of concerns
• Easier testing
• Better error handling
• More maintainable code

4.4 Update Imports and Dependencies

• Update all imports to use new architecture
• Remove deprecated patterns
• Verify no circular dependencies
• Update tests to match new structure

---

Phase 5: Test Coverage (4/6 - 66% Complete)

Goal: Achieve comprehensive test coverage for all components.

Status: IN PROGRESS

✅ 5.1 Service Layer Tests (COMPLETED)

• 30+ tests for FileTreeService, MetadataService, RenameService
• Integration tests for service workflows

✅ 5.2 Utility Module Tests (COMPLETED)

• 70+ tests for PatternExtractor, LanguageCodeExtractor, FrameClassMatcher
• Integration tests for utility interactions

✅ 5.3 Formatter Tests (COMPLETED)

• 40+ tests for all formatter classes
• FormatterApplier testing

✅ 5.4 Dataset Organization (COMPLETED)

• Consolidated test data into datasets/
• 46 filename test cases
• 25 frame class test cases
• Sample file generator

⏳ 5.5 Screen Tests (PENDING)

Status: NOT STARTED

Scope:

• Test OpenScreen functionality
• Test HelpScreen display
• Test RenameConfirmScreen workflow
• Test SettingsScreen interactions
• Mock user input
• Verify screen transitions

⏳ 5.6 App Integration Tests (PENDING)

Status: NOT STARTED

Scope:

• End-to-end workflow testing
• Directory scanning → metadata display → rename
• Mode switching (technical/catalog)
• Cache integration
• Error handling flows
• Command palette integration

Target Coverage: >90%

---

Phase 6: Documentation and Release (0/7)

Goal: Finalize documentation and prepare for release.

Status: NOT STARTED

6.1 Update Technical Documentation

• ✅ ENGINEERING_GUIDE.md created
• API documentation generation
• Architecture diagrams
• Component interaction flows

6.2 Update User Documentation

• ✅ README.md streamlined
• User guide with screenshots
• Common workflows documentation
• Troubleshooting guide
• FAQ section

6.3 Update Developer Documentation

• ✅ DEVELOP.md streamlined
• Contributing guidelines
• Code review checklist
• PR template
• Issue templates

6.4 Create CHANGELOG

• ✅ CHANGELOG.md created
• Detailed version history
• Migration guides for breaking changes
• Deprecation notices

6.5 Version Bump to 0.7.0

• Update version in pyproject.toml
• Update version in all documentation
• Tag release in git
• Create GitHub release

6.6 Build and Test Distribution

• Build wheel and tarball
• Test installation from distribution
• Verify all commands work
• Test on clean environment
• Cross-platform testing

6.7 Prepare for PyPI Release (Optional)

• Create PyPI account
• Configure package metadata
• Test upload to TestPyPI
• Upload to PyPI
• Verify installation from PyPI

---

Testing Status

Current Metrics

• Total Tests: 560
• Pass Rate: 100% (559 passed, 1 skipped)
• Coverage: ~70% (estimated)
• Target: >90%

Manual Testing Checklist

• Test with large directories (1000+ files)
• Test with various video formats
• Test TMDB integration with real API
• Test poster download and display
• Test cache expiration and cleanup
• Test concurrent file operations
• Test error recovery
• Test resource cleanup (no leaks)
• Performance regression testing

---

Known Limitations

Current Issues

• TMDB API requires internet connection
• Poster display requires image-capable terminal
• Some special characters need sanitization
• Large directories may have slow initial scan

Planned Fixes

• Add offline mode with cached data
• Graceful degradation for terminal without image support
• Improve filename sanitization
• Optimize directory scanning with progress indication

---

Breaking Changes to Consider

Potential Breaking Changes in 0.7.0

• Cache key format (already changed in 0.6.0)
• Service layer API (internal, shouldn't affect users)
• Configuration file schema (may need migration)

Migration Strategy

• Provide migration scripts where needed
• Document all breaking changes in CHANGELOG
• Maintain backward compatibility where possible
• Deprecation warnings before removal

---

Performance Goals

Current Performance

• ~2 seconds for 100 files (initial scan)
• ~50ms per file (metadata extraction with cache)
• ~200ms per file (TMDB lookup)

Target Performance

• <1 second for 100 files
• <30ms per file (cached)
• <100ms per file (TMDB with cache)
• Background loading for large directories

---

Architecture Improvements

Already Implemented (Phase 2)

• ✅ Protocol-based extractors
• ✅ Service layer
• ✅ Utility modules
• ✅ Unified cache subsystem
• ✅ Thread pool for concurrent operations

Future Improvements

• Plugin system for custom extractors/formatters
• Event-driven architecture for UI updates
• Dependency injection container
• Configuration validation schema
• API versioning

---

Success Criteria

Phase 4 Complete When:

• All extractors implement Protocol
• All formatters use base classes
• RenamerApp uses services exclusively
• No direct business logic in UI
• All tests passing
• No performance regression

Phase 5 Complete When:

• >90% code coverage
• All screens tested
• Integration tests complete
• Manual testing checklist done
• Performance goals met

Phase 6 Complete When:

• All documentation updated
• Version bumped to 0.7.0
• Distribution built and tested
• Release notes published
• Migration guide available

---

Next Steps

1. Start Phase 4: Refactor to new architecture

   • Begin with extractor Protocol implementation
   • Update one extractor at a time
   • Run tests after each change
   • Document any issues encountered

2. Complete Phase 5: Finish test coverage

   • Add screen tests
   • Add integration tests
   • Run coverage analysis
   • Fix any gaps

3. Execute Phase 6: Documentation and release

   • Update all docs
   • Build distribution
   • Test thoroughly
   • Release v0.7.0

---

See Also:

• CHANGELOG.md - Completed work
• ToDo.md - Future feature requests
• ENGINEERING_GUIDE.md - Technical documentation

Last Updated: 2026-01-01