class-metrix 1.0.0 → 1.0.1

data/README.md

@@ -5,10 +5,12 @@
 
 **ClassMetrix** is a Ruby gem that extracts and compares class behaviors (constants, class methods, and more) across multiple classes, generating clean markdown reports for analysis, documentation, and compliance auditing.
 
+> **Why "Metrix"?** Short for "metrics" - measuring and analyzing class behaviors.
+
 ## ✨ Features
 
 - **🔍 Multi-Type Extraction**: Constants, class methods, and more
-- **📊 Hash Expansion**: Expand hash values into readable sub-rows  
+- **📊 Hash Expansion**: Expand hash values into readable sub-rows
 - **🛡️ Error Handling**: Graceful handling of missing methods and constants
 - **🐛 Debug Mode**: Detailed logging for troubleshooting and analysis
 - **📝 Rich Markdown Reports**: Professional reports with configurable components
@@ -30,7 +32,7 @@ ClassMetrix.extract(:constants, :class_methods)
   .filter(/config$/)
   .expand_hashes
   .handle_errors
-  .to_markdown("audit_report.md", 
+  .to_markdown("audit_report.md",
     title: "Service Configuration Audit",
     footer_style: :detailed,
     show_missing_summary: true
@@ -40,7 +42,7 @@ ClassMetrix.extract(:constants, :class_methods)
 ClassMetrix.extract(:constants)
   .from([DatabaseConfig, RedisConfig])
   .expand_hashes
-  .to_csv("config_analysis.csv", 
+  .to_csv("config_analysis.csv",
     title: "Configuration Analysis",
     flatten_hashes: true
   )
@@ -65,6 +67,7 @@ gem install class-metrix
 ### Basic Extraction
 
 #### Constants
+
 ```ruby
 # Extract constants from multiple classes
 ClassMetrix.extract(:constants)
@@ -79,6 +82,7 @@ ClassMetrix.extract(:constants)
 ```
 
 #### Class Methods
+
 ```ruby
 # Extract class method results
 ClassMetrix.extract(:class_methods)
@@ -94,6 +98,7 @@ ClassMetrix.extract(:class_methods)
 ```
 
 #### Multi-Type Extraction
+
 ```ruby
 # Combine multiple extraction types in one table
 ClassMetrix.extract(:constants, :class_methods)
@@ -110,6 +115,7 @@ ClassMetrix.extract(:constants, :class_methods)
 ### Advanced Features
 
 #### Hash Expansion
+
 ```ruby
 # Expand hash values into readable sub-rows
 ClassMetrix.extract(:constants)
@@ -127,6 +133,7 @@ ClassMetrix.extract(:constants)
 ```
 
 #### Error Handling
+
 ```ruby
 # Handle missing methods and constants gracefully
 ClassMetrix.extract(:class_methods)
@@ -144,6 +151,7 @@ ClassMetrix.extract(:class_methods)
 ```
 
 #### Filtering
+
 ```ruby
 # Filter behaviors by pattern
 ClassMetrix.extract(:constants)
@@ -159,6 +167,7 @@ ClassMetrix.extract(:class_methods)
 ```
 
 #### Debug Mode
+
 ```ruby
 # Enable detailed logging for troubleshooting
 ClassMetrix.extract(:constants, :class_methods)
@@ -185,17 +194,20 @@ ClassMetrix.extract(:constants)
 ```
 
 **Debug Levels:**
+
 - **`:basic`** (default) - Key decisions and summaries only
-- **`:detailed`** - More context and intermediate steps  
+- **`:detailed`** - More context and intermediate steps
 - **`:verbose`** - Full details including individual value processing
 
 **Debug Features:**
+
 - **Safe Object Inspection**: Handles objects with problematic `inspect`/`to_s` methods
 - **Hash Detection Analysis**: Shows why objects are/aren't treated as expandable hashes
 - **Smart Logging**: Reduces spam by grouping related operations and focusing on key decisions
 - **Error Diagnostics**: Detailed error context for troubleshooting
 
 #### CSV Output
+
 ```ruby
 # Basic CSV output
 ClassMetrix.extract(:constants)
@@ -229,6 +241,7 @@ ClassMetrix.extract(:class_methods)
 ClassMetrix offers extensive configuration options for customizing report generation:
 
 ### Markdown Report Options
+
 ```ruby
 ClassMetrix.extract(:constants)
   .from([User, Admin])
@@ -236,30 +249,31 @@ ClassMetrix.extract(:constants)
     # File and title
     "report.md",
     title: "Custom Report Title",
-    
+
     # Content sections
     show_metadata: true,          # Show title and report info
     show_classes: true,           # Show "Classes Analyzed" section
     show_extraction_info: true,   # Show "Extraction Types" section
     show_missing_summary: false,  # Show missing behaviors summary
-    
+
     # Footer configuration
     show_footer: true,            # Show footer
     footer_style: :detailed,      # :default, :minimal, :detailed
     show_timestamp: true,         # Include generation timestamp
     custom_footer: "Custom note", # Custom footer message
-    
+
     # Table formatting
     table_style: :standard,       # :standard, :compact, :wide
     min_column_width: 3,          # Minimum column width
     max_column_width: 50,         # Maximum column width (for :compact style)
-    
+
     # Missing behaviors analysis
     summary_style: :grouped       # :grouped, :flat, :detailed
   )
 ```
 
 ### CSV Output Options
+
 ```ruby
 ClassMetrix.extract(:constants)
   .from([User, Admin])
@@ -267,16 +281,16 @@ ClassMetrix.extract(:constants)
     # File and title
     "report.csv",
     title: "Custom CSV Report",
-    
+
     # Content options
     show_metadata: true,          # Show comment headers
     comment_char: "#",            # Comment character for metadata
-    
+
     # CSV formatting
     separator: ",",               # Column separator (comma, semicolon, tab)
     quote_char: '"',              # Quote character
     null_value: "",               # Value for nil/missing data
-    
+
     # Hash handling
     flatten_hashes: true,         # Flatten hashes into separate columns
                                   # false = expand into sub-rows
@@ -286,20 +300,26 @@ ClassMetrix.extract(:constants)
 ### Footer Styles
 
 #### Default Footer
+
 ```markdown
 ---
-*Report generated by ClassMetrix gem*
+
+_Report generated by ClassMetrix gem_
 ```
 
 #### Minimal Footer
+
 ```markdown
 ---
-*Generated by ClassMetrix*
+
+_Generated by ClassMetrix_
 ```
 
 #### Detailed Footer
+
 ```markdown
 ---
+
 ## Report Information
 
 - **Generated by**: [ClassMetrix gem](https://github.com/patrick204nqh/class-metrix)
@@ -310,18 +330,22 @@ ClassMetrix.extract(:constants)
 ### Missing Behaviors Styles
 
 #### Grouped (Default)
+
 ```markdown
 ## Missing Behaviors Summary
 
 ### DatabaseConfig
+
 - `redis_config` - 🚫 Not defined
 - `cache_timeout` - 🚫 No method
 
-### RedisConfig  
+### RedisConfig
+
 - `db_config` - 🚫 Not defined
 ```
 
 #### Flat
+
 ```markdown
 ## Missing Behaviors
 
@@ -331,22 +355,26 @@ ClassMetrix.extract(:constants)
 ```
 
 #### Detailed
+
 ```markdown
 ## Missing Behaviors Analysis
 
 **Summary**: 3 missing behaviors across 2 classes
 
 ### 🚫 Not (2 items)
+
 - **DatabaseConfig**: `redis_config` - 🚫 Not defined
 - **RedisConfig**: `db_config` - 🚫 Not defined
 
 ### 🚫 No (1 items)
+
 - **DatabaseConfig**: `cache_timeout` - 🚫 No method
 ```
 
 ## 🎯 Real-World Examples
 
 ### Microservices Configuration Audit
+
 ```ruby
 # Audit configuration consistency across services
 services = [DatabaseService, RedisService, S3Service, AuthService]
@@ -365,6 +393,7 @@ ClassMetrix.extract(:constants, :class_methods)
 ```
 
 ### Policy Classes Comparison
+
 ```ruby
 # Compare authorization policies
 policies = [UserPolicy, AdminPolicy, ModeratorPolicy]
@@ -379,6 +408,7 @@ ClassMetrix.extract(:constants)
 ```
 
 ### API Version Compatibility
+
 ```ruby
 # Check API compatibility across versions
 apis = [V1::UsersAPI, V2::UsersAPI, V3::UsersAPI]
@@ -401,7 +431,7 @@ ClassMetrix uses a modular component architecture for maximum flexibility:
 ```
 MarkdownFormatter
 ├── HeaderComponent      # Title, classes, extraction info
-├── TableComponent       # Table formatting and hash expansion  
+├── TableComponent       # Table formatting and hash expansion
 ├── MissingBehaviorsComponent  # Missing behavior analysis
 └── FooterComponent      # Footer with various styles
 ```
@@ -428,7 +458,7 @@ ruby examples/advanced/hash_expansion.rb
 
 ## 📋 Requirements
 
-- Ruby 2.7+ 
+- Ruby 2.7+
 - No runtime dependencies (pure Ruby implementation)
 
 ## 🤝 Contributing

data/Steepfile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Steepfile for ClassMetrix gem
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  # Configure libraries
+  library "pathname"
+  library "csv"
+  library "json"
+  library "fileutils"
+
+  # Configure typing options
+  configure_code_diagnostics(D::Ruby.default)
+
+  # Disable some noisy diagnostics for better development experience
+  configure_code_diagnostics do |hash|
+    hash[D::Ruby::UnresolvedOverloading] = :information
+    hash[D::Ruby::FallbackAny] = :information
+    hash[D::Ruby::ImplicitBreakValueMismatch] = :hint
+  end
+end

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
+```

data/lib/class_metrix/extractor.rb

@@ -48,7 +48,7 @@ module ClassMetrix
       @debug_mode = true
       @debug_level = level
       @logger = Utils::DebugLogger.new("Extractor", @debug_mode, level)
-      @logger.log("Debug mode enabled (level: #{level})")
+      @logger&.log("Debug mode enabled (level: #{level})")
       self
     end
 

data/lib/class_metrix/extractors/constants_extractor.rb

@@ -108,7 +108,7 @@ module ClassMetrix
     end
 
     def get_all_included_modules(klass)
-      modules = []
+      modules = [] # : Array[Module]
       modules.concat(klass.included_modules)
 
       if @options[:include_inherited]

data/lib/class_metrix/extractors/methods_extractor.rb

@@ -115,7 +115,7 @@ module ClassMetrix
     end
 
     def get_all_singleton_modules(klass)
-      modules = []
+      modules = [] # : Array[Module]
       modules.concat(klass.singleton_class.included_modules)
 
       if @options[:include_inherited]

data/lib/class_metrix/extractors/multi_type_extractor.rb

@@ -20,7 +20,7 @@ module ClassMetrix
       # Build headers: ["Type", "Behavior", "Class1", "Class2", ...]
       headers = %w[Type Behavior] + @classes.map(&:name)
 
-      all_rows = []
+      all_rows = [] # : Array[Array[untyped]]
 
       @types.each do |type|
         type_data = extract_single_type(type)
@@ -28,7 +28,7 @@ module ClassMetrix
         # Add rows with type prefix
         type_data[:rows].each do |row|
           behavior_name = row[0]
-          values = row[1..]
+          values = row[1..] || []
 
           new_row = [type_label(type), behavior_name] + values
           all_rows << new_row

data/lib/class_metrix/formatters/base/base_formatter.rb

@@ -26,7 +26,7 @@ module ClassMetrix
             # Common options for all formatters
             title: nil,
             show_metadata: true,
-            extraction_types: []
+            extraction_types: [] # : Array[Symbol]
           }
         end
 
@@ -52,11 +52,11 @@ module ClassMetrix
 
         def collect_all_hash_keys(rows, _headers)
           value_start_idx = value_start_index
-          all_keys = {} # behavior_name => Set of keys
+          all_keys = {} # : Hash[String, Set[String]] # behavior_name => Set of keys
 
           rows.each do |row|
             behavior_name = row[behavior_column_index]
-            values = row[value_start_idx..]
+            values = row[value_start_idx..] || []
 
             values.each do |value|
               if value.is_a?(Hash)

data/lib/class_metrix/formatters/components/footer_component.rb

@@ -16,7 +16,7 @@ module ClassMetrix
         def generate
           return [] unless @show_footer
 
-          output = []
+          output = [] # : Array[String]
 
           # Add separator line
           output << "---" if @show_separator
@@ -36,7 +36,7 @@ module ClassMetrix
         private
 
         def generate_default_footer
-          output = []
+          output = [] # : Array[String]
 
           output << (@custom_footer || "*Report generated by ClassMetrix gem*")
 
@@ -49,7 +49,7 @@ module ClassMetrix
         end
 
         def generate_detailed_footer
-          output = []
+          output = [] # : Array[String]
 
           output << "## Report Information"
           output << ""

data/lib/class_metrix/formatters/components/generic_header_component.rb

@@ -30,7 +30,7 @@ module ClassMetrix
         private
 
         def generate_markdown_header
-          output = []
+          output = [] # : Array[String]
 
           # Add title
           if @title
@@ -58,7 +58,7 @@ module ClassMetrix
         end
 
         def generate_csv_header
-          output = []
+          output = [] # : Array[String]
           comment_char = @options.fetch(:comment_char, "#")
 
           # Add title as comment

data/lib/class_metrix/formatters/components/header_component.rb

@@ -15,7 +15,7 @@ module ClassMetrix
         end
 
         def generate
-          output = []
+          output = [] # : Array[String]
 
           # Add title
           output.concat(generate_title) if @title || @show_metadata
@@ -32,7 +32,7 @@ module ClassMetrix
         private
 
         def generate_title
-          output = []
+          output = [] # : Array[String]
 
           if @title
             output << "# #{@title}"
@@ -46,7 +46,7 @@ module ClassMetrix
         end
 
         def generate_classes_section
-          output = []
+          output = [] # : Array[String]
 
           has_type_column = @data[:headers].first == "Type"
           class_headers = if has_type_column
@@ -66,7 +66,7 @@ module ClassMetrix
         end
 
         def generate_extraction_info
-          output = []
+          output = [] # : Array[String]
 
           output << "## Extraction Types"
           output << ""

data/lib/class_metrix/formatters/components/missing_behaviors_component.rb

@@ -9,7 +9,7 @@ module ClassMetrix
           @options = options
           @show_missing_summary = options.fetch(:show_missing_summary, false)
           @summary_style = options.fetch(:summary_style, :grouped) # :grouped, :flat, :detailed
-          @missing_behaviors = {}
+          @missing_behaviors = {} # : Hash[String, Hash[String, String]]
         end
 
         def generate
@@ -30,7 +30,7 @@ module ClassMetrix
                           end
 
           # Initialize missing behaviors tracking with hash to store behavior name and error message
-          class_headers.each { |class_name| @missing_behaviors[class_name] = {} }
+          class_headers.each { |class_name| @missing_behaviors[class_name] = {} } # : Hash[String, Hash[String, String]]
 
           @data[:rows].each do |row|
             behavior_name = has_type_column ? row[1] : row[0]
@@ -63,7 +63,7 @@ module ClassMetrix
         end
 
         def generate_grouped_summary
-          output = []
+          output = [] # : Array[String]
 
           output << "## Missing Behaviors Summary"
           output << ""
@@ -84,12 +84,12 @@ module ClassMetrix
         end
 
         def generate_flat_summary
-          output = []
+          output = [] # : Array[String]
 
           output << "## Missing Behaviors"
           output << ""
 
-          all_missing = []
+          all_missing = [] # : Array[String]
           @missing_behaviors.each do |class_name, behaviors_hash|
             behaviors_hash.each do |behavior_name, error_message|
               all_missing << "- **#{class_name}**: `#{behavior_name}` - #{error_message}"
@@ -103,7 +103,7 @@ module ClassMetrix
         end
 
         def generate_detailed_summary
-          output = []
+          output = [] # : Array[String]
 
           total_missing = @missing_behaviors.values.map(&:size).sum
           total_classes = @missing_behaviors.keys.size
@@ -114,7 +114,7 @@ module ClassMetrix
           output << ""
 
           # Group by error type
-          by_error_type = {}
+          by_error_type = {} # : Hash[String, Array[Hash[Symbol, String]]]
           @missing_behaviors.each do |class_name, behaviors_hash|
             behaviors_hash.each do |behavior_name, error_message|
               error_type = error_message.split.first(2).join(" ") # e.g., "🚫 Not", "⚠️ Error:"

data/lib/class_metrix/formatters/components/table_component/row_processor.rb

@@ -16,7 +16,8 @@ module ClassMetrix
           def process_simple_rows(rows)
             rows.map do |row|
               processed_row = [row[0]] # Keep the behavior name as-is
-              row[1..].each do |value|
+              rest_values = row[1..] || []
+              rest_values.each do |value|
                 processed_row << ValueProcessor.process(value)
               end
               processed_row
@@ -24,7 +25,7 @@ module ClassMetrix
           end
 
           def process_expanded_rows(rows)
-            expanded_rows = []
+            expanded_rows = [] # : Array[Array[String]]
 
             rows.each do |row|
               if @data_extractor.row_has_expandable_hash?(row)
@@ -41,9 +42,11 @@ module ClassMetrix
 
           def process_non_hash_row(row)
             if @data_extractor.has_type_column?
-              [row[0], row[1]] + row[2..].map { |value| ValueProcessor.process(value) }
+              rest_values = row[2..] || []
+              [row[0], row[1]] + rest_values.map { |value| ValueProcessor.process(value) }
             else
-              [row[0]] + row[1..].map { |value| ValueProcessor.process(value) }
+              rest_values = row[1..] || []
+              [row[0]] + rest_values.map { |value| ValueProcessor.process(value) }
             end
           end
 
@@ -57,7 +60,7 @@ module ClassMetrix
           end
 
           def build_expanded_rows(row_data, all_hash_keys, original_row)
-            expanded_rows = []
+            expanded_rows = [] # : Array[Array[String]]
 
             # Add main row if configured to show
             expanded_rows << build_main_expanded_row(row_data) if should_show_main_row?

data/lib/class_metrix/formatters/components/table_component/table_data_extractor.rb

@@ -37,7 +37,10 @@ module ClassMetrix
           end
 
           def row_has_expandable_hash?(row)
-            row[value_start_index..].any? { |cell| cell.is_a?(Hash) }
+            values = row[value_start_index..] || []
+            return false if values.nil?
+
+            values.any? { |cell| cell.is_a?(Hash) }
           end
 
           def collect_hash_keys(values)

data/lib/class_metrix/formatters/components/table_component/table_renderer.rb

@@ -11,7 +11,7 @@ module ClassMetrix
           end
 
           def render_table(headers, rows, column_widths)
-            output = []
+            output = [] # : Array[String]
             output << build_row(headers, column_widths)
             output << build_separator(column_widths)
 
@@ -19,7 +19,7 @@ module ClassMetrix
               output << build_row(row, column_widths)
             end
 
-            output.join("\n")
+            output
           end
 
           private