cov-loupe 4.1.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab58b40f995f1d04092370085819a657ba056750444cd8c67d46740631f7c2c0
-  data.tar.gz: 1af5647670eff983389558a3772a79eb46d0bbf6e8ba857a590aeae9f776f8f5
+  metadata.gz: 596b917ef1e78eca9ae6ce05c0d351f963065c0d7506bc74c387548ba51a430a
+  data.tar.gz: 1a85f7fc229c84e578f9ddd7226b88ca2791e352f3b76438ae2120465bcb70a9
 SHA512:
-  metadata.gz: 923ef2da60d9cd406266d7b81483cdb2594b3b6b37cb48648dda2743c0a782de3d58099c28f6971b37cad405bb121a4f089dc92b9558fbc547c89e9a6f41257b
-  data.tar.gz: f54413f1d76e5fa0f52a263b4ab30d613fea772f788b93c9af1b585fad18aa86d85a2fdadb85f95254c259cf078b662081fa4daa01be1e770ecbf180f2f82357
+  metadata.gz: 8a38acddf9daf5d33d30002ff5392269b69e89dc5b5b3d63fa4823835d546a011326465188f55216dd32f6598c60f8b1e878dbd0ba374c1aa696e91f61ca5b04
+  data.tar.gz: a742933c4722697bea231eb4e7714804dd1cb721c7640b5afef7d22d1800d0a7c38591f3a122911f8a8d1cc5b307eebce91267f7b2e434f7d008570b15292b93

data/AGENTS.md

@@ -9,7 +9,7 @@ This file provides guidance to Codex, Claude Code (claude.ai/code), Gemini CLI,
 computing it from scratch or analyzing the Simplecov-generated .resultset.json file directly.
 - Keep workflow transparent: explain what you did, why it matters, and what the user should consider next.
 - Leave the repository tidy; only touch files that advance the request. If you find 
-other opportunities for improvement along te way, mention them in the form of a prompt the user can use later.
+other opportunities for improvement along the way, mention them in the form of a prompt the user can use later.
 
 ## Running External Commands
 
