simplecov-mcp 1.0.0 → 2.0.0

data/docs/user/INSTALLATION.md

@@ -0,0 +1,130 @@
+# Installation Guide
+
+[Back to main README](../README.md)
+
+## Prerequisites
+
+- **Ruby >= 3.2** (required by the `mcp` dependency)
+- SimpleCov-generated `.resultset.json` file in your project
+
+## Quick Install
+
+### Via RubyGems
+
+```sh
+gem install simplecov-mcp
+```
+
+### Via Bundler
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'simplecov-mcp'
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+### From Source
+
+```sh
+git clone https://github.com/keithrbennett/simplecov-mcp.git
+cd simplecov-mcp
+bundle install
+gem build simplecov-mcp.gemspec
+gem install simplecov-mcp-*.gem
+```
+
+## Require Path
+
+The gem uses a single require path:
+
+```ruby
+require "simplecov_mcp"
+```
+
+The executable is `simplecov-mcp` (with hyphen).
+
+## PATH Configuration
+
+### With Version Managers
+
+Most version managers (rbenv, asdf, RVM, chruby) automatically configure PATH. After installation:
+
+```sh
+# Refresh shims if needed
+rbenv rehash      # rbenv
+asdf reshim ruby  # asdf
+
+# Verify executable is accessible
+which simplecov-mcp
+```
+
+**Important:** When changing Ruby versions, reinstall the gem and update any MCP configurations that use absolute paths.
+
+### Bundler Execution
+
+If PATH setup is problematic, use bundler:
+
+```sh
+bundle exec simplecov-mcp
+```
+
+This works from any project directory that has simplecov-mcp in its Gemfile.
+
+## Verification
+
+### Test Installation
+
+```sh
+# Check version
+simplecov-mcp version
+
+# Show help
+simplecov-mcp --help
+
+# Run on current project (requires coverage data)
+simplecov-mcp
+```
+
+### Generate Test Coverage
+
+If you don't have coverage data yet:
+
+```sh
+# Run your tests with SimpleCov enabled
+bundle exec rspec  # or your test command
+
+# Verify coverage file exists
+ls -l coverage/.resultset.json
+
+# Now test simplecov-mcp
+simplecov-mcp
+```
+
+## Platform-Specific Notes
+
+### macOS
+
+Works with system Ruby or any version manager. Recommended: use rbenv or asdf, not rvm (see note below).
+
+**Note:** RVM may not work in sandboxed environments (e.g., AI coding assistants) because it requires `/bin/ps`, which sandbox restrictions often block. Use rbenv or chruby instead for sandboxed environments.
+
+### Linux
+
+Works with system Ruby or any version manager.
+
+### Windows
+
+Should work with Ruby installed via RubyInstaller. PATH configuration may differ.
+
+## Next Steps
+
+- **[CLI Usage](CLI_USAGE.md)** - Learn command-line options
+- **[Library API](LIBRARY_API.md)** - Use in Ruby code
+- **[MCP Integration](MCP_INTEGRATION.md)** - Connect to AI assistants
+- **[Troubleshooting](TROUBLESHOOTING.md)** - More detailed troubleshooting

data/docs/{LIBRARY_API.md → user/LIBRARY_API.md}

@@ -1,5 +1,7 @@
 # Library API Guide
 
+[Back to main README](../README.md)
+
 Use this gem programmatically to inspect coverage without running the CLI or MCP server. The primary entry point is `SimpleCovMcp::CoverageModel`.
 
 ## Table of Contents
@@ -42,12 +44,12 @@ raw = model.raw_for("lib/foo.rb")
 
 ## Method Reference
 
-### `all_files(sort_order: :ascending)`
+### `all_files(sort_order: :descending)`
 
 Returns coverage summary for all files in the resultset.
 
 **Parameters:**
