cov-loupe 3.0.0 → 4.0.0.pre

data/examples/mcp-inputs/README.md

@@ -0,0 +1,66 @@
+## MCP JSON Inputs
+
+[Back to main README](../../docs/index.md)
+
+This directory contains example JSON-RPC requests that can be sent to the MCP server over stdio.
+
+Each file contains a single line of JSON (NDJSON-ready), so you can pipe it directly to the executable.
+
+**Target Project:** These inputs are designed to work with the demo project located at `docs/fixtures/demo_project`.
+
+### Running the Examples
+
+From the repository root:
+
+```sh
+exe/cov-loupe -m mcp < examples/mcp-inputs/coverage_summary.json
+exe/cov-loupe -m mcp < examples/mcp-inputs/uncovered_lines.json
+```
+
+If `cov-loupe` is installed globally and available on your `PATH`:
+
+```sh
+cov-loupe -m mcp < examples/mcp-inputs/coverage_summary.json
+```
+
+### Formatting Tips (jq and rexe)
+
+You can use tools like [jq](https://github.com/jqlang/jq) or [rexe](https://github.com/keithrbennett/rexe) to format the JSON input and output, which is especially helpful for debugging.
+
+**Pretty-print an input file:**
+
+Using `jq`:
+```sh
+jq . examples/mcp-inputs/coverage_summary.json
+```
+
+Using Ruby:
+```sh
+ruby -r json -e '
+  puts JSON.pretty_generate(JSON.parse(File.read("examples/mcp-inputs/coverage_summary.json")))
+'
+```
+
+Using `rexe`:
+```sh
+rexe -f examples/mcp-inputs/coverage_summary.json -oJ
+```
+
+**Pretty-print the MCP server's JSON response (NDJSON):**
+
+Using `jq`:
+```sh
+exe/cov-loupe -m mcp < examples/mcp-inputs/coverage_summary.json | jq .
+```
+
+Using Ruby:
+```sh
+exe/cov-loupe -m mcp < examples/mcp-inputs/coverage_summary.json | ruby -r json -e '
+  puts JSON.pretty_generate(JSON.parse($stdin.read))
+'
+```
+
+Using `rexe`:
+```sh
+exe/cov-loupe -m mcp < examples/mcp-inputs/coverage_summary.json | rexe -ml -ij -oJ
+```

data/examples/mcp-inputs/coverage_detailed.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"coverage_detailed_tool","arguments":{"path":"lib/foo.rb","root":"docs/fixtures/demo_project"}}}

data/examples/mcp-inputs/coverage_raw.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_raw_tool","arguments":{"path":"lib/foo.rb","root":"docs/fixtures/demo_project"}}}

data/examples/mcp-inputs/coverage_summary.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/foo.rb","root":"docs/fixtures/demo_project"}}}

data/examples/mcp-inputs/list.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"list_tool","arguments":{"root":"docs/fixtures/demo_project"}}}

data/examples/mcp-inputs/uncovered_lines.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"uncovered_lines_tool","arguments":{"path":"lib/foo.rb","root":"docs/fixtures/demo_project"}}}

data/examples/prompts/README.md

@@ -0,0 +1,27 @@
+## Example Prompts for MCP-Aware Assistants
+
+[Back to main README](../../docs/index.md)
+
+This directory contains example natural-language prompts that you can use with an MCP-enabled AI assistant to interact with the `cov-loupe` server and analyze your project's test coverage.
+
+These prompts demonstrate how to request different types of coverage information. You can adapt them to your specific project and needs.
+
+### Getting Started
+
+1.  **Copy a prompt:** Choose a prompt from one of the `.txt` files in this directory.
+2.  **Paste it into your assistant:** Paste the prompt into your chat with an MCP-enabled AI assistant.
+3.  **Adjust file paths:** If necessary, change the file paths in the prompt to match your project's structure.
+
+### Example Prompts
+
+*   **`summary.txt`**: A basic prompt to get a high-level summary of your project's test coverage.
+*   **`detailed_with_source.txt`**: A more advanced prompt that requests a detailed breakdown of coverage, including the source code of the files.
+*   **`list_lowest.txt`**: A prompt to find the files with the lowest test coverage.
+*   **`uncovered.txt`**: A prompt to get a list of all the lines that are not covered by tests.
+*   **`custom_resultset.txt`**: An example of how to specify a custom SimpleCov resultset file for analysis.
+
+### Tips for Writing Your Own Prompts
+
+*   **Be specific:** The more specific you are in your request, the better the assistant will be able to understand you.
+*   **Request JSON for machine-readable output:** If you want to process the output programmatically, ask for the results in JSON format.
+*   **Specify the root directory:** If your project is not in the current working directory, you can specify the root directory in your prompt.

data/examples/prompts/custom_resultset.txt

