cov-loupe 3.0.0 → 4.0.0.pre

data/README.md

@@ -4,14 +4,19 @@
 </h1>
 
 <p style="text-align:center; margin-bottom:-36px;">
-  <img src="dev/images/cov-loupe-logo.png" alt="CovLoupe logo" width="560">
+  <img src="https://raw.githubusercontent.com/keithrbennett/cov-loupe/main/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.
+</p>
 
+<p style="text-align:center;">
+  <strong><a href="https://keithrbennett.github.io/cov-loupe/">Documentation Website</a></strong>
+</p>
 
 [![Gem Version](https://badge.fury.io/rb/cov-loupe.svg)](https://badge.fury.io/rb/cov-loupe)
+[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://keithrbennett.github.io/cov-loupe/)
 
 ## What is cov-loupe?
 
@@ -26,12 +31,11 @@ Works with any SimpleCov-generated `.resultset.json` file—no runtime dependenc
 ### Key Features
 
 - ✅ **Multiple interfaces** - MCP server, CLI, and Ruby API
-- **Annotated source code** - `--source full|uncovered` with `--context-lines N` for context lines
+- **Annotated source code** - `-s full|uncovered` / `--source full|uncovered` with `-c N` / `--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
 
@@ -51,6 +55,10 @@ Works with any SimpleCov-generated `.resultset.json` file—no runtime dependenc
 gem install cov-loupe
 ```
 
+### Upgrading
+
+If you are upgrading from a previous version, please refer to the [Migration Guides](docs/user/migrations/README.md).
+
 ### Generate Coverage Data
 
 ```sh
@@ -86,49 +94,67 @@ Repository: https://github.com/keithrbennett/cov-loupe  # <--- Project URL ---
 require "cov_loupe"
 
 model = CovLoupe::CoverageModel.new
-files = model.all_files
+list_result = model.list
+files = list_result["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 }
+# => { "file" => "lib/cov_loupe/model.rb", "summary" => { "covered" => 114, "total" => 118, "percentage" => 96.61 } }
 ```
 
+For advanced use cases, multiple models can each have their own data source and log file. See [Library API](docs/user/LIBRARY_API.md#per-model-context-advanced) for details.
+
 **MCP Server:**
 See [MCP Integration Guide](docs/user/MCP_INTEGRATION.md) for AI assistant setup.
 
-## Multi-Suite Coverage Merging
-
-### How It Works
+## Multi-Suite Coverage
 
-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.
+Projects with multiple test suites (RSpec + Cucumber, etc.) are automatically merged. See [Multi-Suite Coverage Merging](docs/user/ADVANCED_USAGE.md#multi-suite-coverage-merging) for details and current limitations.
 
-**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.
+## Documentation Index
 
-### Current Limitations
+Full documentation is available at **[https://keithrbennett.github.io/cov-loupe/](https://keithrbennett.github.io/cov-loupe/)**.
 
-**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.
+**User Guides:**
 
-**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:**
+- [Quick Start](docs/QUICKSTART.md) - Get up and running in 3 steps
+- [User Docs Overview](docs/user/README.md) - Map of all end-user guides
 - [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
+- [Library API](docs/user/LIBRARY_API.md) - Ruby API documentation
 - [Error Handling](docs/user/ERROR_HANDLING.md) - Error modes and exceptions
+- [MCP Integration](docs/user/MCP_INTEGRATION.md) - AI assistant configuration
+- [Troubleshooting](docs/user/TROUBLESHOOTING.md) - Common issues
+
+**Special Topics & Prompts:**
 
-**Reference:**
+- [CLI Fallback for LLMs](docs/user/CLI_FALLBACK_FOR_LLMS.md) - When MCP isn't available
+- [Sample MCP Prompts](docs/user/prompts/README.md) - Ready-to-use ChatGPT/Claude/Gemini prompts
+- [Migration Guides](docs/user/migrations/README.md)
+  - [Migrate to v4](docs/user/migrations/MIGRATING_TO_V4.md)
+  - [Migrate to v3](docs/user/migrations/MIGRATING_TO_V3.md)
+  - [Migrate to v2](docs/user/migrations/MIGRATING_TO_V2.md)
+
+**Developer Docs:**
+
+- [Developer Docs Overview](docs/dev/README.md) - Entry point for contributors
 - [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
+- [Development Guide](docs/dev/DEVELOPMENT.md) - Local dev workflow
+- [Releasing](docs/dev/RELEASING.md) - Release checklist
+- [Future Enhancements](docs/dev/FUTURE_ENHANCEMENTS.md) - Planned improvements
+- [Architecture Decision Records](docs/dev/arch-decisions/README.md) - Design history
+
+**Project Docs & Examples:**
+
+- [Contributing](docs/contributing.md)
+- [Code of Conduct](docs/code_of_conduct.md)
+- [Release Notes](docs/release_notes.md)
+- [License](docs/license.md)
+- [MCP Input Examples](docs/examples/mcp-inputs.md)
+- [Prompt Examples](docs/examples/prompts.md)
+- [Predicate Examples](docs/examples/success_predicates.md)
 
 ## Requirements
 
@@ -141,18 +167,20 @@ When a `.resultset.json` file contains multiple test suites (e.g., RSpec + Cucum
 `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
+# 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="--resultset /path/to/your/coverage"
+export COV_LOUPE_OPTS="-r /path/to/your/coverage"
 
 # MCP server configuration
-# Add to your MCP client config:
-# "args": ["--resultset", "/path/to/your/coverage"]
+# Add to your MCP client config (used as defaults for MCP tools):
+# "args": ["-r", "/path/to/your/coverage"]
 ```
 
-See [CLI Usage Guide](docs/user/CLI_USAGE.md#-r---resultset-path) for complete details.
+**MCP precedence:** For MCP tool calls, per-request JSON parameters win over the CLI args used to start the server (including `COV_LOUPE_OPTS`). If neither is provided, built-in defaults are used (`root: '.'`, `raise_on_stale: false`, etc.). Coverage data is cached globally and automatically reloaded when the resultset file changes.
+
+See [CLI Usage Guide](docs/user/CLI_USAGE.md) for complete details.
 
 
 
@@ -163,16 +191,38 @@ See [CLI Usage Guide](docs/user/CLI_USAGE.md#-r---resultset-path) for complete d
 ```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 | less         # display table in pager, best files first (worst at end)
 cov-loupe list | head -10     # truncate the table
 
-# Specific directory
+# Filter to specific patterns (see COV_LOUPE_OPTS best practice below)
 cov-loupe -g "lib/cov_loupe/tools/**/*.rb" list  # -g = --tracked-globs
 
 # Export for analysis
 cov-loupe -fJ list > coverage-report.json
 ```
 
+### Best Practice: Match SimpleCov Configuration
+
+For accurate coverage tracking and validation, set `COV_LOUPE_OPTS` to match your SimpleCov `track_files` patterns:
+
+```ruby
+# In spec_helper.rb or rails_helper.rb
+SimpleCov.start do
+  add_filter '/spec/'
+  track_files 'lib/**/*.rb'
+  track_files 'app/**/*.rb'
+end
+```
+
+```sh
+# 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.
+
 ### Working with JSON Output
 
 The `-fJ` flag enables programmatic processing of coverage data using command-line JSON tools.
@@ -204,21 +254,58 @@ cov-loupe -fJ list | rexe -ij -mb -oJ 'self["files"].select { |f| f["percentage"
 # Count files below threshold
 cov-loupe -fJ list | rexe -ij -mb -op 'self["files"].count { |f| f["percentage"] < 80 }'
 
-# Human-readable output with AwesomePrint
+# Human-readable output with AmazingPrint
 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.
+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 AmazingPrint output (`-oa`) for human consumption.
+
+### When Coverage Rows Are Skipped
+
+If a file in the resultset is missing on disk or has corrupt data, the CLI now logs and *warns* after rendering the report so operators immediately see that totals may be incomplete. Example table output:
+
+```text
+$ cov-loupe list
+┌─────────────────────────────┬─────────┬─────────┬────────────┬───────┐
+│ File                        │ Covered │ Total   │ % Covered  │ Stale │
+├─────────────────────────────┼─────────┼─────────┼────────────┼───────┤
+│ lib/foo.rb                  │       2 │       3 │     66.67% │       │
+│ lib/bar.rb                  │       1 │       3 │     33.33% │       │
+└─────────────────────────────┴─────────┴─────────┴────────────┴───────┘
+
+WARNING: 1 coverage row skipped due to errors:
+  - lib/deleted.rb: No coverage data found for file: lib/deleted.rb
+Run again with --raise-on-stale to exit when rows are skipped.
+```
+
+Pretty JSON (`-fJ`) reports still emit valid JSON to `stdout`; the warning continues to be printed on `stderr`:
+
+```text
+$ cov-loupe -fJ list
+{
+  "files": [
+    { "file": "lib/foo.rb", "covered": 2, "total": 3, "percentage": 66.67, "stale": null },
+    { "file": "lib/bar.rb", "covered": 1, "total": 3, "percentage": 33.33, "stale": null }
+  ],
+  "counts": { "total": 2, "ok": 2, "stale": 0 }
+}
+
+WARNING: 1 coverage row skipped due to errors:
+  - lib/deleted.rb: No coverage data found for file: lib/deleted.rb
+Run again with --raise-on-stale to exit when rows are skipped.
+```
+
+Use `--raise-on-stale true` (or `-S true`) to turn these warnings into hard failures for CI pipelines.
 
 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).
+For comprehensive JSON processing examples, see [user/EXAMPLES.md](docs/user/EXAMPLES.md).
 
 ### CI/CD Integration
 
 ```sh
-# Fail build if coverage is stale
-cov-loupe --staleness error || exit 1
+# Fail build if coverage is stale (--raise-on-stale or -S)
+cov-loupe --raise-on-stale true list || exit 1
 
 # Generate coverage report artifact
 cov-loupe -fJ list > artifacts/coverage.json
@@ -244,19 +331,41 @@ cov-loupe totals
 cov-loupe -fJ totals
 ```
 
+### Boolean CLI Options
+
+Boolean flags such as `--color` (short: `-C`) and `--raise-on-stale` (short: `-S`) require explicit boolean arguments. Recognized literals:
+
+|        |        |
+|--------|--------|
+| `yes`  | `no`   |
+| `y`    | `n`    |
+| `true` | `false`|
+| `t`    | `f`    |
+| `on`   | `off`  |
+| `+`    | `-`    |
+| `1`    | `0`    |
+
+Each row lists the equivalent `true` token (left) and `false` token (right).
+
+```sh
+cov-loupe --color false        # disable ANSI colors explicitly
+cov-loupe -C false             # short form
+cov-loupe --raise-on-stale yes # enforce stale coverage failures
+```
+
 ## 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`
+**MCP Tools:** `coverage_summary_tool`, `coverage_detailed_tool`, `coverage_raw_tool`, `uncovered_lines_tool`, `list_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
+- [MCP Integration Guide](docs/user/MCP_INTEGRATION.md#available-mcp-tools-functions) - MCP tools documentation
 
 ## Troubleshooting
 
-- **"command not found"** - See [Installation Guide](docs/user/INSTALLATION.md#path-configuration)
+- **"command not found"** - See [Installation Guide](docs/user/INSTALLATION.md#require-path)
 - **"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)
@@ -283,7 +392,7 @@ gem build cov-loupe.gemspec
 gem install cov-loupe-*.gem
 ```
 
-See [docs/dev/DEVELOPMENT.md](docs/dev/DEVELOPMENT.md) for more.
+See [dev/DEVELOPMENT.md](docs/dev/DEVELOPMENT.md) for more.
 
 ## SimpleCov Dependency
 
@@ -301,20 +410,14 @@ Contributions are welcome! Please:
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](docs/license.md) 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
+- **Changelog:** [RELEASE_NOTES.md](docs/release_notes.md)
 
 ---