cov-loupe 3.0.0

data/docs/dev/README.md

@@ -0,0 +1,10 @@
+# Developer Documentation
+
+Resources for contributors working on SimpleCov MCP internals and release
+engineering.
+
+- [Architecture Overview](ARCHITECTURE.md) – subsystem layout and data flow
+- [Development Guide](DEVELOPMENT.md) – setup, testing, release workflow
+- [Branch Coverage Support](BRANCH_ONLY_COVERAGE.md) – implementation notes and limitations
+- [Architecture Decision Records](arch-decisions/README.md) – design history
+- [Presentations](presentations/cov-loupe-presentation.md) – slide deck for talks/demos

data/docs/dev/RELEASING.md

@@ -0,0 +1,146 @@
+# Release Process
+
+This document provides a checklist for releasing new versions of cov-loupe.
+
+## Pre-Release Checklist
+
+### 1. Documentation Review
+
+- [ ] **RELEASE_NOTES.md**: Update version header
+  - Update the version section header to final version (e.g., `## v#{version}`)
+  - For major releases: Ensure all breaking changes are documented with migration examples
+  - Verify new features and bug fixes are listed
+
+- [ ] **README.md**: Verify examples and feature list are current
+
+- [ ] **Documentation**: Ensure all docs in `docs/` are up to date
+
+### 2. Code Quality
+
+- [ ] **Tests**: All tests passing (`bundle exec rspec`)
+  - Verify via git hooks or run manually
+  - Check coverage is still excellent (>95%)
+
+- [ ] **Linting**: No Rubocop violations (`bundle exec rubocop`)
+  - Verify via git hooks or run manually
+
+- [ ] **Version**: Update `lib/cov_loupe/version.rb` to release version
+  - Remove `.pre.X` suffix for stable releases
+
+### 3. Cleanup
+
+- [ ] **Untracked files**: Review `git status` for files that should be:
+  - Added to `.gitignore` (temp files, local experiments, AI reports)
+  - Committed (valuable documentation or examples)
+  - Deleted (obsolete files)
+
+- [ ] **Temporary files**: Remove or ignore:
+  - `*.txt` files (r.txt, rubocop.txt, todo.txt, etc.)
+  - Experimental config files (`.rubocop.yml.new`, etc.)
+  - Local notes (CODING_AGENT_NOTES.md, architecture_insights.md, etc.)
+  - Work-in-progress directories (screencast/, untracked-ai-reports/, etc.)
+
+### 4. Build Verification
+
+- [ ] **Build gem**: Verify gem builds without errors
+```bash
+gem build cov-loupe.gemspec
+```
+
+- [ ] **Test installation**: Install and test locally
+```bash
+gem install cov-loupe-*.gem
+cov-loupe --version
+cov-loupe --help
+# Test on actual project
+cd /path/to/test/project
+cov-loupe list
+```
+
+### 5. Git Release
+
+- [ ] **Commit changes**: Commit version bump and RELEASE_NOTES.md updates
+```bash
+git add lib/cov_loupe/version.rb RELEASE_NOTES.md
+git commit -m "Release version #{version}"
+```
+
+- [ ] **Create tag**: Tag the release
+```bash
+git tag -a v#{version} -m "Version #{version}"
+```
+
+- [ ] **Push**: Push commits and tags
+```bash
+git push origin main --follow-tags
+```
+
+### 6. Publish Gem
+
+- [ ] **Build final gem**: Build from tagged version
+```bash
+gem build cov-loupe.gemspec
+```
+
+- [ ] **Push to RubyGems**: Publish the gem
+```bash
+gem push cov-loupe-#{version}.gem
+```
+
+- [ ] **Verify publication**: Check gem appears on RubyGems.org
+  - Visit https://rubygems.org/gems/cov-loupe
+  - Verify new version is listed
+  - Check that documentation links work
+
+### 7. GitHub Release
+
+- [ ] **Create GitHub release**: Go to https://github.com/keithrbennett/cov-loupe/releases/new
+  - Select the tag you just pushed
+  - Title: `Version #{version}`
+  - Description: Copy relevant sections from RELEASE_NOTES.md
+  - Attach the `.gem` file (optional)
+
+### 8. Post-Release
+
+- [ ] **Announcement**: Consider announcing on:
+  - Ruby Weekly
+  - Reddit (r/ruby)
+  - Slack/Discord communities
+  - Social media
+
+- [ ] **Update dependencies**: For projects using this gem
+  - Update your own projects to use new version
+  - Test integration
+
+- [ ] **Prepare for next release**:
+  - Optionally create a new section in RELEASE_NOTES.md for next version
+  - Consider bumping to next pre-release version if starting new development cycle
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **Major (X.0.0)**: Breaking changes
+- **Minor (0.X.0)**: New features, backward compatible
+- **Patch (0.0.X)**: Bug fixes, backward compatible
+- **Pre-release (X.Y.Z.pre.N)**: Development versions
+
+## Rollback Procedure
+
+If a critical issue is discovered after release:
+
+1. **Yank the gem** (removes from RubyGems but preserves install history):
+```bash
+gem yank cov-loupe -v #{version}
+```
+
+2. **Fix the issue** in a new patch version
+
+3. **Release the fixed version** following this checklist
+
+4. **Communicate**: Update GitHub release notes and announce the issue + fix
+
+## Notes
+
+- GitHub Actions runs tests and Rubocop on every commit (via hooks)
+- Pre-commit hooks ensure code quality before commits

