cov-loupe 3.0.0 → 4.0.0.pre

checksums.yaml

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

data/AGENTS.md

@@ -0,0 +1,230 @@
+# AGENTS.md – Codex Cloud Guide
+
+[Project overview in README](README.md)
+
+This file provides guidance to Codex, Claude Code (claude.ai/code), Gemini CLI, and any related agents when working with this repository. Treat it as the canonical reference for workflows, tooling, and expectations; update it directly whenever new agent instructions are required.
+
+## Mission
+- Pull accurate coverage data and project facts for users by driving cov-loupe tools rather than
+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.
+
+## Running External Commands
+
+- When running shell commands on this project, use a Bash login shell where possible: run commands via bash -lc '<command>' (or the platform’s equivalent) rather than relying on the default shell.
+- If practical, use workdir features of the agent rather than relying on `cd` in the command string
+
+## Environment & Execution
+
+Prefer project‑local tools and scripts (for example, bin/ scripts, package.json scripts, Makefile targets) instead of ad‑hoc one‑off commands when building, testing, or running the project.
+
+
+- Prefer `rg`/`rg --files` for searches; switch only if ripgrep is unavailable.
+- Sandbox: workspace write access; network is restricted. Request escalation (`with_escalated_permissions` + short justification) only when indispensable.
+- Approval mode is `on-request`: retry failed-but-needed commands with escalation rather than asking the user manually.
+- 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.
+
+## 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`.
+- 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
+  - `bundle exec rspec` – run rspec (currently not working in Codex for macOS)
+  - `bundle exec exe/cov-loupe ...` – run CLI or MCP server directly
+  - `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.
+
+### Key Technologies
+- **Ruby** – implementation language and packaging format (gem).
+- **MCP (Model Context Protocol)** – JSON-RPC server for editor/agent integrations.
+- **RSpec** – primary test framework.
+- **Simplecov** - test coverage analysis tool
+
+### Dual Mode Architecture
+`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/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`).
+
+### 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.
+3. Provide coverage data in multiple formats: raw arrays, summaries, uncovered lines, per-line details, totals, and formatted tables.
+
+## Building, Running, and Testing
+
+### Prerequisites
+- Ruby >= 3.2
+- Bundler
+
+### Installation
+```sh
+bundle install
+```
+
+### Running Tests
+Run the full suite (and generate `coverage/.resultset.json`) with:
+```sh
+bundle exec rspec
+```
+You can also run the default Rake task:
+```sh
+rake
+```
+Use `bundle exec rspec spec/path_spec.rb` to target specific specs when needed.
+
+### Manual Testing
+- Run the CLI locally during development:
+  ```sh
+  bundle exec exe/cov-loupe
+  ```
+- Inspect help output (works whether or not the gem is installed globally):
+  ```sh
+  bundle exec exe/cov-loupe --help
+  # or
+  cov-loupe --help
+  ```
+- Exercise 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
+  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"help_tool","arguments":{}}}' | bundle exec exe/cov-loupe
+  ```
+
+### Building
+```sh
+gem build cov-loupe.gemspec
+gem install cov-loupe-*.gem
+```
+
+## CLI Usage
+
+Run `bundle exec exe/cov-loupe` for up-to-date usage information.
+
+The `cov-loupe` executable can be run directly (`bundle exec exe/cov-loupe ...` or `cov-loupe ...` when installed). Core subcommands:
+- `list` – show a table of all files and their coverage.
+- `summary <path>` – show covered/total/percentage for one file.
+- `raw <path>` – print the raw SimpleCov lines array.
+- `uncovered <path>` – list uncovered line numbers.
+- `detailed <path>` – show per-line hit counts and coverage status.
+- `totals` – show aggregated totals for the project.
+- `validate <file|-i code>` – run a Ruby predicate to enforce coverage policies.
+- `version` – show version information.
+
+## 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"}}}
+```
+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.
+
+## 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`.
+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.
+
+## 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.
+- 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.
+
+### 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`.
+
+### Path Resolution Strategy
+1. Attempt exact absolute path matches within the coverage data.
+2. Retry using paths without the working-directory prefix.
+
+### 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.
+- SimpleCov is a lazy-loaded dependency used only when multi-suite resultsets require merging.
+
+## Git Workflow
+1. **Run Tests:** Always run Rubocop and the test suite to verify your changes before considering them complete:
+    ```bash
+   bundle exec rubocop # and then `rubocop -A` if necessary
+   bundle exec rspec
+    ```
+2. **Do Not Commit:** Never execute `git commit` directly. Instead, stage changes with `git add` and propose a clear, concise commit message for the user to use.
+3. **Selective Staging:** Never assume that all uncommitted files are intended to be committed. Do not use `git add .` or similar catch-all commands. Explicitly stage only the files relevant to the current task.
+4. **Use `--no-pager`:** When running git commands that may produce long output (e.g., `git diff`, `git log`), include `--no-pager` between `git` and the subcommand to prevent paging issues in automated environments:
+   ```sh
+   git --no-pager diff
+   git --no-pager log --oneline
+   ```
+5. **Release Scripts:** The project uses `bin/pre-release-check` to automate preflight steps only. Do not flag missing automation for tagging, `git push`, or `gem push`; those are intentionally manual (e.g., MFA prompts, error handling).
+
+## 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.
+- 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.
+
+## Testing Notes
+- Run `bundle exec rspec` to generate the `coverage/.resultset.json` analyzed by the tools.
+- SimpleCov loads lazily only when merging multi-suite resultsets.
+- Test files live in `spec/` and follow standard RSpec conventions.
+- Where possible, make tests more DRY (concise) by iterating over arrays of test setups.
+- If there are test errors that would never occur in production (i.e. that are errors due to the test environment and not logic errors), the agent should modify test code and not production code, and make the solution as simple as possible.
+
+## Troubleshooting Notes
+- Coverage lookup order: 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.
+- `COV_LOUPE_OPTS` can set default CLI flags (command-line arguments still win).
+- Mode selection: Use `-m mcp`/`--mode mcp` to run as MCP server, or `-m cli`/`--mode cli` (or omit for default) for CLI mode.
+
+## Rubocop Linting
+
+Rubocop is used to enforce consistent code styling and best programming practices.
+Write code consistent with Rubocop configured rules, e.g. indentation and use of
+`it_behaves_like` instead of `include_examples` in RSpec.
+
+### Sandbox Environments
+
+If running RuboCop in a sandboxed environment (e.g., AI coding assistants with file system restrictions), you may encounter cache write failures:
+
+```
+Read-only file system @ rb_sysopen
+  → /home/user/.cache/rubocop_cache/...
+```
+
+**Workaround:** Use the `--cache false` flag:
+```sh
+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.
+
+## 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.
+
+## 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.

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# Refer to AGENTS.md
+
+For detailed instructions on using Claude Code, Gemini CLI, and related agents in this repo, read @AGENTS.md first.
+
+When you identify the need to add or expand instructions about how to use these tools, make those additions in @AGENTS.md rather than here, and treat this file as a high-level pointer.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,62 @@
+# Contributor Covenant Code of Conduct
+
+[Back to main README](docs/index.md)
+
+## Our Pledge
+
+We as members, contributors, and users pledge to make participation in this
+project a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+* Demonstrating empathy and kindness toward others  
+* Being respectful of differing opinions, viewpoints, and experiences  
+* Giving and gracefully accepting constructive feedback  
+* Taking responsibility for our mistakes and learning from them  
+* Focusing on what is best for the community, not just ourselves  
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances  
+* Trolling, insulting or derogatory comments, and personal or political attacks  
+* Public or private harassment  
+* Publishing others’ private information, such as physical or email addresses, without explicit permission  
+* Any other conduct which could reasonably be considered inappropriate in a professional setting  
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported through GitHub’s [Report Abuse form](https://github.com/contact/report-abuse).
+
+If inappropriate behavior occurs in this repository’s issues, pull requests,
+or discussions, the maintainer may delete comments, lock threads, or block
+offending users from further participation.
+
+These actions are at the sole discretion of the maintainer and are intended to
+maintain a safe, respectful, and productive environment for everyone.
+
+## Scope
+
+This Code of Conduct applies to all project spaces within this repository and
+also applies when an individual is officially representing the project or its
+community in public spaces.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at 
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+
+For answers to common questions, see the FAQ at 
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq).
+
+[homepage]: https://www.contributor-covenant.org

data/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to cov-loupe
+
+[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.
+
+---
+
+## How to Contribute
+
+### 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).
+
+### 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**:  
+   ```bash
+   bundle install
+   ```
+1. Make your changes, conforming to the project's coding style.
+1. **Run tests** to verify your changes:  
+   ```bash
+   bundle exec rspec
+   ```
+1. **Lint the code**:  
+   ```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.
+
+---
+
+## Development Setup
+
+This project requires Ruby >= 3.2 (due to the `mcp` gem dependency). Typical workflow:
+
+```bash
+git clone https://github.com/keithrbennett/cov-loupe.git
+cd cov-loupe
+bundle install
+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
+
+---
+
+## Documentation
+
+This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) to build and serve documentation.
+
+**Quick start:**
+```bash
+pip3 install -r requirements.txt
+mkdocs serve  # View at http://127.0.0.1:8000
+```
+
+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
+
+---
+
+## Release Process (maintainer only)
+
+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).
+
+---
+
+Thank you for helping improve **cov-loupe**!

data/GEMINI.md

@@ -0,0 +1,5 @@
+# Refer to AGENTS.md
+
+For detailed instructions on using Claude Code, Gemini CLI, and related agents in this repo, read @AGENTS.md first.
+
+When you identify the need to add or expand instructions about how to use these tools, make those additions in @AGENTS.md rather than here, and treat this file as a high-level pointer.