cov-loupe 3.0.0

data/docs/user/V2-BREAKING-CHANGES.md

@@ -0,0 +1,472 @@
+# V2.0 Breaking Changes Guide
+
+This document describes all breaking changes introduced in version 2.0.0 of cov-loupe. These changes improve consistency, clarity, and alignment with Ruby conventions.
+
+---
+
+## Table of Contents
+
+- [Command Line Interface Changes](#command-line-interface-changes)
+  - [Options Must Precede Subcommands](#options-must-precede-subcommands)
+  - [--stale Renamed to --staleness](#--stale-renamed-to---staleness)
+  - [--source-context Renamed to --context-lines](#--source-context-renamed-to---context-lines)
+  - [--source Now Requires Explicit Mode](#--source-now-requires-explicit-mode)
+  - [--json Replaced with --format](#--json-replaced-with---format)
+  - [Error Mode Values Changed](#error-mode-values-changed)
+  - [--success-predicate Replaced with validate Subcommand](#--success-predicate-replaced-with-validate-subcommand)
+  - [Default Sort Order Changed](#default-sort-order-changed)
+- [MCP Tool Changes](#mcp-tool-changes)
+  - [stale Parameter Renamed to staleness](#stale-parameter-renamed-to-staleness)
+  - [Error Mode Values Changed](#error-mode-values-changed-1)
+  - [MCP Tool Arguments Use Symbols](#mcp-tool-arguments-use-symbols)
+- [Ruby API Changes](#ruby-api-changes)
+  - [CLIConfig Renamed to AppConfig](#cliconfig-renamed-to-appconfig)
+  - [AppConfig Field Changes](#appconfig-field-changes)
+- [Behavioral Changes](#behavioral-changes)
+  - [Context Lines Validation](#context-lines-validation)
+- [Migration Guide](#migration-guide)
+
+---
+
+## Command Line Interface Changes
+
+### Options Must Precede Subcommands
+
+**Change:** Global options must now appear *before* the subcommand, not after.
+
+**Rationale:** This aligns with standard Unix command conventions (e.g., `git`, `docker`) and simplifies argument parsing.
+
+**Before (v1.x):**
+```bash
+cov-loupe list --resultset coverage --format json
+cov-loupe summary lib/foo.rb --json
+```
+
+**After (v2.x):**
+```bash
+cov-loupe --resultset coverage --format json list
+cov-loupe --format json summary lib/foo.rb
+```
+
+**Migration:** Move all global options (flags like `-r`, `-f`, `-S`, etc.) before the subcommand name.
+
+---
+
+### --stale Renamed to --staleness
+
+**Change:** The `--stale` option has been renamed to `--staleness`. The short form `-S` is preserved.
+
+**Rationale:** Better describes what the option controls (staleness detection mode) and aligns with internal naming conventions.
+
+**Before (v1.x):**
+```bash
+cov-loupe --stale error list
+```
+
+**After (v2.x):**
+```bash
+cov-loupe --staleness error list
+# OR use the short form:
+cov-loupe -S error list
+```
+
+**Migration:** Replace `--stale` with `--staleness` (or continue using `-S`).
+
+---
+
+### --source-context Renamed to --context-lines
+
+**Change:** The `--source-context` option has been renamed to `--context-lines`.
+
+**Rationale:** More concise and clearer about what the option controls.
+
+**Before (v1.x):**
+```bash
+cov-loupe --source uncovered --source-context 3 uncovered lib/foo.rb
+```
+
+**After (v2.x):**
+```bash
+cov-loupe --source uncovered --context-lines 3 uncovered lib/foo.rb
+# OR use the short form:
+cov-loupe -s uncovered -c 3 uncovered lib/foo.rb
+```
+
+**Migration:** Replace `--source-context` with `--context-lines` (or use `-c`).
+
+---
+
+### --source Now Requires Explicit Mode
+
+**Change:** The `--source` option now requires an explicit mode argument (`full` or `uncovered`).
+
+**Rationale:** Eliminates ambiguity about what source display mode is being used.
+
+**Before (v1.x):**
+```bash
+# Implied 'full' mode
+cov-loupe --source summary lib/foo.rb
+```
+
+**After (v2.x):**
+```bash
+# Must specify mode explicitly
+cov-loupe --source full summary lib/foo.rb
+# OR
+cov-loupe --source uncovered summary lib/foo.rb
+```
+
+**Migration:** Add an explicit mode (`full` or `uncovered`) after `--source`.
+
+---
+
+### --json Replaced with --format
+
+**Change:** The `--json` flag (and related `-j`, `-J`, `--pretty-json` flags) have been removed. Use `--format` instead.
+
+**Rationale:** Supports multiple output formats beyond JSON (YAML, awesome_print, etc.) with a consistent interface.
+
+**Before (v1.x):**
+```bash
+cov-loupe --json list
+cov-loupe -j summary lib/foo.rb
+cov-loupe --pretty-json list
+```
+
+**After (v2.x):**
+```bash
+cov-loupe --format json list
+cov-loupe -f j summary lib/foo.rb        # Short form
+cov-loupe --format pretty-json list
+cov-loupe -f J list                       # Short form for pretty-json
+```
+
+**Available formats:**
+- `table` (default) - Human-readable table format
+- `json` or `j` - Single-line JSON
+- `pretty-json` or `J` - Pretty-printed JSON
+- `yaml` or `y` - YAML format
+- `awesome-print` or `ap` - Colored awesome_print format (requires `awesome_print` gem)
+
+**Migration:** Replace `--json` with `--format json` (or `-f j`). Replace `--pretty-json` with `--format pretty-json` (or `-f J`).
+
+---
+
+### Error Mode Values Changed
+
+**Change:** Error mode enum values have been renamed for clarity:
+- `on` → `log`
+- `trace` → `debug`
+
+The old values are **no longer supported**.
+
+**Rationale:** More descriptive names that better communicate what each mode does.
+
+**Before (v1.x):**
+```bash
+cov-loupe --error-mode on list
+cov-loupe --error-mode trace list
+```
+
+**After (v2.x):**
+```bash
+cov-loupe --error-mode log list
+cov-loupe --error-mode debug list
+# OR use short forms:
+cov-loupe --error-mode l list
+cov-loupe --error-mode d list
+```
+
+**Error modes:**
+- `off` (or `o`) - Silent, no error logging
+- `log` (or `l`) - Log errors to file (default)
+- `debug` (or `d`) - Verbose logging with backtraces
+
+**Migration:** Replace `--error-mode on` with `--error-mode log`. Replace `--error-mode trace` with `--error-mode debug`.
+
+---
+
+### --success-predicate Replaced with validate Subcommand
+
+**Change:** The `--success-predicate` flag has been removed. Use the `validate` subcommand instead.
+
+**Rationale:** Better fits the subcommand paradigm and provides a clearer interface for policy validation.
+
+**Before (v1.x):**
+```bash
+cov-loupe --success-predicate policy.rb
+```
+
+**After (v2.x):**
+```bash
+# File-based policy
+cov-loupe validate policy.rb
+
+# Inline policy (new feature)
+cov-loupe validate -i '->(m) { m.all_files.all? { |f| f["percentage"] >= 80 } }'
+```
+
+**Migration:** Replace `--success-predicate FILE` with `validate FILE`.
+
+---
+
+### Default Sort Order Changed
+
+**Change:** The default sort order for the `list` command changed from `ascending` to `descending`.
+
+**Rationale:** Most users want to see best-covered files first, not worst-covered files first.
+
+**Before (v1.x):**
+```bash
+# Shows worst coverage first by default
+cov-loupe list
+```
+
+**After (v2.x):**
+```bash
+# Shows best coverage first by default
+cov-loupe list
+
+# To get old behavior (worst first):
+cov-loupe --sort-order ascending list
+cov-loupe -o a list  # Short form
+```
+
+**Migration:** If you relied on ascending order (worst coverage first), explicitly specify `--sort-order ascending` or `-o a`.
+
+---
+
+## MCP Tool Changes
+
+### stale Parameter Renamed to staleness
+
+**Change:** All MCP tools that accepted a `stale` parameter now use `staleness` instead.
+
+**Rationale:** Aligns with the `CoverageModel` API and CLI option naming.
+
+**Before (v1.x):**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "coverage_summary_tool",
+    "arguments": {
+      "path": "lib/foo.rb",
+      "stale": "error"
+    }
+  }
+}
+```
+
+**After (v2.x):**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "coverage_summary_tool",
+    "arguments": {
+      "path": "lib/foo.rb",
+      "staleness": "error"
+    }
+  }
+}
+```
+
+**Affected tools:** All file-based tools (`coverage_summary_tool`, `coverage_detailed_tool`, `coverage_raw_tool`, `uncovered_lines_tool`) and aggregate tools (`all_files_coverage_tool`, `coverage_totals_tool`).
+
+**Migration:** Replace `"stale"` with `"staleness"` in all MCP tool calls.
+
+---
+
+### Error Mode Values Changed
+
+**Change:** Error mode enum values changed from `['off', 'on', 'trace']` to `['off', 'log', 'debug']`.
+
+**Rationale:** More descriptive names matching CLI changes.
+
+**Before (v1.x):**
+```json
+{
+  "error_mode": "on"
+}
+```
+
+**After (v2.x):**
+```json
+{
+  "error_mode": "log"
+}
+```
+
+**Migration:** Replace `"on"` with `"log"`, replace `"trace"` with `"debug"`.
+
+---
+
+### MCP Tool Arguments Use Symbols
+
+**Change:** Internally, MCP tools now normalize enum arguments to symbols (`:off`, `:error`, `:log`, `:debug`) for consistency with the Ruby API.
+
+**Impact:** This is mostly an internal change. MCP clients still send strings in JSON, but if you're using the tools programmatically in Ruby, be aware of the symbol usage.
+
+**Migration:** No action needed for MCP clients. For Ruby API users, see [Ruby API Changes](#ruby-api-changes).
+
+---
+
+## Ruby API Changes
+
+### CLIConfig Renamed to AppConfig
+
+**Change:** The `CLIConfig` class has been renamed to `AppConfig`.
+
+**Rationale:** The configuration is now used by both CLI and MCP modes, not just CLI.
+
+**Before (v1.x):**
+```ruby
+require 'cov_loupe/cli_config'
+config = CovLoupe::CLIConfig.new(root: '.', json: true)
+```
+
+**After (v2.x):**
+```ruby
+require 'cov_loupe/app_config'
+config = CovLoupe::AppConfig.new(root: '.', format: :json)
+```
+
+**Migration:** Replace `CLIConfig` with `AppConfig` in your code. Update require statements from `'cov_loupe/cli_config'` to `'cov_loupe/app_config'`.
+
+---
+
+### AppConfig Field Changes
+
+**Change:** Several `AppConfig` fields have been renamed or changed:
+
+| Old Field (v1.x)      | New Field (v2.x) | Type Change                          |
+|-----------------------|------------------|--------------------------------------|
+| `json`                | `format`         | `Boolean` → `Symbol` (`:json`, `:table`, etc.) |
+| `stale_mode`          | `staleness`      | Name change only                     |
+| `success_predicate`   | (removed)        | Moved to `validate` subcommand       |
+| (new)                 | `show_version`   | New field for `-v`/`--version`       |
+
+**Default value changes:**
+- `sort_order`: Changed from `:ascending` to `:descending`
+- `error_mode`: Changed from `:on` to `:log`
+
+**Before (v1.x):**
+```ruby
+config = CovLoupe::CLIConfig.new(
+  json: true,
+  stale_mode: :error,
+  error_mode: :on,
+  sort_order: :ascending
+)
+```
+
+**After (v2.x):**
+```ruby
+config = CovLoupe::AppConfig.new(
+  format: :json,
+  staleness: :error,
+  error_mode: :log,
+  sort_order: :descending  # New default
+)
+```
+
+**Migration:** Update field names when constructing `AppConfig`. Note the new defaults.
+
+---
+
+## Behavioral Changes
+
+### Context Lines Validation
+
+**Change:** The `--context-lines` option (formerly `--source-context`) now raises an `ArgumentError` if given a negative value. Previously, negative values were silently clamped to zero.
+
+**Rationale:** Fail fast and provide clear feedback for invalid input.
+
+**Before (v1.x):**
+```bash
+# Silently clamped to 0
+cov-loupe --source-context -5 uncovered lib/foo.rb
+```
+
+**After (v2.x):**
+```bash
+# Raises ArgumentError
+cov-loupe --context-lines -5 uncovered lib/foo.rb
+# Error: Context lines must be non-negative (got: -5)
+```
+
+**Migration:** Ensure `--context-lines` values are non-negative (>= 0).
+
+---
+
+## Migration Guide
+
+### Quick Checklist
+
+- [ ] Move all global options before subcommands in CLI invocations
+- [ ] Replace `--stale` with `--staleness` (or continue using `-S`)
+- [ ] Replace `--source-context` with `--context-lines` (or use `-c`)
+- [ ] Add explicit mode to `--source` (either `full` or `uncovered`)
+- [ ] Replace `--json` with `--format json` (or `-f j`)
+- [ ] Replace `--error-mode on` with `--error-mode log`
+- [ ] Replace `--error-mode trace` with `--error-mode debug`
+- [ ] Replace `--success-predicate FILE` with `validate FILE`
+- [ ] Update MCP tool calls: rename `stale` to `staleness`
+- [ ] Update MCP tool calls: replace error mode `"on"` with `"log"`, `"trace"` with `"debug"`
+- [ ] Update Ruby code: rename `CLIConfig` to `AppConfig`
+- [ ] Update Ruby code: rename `json` field to `format`, `stale_mode` to `staleness`
+- [ ] Explicitly set `--sort-order ascending` if you need worst-coverage-first sorting
+- [ ] Ensure `--context-lines` values are non-negative
+
+### Script Migration Example
+
+**Before (v1.x):**
+```bash
+#!/bin/bash
+cov-loupe list --json --stale error --sort-order ascending
+cov-loupe summary lib/foo.rb --json
+cov-loupe uncovered lib/bar.rb --source=uncovered --source-context 3
+cov-loupe --success-predicate policy.rb
+```
+
+**After (v2.x):**
+```bash
+#!/bin/bash
+cov-loupe --format json --staleness error --sort-order ascending list
+cov-loupe --format json summary lib/foo.rb
+cov-loupe --source uncovered --context-lines 3 uncovered lib/bar.rb
+cov-loupe validate policy.rb
+```
+
+### Environment Variable Migration
+
+**Before (v1.x):**
+```bash
+export COV_LOUPE_OPTS="--stale error --json"
+```
+
+**After (v2.x):**
+```bash
+export COV_LOUPE_OPTS="--staleness error --format json"
+```
+
+---
+
+## Getting Help
+
+If you encounter issues migrating to v2.0:
+
+1. Check the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) guide
+2. Review the [CLI_USAGE.md](CLI_USAGE.md) for complete CLI reference
+3. See [MCP_INTEGRATION.md](MCP_INTEGRATION.md) for MCP tool documentation
+4. Open an issue at https://github.com/keithrbennett/cov-loupe/issues
+
+---
+
+**See also:**
+- [RELEASE_NOTES.md](../../RELEASE_NOTES.md) - Full release notes with new features
+- [CLI_USAGE.md](CLI_USAGE.md) - Complete CLI reference
+- [MCP_INTEGRATION.md](MCP_INTEGRATION.md) - MCP tool reference

data/exe/cov-loupe

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Make it safe to run via symlink by resolving the real path
+root = File.expand_path('..', File.realpath(__FILE__))
+lib  = File.join(root, 'lib')
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+# Fail fast with a helpful message if Ruby is too old for this gem
+begin
+  require 'rubygems'
+  if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.2')
+    $stderr.puts "cov-loupe requires Ruby >= 3.2 (current: #{RUBY_VERSION})."
+    $stderr.puts 'Please run with a supported Ruby version (e.g., via rbenv, rvm, asdf).'
+    exit 1
+  end
+rescue
+  # If anything goes wrong, let the app load and potentially fail with a more specific error.
+end
+
+require 'cov_loupe'
+
+CovLoupe.run(ARGV)

data/lib/cov_loupe/app_config.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Configuration container for application options (used by both CLI and MCP modes)
+  # Uses Struct for simplicity and built-in functionality
+  AppConfig = Struct.new(
+    :root,
+    :resultset,
+    :format,
+    :sort_order,
+    :source_mode,
+    :source_context,
+    :color,
+    :error_mode,
+    :staleness,
+    :tracked_globs,
+    :log_file,
+    :show_version,
+    keyword_init: true
+  ) do
+    # Set sensible defaults - ALL SYMBOLS FOR ENUMS
+    def initialize(
+      root: '.',
+      resultset: nil,
+      format: :table,
+      sort_order: :descending,
+      source_mode: nil,
+      source_context: 2,
+      color: $stdout.tty?,
+      error_mode: :log,
+      staleness: :off,
+      tracked_globs: nil,
+      log_file: nil,
+      show_version: false
+    )
+      super
+    end
+
+    # Convenience method for CoverageModel initialization
+    def model_options
+      {
+        root: root,
+        resultset: resultset,
+        staleness: staleness,
+        tracked_globs: tracked_globs
+      }
+    end
+
+    # Convenience method for SourceFormatter initialization
+    def formatter_options
+      {
+        color_enabled: color
+      }
+    end
+  end
+end

data/lib/cov_loupe/app_context.rb

@@ -0,0 +1,26 @@
+# 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/base_tool.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'json'
+require_relative 'errors'
+require_relative 'error_handler'
+
+module CovLoupe
+  class BaseTool < ::MCP::Tool
+    COMMON_PROPERTIES = {
+      root: {
+        type: 'string',
+        description: 'Project root used to resolve relative paths ' \
+                     '(defaults to current workspace).',
+        default: '.'
+      },
+      resultset: {
+        type: 'string',
+        description: 'Path to the SimpleCov .resultset.json file (absolute or relative to root).'
+      },
+      staleness: {
+        type: 'string',
+        description: 'How to handle missing/outdated coverage data. ' \
+                     "'off' skips checks; 'error' raises.",
+        enum: [:off, :error],
+        default: :off
+      },
+      error_mode: {
+        type: 'string',
+        description: "Error handling mode: 'off' (silent), 'log' (log errors), " \
+            "'debug' (verbose with backtraces).",
+        enum: %w[off log debug],
+        default: 'log'
+      }
+    }.freeze
+
+    ERROR_MODE_PROPERTY = COMMON_PROPERTIES[:error_mode].freeze
+
+    TRACKED_GLOBS_PROPERTY = {
+      type: 'array',
+      description: 'Glob patterns for files that should exist in the coverage report' \
+                   '(helps flag new files).',
+      items: { type: 'string' }
+    }.freeze
+
+    PATH_PROPERTY = {
+      type: 'string',
+      description: 'Repo-relative or absolute path to the file whose coverage data you need.',
+      examples: ['lib/cov_loupe/model.rb']
+    }.freeze
+
+    def self.coverage_schema(additional_properties: {}, required: [])
+      {
+        type: 'object',
+        additionalProperties: false,
+        properties: COMMON_PROPERTIES.merge(additional_properties),
+        required: required
+      }.freeze
+    end
+
+    FILE_INPUT_SCHEMA = coverage_schema(
+      additional_properties: { path: PATH_PROPERTY },
+      required: ['path']
+    )
+    def self.input_schema_def = FILE_INPUT_SCHEMA
+
+    # Wrap tool execution with consistent error handling.
+    # Yields to the block and rescues any error, delegating to handle_mcp_error.
+    # This eliminates duplicate rescue blocks across all tools.
+    def self.with_error_handling(tool_name, error_mode:)
+      yield
+    rescue => e
+      handle_mcp_error(e, tool_name, error_mode: error_mode)
+    end
+
+    # Handle errors consistently across all MCP tools
+    # Returns an MCP::Tool::Response with appropriate error message
+    def self.handle_mcp_error(error, tool_name, error_mode: :log)
+      # Create error handler with the specified mode
+      error_handler = ErrorHandlerFactory.for_mcp_server(error_mode: error_mode.to_sym)
+
+      # Normalize to a CovLoupe::Error so we can handle/log uniformly
+      normalized = error.is_a?(CovLoupe::Error) \
+        ? error : error_handler.convert_standard_error(error)
+      log_mcp_error(normalized, tool_name, error_handler)
+      ::MCP::Tool::Response.new([{ 'type' => 'text', 'text' => "Error: #{normalized.user_friendly_message}" }])
+    end
+
+    # Respond with JSON as a resource to avoid clients mutating content types.
+    # The resource embeds the JSON string with a clear MIME type.
+    def self.respond_json(payload, name: 'data.json', pretty: false)
+      json = pretty ? JSON.pretty_generate(payload) : JSON.generate(payload)
+      ::MCP::Tool::Response.new([{ 'type' => 'text', 'text' => json }])
+    end
+
+    def self.log_mcp_error(error, tool_name, error_handler)
+      # Use the provided error handler for logging
+      error_handler.send(:log_error, error, tool_name)
+    end
+    private_class_method :log_mcp_error
+  end
+end