cov-loupe 3.0.0 → 4.0.0.pre

data/docs/user/ERROR_HANDLING.md

@@ -1,6 +1,6 @@
 # Error Handling Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 Error handling differs by usage mode:
 
@@ -72,9 +72,9 @@ end
 
 ## Stale Coverage Errors
 
-When strict staleness checking is enabled (`--staleness error`), the model (and CLI) raise a `CoverageDataStaleError` if a source file appears newer than the coverage data or the line counts differ.
+When strict staleness checking is enabled (`--raise-on-stale`), the model (and CLI) raise a `CoverageDataStaleError` if a source file appears newer than the coverage data or the line counts differ.
 
-- Enable per instance: `CovLoupe::CoverageModel.new(staleness: 'error')`
+- Enable per instance: `CovLoupe::CoverageModel.new(raise_on_stale: true)`
 
 The error message is detailed and includes:
 
@@ -89,5 +89,5 @@ Coverage data stale: Coverage data appears stale for lib/foo.rb
 File      - time: 2025-09-16T14:03:22Z (local 2025-09-16T07:03:22-07:00), lines: 226
 Coverage  - time: 2025-09-15T21:11:09Z (local 2025-09-15T14:11:09-07:00), lines: 220
 Delta     - file is +123s newer than coverage
-Resultset - /path/to/your/project/coverage/.resultset.json
+Resultset - /path/to/project/coverage/.resultset.json
 ```

data/docs/user/EXAMPLES.md

@@ -1,12 +1,15 @@
 # Examples and Recipes
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 Practical examples for common tasks with cov-loupe. Examples are organized by skill level and use case.
 
 > For brevity, these examples use `clp`, an alias to the demo fixture with partial coverage:
-> `alias clp='cov-loupe --root docs/fixtures/demo_project'`
+>
+> `alias clp='cov-loupe -R docs/fixtures/demo_project'  # -R = --root`
+>
 > Swap `clp` for `cov-loupe` to run against your own project and resultset.
+> The demo fixture is a small Rails-like project in `docs/fixtures/demo_project` with intentional coverage gaps for testing `--tracked-globs`.
 
 ## Table of Contents
 
@@ -22,11 +25,11 @@ Practical examples for common tasks with cov-loupe. Examples are organized by sk
 ### View All Coverage
 
 ```bash
-# Default: show all files, worst coverage first
+# Default: show all files, best coverage first
 clp
 
-# Show files with best coverage first
-clp -o d list  # -o = --sort-order, d = descending
+# Show files with worst coverage first
+clp -o a list  # -o = --sort-order, a = ascending
 
 # Export to JSON for processing
 clp -fJ list > coverage-report.json
@@ -48,21 +51,21 @@ clp -s u -c 3 uncovered app/controllers/orders_controller.rb  # -s = --source (u
 ### Find Coverage Gaps
 
 ```bash
-# Files with worst coverage
-clp list | head -10
+# Files with worst coverage (account for header/footer)
+clp list | tail -12
 
 # Only show files below 80%
-clp -fJ list | jq '.files[] | select(.percentage < 95)'
+clp -fJ list | jq '.files[] | select(.percentage < 80)'
 
 # Ruby alternative:
 clp -fJ list | ruby -r json -e '
-  JSON.parse($stdin.read)["files"].select { |f| f["percentage"] < 95 }.each do |f|
+  JSON.parse($stdin.read)["files"].select { |f| f["percentage"] < 80 }.each do |f|
     puts JSON.pretty_generate(f)
   end
 '
 
 # Rexe alternative:
-clp -fJ list | rexe -ij -mb -oJ 'self["files"].select { |f| f["percentage"] < 95 }'
+clp -fJ list | rexe -ij -mb -oJ 'self["files"].select { |f| f["percentage"] < 80 }'
 
 # Check specific directory
 clp -g "lib/payments/**/*.rb" list  # -g = --tracked-globs
