simplecov-mcp 1.0.1 → 2.0.0

data/docs/dev/RELEASING.md

@@ -0,0 +1,146 @@
+# Release Process
+
+This document provides a checklist for releasing new versions of simplecov-mcp.
+
+## Pre-Release Checklist
+
+### 1. Documentation Review
+
+- [ ] **RELEASE_NOTES.md**: Update version header
+  - Update the version section header to final version (e.g., `## v#{version}`)
+  - For major releases: Ensure all breaking changes are documented with migration examples
+  - Verify new features and bug fixes are listed
+
+- [ ] **README.md**: Verify examples and feature list are current
+
+- [ ] **Documentation**: Ensure all docs in `docs/` are up to date
+
+### 2. Code Quality
+
+- [ ] **Tests**: All tests passing (`bundle exec rspec`)
+  - Verify via git hooks or run manually
+  - Check coverage is still excellent (>95%)
+
+- [ ] **Linting**: No Rubocop violations (`bundle exec rubocop`)
+  - Verify via git hooks or run manually
+
+- [ ] **Version**: Update `lib/simplecov_mcp/version.rb` to release version
+  - Remove `.pre.X` suffix for stable releases
+
+### 3. Cleanup
+
+- [ ] **Untracked files**: Review `git status` for files that should be:
+  - Added to `.gitignore` (temp files, local experiments, AI reports)
+  - Committed (valuable documentation or examples)
+  - Deleted (obsolete files)
+
+- [ ] **Temporary files**: Remove or ignore:
+  - `*.txt` files (r.txt, rubocop.txt, todo.txt, etc.)
+  - Experimental config files (`.rubocop.yml.new`, etc.)
+  - Local notes (CODING_AGENT_NOTES.md, architecture_insights.md, etc.)
+  - Work-in-progress directories (screencast/, untracked-ai-reports/, etc.)
+
+### 4. Build Verification
+
+- [ ] **Build gem**: Verify gem builds without errors
+```bash
+gem build simplecov-mcp.gemspec
+```
+
+- [ ] **Test installation**: Install and test locally
+```bash
+gem install simplecov-mcp-*.gem
+simplecov-mcp --version
+simplecov-mcp --help
+# Test on actual project
+cd /path/to/test/project
+simplecov-mcp list
+```
+
+### 5. Git Release
+
+- [ ] **Commit changes**: Commit version bump and RELEASE_NOTES.md updates
+```bash
+git add lib/simplecov_mcp/version.rb RELEASE_NOTES.md
+git commit -m "Release version #{version}"
+```
+
+- [ ] **Create tag**: Tag the release
+```bash
+git tag -a v#{version} -m "Version #{version}"
+```
+
+- [ ] **Push**: Push commits and tags
+```bash
+git push origin main --follow-tags
+```
+
+### 6. Publish Gem
+
+- [ ] **Build final gem**: Build from tagged version
+```bash
+gem build simplecov-mcp.gemspec
+```
+
+- [ ] **Push to RubyGems**: Publish the gem
+```bash
+gem push simplecov-mcp-#{version}.gem
+```
+
+- [ ] **Verify publication**: Check gem appears on RubyGems.org
+  - Visit https://rubygems.org/gems/simplecov-mcp
+  - Verify new version is listed
+  - Check that documentation links work
+
+### 7. GitHub Release
+
+- [ ] **Create GitHub release**: Go to https://github.com/keithrbennett/simplecov-mcp/releases/new
+  - Select the tag you just pushed
+  - Title: `Version #{version}`
+  - Description: Copy relevant sections from RELEASE_NOTES.md
+  - Attach the `.gem` file (optional)
+
+### 8. Post-Release
+
+- [ ] **Announcement**: Consider announcing on:
+  - Ruby Weekly
+  - Reddit (r/ruby)
+  - Slack/Discord communities
+  - Social media
+
+- [ ] **Update dependencies**: For projects using this gem
+  - Update your own projects to use new version
+  - Test integration
+
+- [ ] **Prepare for next release**:
+  - Optionally create a new section in RELEASE_NOTES.md for next version
+  - Consider bumping to next pre-release version if starting new development cycle
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **Major (X.0.0)**: Breaking changes
+- **Minor (0.X.0)**: New features, backward compatible
+- **Patch (0.0.X)**: Bug fixes, backward compatible
+- **Pre-release (X.Y.Z.pre.N)**: Development versions
+
+## Rollback Procedure
+
+If a critical issue is discovered after release:
+
+1. **Yank the gem** (removes from RubyGems but preserves install history):
+```bash
+gem yank simplecov-mcp -v #{version}
+```
+
+2. **Fix the issue** in a new patch version
+
+3. **Release the fixed version** following this checklist
+
+4. **Communicate**: Update GitHub release notes and announce the issue + fix
+
+## Notes
+
+- GitHub Actions runs tests and Rubocop on every commit (via hooks)
+- Pre-commit hooks ensure code quality before commits

