ruby-maat 1.0.0

data/README_RUBY.md

@@ -0,0 +1,300 @@
+# Ruby Maat
+
+[![Gem Version](https://badge.fury.io/rb/ruby-maat.svg)](https://badge.fury.io/rb/ruby-maat)
+[![Build Status](https://github.com/viamin/ruby-maat/workflows/CI/badge.svg)](https://github.com/viamin/ruby-maat/actions)
+
+Ruby Maat is a command line tool used to mine and analyze data from version-control systems (VCS). It's a Ruby port of the original [Code Maat](https://github.com/adamtornhill/code-maat) by Adam Tornhill.
+
+Ruby Maat was developed to accompany the discussions in the books [Your Code as a Crime Scene](https://pragprog.com/titles/atcrime/your-code-as-a-crime-scene) and [Software Design X-Rays](https://pragprog.com/titles/atevol/software-design-x-rays).
+
+**Note:** The analyses have evolved into [CodeScene](https://codescene.io/), which automates all the analyses found in Ruby Maat and several new ones.
+
+## Drop-in Replacement
+
+Ruby Maat is designed as a **drop-in replacement** for Code Maat. It supports:
+
+- ✅ Identical command-line arguments
+- ✅ Same VCS log file formats  
+- ✅ Compatible CSV output format
+- ✅ All original analysis types
+
+Simply replace `java -jar code-maat.jar` with `ruby-maat` in your existing scripts!
+
+## Installation
+
+### Via RubyGems (Recommended)
+
+```bash
+gem install ruby-maat
+```
+
+### From Source
+
+```bash
+git clone https://github.com/viamin/ruby-maat.git
+cd ruby-maat
+bundle install
+rake install
+```
+
+### Requirements
+
+- Ruby 3.2 or later
+- No external dependencies beyond the gem requirements
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Analyze Git repository
+ruby-maat -l logfile.log -c git2 -a summary
+
+# With specific analysis
+ruby-maat -l logfile.log -c git2 -a coupling
+
+# Write to file
+ruby-maat -l logfile.log -c git2 -a authors -o results.csv
+```
+
+### Command Line Options
+
+```
+Usage: ruby-maat -l log-file -c vcs-type [options]
+
+Required:
+  -l, --log LOG                    Log file with input data
+  -c, --version-control VCS        Input vcs module type: supports svn, git, git2, hg, p4, or tfs
+
+Analysis:
+  -a, --analysis ANALYSIS          The analysis to run (default: authors)
+                                   Available: abs-churn, age, author-churn, authors, communication, 
+                                   coupling, entity-churn, entity-effort, entity-ownership, 
+                                   fragmentation, identity, main-dev, main-dev-by-revs, messages, 
+                                   refactoring-main-dev, revisions, soc, summary
+
+Output:
+  -r, --rows ROWS                  Max rows in output
+  -o, --outfile OUTFILE            Write the result to the given file name
+      --input-encoding ENCODING    Specify an encoding other than UTF-8 for the log file
+
+Grouping:
+  -g, --group GROUP                A file with a pre-defined set of layers
+  -p, --team-map-file TEAM_MAP     A CSV file with author,team mappings
+  -t, --temporal-period PERIOD     Group commits by temporal period
+
+Filtering:
+  -n, --min-revs MIN_REVS          Minimum number of revisions (default: 5)
+  -m, --min-shared-revs MIN_SHARED Minimum shared revisions (default: 5)
+  -i, --min-coupling MIN_COUPLING  Minimum coupling percentage (default: 30)
+  -x, --max-coupling MAX_COUPLING  Maximum coupling percentage (default: 100)
+  -s, --max-changeset-size SIZE    Maximum changeset size (default: 30)
+
+Analysis-specific:
+  -e, --expression-to-match REGEX  Regex for commit message analysis
+  -d, --age-time-now DATE          Reference date for age analysis (YYYY-MM-dd)
+      --verbose-results            Include additional analysis details
+
+Other:
+  -h, --help                       Show this help message
+      --version                    Show version information
+```
+
+## Generating Input Data
+
+Ruby Maat operates on log files from version-control systems. **Use the exact same commands as Code Maat:**
+
+### Git (Recommended: git2 format)
+
+```bash
+git log --all --numstat --date=short --pretty=format:'--%h--%ad--%aN' --no-renames --after=YYYY-MM-DD > logfile.log
+```
+
+Then use `-c git2` when running Ruby Maat.
+
+### Git (Legacy format)
+
+```bash
+git log --pretty=format:'[%h] %aN %ad %s' --date=short --numstat --after=YYYY-MM-DD > logfile.log
+```
+
+Then use `-c git` when running Ruby Maat.
+
+### Subversion
+
+```bash
+svn log -v --xml > logfile.log -r {YYYYmmDD}:HEAD
+```
+
+### Other VCS Systems
+
+Ruby Maat supports the same log formats as Code Maat for:
+
+- Mercurial (`hg`)
+- Perforce (`p4`)
+- Team Foundation Server (`tfs`)
+
+See the [original documentation](https://github.com/adamtornhill/code-maat#generating-input-data) for specific commands.
+
+## Available Analyses
+
+| Analysis | Description |
+|----------|-------------|
+| `authors` | Number of authors per module (default) |
+| `revisions` | Number of revisions per entity |
+| `coupling` | Logical coupling between modules |
+| `soc` | Sum of coupling per entity |
+| `summary` | High-level project statistics |
+| `abs-churn` | Absolute code churn over time |
+| `author-churn` | Code churn per author |
+| `entity-churn` | Code churn per entity |
+| `entity-ownership` | Code ownership per author per entity |
+| `main-dev` | Main developer per entity (by lines) |
+| `main-dev-by-revs` | Main developer per entity (by commits) |
+| `entity-effort` | Development effort per author per entity |
+| `fragmentation` | Ownership fragmentation (fractal value) |
+| `communication` | Developer communication patterns |
+| `age` | Code age analysis |
+| `messages` | Commit message word frequency |
+| `identity` | Raw data dump (debugging) |
+
+## Examples
+
+### Authors Analysis
+
+```bash
+ruby-maat -l git.log -c git2 -a authors
+```
+
+Output:
+
+```csv
+entity,n-authors,n-revs
+InfoUtils.java,12,60
+BarChart.java,7,30
+Page.java,4,27
+```
+
+### Logical Coupling
+
+```bash
+ruby-maat -l git.log -c git2 -a coupling
+```
+
+Output:
+
+```csv
+entity,coupled,degree,average-revs
+InfoUtils.java,Page.java,78,44
+InfoUtils.java,BarChart.java,62,45
+```
+
+### Summary Statistics
+
+```bash
+ruby-maat -l git.log -c git2 -a summary
+```
+
+Output:
+
+```csv
+statistic,value
+number-of-commits,919
+number-of-entities,730
+number-of-entities-changed,3397
+number-of-authors,79
+```
+
+## Advanced Features
+
+### Architectural Grouping
+
+Group files into architectural layers:
+
+```
+# layers.txt
+src/Features/Core      => Core
+^src\/.*\/.*Tests\.cs$ => CS Tests
+```
+
+```bash
+ruby-maat -l git.log -c git2 -a coupling -g layers.txt
+```
+
+### Team Analysis
+
+Map individual authors to teams:
+
+```csv
+# teams.csv
+author,team
+john.doe,Backend Team
+jane.smith,Frontend Team
+```
+
+```bash
+ruby-maat -l git.log -c git2 -a authors -p teams.csv
+```
+
+### Temporal Analysis
+
+Group commits by time period:
+
+```bash
+ruby-maat -l git.log -c git2 -a coupling -t day
+```
+
+## Differences from Code Maat
+
+While Ruby Maat is a drop-in replacement, there are some minor differences:
+
+### Advantages
+
+- **Faster startup**: No JVM startup time
+- **Better memory efficiency**: Ruby's garbage collection
+- **Easier installation**: No Java dependencies
+- **Native Ruby integration**: Use as a library in Ruby projects
+
+### Performance
+
+- Ruby Maat may be slightly slower on very large datasets
+- For most repositories, performance is comparable
+- Memory usage is typically lower than the JVM version
+
+## Development
+
+### Running Tests
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+### Code Quality
+
+```bash
+bundle exec rubocop
+```
+
+### Building the Gem
+
+```bash
+bundle exec rake build
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/viamin/ruby-maat>.
+
+## License
+
+Ruby Maat is distributed under the [GNU General Public License v3.0](http://www.gnu.org/licenses/gpl.html), the same license as the original Code Maat.
+
+## Acknowledgments
+
+- **Adam Tornhill** - Original Code Maat author and creator of the analysis algorithms
+- **Code Maat contributors** - For the foundational work this port is based on
+
+## About the Name
+
+Like the original Code Maat, this tool is named after Maat, the ancient Egyptian goddess of truth, justice, and order. Ruby Maat continues Maat's work of bringing order to chaotic codebases, now in Ruby.

data/RELEASE_PLEASE_SETUP.md

@@ -0,0 +1,198 @@
+# Release Please Setup
+
+This document explains how the automated release system works using Google's Release Please.
+
+## Overview
+
+Release Please automates:
+
+- ✅ **Version bumping** based on conventional commits
+- ✅ **CHANGELOG generation** from commit messages  
+- ✅ **Release creation** with proper Git tags
+- ✅ **Gem publishing** to RubyGems.org
+- ✅ **GitHub release** with artifacts
+
+## How It Works
+
+### 1. Conventional Commits
+
+Developers use conventional commit format:
+
+```bash
+git commit -m "feat(parser): add SVN log support"
+git commit -m "fix(analysis): handle empty datasets correctly"
+git commit -m "docs: update CLI examples"
+```
+
+### 2. Release Please Analysis
+
+On every push to main/master:
+
+- Analyzes commits since last release
+- Determines if a release is needed
+- Calculates version bump (patch/minor/major)
+
+### 3. Release PR Creation
+
+When releasable changes exist:
+
+- Creates/updates a "Release PR"
+- Updates version files
+- Generates/updates CHANGELOG.md
+- Ready for review and approval
+
+### 4. Automated Publishing
+
+When Release PR is merged:
+
+- Creates GitHub release with tag
+- Publishes gem to RubyGems.org
+- Uploads gem artifact to release
+
+## Configuration Files
+
+### `.release-please-config.json`
+
+- Package configuration
+- Version file locations
+- Changelog sections
+- Extra files to update
+
+### `.release-please-manifest.json`
+
+- Tracks current version
+- Updated automatically by Release Please
+
+### `.commitlintrc.json`
+
+- Validates conventional commit format
+- Enforces consistent commit messages
+- Runs on pull requests
+
+### `.gitmessage`
+
+- Commit message template
+- Set up with: `git config commit.template .gitmessage`
+
+## Conventional Commit Types
+
+| Type | Description | Version Bump |
+|------|-------------|--------------|
+| `feat:` | New feature | Minor |
+| `fix:` | Bug fix | Patch |
+| `feat!:` | Breaking change | Major |
+| `BREAKING CHANGE:` | Breaking change | Major |
+| `docs:` | Documentation | None |
+| `style:` | Code style | None |
+| `refactor:` | Code refactoring | None |
+| `test:` | Tests | None |
+| `chore:` | Maintenance | None |
+| `ci:` | CI/CD changes | None |
+| `deps:` | Dependencies | None |
+
+## Common Scopes
+
+- `analysis` - Analysis modules
+- `parser` - VCS parsers
+- `output` - Output formatters
+- `cli` - Command-line interface
+- `dataset` - Data handling
+- `core` - Core functionality
+
+## Example Workflow
+
+1. **Feature Development**:
+
+   ```bash
+   git commit -m "feat(analysis): add complexity metrics analysis"
+   git commit -m "test(analysis): add tests for complexity metrics"
+   git commit -m "docs(analysis): document complexity analysis options"
+   ```
+
+2. **Push to Main**:
+
+   ```bash
+   git push origin main
+   ```
+
+3. **Release Please Actions**:
+   - Analyzes commits
+   - Creates Release PR titled "chore(main): release 1.1.0"
+   - Updates version from 1.0.0 → 1.1.0
+   - Adds feature to CHANGELOG.md
+
+4. **Review & Merge**:
+   - Review the generated changelog
+   - Merge the Release PR
+   - Automatic publishing begins
+
+5. **Published Release**:
+   - GitHub release created with tag v1.1.0
+   - Gem published to RubyGems.org
+   - Gem artifact attached to release
+
+## Benefits Over Manual Releases
+
+- ✅ **No version conflicts** - automated version management
+- ✅ **Consistent changelogs** - generated from commits
+- ✅ **Enforced conventions** - conventional commit validation
+- ✅ **Zero-downtime releases** - automated testing before publish
+- ✅ **Release approval** - review before publishing via Release PR
+- ✅ **Atomic releases** - all-or-nothing publishing
+
+## Troubleshooting
+
+### No Release PR Created
+
+- Check if commits follow conventional format
+- Ensure commits contain releasable changes (`feat:`, `fix:`, etc.)
+- Verify `.release-please-config.json` is valid
+
+### Release PR Not Publishing
+
+- Check RubyGems API key secret is set
+- Verify tests pass in CI
+- Ensure gem version isn't already published
+
+### Version Not Updated
+
+- Check `version-file` path in config
+- Verify `extra-files` configuration for gemspec
+- Ensure Release PR was merged, not just closed
+
+## Manual Override
+
+To create a release manually:
+
+```bash
+# Trigger release-please workflow manually
+gh workflow run publish.yml
+
+# Or create a conventional commit that forces a release
+git commit -m "chore: trigger release" --allow-empty
+git push origin main
+```
+
+## Getting Started
+
+1. **Set up commit template**:
+
+   ```bash
+   git config commit.template .gitmessage
+   ```
+
+2. **Use conventional commits**:
+
+   ```bash
+   git commit -m "feat(cli): add new --format option"
+   ```
+
+3. **Push changes**:
+
+   ```bash
+   git push origin main
+   ```
+
+4. **Wait for Release PR** and review/merge when ready
+
+That's it! The rest is automated. 🚀

data/RUBY_MAAT.md

@@ -0,0 +1,227 @@
+# RUBY_MAAT.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the Ruby Maat codebase.
+
+## Project Overview
+
+Ruby Maat is a Ruby port of Code Maat, maintaining full backward compatibility while providing a modern Ruby implementation. It's designed as a drop-in replacement for the original Clojure version.
+
+## Build and Development Commands
+
+### Setting Up Development Environment
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linting
+bundle exec rubocop
+
+# Auto-fix linting issues
+bundle exec rubocop -a
+
+# Run all checks
+bundle exec rake
+```
+
+### Building and Installing
+
+```bash
+# Build gem
+bundle exec rake build
+
+# Install locally
+bundle exec rake install
+
+# Run the CLI locally
+bundle exec exe/ruby-maat --help
+```
+
+### Testing
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/ruby_maat/analysis/authors_spec.rb
+
+# Run with coverage
+bundle exec rspec --format documentation
+
+# Test specific functionality
+bundle exec rspec --tag focus
+```
+
+## Architecture Overview
+
+### Core Components
+
+1. **Command Line Interface** (`lib/ruby_maat/cli.rb`)
+   - Uses optparse for argument parsing
+   - Maintains full backward compatibility with Code Maat CLI
+   - Provides identical command-line arguments and behavior
+
+2. **Application Core** (`lib/ruby_maat/app.rb`)
+   - Main orchestration following same pipeline as original:
+     - VCS Parsing → Data Grouping → Analysis → CSV Output
+   - Registry pattern for analysis selection
+   - Error handling and recovery
+
+3. **Data Model**
+   - `ChangeRecord` - Immutable value object for VCS changes
+   - `Dataset` - Wrapper around Rover DataFrame for domain operations
+   - Clean separation between data structures and business logic
+
+4. **VCS Parsers** (`lib/ruby_maat/parsers/`)
+   - Strategy pattern with base class and specific implementations
+   - Identical input formats as original Code Maat
+   - Error handling for malformed log files
+
+5. **Analysis Modules** (`lib/ruby_maat/analysis/`)
+   - Object-oriented design with base class and inheritance
+   - Each analysis encapsulates domain logic
+   - Rover DataFrame integration for statistical operations
+
+6. **Data Processors** (`lib/ruby_maat/groupers/`)
+   - Layer grouping for architectural boundaries
+   - Temporal grouping for time-based analysis
+   - Team mapping for organizational analysis
+
+### Key Design Decisions
+
+**Rover DataFrame Integration:**
+
+- Replaces Incanter from original Clojure version
+- Provides statistical computing capabilities
+- Andrew Kane's excellent DataFrame library
+
+**Object-Oriented Architecture:**
+
+- Functional Clojure code translated to Ruby OOP
+- Strategy pattern for parsers and analyses
+- Immutable value objects where appropriate
+
+**Backward Compatibility:**
+
+- Identical CLI arguments and behavior
+- Same CSV output format
+- Compatible with existing scripts and workflows
+
+### Analysis Modules
+
+All analyses inherit from `BaseAnalysis` and implement `analyze(dataset, options)`:
+
+**Core Analyses:**
+
+- `Authors` - Developer count and revision metrics per entity
+- `LogicalCoupling` - Entities that change together
+- `Entities` - Basic revision counts
+- `Summary` - High-level repository statistics
+
+**Code Quality Analyses:**
+
+- `Churn::*` - Various code churn metrics
+- `Effort::*` - Developer effort and ownership patterns
+- `CodeAge` - Time since last modification
+- `SumOfCoupling` - Aggregated coupling metrics
+
+**Social Analyses:**
+
+- `Communication` - Developer collaboration patterns
+- `CommitMessages` - Commit message word frequency
+
+### Data Flow
+
+1. **Parse** - VCS log files → Array of `ChangeRecord` objects
+2. **Group** - Apply architectural/temporal/team grouping transformations
+3. **Analyze** - Convert to `Dataset` and run analysis algorithms
+4. **Output** - Format results as CSV using `CsvOutput`
+
+### Ruby-Specific Patterns
+
+**Enumerable Usage:**
+
+- Heavy use of `map`, `filter`, `group_by`, `sort_by`
+- Functional programming style within OOP structure
+
+**Error Handling:**
+
+- Consistent error messages and recovery
+- Validation at boundaries (CLI, file parsing)
+- Meaningful error messages for users
+
+**Memory Efficiency:**
+
+- Streaming CSV output
+- Efficient data structures
+- Garbage collection friendly
+
+## Testing Strategy
+
+**RSpec Structure:**
+
+- Unit tests for each class and module
+- Integration tests for end-to-end workflows
+- Test data using `ChangeRecord` factories
+
+**Key Test Areas:**
+
+- Parser accuracy for all VCS formats
+- Analysis algorithm correctness
+- CLI argument parsing and validation
+- Error handling and edge cases
+
+**Test Data:**
+
+- Small, focused datasets for unit tests
+- Real-world patterns for integration tests
+- Edge cases (empty files, malformed data, etc.)
+
+## Development Guidelines
+
+**Code Style:**
+
+- Follow Ruby community conventions
+- Use RuboCop for consistency
+- Prefer explicit over implicit
+- Clear method and variable names
+
+**Performance:**
+
+- Profile with large datasets during development
+- Memory-conscious data structures
+- Efficient algorithms for coupling analysis
+
+**Compatibility:**
+
+- Maintain CLI compatibility religiously
+- Test against Code Maat output for regression
+- Document any behavioral differences
+
+## Integration with Original Code Maat
+
+Ruby Maat is designed to be a seamless replacement:
+
+**Input Compatibility:**
+
+- Accepts identical VCS log file formats
+- Same command-line arguments and flags
+- Compatible option parsing and validation
+
+**Output Compatibility:**
+
+- Identical CSV column names and formats
+- Same sorting and filtering behavior
+- Matching precision for numerical results
+
+**Feature Parity:**
+
+- All 23 analysis types implemented
+- Same grouping and mapping capabilities
+- Identical error messages where possible
+
+This makes Ruby Maat suitable for existing Code Maat workflows, scripts, and integrations without modification.