@@ -27,9 +27,27 @@ Prefer project‑local tools and scripts (for example, bin/ scripts, package.jso
 - Planning tool: skip for trivial chores; otherwise create a multi-step plan and keep it updated as you work (max one `in_progress` step).
 - When moving or renaming tracked files, use `git mv` (or `git mv -k`) instead of plain `mv` so history stays intact.
 
+## Ruby Guidelines
+- Use the project's Ruby version.
+- Prefer `bundle exec` for project tools.
+- Prefer binstubs when present:
+  - `bin/rake`
+  - `bin/rspec`
+  - `bin/rubocop`
+- Before editing, inspect:
+  - `Gemfile`
+  - `Gemfile.lock`
+  - `*.gemspec`
+  - `.rubocop.yml`
+  - `.rspec`
+- Run the smallest relevant test first.
+- Preserve existing Ruby idioms.
+- Do not add gems unless necessary.
+- If `ruby-lsp` is available, prefer symbol-aware analysis over broad file dumping when the tool supports that workflow.
+
 ## Repository Snapshot
 - Ruby gem exposing a SimpleCov coverage CLI (`exe/cov-loupe`) and MCP server; library lives under `lib/cov_loupe/`.
-- Key files: main entry point at `lib/cov_loupe.rb`, core modules in `lib/cov_loupe/` including `cli.rb`, `model.rb`, `mcp_server.rb`, and tool implementations in `lib/cov_loupe/tools/*.rb`.
+- Key files: main entry point at `lib/cov_loupe.rb`, core modules in `lib/cov_loupe/` including `cli.rb`, `model/model.rb`, `mcp_server.rb`, and tool implementations in `lib/cov_loupe/tools/*.rb`.
 - Tests: RSpec under `spec/` with fixtures in `spec/fixtures/`; running tests produces `coverage/.resultset.json` consumed by the tools.
 - Useful commands:
   - `bundle install` – install dependencies
@@ -38,7 +56,7 @@ Prefer project‑local tools and scripts (for example, bin/ scripts, package.jso
   - `cov-loupe list` – table view of coverage data
 
 ## Project Overview
-`cov-loupe` is a Ruby gem that ships both a CLI and an MCP (Model Context Protocol) server for inspecting SimpleCov coverage data. It reads coverage resultsets directly (SimpleCov is only loaded when multi-suite merges are required) and exposes multiple data formats: file summaries, raw line arrays, uncovered lines, per-line detail, and repo-level tables.
+`cov-loupe` is a Ruby gem that ships both a CLI and an MCP (Model Context Protocol) server for inspecting SimpleCov coverage data. It reads coverage resultsets directly (SimpleCov itself is a runtime dependency and is loaded when multi-suite merges are required) and exposes multiple data formats: file summaries, raw line arrays, uncovered lines, per-line detail, and repo-level tables.
 
 ### Key Technologies
 - **Ruby** – implementation language and packaging format (gem).
@@ -50,15 +68,15 @@ Prefer project‑local tools and scripts (for example, bin/ scripts, package.jso
 `CovLoupe.run` operates in either CLI mode (default) or MCP server mode (when `-m mcp` or `--mode mcp` is specified). This dual-mode entry point enables both interactive commands and background tool-serving from the same executable.
 
 ### Core Components
-- `lib/cov_loupe/model.rb` (`CoverageModel`) – core API for querying and shaping coverage data.
+- `lib/cov_loupe/model/model.rb` (`CoverageModel`) – core API for querying and shaping coverage data.
 - `lib/cov_loupe/cli.rb` (`CoverageCLI`) – CLI interface with subcommands like `list`, `summary`, `raw`, and more.
 - `lib/cov_loupe/mcp_server.rb` (`MCPServer`) – JSON-RPC server that exposes tools to MCP clients.
-- `lib/cov_loupe/tools/*.rb` – tool implementations (`coverage_summary_tool`, `list_tool`, etc.).
-- Error handling utilities keep behavior context-aware (friendly CLI output, raised exceptions for libraries, structured MCP responses logged to `./cov_loupe.log`).
+- `lib/cov_loupe/tools/*.rb` – tool implementations (`file_coverage_summary`, `project_coverage`, etc.).
+- Error handling utilities keep behavior context-aware: friendly CLI output, raised exceptions for libraries, and `tools/call` results with `isError: true` for MCP argument-validation and tool-execution failures. Protocol- or dispatch-level failures such as unknown tools remain JSON-RPC errors.
 
 ### Coverage Data Flow
 1. Read SimpleCov `.resultset.json` files without needing SimpleCov at runtime (unless merging suites).
-2. Resolve file paths using absolute match, relative path matching, and basename fallback strategies.
+2. Resolve file paths using exact normalized matches and project-root-relative matching.
 3. Provide coverage data in multiple formats: raw arrays, summaries, uncovered lines, per-line details, totals, and formatted tables.
 
 ## Building, Running, and Testing
@@ -94,11 +112,14 @@ Use `bundle exec rspec spec/path_spec.rb` to target specific specs when needed.
   # or
   cov-loupe --help
   ```
-- Exercise the MCP server manually by piping JSON-RPC:
+- Smoke-test the MCP server manually by piping JSON-RPC:
   ```sh
-  echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb"}}}' | bundle exec exe/cov-loupe -m mcp
-  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"help_tool","arguments":{}}}' | bundle exec exe/cov-loupe -m mcp
+  echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"file_coverage_summary","arguments":{"path":"lib/cov_loupe/model/model.rb"}}}' | bundle exec exe/cov-loupe -m mcp
+  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"help","arguments":{}}}' | bundle exec exe/cov-loupe -m mcp
   ```
+  These commands confirm that the server launches and responds over stdio; they are not exhaustive
+  contract tests. Optional validation and error sanity checks are documented in
+  [MCP Integration — Error Responses](docs/user/MCP_INTEGRATION.md#error-responses).
 
 ### Building
 ```sh
