cov-loupe 3.0.0 → 4.0.0.pre

data/docs/user/installing-a-prelease-version-of-covloupe.md

@@ -0,0 +1,43 @@
+# Installing a Prerelease Version of cov-loupe
+
+Prerelease versions of gems (those containing `.pre`, `.alpha`, `.beta`, `.rc`, etc.) are **not** installed by default in RubyGems.
+
+## Command Line Installation
+
+When users run `gem install cov-loupe`, RubyGems installs the latest **stable** version, skipping any prereleases.
+
+To install a prerelease, you must explicitly opt in:
+
+```sh
+# Install the latest prerelease
+gem install cov-loupe --pre
+
+# Install a specific prerelease version
+gem install cov-loupe -v 4.0.0.pre
+```
+
+## Gemfile
+
+In a Gemfile, you need to explicitly specify the prerelease version:
+
+```ruby
+# Exact version
+gem 'cov-loupe', '4.0.0.pre'
+
+# Or allow any 4.0.0 prerelease
+gem 'cov-loupe', '~> 4.0.0.pre'
+```
+
+Without an explicit version constraint that includes the prerelease suffix, Bundler will skip prereleases just like `gem install` does.
+
+## Gemspec Dependencies
+
+For gemspec dependencies on prerelease gems, you must specify the prerelease version explicitly:
+
+```ruby
+spec.add_dependency 'cov-loupe', '~> 4.0.0.pre'
+```
+
+## Key Point
+
+Version constraints like `~> 4.0` or `>= 4.0` will **not** match prereleases. You must include the prerelease segment in the constraint for it to match.

data/docs/user/{V2-BREAKING-CHANGES.md → migrations/MIGRATING_TO_V2.md}

@@ -1,23 +1,20 @@
-# V2.0 Breaking Changes Guide
+# V2.0 Breaking Changes and Migration 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.
+[Back to main README](../../index.md)
+
+This document describes all breaking changes introduced in version 2.0.0 of simplecov-mcp. These changes improve consistency, clarity, and alignment with Ruby conventions.
+
+> Note: Current versions use the boolean `--raise-on-stale` / `raise_on_stale` flag (short form `-S`) for staleness enforcement. The `--staleness` and `stale` names referenced below are kept for historical context about the v1→v2 transition.
 
 ---
 
 ## 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)
@@ -30,25 +27,17 @@ This document describes all breaking changes introduced in version 2.0.0 of cov-
 
 ## 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.
+**Migration:** Move all global options before the subcommand name. These options are:
 
-**Before (v1.x):**
-```bash
-cov-loupe list --resultset coverage --format json
-cov-loupe summary lib/foo.rb --json
-```
+`-r`, `-R`, `-f`, `-o`, `-s`, `-c`, `-C`, `-S`, `-g`, `-l`, `-F`, and `-e`
 
-**After (v2.x):**
+**Exception:** The `validate` subcommand has its own subcommand-specific option `-i/--inline` that must appear *after* the subcommand:
 ```bash
-cov-loupe --resultset coverage --format json list
-cov-loupe --format json summary lib/foo.rb
+cov-loupe validate -i '->(m) { m.list.all? { |f| f["percentage"] >= 80 } }'
 ```
 
-**Migration:** Move all global options (flags like `-r`, `-f`, `-S`, etc.) before the subcommand name.
 
 ---
 
@@ -60,14 +49,14 @@ cov-loupe --format json summary lib/foo.rb
 
 **Before (v1.x):**
 ```bash
-cov-loupe --stale error list
+simplecov-mcp --stale error list
 ```
 
 **After (v2.x):**
 ```bash
-cov-loupe --staleness error list
+simplecov-mcp --staleness error list
 # OR use the short form:
-cov-loupe -S error list
+simplecov-mcp -S error list
 ```
 
 **Migration:** Replace `--stale` with `--staleness` (or continue using `-S`).
@@ -82,14 +71,14 @@ cov-loupe -S error list
 
 **Before (v1.x):**
 ```bash
-cov-loupe --source uncovered --source-context 3 uncovered lib/foo.rb
+simplecov-mcp --source uncovered --source-context 3 uncovered lib/foo.rb
 ```
 
 **After (v2.x):**
 ```bash
-cov-loupe --source uncovered --context-lines 3 uncovered lib/foo.rb
+simplecov-mcp --source uncovered --context-lines 3 uncovered lib/foo.rb
 # OR use the short form:
-cov-loupe -s uncovered -c 3 uncovered lib/foo.rb
+simplecov-mcp -s uncovered -c 3 uncovered lib/foo.rb
 ```
 
 **Migration:** Replace `--source-context` with `--context-lines` (or use `-c`).