@@ -92,18 +95,18 @@ Here are some examples:
 **Parse and filter:**
 ```bash
 # Files below threshold
-clp -fJ list | jq '.files[] | select(.percentage < 95) | {file, coverage: .percentage}'
+clp -fJ list | jq '.files[] | select(.percentage < 80) | {file, coverage: .percentage}'
 
 # Ruby alternative:
 clp -fJ list | ruby -r json -e '
-  JSON.parse($stdin.read)["files"].select { |f| f["percentage"] < 95 }.each do |f|
+  JSON.parse($stdin.read)["files"].select { |f| f["percentage"] < 80 }.each do |f|
     puts JSON.pretty_generate({file: f["file"], coverage: f["percentage"]})
   end
 '
 
 # Rexe alternative:
 clp -fJ list | rexe -ij -mb -oJ '
-  self["files"].select { |f| f["percentage"] < 95 }.map do |f|
+  self["files"].select { |f| f["percentage"] < 80 }.map do |f|
     {file: f["file"], coverage: f["percentage"]}
   end
 '
@@ -199,7 +202,7 @@ model = CovLoupe::CoverageModel.new(root: root)
 # Project totals
 totals = model.project_totals
 puts "Total files: #{totals['files']['total']}"
-puts "Average coverage: #{totals['percentage']}%"
+puts "Average coverage: #{totals['lines']['percent_covered']}%"
 
 # Check specific file
 summary = model.summary_for("app/models/order.rb")
@@ -217,11 +220,11 @@ require "cov_loupe"
 
 root = "docs/fixtures/demo_project"
 model = CovLoupe::CoverageModel.new(root: root)
-all_files = model.all_files
+list = model.list['files']
 
 # Find files below threshold
 THRESHOLD = 80.0
-low_coverage = all_files.select { |f| f['percentage'] < THRESHOLD }
+low_coverage = list.select { |f| f['percentage'] < THRESHOLD }
 
 if low_coverage.any?
   puts "Files below #{THRESHOLD}%:"
@@ -235,7 +238,7 @@ dirs = %w[app lib lib/payments lib/ops/jobs].uniq
 dirs.each do |dir|
   pattern = File.join(dir, '**/*.rb')
   totals = model.project_totals(tracked_globs: pattern)
-  puts "#{dir}: #{totals['percentage'].round(2)}% (#{totals['files']['total']} files)"
+  puts "#{dir}: #{totals['lines']['percent_covered'].round(2)}% (#{totals['files']['total']} files)"
 end
 ```
 
@@ -247,11 +250,11 @@ require "pathname"
 
 root = "docs/fixtures/demo_project"
 model = CovLoupe::CoverageModel.new(root: root)
-all_files = model.all_files
+list = model.list['files']
 
 # Filter to lib/payments (coverage data stores absolute paths)
 lib_root = File.expand_path("lib/payments", File.expand_path(root, Dir.pwd))
-lib_files = all_files.select { |f| f['file'].start_with?(lib_root) }
+lib_files = list.select { |f| f['file'].start_with?(lib_root) }
 
 # Generate custom table
 table = model.format_table(lib_files, sort_order: :ascending)
@@ -269,65 +272,48 @@ end
 
 ### Coverage Analysis
 
-```
-Using cov-loupe, show me a table of all files sorted by coverage percentage.
-```
+"Using cov-loupe, show me a table of all files sorted by coverage percentage."
 
-```
-Using cov-loupe, find the 10 files with the lowest coverage and create a markdown report with:
+"Using cov-loupe, find the 10 files with the lowest coverage and create a markdown report with:
 1. File path
 2. Current coverage %
-3. Number of uncovered lines
-```
+3. Number of uncovered lines"
 
-```
-Using cov-loupe, analyze the lib/payments/ directory and identify which files should be prioritized for additional testing based on coverage gaps and file complexity.
-```
+"Using cov-loupe, analyze the lib/payments/ directory and identify which files should be prioritized for additional testing based on coverage gaps and file complexity."
 
 ### Finding Specific Issues
 
-```
-Using cov-loupe, show me the uncovered lines in app/controllers/orders_controller.rb with 5 lines of context around each uncovered block.
-```
+"Using cov-loupe, show me the uncovered lines in app/controllers/orders_controller.rb with 5 lines of context around each uncovered block."
 