@@ -0,0 +1,2 @@
+Read coverage from build/coverage/.resultset.json for src/app.rb. Compare its coverage level to typical standards for application entry points. If coverage is incomplete, explain what failure modes or edge cases might be untested and why that matters for a main application file.
+

data/examples/prompts/detailed_with_source.txt

@@ -0,0 +1,2 @@
+Examine the detailed line-by-line coverage for lib/foo.rb. Identify patterns in what's tested vs untested (e.g., are error paths covered? edge cases? happy paths only?). Highlight any concerning gaps and suggest what test cases would address them.
+

data/examples/prompts/list_lowest.txt

@@ -0,0 +1,2 @@
+Identify the 5 files with the lowest test coverage. For each, analyze what type of code it contains (core logic, utilities, error handling, etc.) and assess the risk of inadequate testing. Recommend a priority order for adding tests based on both coverage percentage and code criticality.
+

data/examples/prompts/summary.txt

@@ -0,0 +1,2 @@
+Analyze the coverage for lib/foo.rb. If coverage is below 80%, identify the riskiest uncovered areas and suggest specific test scenarios that would improve quality. Prioritize by impact.
+

data/examples/prompts/uncovered.txt

@@ -0,0 +1,2 @@
+Find all uncovered lines in lib/foo.rb. Analyze which uncovered sections represent the highest risk (e.g., error handling, edge cases, complex logic). Recommend which lines should be tested first and why.
+

data/examples/success_predicates/README.md

@@ -0,0 +1,198 @@
+# Coverage Validation Predicate Examples
+
+[Back to main README](../../docs/index.md)
+
+This directory contains example coverage validation predicates for use with the `validate` subcommand.
+
+> **⚠️ SECURITY WARNING**
+>
+> Success predicates execute as **arbitrary Ruby code with full system privileges**. They have unrestricted access to:
+> - File system operations (read, write, delete)
+> - Network operations (HTTP requests, sockets)
+> - System commands (via backticks, `system()`, `exec()`, etc.)
+> - Environment variables and sensitive data
+>
+> **Only use predicate files from trusted sources.** Treat them like any other executable code in your project.
+> - Never use predicates from untrusted or unknown sources
+> - Review predicates before use, especially in CI/CD environments
+> - Store predicates in version control with code review
+> - Be cautious when copying examples from the internet
+
+## Usage
+
+**File mode:**
+```sh
+cov-loupe validate examples/success_predicates/<filename>.rb
+```
+
+**String mode:**
+```sh
+cov-loupe validate -i '->(model) { model.list["files"].all? { |f| f["percentage"] >= 80 } }'
+```
+
+The predicate receives a `CoverageModel` instance and returns:
+- **Truthy value** → Exit code 0 (success)
+- **Falsy value** → Exit code 1 (failure)
+- **Exception** → Exit code 2 (error)
+
+## Available Examples
+
+### `all_files_above_threshold_predicate.rb`
+All files must have >= 80% coverage.
+
+```sh
+cov-loupe validate examples/success_predicates/all_files_above_threshold_predicate.rb
+```
+
+### `project_coverage_minimum_predicate.rb`
+Total project coverage must be >= 85%.
+
+```sh
+cov-loupe validate examples/success_predicates/project_coverage_minimum_predicate.rb
+```
+
+### `directory_specific_thresholds_predicate.rb`
+Different thresholds for different directories:
+- `lib/api/` - 90% required
+- `lib/core/` - 85% required
+- `lib/legacy/` - 60% required
+
+```sh
+cov-loupe validate examples/success_predicates/directory_specific_thresholds_predicate.rb
+```
+
+## Creating Custom Predicates
+
+A predicate must be a callable object (lambda, proc, or class with `#call` method):
+
+**Lambda example:**
+```ruby
+->(model) do
+  model.list['files'].all? { |f| f['percentage'] >= 80 }
+end
+```
+
+**Class method example:**
+```ruby
+class MyPolicy
+  def self.call(model)
+    model.list['files'].all? { |f| f['percentage'] >= @threshold }
+  end
+end
+
+MyPolicy  # The class itself
+```
+
+**Instance method example:**
+```ruby
+class MyPolicy
+  def initialize(threshold = 80)
+    @threshold = threshold
+  end
+
+  def call(model)
+    model.list['files'].all? { |f| f['percentage'] >= @threshold }
+  end
+end
+
+MyPolicy
+
+```
+
+### CoverageModel API
+
+The `model` parameter provides:
+
+```ruby
+# Get all files
+files = model.list['files']
+# => [{ "file" => "...", "covered" => 12, "total" => 14, "percentage" => 85.71, "stale" => false }, ...]
+
+# Filter by globs
+api_files = model.list(tracked_globs: ['lib/api/**/*.rb'])['files']
+
+# Get specific file data
+summary = model.summary_for('lib/model.rb')
+uncovered = model.uncovered_for('lib/model.rb')
+```
+
+See [docs/user/LIBRARY_API.md](../../docs/user/LIBRARY_API.md) for the complete API.
+
+### When to Use Standalone Scripts Instead
+
+For more complex scenarios, you may prefer writing a standalone Ruby script that uses the `cov-loupe` library directly instead of using the `validate` subcommand.
+
+**Use a standalone script when:**
+- **External dependencies needed** - Your policy requires other gems or libraries
+- **Complex setup required** - You need custom logging, database connections, or API calls
+- **Easier testing desired** - Standalone scripts can be tested like any Ruby code
+- **More explicit control** - You want full control over model initialization and error handling
+- **Sophisticated logic** - Multi-step analysis, data aggregation, or integration with other tools
+
+**Predicate approach is better when:**
+- Policy is simple and self-contained (most common use case)
+- You want the tool to handle option parsing (--resultset, --raise-on-stale, etc.)
+- Consistent error handling and exit codes are desired
+- Less boilerplate is preferred
+
+**Example standalone script:**
+```ruby
+#!/usr/bin/env ruby
+require 'cov_loupe'
+require 'httparty'  # External gem
+
+# Custom initialization
+model = CovLoupe::CoverageModel.new(
+  resultset: ENV['COVERAGE_PATH'],
+  raise_on_stale: true
+)
+
+# Complex logic with external API
+files = model.list['files']
+low_coverage_files = files.select { |f| f['percentage'] < 80 }
+
+# Post to Slack
+if low_coverage_files.any?
+  HTTParty.post(
+    ENV['SLACK_WEBHOOK_URL'],
+    body: { text: "#{low_coverage_files.size} files below 80%" }.to_json
+  )
+  exit 1
+else
+  exit 0
+end
+```
+
+Both approaches execute arbitrary code with full system privileges, so the security considerations are identical. Choose the approach that best fits your use case.
+
+## CI/CD Integration
+
+**GitHub Actions:**
+```yaml
+- name: Enforce Coverage Policy
+  run: bundle exec cov-loupe validate coverage_policy.rb
+```
+
+**GitLab CI:**
+```yaml
+coverage:enforce:
+  script:
+    - bundle exec cov-loupe validate coverage_policy.rb
+```
+
+**Jenkins:**
+```groovy
+stage('Coverage Policy') {
+    steps {
+        sh 'bundle exec cov-loupe validate coverage_policy.rb'
+    }
+}
+```
+
+## Exit Codes
+
+- **0** - Predicate returned truthy (success)
+- **1** - Predicate returned falsy (failure)
+- **2** - Predicate raised an error
+
+Use exit code 1 to fail CI/CD builds when coverage doesn't meet policy.