-- `sort_order` (Symbol, optional): `:ascending` (default) or `:descending` by coverage percentage
+- `sort_order` (Symbol, optional): `:descending` (default) or `:ascending` by coverage percentage
 
 **Returns:** `Array<Hash>` - See [all_files return type](#all_files)
 
@@ -74,7 +76,7 @@ Returns coverage summary for a specific file.
 **Example:**
 ```ruby
 summary = model.summary_for("lib/foo.rb")
-# => { 'file' => '/abs/.../lib/foo.rb', 'summary' => {'covered'=>12, 'total'=>14, 'pct'=>85.71}, 'stale' => false }
+# => { 'file' => '/abs/.../lib/foo.rb', 'summary' => {'covered'=>12, 'total'=>14, 'percentage'=>85.71}, 'stale' => false }
 ```
 
 ### `uncovered_for(path)`
@@ -128,13 +130,13 @@ raw = model.raw_for("lib/foo.rb")
 # => { 'file' => '/abs/.../lib/foo.rb', 'lines' => [nil, 1, 0, 3, ...], 'stale' => false }
 ```
 
-### `format_table(rows = nil, sort_order: :ascending)`
+### `format_table(rows = nil, sort_order: :descending)`
 
 Generates formatted ASCII table string.
 
 **Parameters:**
 - `rows` (Array<Hash>, optional): Custom row data; defaults to `all_files`
-- `sort_order` (Symbol, optional): `:ascending` (default) or `:descending`
+- `sort_order` (Symbol, optional): `:descending` (default) or `:ascending`
 
 **Returns:** `String` - Formatted table with Unicode borders
 
@@ -150,6 +152,46 @@ lib_table = model.format_table(lib_files, sort_order: :descending)
 puts lib_table
 ```
 
+### `project_totals(tracked_globs: nil)`
+
+Returns aggregated coverage totals across all files.
+
+**Parameters:**
+- `tracked_globs` (Array<String> or String, optional): Glob patterns to filter files
+
+**Returns:** `Hash` - See [project_totals return type](#project_totals)
+
+**Example:**
+```ruby
+totals = model.project_totals
+# => { 'lines' => { 'total' => 123, 'covered' => 100, 'uncovered' => 23 }, 'percentage' => 81.3, 'files' => { 'total' => 5, 'ok' => 4, 'stale' => 1 } }
+
+# Filter to specific directory
+lib_totals = model.project_totals(tracked_globs: 'lib/**/*.rb')
+```
+
+### `relativize(data)`
+
+Converts absolute file paths in coverage data to relative paths from project root.
+
+**Parameters:**
+- `data` (Hash or Array<Hash>): Coverage data with absolute file paths
+
+**Returns:** `Hash` or `Array<Hash>` - Same structure with relative paths
+
+**Example:**
+```ruby
+summary = model.summary_for('lib/simplecov_mcp/model.rb')
+# => { 'file' => '/home/user/project/lib/simplecov_mcp/model.rb', ... }
+
+relative_summary = model.relativize(summary)
+# => { 'file' => 'lib/simplecov_mcp/model.rb', ... }
+
+# Works with arrays too
+files = model.all_files
+relative_files = model.relativize(files)
+```
+
 ## Return Types
 
 ### `all_files`
@@ -176,7 +218,7 @@ Returns `Hash`:
   'summary' => {
     'covered' => Integer, # Number of covered lines
     'total' => Integer,   # Total relevant lines
-    'pct' => Float        # Coverage percentage (0.00-100.00)
+    'percentage' => Float        # Coverage percentage (0.00-100.00)
   }
 }
 ```
@@ -192,7 +234,7 @@ Returns `Hash`:
   'summary' => {
     'covered' => Integer,
     'total' => Integer,
-    'pct' => Float
+    'percentage' => Float
   }
 }
 ```
@@ -208,7 +250,7 @@ Returns `Hash`:
   'summary' => {
     'covered' => Integer,
     'total' => Integer,
-    'pct' => Float
+    'percentage' => Float
   }
 }
 ```
@@ -233,6 +275,26 @@ Returns `Hash`:
 }
 ```
 
+### `project_totals`
+
+Returns `Hash`:
+
+```ruby
+{
+  'lines' => {
+    'total' => Integer,      # Total relevant lines across all files
+    'covered' => Integer,    # Total covered lines
+    'uncovered' => Integer   # Total uncovered lines
+  },
+  'percentage' => Float,     # Overall coverage percentage
+  'files' => {
+    'total' => Integer,      # Total number of files
+    'ok' => Integer,         # Files with fresh coverage
+    'stale' => Integer       # Files with stale coverage
+  }
+}
+```
+
 ## Error Handling
 
 ### Exception Types