-```
-Using cov-loupe, find all files in lib/payments/ with less than 80% coverage and list the specific uncovered line numbers for each.
-```
+"Using cov-loupe, find all files in lib/payments/ with less than 80% coverage and list the specific uncovered line numbers for each."
 
 ### Test Generation
 
-```
-Using cov-loupe, identify the uncovered lines in lib/ops/jobs/report_job.rb and write RSpec tests to cover them.
-```
+"Using cov-loupe, identify the uncovered lines in lib/ops/jobs/report_job.rb and write *meaningful* RSpec tests to cover them."
 
-```
-Using cov-loupe, analyze coverage gaps in the app/controllers/ directory and generate a test plan prioritizing:
+"Using cov-loupe, analyze coverage gaps in the app/controllers/ directory and generate a test plan prioritizing:
 1. Public API methods
 2. Error handling paths
-3. Edge cases
-```
+3. Edge cases"
 
 ### Reporting
 
-```
-Using cov-loupe, create a coverage report showing:
+"Using cov-loupe, create a coverage report showing:
 - Overall project coverage percentage
 - Top 5 files with worst coverage
 - Recommended next steps to improve coverage
 
-Format as markdown.
-```
+Format as markdown."
 
 ## Test Run Integration
 
-### Display Low Coverage Files After RSpec
+### Display Low Coverage Files
 
 Add this to your `spec/spec_helper.rb` to automatically report files below a coverage threshold after each test run:
 
 ```ruby
 require 'simplecov'
 SimpleCov.start do
-  enable_coverage :branch
   add_filter %r{^/spec/}
   track_files 'lib/**/*.rb'  # Ensures new/untested files show up with 0%
 end
@@ -355,29 +341,72 @@ Lowest coverage files (< 80%):
 **Parameters:**
 - `threshold:` - Coverage percentage below which files are included (default: 80)
 - `count:` - Maximum number of files to show (default: 5)
+- `root:` - Project root directory (defaults to `SimpleCov.root` when SimpleCov is loaded, otherwise `'.'`)
+- `resultset:` - Path or directory to `.resultset.json` (defaults to `SimpleCov.coverage_dir/.resultset.json` when SimpleCov is loaded)
+- `model:` - Pre-configured `CoverageModel` instance (optional, overrides `root:`/`resultset:`)
 
 **Returns:** Formatted string, or `nil` if no files are below the threshold.
 
+**SimpleCov Integration:** When SimpleCov is loaded, `CoverageReporter.report` automatically uses SimpleCov's configured root and coverage directory. You can override these by passing explicit `root:` or `resultset:` parameters, or provide a custom `model:` instance.
+
+### Custom Coverage Directory
+
+If your project uses a custom coverage directory:
+
+```ruby
+require 'simplecov'
+SimpleCov.start do
+  add_filter %r{^/spec/}
+  coverage_dir 'reports/coverage'  # Custom coverage directory
+  track_files 'lib/**/*.rb'
+end
+
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  require 'cov_loupe'
+  
+  # CoverageReporter will automatically find the coverage in reports/coverage
+  report = CovLoupe::CoverageReporter.report(threshold: 80, count: 5)
+  puts report if report
+end
+```
+
+Or specify the resultset path explicitly:
+
+```ruby
+report = CovLoupe::CoverageReporter.report(
+  threshold: 80,
+  count: 5,
+  resultset: 'reports/coverage/.resultset.json'
+)
+```
+
 ## CI/CD Integration
 
 ### GitHub Actions
 
-**Fail on low coverage:**
+**Fail on low coverage (Cross-Platform):**
 ```yaml
 name: Coverage Check
 
 on: [push, pull_request]
 
 jobs:
-  coverage:
-    runs-on: ubuntu-latest
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        ruby-version: ['3.4']
+
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 3.3
+          ruby-version: ${{ matrix.ruby-version }}
           bundler-cache: true
 
       - name: Run tests
@@ -387,63 +416,55 @@ jobs:
         run: gem install cov-loupe
 
       - name: Check coverage threshold
+        shell: bash
         run: |
