class-metrix 0.1.2 → 1.0.1

data/CHANGELOG.md

@@ -5,20 +5,88 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2025-06-07
+## [Unreleased]
+
+## [1.0.1] - 2025-06-08
+
+## [1.0.0] - 2025-06-07
+
+### 🎉 Major Release - Production Ready
+
+This marks the first stable release of ClassMetrix with a comprehensive feature set and robust architecture.
+
+### Added
+
+- **🐛 Advanced Debug System**: Comprehensive debug logging with three levels (`:basic`, `:detailed`, `:verbose`)
+  - Safe object inspection for problematic objects with broken `inspect`/`to_s` methods
+  - Smart hash detection to prevent issues with proxy objects
+  - Component-specific debug loggers for targeted troubleshooting
+  - Error-resistant operations with graceful degradation
+- **📊 Enhanced Hash Expansion**: Multiple hash expansion modes for different analysis needs
+  - `show_only_main`: Show collapsed hash representations (default)
+  - `show_only_keys`: Show only expanded key rows for detailed analysis
+  - `show_expanded_details`: Show both main and expanded rows
+  - Support for nested hash structures with proper truncation
+- **🏗️ Refactored Architecture**: Clean separation of concerns and improved maintainability
+  - Modular extractor system with dedicated extractors for each type
+  - Shared table builders for consistent formatting across output formats
+  - Centralized value processor for robust value handling
+  - Component-based formatter architecture
+- **⚙️ Enhanced Configuration**: More granular control over extraction and formatting
+  - Hash expansion display options (`hide_main_row`, `hide_key_rows`)
+  - Improved inheritance and module inclusion handling
+  - Better error handling and recovery mechanisms
+- **🔧 VS Code Integration**: Complete development environment setup
+  - Auto-formatting with Rubocop integration
+  - Task definitions for common operations
+  - Debug configurations for Ruby and RSpec
+  - Recommended extensions for optimal development experience
+
+### Enhanced
+
+- **Hash Processing**: Robust handling of complex nested structures and edge cases
+- **CSV Export**: Improved hash flattening with better column organization
+- **Error Handling**: More resilient extraction with detailed error reporting
+- **Performance**: Optimized table building and value processing
+- **Documentation**: Comprehensive examples and architecture documentation
+
+### Fixed
+
+- Parameter list optimization in `MultiTypeExtractor` (reduced from 6 to 5 parameters)
+- Method length optimization in `ValueProcessor.process_for_csv` (reduced from 28 to 25 lines)
+- Improved hash detection to prevent issues with ActiveRecord and other proxy objects
+- Better handling of objects with problematic method behaviors
+
+### Technical Improvements
+
+- **Safety-First Design**: All operations wrapped with exception handling
+- **Debug Integration**: Every component includes comprehensive debug logging
+- **Type Safety**: Strict hash detection prevents issues with duck-typed objects
+- **Modular Design**: Easy to extend with new extraction types and formatters
+- **Test Coverage**: Extensive test suite covering edge cases and error conditions
+
+### Breaking Changes
+
+- Hash expansion now defaults to `show_only_main` (was `show_expanded_details`)
+- Some internal API changes for better consistency (affects custom extensions)
+
+## [0.1.2] - 2025-06-07
 
 ### Added
+
 - GitHub Actions CI/CD workflow for automated releases
 - Multi-version Ruby testing (3.1, 3.2, 3.3)
 - Automated gem publishing to RubyGems
 - Version consistency checking
 
 ### Changed
+
 - Improved CI workflow with better test coverage
 
-## [0.1.0] - 2024-01-XX
+## [0.1.0] - 2025-06-07
 
 ### Added
+
 - Initial release of ClassMetrix
 - Constants extraction from Ruby classes
 - Class methods extraction and comparison
@@ -32,10 +100,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - RuboCop integration
 
 ### 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
 - 📝 Rich Markdown Reports: Professional reports with configurable components
 - 📄 CSV Export: Data analysis-friendly CSV output with hash flattening
 - ⚙️ Highly Configurable: Customize every aspect of the output
-- 🚀 Simple API: Chainable, intuitive interface 
+- 🚀 Simple API: Chainable, intuitive interface

data/README.md

@@ -5,11 +5,14 @@
 
 **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
 - **📄 CSV Export**: Data analysis-friendly CSV output with hash flattening
 - **⚙️ Highly Configurable**: Customize every aspect of the output
@@ -29,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
@@ -39,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
   )
@@ -64,6 +67,7 @@ gem install class-metrix
 ### Basic Extraction
 
 #### Constants