@@ -105,15 +94,15 @@ cov-loupe -s uncovered -c 3 uncovered lib/foo.rb
 **Before (v1.x):**
 ```bash
 # Implied 'full' mode
-cov-loupe --source summary lib/foo.rb
+simplecov-mcp --source summary lib/foo.rb
 ```
 
 **After (v2.x):**
 ```bash
 # Must specify mode explicitly
-cov-loupe --source full summary lib/foo.rb
+simplecov-mcp --source full summary lib/foo.rb
 # OR
-cov-loupe --source uncovered summary lib/foo.rb
+simplecov-mcp --source uncovered summary lib/foo.rb
 ```
 
 **Migration:** Add an explicit mode (`full` or `uncovered`) after `--source`.
@@ -122,23 +111,23 @@ cov-loupe --source uncovered summary lib/foo.rb
 
 ### --json Replaced with --format
 
-**Change:** The `--json` flag (and related `-j`, `-J`, `--pretty-json` flags) have been removed. Use `--format` instead.
+**Change:** The `--json` flag (and related `-j`, `-J`, `--pretty-json` flags) have been removed. Use `-f/--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
+simplecov-mcp --json list
+simplecov-mcp -j summary lib/foo.rb
+simplecov-mcp --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
+simplecov-mcp --format json list
+simplecov-mcp -f j summary lib/foo.rb    # Short form
+simplecov-mcp --format pretty-json list
+simplecov-mcp -f J list                  # Short form for pretty-json
 ```
 
 **Available formats:**
@@ -146,7 +135,7 @@ cov-loupe -f J list                       # Short form for pretty-json
 - `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)
+- `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`).
 
@@ -164,17 +153,17 @@ The old values are **no longer supported**.
 
 **Before (v1.x):**
 ```bash
-cov-loupe --error-mode on list
-cov-loupe --error-mode trace list
+simplecov-mcp --error-mode on list
+simplecov-mcp --error-mode trace list
 ```
 
 **After (v2.x):**
 ```bash
-cov-loupe --error-mode log list
-cov-loupe --error-mode debug list
+simplecov-mcp --error-mode log list
+simplecov-mcp --error-mode debug list
 # OR use short forms:
-cov-loupe --error-mode l list
-cov-loupe --error-mode d list
+simplecov-mcp --error-mode l list
+simplecov-mcp --error-mode d list
 ```
 
 **Error modes:**
@@ -194,16 +183,16 @@ cov-loupe --error-mode d list
 
 **Before (v1.x):**
 ```bash
-cov-loupe --success-predicate policy.rb
+simplecov-mcp --success-predicate policy.rb
 ```
 
 **After (v2.x):**
 ```bash
 # File-based policy
-cov-loupe validate policy.rb
+simplecov-mcp validate policy.rb
 
 # Inline policy (new feature)
-cov-loupe validate -i '->(m) { m.all_files.all? { |f| f["percentage"] >= 80 } }'
+simplecov-mcp validate -i '->(m) { m.list.all? { |f| f["percentage"] >= 80 } }'
 ```
 
 **Migration:** Replace `--success-predicate FILE` with `validate FILE`.
@@ -214,22 +203,23 @@ cov-loupe validate -i '->(m) { m.all_files.all? { |f| f["percentage"] >= 80 } }'
 
 **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.
+**Rationale:** Most users want to see worst-covered files last so that when scrolling is finished
+the worst-covered files are displayed on the screen.
 
 **Before (v1.x):**
 ```bash
 # Shows worst coverage first by default
-cov-loupe list
+simplecov-mcp list
 ```
 
 **After (v2.x):**
 ```bash
 # Shows best coverage first by default
-cov-loupe list
+simplecov-mcp list
 
 # To get old behavior (worst first):
-cov-loupe --sort-order ascending list
-cov-loupe -o a list  # Short form
+simplecov-mcp --sort-order ascending list
+simplecov-mcp -o a list  # Short form
 ```
 
 **Migration:** If you relied on ascending order (worst coverage first), explicitly specify `--sort-order ascending` or `-o a`.
@@ -274,7 +264,7 @@ cov-loupe -o a list  # Short form
 }
 ```
 
-**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`).
+**Affected tools:** All file-based tools (`coverage_summary_tool`, `coverage_detailed_tool`, `coverage_raw_tool`, `uncovered_lines_tool`) and aggregate tools (`list_tool`, `coverage_totals_tool`).
 
 **Migration:** Replace `"stale"` with `"staleness"` in all MCP tool calls.
 
@@ -388,13 +378,13 @@ config = CovLoupe::AppConfig.new(
 **Before (v1.x):**
 ```bash
 # Silently clamped to 0
-cov-loupe --source-context -5 uncovered lib/foo.rb
+simplecov-mcp --source-context -5 uncovered lib/foo.rb
 ```
 
 **After (v2.x):**
 ```bash
 # Raises ArgumentError
