diff --git a/ISSUE_147_EXPLODE_IMPLODE_ENHANCEMENT_GAMEPLAN.md b/ISSUE_147_EXPLODE_IMPLODE_ENHANCEMENT_GAMEPLAN.md new file mode 100644 index 00000000..5a3cf634 --- /dev/null +++ b/ISSUE_147_EXPLODE_IMPLODE_ENHANCEMENT_GAMEPLAN.md @@ -0,0 +1,182 @@ +# Issue #147: Explode-Implode Enhancement Gameplan + +## Executive Summary + +This document outlines the comprehensive gameplan to enhance the explode-implode cycle in MarkiTect, addressing the need to preserve directory organization and provide multiple explosion variants while maintaining complete reversibility. + +## Problem Statement + +Current limitations of the explode-implode system: +1. **Ordering Loss**: Chapter sequence not preserved during explode → implode cycle +2. **No Directory Organization Options**: Only one explosion pattern supported +3. **No Metadata Preservation**: Original structure context lost +4. **Missing File Type Conventions**: No standardized extensions (.mdd, .mdz, .mdt) +5. **No Auto-Detection**: Can't automatically determine explosion variant during implode + +## Solution Architecture + +### 1. Directory Organization Variants + +**Variant A: Current Flat Structure** +``` +book.mdd/ +├── manifest.md # NEW: Order preservation +├── book_title/ +│ ├── index.md # Main content +│ ├── chapter_1.md +│ └── chapter_2.md +└── conclusion.md +``` + +**Variant B: Hierarchical Structure** +``` +book.mdd/ +├── manifest.md +├── 01_book_title/ +│ ├── index.md +│ ├── 01_chapter_1/ +│ │ ├── index.md +│ │ └── 01_section_1.md +│ └── 02_chapter_2/ +└── 99_conclusion.md +``` + +**Variant C: Semantic Structure** +``` +book.mdd/ +├── manifest.md +├── parts/ +│ ├── 01_fundamentals/ +│ └── 02_advanced/ +├── chapters/ +│ ├── 01_basics/ +│ └── 02_intermediate/ +└── appendices/ +``` + +### 2. Manifest System for Reversibility + +**manifest.md Structure:** +```yaml +--- +explosion_type: hierarchical_v1 +original_file: book.md +created: 2025-10-12T19:30:00Z +markitect_version: 0.1.0 +preservation: + front_matter: true + section_order: true + heading_levels: true +structure: + - type: h1 + title: "Book Title" + path: "01_book_title/index.md" + order: 1 + - type: h2 + title: "Chapter 1: Basics" + path: "01_book_title/01_chapter_1/index.md" + parent: "Book Title" + order: 2 +--- + +# Explosion Manifest + +This directory was created by exploding `book.md` using the hierarchical structure variant. +``` + +### 3. File Extension Conventions + +- **.md** - Standard markdown file +- **.mdd** - Markdown Directory (exploded markdown structure) +- **.mdz** - Markdown Zip (compressed .mdd with manifest) +- **.mdt** - Markdown Transcluded (zip with all referenced resources) + +### 4. Enhanced Command Interface + +```bash +# Explode with variants +markitect md-explode book.md --variant=flat # Current behavior +markitect md-explode book.md --variant=hierarchical # Numbered structure +markitect md-explode book.md --variant=semantic # Semantic grouping + +# Auto-detect and implode +markitect md-implode book.mdd/ # Auto-detects variant +markitect md-implode book.mdd/ --force-variant=flat # Override detection + +# Package operations +markitect md-package book.mdd/ book.mdz # Create zip +markitect md-package book.mdd/ book.mdt --transclude # Include resources +``` + +### 5. Auto-Detection Algorithm + +1. **Check for manifest.md** - Primary detection method +2. **Directory naming patterns** - Numbered prefixes → hierarchical +3. **Semantic directory names** - parts/, chapters/ → semantic +4. **Fallback to current** - No pattern → flat structure + +## Implementation Strategy + +### Phase 1: Core Infrastructure +1. Create `ExplodeVariant` enum and base classes +2. Implement `ManifestManager` for manifest creation/parsing +3. Add variant detection logic +4. Update command interface with `--variant` parameter + +### Phase 2: Variant Implementations +1. Refactor current logic into `FlatVariant` class +2. Implement `HierarchicalVariant` with numbered structure +3. Implement `SemanticVariant` with content-based grouping +4. Add comprehensive tests for each variant + +### Phase 3: Advanced Features +1. Implement `.mdz` and `.mdt` packaging +2. Add transclusion support for external resources +3. Enhance auto-detection with machine learning patterns +4. Add migration tools for existing exploded structures + +### Phase 4: Integration & Polish +1. Update documentation and examples +2. Add performance benchmarks +3. Create migration guide for existing users +4. Integration with asset management system + +## Benefits + +✅ **Preserves All Information** - Manifest ensures reversibility +✅ **Multiple Organization Patterns** - Suits different use cases +✅ **Backward Compatibility** - Current behavior preserved as default +✅ **Auto-Detection** - Seamless implode operations +✅ **Extensible** - Easy to add new variants +✅ **Standardized** - Clear file extension conventions + +## Success Criteria + +1. **100% Reversibility** - Any exploded structure can be perfectly imploded +2. **Variant Auto-Detection** - Implode automatically detects explosion variant +3. **Backward Compatibility** - Existing workflows continue to work +4. **Performance** - New features don't significantly impact performance +5. **Documentation** - Complete user and developer documentation +6. **Test Coverage** - Comprehensive test suite for all variants and edge cases + +## Timeline Estimate + +- **Phase 1**: 2-3 weeks (Core Infrastructure) +- **Phase 2**: 3-4 weeks (Variant Implementations) +- **Phase 3**: 2-3 weeks (Advanced Features) +- **Phase 4**: 1-2 weeks (Integration & Polish) + +**Total Estimated Duration**: 8-12 weeks + +## Risk Assessment + +**Medium Risk**: Backward compatibility with existing exploded structures +**Low Risk**: Performance impact of manifest system +**Low Risk**: Complexity of auto-detection algorithm + +## Next Steps + +1. Create detailed implementation issues for each phase +2. Set up feature branch for development +3. Begin Phase 1 implementation +4. Coordinate with asset management system integration \ No newline at end of file