cov-loupe 3.0.0 → 4.0.0.pre

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

@@ -1,95 +0,0 @@
-# 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

@@ -1,159 +0,0 @@
-# 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

@@ -1,165 +0,0 @@
-# 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`

data/lib/cov_loupe/app_context.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module CovLoupe
-  # Encapsulates per-request configuration such as error handling and logging.
-  class AppContext
-    attr_reader :error_handler, :log_target, :mode
-
-    def initialize(error_handler:, log_target: nil, mode: :library)
-      @error_handler = error_handler
-      @log_target = log_target
-      @mode = mode
-    end
-
-    def with_error_handler(handler)
-      self.class.new(error_handler: handler, log_target: log_target, mode: mode)
-    end
-
-    def with_log_target(target)
-      self.class.new(error_handler: error_handler, log_target: target, mode: mode)
-    end
-
-    def mcp_mode? = mode == :mcp
-    def cli_mode? = mode == :cli
-    def library_mode? = mode == :library
-  end
-end

data/lib/cov_loupe/constants.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module CovLoupe
-  # Shared constants used across multiple components to avoid duplication.
-  # This ensures consistency between CLI option parsing and mode detection.
-  module Constants
-    # CLI options that expect an argument value following them.
-    # Used by both CoverageCLI and ModeDetector to correctly parse command-line arguments.
-    OPTIONS_EXPECTING_ARGUMENT = %w[
-      -r --resultset
-      -R --root
-      -f --format
-      -o --sort-order
-      -s --source
-      -c --context-lines
-      -S --staleness
-      -g --tracked-globs
-      -l --log-file
-      --error-mode
-    ].freeze
-  end
-end

data/lib/cov_loupe/coverage_reporter.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module CovLoupe
-  # Reports files with coverage below a specified threshold.
-  # Useful for displaying low coverage files after test runs.
-  #
-  # @example Basic usage in spec_helper.rb
-  #   SimpleCov.at_exit do
-  #     SimpleCov.result.format!
-  #     report = CovLoupe::CoverageReporter.report(threshold: 80, count: 5)
-  #     puts report if report
-  #   end
-  #
-  module CoverageReporter
-    module_function def report(threshold: 80, count: 5, model: nil)
-      model ||= CoverageModel.new
-      file_list = model.all_files(sort_order: :ascending)
-        .select { |f| f['percentage'] < threshold }
-        .first(count)
-      file_list = model.relativize(file_list)
-
-      return nil if file_list.empty?
-
-      lines = ["\nLowest coverage files (< #{threshold}%):"]
-      file_list.each do |f|
-        lines << format('  %5.1f%%  %s', f['percentage'], f['file'])
-      end
-      lines.join("\n")
-    end
-  end
-end

data/lib/cov_loupe/formatters.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-
-module CovLoupe
-  module Formatters
-    # Maps format symbols to their formatter lambdas
-    # Following the rexe pattern for simple, extensible formatting
-    FORMATTERS = {
-      table: ->(obj) { obj }, # Pass through - table formatting handled elsewhere
-      json: lambda(&:to_json),
-      pretty_json: ->(obj) { JSON.pretty_generate(obj) },
-      yaml: ->(obj) {
-        require 'yaml'
-        obj.to_yaml
-      },
-      awesome_print: ->(obj) {
-        require 'awesome_print'
-        obj.ai
-      }
-    }.freeze
-
-    # Maps format symbols to their required libraries
-    # Only loaded when the format is actually used
-    FORMAT_REQUIRES = {
-      yaml: 'yaml',
-      awesome_print: 'awesome_print'
-    }.freeze
-
-    # Returns the formatter lambda for the given format
-    def self.formatter_for(format)
-      FORMATTERS[format] or raise ArgumentError, "Unknown format: #{format}"
-    end
-
-    # Ensures required libraries are loaded for the given format
-    def self.ensure_requirements_for(format)
-      requirement = FORMAT_REQUIRES[format]
-      require requirement if requirement
-    end
-
-    # Formats an object using the specified format
-    def self.format(obj, format)
-      ensure_requirements_for(format)
-      formatter_for(format).call(obj)
-    rescue LoadError => e
-      gem_name = e.message[/-- (\S+)/, 1] || 'required gem'
-      raise LoadError, "The #{format} format requires the '#{gem_name}' gem. " \
-                       "Install it with: gem install #{gem_name}"
-    end
-  end
-end

data/lib/cov_loupe/mode_detector.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'constants'
-
-module CovLoupe
-  # Centralizes the logic for detecting whether to run in CLI or MCP server mode.
-  # This makes the mode detection strategy explicit and testable.
-  class ModeDetector
-    SUBCOMMANDS = %w[list summary raw uncovered detailed totals validate version].freeze
-
-    # Reference shared constant to avoid duplication with CoverageCLI
-    OPTIONS_EXPECTING_ARGUMENT = Constants::OPTIONS_EXPECTING_ARGUMENT
-
-    def self.cli_mode?(argv, stdin: $stdin)
-      # 1. Explicit flags that force CLI mode always win
-      cli_options = %w[--force-cli -h --help --version -v]
-      return true if argv.intersect?(cli_options)
-
-
-      # 2. Find the first non-option argument
-      first_non_option = find_first_non_option(argv)
-
-      # 3. If a non-option argument exists, it must be a CLI command (or an error)
-      return true if first_non_option
-
-      # 4. Fallback: If no non-option args, use TTY status to decide
-      stdin.tty?
-    end
-
-    def self.mcp_server_mode?(argv, stdin: $stdin)
-      !cli_mode?(argv, stdin: stdin)
-    end
-
-    # Scans argv and returns the first token that is not an option or a value for an option.
-    def self.find_first_non_option(argv)
-      pending_option = false
-      argv.each do |token|
-        if pending_option
-          pending_option = false
-          next
-        end
-
-        if token.start_with?('-')
-          # Check if the option is one that takes a value and isn't using '=' syntax.
-          pending_option = OPTIONS_EXPECTING_ARGUMENT.include?(token) && !token.include?('=')
-          next
-        end
-
-        # Found the first token that is not an option
-        return token
-      end
-      nil
-    end
-    private_class_method :find_first_non_option
-  end
-end