-cov-loupe --context-lines -5 uncovered lib/foo.rb
+simplecov-mcp --context-lines -5 uncovered lib/foo.rb
 # Error: Context lines must be non-negative (got: -5)
 ```
 
@@ -426,26 +416,26 @@ cov-loupe --context-lines -5 uncovered lib/foo.rb
 **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
+simplecov-mcp list --json --stale error --sort-order ascending
+simplecov-mcp summary lib/foo.rb --json
+simplecov-mcp uncovered lib/bar.rb --source=uncovered --source-context 3
+simplecov-mcp --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
+simplecov-mcp --format json --staleness error --sort-order ascending list
+simplecov-mcp --format json summary lib/foo.rb
+simplecov-mcp --source uncovered --context-lines 3 uncovered lib/bar.rb
+simplecov-mcp validate policy.rb
 ```
 
 ### Environment Variable Migration
 
 **Before (v1.x):**
 ```bash
-export COV_LOUPE_OPTS="--stale error --json"
+export SIMPLECOV_MCP_OPTS="--stale error --json"
 ```
 
 **After (v2.x):**
@@ -459,14 +449,14 @@ export COV_LOUPE_OPTS="--staleness error --format json"
 
 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
+1. Check the [Troubleshooting](../TROUBLESHOOTING.md) guide
+2. Review the [CLI Usage](../CLI_USAGE.md) for complete CLI reference
+3. See [MCP Integration](../MCP_INTEGRATION.md) for MCP tool documentation
+4. Open an issue at https://github.com/keithrbennett/simplecov-mcp/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
+- [RELEASE_NOTES.md](../../release_notes.md) - Full release notes with new features
+- [CLI Usage](../CLI_USAGE.md) - Complete CLI reference
+- [MCP Integration](../MCP_INTEGRATION.md) - MCP tool reference

data/docs/user/migrations/MIGRATING_TO_V3.md

@@ -0,0 +1,72 @@
+# V3.0 Breaking Changes Guide
+
+[Back to main README](../../index.md)
+
+This document describes the breaking changes introduced in version 3.0.0, which primarily involve the renaming of the gem from `simplecov-mcp` to `cov-loupe`. These changes affect the gem name, executable, Ruby API, and configuration.
+
+---
+
+## What Changed
+
+The project has been completely renamed, impacting various aspects:
+
+### Gem & Executable
+*   **Gem name**: `simplecov-mcp` → `cov-loupe`
+*   **Executable**: `simplecov-mcp` → `cov-loupe`
+*   **Repository**: `github.com/keithrbennett/simplecov-mcp` → `github.com/keithrbennett/cov-loupe`
+
+### Ruby API
+*   **Module Name**: `SimpleCovMcp` → `CovLoupe`
+*   **Require Path**: `require 'simplecov_mcp'` → `require 'cov_loupe'`
+
+### Configuration
+*   **Environment variable**: `SIMPLECOV_MCP_OPTS` → `COV_LOUPE_OPTS`
+*   **Log file**: `simplecov_mcp.log` → `cov_loupe.log`
+*   **Documentation alias**: `smcp` → `clp`
+
+## What Stayed the Same
+
+*   **Core functionality**: No breaking changes to features, CLI command logic (other than the executable name), or the internal structure of the `CoverageModel` logic.
+*   **MCP Protocol**: The JSON-RPC tool definitions and behaviors remain consistent.
+
+## Migration Steps
+
+To upgrade from `simplecov-mcp` (v2.x) to `cov-loupe` (v3.x), follow these steps:
+
+1.  **Uninstall the old gem**:
+    ```bash
+    gem uninstall simplecov-mcp
+    ```
+
+2.  **Install the new gem**:
+    ```bash
+    gem install cov-loupe
+    ```
+
+3.  **Update scripts and aliases**:
+    *   Change all occurrences of the `simplecov-mcp` command to `cov-loupe` in your shell scripts, CI/CD configurations, and shell aliases.
+
+4.  **Update Ruby code**:
+    *   Find: `require 'simplecov_mcp'`
+    *   Replace with: `require 'cov_loupe'`
+    *   Find: `SimpleCovMcp`
+    *   Replace with: `CovLoupe`
+
+5.  **Update environment variables**:
+    *   Rename any `SIMPLECOV_MCP_OPTS` environment variables to `COV_LOUPE_OPTS`.
+
+6.  **Update log file references**:
+    *   If you rely on the default log file, it will now be named `cov_loupe.log`. Update any scripts or tools that reference `simplecov_mcp.log`.
+
+**Note**: The old `simplecov-mcp` gem (v2.0.1) will remain available on RubyGems but will not receive further updates.
+
+---
+
+## Getting Help
+
+If you encounter issues migrating to v3.0:
+
+1.  Check the [Troubleshooting](../TROUBLESHOOTING.md) guide.
+2.  Review the [CLI Usage](../CLI_USAGE.md) for complete CLI reference.
+3.  See [MCP Integration](../MCP_INTEGRATION.md) for MCP tool documentation.
+4.  Open an issue at https://github.com/keithrbennett/cov-loupe/issues.