simplecov-mcp 1.0.0 → 2.0.0

data/docs/{ADVANCED_USAGE.md → user/ADVANCED_USAGE.md}

@@ -1,6 +1,10 @@
 # Advanced Usage Guide
 
-This guide covers advanced usage patterns, integration strategies, and optimization techniques for simplecov-mcp.
+[Back to main README](../README.md)
+
+> Examples use `smcp`, an alias pointed at the demo fixture with partial coverage:
+> `alias smcp='simplecov-mcp --root docs/fixtures/demo_project'`
+> Swap `smcp` with `simplecov-mcp` if you want to target your own project/resultset.
 
 ## Table of Contents
 
@@ -20,7 +24,7 @@ This guide covers advanced usage patterns, integration strategies, and optimizat
 
 ### MCP Error Handling
 
-The MCP server uses structured error responses. Understanding the error types helps with debugging:
+The MCP server uses structured error responses:
 
 ```json
 {
@@ -37,54 +41,11 @@ The MCP server uses structured error responses. Understanding the error types he
 }
 ```
 
-**Error Types:**
-- `FileError` - File not found in coverage or filesystem
-- `FileNotFoundError` - Source file missing from filesystem
-- `CoverageDataError` - Invalid or corrupt `.resultset.json`
-- `CoverageDataStaleError` - Coverage older than source (single file)
-- `CoverageDataProjectStaleError` - Project-wide staleness issues
-
 ### MCP Server Logging
 
-The MCP server logs to `simplecov_mcp.log` in the current directory by default. For custom log locations, configure via your MCP client:
-
-**Claude Code (`claude_desktop_config.json`):**
-```json
-{
-  "mcpServers": {
-    "simplecov-mcp": {
-      "command": "simplecov-mcp",
-      "args": ["--log-file", "/var/log/coverage/mcp.log"]
-    }
-  }
-}
-```
-
-**Or use environment variables:**
-```json
-{
-  "mcpServers": {
-    "simplecov-mcp": {
-      "command": "simplecov-mcp",
-      "env": {
-        "SIMPLECOV_MCP_OPTS": "--log-file /var/log/coverage/mcp.log"
-      }
-    }
-  }
-}
-```
+The MCP server logs to `simplecov_mcp.log` in the current directory by default.
 
-**To log to standard error:**
-```json
-{
-  "mcpServers": {
-    "simplecov-mcp": {
-      "command": "simplecov-mcp",
-      "args": ["--log-file", "stderr"]
-    }
-  }
-}
-```
+To override the default log file location, specify the `--log-file` argument wherever and however you configure your MCP server. For example, to log to a different file path, include `--log-file /path/to/logfile.log` in your server configuration. To log to standard error, use `--log-file stderr`.
 
 **Note:** Logging to `stdout` is not permitted in MCP mode.
 
@@ -94,16 +55,16 @@ Use JSON-RPC over stdin to test the MCP server:
 
 ```sh
 # Get version
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | simplecov-mcp
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"version_tool","arguments":{}}}' | smcp
 
 # Get file summary
-echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/simplecov_mcp/model.rb"}}}' | simplecov-mcp
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"app/models/order.rb"}}}' | smcp
 
 # List all files with sorting
-echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"all_files_coverage_tool","arguments":{"sort_order":"ascending"}}}' | simplecov-mcp
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"all_files_coverage_tool","arguments":{"sort_order":"ascending"}}}' | smcp
 
 # Get uncovered lines
-echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"uncovered_lines_tool","arguments":{"path":"lib/simplecov_mcp/cli.rb"}}}' | simplecov-mcp
+echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"uncovered_lines_tool","arguments":{"path":"app/controllers/orders_controller.rb"}}}' | smcp
 ```
 
 ---
@@ -133,11 +94,8 @@ A file is considered stale when any of the following are true:
 
 **CLI Usage:**
 ```sh
-# Fail if any file is stale
-simplecov-mcp --stale error summary lib/model.rb
-
-# Check specific file staleness
-simplecov-mcp summary lib/model.rb --stale error
+# Fail if any file is stale (option before subcommand)
+smcp --staleness error summary app/models/order.rb
 ```
 
 **Ruby API:**
@@ -147,7 +105,7 @@ model = SimpleCovMcp::CoverageModel.new(
 )
 
 begin
-  summary = model.summary_for('lib/model.rb')
+  summary = model.summary_for('app/models/order.rb')
 rescue SimpleCovMcp::CoverageDataStaleError => e
   puts "File modified after coverage: #{e.file_path}"
   puts "Coverage timestamp: #{e.cov_timestamp}"