data/docs/dev/arch-decisions/001-x-arch-decision.md

@@ -0,0 +1,95 @@
+# ADR 001: Dual-Mode Operation (CLI and MCP Server)
+
+[Back to main README](../../README.md)
+
+## Status
+
+Accepted
+
+## Context
+
+SimpleCov MCP needed to serve two distinct use cases:
+
+1. **Human users** wanting a command-line tool to inspect coverage reports in their terminal
+2. **AI agents and MCP clients** needing programmatic access to coverage data via the Model Context Protocol (MCP) over JSON-RPC
+
+We considered three approaches:
+
+1. **Separate binaries/gems**: Create `simplecov-cli` and `cov-loupe` as separate projects
+2. **Single binary with explicit mode flags**: Require users to pass `--mcp` or `--cli` to select mode
+3. **Automatic mode detection**: Single binary that automatically detects the operating mode based on input
+
+### Key Constraints
+
+- MCP servers communicate via JSON-RPC over stdin/stdout, so any human-readable output would corrupt the protocol
+- CLI users expect immediate, readable output without ceremony
+- The gem should be simple to install and use for both audiences
+- Mode detection must be reliable and unambiguous
+
+## Decision
+
+We implemented **automatic mode detection** via a single entry point (`CovLoupe.run`) that routes to either CLI or MCP server mode based on the execution context.
+
+### Mode Detection Algorithm
+
+The `ModeDetector` class (lib/cov_loupe/mode_detector.rb:6) implements a priority-based detection strategy:
+
+1. **Explicit CLI flags** (`--force-cli`, `-h`, `--help`, `--version`) → CLI mode
+2. **Presence of subcommands** (non-option arguments like `summary`, `list`) → CLI mode
+3. **TTY detection** fallback: `stdin.tty?` returns true → CLI mode, false → MCP server mode
+
+The implementation is in `lib/cov_loupe.rb:34-52`:
+
+```ruby
+def run(argv)
+  env_opts = extract_env_opts
+  full_argv = env_opts + argv
+
+  if ModeDetector.cli_mode?(full_argv)
+    CoverageCLI.new.run(argv)
+  else
+    CovLoupe.default_log_file = parse_log_file(full_argv)
+    MCPServer.new.run
+  end
+end
+```
+
+### Why This Works
+
+- **MCP clients** pipe JSON-RPC to stdin (not a TTY) and don't pass subcommands → routes to MCP server
+- **CLI users** run from an interactive terminal (TTY) or pass explicit subcommands → routes to CLI
+- **Edge cases** are covered by explicit flags (`--force-cli` for testing MCP mode from a TTY)
+
+## Consequences
+
+### Positive
+
+1. **User convenience**: Single gem to install (`gem install cov-loupe`), single executable (`cov-loupe`)
+2. **No ceremony**: Users don't need to remember mode flags or understand the MCP/CLI distinction
+3. **Testable**: The `ModeDetector` class is a pure function that can be tested in isolation
+4. **Clear separation**: CLI and MCP server implementations remain completely separate after routing
+
+### Negative
+
+1. **Complexity**: Requires maintaining the mode detection logic and keeping it accurate
+2. **Potential ambiguity**: In unusual environments (non-TTY CLI execution without subcommands), users must understand `--force-cli`
+3. **Shared dependencies**: Some components (error handling, coverage model) must work correctly in both modes
+
+### Trade-offs
+
+- **Versus separate gems**: More initial complexity, but better DX (single installation, no confusion about which gem to use)
+- **Versus explicit mode flags**: Slightly more "magical", but eliminates user error and reduces boilerplate
+
+### Future Constraints
+
+- Mode detection logic must remain stable and backward-compatible
+- Any new CLI subcommands must be registered in `ModeDetector::SUBCOMMANDS`
+- Shared components (like `CoverageModel`) must never output to stdout/stderr in ways that differ by mode
+
+## References
+
+- Implementation: `lib/cov_loupe.rb:34-52`
+- Mode detection: `lib/cov_loupe/mode_detector.rb:6-63`
+- CLI implementation: `lib/cov_loupe/cli.rb`
+- MCP server implementation: `lib/cov_loupe/mcp_server.rb`
+- Related ADR: [002: Context-Aware Error Handling](002-x-arch-decision.md)

