ruby-maat 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb9765769289bffda3972bb5e38c0f447c57266d811e29751b08c4c4b2dfe7c1
+  data.tar.gz: d3f8a816d384207f2f47dc03b7d1d912ab073a874ba7e3c8508882bf367c058b
+SHA512:
+  metadata.gz: bb422d1872d9ee5016c08ada681798cb4113ee00dc6a33d357157a5fee4e3c7e319a9ac90ed9e43da6cde80a9136f373642b8e4a467ff3f6ee0326e4b9bac62c
+  data.tar.gz: c343edcaafdaeaca4b348dcc4b643e1bd69000034c3a7be4f7d14345755626eb7d7227276b3f4495ccf1d87891857ffb360735938bace0ccfe643ea0f0d82b4d

data/.commitlintrc.json

@@ -0,0 +1,44 @@
+{
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "type-enum": [
+      2,
+      "always",
+      [
+        "feat",
+        "fix",
+        "docs",
+        "style",
+        "refactor",
+        "perf",
+        "test",
+        "chore",
+        "ci",
+        "deps"
+      ]
+    ],
+    "scope-enum": [
+      2,
+      "always",
+      [
+        "analysis",
+        "parser",
+        "output",
+        "cli",
+        "dataset",
+        "grouper",
+        "core",
+        "deps",
+        "ci"
+      ]
+    ],
+    "scope-empty": [0, "never"],
+    "subject-case": [1, "always", "lower-case"],
+    "subject-empty": [1, "never"],
+    "subject-full-stop": [2, "never", "."],
+    "type-case": [1, "always", "lower-case"],
+    "type-empty": [1, "never"],
+    "header-max-length": [1, "always", 100],
+    "body-max-line-length": [1, "always", 100]
+  }
+}

data/.mailmap

@@ -0,0 +1,3 @@
+Adam Tornhill <adam@adamtornhill.com> Adam Petersen <adam@adampetersen.se>
+robertc <robert@logicalchaos.org> LogicalChaos <robert@logicalchaos.org>
+Adam Tornhill <adam@adamtornhill.com> Adam Petersen Tornhill <adam@adampetersen.se>

data/.overcommit.yml

@@ -0,0 +1,77 @@
+# Ruby Maat Overcommit Configuration
+# See https://github.com/sds/overcommit for documentation
+
+# Verify signatures of committed configuration
+verify_signatures: false
+
+# Gemfile and Gemfile.lock consistency check
+gemfile: true
+
+PreCommit:
+  # General file checks
+  TrailingWhitespace:
+    enabled: true
+    exclude:
+      - '**/*.md'  # Markdown may intentionally have trailing spaces
+
+  EndOfFile:
+    enabled: true
+
+  YamlSyntax:
+    enabled: true
+
+  JsonSyntax:
+    enabled: true
+
+  # Ruby-specific checks
+  RuboCop:
+    enabled: true
+    command: ['bundle', 'exec', 'rubocop']
+    flags: ['--format', 'emacs', '--force-exclusion', '--display-cop-names']
+    on_warn: fail
+
+  # Use StandardRB instead of separate RuboCop config
+  StandardRb:
+    enabled: true
+    command: ['bundle', 'exec', 'standardrb']
+    flags: ['--no-fix']
+    on_warn: fail
+
+  # Run tests before committing
+  RSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'rspec']
+    flags: ['--format', 'progress']
+    on_warn: fail
+
+  # Check for merge conflict markers
+  MergeConflicts:
+    enabled: true
+
+  # Check for large files (>500KB)
+  FileSize:
+    enabled: true
+    size_limit_bytes: 512000
+
+CommitMsg:
+  # Validate conventional commit format using Ruby script
+  ConventionalCommit:
+    enabled: true
+    command: ['bin/validate-commit-msg']
+    flags: []
+    on_warn: warn
+
+PostCommit:
+  # Optional: Show a success message
+  MessageDisplay:
+    enabled: false
+
+PostMerge:
+  # Bundle install if Gemfile changes
+  BundleInstall:
+    enabled: true
+
+PostRewrite:
+  # Bundle install if Gemfile changes during rebase
+  BundleInstall:
+    enabled: true

data/.release-please-config.json

