class-metrix 0.1.2 → 1.0.0

data/examples/README.md

@@ -1,155 +1,202 @@
 # ClassMetrix Examples
 
-This directory contains comprehensive examples demonstrating all features of the ClassMetrix gem, organized from basic to advanced real-world scenarios.
+This directory contains examples demonstrating ClassMetrix features, from basic usage to advanced inheritance and module analysis.
 
 ## 🎯 Quick Start
 
-If you're new to ClassMetrix, start with the basic examples:
+New to ClassMetrix? Start with these examples:
 
 ```bash
-# Run basic examples in order
-ruby examples/basic/01_simple_constants.rb
-ruby examples/basic/02_simple_methods.rb
-ruby examples/basic/03_multi_type_extraction.rb
+ruby examples/basic_usage.rb              # Basic constants and methods
+ruby examples/inheritance_and_modules.rb  # Inheritance and module analysis
 ```
 
-## 📁 Directory Structure
+## 📁 Available Examples
 
-### `/basic/` - Getting Started
-Perfect for learning the core concepts and API.
+### Core Examples
 
-- **`01_simple_constants.rb`** - Extract and compare constants across classes
-  - Basic constant extraction
-  - Filtering with regex and strings
-  - Understanding the output format
+- **`basic_usage.rb`** - Basic constant and method extraction
+  - Simple class comparison
+  - Filtering and multi-type extraction
+  - Hash expansion basics
 
-- **`02_simple_methods.rb`** - Extract and compare class methods
-  - Class method extraction
-  - Handling different return types (strings, numbers, booleans, arrays)
-  - Method filtering techniques
+- **`inheritance_and_modules.rb`** - Inheritance and module analysis
+  - Class inheritance support
+  - Module inclusion analysis
+  - Combined inheritance and module extraction
 
-- **`03_multi_type_extraction.rb`** - Combine constants and methods in one table
-  - Multi-type extraction with Type column
-  - Comparing constants vs methods with similar names
-  - Understanding behavior differences
+### Advanced Examples
 
-### `/advanced/` - Powerful Features
-Advanced features for complex scenarios.
+- **`csv_output_demo.rb`** - CSV output format demonstration
+- **`/advanced/`** - Complex hash expansion scenarios
+- **`/basic/`** - Step-by-step learning examples
+- **`/real_world/`** - Production use case examples
 
-- **`hash_expansion.rb`** - Hash value expansion into sub-rows
-  - Normal vs expanded hash display
-  - Hash key comparison across classes
-  - Mixed data type handling
-  - Multi-type extraction with expansion
+## 🚀 Core Functionality
 
-- **`error_handling.rb`** - Graceful error handling
-  - Methods that raise exceptions
-  - Missing constants and methods
-  - Boolean and nil value processing
-  - Error indicators and recovery
+### Basic Extraction
 
-### `/real_world/` - Production Examples
-Real-world scenarios you might encounter.
+```ruby
+require_relative "../lib/class_metrix"
 
-- **`microservices_audit.rb`** - Complete microservices configuration audit
-  - Service metadata comparison
-  - Feature flag consistency analysis
-  - Database and cache configuration audits
-  - Performance metrics comparison
-  - Security configuration analysis
+# Extract constants from multiple classes
+ClassMetrix.extract(:constants)
+           .from([User, Admin])
+           .to_markdown
+
+# Extract class methods
+ClassMetrix.extract(:class_methods)
+           .from([DatabaseService, CacheService])
+           .to_markdown
+
+# Combined extraction
+ClassMetrix.extract(:constants, :class_methods)
+           .from([Class1, Class2])
+           .filter(/config/)
+           .to_markdown
+```
 
-## 🚀 Running Examples
+### Inheritance & Module Analysis
 
-Each example is self-contained and can be run independently:
+```ruby
+# Include inherited constants and methods
+ClassMetrix.extract(:constants, :class_methods)
+           .from([ChildClass])
+           .include_inherited
+           .to_markdown
+
+# Include module constants and methods
+ClassMetrix.extract(:constants, :class_methods)
+           .from([ClassWithModules])
+           .include_modules
+           .to_markdown
+
+# Complete analysis: own + inherited + modules
+ClassMetrix.extract(:constants, :class_methods)
+           .from([ComplexClass])
+           .include_all
+           .to_markdown
+```
 
