Requirements

• Ruby >= 3.2 (required by mcp gem dependency)
• SimpleCov-generated .resultset.json file
• simplecov gem >= 0.21

SimpleCov Dependency

cov-loupe declares a runtime dependency on simplecov (>= 0.21) to support multi-suite merging using SimpleCov's combine helpers. The dependency is lazy-loaded only when needed, ensuring fast startup for single-suite projects.

Installation

gem install cov-loupe

Fail build if coverage is stale (--raise-on-stale or -S)

cov-loupe --raise-on-stale true list || exit 1

Clone and setup

git clone https://github.com/keithrbennett/cov-loupe.git cd cov-loupe bundle install

Build and install

gem build cov-loupe.gemspec gem install cov-loupe-*.gem ```

See dev/DEVELOPMENT.md for more.

Practical Use Cases

• Query coverage data from AI assistants, e.g.:
• "Using cov-loupe, analyze test coverage data and write a report to a markdown file containing a free text analysis of each issue and then two tables, one sorted in descending order of urgency, the other in ascending order of level of effort."
• "Using cov-loupe, generate a table of directories and their average coverage rates, in ascending order of coverage."
• Find files with the lowest coverage
• Investigate specific files or directories
• Generate CI/CD coverage reports
• Create custom pass/fail predicates for scripts and CI - use the library API or CLI JSON output to implement arbitrarily complex coverage rules beyond simple thresholds (e.g., require higher coverage for critical paths, exempt test utilities, track coverage trends)

Quick Start

Basic Usage

CLI - View Coverage Table: ```sh cov-loupe

Configuring the Resultset

cov-loupe automatically searches for .resultset.json in standard locations (coverage/.resultset.json, .resultset.json, tmp/.resultset.json). For non-standard locations:

```sh

Command-line option (highest priority) - use -r or --resultset

cov-loupe -r /path/to/your/coverage

Environment variable (project-wide default)

export COV_LOUPE_OPTS="-r /path/to/your/coverage"

MCP server configuration

Add to your MCP client config (used as defaults for MCP tools):

Best Practice: Match SimpleCov Configuration

For accurate coverage tracking and validation, set COV_LOUPE_OPTS to match your SimpleCov track_files patterns:

```ruby

In your shell config (.bashrc, .zshrc, etc.)

export COV_LOUPE_OPTS="--tracked-globs lib/**/.rb,app/*/*.rb" ```

This ensures list and totals output matches SimpleCov's scope and missing_tracked_files (in list) / missing_from_coverage (in totals) report meaningful gaps.

Note: By default, --tracked-globs is empty (shows all files in the resultset). This prevents silently hiding coverage data that doesn't match assumed patterns.

Boolean CLI Options

Boolean flags such as --color (short: -C) and --raise-on-stale (short: -S) require explicit boolean arguments. Recognized literals:

Each row lists the equivalent true token (left) and false token (right).

cov-loupe --color false        # disable ANSI colors explicitly
cov-loupe -C false             # short form
cov-loupe --raise-on-stale yes # enforce stale coverage failures

Common Workflows

CI/CD Integration

```sh

Troubleshooting

• "command not found" - See Installation Guide
• "cannot load such file -- mcp" - Requires Ruby >= 3.2. Verify: ruby -v
• "Could not find .resultset.json" - Ensure SimpleCov is configured in your test suite, then run tests to generate coverage. See the Configuring the Resultset section for more details.
• MCP server won't connect - Check PATH and Ruby version in MCP Troubleshooting
• RVM in sandboxed environments (macOS) - RVM requires /bin/ps which may be blocked by sandbox restrictions. Use rbenv or chruby instead.

For more detailed help, see the full Troubleshooting Guide.