@@ -0,0 +1,33 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "ruby-maat",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true,
+      "draft": false,
+      "prerelease": false,
+      "version-file": "lib/ruby_maat/version.rb",
+      "changelog-sections": [
+        {"type": "feat", "section": "Features"},
+        {"type": "feature", "section": "Features"},
+        {"type": "fix", "section": "Bug Fixes"},
+        {"type": "perf", "section": "Performance Improvements"},
+        {"type": "deps", "section": "Dependencies"},
+        {"type": "ci", "section": "CI/CD"},
+        {"type": "docs", "section": "Documentation"},
+        {"type": "refactor", "section": "Refactoring", "hidden": false},
+        {"type": "test", "section": "Tests", "hidden": false},
+        {"type": "chore", "section": "Miscellaneous", "hidden": false},
+        {"type": "style", "section": "Code Style", "hidden": false}
+      ],
+      "extra-files": [
+        {
+          "type": "generic",
+          "path": "ruby-maat.gemspec",
+          "glob": "spec.version = \"*\""
+        }
+      ]
+    }
+  }
+}

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.0.0"
+}

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,48 @@
+# Inherit StandardRB configuration
+inherit_gem:
+  standard: config/base.yml
+
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+
+# Project-specific overrides
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+# RSpec-specific configurations
+RSpec/ExampleLength:
+  Max: 30
+
+RSpec/MultipleExpectations:
+  Max: 25
+
+RSpec/NestedGroups:
+  Max: 5

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-08-15
+
+### Added
+
+- Initial Ruby port of Code Maat
+- Support for all VCS parsers: Git, Git2, SVN, Mercurial, Perforce, TFS
+- Complete analysis suite:
+  - Authors analysis
+  - Entities analysis  
+  - Logical coupling analysis
+  - Sum of coupling analysis
+  - Code churn analysis (absolute, by author, by entity, ownership)
+  - Effort analysis (by revisions, main developer, fragmentation)
+  - Communication analysis
+  - Code age analysis
+  - Commit messages analysis
+  - Summary analysis
+- Data grouping capabilities:
+  - Layer grouping (architectural boundaries)
+  - Temporal grouping (time-based aggregation)
+  - Team mapping (author-to-team mapping)
+- Command-line interface with full backward compatibility
+- CSV output format
+- Comprehensive RSpec test suite
+- Ruby 3.2+ support
+- Rover DataFrame integration for statistical computing
+
+### Changed
+
+- Ported from Clojure to Ruby while maintaining API compatibility
+- Replaced Incanter with Rover DataFrame for statistical operations
+- Converted from functional to object-oriented architecture
+
+### Technical Notes
+
+- Drop-in replacement for original Code Maat
+- Identical command-line arguments and CSV output format
+- Improved memory efficiency through Ruby's garbage collection
+- Enhanced error handling and validation

data/CI_CD_SETUP.md