@@ -168,19 +126,19 @@ Detects system-wide staleness issues:
 **CLI Usage:**
 ```sh
 # Track specific patterns
-simplecov-mcp --stale error \
-  --tracked-globs "lib/**/*.rb" \
-  --tracked-globs "app/**/*.rb"
+smcp --staleness error \
+  -g "lib/payments/**/*.rb" \
+  -g "lib/ops/jobs/**/*.rb"  # -g = --tracked-globs
 
 # Combine with JSON output for parsing
-simplecov-mcp list --stale error --json > stale-check.json
+smcp --staleness error -fJ list > stale-check.json
 ```
 
 **Ruby API:**
 ```ruby
 model = SimpleCovMcp::CoverageModel.new(
   staleness: 'error',
-  tracked_globs: ['lib/**/*.rb', 'app/**/*.rb']
+  tracked_globs: ['lib/payments/**/*.rb', 'lib/ops/jobs/**/*.rb']
 )
 
 begin
@@ -194,51 +152,37 @@ end
 
 ### Staleness in CI/CD
 
-**Example: GitHub Actions**
-```yaml
-- name: Validate Coverage Freshness
-  run: |
-    bundle exec rspec
-    simplecov-mcp --stale error --tracked-globs "lib/**/*.rb" || {
-      echo "Coverage is stale! Re-run tests."
-      exit 1
-    }
-```
+Staleness checking is particularly useful in CI/CD pipelines to ensure coverage data is fresh:
+
+```sh
+# Run tests to generate coverage
+bundle exec rspec
+
+# Validate coverage freshness (fails with exit code 1 if stale)
+smcp --staleness error -g "lib/**/*.rb"
 
-**Example: GitLab CI**
-```yaml
-coverage:validate:
-  script:
-    - bundle exec rspec
-    - simplecov-mcp list --stale error --json > coverage.json
-  artifacts:
-    reports:
-      coverage_report:
-        coverage_format: cobertura
-        path: coverage.json
+# Export validated data for CI artifacts
+smcp -fJ list > coverage.json
 ```
 
+The `--staleness error` flag causes the command to exit with a non-zero status when coverage is outdated, making it suitable for pipeline failure conditions.
+
 ---
 
 ## Advanced Path Resolution
 
 ### Multi-Strategy Path Matching
 
-SimpleCov-mcp uses a sophisticated path resolution strategy:
+Path resolution order:
 
 1. **Exact absolute path match**
 2. **Relative path resolution from root**
-3. **Basename (filename) fallback**
-
-This allows flexible path specifications:
 
 ```ruby
 model = SimpleCovMcp::CoverageModel.new(root: '/project')
 
-# All these work:
-model.summary_for('/project/lib/model.rb')           # Absolute
-model.summary_for('lib/model.rb')                    # Relative
-model.summary_for('model.rb')                        # Basename only
+model.summary_for('/project/app/models/order.rb')  # Absolute
+model.summary_for('app/models/order.rb')           # Relative
 ```
 
 ### Working with Multiple Projects
@@ -270,35 +214,24 @@ coverage_b = model_b.all_files
 
 ### Context-Aware Error Handling
 
-SimpleCov-mcp uses different error handling strategies based on context:
-
-**CLI Mode:**
-- User-friendly messages
-- Exit codes (0 = success, 1 = error)
-- Optional debug mode
+**CLI Mode:** user-facing messages, exit codes, optional debug mode
 
-**Library Mode:**
-- Raises typed exceptions
-- Programmatic error handling
-- Full exception details
+**Library Mode:** typed exceptions with full details
 
-**MCP Server Mode:**
-- JSON-RPC error responses
-- Logging to file
-- Structured error data
+**MCP Server Mode:** JSON-RPC errors logged to file with structured data
 
 ### Error Modes
 
 **CLI Error Modes:**
 ```sh
 # Silent mode - minimal output
-simplecov-mcp --error-mode off summary lib/model.rb
+smcp --error-mode off summary app/models/order.rb
 
 # Standard mode - user-friendly errors (default)
-simplecov-mcp --error-mode on summary lib/model.rb
+smcp --error-mode log summary app/models/order.rb
 
 # Verbose mode - full stack traces
-simplecov-mcp --error-mode trace summary lib/model.rb
+smcp --error-mode debug summary app/models/order.rb
 ```
 
 **Ruby API Error Handling:**
@@ -321,7 +254,7 @@ end
 
 ### Custom Error Handlers
 