data/docs/{arch-decisions → dev/arch-decisions}/001-x-arch-decision.md

@@ -1,5 +1,7 @@
 # ADR 001: Dual-Mode Operation (CLI and MCP Server)
 
+[Back to main README](../../README.md)
+
 ## Status
 
 Accepted
@@ -40,7 +42,7 @@ The implementation is in `lib/simplecov_mcp.rb:34-52`:
 
 ```ruby
 def run(argv)
-  env_opts = parse_env_opts_for_mode_detection
+  env_opts = extract_env_opts
   full_argv = env_opts + argv
 
   if ModeDetector.cli_mode?(full_argv)

data/docs/{arch-decisions → dev/arch-decisions}/002-x-arch-decision.md

@@ -1,5 +1,7 @@
 # ADR 002: Context-Aware Error Handling Strategy
 
+[Back to main README](../../README.md)
+
 ## Status
 
 Accepted
@@ -56,9 +58,9 @@ The `ErrorHandler` class (lib/simplecov_mcp/error_handler.rb:7) provides configu
 class ErrorHandler
   attr_accessor :error_mode, :logger
 
-  VALID_ERROR_MODES = [:off, :on, :trace].freeze
+  VALID_ERROR_MODES = [:off, :log, :debug].freeze
 
-  def initialize(error_mode: :on, logger: nil)
+  def initialize(error_mode: :log, logger: nil)
     @error_mode = error_mode
     @logger = logger
   end
@@ -84,7 +86,7 @@ The `ErrorHandlerFactory` (lib/simplecov_mcp/error_handler_factory.rb:4) creates
 
 ```ruby
 module ErrorHandlerFactory
-  def self.for_cli(error_mode: :on)
+  def self.for_cli(error_mode: :log)
     ErrorHandler.new(error_mode: error_mode)
   end
 
@@ -92,8 +94,8 @@ module ErrorHandlerFactory
     ErrorHandler.new(error_mode: :off)  # No logging
   end
 
-  def self.for_mcp_server(error_mode: :on)
-    ErrorHandler.new(error_mode: :on)   # Logs to file
+  def self.for_mcp_server(error_mode: :log)
+    ErrorHandler.new(error_mode: :log)   # Logs to file
   end
 end
 ```

data/docs/{arch-decisions → dev/arch-decisions}/003-x-arch-decision.md

@@ -1,5 +1,7 @@
 # ADR 003: Coverage Staleness Detection
 
+[Back to main README](../../README.md)
+
 ## Status
 
 Accepted

data/docs/{arch-decisions → dev/arch-decisions}/004-x-arch-decision.md

@@ -1,5 +1,7 @@
 # ADR 004: Ruby `instance_eval` for Success Predicates
 
+[Back to main README](../../README.md)
+
 ## Status
 
 Accepted
@@ -90,7 +92,7 @@ def run_success_predicate
   exit(result ? 0 : 1)  # 0 = success, 1 = failure
 rescue => e
   warn "Success predicate error: #{e.message}"
-  warn e.backtrace.first(5).join("\n") if config.error_mode == :trace
+  warn e.backtrace.first(5).join("\n") if config.error_mode == :debug
   exit 2  # Exit code 2 for predicate errors
 end
 ```
