cov-loupe 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59634d5c998df34ccad24447f4cd4d64d6684f7585e2e8749905344b6e532b81
+  data.tar.gz: 298f4cab2b8cbc0b837d5a47504851fcc6d5137202daff68f640e6e92ca04c0d
+SHA512:
+  metadata.gz: c4cbe5d778fde90a412d27710eb9c022b3be1e77dd520cb3b263076e9ee36f5ce8e6bd65a2654048ca22e1073f77ec81dcf79e2615babeace4d3c41678ace3b2
+  data.tar.gz: 39de9d95a5665fb0caafb78090768cfa0f5b72b4572c312a340f8a23f1880dff24ffdf76374206610f5d31426628025a042db31e1c97541b7da136478984e1e3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Keith Bennett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,329 @@
+<!-- Invisible SEO-friendly H1 -->
+<h1 style="position:absolute; left:-9999px; top:auto; width:1px; height:1px; overflow:hidden;">
+  CovLoupe
+</h1>
+
+<p style="text-align:center; margin-bottom:-36px;">
+  <img src="dev/images/cov-loupe-logo.png" alt="CovLoupe logo" width="560">
+</p>
+
+<p style="text-align:center;">
+  An MCP server, command line utility, and library for Ruby SimpleCov test coverage analysis.
+
+
+[![Gem Version](https://badge.fury.io/rb/cov-loupe.svg)](https://badge.fury.io/rb/cov-loupe)
+
+## What is cov-loupe?
+
+**cov-loupe** makes SimpleCov coverage data queryable and actionable through three interfaces:
+
+- **MCP server** - Lets AI assistants analyze your coverage
+- **CLI** - Fast command-line coverage reports and queries
+- **Ruby library** - Programmatic API for custom tooling
+
+Works with any SimpleCov-generated `.resultset.json` file—no runtime dependency on your test suite.
+
+### Key Features
+
+- ✅ **Multiple interfaces** - MCP server, CLI, and Ruby API
+- **Annotated source code** - `--source full|uncovered` with `--context-lines N` for context lines
+- ✅ **Staleness detection** - Identify outdated coverage (missing files, timestamp mismatches, line count changes)
+- ✅ **Multi-suite support** - Automatic merging of multiple test suites (RSpec + Cucumber, etc.)
+- ✅ **Flexible path resolution** - Works with absolute or relative paths
+- ✅ **Comprehensive error handling** - Context-aware messages for each mode
+- ⚠️ **Branch coverage limitation** - Branch-level metrics are collapsed to per-line totals. Use native SimpleCov reports for branch-by-branch analysis.
+
+### 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
+
+### Installation
+
+```sh
+gem install cov-loupe
+```
+
+### Generate Coverage Data
+
+```sh
+# Run your tests with SimpleCov enabled
+bundle exec rspec  # or your test command
+
+# Verify coverage was generated
+ls -l coverage/.resultset.json
+```
+
+### Basic Usage
+
+**CLI - View Coverage Table:**
+```sh
+cov-loupe
+```
+
+**CLI - Check Specific File:**
+```sh
+cov-loupe summary lib/cov_loupe/model.rb
+cov-loupe uncovered lib/cov_loupe/cli.rb
+```
+
+**CLI - Find the Project Homepage Fast:**
+Run `cov-loupe -h` and the banner's second line shows the repository URL. Some terminal applications (e.g. iTerm2) will enable direct clicking the link using modifier keys such as `Cmd` or `Alt`.
+```
+Usage:      cov-loupe [options] [subcommand] [args]
+Repository: https://github.com/keithrbennett/cov-loupe  # <--- Project URL ---
+```
+
+**Ruby Library:**
+```ruby
+require "cov_loupe"
+
+model = CovLoupe::CoverageModel.new
+files = model.all_files
+# => [{ "file" => "lib/cov_loupe/model.rb", "covered" => 114, "total" => 118, "percentage" => 96.61, "stale" => false }, ...]
+
+summary = model.summary_for("lib/cov_loupe/model.rb")
+# => { "file" => "lib/cov_loupe/model.rb", "summary" => { "covered" => 114, "total" => 118, "percentage" => 96.61 }, "stale" => false }
+```
+
+**MCP Server:**
+See [MCP Integration Guide](docs/user/MCP_INTEGRATION.md) for AI assistant setup.
+
+## Multi-Suite Coverage Merging
+
+### How It Works
+
+When a `.resultset.json` file contains multiple test suites (e.g., RSpec + Cucumber), `cov-loupe` automatically merges them using SimpleCov's combine logic. All covered files from every suite become available to the CLI, library, and MCP tools.
+
+**Performance:** Single-suite projects avoid loading SimpleCov at runtime. Multi-suite resultsets trigger a lazy SimpleCov load only when needed, keeping the tool fast for the simpler coverage configurations.
+
+### Current Limitations
+
+**Staleness checks:** When suites are merged, we keep a single "latest suite" timestamp. This matches prior behavior but may under-report stale files if only some suites were re-run after a change. A per-file timestamp refinement is planned. Until then, consider multi-suite staleness checks advisory rather than definitive.
+
+**Multiple resultset files:** Only suites stored inside a *single* `.resultset.json` are merged automatically. If your project produces separate resultset files (e.g., different CI jobs writing `coverage/job1/.resultset.json`, `coverage/job2/.resultset.json`), you must merge them yourself before pointing `cov-loupe` at the combined file.
+
+## Documentation
+
+**Getting Started:**
+- [Installation](docs/user/INSTALLATION.md) - Setup for different environments
+- [CLI Usage](docs/user/CLI_USAGE.md) - Command-line reference
+- [Examples](docs/user/EXAMPLES.md) - Common use cases
+
+**Advanced Usage:**
+- [MCP Integration](docs/user/MCP_INTEGRATION.md) - AI assistant configuration
+- [CLI Fallback for LLMs](docs/user/CLI_FALLBACK_FOR_LLMS.md) - Using CLI when MCP isn't available
+- [Library API](docs/user/LIBRARY_API.md) - Ruby API documentation
+- [Advanced Usage](docs/user/ADVANCED_USAGE.md) - Staleness detection, error modes, path resolution
+- [Error Handling](docs/user/ERROR_HANDLING.md) - Error modes and exceptions
+
+**Reference:**
+- [Architecture](docs/dev/ARCHITECTURE.md) - Design and internals
+- [Branch Coverage](docs/dev/BRANCH_ONLY_COVERAGE.md) - Branch coverage limitations
+- [Troubleshooting](docs/user/TROUBLESHOOTING.md) - Common issues
+- [Development](docs/dev/DEVELOPMENT.md) - Contributing guide
+
+## Requirements
+
+- **Ruby >= 3.2** (required by `mcp` gem dependency)
+- SimpleCov-generated `.resultset.json` file
+- `simplecov` gem >= 0.21
+
+## 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)
+cov-loupe --resultset /path/to/your/coverage
+
+# Environment variable (project-wide default)
+export COV_LOUPE_OPTS="--resultset /path/to/your/coverage"
+
+# MCP server configuration
+# Add to your MCP client config:
+# "args": ["--resultset", "/path/to/your/coverage"]
+```
+
+See [CLI Usage Guide](docs/user/CLI_USAGE.md#-r---resultset-path) for complete details.
+
+
+
+## Common Workflows
+
+### Find Coverage Gaps
+
+```sh
+# Files with worst coverage
+cov-loupe -o d list           # -o = --sort-order, d = descending (worst at end)
+cov-loupe list | less         # display table in pager, worst files first
+cov-loupe list | head -10     # truncate the table
+
+# Specific directory
+cov-loupe -g "lib/cov_loupe/tools/**/*.rb" list  # -g = --tracked-globs
+
+# Export for analysis
+cov-loupe -fJ list > coverage-report.json
+```
+
+### Working with JSON Output
+
+The `-fJ` flag enables programmatic processing of coverage data using command-line JSON tools.
+
+**Using jq:**
+```sh
+# Filter files below 80% coverage
+cov-loupe -fJ list | jq '.files[] | select(.percentage < 80)'
+```
+
+**Using Ruby one-liners:**
+```sh
+# Count files below threshold
+cov-loupe -fJ list | ruby -r json -e '
+  puts JSON.parse($stdin.read)["files"].count { |f| f["percentage"] < 80 }
+'
+```
+
+**Using rexe:**
+
+[rexe](https://github.com/keithrbennett/rexe) is a Ruby gem that enables shorter Ruby command lines by providing command-line options for input and output formats, plus other conveniences. It eliminates the need for explicit JSON parsing and formatting code.
+
+Install: `gem install rexe`
+
+```sh
+# Filter files below 80% coverage with pretty-printed JSON output
+cov-loupe -fJ list | rexe -ij -mb -oJ 'self["files"].select { |f| f["percentage"] < 80 }'
+
+# Count files below threshold
+cov-loupe -fJ list | rexe -ij -mb -op 'self["files"].count { |f| f["percentage"] < 80 }'
+
+# Human-readable output with AwesomePrint
+cov-loupe -fJ list | rexe -ij -mb -oa 'self["files"].first(3)'
+```
+
+With rexe's `-ij -mb` options, `self` automatically becomes the parsed JSON object. The same holds true for JSON output -- using `-oJ` produces pretty-printed JSON without explicit formatting calls. Rexe also supports YAML input/output (`-iy`, `-oy`) and AwesomePrint output (`-oa`) for human consumption.
+
+Run `rexe -h` to see all available options, or visit the [rexe project page](https://github.com/keithrbennett/rexe) for more examples.
+
+For comprehensive JSON processing examples, see [docs/user/EXAMPLES.md](docs/user/EXAMPLES.md).
+
+### CI/CD Integration
+
+```sh
+# Fail build if coverage is stale
+cov-loupe --staleness error || exit 1
+
+# Generate coverage report artifact
+cov-loupe -fJ list > artifacts/coverage.json
+```
+
+### Investigate Specific Files
+
+```sh
+# Quick summary
+cov-loupe summary lib/cov_loupe/model.rb
+
+# See uncovered lines
+cov-loupe uncovered lib/cov_loupe/cli.rb
+
+# View in context
+cov-loupe -s u -c 3 uncovered lib/cov_loupe/cli.rb  # -s = --source (u = uncovered), -c = --context-lines
+
+# Detailed hit counts
+cov-loupe detailed lib/cov_loupe/util.rb
+
+# Project totals
+cov-loupe totals
+cov-loupe -fJ totals
+```
+
+## Commands and Tools
+
+**CLI Subcommands:** `list`, `summary`, `uncovered`, `detailed`, `raw`, `totals`, `validate`, `version`
+
+**MCP Tools:** `coverage_summary_tool`, `coverage_detailed_tool`, `coverage_raw_tool`, `uncovered_lines_tool`, `all_files_coverage_tool`, `coverage_totals_tool`, `coverage_table_tool`, `validate_tool`, `help_tool`, `version_tool`
+
+📖 **See also:**
+- [CLI Usage Guide](docs/user/CLI_USAGE.md) - Complete command-line reference
+- [MCP Integration Guide](docs/user/MCP_INTEGRATION.md#available-mcp-tools) - MCP tools documentation
+
+## Troubleshooting
+
+- **"command not found"** - See [Installation Guide](docs/user/INSTALLATION.md#path-configuration)
+- **"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](#configuring-the-resultset) section for more details.
+- **MCP server won't connect** - Check PATH and Ruby version in [MCP Troubleshooting](docs/user/MCP_INTEGRATION.md#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](docs/user/TROUBLESHOOTING.md).
+
+## Development
+
+```sh
+# Clone and setup
+git clone https://github.com/keithrbennett/cov-loupe.git
+cd cov-loupe
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Test locally
+bundle exec exe/cov-loupe
+
+# Build and install
+gem build cov-loupe.gemspec
+gem install cov-loupe-*.gem
+```
+
+See [docs/dev/DEVELOPMENT.md](docs/dev/DEVELOPMENT.md) for more.
+
+## 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.
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass (`bundle exec rspec`)
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Links
+
+- **GitHub:** https://github.com/keithrbennett/cov-loupe
+- **RubyGems:** https://rubygems.org/gems/cov-loupe
+- **Issues:** https://github.com/keithrbennett/cov-loupe/issues
+- **Changelog:** [RELEASE_NOTES.md](RELEASE_NOTES.md)
+
+## Related Files
+
+- [CLAUDE.md](CLAUDE.md) - Claude Code integration notes
+- [AGENTS.md](AGENTS.md) - AI agent configuration
+- [GEMINI.md](GEMINI.md) - Gemini-specific guidance
+
+---
+
+## Next Steps
+
+📦 **Install:** `gem install cov-loupe`
+
+📖 **Read:** [CLI Usage Guide](docs/user/CLI_USAGE.md) | [MCP Integration](docs/user/MCP_INTEGRATION.md)
+
+🐛 **Report issues:** [GitHub Issues](https://github.com/keithrbennett/cov-loupe/issues)
+
+⭐ **Star the repo** if you find it useful!

data/docs/dev/ARCHITECTURE.md

@@ -0,0 +1,80 @@
+# Architecture
+
+[Back to main README](../README.md)
+
+cov-loupe is organized around a single coverage data model that feeds three delivery channels: a command-line interface, an MCP server for LLM agents, and a light-weight Ruby API. The codebase is intentionally modular—shared logic for loading, normalizing, and validating SimpleCov data lives in `lib/cov_loupe/`, while adapters wrap that core for each runtime mode.
+
+## Runtime Entry Points
+
+- **Executable** – `exe/cov-loupe` bootstraps the gem, enforces Ruby >= 3.2, and delegates to `CovLoupe.run(ARGV)`.
+- **Mode Negotiation** – `CovLoupe.run` inspects environment defaults from `COV_LOUPE_OPTS`, checks for CLI subcommands, and defaults to CLI mode when STDIN is a TTY. Otherwise it instantiates `CovLoupe::MCPServer` for MCP protocol communication over STDIO.
+- **Embedded Usage** – Applications embed the gem by instantiating `CovLoupe::CoverageModel` directly, optionally wrapping work in `CovLoupe.with_context` to install a library-oriented error handler.
+
+## Coverage Data Pipeline
+
+1. **Resultset discovery** – The tool locates the `.resultset.json` file by checking a series of default paths or by using a path specified by the user. For a detailed explanation of the configuration options, see the [Configuring the Resultset](../README.md#configuring-the-resultset) section in the main README.
+2. **Parsing and normalization** – `CoverageModel` loads the chosen resultset once, extracts all test suites that expose `coverage` data (e.g., "RSpec", "Minitest"), merges them if multiple suites exist, and maps all file keys to absolute paths anchored at the configured project root. Timestamps are cached for staleness checks.
+3. **Path relativizing** – `PathRelativizer` produces relative paths for user-facing payloads without mutating the canonical data. Tool responses pass through `CoverageModel#relativize` before leaving the process.
+4. **Derived metrics** – `CovUtil.summary`, `CovUtil.uncovered`, and `CovUtil.detailed` compute coverage stats from the raw `lines` arrays. `CoverageModel` exposes `summary_for`, `uncovered_for`, `detailed_for`, and `raw_for` helpers that wrap these utilities.
+5. **Staleness detection** – `StalenessChecker` compares source mtimes/line counts to coverage metadata. CLI flags and MCP arguments can promote warnings to hard failures (`--staleness error`) or simply mark rows as stale for display.
+
+## Interfaces
+
+### CLI (`CovLoupe::CoverageCLI`)
+
+- Builds on Ruby’s `OptionParser`, with global options such as `--resultset`, `--staleness`, `-fJ`, and `--source` modes.
+- Subcommands (`list`, `summary`, `raw`, `uncovered`, `detailed`, `version`) translate to calls on `CoverageModel`.
+- Uses `ErrorHandlerFactory.for_cli` to convert unexpected exceptions into friendly user messages while honoring `--error-mode`.
+- Formatting logic (tables, JSON) lives in the model to keep presentation consistent with MCP responses.
+
+### MCP Server (`CovLoupe::MCPServer`)
+
+- Assembles a list of tool classes and mounts them in `MCP::Server` using STDIO transport.
+- Relies on the same core model; each tool instance recreates `CoverageModel` with the arguments provided by the MCP client, keeping the server stateless between requests.
+- Error handling delegates to `BaseTool.handle_mcp_error`, which swaps in the MCP-specific handler and emits `MCP::Tool::Response` objects.
+
+### Library API
+
+- Consuming code instantiates `CoverageModel` directly for fine-grained control over coverage queries.
+- Use `CovLoupe::ErrorHandlerFactory.for_library` together with `CovLoupe.with_context` when an embedded caller wants to suppress CLI-friendly error logging.
+
+## MCP Tool Stack
+
+- `CovLoupe::BaseTool` centralizes JSON schema definitions, error conversion, and response serialization for the MCP protocol.
+- Individual tools reside in `lib/cov_loupe/tools/` and follow a consistent shape: define an input schema, call into `CoverageModel`, then serialize via `respond_json`. Examples include `AllFilesCoverageTool`, `CoverageSummaryTool`, and `UncoveredLinesTool`.
+- Tools are registered in `CovLoupe::MCPServer#run`. Adding a new tool only requires creating a subclass and appending it to that list.
+
+## Error Handling & Logging
+
+- Custom exceptions under `lib/cov_loupe/errors.rb` capture context for configuration issues, missing files, stale coverage, and general runtime errors. Each implements `#user_friendly_message` for consistent UX.
+- `CovLoupe::ErrorHandler` encapsulates logging and severity decisions. Modes (`:off`, `:log`, `:debug`) control whether errors are recorded and whether stack traces are included.
+- Runtime configuration (error handlers, log destinations) flows through `CovLoupe::AppContext`. Entry points push a context with `CovLoupe.with_context`, which stores the active configuration in a thread-local slot (`CovLoupe.context`). Nested calls automatically restore the previous context when the block exits, ensuring isolation even when multiple callers share a process or thread.
+- Two helper accessors clarify intent:
+  - `CovLoupe.default_log_file` / `default_log_file=` adjust the baseline log sink that future contexts inherit.
+  - `CovLoupe.active_log_file` / `active_log_file=` mutate only the current context (or create one on demand) so the change applies immediately without touching the default.
+- `ErrorHandlerFactory` wires the appropriate handler per runtime: CLI, MCP server, or embedded library, each of which installs its handler inside a fresh `AppContext` before executing user work.
+- Diagnostics are written via `CovUtil.log` to `cov_loupe.log` in the current directory by default; override with CLI `--log-file`, set `CovLoupe.default_log_file` for future contexts, or temporarily tweak `CovLoupe.active_log_file` when a caller needs a different destination mid-run.
+
+## Configuration Surface
+
+- **Environment defaults** – `COV_LOUPE_OPTS` applies baseline CLI flags before parsing the actual command line.
+- **Resultset overrides** – The location of the `.resultset.json` file can be specified via CLI options or in the MCP configuration. See [Configuring the Resultset](../README.md#configuring-the-resultset) for details.
+- **Tracked globs** – Glob patterns (e.g., `lib/**/*.rb`) that specify which files should have coverage. When provided, SimpleCov MCP alerts you if any matching files are missing from the coverage data, helping catch untested files that were added to the project but never executed during test runs.
+- **Colorized source** – CLI-only flags (`--source`, `--source-context`, `--color`) enhance human-readable reports when working locally.
+
+## Repository Layout Highlights
+
+- `lib/cov_loupe/` – Core runtime (model, utilities, error handling, CLI, MCP server, tools).
+- `lib/cov_loupe.rb` – Primary public entry point required by gem consumers.
+- `docs/` – Audience-specific guides (`docs/user` for usage, `docs/dev` for contributors).
+- `spec/` – RSpec suite with fixtures under `spec/fixtures/` for deterministic coverage data.
+
+## Extending the System With a New Tool or Metric
+
+1. Add or update data processing inside `CoverageModel` or `CovUtil` when a new metric is needed.
+2. Surface that metric through all interfaces: add a CLI option/subcommand, create an MCP tool, and expose a library helper method.
+3. Register the new tool in `MCPServer` and update CLI option parsing in `CoverageCLI`.
+4. Provide tests under `spec/` mirroring the lib path (`spec/lib/cov_loupe/..._spec.rb`).
+5. Update documentation to reflect the new capability.
+
+By funnelling every interface through the shared `CoverageModel`, cov-loupe guarantees that CLI users, MCP clients, and embedding libraries all observe identical coverage semantics and staleness rules, while still allowing each adapter to tailor presentation and error handling to its audience.

data/docs/dev/BRANCH_ONLY_COVERAGE.md

@@ -0,0 +1,158 @@
+# Branch-Only Coverage Handling
+
+[Back to main README](../README.md)
+
+> **Note:** This document is for **developers working on SimpleCov MCP**, not for users of the gem.
+> If you're a user, you don't need to read this - branch-only coverage "just works" automatically.
+> This explains the internal implementation for contributors who need to maintain or modify the code.
+
+## The Problem This Solves for SimpleCov MCP
+
+SimpleCov can be configured to track different types of coverage:
+- **Line coverage**: Which lines of code were executed
+- **Branch coverage**: Which paths through if/else, case/when, etc. were taken
+- **Both**: Track both lines and branches together
+
+When users configure SimpleCov to track **only branch coverage** (without line coverage),
+the `.resultset.json` file has a different structure: the `lines` array is `null`,
+and only the `branches` data exists.
+
+**This breaks SimpleCov MCP** because our entire tool is designed around the `lines` array:
+- Our MCP tools (`coverage_summary_tool`, `uncovered_lines_tool`, etc.) expect line data
+- Our CLI commands expect line data
+- Our `CoverageModel` API expects line data
+
+Rather than failing with "no coverage data found" errors, SimpleCov MCP **automatically
+converts branch coverage into line coverage** so all our tools continue to work seamlessly
+for projects using branch-only configuration.
+
+## What Branch-Only Coverage Data Looks Like
+
+When SimpleCov writes branch-only coverage, the `.resultset.json` file looks different
+from the normal line coverage format. Here's an example:
+
+```json
+{
+  "lib/example.rb": {
+    "lines": null,
+    "branches": {
+      "[:if, 0, 12, 4, 20, 29]": {
+        "[:then, 1, 13, 6, 13, 18]": 4,
+        "[:else, 2, 15, 6, 15, 16]": 0
+      }
+    }
+  }
+}
+```
+
+### Understanding the Branch Data Structure
+
+The `branches` hash uses a nested structure:
+
+**Outer key** (e.g., `"[:if, 0, 12, 4, 20, 29]"`):
+- This is either a Ruby array or its stringified version
+- It describes where the branch decision happens (the `if` statement itself)
+- Format: `[type, id, start_line, start_col, end_line, end_col]`
+  - Position 0: Branch type (`:if`, `:case`, `:unless`, etc.)
+  - Position 1: SimpleCov's internal ID for this branch
+  - **Position 2: The line number** ← This is what we need for line coverage!
+  - Position 3: Starting column
+  - Position 4: Ending line
+  - Position 5: Ending column
+
+**Nested hash** (the value of the outer key):
+- Contains each possible path through the branch
+- Keys are branch targets like `"[:then, 1, 13, 6, 13, 18]"` or `"[:else, 2, 15, 6, 15, 16]"`
+- Each target has the same array format as the outer key
+- Values are integers showing how many times that path was executed
+  - `4` means the `then` branch ran 4 times
+  - `0` means the `else` branch never ran
+
+**Why this matters for our conversion:**
+- We extract the line number (position 2) from each branch target
+- We sum up all the execution counts for branches on the same line
+- This gives us enough information to build a line coverage array
+
+## How SimpleCov MCP Converts Branch Coverage to Line Coverage
+
+Since all of SimpleCov MCP's tools expect a `lines` array, we need to build one from
+the `branches` data. This happens automatically in the `CoverageLineResolver` whenever
+it detects that `lines` is `null` but `branches` exists.
+
+### The Conversion Algorithm
+
+Here's how we transform branch data into line data:
+
+**Step 1: Parse the branch keys**
+- Branch keys can be either raw Ruby arrays or stringified (e.g., `"[:if, 0, 12, 4, 20, 29]"`)
+- We handle both formats by parsing the string format when needed
+
+**Step 2: Extract line numbers**
+- From each branch target tuple, we pull out position 2 (the line number)
+- Invalid or malformed tuples are silently skipped
+
+**Step 3: Sum hits per line**
+- Multiple branches can exist on the same line (e.g., nested ifs, ternaries)
+- We add up all the execution counts for branches on the same line
+- Example: if line 15 has a `then` branch hit 4 times and an `else` branch hit 2 times,
+  that line gets a total of 6 hits
+
+**Step 4: Build the line array**
+- We create an array with length equal to the highest line number found
+- Each array position represents a line: `array[0]` = line 1, `array[1]` = line 2, etc.
+- Positions get the summed hit count for that line, or `nil` if no branches appeared there
+
+**Result:** We now have a `lines` array that looks exactly like SimpleCov's normal
+format, so all our tools (`summary`, `uncovered`, staleness checks, etc.) work without
+knowing branch coverage was involved.
+
+## Where to Find the Code
+
+If you need to modify or debug the branch coverage conversion, here's where everything lives:
+
+### Implementation
+**`lib/cov_loupe/resolvers/coverage_line_resolver.rb`**
+- Line 59-66: `lines_from_entry` - Detects when to synthesize line data
+- Line 68-103: `synthesize_lines_from_branches` - The main conversion logic
+- Line 105-123: `extract_line_number` - Parses line numbers from branch tuples
+
+This file is referenced in the code comments at line 79.
+
+### Tests
+**`spec/resolvers/coverage_line_resolver_spec.rb`**
+- Contains tests specifically for the resolver and branch synthesis
+
+**`spec/cov_loupe_model_spec.rb`**
+- Integration tests showing how the model uses synthesized line data
+
+### Test Data
+**`spec/fixtures/branch_only_project/coverage/.resultset.json`**
+- Example of real branch-only coverage data used in tests
+- Useful reference when debugging issues or adding new test cases
+
+## Important Implementation Notes
+
+### Why the resolver returns `nil` for missing files
+
+When `CoverageLineResolver.lookup_lines` can't find a file, it returns `nil` rather
+than immediately raising an error. This is deliberate:
+
+- The lookup tries multiple strategies: exact path match, relative path, path without
+  working directory prefix
+- Each strategy calls `lines_from_entry` which may return `nil`
+- Only after **all strategies fail** does the resolver raise a `FileError`
+- This ensures we try every possible way to find the file before giving up
+
+If you change `lines_from_entry` to raise an error immediately, the multi-strategy
+lookup will break!
+
+### Future-proofing for SimpleCov changes
+
+SimpleCov's branch tuple format could change in future versions. If that happens:
+
+1. Update `extract_line_number` to recognize the new tuple format
+2. Add test fixtures with the new format
+3. Update this documentation with the new structure
+4. Keep backward compatibility with the old format if possible
+
+This way, SimpleCov MCP continues working even when SimpleCov evolves.

data/docs/dev/DEVELOPMENT.md

@@ -0,0 +1,83 @@
+# Development Guide
+
+[Back to main README](../README.md)
+
+> **Note:** Commands like `cov-loupe` assume the gem is installed globally. If not, substitute `bundle exec exe/cov-loupe`.
+
+## Setup
+
+```sh
+git clone https://github.com/keithrbennett/cov-loupe.git
+cd cov-loupe
+bundle install
+gem build cov-loupe.gemspec && gem install cov-loupe-*.gem  # optional
+cov-loupe version  # verify it works
+```
+
+## Running Tests
+
+```sh
+bundle exec rspec
+```
+
+## Project-Specific Patterns
+
+**All Ruby files start with:**
+```ruby
+# frozen_string_literal: true
+```
+
+**Error handling uses custom exceptions from `errors.rb`:**
+```ruby
+rescue Errno::ENOENT => e
+  raise FileError.new("Coverage data not found: #{e.message}")
+rescue JSON::ParserError => e
+  raise CoverageDataError.new("Invalid coverage format: #{e.message}")
+```
+
+**MCP tools extend `BaseTool` and follow this pattern:**
+```ruby
+module CovLoupe::Tools
+  class MyTool < BaseTool
+    def self.name = 'my_tool'
+    def self.description = 'What this tool does'
+    
+    def self.call(path:, root: '.', resultset: nil, stale: 'off', error_mode: 'on', **)
+      model = CoverageModel.new(root: root, resultset: resultset, staleness: stale)
+      data = model.my_method_for(path)
+      respond_json(model.relativize(data), name: 'my_tool_output.json')
+    rescue => e
+      handle_mcp_error(e, name, error_mode: error_mode.to_sym)
+    end
+  end
+end
+```
+
+**Use test fixtures for consistency:**
+```ruby
+let(:project_root) { (FIXTURES_DIR / 'project1').to_s }
+let(:coverage_dir) { File.join(project_root, 'coverage') }
+```
+
+**MCP tool tests need setup:**
+```ruby
+let(:server_context) { instance_double('ServerContext').as_null_object }
+before { setup_mcp_response_stub }
+```
+
+## Adding Features
+
+**CLI commands:** Add to `SUBCOMMANDS` in `cli.rb`, implement handler, add tests
+
+**MCP tools:** Create `*_tool.rb` in `lib/cov_loupe/tools/`, register in `mcp_server.rb`
+
+**Coverage features:** Add to `CoverageModel` in `model.rb` or `CovUtil` in `util.rb`
+
+## Troubleshooting
+
+**RVM + Codex macOS:** Currently not possible for Codex to run rspec when running on macOS with rvm-managed rubies - see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+
+**MCP server testing:**
+```sh
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | cov-loupe
+```