data/examples/success_predicates/all_files_above_threshold_predicate.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Success predicate: All files must have >= 80% coverage, illustrates use of a class `call` method
+# Usage: cov-loupe --success-predicate examples/success_predicates/all_files_above_threshold_predicate.rb
+class AllFilesAboveThreshold
+  THRESHOLD = 95
+
+  def self.call(model)
+    low_files = model.list.select { |f| f['percentage'] < THRESHOLD }
+
+    if low_files.any?
+      # Can add custom logging/reporting here
+      warn "Files below #{THRESHOLD}%:"
+      low_files.each { |f| warn format('%5.1f%%  %s', f['percentage'], f['name']) }
+    end
+
+    low_files.none?
+  end
+end
+
+AllFilesAboveThreshold

data/examples/success_predicates/directory_specific_thresholds_predicate.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Success predicate: Different thresholds for different directories, using a `call` class method
+# Usage: cov-loupe --success-predicate examples/success_predicates/directory_specific_thresholds_predicate.rb
+
+class DirectorySpecificThresholds
+  def self.call(model)
+    new(model).call
+  end
+
+  def initialize(model)
+    @files = model.relativize(model.list)
+  end
+
+  def files_ok?(filemask, threshold_percentage)
+    files = @files.select { |f| File.fnmatch?(filemask, f['file']) }
+    files.all? { |f| f['percentage'] >= threshold_percentage }
+  end
+
+  def call
+    [
+      ['lib/cov_loupe/**/*.rb',                 85], # global default minimum
+      ['lib/cov_loupe/option_parsers/**/*.rb',  95],
+      ['lib/cov_loupe/tools/**/*.rb',          100]
+    ].map { |(filemask, threshold_pct)| files_ok?(filemask, threshold_pct) }
+      .all?
+  end
+end
+
+DirectorySpecificThresholds

data/examples/success_predicates/project_coverage_minimum_predicate.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Success predicate: Total project coverage >= 85%
+# Usage: cov-loupe --success-predicate examples/success_predicates/project_coverage_minimum_predicate.rb
+
+->(model) { model.project_totals['lines']['percent_covered'] >= 85.0 }