-```bash
-# Run any example directly
-ruby examples/basic/01_simple_constants.rb
-ruby examples/advanced/hash_expansion.rb
-ruby examples/real_world/microservices_audit.rb
+### Advanced Features
+
+```ruby
+# Hash expansion for detailed analysis
+ClassMetrix.extract(:constants, :class_methods)
+           .from([ConfigClass])
+           .expand_hashes
+           .to_markdown
+
+# Hash expansion (main rows only - default)
+ClassMetrix.extract(:class_methods)
+           .from([ServiceClass])
+           .expand_hashes
+           .to_markdown
+
+# Show only key rows (detailed view)
+ClassMetrix.extract(:class_methods)
+           .from([ServiceClass])
+           .expand_hashes
+           .show_only_keys
+           .to_markdown
+
+# Show both main and key rows
+ClassMetrix.extract(:class_methods)
+           .from([ServiceClass])
+           .expand_hashes
+           .show_expanded_details
+           .to_markdown
+
+# Error handling for robust extraction
+ClassMetrix.extract(:class_methods)
+           .from([ClassWithErrors])
+           .handle_errors
+           .to_markdown
+
+# Save to file
+ClassMetrix.extract(:constants)
+           .from([Class1, Class2])
+           .to_markdown("analysis.md")
 ```
 
 ## 📊 Example Output
 
-All examples generate markdown tables that look like this:
-
+### Basic Comparison
 ```markdown
-| Constant     | UserService | OrderService | PaymentService |
-|--------------|-------------|--------------|----------------|
-| SERVICE_NAME | user-service| order-service| payment-service|
-| VERSION      | 2.1.0       | 1.8.5        | 3.0.1          |
-| PORT         | 8001        | 8002         | 8003           |
+| Constant | User    | Admin   |
+|----------|---------|---------|
+| ROLE     | user    | admin   |
+| TIMEOUT  | 3600    | 7200    |
 ```
 
-With hash expansion:
+### With Inheritance
 ```markdown
-| Method         | UserService | OrderService | PaymentService |
-|----------------|-------------|--------------|----------------|
-| database_config| 📋 7 keys   | 📋 8 keys    | 📋 8 keys      |
-|   └─ host      | user-db...  | order-db...  | payment-db...  |
-|   └─ port      | 5432        | 5432         | 5432           |
-|   └─ ssl       | true        | true         | true           |
+| Constant      | DatabaseService | CacheService |
+|---------------|-----------------|--------------|
+| SERVICE_NAME  | database        | cache        |
+| SERVICE_VERSION| 1.0            | 1.0          |
+| DEFAULT_TIMEOUT| 30             | 30           |
 ```
 
-## 🛠️ Building Your Own Examples
-
-Use these examples as templates for your own analysis:
-
-```ruby
-require_relative "../lib/class_metrix"
-
-# Define your classes...
-class MyService
-  CONFIG_SETTING = "value"
-  
-  def self.some_method
-    "result"
-  end
-end
-
-# Extract and compare
-result = ClassMetrix.extract(:constants, :class_methods)
-  .from([MyService, AnotherService])
-  .filter(/CONFIG|method/)
-  .expand_hashes
-  .handle_errors
-  .to_markdown("my_analysis.md")
-
-puts result
+### Hash Expansion
+```markdown
+| Method        | Service1        | Service2        |
+|---------------|-----------------|-----------------|
+| config        | {...}           | {...}           |
+| config.host   | localhost       | production.com  |
+| config.port   | 3000            | 443             |
+| config.ssl    | ❌              | ✅              |
 ```
 