-For library integration, provide custom error handlers:
+Provide custom error handlers when embedding the CLI:
 
 ```ruby
 class CustomErrorHandler
@@ -334,9 +267,7 @@ class CustomErrorHandler
   end
 end
 
-cli = SimpleCovMcp::CoverageCLI.new(
-  error_handler: CustomErrorHandler.new
-)
+cli = SimpleCovMcp::CoverageCLI.new(error_handler: CustomErrorHandler.new)
 ```
 
 ---
@@ -345,7 +276,7 @@ cli = SimpleCovMcp::CoverageCLI.new(
 
 ### Building Custom Coverage Policies
 
-Use `--success-predicate` to enforce custom coverage policies in CI/CD. Example predicates are in [`examples/success_predicates/`](../../examples/success_predicates/).
+Use the `validate` subcommand to enforce custom coverage policies in CI/CD. Example predicates are in [`examples/success_predicates/`](../../examples/success_predicates/).
 
 > **⚠️ SECURITY WARNING**
 >
@@ -364,13 +295,16 @@ Use `--success-predicate` to enforce custom coverage policies in CI/CD. Example
 **Quick Usage:**
 ```sh
 # All files must be >= 80%
-simplecov-mcp --success-predicate examples/success_predicates/all_files_above_threshold.rb
+smcp validate examples/success_predicates/all_files_above_threshold_predicate.rb
 
 # Total project coverage >= 85%
-simplecov-mcp --success-predicate examples/success_predicates/project_coverage_minimum.rb
+smcp validate examples/success_predicates/project_coverage_minimum_predicate.rb
+
+# Custom predicate from file
+smcp validate coverage_policy.rb
 
-# Custom predicate
-simplecov-mcp --success-predicate coverage_policy.rb
+# Inline string mode
+smcp validate -i '->(m) { m.all_files.all? { |f| f["percentage"] >= 80 } }'
 ```
 
 **Creating a predicate:**
@@ -383,6 +317,7 @@ end
 ```
 
 **Advanced predicate with reporting:**
+
 ```ruby
 # coverage_policy.rb
 class CoveragePolicy
@@ -419,216 +354,64 @@ Convert absolute paths to relative for cleaner output:
 model = SimpleCovMcp::CoverageModel.new(root: '/project')
 
 # Get data with absolute paths
-data = model.summary_for('lib/model.rb')
-# => { 'file' => '/project/lib/model.rb', ... }
+data = model.summary_for('app/models/order.rb')
+# => { 'file' => '/project/app/models/order.rb', ... }
 
 # Relativize paths
 relative_data = model.relativize(data)
-# => { 'file' => 'lib/model.rb', ... }
+# => { 'file' => 'app/models/order.rb', ... }
 
 # Works with arrays too
 files = model.all_files
 relative_files = model.relativize(files)
 ```
 
-### Batch Operations
-
-```ruby
-# Process multiple files efficiently
-files_to_check = ['lib/model.rb', 'lib/controller.rb', 'lib/view.rb']
-
-model = SimpleCovMcp::CoverageModel.new
-
-results = files_to_check.map do |file|
-  begin
-    {
-      file: file,
-      summary: model.summary_for(file),
-      uncovered: model.uncovered_for(file)
-    }
-  rescue SimpleCovMcp::FileError => e
-    { file: file, error: e.message }
-  end
-end
-```
-
 ---
 
-## CI/CD Integration Patterns
-
-### GitHub Actions
-
-**Complete Workflow:**
-```yaml
-name: Coverage Analysis
-
-on: [push, pull_request]
-
-jobs:
-  coverage:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.2
-          bundler-cache: true
-
-      - name: Run tests with coverage
-        run: bundle exec rspec
-
-      - name: Install simplecov-mcp
-        run: gem install simplecov-mcp
-
-      - name: Validate coverage freshness
-        run: |
-          simplecov-mcp --stale error \
-            --tracked-globs "lib/**/*.rb" \
-            --tracked-globs "app/**/*.rb"
-
-      - name: Check minimum coverage
-        run: |
-          # Export coverage data
-          simplecov-mcp list --json > coverage.json
-
-          # Use jq to check minimum threshold
-          MIN_COVERAGE=$(jq '[.files[].percentage] | add / length' coverage.json)
-          if (( $(echo "$MIN_COVERAGE < 80" | bc -l) )); then
-            echo "Coverage below 80%: $MIN_COVERAGE%"
-            exit 1
-          fi
-
-      - name: Upload coverage report
-        uses: actions/upload-artifact@v3
-        with:
-          name: coverage-report
-          path: coverage.json
-
-      - name: Comment PR with coverage
-        if: github.event_name == 'pull_request'
-        run: |
-          COVERAGE=$(simplecov-mcp list)
-          gh pr comment ${{ github.event.pull_request.number }} \
-            --body "## Coverage Report\n\`\`\`\n$COVERAGE\n\`\`\`"
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-
-### GitLab CI
-
-```yaml
-coverage:
-  stage: test
-  script:
-    - bundle exec rspec
-    - gem install simplecov-mcp
-    - simplecov-mcp --stale error
-  artifacts:
-    reports:
-      coverage_report:
-        coverage_format: cobertura
-        path: coverage/coverage.xml
-    paths:
-      - coverage/
-  coverage: '/TOTAL.*\s(\d+\.\d+)%/'
-```
-
-### Jenkins Pipeline
-
-```groovy
-pipeline {
-    agent any
-
-    stages {
-        stage('Test') {
-            steps {
-                sh 'bundle exec rspec'
-            }
-        }
-
-        stage('Coverage Analysis') {
-            steps {
-                sh 'gem install simplecov-mcp'
-                sh '''
-                    simplecov-mcp list --json > coverage.json
-                    simplecov-mcp --stale error || exit 1
-                '''
-            }
-        }
-
-        stage('Coverage Report') {
-            steps {
-                publishHTML([
-                    reportDir: 'coverage',
-                    reportFiles: 'index.html',
-                    reportName: 'Coverage Report'
-                ])
-            }
-        }
-    }
-}
-```
+## CI/CD Integration
 
-### Pre-commit Hooks
+The CLI is designed for CI/CD use with features that integrate naturally into pipeline workflows:
 
-```sh
-#!/bin/bash
-# .git/hooks/pre-commit
+### Key Integration Features
 
-# Run tests
-bundle exec rspec || exit 1
+- **Exit codes**: Non-zero on failure, making it suitable for pipeline failure conditions
+- **JSON output**: `-fJ` format for parsing by CI tools and custom processing
+- **Staleness checking**: `--stale error` to fail on outdated coverage data
+- **Success predicates**: Custom Ruby policies for coverage enforcement
 
-# Validate coverage
-simplecov-mcp --stale error --tracked-globs "lib/**/*.rb" || {
-    echo "Coverage validation failed!"
-    echo "Re-run tests or review coverage changes."
-    exit 1
-}
+### Basic CI Pattern
+
+```bash
+# 1. Run tests to generate coverage
+bundle exec rspec
 
-# Check for files with low coverage
-LOW_COVERAGE=$(simplecov-mcp list --json | \
-    jq -r '.files[] | select(.percentage < 80) | .file' | \
-    head -5)
+# 2. Validate coverage freshness (fails with exit code 1 if stale)
+smcp --staleness error -g "lib/**/*.rb"
 
-if [ -n "$LOW_COVERAGE" ]; then
-    echo "Warning: Files with coverage below 80%:"
-    echo "$LOW_COVERAGE"
-fi
+# 3. Export data for CI artifacts or further processing
+smcp -fJ list > coverage.json
 ```
 
-### Using Success Predicates in CI/CD
+### Using Coverage Validation
 
-Use `--success-predicate` to enforce coverage policies:
+Enforce custom coverage policies with the `validate` subcommand:
 
-**GitHub Actions:**
-```yaml
-- name: Enforce Coverage Policy
-  run: |
-    bundle exec rspec
-    bundle exec simplecov-mcp --success-predicate coverage_policy.rb
-```
+```bash
+# Run tests
+bundle exec rspec
 
-**GitLab CI:**
-```yaml
-coverage:enforce:
-  script:
-    - bundle exec rspec
-    - bundle exec simplecov-mcp --success-predicate coverage_policy.rb
+# Apply coverage policy (fails with exit code 1 if predicate returns false)
+smcp validate coverage_policy.rb
 ```
 
-**Jenkins:**
-```groovy
-stage('Coverage Policy') {
-    steps {
-        sh 'bundle exec rspec'
-        sh 'bundle exec simplecov-mcp --success-predicate coverage_policy.rb'
-    }
-}
-```
+Exit codes:
+- `0` - Success (coverage meets requirements)
+- `1` - Failure (coverage policy not met or stale data detected)
+- `2` - Error (invalid predicate or system error)
+
+### Platform-Specific Examples
 
-The build will fail (exit code 1) if the predicate returns falsy.
+For platform-specific integration examples (GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.), see community contributions in the [GitHub Discussions](https://github.com/simplecov-ruby/simplecov-mcp/discussions).
 
 ---
 
@@ -649,10 +432,20 @@ Uses Ruby's `File.fnmatch` with extended glob support:
 --tracked-globs "lib/**/*.rb"
 
 # Multiple patterns
---tracked-globs "lib/**/*.rb" --tracked-globs "app/**/*.rb"
+--tracked-globs "lib/payments/**/*.rb" --tracked-globs "lib/ops/jobs/**/*.rb"
 
 # Exclude patterns (use CLI filtering)
-simplecov-mcp list --json | jq '.files[] | select(.file | test("spec") | not)'
+smcp -fJ list | jq '.files[] | select(.file | test("spec") | not)'
+
+# Ruby alternative:
+smcp -fJ list | ruby -r json -e '
+  JSON.parse($stdin.read)["files"].reject { |f| f["file"].include?("spec") }.each do |f|
+    puts JSON.pretty_generate(f)
+  end
+'
+
+# Rexe alternative:
+smcp -fJ list | rexe -ij -mb -oJ 'self["files"].reject { |f| f["file"].include?("spec") }'
 
 # Complex patterns
 --tracked-globs "lib/{models,controllers}/**/*.rb"
@@ -664,26 +457,23 @@ simplecov-mcp list --json | jq '.files[] | select(.file | test("spec") | not)'
 **1. Monitor Subsystem Coverage:**
 ```sh
 # API layer only
-simplecov-mcp list --tracked-globs "lib/api/**/*.rb"
+smcp -g "lib/api/**/*.rb" list
 
 # Core business logic
-simplecov-mcp list --tracked-globs "lib/domain/**/*.rb"
+smcp -g "lib/domain/**/*.rb" list
 ```
 
 **2. Ensure New Files Have Coverage:**
 ```sh
 # Fail if any tracked file lacks coverage
-simplecov-mcp --stale error \
-  --tracked-globs "lib/features/**/*.rb"
+smcp --staleness error -g "lib/features/**/*.rb"
 ```
 
 **3. Multi-tier Reporting:**
 ```sh
 # Generate separate reports per layer
 for layer in models views controllers; do
-  simplecov-mcp list \
-    --tracked-globs "app/${layer}/**/*.rb" \
-    --json > "coverage-${layer}.json"
+  smcp -g "app/${layer}/**/*.rb" -fJ list > "coverage-${layer}.json"
 done
 ```
 
@@ -868,12 +658,12 @@ The CLI supports annotated source viewing:
 
 ```sh
 # Show uncovered lines with context
-simplecov-mcp uncovered lib/model.rb \
+smcp uncovered app/models/order.rb \
   --source uncovered \
   --source-context 3
 
 # Show full file with coverage annotations
-simplecov-mcp uncovered lib/model.rb \
+smcp uncovered app/models/order.rb \
   --source full \
   --source-context 0
 ```
@@ -903,7 +693,7 @@ def annotate_source(file_path)
   output.join
 end
 
-puts annotate_source('lib/model.rb')
+puts annotate_source('app/models/order.rb')
 ```
 
 ### Integration with Coverage Trackers
@@ -912,7 +702,7 @@ puts annotate_source('lib/model.rb')
 ```sh
 #!/bin/bash
 bundle exec rspec
-simplecov-mcp list --json > coverage.json
+smcp -fJ list > coverage.json
 
 # Transform to Codecov format (example)
 jq '{
@@ -925,6 +715,30 @@ jq '{
 }' coverage.json | curl -X POST \
   -H "Authorization: token $CODECOV_TOKEN" \
   -d @- https://codecov.io/upload
+
+# Ruby alternative:
+ruby -r json -e '
+  data = JSON.parse(File.read("coverage.json"))
+  transformed = {
+    coverage: data["files"].map { |f|
+      {name: f["file"], coverage: f["percentage"]}
+    }
+  }
+  puts JSON.pretty_generate(transformed)
+' | curl -X POST \
+  -H "Authorization: token $CODECOV_TOKEN" \
+  -d @- https://codecov.io/upload
+
+# Rexe alternative:
+rexe -f coverage.json -oJ '
+  {
+    coverage: self["files"].map { |f|
+      {name: f["file"], coverage: f["percentage"]}
+    }
+  }
+' | curl -X POST \
+  -H "Authorization: token $CODECOV_TOKEN" \
+  -d @- https://codecov.io/upload
 ```
 
 **Send to Coveralls:**
@@ -961,7 +775,3 @@ Net::HTTP.post(uri, coveralls_data.to_json, {
 - [MCP Integration Guide](MCP_INTEGRATION.md)
 - [Error Handling Details](ERROR_HANDLING.md)
 - [Troubleshooting](TROUBLESHOOTING.md)
-
----
-
-**Made with ❤️ for sophisticated Ruby test coverage analysis**