diff --git a/.markitect_workspace/issue_38/GAMEPLAN.md b/.markitect_workspace/issue_38/GAMEPLAN.md new file mode 100644 index 00000000..b1a2665d --- /dev/null +++ b/.markitect_workspace/issue_38/GAMEPLAN.md @@ -0,0 +1,158 @@ +# GAMEPLAN for Issue #38: Content Commands - Access Content Stats and Raw Content Separately + +## ๐ŸŽฏ **OBJECTIVE** (Updated Scope) +Implement dedicated CLI commands for content analysis and raw content access, completing the foundation of granular markdown component access. This issue now focuses specifically on **content commands** after decomposing the original broader scope into separate issues: +- Issue #41: Frontmatter Commands +- Issue #42: Contentmatter Commands +- Issue #43: Tailmatter Commands + +## ๐Ÿ“‹ **REQUIREMENTS ANALYSIS** + +### **Current State Assessment:** +- โœ… `markitect metadata` command renamed to `db-data` (Phase 1 completed) +- โœ… Backward compatibility maintained with deprecation warnings +- ๐ŸŽฏ **Current Focus**: Implement content analysis and raw content access commands + +### **Target Architecture (Content Commands Only):** +Based on MarkdownMatters.md specification, this issue focuses on: +1. **Content Statistics**: Word count, line count, heading analysis, link analysis +2. **Raw Content Access**: Extract clean markdown content without frontmatter/tailmatter +3. **Content Processing**: Strip matter blocks, analyze structure, provide metrics + +## ๐Ÿš€ **IMPLEMENTATION PHASES** + +### **Phase 1: Command Restructuring (Foundation)** โœ… **COMPLETED** +- [x] Rename `metadata` command to `db-data` +- [x] Update all references in codebase and tests +- [x] Maintain backward compatibility with deprecation warnings +- [x] Update CLI help and documentation + +### **Phase 2: Content Commands (Current Focus)** +- [ ] Create `content_processor.py` module with ContentStats and ContentProcessor classes +- [ ] Implement `content-stats` command - Statistics about content (word count, line count, headings, etc.) +- [ ] Implement `content-get [path]` command - Echo content without frontmatter and tailmatter +- [ ] Comprehensive testing for both commands +- [ ] Integration with existing CLI patterns + +## **Related Issues (Now Separate)** +The following phases have been moved to separate issues for focused development: +- **Phase 3: Frontmatter Commands** โ†’ Issue #41: Frontmatter Commands - YAML/JSON Header Manipulation +- **Phase 4: Contentmatter Commands** โ†’ Issue #42: Contentmatter Commands - MMD Key-Value Processing +- **Phase 5: Tailmatter Commands** โ†’ Issue #43: Tailmatter Commands - QA and Editorial Metadata Management + +## ๐Ÿงช **TESTING STRATEGY** + +### **Test Organization (Updated for Content Commands Focus):** +- โœ… `test_issue_38_command_restructuring.py` - Phase 1 tests (completed) +- ๐ŸŽฏ `test_issue_38_content_commands.py` - Phase 2 content commands tests (current focus) + +### **Test Categories:** +1. **Command Existence Tests** - Verify all commands are properly registered +2. **Functionality Tests** - Test core behavior for each command +3. **Error Handling Tests** - Invalid files, missing keys, malformed content +4. **Format Support Tests** - JSON, YAML, table output formats +5. **Integration Tests** - Commands working together in workflows +6. **Performance Tests** - Large file handling and response times + +## ๐Ÿ—๏ธ **TECHNICAL ARCHITECTURE** + +### **New Module Structure (Content Commands Focus):** +``` +markitect/ +โ”œโ”€โ”€ content_processor.py # Content parsing and analysis (THIS ISSUE) +โ””โ”€โ”€ [Other processors moved to separate issues] +``` + +### **Data Models (Content Commands Focus):** +```python +@dataclass +class ContentStats: + word_count: int + line_count: int + character_count: int + heading_counts: Dict[int, int] # level -> count + link_count: int + external_link_count: int + image_count: int + code_block_count: int + list_item_count: int + +class ContentProcessor: + def analyze_content(self, content: str) -> ContentStats + def extract_content(self, markdown: str) -> str + def strip_frontmatter(self, content: str) -> str + def strip_tailmatter(self, content: str) -> str +``` + +### **CLI Commands (This Issue):** +- `content-stats` - Comprehensive content analysis and statistics +- `content-get` - Extract raw content without frontmatter/tailmatter +- โœ… `db-data` - Complete data access (renamed from metadata, completed) + +## ๐Ÿ“Š **SUCCESS METRICS** + +### **Functional Success (Updated for Content Commands):** +- [ ] 2 new content CLI commands implemented and working +- [ ] Complete test coverage (>95%) for content command functionality +- [ ] Backward compatibility maintained for existing workflows +- [ ] Performance within 10% of current db-data command speed + +### **User Experience Success:** +- [ ] Intuitive command naming following consistent patterns +- [ ] Comprehensive help documentation for all commands +- [ ] Consistent output formatting across all commands +- [ ] Clear error messages for all failure scenarios + +### **Technical Success (Content Commands Focus):** +- [ ] Clean content processing module with clear responsibilities +- [ ] Extensible ContentProcessor architecture for future content analysis features +- [ ] Efficient markdown parsing and content extraction +- [ ] Thread-safe operation for concurrent content analysis + +## โšก **IMPLEMENTATION APPROACH** + +### **TDD8 Methodology:** +1. **ISSUE**: Break down into manageable sub-issues for each phase +2. **TEST**: Write comprehensive tests for each command before implementation +3. **RED**: Ensure tests fail initially (proper TDD red state) +4. **GREEN**: Implement minimal code to make tests pass +5. **REFACTOR**: Clean up implementation and optimize performance +6. **DOCUMENT**: Update CLI help, README, and user documentation +7. **REFINE**: Performance testing and edge case handling +8. **PUBLISH**: Integration testing and final validation + +### **Development Order (Updated for Content Commands Focus):** +1. โœ… Complete Phase 1 (command restructuring) - DONE +2. ๐ŸŽฏ Implement Phase 2 (content commands) - CURRENT FOCUS + - Create content_processor.py module + - Implement content-stats command + - Implement content-get command + - Comprehensive testing + +## ๐ŸŽฏ **IMMEDIATE NEXT STEPS** + +1. โœ… **Phase 1 Tests and Implementation** - COMPLETED +2. โœ… **Implement db-data Command** - COMPLETED +3. ๐ŸŽฏ **Create Content Processor Module**: Foundation for content analysis (NEXT) +4. ๐ŸŽฏ **Implement content-stats Command**: Content analysis and statistics (NEXT) +5. ๐ŸŽฏ **Implement content-get Command**: Raw content extraction (NEXT) + +## ๐Ÿ“ **NOTES** + +- **Backward Compatibility**: Maintain `metadata` command with deprecation warning +- **Performance**: Cache parsed components to avoid re-parsing for related commands +- **Error Handling**: Graceful degradation for malformed markdown files +- **Output Formats**: Support table, JSON, YAML formats consistently across all commands +- **Documentation**: Reference MarkdownMatters.md specification for implementation details + +--- + +**Estimated Timeline:** 3-5 days for content commands implementation +**Risk Level:** Low (focused scope, clear requirements, foundation completed) +**Dependencies:** Existing CLI infrastructure, markdown parsing capabilities + +## ๐Ÿ”— **RELATED ISSUES** +- Issue #41: Frontmatter Commands - YAML/JSON Header Manipulation +- Issue #42: Contentmatter Commands - MMD Key-Value Processing +- Issue #43: Tailmatter Commands - QA and Editorial Metadata Management +- Issue #39: Database Command Reorganization (foundation completed) \ No newline at end of file