+
 ```ruby
 # Extract constants from multiple classes
 ClassMetrix.extract(:constants)
@@ -78,6 +82,7 @@ ClassMetrix.extract(:constants)
 ```
 
 #### Class Methods
+
 ```ruby
 # Extract class method results
 ClassMetrix.extract(:class_methods)
@@ -93,6 +98,7 @@ ClassMetrix.extract(:class_methods)
 ```
 
 #### Multi-Type Extraction
+
 ```ruby
 # Combine multiple extraction types in one table
 ClassMetrix.extract(:constants, :class_methods)
@@ -109,6 +115,7 @@ ClassMetrix.extract(:constants, :class_methods)
 ### Advanced Features
 
 #### Hash Expansion
+
 ```ruby
 # Expand hash values into readable sub-rows
 ClassMetrix.extract(:constants)
@@ -126,6 +133,7 @@ ClassMetrix.extract(:constants)
 ```
 
 #### Error Handling
+
 ```ruby
 # Handle missing methods and constants gracefully
 ClassMetrix.extract(:class_methods)
@@ -143,6 +151,7 @@ ClassMetrix.extract(:class_methods)
 ```
 
 #### Filtering
+
 ```ruby
 # Filter behaviors by pattern
 ClassMetrix.extract(:constants)
@@ -157,7 +166,48 @@ ClassMetrix.extract(:class_methods)
   .to_markdown
 ```
 
+#### Debug Mode
+
+```ruby
+# Enable detailed logging for troubleshooting
+ClassMetrix.extract(:constants, :class_methods)
+  .from([ServiceA, ServiceB])
+  .expand_hashes
+  .debug  # Enable debug mode (basic level)
+  .to_markdown("debug_report.md")
+
+# Different debug levels for different needs
+ClassMetrix.extract(:constants)
+  .from([ServiceA, ServiceB])
+  .debug(:basic)    # Key decisions and summaries only
+  .to_markdown
+
+ClassMetrix.extract(:constants)
+  .from([ServiceA, ServiceB])
+  .debug(:detailed) # More context and intermediate steps
+  .to_markdown
+
+ClassMetrix.extract(:constants)
+  .from([ServiceA, ServiceB])
+  .debug(:verbose)  # Full details including individual value processing
+  .to_markdown
+```
+
+**Debug Levels:**
+
+- **`:basic`** (default) - Key decisions and summaries only
+- **`: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)
@@ -191,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])
@@ -198,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])
@@ -229,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
@@ -248,23 +300,29 @@ 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/your-username/class-metrix)
+- **Generated by**: [ClassMetrix gem](https://github.com/patrick204nqh/class-metrix)
 - **Generated at**: 2024-01-15 14:30:25 UTC
 - **Ruby version**: 3.2.0
 ```
@@ -272,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
 
@@ -293,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]
@@ -327,6 +393,7 @@ ClassMetrix.extract(:constants, :class_methods)
 ```
 
 ### Policy Classes Comparison
+
 ```ruby
 # Compare authorization policies
 policies = [UserPolicy, AdminPolicy, ModeratorPolicy]
@@ -341,6 +408,7 @@ ClassMetrix.extract(:constants)
 ```
 
 ### API Version Compatibility
+
 ```ruby
 # Check API compatibility across versions
 apis = [V1::UsersAPI, V2::UsersAPI, V3::UsersAPI]
@@ -363,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
 ```
@@ -374,7 +442,7 @@ Each component is independently configurable and can be customized for specific
 
 ```bash
 # Clone the repository
-git clone https://github.com/your-username/class-metrix.git
+git clone https://github.com/patrick204nqh/class-metrix.git
 cd class-metrix
 
 # Install dependencies
@@ -390,7 +458,7 @@ ruby examples/advanced/hash_expansion.rb
 
 ## 📋 Requirements
 
-- Ruby 2.7+ 
+- Ruby 2.7+
 - No runtime dependencies (pure Ruby implementation)
 
 ## 🤝 Contributing
@@ -407,11 +475,7 @@ This gem is available as open source under the terms of the [MIT License](LICENS
 
 ## 🔗 Links
 
-- [Documentation](https://github.com/your-username/class-metrix/wiki)
+- [Documentation](https://github.com/patrick204nqh/class-metrix/wiki)
 - [Examples](examples/)
 - [Build Guide](BUILD_GUIDE.md)
 - [Changelog](CHANGELOG.md)
-
----
-
-**Built with ❤️ for Ruby developers who love clean, maintainable code.**

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