class-metrix 1.0.1 → 1.1.0

data/docs/RELEASE_GUIDE.md

@@ -0,0 +1,318 @@
+# 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. **Slack Integration** (optional): Set up `SLACK_WEBHOOK_URL` for release notifications
+3. **Clean working directory**: All changes committed to `master` branch
+4. **Tests passing**: Run `bundle exec rake` to verify
+5. **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
+
+### Release Triggers
+
+The release workflow can be triggered in two ways:
+
+1. **Tag Push** (recommended): Push a version tag (e.g., `v0.1.1`)
+2. **Manual Dispatch**: Use GitHub Actions UI for manual releases
+
+### Tag-Based Release (Recommended)
+
+When you push a tag (e.g., `v0.1.1`), GitHub Actions automatically:
+
+1. **Validates Release**: Checks version format and consistency
+2. **Runs Tests**: Comprehensive tests across Ruby 3.2 and 3.3
+3. **Security Scan**: Brakeman security analysis
+4. **Quality Check**: RuboCop code quality verification
+5. **Builds Gem**: Creates and tests the gem package
+6. **Publishes to RubyGems**: Uploads to the gem repository
+7. **Creates GitHub Release**: With installation instructions and links
+8. **Slack Notification**: Success/failure alerts to `#cicd-notifications`
+
+### Manual Release via GitHub Actions
+
+For more control, use the manual release option:
+
+1. Go to **Actions** → **Release Gem** → **Run workflow**
+2. Enter the version number (e.g., `1.0.2`)
+3. Optionally enable **Dry run** to test without publishing
+4. Click **Run workflow**
+
+### Workflow Features
+
+- **Version Validation**: Ensures semantic versioning format
+- **Consistency Check**: Verifies tag matches `lib/class_metrix/version.rb`
+- **Duplicate Protection**: Prevents releasing existing versions
+- **Dry Run Mode**: Test releases without publishing
+- **Rich Notifications**: Detailed Slack alerts with links and context
+- **Artifact Storage**: Saves gem files for 90 days
+
+### Workflow Files
+
+- **`.github/workflows/main.yml`**: CI pipeline for PRs and `master` pushes
+- **`.github/workflows/release.yml`**: Release automation for tags and manual dispatch
+
+## 🔑 Required GitHub Secrets
+
+### Essential Secrets
+
+1. **`RUBYGEMS_API_KEY`** (Required):
+
+   ```bash
+   # Generate your API key
+   gem signin
+   # Get your API key from ~/.gem/credentials
+   ```
+
+2. **`SLACK_WEBHOOK_URL`** (Optional):
+   - Set up for release notifications
+   - See [Slack Integration Guide](./SLACK_INTEGRATION.md) for details
+
+### Adding Secrets to GitHub
+
+1. Go to your repository → **Settings** → **Secrets and variables** → **Actions**
+2. Click **New repository secret**
+3. Add the secret name and value
+4. Click **Add secret**
+
+## 📊 Release Checklist
+
+### Pre-Release Verification
+
+- [ ] All tests pass (`bundle exec rake`)
+- [ ] Security scan clean (`bundle exec brakeman`)
+- [ ] Code quality good (`bundle exec rubocop`)
+- [ ] Documentation is updated
+- [ ] CHANGELOG.md reflects new changes
+- [ ] Version is bumped appropriately in `lib/class_metrix/version.rb`
+- [ ] No TODO items in gemspec
+- [ ] Working on clean `master` branch
+
+### GitHub Configuration
+
+- [ ] `RUBYGEMS_API_KEY` secret is configured
+- [ ] `SLACK_WEBHOOK_URL` secret is configured (optional)
+- [ ] Repository permissions allow workflow execution
+- [ ] You have push permissions for the gem on RubyGems
+
+### Post-Release Verification
+
+- [ ] Release appears on [RubyGems](https://rubygems.org/gems/class-metrix)
+- [ ] GitHub Release was created with proper notes
+- [ ] Slack notification received (if configured)
+- [ ] Gem installs correctly: `gem install class-metrix -v X.X.X`
+
+## 🐛 Troubleshooting
+
+### Common Release Issues
+
+#### Version Mismatch Error
+
+```
+❌ Version mismatch! Gemspec: 0.1.0, Release: 0.1.1
+```
+
+**Solution**: Ensure the version in `lib/class_metrix/version.rb` matches your git tag exactly.
+
+#### RubyGems Publishing Failed
+
+**Possible causes**:
+
+- `RUBYGEMS_API_KEY` secret is incorrect or expired
+- You don't have push permissions for the gem
+- The version already exists on RubyGems
+- Network connectivity issues
+
+**Solutions**:
+
+1. Regenerate and update the RubyGems API key
+2. Check gem ownership: `gem owner class-metrix`
+3. Verify version doesn't exist: `gem list class-metrix --remote`
+
+#### GitHub Release Creation Failed
+
+**Possible causes**:
+
+- Insufficient repository permissions
+- Tag already exists with different content
+- Network issues
+
+**Solutions**:
+
+1. Check repository permissions (usually automatic for `GITHUB_TOKEN`)
+2. Delete and recreate the tag if needed
+3. Re-run the workflow
+
+#### Workflow Validation Errors
+
+**Common issues**:
+
+- Non-semantic version format
+- Missing CHANGELOG entries
+- Failing tests or security scans
+
+**Solutions**:
+
+1. Use semantic versioning format: `X.Y.Z`
+2. Update CHANGELOG.md before tagging
+3. Fix any failing tests or security issues before release
+
+#### Slack Notifications Not Working
+
+**Check**:
+
+- `SLACK_WEBHOOK_URL` secret is configured
+- Slack webhook is still active
+- `#cicd-notifications` channel exists
+- Webhook has permission to post
+
+See [Slack Integration Guide](./SLACK_INTEGRATION.md) for detailed troubleshooting.
+
+### Emergency Release Recovery
+
+If a release fails partway through:
+
+1. **Check RubyGems**: Verify if the gem was published
+2. **Check GitHub Releases**: See if release was created
+3. **Manual Cleanup**: Delete tags/releases if needed
+4. **Re-run**: Fix issues and re-trigger the workflow
+
+## 📈 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 Tasks
+
+### Immediate Verification
+
+1. **Check RubyGems**: Verify the new version appears on [rubygems.org/gems/class-metrix](https://rubygems.org/gems/class-metrix)
+2. **Test Installation**:
+   ```bash
+   gem install class-metrix -v X.X.X
+   # Test in a new Ruby environment
+   ```
+3. **Verify GitHub Release**: Check that release notes and assets are correct
+4. **Slack Confirmation**: Ensure success notification was received
+
+### Follow-up Actions
+
+1. **Update Dependencies**: In projects using ClassMetrix
+
+   ```ruby
+   # Gemfile
+   gem 'class-metrix', '~> X.X.X'
+   ```
+
+2. **Documentation Updates**:
+
+   - Update any version-specific documentation
+   - Refresh installation instructions if needed
+   - Update examples if new features were added
+
+3. **Announcements**: Consider announcing on:
+
+   - Project README badges
+   - Relevant Ruby community channels
+   - Internal team notifications
+
+4. **Monitor**: Watch for any user reports or issues with the new version
+
+### Rollback Procedure
+
+If a critical issue is discovered post-release:
+
+1. **Immediate**: Document the issue clearly
+2. **Quick Fix**: If possible, prepare a patch release
+3. **Communication**: Notify users via appropriate channels
+4. **Yanking** (last resort):
+   ```bash
+   gem yank class-metrix -v X.X.X
+   ```
+
+## 📚 Additional Resources
+
+- **[Slack Integration Guide](./SLACK_INTEGRATION.md)**: Set up release notifications
+- **[Architecture Guide](./ARCHITECTURE.md)**: Understanding the codebase
+- **[QLTY Integration](./QLTY_INTEGRATION.md)**: Code quality monitoring
+- **[Semantic Versioning](https://semver.org/)**: Version numbering guidelines
+- **[RubyGems Guides](https://guides.rubygems.org/)**: Official gem publishing documentation

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