simplecov-mcp 0.3.0 → 1.0.0

data/docs/TROUBLESHOOTING.md

@@ -0,0 +1,276 @@
+# Troubleshooting Guide
+
+This guide helps you diagnose and fix common issues with simplecov-mcp. Issues are organized by symptom for quick lookup.
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [Running Issues](#running-issues)
+- [Coverage Data Issues](#coverage-data-issues)
+- [MCP Server Issues](#mcp-server-issues)
+- [Development Issues](#development-issues)
+- [Diagnostic Commands](#diagnostic-commands)
+
+## Installation Issues
+
+### "command not found: simplecov-mcp"
+
+**Symptom:** Shell can't find the simplecov-mcp executable.
+
+**Solutions:**
+
+1. **Verify installation:**
+   ```bash
+   gem list simplecov-mcp
+   ```
+   If not listed, install it: `gem install simplecov-mcp`
+
+2. **Check PATH:**
+   ```bash
+   which simplecov-mcp
+   echo $PATH | grep -o "$(gem env gemdir)/bin"
+   ```
+
+3. **Rehash version manager shims:**
+   ```bash
+   # rbenv
+   rbenv rehash
+
+   # asdf
+   asdf reshim ruby
+
+   # RVM
+   rvm reload
+   ```
+
+4. **Use bundler as workaround:**
+   ```bash
+   bundle exec simplecov-mcp
+   ```
+
+### "cannot load such file -- mcp"
+
+**Symptom:** Ruby can't load the mcp gem dependency.
+
+**Cause:** Ruby version is too old (< 3.2).
+
+**Solution:**
+
+```bash
+# Check your Ruby version
+ruby -v  # Should be 3.2.0 or higher
+
+# Upgrade Ruby, then reinstall
+gem install simplecov-mcp
+```
+
+### Multiple versions causing conflicts
+
+**Symptom:** "wrong number of arguments" or other unexpected errors.
+
+**Solution:** Clean up and reinstall:
+
+```bash
+gem uninstall simplecov-mcp
+# Select "All versions" if prompted
+gem install simplecov-mcp
+```
+
+## Running Issues
+
+### Running the Test Suite with RVM (Codex macOS)
+
+Codex's macOS sandbox forbids `/bin/ps`; RVM shells need it. When you run `bundle exec rspec` there, the shell falls back to macOS Ruby 2.6 and Bundler dies with `Gem::Resolver::APISet::GemParser` errors.
+
+**Workarounds:**
+
+- Run outside the macOS sandbox (Codex on Ubuntu, Gemini, Claude Code, local shells) or use a version manager that does not invoke `ps`.
+- Or execute RSpec with explicit RVM paths:
+  ```bash
+  PATH="$HOME/.rvm/gems/ruby-3.4.5@simplecov-mcp/bin:$HOME/.rvm/rubies/ruby-3.4.5/bin:$PATH" \
+    GEM_HOME="$HOME/.rvm/gems/ruby-3.4.5@simplecov-mcp" \
+    GEM_PATH="$HOME/.rvm/gems/ruby-3.4.5@simplecov-mcp:$HOME/.rvm/gems/ruby-3.4.5@global" \
+    $HOME/.rvm/rubies/ruby-3.4.5/bin/bundle exec rspec
+  ```
+- Use a different AI coding agent and/or operating system.
+
+## Coverage Data Issues
+
+### Missing `coverage/.resultset.json`
+
+`simplecov-mcp` only reads coverage data; it never generates it. If you see "Could not find .resultset.json":
+
+1. Run the test suite with SimpleCov enabled (default project setup already enables it).
+   ```bash
+   bundle exec rspec
+   ls coverage/.resultset.json
+   ```
+2. If your coverage lives elsewhere, point the tools at it:
+   ```bash
+   simplecov-mcp --resultset build/coverage/.resultset.json
+   # or
+   export SIMPLECOV_MCP_OPTS="--resultset build/coverage"
+   ```
+
+### Stale Coverage Errors
+
+`--stale error` (or `staleness: 'error'`) compares file mtimes and line counts to the coverage snapshot. When it fails:
+
+- Regenerate coverage (`bundle exec rspec`) so the snapshot matches current sources.
+- Or drop back to warning-only behaviour using `--stale off` / `staleness: 'off'`.
+
+If you only care about a subset of files, supply `--tracked-globs` (CLI) or `tracked_globs:` (API) so new files outside those globs do not trigger staleness.
+
+### "No coverage data found for file"
+
+The model looks up files by absolute path, then cwd-relative path, then basename. If you still hit this error:
+
+1. Verify the file is listed in the coverage table (`simplecov-mcp list | grep model.rb`).
+2. Use the exact project-relative path that SimpleCov recorded (case-sensitive, no symlinks).
+3. If the file truly never executes under tests, add coverage or exclude it from your workflow.
+
+## MCP Server Issues
+
+### MCP Server Won't Start
+
+**Symptom:** AI assistant reports "Could not connect to MCP server".
+
+**Diagnostic steps:**
+
+1. **Verify executable exists and works:**
+   ```bash
+   which simplecov-mcp
+   simplecov-mcp version
+   ```
+
+2. **Test MCP server mode manually:**
+   ```bash
+   echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | simplecov-mcp
+   ```
+   Should return JSON-RPC response.
+
+3. **Check Ruby version in MCP context:**
+   ```bash
+   # The version your MCP client sees might differ from your shell
+   $(which simplecov-mcp) --version
+   ```
+
+4. **Use absolute path in MCP config:**
+   ```bash
+   # Find absolute path
+   which simplecov-mcp
+
+   # Update your MCP client config to use this path
+   ```
+
+### MCP Tools Not Available in AI Assistant
+
+**Symptom:** AI says "I don't have access to simplecov-mcp tools".
+
+**Solutions:**
+
+1. **Restart AI assistant** - Config changes often require restart
+
+2. **Verify MCP server is configured:**
+   ```bash
+   # For Claude Code
+   claude mcp list
+
+   # Check logs
+   tail -f ~/simplecov_mcp.log
+   ```
+
+3. **Try CLI fallback:**
+   ```bash
+   # If MCP isn't working, use CLI with --json
+   simplecov-mcp list --json
+   simplecov-mcp summary lib/file.rb --json
+   ```
+
+### Path Issues with Version Managers
+
+**Symptom:** Works in terminal but not in MCP client.
+
+**Cause:** MCP client doesn't have your shell environment (PATH, RVM, etc.).
+
+**Solution:** Use absolute paths in MCP configuration:
+
+```bash
+# For rbenv/asdf
+which simplecov-mcp
+# Use this path in MCP config
+
+# For RVM, create wrapper
+rvm wrapper ruby-3.3.8 simplecov-mcp simplecov-mcp
+# Use: ~/.rvm/wrappers/ruby-3.3.8/simplecov-mcp
+```
+
+## Development Issues
+
+### Test Suite Failures
+
+**Symptom:** `bundle exec rspec` fails with coverage errors.
+
+**Common causes:**
+
+1. **Stale coverage data** - Delete `coverage/` directory and re-run
+2. **SimpleCov not loaded** - Check `spec/spec_helper.rb` requires SimpleCov
+3. **Wrong Ruby version** - Verify Ruby >= 3.2
+
+## Diagnostic Commands
+
+Before reporting an issue, run these diagnostic commands and include the output:
+
+```bash
+# System info
+ruby -v
+gem -v
+bundle -v
+
+# simplecov-mcp info
+gem list simplecov-mcp
+which simplecov-mcp
+simplecov-mcp version
+
+# Test basic functionality
+simplecov-mcp --help
+simplecov-mcp list 2>&1
+
+# Check coverage data
+ls -la coverage/.resultset.json
+head -20 coverage/.resultset.json
+
+# Test MCP mode
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | simplecov-mcp 2>&1
+```
+
+## Getting More Help
+
+If the above doesn't solve your problem:
+
+1. **Check error mode** - Run with `--error-mode trace` for full stack traces:
+   ```bash
+   simplecov-mcp --error-mode trace summary lib/file.rb
+   ```
+
+2. **Check logs:**
+   ```bash
+   # MCP server logs
+   tail -50 simplecov_mcp.log
+
+   # Or specify custom log location
+   simplecov-mcp --log-file /tmp/debug.log summary lib/file.rb
+   ```
+
+3. **Search existing issues:**
+   https://github.com/keithrbennett/simplecov-mcp/issues
+
+4. **Report a bug:**
+   Include output from [Diagnostic Commands](#diagnostic-commands) above
+
+## Related Documentation
+
+- [Installation Guide](INSTALLATION.md) - Setup and PATH configuration
+- [CLI Usage](CLI_USAGE.md) - Command-line options and examples
+- [MCP Integration](MCP_INTEGRATION.md) - MCP server configuration
+- [Error Handling](ERROR_HANDLING.md) - Understanding error modes

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

@@ -0,0 +1,93 @@
+# ADR 001: Dual-Mode Operation (CLI and MCP Server)
+
+## 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 `simplecov-mcp` 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 (`SimpleCovMcp.run`) that routes to either CLI or MCP server mode based on the execution context.
+
+### Mode Detection Algorithm
+
+The `ModeDetector` class (lib/simplecov_mcp/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/simplecov_mcp.rb:34-52`:
+
+```ruby
+def run(argv)
+  env_opts = parse_env_opts_for_mode_detection
+  full_argv = env_opts + argv
+
+  if ModeDetector.cli_mode?(full_argv)
+    CoverageCLI.new.run(argv)
+  else
+    SimpleCovMcp.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 simplecov-mcp`), single executable (`simplecov-mcp`)
+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/simplecov_mcp.rb:34-52`
+- Mode detection: `lib/simplecov_mcp/mode_detector.rb:6-63`
+- CLI implementation: `lib/simplecov_mcp/cli.rb`
+- MCP server implementation: `lib/simplecov_mcp/mcp_server.rb`
+- Related ADR: [002: Context-Aware Error Handling](002-x-arch-decision.md)

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

@@ -0,0 +1,157 @@
+# ADR 002: Context-Aware Error Handling Strategy
+
+## 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 `SimpleCovMcp::Error` (lib/simplecov_mcp/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/simplecov_mcp/error_handler.rb:7) provides configurable error handling behavior:
+
+```ruby
+class ErrorHandler
+  attr_accessor :error_mode, :logger
+
+  VALID_ERROR_MODES = [:off, :on, :trace].freeze
+
+  def initialize(error_mode: :on, 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?(SimpleCovMcp::Error) ? error : convert_standard_error(error)
+    end
+  end
+end
+```
+
+The `convert_standard_error` method (lib/simplecov_mcp/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/simplecov_mcp/error_handler_factory.rb:4) creates mode-specific handlers:
+
+```ruby
+module ErrorHandlerFactory
+  def self.for_cli(error_mode: :on)
+    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: :on)
+    ErrorHandler.new(error_mode: :on)   # Logs to file
+  end
+end
+```
+
+### Error Flow by Mode
+
+**CLI Mode** (lib/simplecov_mcp/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/simplecov_mcp/base_tool.rb:46):
+1. Each tool wraps execution in a rescue block
+2. Uses `for_mcp_server` handler to log errors to `~/simplecov_mcp.log`
+3. Returns structured JSON-RPC error response
+4. Server continues running (no crashes)
+
+**Library Mode** (lib/simplecov_mcp.rb:75):
+1. Uses `for_library` handler with `error_mode: :off` (no logging)
+2. Raises custom exceptions directly
+3. Consumers catch and handle `SimpleCovMcp::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/simplecov_mcp/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/simplecov_mcp/errors.rb`
+- ErrorHandler implementation: `lib/simplecov_mcp/error_handler.rb:7-124`
+- ErrorHandlerFactory: `lib/simplecov_mcp/error_handler_factory.rb:4-29`
+- CLI error handling: `lib/simplecov_mcp/cli.rb` (rescue block in run method)
+- MCP tool error handling: `lib/simplecov_mcp/base_tool.rb:46-54`
+- Library mode: `lib/simplecov_mcp.rb:75-86`
+- Related ADR: [001: Dual-Mode Operation](001-x-arch-decision.md)

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

@@ -0,0 +1,163 @@
+# ADR 003: Coverage Staleness Detection
+
+## 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/simplecov_mcp/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/simplecov_mcp/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/simplecov_mcp/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/simplecov_mcp/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/simplecov_mcp/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/simplecov_mcp/staleness_checker.rb:8-168`
+- File-level checking: `lib/simplecov_mcp/staleness_checker.rb:25-55`
+- Project-level checking: `lib/simplecov_mcp/staleness_checker.rb:59-95`
+- Staleness detail computation: `lib/simplecov_mcp/staleness_checker.rb:137-166`
+- Error types: `lib/simplecov_mcp/errors.rb` (CoverageDataStaleError, CoverageDataProjectStaleError)
+- Usage in tools: `lib/simplecov_mcp/tools/all_files_coverage_tool.rb`, `lib/simplecov_mcp/model.rb`