-## 📝 Generated Reports
-
-Many examples save their output to markdown files:
-
-- `config_analysis_expanded.md` - Hash expansion demo output
-- `error_analysis_report.md` - Error handling demo output  
-- `microservices_audit_report.md` - Complete microservices audit
-- `service_analysis_report.md` - Service comparison report
+## 🛠️ API Reference
+
+### Extraction Types
+- `:constants` - Class constants
+- `:class_methods` - Class methods
+
+### Options
+- `.from(classes)` - Classes to analyze (array)
+- `.filter(pattern)` - Filter by name (regex or string)
+- `.include_inherited` - Include parent class behaviors
+- `.include_modules` - Include module behaviors  
+- `.include_all` - Include inherited + modules
+- `.expand_hashes` - Expand hash values (shows main rows by default)
+- `.show_only_main` - Show only main rows (collapsed hashes) - **Default**
+- `.show_only_keys` - Show only key rows (expanded details)
+- `.show_expanded_details` - Show both main and key rows
+- `.handle_errors` - Graceful error handling
+- `.to_markdown(file)` - Generate markdown output
+- `.to_csv(file)` - Generate CSV output
+
+## 💡 Common Use Cases
+
+- **Configuration Analysis** - Compare settings across classes
+- **Inheritance Review** - Analyze class hierarchies
+- **Module Usage Audit** - Track module inclusion patterns
+- **API Comparison** - Compare method signatures
+- **Feature Flag Analysis** - Ensure consistency
+- **Service Configuration** - Microservices governance
 
 ## 🎓 Learning Path
 
-1. **Start with Basic Examples** - Learn the core API and concepts
-2. **Try Advanced Features** - Explore hash expansion and error handling
-3. **Study Real-World Examples** - See practical applications
-4. **Build Your Own** - Apply ClassMetrix to your specific use cases
-
-## 💡 Use Case Ideas
+1. Run `basic_usage.rb` to understand core concepts
+2. Try `inheritance_and_modules.rb` for advanced features
+3. Explore `/basic/` examples for step-by-step learning
+4. Check `/real_world/` for production scenarios
+5. Build custom analysis for your use cases
 
-- **Configuration Management**: Compare settings across environments
-- **API Analysis**: Compare method signatures and return types
-- **Feature Flag Audits**: Ensure consistency across services
-- **Class Architecture Review**: Compare similar classes for consistency
-- **Microservices Governance**: Standardize configurations across services
-- **Legacy Code Analysis**: Understand differences between old and new implementations
+## 📝 Running Examples
 
-## 🤝 Contributing Examples
+```bash
+# Basic functionality
+ruby examples/basic_usage.rb
 
-Have a great ClassMetrix use case? Consider contributing an example!
+# Inheritance and modules
+ruby examples/inheritance_and_modules.rb
 
-1. Create a new file in the appropriate directory
-2. Follow the existing example structure
-3. Include clear comments and output explanations
-4. Add an entry to this README
+# Advanced features
+ruby examples/advanced/hash_expansion.rb
 
-Happy analyzing! 🎉 
+# Real-world scenarios  
+ruby examples/real_world/microservices_audit.rb
+```

data/examples/basic_usage.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/class_metrix"
+
+# Basic Usage Example
+puts "ClassMetrix Basic Usage"
+puts "=" * 30
+
+# Define some simple classes for comparison
+class User
+  ROLE = "user"
+  MAX_LOGIN_ATTEMPTS = 3
+  
+  def self.permissions
+    ["read"]
+  end
+  
+  def self.session_timeout
+    3600
+  end
+end
+
+class Admin
+  ROLE = "admin"
+  MAX_LOGIN_ATTEMPTS = 5
+  
+  def self.permissions
+    ["read", "write", "admin"]
+  end
+  
+  def self.session_timeout
+    7200
+  end
+end
+
+classes = [User, Admin]
+
+# 1. Extract constants
+puts "\n1. Constants Comparison"
+puts "-" * 25
+result = ClassMetrix.extract(:constants)
+                   .from(classes)
+                   .to_markdown
+puts result
+
+# 2. Extract class methods
+puts "\n2. Class Methods Comparison" 
+puts "-" * 25
+result = ClassMetrix.extract(:class_methods)
+                   .from(classes)
+                   .to_markdown
+puts result
+
+# 3. Combined extraction
+puts "\n3. Combined Analysis"
+puts "-" * 25
+result = ClassMetrix.extract(:constants, :class_methods)
+                   .from(classes)
+                   .to_markdown
+puts result
+
+# 4. Filtered analysis
+puts "\n4. Filtered Analysis (ROLE and permissions only)"
+puts "-" * 25
+result = ClassMetrix.extract(:constants, :class_methods)
+                   .from(classes)
+                   .filter(/ROLE|permissions/)
+                   .to_markdown
+puts result
+
+# 5. Hash expansion
+puts "\n5. Hash Expansion Example"
+puts "-" * 25
+
+class ConfigExample
+  SETTINGS = { timeout: 30, retries: 3, ssl: true }.freeze
+  
+  def self.database_config
+    { host: "localhost", port: 5432, pool_size: 5 }
+  end
+end
+
+result = ClassMetrix.extract(:constants, :class_methods)
+                   .from([ConfigExample])
+                   .expand_hashes
+                   .to_markdown
+puts result 