@@ -254,7 +316,7 @@ require "simplecov_mcp"
 begin
   model = SimpleCovMcp::CoverageModel.new
   summary = model.summary_for("lib/foo.rb")
-  puts "Coverage: #{summary['summary']['pct']}%"
+  puts "Coverage: #{summary['summary']['percentage']}%"
 rescue SimpleCovMcp::FileError => e
   puts "File not in coverage data: #{e.message}"
 rescue SimpleCovMcp::ResultsetNotFoundError => e
@@ -313,7 +375,7 @@ summary = find_coverage(model, [
 ])
 
 if summary
-  puts "Coverage: #{summary['summary']['pct']}%"
+  puts "Coverage: #{summary['summary']['percentage']}%"
 else
   puts "File not found in coverage data"
 end
@@ -340,8 +402,8 @@ results = files_to_check.map do |path|
     summary = model.summary_for(path)
     {
       file: path,
-      coverage: summary['summary']['pct'],
-      status: summary['summary']['pct'] >= 80 ? :ok : :low
+      coverage: summary['summary']['percentage'],
+      status: summary['summary']['percentage'] >= 80 ? :ok : :low
     }
   rescue SimpleCovMcp::FileError
     {
@@ -425,25 +487,19 @@ validator.validate!
 require "simplecov_mcp"
 
 model = SimpleCovMcp::CoverageModel.new
-files = model.all_files
 
-# Calculate coverage by directory
-by_directory = files.group_by do |file|
-  # Get first two path components (e.g., "lib/services")
-  file['file'].split('/')[0..1].join('/')
-end
+# Calculate coverage by directory using the totals API
+patterns = %w[lib/simplecov_mcp/tools/**/*.rb lib/simplecov_mcp/commands/**/*.rb lib/simplecov_mcp/presenters/**/*.rb]
 
-directory_stats = by_directory.map do |dir, dir_files|
-  total_lines = dir_files.sum { |f| f['total'] }
-  covered_lines = dir_files.sum { |f| f['covered'] }
-  percentage = (covered_lines.to_f / total_lines * 100).round(2)
+directory_stats = patterns.map do |pattern|
+  totals = model.project_totals(tracked_globs: pattern)
 
   {
-    directory: dir,
-    files: dir_files.length,
-    coverage: percentage,
-    covered: covered_lines,
-    total: total_lines
+    directory: pattern,
+    files: totals['files']['total'],
+    coverage: totals['percentage'].round(2),
+    covered: totals['lines']['covered'],
+    total: totals['lines']['total']
   }
 end
 
@@ -545,6 +601,7 @@ class CoverageReporter
 
   def generate_markdown_report(output_path)
     files = @model.all_files
+    totals = @model.project_totals
 
     File.open(output_path, 'w') do |f|
       f.puts "# Coverage Report"
@@ -553,13 +610,14 @@ class CoverageReporter
       f.puts
 
       # Overall stats
-      total_lines = files.sum { |file| file['total'] }
-      covered_lines = files.sum { |file| file['covered'] }
-      overall_pct = (covered_lines.to_f / total_lines * 100).round(2)
+      overall_percentage = totals['percentage']
+      total_lines = totals['lines']['total']
+      covered_lines = totals['lines']['covered']
+      total_files = totals['files']['total']
 
-      f.puts "## Overall Coverage: #{overall_pct}%"
+      f.puts "## Overall Coverage: #{overall_percentage}%"
       f.puts
-      f.puts "- Total Files: #{files.length}"
+      f.puts "- Total Files: #{total_files}"
       f.puts "- Total Lines: #{total_lines}"
       f.puts "- Covered Lines: #{covered_lines}"
       f.puts

data/docs/{MCP_INTEGRATION.md → user/MCP_INTEGRATION.md}

@@ -1,6 +1,6 @@
 # MCP Integration Guide
 
-This guide covers setting up simplecov-mcp as an MCP (Model Context Protocol) server for AI coding assistants.
+[Back to main README](../README.md)
 
 ## Table of Contents
 
@@ -213,7 +213,7 @@ For any MCP client that uses JSON configuration:
 
 ### Tool Catalog
 
-simplecov-mcp exposes 8 MCP tools:
+simplecov-mcp exposes 10 MCP tools:
 
 | Tool | Purpose | Key Parameters |
 |------|---------|----------------|
@@ -222,8 +222,10 @@ simplecov-mcp exposes 8 MCP tools:
 | `coverage_raw_tool` | Raw SimpleCov array | `path` |
 | `uncovered_lines_tool` | List uncovered lines | `path` |
 | `all_files_coverage_tool` | Project-wide coverage | `sort_order`, `tracked_globs` |
+| `coverage_totals_tool` | Aggregated line totals | `tracked_globs` |
 | `coverage_table_tool` | Formatted coverage table | `sort_order` |
-| `help_tool` | Tool discovery | `query` (optional) |
+| `validate_tool` | Validate coverage policies | `code` or `file` |
+| `help_tool` | Tool discovery | (none) |
 | `version_tool` | Version information | (none) |
 
 ### JSON Response Format
@@ -234,7 +236,7 @@ For tools that return structured data, `simplecov-mcp` serializes the data as a
 ```json
 {
   "type": "text",
-  "text": "{"coverage_summary":{"covered":10,"total":20,"pct":50.0}}"
+  "text": "{"coverage_summary":{"covered":10,"total":20,"percentage":50.0}}"
 }
 ```
 
@@ -255,8 +257,8 @@ All file-specific tools accept these parameters:
 - `path` (required for file tools) - File path (relative or absolute)
 - `root` (optional) - Project root directory (default: `.`)
 - `resultset` (optional) - Path to the `.resultset.json` file. See [Configuring the Resultset](../README.md#configuring-the-resultset) for details.
-- `stale` (optional) - Staleness mode: `"off"` (default) or `"error"`
-- `error_mode` (optional) - Error handling: `"off"`, `"on"` (default), `"trace"`
+- `staleness` (optional) - Staleness mode: `"off"` (default) or `"error"`
+- `error_mode` (optional) - Error handling: `"off"`, `"log"` (default), `"debug"`
 
 ### Tool Details
 
@@ -266,7 +268,7 @@ These tools analyze individual files. All require `path` parameter.
 
 **`coverage_summary_tool`** - Covered/total/percentage summary
 ```json
-{"file": "...", "summary": {"covered": 12, "total": 14, "pct": 85.71}, "stale": false}
+{"file": "...", "summary": {"covered": 12, "total": 14, "percentage": 85.71}, "stale": false}
 ```
 
 **`uncovered_lines_tool`** - List uncovered line numbers
@@ -290,13 +292,27 @@ These tools analyze individual files. All require `path` parameter.
 - Parameters: `sort_order` (`ascending`|`descending`), `tracked_globs` (array)
 - Returns: `{"files": [...], "counts": {"total": N, "ok": N, "stale": N}}`
 
+**`coverage_totals_tool`** - Aggregated line totals
+- Parameters: `tracked_globs` (array), `staleness`
+- Returns: `{"lines":{"total":N,"covered":N,"uncovered":N},"percentage":Float,"files":{"total":N,"ok":N,"stale":N}}`
+
 **`coverage_table_tool`** - Formatted ASCII table
 - Parameters: `sort_order` (`ascending`|`descending`)
 - Returns: Plain text table
 
+#### Policy Validation Tools
+
+**`validate_tool`** - Validate coverage against custom policies
+- Parameters: Either `code` (Ruby string) OR `file` (path to Ruby file), plus optional `root`, `resultset`, `staleness`, `error_mode`
+- Returns: `{"result": Boolean}` where `true` means policy passed, `false` means failed
+- Security Warning: Predicates execute as arbitrary Ruby code with full system privileges. Only use predicate files from trusted sources.
+- Examples:
+  - Check if all files have at least 80% coverage: `{"code": "->(m) { m.all_files.all? { |f| f['percentage'] >= 80 } }"}`
+  - Run coverage policy from file: `{"file": "coverage_policy.rb"}`
+
 #### Utility Tools
 
-**`help_tool`** - Tool discovery (optional `query` parameter)
+**`help_tool`** - Tool discovery
 **`version_tool`** - Version information
 
 ## Example Prompts for AI Assistants
@@ -396,18 +412,7 @@ tail -f simplecov_mcp.log
 grep ERROR simplecov_mcp.log | tail -20
 ```
 
-**Configure custom log location** when adding the server:
-
-```sh
-# Claude Code
-claude mcp add simplecov-mcp simplecov-mcp --log-file /var/log/simplecov.log
-
-# Codex
-codex mcp add simplecov-mcp --command simplecov-mcp --args "--log-file" --args "/var/log/simplecov.log"
-
-# Log to stderr (Claude)
-claude mcp add simplecov-mcp simplecov-mcp --log-file stderr
-```
+To override the default log file location, specify the `--log-file` argument wherever and however you configure your MCP server. For example, to log to a different file path, include `--log-file /path/to/logfile.log` in your server configuration. To log to standard error, use `--log-file stderr`.
 
 **Note:** Logging to `stdout` is not permitted in MCP mode.
 
@@ -415,17 +420,13 @@ claude mcp add simplecov-mcp simplecov-mcp --log-file stderr
 
 ### CLI Fallback
 
-**Important:** If the MCP server doesn't work, use CLI commands with `--json` for structured output:
-
-```sh
-simplecov-mcp summary lib/file.rb --json      # coverage_summary_tool
-simplecov-mcp uncovered lib/file.rb --json    # uncovered_lines_tool
-simplecov-mcp detailed lib/file.rb --json     # coverage_detailed_tool
-simplecov-mcp list --json                      # all_files_coverage_tool
-simplecov-mcp version --json                   # version_tool
-```
+**Important:** If the MCP server doesn't work, you can use the CLI directly with the `-fJ` flag.
 
-See [CLI Usage](CLI_USAGE.md) for complete documentation.
+See the **[CLI Fallback for LLMs Guide](CLI_FALLBACK_FOR_LLMS.md)** for:
+- Complete command reference and MCP tool mappings
+- Sample prompt to give your LLM
+- JSON output examples
+- Tips for using CLI as an MCP alternative
 
 ### Common Issues
 
@@ -461,13 +462,13 @@ For troubleshooting, add error mode when configuring the server:
 
 ```sh
 # Claude Code
-claude mcp add simplecov-mcp simplecov-mcp --error-mode trace
+claude mcp add simplecov-mcp simplecov-mcp --error-mode debug
 
 # Codex
-codex mcp add simplecov-mcp --command simplecov-mcp --args "--error-mode" --args "trace"
+codex mcp add simplecov-mcp --command simplecov-mcp --args "--error-mode" --args "debug"
 
 # Gemini
-gemini mcp add simplecov-mcp "$(which simplecov-mcp) --error-mode trace"
+gemini mcp add simplecov-mcp "$(which simplecov-mcp) --error-mode debug"
 ```
 
 ### Project-Specific vs. Global Configuration
@@ -483,6 +484,7 @@ gemini mcp add simplecov-mcp "$(which simplecov-mcp) --error-mode trace"
 
 ## Next Steps
 
-- **[CLI Usage](CLI_USAGE.md)** - Alternative to MCP for direct queries
+- **[CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md)** - Using CLI when MCP isn't available
+- **[CLI Usage](CLI_USAGE.md)** - Complete CLI reference
 - **[Examples](EXAMPLES.md)** - Example prompts and workflows
 - **[Troubleshooting](TROUBLESHOOTING.md)** - Detailed troubleshooting guide

data/docs/user/README.md

@@ -0,0 +1,14 @@
+# User Documentation
+
+Guides for installing, configuring, and using SimpleCov MCP in day-to-day
+workflows.
+
+- [Installation](INSTALLATION.md) – environment setup across platforms
+- [CLI Usage](CLI_USAGE.md) – command reference with examples
+- [Examples](EXAMPLES.md) – common coverage workflows
+- [Advanced Usage](ADVANCED_USAGE.md) – resultset paths, staleness, predicates
+- [Error Handling](ERROR_HANDLING.md) – modes, exceptions, logging
+- [MCP Integration](MCP_INTEGRATION.md) – configuring AI assistants
+- [CLI Fallback for LLMs](CLI_FALLBACK_FOR_LLMS.md) – when MCP isn't available
+- [Library API](LIBRARY_API.md) – embedding the gem in Ruby code
+- [Troubleshooting](TROUBLESHOOTING.md) – diagnostics for common issues