-          clp -fJ list > coverage.json
-          BELOW_THRESHOLD=$(jq '[.files[] | select(.percentage < 80)] | length' coverage.json)
-
-          # Ruby alternative:
-          # BELOW_THRESHOLD=$(ruby -r json -e '
-          #   puts JSON.parse(File.read("coverage.json"))["files"].count { |f| f["percentage"] < 80 }
-          # ')
-
-          # Rexe alternative:
-          # BELOW_THRESHOLD=$(rexe -f coverage.json -op 'self["files"].count { |f| f["percentage"] < 80 }')
-
-          if [ "$BELOW_THRESHOLD" -gt 0 ]; then
-            echo "❌ $BELOW_THRESHOLD files below 80% coverage"
-            jq -r '.files[] | select(.percentage < 80) | "\(.file): \(.percentage)%"' coverage.json
-
-            # Ruby alternative:
-            # ruby -r json -e '
-            #   JSON.parse(File.read("coverage.json"))["files"].select { |f| f["percentage"] < 80 }.each do |f|
-            #     puts "#{f["file"]}: #{f["percentage"]}%"
-            #   end
-            # '
-
-            # Rexe alternative:
-            # rexe -f coverage.json '
-            #   self["files"].select { |f| f["percentage"] < 80 }.each do |f|
-            #     puts "#{f["file"]}: #{f["percentage"]}%"
-            #   end
-            # '
-
-            exit 1
-          fi
-          echo "✓ All files meet coverage threshold"
+          # Generate JSON report using the full command (aliases like 'clp' are not available here)
+          cov-loupe -fJ list > coverage.json
+
+          # Verify coverage using Ruby for cross-platform compatibility
+          # (Tools like jq and rexe are not guaranteed to be installed on all runners)
+          ruby -r json -e '
+            data = JSON.parse(File.read("coverage.json"))
+            files = data["files"]
+            low_cov_files = files.select { |f| f["percentage"] < 80 }
+
+            if low_cov_files.any?
+              puts "❌ #{low_cov_files.count} files below 80% coverage:"
+              low_cov_files.each do |f|
+                puts "  #{f["percentage"]}% #{f["file"]}"
+              end
+              exit 1
+            end
+            puts "✓ All files meet coverage threshold"
+          '
 
       - name: Upload coverage report
-        uses: actions/upload-artifact@v3
+        # Saves the coverage file as an artifact so you can download/inspect it 
+        # from the GitHub Actions run summary page.
+        uses: actions/upload-artifact@v4
+        if: always()
         with:
-          name: coverage-report
+          name: coverage-report-${{ matrix.os }}
           path: coverage.json
 ```
 
 **Check for stale coverage:**
 ```yaml
       - name: Verify coverage is fresh
-        run: cov-loupe --staleness error || exit 1
+        shell: bash
+        run: cov-loupe --raise-on-stale true list || exit 1
 ```
 
 ### GitLab CI
 
 ```yaml
 test:
-  image: ruby:3.3
+  image: ruby:3.4
   before_script:
     - gem install cov-loupe
   script:
     - bundle exec rspec
-    - cov-loupe --staleness error
+    - cov-loupe --raise-on-stale true list
   artifacts:
     paths:
       - coverage/
@@ -458,18 +479,18 @@ test:
 ```ruby
 # coverage_policy.rb
 ->(model) do
-  all_files = model.all_files
+  list = model.list['files']
 
   # Must have at least 80% average coverage
   totals = model.project_totals
-  return false if totals['percentage'] < 80.0
+  return false if totals['lines']['percent_covered'] < 80.0
 
   # No files below 60%
-  return false if all_files.any? { |f| f['percentage'] < 60.0 }
+  return false if list.any? { |f| f['percentage'] < 60.0 }
 
   # lib/ files must average 90%
   lib_totals = model.project_totals(tracked_globs: ['lib/**/*.rb'])
-  return false if lib_totals['percentage'] < 90.0
+  return false if lib_totals['lines']['percent_covered'] < 90.0
 
   true
 end
@@ -477,7 +498,7 @@ end
 
 ```bash
 # Use in CI