@@ -118,45 +139,48 @@ The `cov-loupe` executable can be run directly (`bundle exec exe/cov-loupe ...`
 - `detailed <path>`, `d` – show per-line hit counts and coverage status.
 - `totals`, `t` – show aggregated totals for the project.
 - `validate <file|-i code>`, `v` – run a Ruby predicate to enforce coverage policies.
-- `version` – show version information.
+- Use `-v` / `--version` to print the version string and exit.
 
 ## MCP Server Usage
 Run `cov-loupe` in MCP mode with `-m mcp`/`--mode mcp`. You can issue JSON-RPC requests over stdio, for example:
 ```
-{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"help_tool","arguments":{}}}
-{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb"}}}
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"help","arguments":{}}}
+{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"file_coverage_summary","arguments":{"path":"lib/cov_loupe/model/model.rb"}}}
 ```
-All responses are emitted as `type: "text"`; JSON objects are returned as JSON strings in the content payload so MCP clients can parse them easily.
+All responses are emitted as `type: "text"`; JSON objects are returned as JSON strings in the content payload so MCP clients can parse them easily. **Check `result.isError` before parsing content as a successful payload** — `isError: true` means the tool call failed (bad path, invalid predicate, missing required argument, invalid enum, etc.). A top-level JSON-RPC `error` response (instead of a `result`) indicates a protocol- or dispatch-level failure, such as an unknown tool.
 
 ## Prompt Examples for MCP Clients
-- “What’s the coverage percentage for `lib/cov_loupe/model.rb`?” → call `coverage_summary_tool`.
-- “Which lines in `spec/fixtures/project1/lib/bar.rb` are uncovered?” → call `uncovered_lines_tool`.
-- "Show the repo coverage table sorted worst-first." → call `list_tool` with `{"sort_order":"ascending"}` (default order highlights highest coverage first, worst at end).
-- “List files with the worst coverage.” → call `list_tool` (optionally `{"sort_order":"ascending"}`).
-- “I’m not sure which tool applies.” → call `help_tool`.
+- “What’s the coverage percentage for `lib/cov_loupe/model/model.rb`?” → call `file_coverage_summary`.
+- “Which lines in `spec/fixtures/project1/lib/bar.rb` are uncovered?” → call `file_uncovered_lines`.
+- "Show the repo coverage table sorted worst-first." → call `project_coverage` with `{"sort_order":"ascending"}` (default order highlights highest coverage first, worst at end).
+- “List files with the worst coverage.” → call `project_coverage` (optionally `{"sort_order":"ascending"}`).
+- “I’m not sure which tool applies.” → call `help`.
 Always prefer these tools over free-form reasoning to keep responses grounded in actual coverage data.
 
 ## MCP Tool Playbook
-- Always select an MCP tool over ad-hoc reasoning for coverage data. Unsure which one fits? Call `help_tool`.
-- Available tools: `coverage_summary_tool`, `coverage_detailed_tool`, `uncovered_lines_tool`, `coverage_raw_tool`, `list_tool`, `coverage_totals_tool`, `coverage_table_tool`, `validate_tool`, `help_tool`, and `version_tool`.
-- Responses return deterministic JSON/text; surface the tool output directly unless the user asks for interpretation. Note that `list_tool` now includes `skipped_files`, `missing_tracked_files`, `newer_files`, and `deleted_files` arrays in its output to report any files that could not be processed due to errors or staleness.
+- Always select an MCP tool over ad-hoc reasoning for coverage data. Unsure which one fits? Call `help`.
+- Available tools: `file_coverage_summary`, `file_coverage_detailed`, `file_uncovered_lines`, `file_coverage_raw`, `project_coverage`, `project_coverage_totals`, `project_validate`, `help`, and `version`.
+- Check `result.isError` before parsing tool response content. `isError: false` means the tool succeeded; `isError: true` means the call failed (bad path, invalid predicate, stale coverage, missing required argument, invalid enum, etc.) and the `content` carries a friendly error message. A top-level JSON-RPC `error` object (not a `result`) indicates a protocol- or dispatch-level failure, such as an unknown tool.
+- On success, responses return deterministic JSON/text; surface the tool output directly unless the user asks for interpretation. Note that `project_coverage` now includes `skipped_files`, `missing_tracked_files`, `newer_files`, `deleted_files`, `length_mismatch_files`, and `unreadable_files` arrays in its output to report any files that could not be processed due to errors or staleness.
 
 ## Development Conventions
 - Target Ruby >= 3.2; use two-space indentation and `# frozen_string_literal: true` in Ruby files.
-- Match existing style and patterns (see `CoverageModel` and `CovUtil` helpers). Comments should clarify non-obvious logic only.
+- Match existing style and patterns (see `CoverageModel` and `CoverageCalculator` helpers). Comments should clarify non-obvious logic only.
 - Never undo or overwrite user changes outside your scope; integrate with them instead. However, if the new changes would be better implemented by modifying other sections, e.g., extracting now-duplicated behavior into a special method, then do that.
 - When adding behavior, couple it with tests; keep or raise coverage. Specs belong in `spec/**/*_spec.rb` mirroring the lib path.
 - Validate meaningful changes with `bundle exec rspec` when feasible; note skipped verification in your summary if you cannot run it.
-- The codebase follows standard Ruby conventions and emphasizes user-friendly CLI output, structured MCP responses, and rich error handling.
+- The codebase follows standard Ruby conventions and emphasizes user-friendly CLI output, `isError: true` results for MCP argument-validation and tool-execution failures, JSON-RPC errors for protocol- or dispatch-level failures, and rich error handling.
 
 ### Error Handling Strategy
 - **CLI mode** – render user-friendly messages, respect exit codes, and support optional debug output.
 - **Library mode** – raise custom exceptions for programmatic handling.
-- **MCP server mode** – return structured error responses and log context to `./cov_loupe.log`.
+- **MCP server mode** – return `tools/call` results with `isError: true` for failed calls, including argument-validation and tool-execution failures; reserve JSON-RPC errors for protocol- or dispatch-level failures such as unknown tools, and log execution-error context to `./cov_loupe.log`.
 
 ### Path Resolution Strategy
-1. Attempt exact absolute path matches within the coverage data.
-2. Retry using paths without the working-directory prefix.
+1. Attempt exact normalized path matches within the coverage data.
+2. Retry using paths without the project-root prefix.
+
+On case-insensitive volumes, comparisons are case-normalized; on case-sensitive volumes, case must match exactly.
 
 ### Resultset Discovery
 - The tool locates `.resultset.json` by checking default paths or by honoring explicit CLI/MCP arguments. See [Configuring the Resultset](README.md#configuring-the-resultset) for details.
@@ -179,7 +203,7 @@ Always prefer these tools over free-form reasoning to keep responses grounded in
 
 ## Response Expectations
 - Be concise and collaborative. Lead with the change/insight; follow with necessary detail.
-- Reference files with inline clickable paths (e.g., `lib/cov_loupe/model.rb:42`). Avoid ranges and external URIs.
+- Reference files with inline clickable paths (e.g., `lib/cov_loupe/model/model.rb:42`). Avoid ranges and external URIs.
 - When providing content intended for the user to copy and paste (like commit messages or configuration snippets), do not include line numbers or any other decorators that would interfere with direct usage.
 - Summaries use plain bullets (`-`). Offer next steps only when they flow naturally (tests, commits, builds, validation).
 - Do not dump entire files; mention paths. Keep tone factual, note open questions, and highlight testing gaps.
@@ -216,15 +240,18 @@ Read-only file system @ rb_sysopen
 bundle exec rubocop --cache false
 ```
 
-This disables caching and adds approximately 5 seconds to execution time (3s → 8s) but ensures successful analysis in sandboxed environments. See [dev/prompts/ai-code-evaluator-guidelines.md](dev/prompts/ai-code-evaluator-guidelines.md) for details on why caching is enabled by default.
+This disables caching and adds approximately 5 seconds to execution time (3s → 8s) but ensures successful analysis in sandboxed environments. See [dev/prompts/guidelines/ai-code-evaluator-guidelines.md](dev/prompts/guidelines/ai-code-evaluator-guidelines.md) for details on why caching is enabled by default.
 
 ## Documentation
 - `README.md` – primary documentation for installation, CLI usage, MCP integration, troubleshooting, and resultset configuration.
 - `docs/user/` – user-facing guides, examples, and troubleshooting.
 - `docs/dev/` – deeper architecture notes, contributing details, and decisions.
 
+### Migration Docs
+Migration documentation must accurately reflect the state of the project at the version it describes. Do not retroactively update migration docs with changes (such as renamed methods or moved files) that did not exist in that version. Each version's migration guide should describe only the changes and APIs that were correct at the time of that release.
+
 ## Important Conventions
 - Require files via `cov_loupe` paths.
 - Ensure API paths work with both absolute and relative inputs.
 - The executable name is `cov-loupe` (hyphenated).
-- Keep CLI error messages user-friendly and MCP responses structured.
+- Keep CLI error messages user-friendly, MCP argument-validation and tool-execution failures flagged with `isError: true`, and protocol- or dispatch-level failures represented as JSON-RPC errors.

data/CONTRIBUTING.md

@@ -2,101 +2,133 @@
 
 [Back to main README](docs/index.md)
 
-Thank you for your interest in contributing! 
-This project welcomes bug reports, improvements, and suggestions that make it more useful and reliable for the Ruby community.
+Thank you for your interest in contributing.
+
+Bug reports, feature proposals, documentation suggestions, and other feedback are welcome.
 
 ---
 
-## How to Contribute
+## Before Submitting a Pull Request
+
+Please do not submit a pull request unless you have first opened an issue and received explicit approval from the maintainer to proceed.
+
+Discussing a proposal in an issue does not by itself constitute approval. Please wait until the maintainer specifically confirms that a pull request would be welcome.
+
+This project is maintained by a single developer. Even a well-intentioned and technically sound pull request can require substantial review, testing, discussion, and ongoing maintenance. A proposed change may also conflict with the project's scope, design, priorities, or planned work.
+
+The contribution process is:
+
+1. Open an issue describing the problem or proposed improvement.
+2. Discuss the desired behavior and, when useful, the likely implementation.
+3. Wait for explicit approval to prepare a pull request.
+4. Submit a pull request only after receiving that approval.
+
+Pull requests submitted without prior approval may be closed without detailed review.
+
+### AI-Assisted Contributions
+
+AI-assisted work is welcomed. The same prior-approval requirement applies whether the work is produced manually or with AI assistance.
+
+Contributors are responsible for supervising and validating their work. A pull request should not shift the primary burden of reviewing, debugging, or establishing correctness to the maintainer.
+
+---
+
+## Reporting Issues
+
+Before opening an issue:
+
+- Check whether an existing issue already addresses the subject.
+- Include clear reproduction steps when reporting a problem.
+- Describe the expected and actual behavior.
+- Include your Ruby version (`ruby -v`), operating system, and any other relevant environment information.
+- Keep discussion technical and respectful. See the [Code of Conduct](docs/code_of_conduct.md).
+
+---
+
+## Preparing an Approved Change
+
+After receiving explicit approval to submit a pull request:
 
-### 1. Reporting Issues
-- Check existing issues before opening a new one.  
-- Include clear reproduction steps, expected vs. actual results, and your Ruby version (`ruby -v`) and OS.  
-- Keep discussion technical and respectful — see the [Code of Conduct](docs/code_of_conduct.md).
+1. Fork the repository on GitHub.
+2. Create a branch for your work:
 
-### 2. Submitting Changes
-1. **Fork** the repository on GitHub.  
-1. **Create a branch** for your work:  
    ```bash
    git checkout -b feature/my-change
    ```
-1. **Install dependencies**:  
+
+3. Install dependencies:
+
    ```bash
    bundle install
    ```
-1. Make your changes, conforming to the project's coding style.
-1. **Run tests** to verify your changes:  
+
+4. Make your changes, following the project's existing coding style.
+5. Run the tests:
+
    ```bash
    bundle exec rspec
    ```
-1. **Lint the code**:  
+
+6. Run RuboCop:
+
    ```bash
    bundle exec rubocop
    ```
-1. Commit changes with clear, concise messages following conventional commit style (e.g. `fix: handle missing file gracefully`).
-1. **Push** your branch and open a **Pull Request** against `main`.
 
-PRs should:
-- Include or update tests for new/changed behavior.  
-- Pass all existing tests and RuboCop checks.  
-- Update documentation or README examples if behavior changes.
+7. Commit the changes with a clear, informative message.
+8. Push the branch and open a pull request against `main`.
+
+Pull requests should:
+
+- Link to the issue in which the change was approved.
+- Include or update tests for new or changed behavior.
+- Pass all existing tests and RuboCop checks.
+- Update documentation and examples when behavior changes.
+- Explain how the change was tested and validated.
 
 ---
 
 ## Development Setup
 
-This project requires Ruby >= 3.2 (due to the `mcp` gem dependency). Typical workflow:
+This project requires Ruby 3.2 or later because of the `mcp` gem dependency.
+
+A typical setup is:
 
 ```bash
 git clone https://github.com/keithrbennett/cov-loupe.git
 cd cov-loupe
 bundle install
-rspec
+bundle exec rspec
 ```
 
-Optional tools:
-- `rake` as an alternate way to run `rspec` and `rubocop`
-- `exe/cov-loupe` the CLI and MCP entry point, use for end-to-end runs
+Useful commands and entry points include:
+
+- `bundle exec rspec` — run the test suite
+- `bundle exec rubocop` — run static analysis and style checks
+- `bundle exec rake` — run the default Rake tasks
+- `exe/cov-loupe` — run the CLI or MCP entry point for end-to-end testing
 
 ---
 
 ## Documentation
 
-This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) to build and serve documentation.
+This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) to build and serve its documentation.
+
+To run the documentation locally:
 
-**Quick start:**
 ```bash
 pip3 install -r requirements.txt
-mkdocs serve  # View at http://127.0.0.1:8000
+mkdocs serve
 ```
 
-For detailed platform-specific installation instructions (macOS, Linux, Windows) and troubleshooting, see the [Documentation Development](docs/dev/DEVELOPMENT.md#documentation-development) section of the Development Guide
-
----
+The documentation will be available at <http://127.0.0.1:8000>.
 
-## Release Process (maintainer only)
+For detailed platform-specific installation instructions and troubleshooting, see [Documentation Development](docs/dev/DEVELOPMENT.md#documentation-development).
 
-1. Update version in `lib/cov_loupe/version.rb`
-2. Update `RELEASE_NOTES.md`
-3. Commit, tag, and push:
-   ```bash
-   git add -A
-   git commit -m "Bump version to 1.0.0, update release notes"
-   git tag -a v1.0.0 -m "v1.0.0 - brief summary of release"
-   git push origin main --tags
-   ```
-4. Build and publish:
-   ```bash
-   gem build cov-loupe.gemspec
-   gem push cov-loupe-#{version-string}.gem
-   ```
 ---
 
 ## Code of Conduct
 
-Please review and follow the [Code of Conduct](docs/code_of_conduct.md). 
-Instances of unacceptable behavior may be reported through GitHub’s [Report Abuse form](https://github.com/contact/report-abuse).
-
----
+Please review and follow the [Code of Conduct](docs/code_of_conduct.md).
 
-Thank you for helping improve **cov-loupe**!
+Instances of unacceptable behavior may be reported through GitHub's [Report Abuse form](https://github.com/contact/report-abuse).