class-metrix 1.0.0 → 1.1.0

data/docs/ARCHITECTURE.md

@@ -11,31 +11,31 @@ graph TD
     subgraph "Public API Layer"
         API["ClassMetrix.extract(:constants, :class_methods)<br/>.from([Class1, Class2])<br/>.include_inherited<br/>.expand_hashes<br/>.to_markdown()"]
     end
-    
+
     subgraph "Core Extraction Layer"
         Extractor["Extractor<br/>(Coordinator)"]
         ClassResolver["Class Resolver<br/>(Utilities)"]
         ValueProcessor["Value Processor<br/>(Utilities)"]
     end
-    
+
     subgraph "Specialized Extractors"
         ConstantsExtractor["Constants<br/>Extractor"]
         MethodsExtractor["Methods<br/>Extractor"]
         MultiTypeExtractor["Multi-Type<br/>Extractor"]
     end
-    
+
     subgraph "Formatting Layer"
         MarkdownFormatter["Markdown<br/>Formatter"]
         CsvFormatter["CSV<br/>Formatter"]
     end
-    
+
     subgraph "Component Layer"
         subgraph "Report Components"
             HeaderComponent["Header<br/>Component"]
             TableComponent["Table<br/>Component"]
             FooterComponent["Footer<br/>Component"]
         end
-        
+
         subgraph "Table Sub-Components"
             TableDataExtractor["Table Data<br/>Extractor"]
             RowProcessor["Row<br/>Processor"]
@@ -43,31 +43,31 @@ graph TD
             TableRenderer["Table<br/>Renderer"]
         end
     end
-    
+
     API --> Extractor
     Extractor --> ClassResolver
     Extractor --> ValueProcessor
     Extractor --> ConstantsExtractor
     Extractor --> MethodsExtractor
     Extractor --> MultiTypeExtractor
-    
+
     ConstantsExtractor --> MarkdownFormatter
     MethodsExtractor --> MarkdownFormatter
     MultiTypeExtractor --> MarkdownFormatter
-    
+
     ConstantsExtractor --> CsvFormatter
     MethodsExtractor --> CsvFormatter
     MultiTypeExtractor --> CsvFormatter
-    
+
     MarkdownFormatter --> HeaderComponent
     MarkdownFormatter --> TableComponent
     MarkdownFormatter --> FooterComponent
-    
+
     TableComponent --> TableDataExtractor
     TableComponent --> RowProcessor
     TableComponent --> ColumnWidthCalculator
     TableComponent --> TableRenderer
-    
+
     style API fill:#e1f5fe
     style Extractor fill:#f3e5f5
     style MarkdownFormatter fill:#e8f5e8
@@ -134,7 +134,7 @@ ClassMetrix includes robust safety measures for handling unusual objects:
 ```ruby
 # Safe inspection methods that handle problematic objects
 logger.safe_inspect(value)    # Won't crash on inspect failures
-logger.safe_class(value)      # Won't crash on class failures  
+logger.safe_class(value)      # Won't crash on class failures
 logger.safe_keys(hash)        # Won't crash on keys failures
 logger.safe_to_s(value)       # Won't crash on to_s failures
 ```