-clp validate coverage_policy.rb
+cov-loupe validate coverage_policy.rb
 ```
 
 ## Advanced Usage
@@ -489,7 +510,6 @@ require "cov_loupe"
 
 root = "docs/fixtures/demo_project"
 model = CovLoupe::CoverageModel.new(root: root)
-all_files = model.all_files
 
 # Calculate coverage by directory (uses the same data as `cov-loupe totals`)
 patterns = %w[
@@ -504,7 +524,7 @@ results = patterns.map do |pattern|
   {
     directory: pattern,
     files: totals['files']['total'],
-    coverage: totals['percentage'].round(2),
+    coverage: totals['lines']['percent_covered'].round(2),
     covered: totals['lines']['covered'],
     total: totals['lines']['total']
   }
@@ -516,34 +536,6 @@ results.sort_by { |r| r[:coverage] }.each do |r|
 end
 ```
 
-### Coverage Delta Tracking
-
-```ruby
-require "cov_loupe"
-require "json"
-
-# Save current coverage
-root = "docs/fixtures/demo_project"
-model = CovLoupe::CoverageModel.new(root: root)
-current = model.all_files
-
-File.write("coverage_baseline.json", JSON.pretty_generate(current))
-
-# Later, compare with baseline
-baseline = JSON.parse(File.read("coverage_baseline.json"))
-
-current.each do |file|
-  baseline_file = baseline.find { |f| f['file'] == file['file'] }
-  next unless baseline_file
-
-  delta = file['percentage'] - baseline_file['percentage']
-  if delta.abs > 0.1  # Changed by more than 0.1%
-    symbol = delta > 0 ? '↑' : '↓'
-    puts "#{symbol} #{file['file']}: #{baseline_file['percentage']}% → #{file['percentage']}%"
-  end
-end
-```
-
 ### Integration with Code Review
 
 ```ruby
@@ -575,10 +567,11 @@ end
 
 ## Example Scripts
 
-The [`/examples`](/examples) directory contains runnable scripts:
+The `examples/` directory contains runnable scripts:
 
-- **[filter_and_table_demo.rb](../examples/filter_and_table_demo.rb)** - Filter and format coverage data
-- **[success_predicates/](/examples/success_predicates/)** - Custom coverage policy examples
+- **filter_and_table_demo.rb** - Filter and format coverage data (in `examples/` directory)
+- **[success_predicates](../examples/success_predicates.md)** - Custom coverage policy examples
+- **[Coverage Delta Tracking recipe in the Library API Guide](LIBRARY_API.md#coverage-delta-tracking)**
 
 ## Related Documentation
 

data/docs/user/INSTALLATION.md

@@ -1,6 +1,6 @@
 # Installation Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 ## Prerequisites
 
@@ -49,33 +49,6 @@ require "cov_loupe"
 
 The executable is `cov-loupe` (with hyphen).
 
-## PATH Configuration
-
-### With Version Managers
-
-Most version managers (rbenv, asdf, RVM, chruby) automatically configure PATH. After installation:
-
-```sh
-# Refresh shims if needed
-rbenv rehash      # rbenv
-asdf reshim ruby  # asdf
-
-# Verify executable is accessible
-which cov-loupe
-```
-
-**Important:** When changing Ruby versions, reinstall the gem and update any MCP configurations that use absolute paths.
-
-### Bundler Execution
-
-If PATH setup is problematic, use bundler:
-
-```sh
-bundle exec cov-loupe
-```
-
-This works from any project directory that has cov-loupe in its Gemfile.
-
 ## Verification
 
 ### Test Installation
@@ -122,6 +95,14 @@ Works with system Ruby or any version manager.
 
 Should work with Ruby installed via RubyInstaller. PATH configuration may differ.
 
+## Upgrading
+
+If you are upgrading from an earlier version of `cov-loupe`, please check the migration guides:
+
+- [Migrating to v4](migrations/MIGRATING_TO_V4.md)
+- [Migrating to v3](migrations/MIGRATING_TO_V3.md)
+- [Migrating to v2](migrations/MIGRATING_TO_V2.md)
+
 ## Next Steps
 
 - **[CLI Usage](CLI_USAGE.md)** - Learn command-line options