data/docs/dev/arch-decisions/002-x-arch-decision.md

@@ -0,0 +1,159 @@
+# ADR 002: Context-Aware Error Handling Strategy
+
+[Back to main README](../../README.md)
+
+## Status
+
+Accepted
+
+## Context
+
+SimpleCov MCP operates in three distinct contexts, each with different error handling requirements:
+
+1. **CLI mode**: Human users expect friendly error messages, exit codes, and optional debug traces
+2. **MCP server mode**: AI agents/clients need structured error responses that don't crash the server
+3. **Library mode**: Embedding applications need exceptions they can catch and handle programmatically
+
+Initially, we considered uniform error handling across all modes, but this created poor user experiences:
+
+- CLI users saw raw exceptions with stack traces (scary and unhelpful)
+- MCP servers crashed on errors instead of returning error responses
+- Library users got friendly messages logged to stderr (unwanted side effects in their applications)
+
+### Key Requirements
+
+- **CLI**: User-friendly messages, meaningful exit codes, optional stack traces for debugging
+- **MCP Server**: Logged errors (to file, not stdout), structured JSON-RPC error responses, no server crashes
+- **Library**: Raise custom exceptions with no logging, allowing consumers to handle errors as needed
+- **Consistency**: Same underlying error types, but different presentation strategies
+
+## Decision
+
+We implemented a **context-aware error handling strategy** using three components:
+
+### 1. Custom Exception Hierarchy
+
+All errors inherit from `CovLoupe::Error` (lib/cov_loupe/errors.rb) with a `user_friendly_message` method:
+
+```ruby
+class Error < StandardError
+  def user_friendly_message
+    message  # Can be overridden in subclasses
+  end
+end
+
+class FileNotFoundError < FileError; end
+class CoverageDataError < Error; end
+class ResultsetNotFoundError < CoverageDataError; end
+# ... etc
+```
+
+This provides a unified interface for presenting errors to users while preserving exception types for programmatic handling.
+
+### 2. ErrorHandler Class
+
+The `ErrorHandler` class (lib/cov_loupe/error_handler.rb:7) provides configurable error handling behavior:
+
+```ruby
+class ErrorHandler
+  attr_accessor :error_mode, :logger
+
+  VALID_ERROR_MODES = [:off, :log, :debug].freeze
+
+  def initialize(error_mode: :log, logger: nil)
+    @error_mode = error_mode
+    @logger = logger
+  end
+
+  def handle_error(error, context: nil, reraise: true)
+    log_error(error, context)
+    if reraise
+      raise error.is_a?(CovLoupe::Error) ? error : convert_standard_error(error)
+    end
+  end
+end
+```
+
+The `convert_standard_error` method (lib/cov_loupe/error_handler.rb:37) transforms Ruby's standard errors into user-friendly custom exceptions:
+
+- `Errno::ENOENT` → `FileNotFoundError`
+- `JSON::ParserError` → `CoverageDataError`
+- `Errno::EACCES` → `FilePermissionError`
+
+### 3. ErrorHandlerFactory
+
+The `ErrorHandlerFactory` (lib/cov_loupe/error_handler_factory.rb:4) creates mode-specific handlers:
+
+```ruby
+module ErrorHandlerFactory
+  def self.for_cli(error_mode: :log)
+    ErrorHandler.new(error_mode: error_mode)
+  end
+
+  def self.for_library(error_mode: :off)
+    ErrorHandler.new(error_mode: :off)  # No logging
+  end
+
+  def self.for_mcp_server(error_mode: :log)
+    ErrorHandler.new(error_mode: :log)   # Logs to file
+  end
+end
+```
+
+### Error Flow by Mode
+
+**CLI Mode** (lib/cov_loupe/cli.rb):
+1. Catches all exceptions in the main run loop
+2. Uses `for_cli` handler to log errors if debug mode is enabled
+3. Displays `user_friendly_message` to the user
+4. Exits with appropriate code (1 for errors, 2 for usage errors)
+
+**MCP Server Mode** (lib/cov_loupe/base_tool.rb:46):
+1. Each tool wraps execution in a rescue block
+2. Uses `for_mcp_server` handler to log errors to `~/cov_loupe.log`
+3. Returns structured JSON-RPC error response
+4. Server continues running (no crashes)
+
+**Library Mode** (lib/cov_loupe.rb:75):
+1. Uses `for_library` handler with `error_mode: :off` (no logging)
+2. Raises custom exceptions directly
+3. Consumers catch and handle `CovLoupe::Error` subclasses
+
+## Consequences
+
+### Positive
+
+1. **Excellent UX**: Each context gets appropriate error handling behavior
+2. **Robustness**: MCP server never crashes on tool errors
+3. **Debuggability**: CLI users can enable stack traces with error modes, MCP errors are logged
+4. **Clean library API**: No unwanted side effects (logging, stderr output) when used as a library
+5. **Type safety**: Custom exceptions allow programmatic error handling by type
+
+### Negative
+
+1. **Complexity**: Three error handling paths to maintain and test
+2. **Coordination required**: All error types must implement `user_friendly_message` consistently
+3. **Error conversion overhead**: Standard errors must be converted to custom exceptions
+
+### Trade-offs
+
+- **Versus uniform error handling**: More code complexity, but dramatically better UX in each context
+- **Versus separate error classes per mode**: Single error hierarchy is simpler, factory pattern adds mode-specific behavior
+
+### Implementation Notes
+
+The `ErrorHandler.convert_standard_error` method (lib/cov_loupe/error_handler.rb:37) uses pattern matching on exception types and error messages to provide helpful, context-aware error messages. This includes:
+
+- Extracting filenames from system error messages
+- Detecting SimpleCov-specific error patterns
+- Providing actionable suggestions ("please run your tests first")
+
+## References
+
+- Custom exceptions: `lib/cov_loupe/errors.rb`
+- ErrorHandler implementation: `lib/cov_loupe/error_handler.rb:7-124`
+- ErrorHandlerFactory: `lib/cov_loupe/error_handler_factory.rb:4-29`
+- CLI error handling: `lib/cov_loupe/cli.rb` (rescue block in run method)
+- MCP tool error handling: `lib/cov_loupe/base_tool.rb:46-54`
+- Library mode: `lib/cov_loupe.rb:75-86`
+- Related ADR: [001: Dual-Mode Operation](001-x-arch-decision.md)