@@ -0,0 +1,180 @@
+# CI/CD Setup Documentation
+
+This document describes the GitHub Actions CI/CD pipeline for the Ruby Maat project.
+
+## Workflows
+
+### 1. CI Workflow (`.github/workflows/ci.yml`)
+
+Runs on every push and pull request to main/master branches.
+
+#### Jobs
+
+- **Test**: Runs RSpec tests across multiple Ruby versions (3.2, 3.3, 3.4) and operating systems (Ubuntu, macOS, Windows)
+- **Lint**: Runs RuboCop and StandardRB linting
+- **Security**: Runs Bundler Audit for security vulnerabilities
+- **Integration**: Tests CLI functionality with sample data
+- **Build**: Builds the gem and uploads it as an artifact
+
+#### Matrix Testing
+
+- Ruby versions: 3.2, 3.3, 3.4
+- Operating systems: Ubuntu (all versions), macOS (all versions), Windows (Ruby 3.3 only)
+
+### 2. Release Please Workflow (`.github/workflows/publish.yml`)
+
+Runs on every push to main/master branches and uses conventional commits to automate releases.
+
+#### How it works
+
+1. **Release Please** analyzes conventional commits since the last release
+2. **Creates Release PRs** when releasable changes are detected
+3. **Merging a Release PR** triggers the actual release:
+   - Updates version in `lib/ruby_maat/version.rb` and `ruby-maat.gemspec`
+   - Generates/updates `CHANGELOG.md` automatically
+   - Creates a GitHub release with the changelog
+   - Runs full test suite and linting
+   - Publishes gem to RubyGems.org
+   - Uploads gem artifact to the release
+
+## Required Secrets
+
+To enable automatic publishing to RubyGems, add these secrets to your GitHub repository:
+
+### RubyGems API Key
+
+1. Get your API key from [RubyGems.org](https://rubygems.org/profile/edit)
+2. Add it as a repository secret named `RUBYGEMS_API_KEY`
+
+### GitHub Token
+
+- `GITHUB_TOKEN` is automatically provided by GitHub Actions
+
+## Environment Setup
+
+The publish workflow uses a GitHub Environment named `rubygems` for additional security. To set this up:
+
+1. Go to your repository Settings → Environments
+2. Create an environment named `rubygems`
+3. Add protection rules (recommended):
+   - Required reviewers
+   - Deployment branches (limit to main/master)
+
+## Dependabot
+
+Dependabot is configured to:
+
+- Check for Ruby gem updates weekly (Sundays at 09:00)
+- Check for GitHub Actions updates weekly
+- Create PRs with appropriate labels and assignees
+
+## Coverage Reporting
+
+SimpleCov is configured to:
+
+- Generate coverage reports for all test runs
+- Group coverage by component (Analyses, Parsers, Output)
+- Require minimum 50% coverage (adjustable in `spec/spec_helper.rb`)
+- Upload coverage to Codecov (when CODECOV_TOKEN is set)
+
+## Security Scanning
+
+The CI pipeline includes:
+
+- Bundler Audit for dependency vulnerabilities
+- RuboCop security cops
+- Dependabot security updates
+
+## Local Development
+
+To run the same checks locally:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests with coverage
+bundle exec rspec
+
+# Run linting
+bundle exec rubocop
+bundle exec standardrb
+
+# Run security audit
+bundle exec bundler-audit
+
+# Build gem
+gem build ruby-maat.gemspec
+```
+
+## Triggering a Release
+
+Release Please uses **conventional commits** to automatically determine version bumps and generate changelogs:
+
+### Conventional Commit Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Commit Types
+
+- `feat:` - New features (triggers minor version bump)
+- `fix:` - Bug fixes (triggers patch version bump)
+- `feat!:` or `BREAKING CHANGE:` - Breaking changes (triggers major version bump)
+- `docs:`, `style:`, `refactor:`, `test:`, `chore:`, `ci:`, `deps:` - No version bump
+
+### Release Process
+
+1. **Make commits** using conventional commit format
+2. **Push to main/master** - Release Please analyzes commits
+3. **Review Release PR** - Automatically created when releasable changes exist
+4. **Merge Release PR** - Triggers automatic release and publication
+
+### Example Commits
+
+```bash
+git commit -m "feat(analysis): add new coupling algorithm"
+git commit -m "fix(parser): handle empty git logs correctly"
+git commit -m "docs: update CLI usage examples"
+git commit -m "feat!: change CLI argument format" # breaking change
+```
+
+### Set up commit message template
+
+```bash
+git config commit.template .gitmessage
+```
+
+## Troubleshooting
+
+### Gem Push Fails
+
+- Verify `RUBYGEMS_API_KEY` secret is set correctly
+- Ensure you have push permissions to the gem on RubyGems.org
+- Check that the gem version hasn't been published already
+
+### Test Failures
+
+- Check the CI logs for specific failure reasons
+- Ensure all dependencies are properly specified
+- Test matrix may reveal OS or Ruby version specific issues
+
+### Coverage Too Low
+
+- Add tests for uncovered code
+- Adjust minimum coverage threshold in `spec/spec_helper.rb` if needed
+- Check coverage report in the `coverage/` directory after running tests
+
+## Badge Status
+
+Add these badges to your README to show CI status:
+
+```markdown
+![CI](https://github.com/viamin/ruby-maat/workflows/CI/badge.svg)
+![Gem Version](https://badge.fury.io/rb/ruby-maat.svg)
+```

data/CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Code Maat is a command-line tool for mining and analyzing data from version control systems (VCS). It extracts insights about code evolution, developer patterns, logical coupling, and code quality metrics from Git, SVN, Mercurial, Perforce, and TFS repositories.
+
+## Build and Development Commands
+
+### Building the Project
+
+```bash
+# Build standalone JAR (primary method)
+lein uberjar
+
+# Run directly via Leiningen (for development)
+lein run -l logfile.log -c <vcs>
+
+# Build Docker image
+docker build -t code-maat-app .
+
+# Run tests
+lein test
+```
+
+### Running Code Maat
+
+```bash
+# Using standalone JAR
+java -jar code-maat-1.0.5-SNAPSHOT-standalone.jar -l logfile.log -c <vcs>
+
+# Using Docker
+docker run -v /host/path:/data -it code-maat-app -l /data/logfile.log -c <vcs>
+
+# Show help and all available analyses
+java -jar code-maat-1.0.5-SNAPSHOT-standalone.jar -h
+```
+
+### Memory Configuration
+
+Code Maat is memory-intensive. The project.clj includes these JVM options:
+
+- `-Xmx4g` (4GB heap)
+- `-Djava.awt.headless=true` (suppress AWT frames)
+- `-Xss512M` (512MB stack size)
+
+## Architecture Overview
+
+### Core Components
+
+1. **Command Line Interface** (`src/code_maat/cmd_line.clj`)
+   - Entry point and argument parsing
+   - Uses clojure.tools.cli for option handling
+
+2. **Application Core** (`src/code_maat/app/app.clj`)
+   - Main orchestration logic following pipeline pattern:
+     - Input → Parsers → Layer Mapping → Incanter Datasets → Analysis → Output
+   - Contains registry of all supported analyses
+   - Handles VCS parser selection and error recovery
+
+3. **VCS Parsers** (`src/code_maat/parsers/`)
+   - Modular parsers for different VCS systems
+   - `git2.clj` - preferred Git parser (faster, more tolerant)
+   - `git.clj` - legacy Git parser (maintained for backward compatibility)
+   - `svn.clj`, `mercurial.clj`, `perforce.clj`, `tfs.clj` - other VCS support
+
+4. **Analysis Modules** (`src/code_maat/analysis/`)
+   - Independent analysis implementations
+   - Each returns Incanter datasets
+   - Key analyses: authors, coupling, churn, code-age, communication, effort
+
+5. **Data Processing** (`src/code_maat/app/`)
+   - `grouper.clj` - maps files to architectural layers
+   - `time_based_grouper.clj` - temporal aggregation
+   - `team_mapper.clj` - maps authors to teams
+
+6. **Output** (`src/code_maat/output/`)
+   - CSV output formatting
+   - Filtering and row limiting
+
+### Supported Analyses
+
+Available via the `-a` parameter (see `supported-analysis` map in `app.clj:55`):
+
+- `authors` - developer count per module
+- `coupling` - logical coupling between modules  
+- `revisions` - revision count per entity
+- `churn` - code churn metrics (abs-churn, author-churn, entity-churn)
+- `age` - code age analysis
+- `communication` - developer communication patterns
+- `summary` - project overview statistics
+- `effort` - developer effort distribution
+
+### Data Flow
+
+1. Parse VCS log files into modification records
+2. Optional aggregation by architectural boundaries (grouping files)
+3. Optional temporal aggregation (group commits by time period)
+4. Optional team mapping (map individual authors to teams)
+5. Convert to Incanter dataset
+6. Run analysis
+7. Output results as CSV
+
+### Key Dependencies
+
+- Clojure 1.8.0
+- Incanter (statistical computing)
+- clojure.tools.cli (command line parsing)
+- clj-time (date/time handling)
+- instaparse (parsing DSL)
+
+## Testing
+
+Tests are located in `test/code_maat/` and follow the source structure. Key test categories:
+
+- Unit tests for individual analysis modules
+- End-to-end scenario tests with sample VCS data
+- Parser tests for different VCS formats
+
+Run all tests with `lein test`.
+
+## Development Notes
+
+- The codebase follows functional programming principles
+- All analysis modules are independent and composable  
+- Parsers return sequences of maps representing modifications
+- Heavy use of Incanter for dataset operations
+- Error handling with recovery points for user-friendly messages
+- Memory usage can be high for large repositories - consider date filtering

data/Dockerfile

@@ -0,0 +1,40 @@
+FROM ruby:3.3-alpine
+
+VOLUME /data
+LABEL description="Ruby Maat - A Ruby port of Code Maat for mining VCS data"
+
+ARG dest=/usr/src/ruby-maat
+
+# Install build dependencies
+RUN apk add --no-cache \
+    build-base \
+    git
+
+# Set working directory
+RUN mkdir -p $dest
+WORKDIR $dest
+
+# Copy gem files first for better caching
+COPY ruby-maat.gemspec Gemfile Gemfile.lock $dest/
+COPY lib/ruby_maat/version.rb $dest/lib/ruby_maat/
+
+# Install dependencies
+RUN bundle install --deployment --without development test
+
+# Copy the rest of the application
+COPY . $dest
+
+# Build and install the gem
+RUN gem build ruby-maat.gemspec && \
+    gem install ruby-maat-*.gem && \
+    rm -rf $dest
+
+# Create a non-root user
+RUN adduser -D -s /bin/sh ruby-maat
+USER ruby-maat
+
+# Set working directory to /data for user convenience
+WORKDIR /data
+
+ENTRYPOINT ["ruby-maat"]
+CMD ["--help"]