@@ -160,6 +160,7 @@ This prevents objects like `Delayed::Backend::ActiveRecord::Job` (which may resp
 ## 🔄 Data Flow
 
 ### 1. **API Entry Point**
+
 ```ruby
 ClassMetrix.extract(:constants, :class_methods)
            .from([DatabaseService, CacheService])
@@ -172,40 +173,40 @@ ClassMetrix.extract(:constants, :class_methods)
 
 ```mermaid
 graph TD
-    UserRequest["User Request<br/>ClassMetrix.extract()"] 
-    
+    UserRequest["User Request<br/>ClassMetrix.extract()"]
+
     ClassMetrix["ClassMetrix<br/>.extract()"]
     Extractor["Extractor<br/>(Main Coordinator)"]
     ClassResolver["ClassResolver<br/>.normalize()"]
-    
+
     Router["Route to<br/>Appropriate<br/>Extractor"]
-    
+
     ConstantsExtractor["Constants<br/>Extractor"]
-    MethodsExtractor["Methods<br/>Extractor"] 
+    MethodsExtractor["Methods<br/>Extractor"]
     MultiTypeExtractor["Multi-Type<br/>Extractor"]
-    
+
     RawTableData["Raw Table Data<br/>{headers:[], rows:[]}"]
-    
+
     Formatter["Formatter<br/>(Markdown/CSV)"]
-    
+
     FormattedOutput["Formatted Output<br/>(String)"]
-    
+
     UserRequest --> ClassMetrix
     ClassMetrix --> Extractor
     Extractor --> ClassResolver
     Extractor --> Router
-    
+
     Router --> ConstantsExtractor
     Router --> MethodsExtractor
     Router --> MultiTypeExtractor
-    
+
     ConstantsExtractor --> RawTableData
     MethodsExtractor --> RawTableData
     MultiTypeExtractor --> RawTableData
-    
+
     RawTableData --> Formatter
     Formatter --> FormattedOutput
-    
+
     style UserRequest fill:#e3f2fd
     style Extractor fill:#f3e5f5
     style Router fill:#fff3e0
@@ -218,32 +219,32 @@ graph TD
 ```mermaid
 graph TD
     TableDataInput["Table Data Input<br/>{headers:[], rows:[]}"]
-    
+
     TableComponent["TableComponent<br/>(Main Coordinator)<br/>- Orchestrates<br/>- Delegates"]
-    
+
     TableDataExtractor["TableDataExtractor<br/>• has_type_column?()<br/>• extract_row_data()<br/>• collect_hash_keys()"]
-    
+
     RowProcessor["RowProcessor<br/>• process_simple_rows()<br/>• process_expanded_rows()<br/>• expand_row() (hash expansion)"]
-    
+
     ColumnWidthCalculator["ColumnWidthCalculator<br/>• calculate_widths()<br/>• initialize_column_widths()<br/>• apply_minimum_widths()"]
-    
+
     TableRenderer["TableRenderer<br/>• render_table()<br/>• build_row()<br/>• format_cells()"]
-    
+
     FinalRenderedTable["Final Rendered Table<br/>(Markdown/CSV String)"]
-    
+
     TableDataInput --> TableComponent
-    
+
     TableComponent --> TableDataExtractor
     TableComponent --> RowProcessor
     TableComponent --> ColumnWidthCalculator
     TableComponent --> TableRenderer
-    
+
     TableDataExtractor --> RowProcessor
     RowProcessor --> ColumnWidthCalculator
     ColumnWidthCalculator --> TableRenderer
-    
+
     TableRenderer --> FinalRenderedTable
-    
+
     style TableDataInput fill:#e3f2fd
     style TableComponent fill:#fff3e0
     style TableDataExtractor fill:#e8f5e8
@@ -256,6 +257,7 @@ graph TD
 ## 🧩 Core Components
 
 ### **1. Extractor (Coordinator)**
+
 - **Purpose**: Main API interface and request coordination
 - **Responsibilities**:
   - Parse user configuration
@@ -267,22 +269,29 @@ graph TD
 ### **2. Specialized Extractors**
 
 #### **ConstantsExtractor**
+
 - **Purpose**: Extract constants with inheritance/module support
 - **Key Features**:
+
   - Own constants: `Class.constants(false)`
   - Inherited constants: Walk superclass chain
-  - Module constants: Scan `included_modules`
+  - Module constants: Sca `included_modules`
+
   - Source tracking for debugging
 
-#### **MethodsExtractor** 
+#### **MethodsExtractor**
+
 - **Purpose**: Extract class methods with inheritance/module support
 - **Key Features**:
+
   - Own methods: `Class.singleton_methods(false)`
   - Inherited methods: Walk superclass chain
+
   - Module methods: Scan `singleton_class.included_modules`
   - Method resolution order handling
 
 #### **MultiTypeExtractor**
+
 - **Purpose**: Combine multiple extraction types into unified table
 - **Key Features**:
   - Add "Type" column to distinguish behavior types
@@ -294,26 +303,32 @@ graph TD
 The table component was recently refactored from a monolithic 269-line class into focused, reusable components:
 
 #### **TableComponent** (Main Coordinator - 42 lines)
+
 - **Purpose**: Orchestrate table generation process
 - **Responsibilities**: Initialize sub-components, coordinate data flow
 - **Pattern**: Composition over inheritance
 
 #### **TableDataExtractor** (55 lines)
+
 - **Purpose**: Data structure analysis and extraction utilities
 - **Key Methods**: `has_type_column?()`, `extract_row_data()`, `collect_hash_keys()`
 - **Responsibility**: Understand table structure and extract metadata
 
 #### **RowProcessor** (125 lines)
+
 - **Purpose**: Process table rows and handle hash expansion
 - **Key Methods**: `process_simple_rows()`, `process_expanded_rows()`, `expand_row()`
+
 - **Responsibility**: Transform raw data into renderable format
 
 #### **ColumnWidthCalculator** (57 lines)
+
 - **Purpose**: Calculate optimal column widths for table rendering
 - **Key Methods**: `calculate_widths()`, `apply_minimum_widths()`
 - **Responsibility**: Ensure proper table formatting
 
 #### **TableRenderer** (56 lines)
+
 - **Purpose**: Render final table with proper formatting
 - **Key Methods**: `render_table()`, `build_row()`, `format_cells()`
 - **Responsibility**: Generate final markdown table output
@@ -321,6 +336,7 @@ The table component was recently refactored from a monolithic 269-line class int
 ### **4. Formatters**
 
 #### **MarkdownFormatter**
+
 - **Purpose**: Generate rich markdown reports
 - **Key Features**:
   - Modular component architecture
@@ -329,8 +345,10 @@ The table component was recently refactored from a monolithic 269-line class int
   - Missing behavior analysis
 
 #### **CsvFormatter**
+
 - **Purpose**: Generate CSV output for data analysis
 - **Key Features**:
+
   - Clean CSV structure
   - Configurable separators and quotes
   - Hash flattening options
@@ -338,56 +356,69 @@ The table component was recently refactored from a monolithic 269-line class int
 ### **5. Support Components**
 
 #### **ValueProcessor**
+
 - **Purpose**: Process all Ruby value types consistently
 - **Handles**: Strings, numbers, booleans, arrays, hashes, nil, errors
 - **Visual Indicators**: ✅ (true), ❌ (false/nil), 🚫 (errors), ⚠️ (warnings)
 
 #### **ClassResolver**
+
 - **Purpose**: Normalize class inputs (strings vs class objects)
 - **Handles**: Class objects, string class names, error cases
 
 ## 🔧 Key Design Patterns
 
 ### **1. Fluent Interface**
+
 ```ruby
 ClassMetrix.extract(:constants)
            .from([Class1, Class2])
            .include_inherited
            .filter(/config/)
+
            .expand_hashes
            .to_markdown()
 ```
 
 ### **2. Strategy Pattern**
+
 - Different extractors for different extraction types
+
 - Different formatters for different output formats
 - Pluggable components for different behaviors
 
 ### **3. Composition Pattern**
+
 - Table component composed of focused sub-components
+
 - Formatters composed of reusable components
 - Modular architecture throughout
 
 ### **4. Template Method Pattern**
+
 - Base classes define structure
+
 - Subclasses implement specific behaviors
 - Consistent interfaces across components
 
 ## 🚀 Extension Points
 
 ### **Adding New Extraction Types**
+
 1. Create new extractor in `extractors/`
 2. Implement standard interface (`extract` method)
 3. Add type routing in `MultiTypeExtractor`
 4. Add API method in `Extractor`
 
 ### **Adding New Output Formats**
+
 1. Create new formatter in `formatters/`
 2. Extend base formatter class
 3. Implement format-specific logic
 4. Add API method in `Extractor`
 
 ### **Adding New Components**
+
 1. Create component in `formatters/components/`
 2. Extend `BaseComponent`
 3. Implement `generate` method
@@ -402,7 +433,7 @@ graph TD
     subgraph "Test Structure"
         APITests["API Integration Tests<br/>class_metrix_spec.rb"]
         ExtractorTests["Core Coordinator Tests<br/>extractor_spec.rb"]
-        
+
         subgraph "Unit Tests"
             ExtractorUnitTests["Extractor Unit Tests<br/>extractors/"]
             FormatterUnitTests["Formatter Tests<br/>formatters/"]
@@ -410,33 +441,34 @@ graph TD
             UtilsUnitTests["Utility Tests<br/>utils/"]
         end
     end
-    
+
     subgraph "Test Classes Hierarchy"
         TestParent["TestParent<br/>PARENT_CONSTANT<br/>parent_method()"]
         TestChild["TestChild<br/>CHILD_CONSTANT<br/>child_method()"]
         TestGrandchild["TestGrandchild<br/>GRANDCHILD_CONSTANT<br/>grandchild_method()"]
-        
+
         TestParent --> TestChild
         TestChild --> TestGrandchild
     end
-    
+
     subgraph "Test Modules"
         TestModule["TestModule<br/>TEST_MODULE_CONSTANT<br/>module_method()"]
         AnotherTestModule["AnotherTestModule<br/>ANOTHER_CONSTANT<br/>another_module_method()"]
     end
-    
+
     subgraph "Realistic Examples"
         TestUser["TestUser<br/>ROLE_NAME = 'user'<br/>config()"]
         TestAdmin["TestAdmin<br/>ROLE_NAME = 'admin'<br/>admin_config()"]
     end
-    
+
     TestChild -.->|includes| TestModule
     TestGrandchild -.->|includes| AnotherTestModule
-    
+
     APITests --> ExtractorTests
+
     ExtractorTests --> ExtractorUnitTests
     ExtractorTests --> FormatterUnitTests
-    
+
     ExtractorUnitTests -.->|uses| TestParent
     ExtractorUnitTests -.->|uses| TestChild
     ExtractorUnitTests -.->|uses| TestGrandchild
@@ -444,37 +476,44 @@ graph TD
     ExtractorUnitTests -.->|uses| AnotherTestModule
     ExtractorUnitTests -.->|uses| TestUser
     ExtractorUnitTests -.->|uses| TestAdmin
-    
+
+
     style APITests fill:#e3f2fd
     style ExtractorTests fill:#f3e5f5
     style TestParent fill:#e8f5e8
     style TestChild fill:#fff3e0
+
     style TestGrandchild fill:#fce4ec
     style TestModule fill:#e1f5fe
     style AnotherTestModule fill:#e1f5fe
 ```
 
 ### **Test Coverage**
+
 - ✅ **Basic Extraction**: Constants and methods from simple classes
 - ✅ **Inheritance**: Multi-level inheritance chains
 - ✅ **Modules**: Module inclusion and method resolution
 - ✅ **Error Handling**: Missing methods, constants, class resolution failures
 - ✅ **Value Types**: All Ruby value types and edge cases
+
 - ✅ **Integration**: End-to-end functionality with real-world scenarios
 
 ## 📈 Performance Considerations
 
 ### **Lazy Evaluation**
+
 - Extractors only process data when `to_markdown()`/`to_csv()` is called
 - Filters applied efficiently during extraction
 - Minimal memory usage for large class sets
 
 ### **Inheritance Optimization**
+
 - Superclass chain traversal is optimized
 - Core Ruby classes (`Object`, `BasicObject`) are skipped
 - Module resolution uses efficient set operations
 
 ### **Table Rendering Optimization**
+
 - Column width calculation is performed once
 - Row processing is streamlined
 - String operations are minimized
@@ -482,20 +521,23 @@ graph TD
 ## 🔄 Future Architecture Plans
 
 ### **Plugin System**
+
 - Plugin architecture for custom extractors
 - Extension points for custom components
 - Configuration system for plugin management
 
 ### **Caching Layer**
+
 - Cache class metadata for performance
 - Invalidation strategies for development
 - Configurable caching backends
 
 ### **Parallel Processing**
+
 - Parallel extraction for large class sets
 - Worker pool for I/O operations
 - Memory-efficient streaming for large datasets
 
 ---
 
-*This architecture document is maintained alongside code changes.* 
+_This architecture document is maintained alongside code changes._

data/docs/CHANGELOG_EVOLUTION_EXAMPLE.md

@@ -0,0 +1,95 @@
+# ClassMetrix Changelog Evolution Example
+
+## Current State (v1.0.0 released)
+
+```markdown
+## [Unreleased]
+
+## [1.0.0] - 2025-06-07
+
+### Added
+
+- Advanced Debug System
+- Enhanced Hash Expansion
+
+# ... existing content
+```
+
+## After working on some features
+
+```markdown
+## [Unreleased]
+
+### Added
+
+- Instance variable extraction support
+- New output format: JSON
+- CLI interface for command-line usage
+
+### Changed
+
+- Improved performance for large class hierarchies
+- Better error messages with suggestions
+
+### Fixed
+
+- Memory leak in hash expansion
+- CSV encoding issues with special characters
+
+## [1.0.0] - 2025-06-07
+
+# ... existing content
+```
+
+## Ready for v1.1.0 release
+
+```markdown
+## [Unreleased]
+
+## [1.1.0] - 2025-07-15
+
+### Added
+
+- Instance variable extraction support
+- New output format: JSON
+- CLI interface for command-line usage
+
+### Changed
+
+- Improved performance for large class hierarchies
+- Better error messages with suggestions
+
+### Fixed
+
+- Memory leak in hash expansion
+- CSV encoding issues with special characters
+
+## [1.0.0] - 2025-06-07
+
+# ... existing content
+```
+
+## Working on next features
+
+```markdown
+## [Unreleased]
+
+### Added
+
+- Plugin system for custom extractors
+- Web UI for interactive analysis
+
+### Changed
+
+- Refactored formatter architecture
+
+## [1.1.0] - 2025-07-15
+
+### Added
+
+- Instance variable extraction support
+- New output format: JSON
+- CLI interface for command-line usage
+
+# ... etc
+```