diff --git a/AGENTS.md b/AGENTS.md index 405edf3..540cb72 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -651,14 +651,30 @@ except (LookupError, ValueError, AttributeError) as e: 4. **Simplicity First**: Avoid over-engineering solutions 5. **Document Changes**: Update relevant documentation -### When Adding Features +### Documentation Update Protocol + +**After every change to functionality, architecture, or deployment — always:** + +1. **Update CHANGELOG.md** — add an entry under `[Unreleased]` describing what changed and why +2. **Update AGENTS.md** — if architecture, file structure, key bindings, settings, screens, or any documented component changed +3. **Update README.md** — if user-facing behaviour, commands, or config changed +4. **Check `docs/ToDo.md`** — if the completed work matches a task there, mark it ✅ done +5. **Propose these updates to the user** before finishing — don't silently skip doc updates + +**When a feature request is deferred or postponed:** + +1. **Propose adding it to `docs/ToDo.md`** under the appropriate priority section +2. **If it's large or complex** (multi-step, affects multiple components, or needs design decisions): propose creating a standalone spec file in `docs/` (e.g. `docs/feature-mkv-editor.md`) and add a reference link in `docs/ToDo.md` +3. **Always confirm with the user** before creating new doc files + +**When adding a new feature:** 1. Read existing code and understand architecture -2. Check `REFACTORING_PROGRESS.md` for pending tasks +2. Check `docs/ToDo.md` and `docs/REFACTORING_PROGRESS.md` for related pending tasks 3. Implement features incrementally 4. Test with real media files 5. Ensure backward compatibility -6. Update documentation +6. Apply Documentation Update Protocol above 7. Update tests as needed 8. Run `uv run release` before committing @@ -677,6 +693,7 @@ except (LookupError, ValueError, AttributeError) as e: 3. Check all formatters (formatting is centralized) 4. Verify extractor chain (ensure data flow intact) 5. Run full test suite +6. Apply Documentation Update Protocol above ### Common Pitfalls to Avoid diff --git a/CLAUDE.md b/CLAUDE.md index ef70eb9..3b24b7b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,8 +1,5 @@ # CLAUDE.md - AI Assistant Reference -**Version**: 0.8.11 -**Last Updated**: 2026-04-11 - > **📘 All technical documentation has been moved to [AGENTS.md](AGENTS.md)** ## For AI Assistants diff --git a/docs/REFACTORING_PROGRESS.md b/docs/REFACTORING_PROGRESS.md index b3ad965..aeca7e6 100644 --- a/docs/REFACTORING_PROGRESS.md +++ b/docs/REFACTORING_PROGRESS.md @@ -1,331 +1,105 @@ # moma - Refactoring Roadmap **Version**: 0.8.11 -**Last Updated**: 2026-04-11 +**Last Updated**: 2026-04-12 -> **📋 For completed work, see [CHANGELOG.md](CHANGELOG.md)** - -This document tracks the future refactoring plan for moma v0.8.x+. +> **📋 For completed work detail, see [CHANGELOG.md](../CHANGELOG.md)** --- -## Completed Phases +## Completed (Summary) -✅ **Phase 1**: Critical Bug Fixes (5/5) - [See CHANGELOG.md](CHANGELOG.md) -✅ **Phase 2**: Architecture Foundation (5/5) - [See CHANGELOG.md](CHANGELOG.md) -✅ **Phase 3**: Code Quality (5/5) - [See CHANGELOG.md](CHANGELOG.md) +| Phase | Description | Version | +|-------|-------------|---------| +| ✅ Phase 1 | Critical Bug Fixes — cache key fix, resource leaks, thread safety, logging | 0.7.0 | +| ✅ Phase 2 | Architecture Foundation — `DataExtractor` Protocol, service layer, utility modules, command palette (Ctrl+P) | 0.7.0 | +| ✅ Phase 3 | Code Quality — constants split into 8 modules, type hints, docstrings, dynamic year validation | 0.7.0 | +| ✅ Phase 3.6 | Cleanup — `ProposedFilenameView` moved to decorator pattern; `src/decorators/` dir removed | 0.7.0 | +| ✅ Phase 5 (4/6) | Tests — service, utility, formatter, cache, dataset tests; 560 total, 100% pass rate | 0.7.0 | +| ✅ Phase 6 (partial) | Docs — AGENTS.md, CHANGELOG.md, README.md, DEVELOP.md created/updated | 0.7.0 | --- -## Pending Phases +## Pending -### Phase 3.6: Cleanup and Preparation (2/2 COMPLETED) +### Phase 4: Refactor to New Architecture -#### 3.6.1 Refactor ProposedNameFormatter to Use Decorator Pattern -**Status**: ✅ COMPLETED - -The class was renamed `ProposedFilenameView` and moved to `src/views/proposed_filename.py`. It now uses the decorator pattern with `@conditional_decorators`, `@text_decorators`, etc. — consistent with the rest of the formatter system. - -#### 3.6.2 Clean Up Decorators Directory -**Status**: ✅ COMPLETED - -`src/decorators/` directory no longer exists. All cache decorators live in `src/cache/decorators.py`. - ---- - -### Phase 4: Refactor to New Architecture (0/4) - -**Goal**: Migrate existing code to use the new architecture from Phase 2. - -**Status**: NOT STARTED +**Status**: NOT STARTED +**Goal**: Migrate existing code to fully use the architecture established in Phase 2. #### 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 +- Ensure consistent method signatures and fill missing Protocol methods +- Update type hints throughout -**Files to Update**: -- `filename_extractor.py` -- `mediainfo_extractor.py` -- `metadata_extractor.py` -- `fileinfo_extractor.py` -- `tmdb_extractor.py` +**Files**: `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 +- Update all formatters to inherit from `DataFormatter`, `TextFormatter`, or `MarkupFormatter` +- Ensure consistent interface across formatter hierarchy -**Files to Update**: -- `media_formatter.py` -- `catalog_formatter.py` -- `track_formatter.py` -- `proposed_name_formatter.py` -- All specialized formatters +**Files**: `catalog_formatter.py`, `track_formatter.py`, and all specialized formatters in `src/formatters/` #### 4.3 Integrate MomaApp with Services -- Refactor `app.py` to use service layer +- Refactor `app.py` to use service layer exclusively - 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 +- Remove all business logic from UI layer #### 4.4 Update Imports and Dependencies -- Update all imports to use new architecture -- Remove deprecated patterns -- Verify no circular dependencies +- Clean up imports after Phase 4.1–4.3 +- Remove deprecated patterns, verify no circular dependencies - Update tests to match new structure --- -### Phase 5: Test Coverage (4/6 - 66% Complete) +### Phase 5: Test Coverage (4/6 — IN PROGRESS) -**Goal**: Achieve comprehensive test coverage for all components. +#### ⏳ 5.5 Screen Tests +- Test all 6 screens: OpenScreen, HelpScreen, RenameConfirmScreen, ConvertConfirmScreen, DeleteConfirmScreen, SettingsScreen +- Mock user input, verify screen transitions and error handling -**Status**: IN PROGRESS +#### ⏳ 5.6 App Integration Tests +- End-to-end: directory scan → metadata display → rename +- Mode switching, cache integration, error handling, command palette flows -#### ✅ 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% +**Target**: >90% coverage --- -### Phase 6: Documentation and Release (0/7) +### Phase 6: Documentation and Release (partially done) -**Goal**: Finalize documentation and prepare for release. +#### ✅ Done +- AGENTS.md — comprehensive technical reference +- CHANGELOG.md — version history +- README.md — streamlined user guide +- DEVELOP.md — developer setup -**Status**: NOT STARTED - -#### 6.1 Update Technical Documentation -- ✅ AGENTS.md created +#### Remaining - [ ] 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 +- [ ] Architecture diagrams and component interaction flows +- [ ] Contributing guidelines, PR/issue templates +- [ ] Build and test distribution (`uv build`, clean install test) +- [ ] PyPI release (optional) --- -## 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 -- [ ] MomaApp 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 +- [ ] Large directories (1000+ files) +- [ ] Various video formats +- [ ] TMDB integration with real API key +- [ ] Poster download and display (pseudo/viu/richpixels modes) +- [ ] Cache expiration and cleanup +- [ ] Concurrent file operations +- [ ] Error recovery (missing files, permission errors, network failures) --- **See Also**: -- [CHANGELOG.md](CHANGELOG.md) - Completed work -- [ToDo.md](ToDo.md) - Future feature requests -- [AGENTS.md](AGENTS.md) - Technical documentation +- [../CHANGELOG.md](../CHANGELOG.md) — Completed work with full details +- [ToDo.md](ToDo.md) — Feature requests and future ideas +- [../AGENTS.md](../AGENTS.md) — Architecture and technical documentation -**Last Updated**: 2026-04-11 +**Last Updated**: 2026-04-12