class-metrix 0.1.2

data/RELEASE_GUIDE.md

@@ -0,0 +1,158 @@
+# Release Guide
+
+This guide explains how to release new versions of the ClassMetrix gem.
+
+## 🚀 Quick Release
+
+For a simple patch release:
+
+```bash
+# Using the release script (recommended)
+./bin/release --type patch --push
+
+# Or manually
+./bin/release --type patch
+# Then follow the printed instructions to commit and push
+```
+
+## 📋 Prerequisites
+
+Before creating a release, ensure you have:
+
+1. **RubyGems API Key**: Set up in GitHub repository secrets as `RUBYGEMS_API_KEY`
+2. **Clean working directory**: All changes committed
+3. **Tests passing**: Run `bundle exec rake` to verify
+4. **Updated documentation**: Ensure README and docs are current
+
+## 🛠️ Release Process
+
+### 1. Using the Release Script (Recommended)
+
+The `bin/release` script automates version bumping and changelog updates:
+
+```bash
+# Patch release (0.1.0 → 0.1.1)
+./bin/release --type patch
+
+# Minor release (0.1.0 → 0.2.0)  
+./bin/release --type minor
+
+# Major release (0.1.0 → 1.0.0)
+./bin/release --type major
+
+# Dry run to see what would happen
+./bin/release --type patch --dry-run
+
+# Automatic commit and push
+./bin/release --type patch --push
+```
+
+### 2. Manual Release Process
+
+If you prefer to do it manually:
+
+1. **Update Version**:
+   ```ruby
+   # lib/class_metrix/version.rb
+   module ClassMetrix
+     VERSION = "0.1.1"  # Increment appropriately
+   end
+   ```
+
+2. **Update CHANGELOG.md**:
+   ```markdown
+   ## [Unreleased]
+
+   ## [0.1.1] - 2024-01-15
+   ### Fixed
+   - Bug fixes and improvements
+   ```
+
+3. **Commit and Tag**:
+   ```bash
+   git add -A
+   git commit -m "Release v0.1.1"
+   git tag v0.1.1
+   git push origin master
+   git push origin v0.1.1
+   ```
+
+## 🤖 Automated Release Workflow
+
+When you push a tag (e.g., `v0.1.1`), GitHub Actions automatically:
+
+1. **Runs tests** across Ruby 3.1, 3.2, and 3.3
+2. **Verifies version consistency** between tag and gemspec
+3. **Builds the gem**
+4. **Publishes to RubyGems**
+5. **Creates a GitHub Release**
+
+### Workflow Files
+
+- **`.github/workflows/main.yml`**: CI pipeline for PRs and pushes
+- **`.github/workflows/release.yml`**: Release automation for tags
+
+## 🔑 Setting Up RubyGems API Key
+
+1. **Generate API Key**:
+   ```bash
+   gem signin
+   # Get your API key from ~/.gem/credentials
+   ```
+
+2. **Add to GitHub Secrets**:
+   - Go to your repo → Settings → Secrets and variables → Actions
+   - Add secret named `RUBYGEMS_API_KEY`
+   - Paste your API key as the value
+
+## 📊 Release Checklist
+
+Before each release:
+
+- [ ] All tests pass (`bundle exec rake`)
+- [ ] RuboCop passes (`bundle exec rubocop`)
+- [ ] Documentation is updated
+- [ ] CHANGELOG.md reflects new changes
+- [ ] Version is bumped appropriately
+- [ ] No TODO items in gemspec
+- [ ] GitHub secrets are configured
+
+## 🐛 Troubleshooting
+
+### Version Mismatch Error
+
+If the workflow fails with a version mismatch:
+
+```
+Version mismatch! Gemspec: 0.1.0, Tag: 0.1.1
+```
+
+Ensure the version in `lib/class_metrix/version.rb` matches your git tag.
+
+### RubyGems Push Failed
+
+Check that:
+1. `RUBYGEMS_API_KEY` secret is set correctly
+2. You have push permissions for the gem
+3. The version doesn't already exist on RubyGems
+
+### GitHub Release Failed
+
+Ensure the `GITHUB_TOKEN` has sufficient permissions (this is usually automatic).
+
+## 📈 Semantic Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **PATCH** (`0.1.0` → `0.1.1`): Bug fixes, documentation updates
+- **MINOR** (`0.1.0` → `0.2.0`): New features, backwards compatible
+- **MAJOR** (`0.1.0` → `1.0.0`): Breaking changes
+
+## 🎯 Post-Release
+
+After a successful release:
+
+1. **Verify on RubyGems**: Check that the new version appears on [rubygems.org](https://rubygems.org/gems/class-metrix)
+2. **Test installation**: `gem install class-metrix -v X.X.X`
+3. **Update dependencies**: In projects using the gem
+4. **Announce**: Consider announcements on relevant channels 

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/README.md

@@ -0,0 +1,155 @@
+# ClassMetrix Examples
+
+This directory contains comprehensive examples demonstrating all features of the ClassMetrix gem, organized from basic to advanced real-world scenarios.
+
+## 🎯 Quick Start
+
+If you're new to ClassMetrix, start with the basic 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
+```
+
+## 📁 Directory Structure
+
+### `/basic/` - Getting Started
+Perfect for learning the core concepts and API.
+
+- **`01_simple_constants.rb`** - Extract and compare constants across classes
+  - Basic constant extraction
+  - Filtering with regex and strings
+  - Understanding the output format
+
+- **`02_simple_methods.rb`** - Extract and compare class methods
+  - Class method extraction
+  - Handling different return types (strings, numbers, booleans, arrays)
+  - Method filtering techniques
+
+- **`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/` - Powerful Features
+Advanced features for complex scenarios.
+
+- **`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
+
+- **`error_handling.rb`** - Graceful error handling
+  - Methods that raise exceptions
+  - Missing constants and methods
+  - Boolean and nil value processing
+  - Error indicators and recovery
+
+### `/real_world/` - Production Examples
+Real-world scenarios you might encounter.
+
+- **`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
+
+## 🚀 Running Examples
+
+Each example is self-contained and can be run independently:
+
+```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
+```
+
+## 📊 Example Output
+
+All examples generate markdown tables that look like this:
+
+```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           |
+```
+
+With hash expansion:
+```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           |
+```
+
+## 🛠️ 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
+```
+
+## 📝 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
+
+## 🎓 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
+
+- **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
+
+## 🤝 Contributing Examples
+
+Have a great ClassMetrix use case? Consider contributing an example!
+
+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
+
+Happy analyzing! 🎉 

data/examples/advanced/error_handling.rb

@@ -0,0 +1,199 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/class_metrix"
+
+puts "=== Advanced Example: Error Handling ==="
+puts
+
+# Classes that demonstrate various error scenarios
+class WorkingService
+  # Working constants
+  SERVICE_NAME = "working"
+  VERSION = "1.0.0"
+  ENABLED = true
+
+  # Working methods
+  def self.status
+    "healthy"
+  end
+
+  def self.version
+    "1.0.0"
+  end
+
+  def self.health_check
+    { status: "ok", uptime: 12_345 }
+  end
+
+  def self.enabled?
+    true
+  end
+end
+
+class PartiallyBrokenService
+  # Working constants
+  SERVICE_NAME = "partially_broken"
+  VERSION = "0.9.0"
+  # Missing ENABLED constant
+
+  # Working methods
+  def self.status
+    "degraded"
+  end
+
+  def self.version
+    "0.9.0"
+  end
+
+  # Broken method that raises an error
+  def self.health_check
+    raise StandardError, "Health check failed!"
+  end
+
+  def self.enabled?
+    false
+  end
+
+  # Method that returns nil
+  def self.uptime
+    nil
+  end
+
+  # Method with complex error
+  def self.database_connection
+    raise ActiveRecord::ConnectionNotEstablished, "Database unavailable"
+  rescue NameError
+    # If ActiveRecord is not available, raise a different error
+    raise "Connection library not available"
+  end
+end
+
+class CompletelyBrokenService
+  # Has some constants
+  SERVICE_NAME = "broken"
+  # Missing VERSION and ENABLED
+
+  # Has working method
+  def self.status
+    "down"
+  end
+
+  # Missing version method
+
+  # Broken health_check
+  def self.health_check
+    raise NoMethodError, "Health monitoring not implemented"
+  end
+
+  # Method that raises during execution
+  def self.enabled?
+    some_undefined_variable.call
+  end
+
+  # Method that returns false
+  def self.deprecated?
+    true
+  end
+end
+
+puts "=== Service Classes Defined ==="
+puts "WorkingService: All methods work"
+puts "PartiallyBrokenService: Some methods fail"
+puts "CompletelyBrokenService: Most methods fail"
+puts
+
+# 1. Extract without error handling (will raise errors)
+puts "💥 1. WITHOUT ERROR HANDLING (This will show errors)"
+puts "-" * 60
+
+begin
+  result = ClassMetrix.extract(:class_methods)
+                      .from([WorkingService, PartiallyBrokenService])
+                      .filter(/health_check/)
+                      .to_markdown
+  puts result
+rescue StandardError => e
+  puts "❌ Error occurred: #{e.class.name}: #{e.message}"
+end
+puts
+
+# 2. Extract with error handling
+puts "🛡️ 2. WITH ERROR HANDLING (Graceful failure)"
+puts "-" * 60
+result = ClassMetrix.extract(:class_methods)
+                    .from([WorkingService, PartiallyBrokenService, CompletelyBrokenService])
+                    .handle_errors
+                    .to_markdown
+
+puts result
+puts
+
+# 3. Constants with missing values
+puts "📋 3. CONSTANTS WITH MISSING VALUES"
+puts "-" * 60
+result = ClassMetrix.extract(:constants)
+                    .from([WorkingService, PartiallyBrokenService, CompletelyBrokenService])
+                    .handle_errors
+                    .to_markdown
+
+puts result
+puts
+
+# 4. Multi-type extraction with errors
+puts "📊 4. MULTI-TYPE WITH ERROR HANDLING"
+puts "-" * 60
+result = ClassMetrix.extract(:constants, :class_methods)
+                    .from([WorkingService, PartiallyBrokenService, CompletelyBrokenService])
+                    .filter(/SERVICE_NAME|status|enabled/)
+                    .handle_errors
+                    .to_markdown
+
+puts result
+puts
+
+# 5. Focus on problematic methods
+puts "🔍 5. PROBLEMATIC METHODS ANALYSIS"
+puts "-" * 60
+result = ClassMetrix.extract(:class_methods)
+                    .from([WorkingService, PartiallyBrokenService, CompletelyBrokenService])
+                    .filter(/health_check|database|uptime/)
+                    .handle_errors
+                    .to_markdown
+
+puts result
+puts
+
+# 6. Boolean and nil value handling
+puts "✅ 6. BOOLEAN AND NIL VALUE HANDLING"
+puts "-" * 60
+result = ClassMetrix.extract(:class_methods)
+                    .from([WorkingService, PartiallyBrokenService, CompletelyBrokenService])
+                    .filter(/enabled\?|deprecated\?|uptime/)
+                    .handle_errors
+                    .to_markdown
+
+puts result
+puts
+
+# 7. Save comprehensive error analysis report
+puts "💾 7. SAVING COMPREHENSIVE ERROR ANALYSIS REPORT"
+puts "-" * 60
+report = ClassMetrix.extract(:constants, :class_methods)
+                    .from([WorkingService, PartiallyBrokenService, CompletelyBrokenService])
+                    .handle_errors
+                    .to_markdown("error_analysis_report.md", title: "Service Health Analysis Report")
+
+puts "✅ Comprehensive error analysis saved to: error_analysis_report.md"
+puts "📊 Report contains #{report.lines.count} lines with rich metadata"
+puts
+
+puts "🛡️ Enhanced Error Handling Features Demonstrated:"
+puts "• 🚫 Missing constants: '🚫 Not defined'"
+puts "• 🚫 Missing methods: '🚫 No method'"
+puts "• ⚠️ Runtime errors: '⚠️ Error: [descriptive message]'"
+puts "• ❌ Boolean false and nil values: '❌'"
+puts "• ✅ Boolean true values: '✅'"
+puts "• 📊 Rich markdown reports with titles and metadata"
+puts "• 📋 Missing behaviors summary per class"
+puts "• 🛡️ handle_errors flag enables graceful degradation"

data/examples/advanced/hash_expansion.rb

@@ -0,0 +1,180 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../../lib/class_metrix"
+
+puts "=== Advanced Example: Hash Expansion ==="
+puts
+
+# Configuration classes with complex hash structures
+class DatabaseConfig
+  # Hash constants
+  DEFAULT_CONFIG = {
+    host: "localhost",
+    port: 5432,
+    ssl: true,
+    pool_size: 5
+  }.freeze
+
+  CONNECTION_POOLS = {
+    read: { size: 10, timeout: 30 },
+    write: { size: 5, timeout: 15 },
+    admin: { size: 2, timeout: 60 }
+  }.freeze
+
+  # Hash methods
+  def self.production_config
+    {
+      host: "db.production.com",
+      port: 5432,
+      database: "myapp_production",
+      ssl: true,
+      pool_size: 20,
+      timeout: 30,
+      backup_enabled: true
+    }
+  end
+
+  def self.development_config
+    {
+      host: "localhost",
+      port: 5432,
+      database: "myapp_development",
+      ssl: false,
+      pool_size: 5,
+      timeout: 10
+    }
+  end
+
+  def self.simple_value
+    "not a hash"
+  end
+end
+
+class RedisConfig
+  # Hash constants
+  DEFAULT_CONFIG = {
+    host: "localhost",
+    port: 6379,
+    ssl: false,
+    timeout: 5
+  }.freeze
+
+  CLUSTER_CONFIG = {
+    nodes: 3,
+    replication: true,
+    failover: "auto"
+  }.freeze
+
+  # Hash methods
+  def self.production_config
+    {
+      host: "redis.internal",
+      port: 6379,
+      database: 0,
+      ssl: false,
+      max_connections: 100,
+      cluster_enabled: true
+    }
+  end
+
+  def self.development_config
+    {
+      host: "localhost",
+      port: 6379,
+      database: 1,
+      ssl: false,
+      max_connections: 10
+    }
+  end
+
+  def self.simple_value
+    42
+  end
+end
+
+puts "=== Configuration Classes Defined ==="
+puts "DatabaseConfig and RedisConfig with hash constants and methods"
+puts
+
+# 1. Normal output (without expansion)
+puts "📋 1. NORMAL OUTPUT (Hashes as inspect strings)"
+puts "-" * 60
+result = ClassMetrix.extract(:class_methods)
+                    .from([DatabaseConfig, RedisConfig])
+                    .filter(/config$/)
+                    .to_markdown
+
+puts result
+puts
+
+# 2. Expanded output
+puts "🔍 2. EXPANDED OUTPUT (Hash keys as sub-rows)"
+puts "-" * 60
+result = ClassMetrix.extract(:class_methods)
+                    .from([DatabaseConfig, RedisConfig])
+                    .filter(/config$/)
+                    .expand_hashes
+                    .to_markdown
+
+puts result
+puts
+
+# 3. Constants with expansion
+puts "📊 3. CONSTANTS WITH HASH EXPANSION"
+puts "-" * 60
+result = ClassMetrix.extract(:constants)
+                    .from([DatabaseConfig, RedisConfig])
+                    .filter(/CONFIG/)
+                    .expand_hashes
+                    .handle_errors
+                    .to_markdown
+
+puts result
+puts
+
+# 4. Mixed data types with expansion
+puts "🔧 4. MIXED DATA TYPES WITH EXPANSION"
+puts "-" * 60
+result = ClassMetrix.extract(:class_methods)
+                    .from([DatabaseConfig, RedisConfig])
+                    .expand_hashes
+                    .to_markdown
+
+puts result
+puts
+
+# 5. Multi-type extraction with expansion
+puts "🚀 5. MULTI-TYPE WITH HASH EXPANSION"
+puts "-" * 60
+result = ClassMetrix.extract(:constants, :class_methods)
+                    .from([DatabaseConfig, RedisConfig])
+                    .filter(/DEFAULT_CONFIG|production_config/)
+                    .expand_hashes
+                    .handle_errors
+                    .to_markdown
+
+puts result
+puts
+
+# 6. Save expanded report
+puts "💾 6. SAVING EXPANDED REPORT"
+puts "-" * 60
+report = ClassMetrix.extract(:constants, :class_methods)
+                    .from([DatabaseConfig, RedisConfig])
+                    .expand_hashes
+                    .handle_errors
+                    .to_markdown("config_analysis_expanded.md")
+
+puts "✅ Expanded report saved to: config_analysis_expanded.md"
+puts "📊 Report contains #{report.lines.count} lines"
+puts
+
+puts "✨ Hash Expansion Features Demonstrated:"
+puts "• 📋 Hash indicators show number of keys"
+puts "• └─ Sub-rows show individual key-value pairs"
+puts "• ❌ Missing keys shown clearly"
+puts "• — Non-hash values shown with dash"
+puts "• Mixed data types handled properly"
+puts "• Works with both constants and methods"
+puts "• Compatible with multi-type extraction"