data/docs/dev/arch-decisions/003-x-arch-decision.md

@@ -0,0 +1,165 @@
+# ADR 003: Coverage Staleness Detection
+
+[Back to main README](../../README.md)
+
+## Status
+
+Accepted
+
+## Context
+
+Coverage data can become outdated when source files are modified after tests run. This creates misleading results:
+
+- Coverage percentages appear lower/higher than reality
+- Line numbers in coverage reports don't match the current source
+- AI agents and users may make decisions based on stale data
+
+We needed a staleness detection system that could:
+
+1. Detect when source files have been modified since coverage was collected
+2. Detect when source files have different line counts than coverage data
+3. Handle edge cases (deleted files, files without trailing newlines)
+4. Support both file-level and project-level checks
+5. Allow users to control whether staleness is reported or causes errors
+
+### Alternative Approaches Considered
+
+1. **No staleness checking**: Simple, but leads to confusing/incorrect reports
+2. **Single timestamp check**: Fast, but misses line count mismatches (files edited and reverted)
+3. **Content hashing**: Accurate, but expensive for large projects
+4. **Multi-type detection with modes**: More complex, but provides accurate detection with user control
+
+## Decision
+
+We implemented a **three-type staleness detection system** with configurable error modes.
+
+### Three Staleness Types
+
+The `StalenessChecker` class (lib/cov_loupe/staleness_checker.rb:8) detects three distinct types of staleness:
+
+1. **Type 'M' (Missing)**: The source file exists in coverage but is now deleted/missing
+   - Returned by `stale_for_file?` when `File.file?(file_abs)` returns false
+   - Example: File was deleted after tests ran
+
+2. **Type 'T' (Timestamp)**: The source file's mtime is newer than the coverage timestamp
+   - Detected by comparing `File.mtime(file_abs)` with coverage timestamp
+   - Example: File was edited after tests ran
+
+3. **Type 'L' (Length)**: The source file line count doesn't match the coverage lines array length
+   - Detected by comparing `File.foreach(path).count` with `coverage_lines.length`
+   - Handles edge case: Files without trailing newlines (adjusts count by 1)
+   - Example: Lines were added/removed without changing mtime (rare but possible with version control)
+
+### Implementation Details
+
+The core algorithm is in `compute_file_staleness_details` (lib/cov_loupe/staleness_checker.rb:137):
+
+```ruby
+def compute_file_staleness_details(file_abs, coverage_lines)
+  coverage_ts = coverage_timestamp
+  exists = File.file?(file_abs)
+  file_mtime = exists ? File.mtime(file_abs) : nil
+
+  cov_len = coverage_lines.respond_to?(:length) ? coverage_lines.length : 0
+  src_len = exists ? safe_count_lines(file_abs) : 0
+
+  newer = !!(file_mtime && file_mtime.to_i > coverage_ts.to_i)
+
+  # Adjust for missing trailing newline edge case
+  adjusted_src_len = src_len
+  if exists && cov_len.positive? && src_len == cov_len + 1 && missing_trailing_newline?(file_abs)
+    adjusted_src_len -= 1
+  end
+
+  len_mismatch = (cov_len.positive? && adjusted_src_len != cov_len)
+  newer &&= !len_mismatch  # Prioritize length mismatch over timestamp
+
+  {
+    exists: exists,
+    file_mtime: file_mtime,
+    coverage_timestamp: coverage_ts,
+    cov_len: cov_len,
+    src_len: src_len,
+    newer: newer,
+    len_mismatch: len_mismatch
+  }
+end
+```
+
+### Staleness Modes
+
+The checker supports two modes (lib/cov_loupe/staleness_checker.rb:9):
+
+- **`:off`** (default): Staleness is detected but only reported in responses, never raises errors
+- **`:error`**: Staleness raises `CoverageDataStaleError` or `CoverageDataProjectStaleError`
+
+This allows:
+- Interactive tools to show warnings without crashing
+- CI systems to fail builds on stale coverage
+- AI agents to decide how to handle staleness based on their goals
+
+### File-Level vs Project-Level Checks
+
+**File-level** (`check_file!` and `stale_for_file?`, lib/cov_loupe/staleness_checker.rb:25,49):
+- Checks a single file's staleness
+- Returns `false` or staleness type character ('M', 'T', 'L')
+- Used by single-file tools (summary, detailed, uncovered)
+
+**Project-level** (`check_project!`, lib/cov_loupe/staleness_checker.rb:59):
+- Checks all covered files plus optionally tracked files
+- Detects:
+  - Files newer than coverage timestamp
+  - Files deleted since coverage was collected
+  - Tracked files missing from coverage (newly added files)
+- Raises `CoverageDataProjectStaleError` with lists of problematic files
+- Used by `all_files_coverage_tool` and `coverage_table_tool`
+
+### Tracked Globs Feature
+
+The project-level check supports `tracked_globs` parameter to detect newly added files:
+
+```ruby
+# Detects if lib/**/*.rb files exist that have no coverage data
+checker.check_project!(coverage_map)  # with tracked_globs: ['lib/**/*.rb']
+```
+
+This helps teams ensure new files are included in test runs.
+
+## Consequences
+
+### Positive
+
+1. **Accurate detection**: Three types catch different staleness scenarios comprehensively
+2. **Edge case handling**: Missing trailing newlines handled correctly
+3. **User control**: Modes allow errors or warnings based on use case
+4. **Detailed information**: Staleness errors include specific file lists and timestamps
+5. **Project awareness**: Can detect newly added files that lack coverage
+
+### Negative
+
+1. **Complexity**: Three staleness types are harder to understand than a single timestamp check
+2. **Performance**: Line counting and mtime checks for every file add overhead
+3. **Maintenance burden**: Edge case logic (trailing newlines) requires careful testing
+4. **Ambiguity**: When multiple staleness types apply, prioritization logic (length > timestamp) may surprise users
+
+### Trade-offs
+
+- **Versus timestamp-only**: More accurate but slower and more complex
+- **Versus content hashing**: Fast enough for most projects, but can't detect "edit then revert" scenarios
+- **Versus no checking**: Essential for reliable coverage reporting, worth the complexity
+
+### Edge Cases Handled
+
+1. **Missing trailing newline**: Files without `\n` at EOF have `line_count == coverage_length + 1`, checker adjusts for this
+2. **Deleted files**: Appear as 'M' (missing) type staleness
+3. **Empty files**: `cov_len.positive?` guard prevents false positives
+4. **No coverage timestamp**: Defaults to 0, effectively disabling timestamp checks
+
+## References
+
+- Implementation: `lib/cov_loupe/staleness_checker.rb:8-168`
+- File-level checking: `lib/cov_loupe/staleness_checker.rb:25-55`
+- Project-level checking: `lib/cov_loupe/staleness_checker.rb:59-95`
+- Staleness detail computation: `lib/cov_loupe/staleness_checker.rb:137-166`
+- Error types: `lib/cov_loupe/errors.rb` (CoverageDataStaleError, CoverageDataProjectStaleError)
+- Usage in tools: `lib/cov_loupe/tools/all_files_coverage_tool.rb`, `lib/cov_loupe/model.rb`