class-metrix 1.0.0 → 1.1.0

data/docs/SLACK_INTEGRATION.md

@@ -0,0 +1,227 @@
+# Slack Integration for ClassMetrix CI/CD
+
+This document explains how to set up Slack notifications for ClassMetrix GitHub Actions workflows.
+
+## Overview
+
+ClassMetrix uses Slack notifications to keep your team informed about CI/CD pipeline status. The integration provides minimal, focused notifications:
+
+- **CI Pipeline**: One notification when the entire CI pipeline completes (success/failure/partial)
+- **Release Pipeline**: One notification for release success, one for release failure
+
+All notifications are sent to a single channel: `#cicd-notifications`
+
+## Features
+
+### CI Notifications
+
+- ✅ **Pipeline Status**: Overall CI result with individual job statuses
+- 🔗 **Direct Links**: Links to workflow runs and repository
+- 📊 **Job Breakdown**: Status of tests, security, quality, and compatibility checks
+- 🎯 **Contextual Info**: Branch, trigger type, and repository details
+
+### Release Notifications
+
+- 🚀 **Release Success**: Version info, installation commands, and useful links
+- ❌ **Release Failure**: Detailed failure information and troubleshooting context
+- 📦 **RubyGems Links**: Direct links to published gems
+- 📚 **GitHub Release**: Links to release notes and documentation
+
+## Setup Instructions
+
+### 1. Create Slack Webhook
+
+1. Go to your Slack workspace
+2. Navigate to **Apps** → **Incoming Webhooks**
+3. Click **Add to Slack**
+4. Choose the `#cicd-notifications` channel (create it if it doesn't exist)
+5. Copy the webhook URL (starts with `https://hooks.slack.com/services/...`)
+
+### 2. Add GitHub Secret
+
+1. Go to your GitHub repository: `https://github.com/patrick204nqh/class-metrix`
+2. Navigate to **Settings** → **Secrets and variables** → **Actions**
+3. Click **New repository secret**
+4. Name: `SLACK_WEBHOOK_URL`
+5. Value: Your Slack webhook URL
+6. Click **Add secret**
+
+### 3. Create Slack Channel
+
+Create a `#cicd-notifications` channel in your Slack workspace where all CI/CD notifications will be posted.
+
+## Notification Examples
+
+### CI Pipeline Complete (Success)
+
+```
+✅ CI Pipeline Complete
+Repository: your-org/class-metrix
+Branch: main
+Trigger: push
+Status: success
+Tests: success
+Security: success
+Quality: success
+Compatibility: success
+```
+
+### CI Pipeline Complete (Failure)
+
+```
+❌ CI Pipeline Complete
+Repository: your-org/class-metrix
+Branch: feature-branch
+Trigger: pull_request
+Status: failure
+Tests: failure
+Security: success
+Quality: success
+Compatibility: success
+```
+
+### Release Success
+
+```
+🚀 ClassMetrix Release Complete
+Version: v1.2.3
+Trigger: Manual
+Installation: gem install class-metrix -v 1.2.3
+Links: 📦 RubyGems • 📚 GitHub Release
+```
+
+### Release Failure
+
+```
+❌ ClassMetrix Release Failed
+Failed Step: Build & Publish
+Version: v1.2.3
+Reason: Gem build or RubyGems publishing failed
+Repository: your-org/class-metrix
+Workflow Run: View Logs
+Triggered By: username
+```
+
+## Workflow Integration
+
+### Main CI Workflow (`.github/workflows/main.yml`)
+
+- Runs on push to main/master and pull requests
+- Sends one notification after all jobs complete
+- Includes status of: tests, security scan, quality checks, compatibility
+- Only sends notifications if `SLACK_WEBHOOK_URL` secret is configured
+
+### Release Workflow (`.github/workflows/release.yml`)
+
+- Runs on version tags or manual dispatch
+- Sends success notification with installation instructions and links
+- Sends failure notification with detailed troubleshooting information
+- Includes RubyGems and GitHub release links
+
+## Testing the Integration
+
+### Test CI Notifications
+
+1. Make a small change to your code
+2. Push to a branch or create a pull request
+3. Check the `#cicd-notifications` channel for the CI completion message
+
+### Test Release Notifications
+
+1. Create a test release using workflow dispatch:
+   ```bash
+   # Go to Actions → Release Gem → Run workflow
+   # Enable "Dry run" to test without publishing
+   ```
+2. Check the channel for release notifications
+
+### Manual Testing Script
+
+You can test the Slack webhook directly:
+
+```bash
+#!/bin/bash
+# Save as bin/test_slack_integration
+
+WEBHOOK_URL="YOUR_SLACK_WEBHOOK_URL"
+
+curl -X POST -H 'Content-type: application/json' \
+  --data '{
+    "channel": "#cicd-notifications",
+    "username": "GitHub Actions CI",
+    "icon_emoji": ":robot_face:",
+    "text": "🧪 Testing Slack integration for ClassMetrix CI/CD"
+  }' \
+  "$WEBHOOK_URL"
+```
+
+## Troubleshooting
+
+### No Notifications Received
+
+1. **Check Secret**: Verify `SLACK_WEBHOOK_URL` is set correctly in GitHub repository secrets
+2. **Check Channel**: Ensure `#cicd-notifications` channel exists and webhook has access
+3. **Check Webhook**: Test webhook URL manually using curl or Postman
+4. **Check Logs**: View workflow run logs for any Slack notification errors
+
+### Webhook URL Issues
+
+- Ensure the URL starts with `https://hooks.slack.com/services/`
+- Verify the webhook is still active in Slack settings
+- Check that the webhook has permission to post to the channel
+
+### Missing Notifications
+
+- Notifications only send if workflows complete (not cancelled mid-run)
+- CI notifications require all jobs to finish (test, security, quality, compatibility)
+- Release notifications only send if `dry_run` is not enabled
+
+## Customization
+
+### Changing the Channel
+
+To send notifications to a different channel, update the `"channel"` field in both workflow files:
+
+```yaml
+"channel": "#your-custom-channel"
+```
+
+### Adding More Notifications
+
+The current setup provides minimal notifications. To add more:
+
+1. Review the conversation summary for previously removed notifications
+2. Add new notification steps to appropriate workflow jobs
+3. Follow the same webhook format for consistency
+
+### Notification Format
+
+All notifications use Slack's rich attachment format with:
+
+- Color coding (green for success, red for failure, yellow for warnings)
+- Structured fields for easy scanning
+- Direct links to relevant resources
+- Contextual information (branch, trigger, repository)
+
+## Security Considerations
+
+- **Webhook URL**: Keep the `SLACK_WEBHOOK_URL` secret secure
+- **Channel Access**: Ensure only appropriate team members have access to the notifications channel
+- **Information Exposure**: Current notifications don't expose sensitive code or secrets
+- **Rate Limiting**: Slack has rate limits for webhook calls (not typically an issue with minimal notifications)
+
+## Support
+
+For issues with Slack integration:
+
+1. Check this documentation first
+2. Review GitHub Actions workflow logs
+3. Test webhook URL manually
+4. Verify Slack workspace permissions
+5. Create an issue in the ClassMetrix repository if problems persist
+
+## Related Documentation
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Slack Incoming Webhooks](https://api.slack.com/messaging/webhooks)
+- [ClassMetrix Release Guide](./RELEASE_GUIDE.md)

data/examples/README.md

@@ -16,6 +16,7 @@ ruby examples/inheritance_and_modules.rb  # Inheritance and module analysis
 ### Core Examples
 
 - **`basic_usage.rb`** - Basic constant and method extraction
+
   - Simple class comparison
   - Filtering and multi-type extraction
   - Hash expansion basics
@@ -122,43 +123,48 @@ ClassMetrix.extract(:constants)
 ## 📊 Example Output
 
 ### Basic Comparison
+
 ```markdown
-| Constant | User    | Admin   |
-|----------|---------|---------|
-| ROLE     | user    | admin   |
-| TIMEOUT  | 3600    | 7200    |
+| Constant | User | Admin |
+| -------- | ---- | ----- |
+| ROLE     | user | admin |
+| TIMEOUT  | 3600 | 7200  |
 ```
 
 ### With Inheritance
+
 ```markdown
-| Constant      | DatabaseService | CacheService |
-|---------------|-----------------|--------------|
-| SERVICE_NAME  | database        | cache        |
-| SERVICE_VERSION| 1.0            | 1.0          |
-| DEFAULT_TIMEOUT| 30             | 30           |
+| Constant        | DatabaseService | CacheService |
+| --------------- | --------------- | ------------ |
+| SERVICE_NAME    | database        | cache        |
+| SERVICE_VERSION | 1.0             | 1.0          |
+| DEFAULT_TIMEOUT | 30              | 30           |
 ```
 
 ### Hash Expansion
+
 ```markdown
-| Method        | Service1        | Service2        |
-|---------------|-----------------|-----------------|
-| config        | {...}           | {...}           |
-| config.host   | localhost       | production.com  |
-| config.port   | 3000            | 443             |
-| config.ssl    | ❌              | ✅              |
+| Method      | Service1  | Service2       |
+| ----------- | --------- | -------------- |
+| config      | {...}     | {...}          |
+| config.host | localhost | production.com |
+| config.port | 3000      | 443            |
+| config.ssl  | ❌        | ✅             |
 ```
 
 ## 🛠️ 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_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**
@@ -197,6 +203,6 @@ ruby examples/inheritance_and_modules.rb
 # Advanced features
 ruby examples/advanced/hash_expansion.rb
 
-# Real-world scenarios  
+# Real-world scenarios
 ruby examples/real_world/microservices_audit.rb
 ```

data/examples/basic_usage.rb

@@ -11,11 +11,11 @@ puts "=" * 30
 class User
   ROLE = "user"
   MAX_LOGIN_ATTEMPTS = 3
-  
+
   def self.permissions
     ["read"]
   end
-  
+
   def self.session_timeout
     3600
   end
@@ -24,11 +24,11 @@ end
 class Admin
   ROLE = "admin"
   MAX_LOGIN_ATTEMPTS = 5
-  
+
   def self.permissions
     ["read", "write", "admin"]
   end
-  
+
   def self.session_timeout
     7200
   end
@@ -40,33 +40,33 @@ classes = [User, Admin]
 puts "\n1. Constants Comparison"
 puts "-" * 25
 result = ClassMetrix.extract(:constants)
-                   .from(classes)
-                   .to_markdown
+                    .from(classes)
+                    .to_markdown
 puts result
 
 # 2. Extract class methods
-puts "\n2. Class Methods Comparison" 
+puts "\n2. Class Methods Comparison"
 puts "-" * 25
 result = ClassMetrix.extract(:class_methods)
-                   .from(classes)
-                   .to_markdown
+                    .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
+                    .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
+                    .from(classes)
+                    .filter(/ROLE|permissions/)
+                    .to_markdown
 puts result
 
 # 5. Hash expansion
@@ -75,14 +75,14 @@ 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 
+                    .from([ConfigExample])
+                    .expand_hashes
+                    .to_markdown
+puts result

data/examples/debug_levels_demo.rb

@@ -9,7 +9,7 @@ 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
@@ -17,7 +17,7 @@ end
 
 class ServiceB
   CONFIG = { host: 'remote', port: 8080 }
-  
+
   def self.get_settings
     { cache: false, retries: 1 }
   end
@@ -30,36 +30,35 @@ puts
 levels = [:basic, :detailed, :verbose]
 
 levels.each do |level|
-  puts "\n" + "="*50
+  puts "\n" + "=" * 50
   puts "DEBUG LEVEL: #{level.upcase}"
-  puts "="*50
-  
+  puts "=" * 50
+
   begin
     result = ClassMetrix.extract(:constants, :class_methods)
-      .from([ServiceA, ServiceB])
-      .expand_hashes
-      .debug(level)  # Set debug level
-      .to_markdown
-      
+                        .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 "\n" + "=" * 50
 puts "DEBUG LEVEL SUMMARY"
-puts "="*50
+puts "=" * 50
 puts
 puts ":basic    - Key decisions and summaries only"
-puts ":detailed - More context and intermediate steps"  
+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" 
+puts "Use :verbose for deep debugging of specific values"

data/examples/debug_mode_demo.rb

@@ -9,7 +9,7 @@ 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
@@ -18,7 +18,7 @@ end
 class ProblematicService
   # This constant is a Class object (not a Hash)
   CONFIG_CLASS = SafeService
-  
+
   def self.service_config
     SafeService::CONFIG
   end
@@ -29,11 +29,11 @@ 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
@@ -41,7 +41,7 @@ end
 
 class WeirdService
   BROKEN_OBJECT = ProblematicObject.new
-  
+
   def self.get_config
     { normal: 'value', broken: ProblematicObject.new }
   end
@@ -58,18 +58,17 @@ puts
 
 begin
   result = ClassMetrix.extract(:constants, :class_methods)
-    .from([SafeService, ProblematicService, WeirdService])
-    .expand_hashes
-    .handle_errors
-    .debug  # Enable debug mode
-    .to_markdown
-    
+                      .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 
+end