@@ -126,7 +128,9 @@ end
 ```
 
 **Class example:**
+
 ```ruby
+
 class CoveragePolicy
   def call(model)
     api_files = model.all_files.select { |f| f['file'].start_with?('lib/api/') }
@@ -134,7 +138,7 @@ class CoveragePolicy
   end
 end
 
-CoveragePolicy.new
+AllFilesAboveThreshold.new
 ```
 
 The predicate receives a full `CoverageModel` instance with access to:

data/docs/{arch-decisions → dev/arch-decisions}/005-x-arch-decision.md

@@ -1,5 +1,7 @@
 # ADR 005: No SimpleCov Runtime Dependency
 
+[Back to main README](../../README.md)
+
 ## Status
 
 Replaced – simplecov-mcp now requires SimpleCov at runtime so that multi-suite resultsets can be merged using SimpleCov’s combine helpers.
@@ -71,8 +73,8 @@ def summary(arr)
     total += 1
     covered += 1 if hits.to_i > 0
   end
-  pct = total.zero? ? 100.0 : ((covered.to_f * 100.0 / total) * 100).round / 100.0
-  { 'covered' => covered, 'total' => total, 'pct' => pct }
+  percentage = total.zero? ? 100.0 : ((covered.to_f * 100.0 / total) * 100).round / 100.0
+  { 'covered' => covered, 'total' => total, 'percentage' => percentage }
 end
 
 def uncovered(arr)

data/docs/{arch-decisions → dev/arch-decisions}/README.md

@@ -1,6 +1,6 @@
 # Architecture Decision Records
 
-This directory contains Architecture Decision Records (ADRs) for the SimpleCov MCP project.
+[Back to main README](../../README.md)
 
 ## What is an ADR?
 
@@ -20,10 +20,10 @@ A short phrase describing the decision (e.g., "Dual-Mode Operation: CLI and MCP
 - **Superseded**: Replaced by a newer decision
 
 ### Context
-The background, problem statement, and constraints that led to this decision. This section answers "Why did we need to make a decision here?"
+The background, problem statement, and constraints that led to the decision.
 
 ### Decision
-The architectural decision that was made. This section answers "What did we decide to do?"
+The architectural choice that was made.
 
 ### Consequences
 The implications of this decision, both positive and negative. This includes:

data/docs/{presentations → dev/presentations}/simplecov-mcp-presentation.md

@@ -1,3 +1,5 @@
+[Back to main README](../../README.md)
+
 ---
 marp: true
 theme: default
@@ -69,24 +71,17 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_s
 
 ## MCP Tools (Functions) Available
 
-| Tool                      | Purpose |
-|---------------------------|---------|
-| `all_files_coverage_tool` | Project-wide coverage data |
-| `coverage_detailed_tool`  | Per-line hit counts |
-| `coverage_summary_tool`   | Get coverage % for a file |
-| `coverage_table_tool`     | Formatted coverage table |
-| `uncovered_lines_tool`    | Find missing test coverage |
-
-| Tool                    | Purpose                    | Example Command                                     |
-|-------------------------|----------------------------|-----------------------------------------------------|
-| all_files_coverage_tool | Project-wide coverage data | simplecov-mcp all-files                             |
-| coverage_detailed_tool  | Per-line hit counts        | simplecov-mcp detailed lib/simplecov_mcp/model.rb  |
-| coverage_raw_tool       | Raw SimpleCov lines array  | simplecov-mcp raw lib/simplecov_mcp/model.rb       |
-| coverage_summary_tool   | Get coverage % for a file  | simplecov-mcp summary lib/simplecov_mcp/model.rb   |
-| coverage_table_tool     | Formatted coverage table   | simplecov-mcp table                                 |
-| help_tool               | Tool usage guidance        | simplecov-mcp help                                  |
-| uncovered_lines_tool    | Find missing test coverage | simplecov-mcp uncovered lib/simplecov_mcp/model.rb |
-| version_tool            | Display version info       | simplecov-mcp version                               |
+| Tool                      | Purpose                    | Example CLI Command                                  |
+|---------------------------|----------------------------|------------------------------------------------------|
+| `all_files_coverage_tool` | Project-wide coverage data | `simplecov-mcp list`                                 |
+| `coverage_detailed_tool`  | Per-line hit counts        | `simplecov-mcp detailed lib/simplecov_mcp/model.rb`  |
+| `coverage_raw_tool`       | Raw SimpleCov lines array  | `simplecov-mcp raw lib/simplecov_mcp/model.rb`       |
+| `coverage_summary_tool`   | Get coverage % for a file  | `simplecov-mcp summary lib/simplecov_mcp/model.rb`   |
+| `coverage_table_tool`     | Formatted coverage table   | `simplecov-mcp list`                                 |
+| `coverage_totals_tool`    | Aggregated line totals     | `simplecov-mcp totals`                               |
+| `help_tool`               | Tool usage guidance        | `simplecov-mcp --help`                               |
+| `uncovered_lines_tool`    | Find missing test coverage | `simplecov-mcp uncovered lib/simplecov_mcp/cli.rb`   |
+| `version_tool`            | Display version info       | `simplecov-mcp version`                              |
 
 ---
 
@@ -104,7 +99,17 @@ simplecov-mcp summary lib/simplecov_mcp/cli.rb
 simplecov-mcp uncovered lib/simplecov_mcp/cli.rb --source=uncovered --source-context 3
 
 # JSON for scripts
-simplecov-mcp --json | jq '.files[] | select(.percentage < 80)'
+simplecov-mcp -fJ | jq '.files[] | select(.percentage < 80)'
+
+# Ruby alternative:
+simplecov-mcp -fJ | ruby -r json -e '
+  JSON.parse($stdin.read)["files"].select { |f| f["percentage"] < 80 }.each do |f|
+    puts JSON.pretty_generate(f)
+  end
+'
+
+# Rexe alternative:
+simplecov-mcp -fJ | rexe -ij -mb -oJ 'self["files"].select { |f| f["percentage"] < 80 }'
 ```
 
 ---
