github-personal/moma
1
0
Fork 0
mirror of https://github.com/shadoll/moma.git synced 2026-08-28 03:27:34 +00:00
Code Issues Packages Projects Releases 4 Wiki Activity

feat: Enhance documentation update protocol in AGENTS.md and REFACTORING_PROGRESS.md; remove version info from CLAUDE.md

Browse Source
This commit is contained in:
sha
2026-04-12 11:32:29 +03:00
parent 0ac0d67aae
commit 7605a7d2fc
3 changed files with 75 additions and 287 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REFACTORING_PROGRESS.md
+55 -281
View File
@@ -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