data/examples/debug_levels_demo.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Debug Levels Demonstration
+# Shows the different levels of debug output
+
+require_relative '../lib/class_metrix'
+
+# Example classes
+class ServiceA
+  CONFIG = { host: 'localhost', port: 3000, timeout: 30 }
+  
+  def self.get_settings
+    { cache: true, retries: 3 }
+  end
+end
+
+class ServiceB
+  CONFIG = { host: 'remote', port: 8080 }
+  
+  def self.get_settings
+    { cache: false, retries: 1 }
+  end
+end
+
+puts "=== ClassMetrix Debug Levels Demo ==="
+puts
+
+# Test different debug levels
+levels = [:basic, :detailed, :verbose]
+
+levels.each do |level|
+  puts "\n" + "="*50
+  puts "DEBUG LEVEL: #{level.upcase}"
+  puts "="*50
+  
+  begin
+    result = ClassMetrix.extract(:constants, :class_methods)
+      .from([ServiceA, ServiceB])
+      .expand_hashes
+      .debug(level)  # Set debug level
+      .to_markdown
+      
+    puts "\n--- Result Summary ---"
+    puts "Report generated successfully! ✅"
+    puts "Lines in output: #{result.lines.count}"
+    
+  rescue => e
+    puts "Error: #{e.class}: #{e.message}"
+  end
+  
+  puts "\n"
+end
+
+puts "\n" + "="*50
+puts "DEBUG LEVEL SUMMARY"
+puts "="*50
+puts
+puts ":basic    - Key decisions and summaries only"
+puts ":detailed - More context and intermediate steps"  
+puts ":verbose  - Full details including individual value processing"
+puts
+puts "Use :basic for general troubleshooting"
+puts "Use :detailed for understanding data flow"
+puts "Use :verbose for deep debugging of specific values" 

data/examples/debug_mode_demo.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Debug Mode Demonstration
+# Shows how ClassMetrix handles problematic objects safely
+
+require_relative '../lib/class_metrix'
+
+# Example classes with different types of values
+class SafeService
+  CONFIG = { host: 'localhost', port: 3000 }
+  
+  def self.timeout_config
+    { connect: 30, read: 60 }
+  end
+end
+
+class ProblematicService
+  # This constant is a Class object (not a Hash)
+  CONFIG_CLASS = SafeService
+  
+  def self.service_config
+    SafeService::CONFIG
+  end
+end
+
+# Mock object that has problematic method behavior
+class ProblematicObject
+  def inspect
+    raise "Inspect not allowed!"
+  end
+  
+  def to_s
+    raise "To_s not allowed!"
+  end
+  
+  def class
+    raise "Class not allowed!"
+  end
+end
+
+class WeirdService
+  BROKEN_OBJECT = ProblematicObject.new
+  
+  def self.get_config
+    { normal: 'value', broken: ProblematicObject.new }
+  end
+end
+
+puts "=== ClassMetrix Debug Mode Demo ==="
+puts
+
+puts "This demo shows how ClassMetrix safely handles:"
+puts "1. Class objects in constants"
+puts "2. Objects with broken inspect/to_s methods"
+puts "3. Hash expansion with mixed value types"
+puts
+
+begin
+  result = ClassMetrix.extract(:constants, :class_methods)
+    .from([SafeService, ProblematicService, WeirdService])
+    .expand_hashes
+    .handle_errors
+    .debug  # Enable debug mode
+    .to_markdown
+    
+  puts "\n=== Generated Report ==="
+  puts result[0..500] + "..." if result.length > 500
+  puts "\nReport generated successfully! ✅"
+  puts "Note: Debug output above shows how problematic objects were handled safely."
+  
+rescue => e
+  puts "Error: #{e.class}: #{e.message}"
+  puts "This should not happen with the safety improvements!"
+end