@@ -119,7 +124,7 @@ simplecov-mcp --resultset coverage-all/
 simplecov-mcp --sort-order d
 
 # Staleness checking (file newer than coverage?)
-simplecov-mcp --stale error
+simplecov-mcp --staleness error
 
 # Track new files missing from coverage
 simplecov-mcp --tracked-globs "lib/**/tools/*.rb"
@@ -155,7 +160,7 @@ puts "Missing lines: #{uncovered['uncovered'].inspect}"
 ## Custom Threshold Git Pre-Commit Hook
 
 ```ruby
-require_relative 'lib/simple_cov_mcp'
+require 'simplecov_mcp'
 
 files = SimpleCovMcp::CoverageModel.new.all_files
 critical, other = files.partition { |f| f['file'].include?('/lib/critical/') }
@@ -177,7 +182,7 @@ end
 ## Architecture Overview
 
 ```
-lib/simple_cov_mcp
+lib/simplecov_mcp
 ├── base_tool.rb
 ├── cli.rb
 ├── error_handler_factory.rb
@@ -193,6 +198,7 @@ lib/simple_cov_mcp
 │ ├── coverage_raw_tool.rb
 │ ├── coverage_summary_tool.rb
 │ ├── coverage_table_tool.rb
+│ ├── coverage_totals_tool.rb
 │ ├── help_tool.rb
 │ ├── uncovered_lines_tool.rb
 │ └── version_tool.rb

data/docs/fixtures/demo_project/README.md

@@ -0,0 +1,9 @@
+# Demo project fixture
+
+This small demo project powers the documentation examples that rely on partial coverage and tracked globs.
+
+- Location: `docs/fixtures/demo_project`
+- Resultset: `.resultset.json` in this directory
+- Suggested alias for docs: `alias smcp='simplecov-mcp --root docs/fixtures/demo_project'`
+
+Files include controllers, models, payments services, background jobs, and an API client. A few files are intentionally missing from the resultset so the `--tracked-globs` examples surface gaps.