cov-loupe 3.0.0 → 4.0.0.pre

data/docs/user/LIBRARY_API.md

@@ -1,6 +1,6 @@
 # Library API Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 Use this gem programmatically to inspect coverage without running the CLI or MCP server. The primary entry point is `CovLoupe::CoverageModel`.
 
@@ -11,7 +11,6 @@ Use this gem programmatically to inspect coverage without running the CLI or MCP
 - [Return Types](#return-types)
 - [Error Handling](#error-handling)
 - [Advanced Recipes](#advanced-recipes)
-- [API Stability](#api-stability)
 
 ## Quick Start
 
@@ -21,45 +20,54 @@ require "cov_loupe"
 # Defaults (omit args; shown here with comments):
 # - root: "."
 # - resultset: resolved from common paths under root
-# - staleness: "off" (no stale checks)
-# - tracked_globs: nil (no project-level file-set checks)
+# - raise_on_stale: false (don't raise on stale data)
+# - tracked_globs: [] (no project-level file-set checks)
 model = CovLoupe::CoverageModel.new
 
 # Custom configuration (non-default values):
 model = CovLoupe::CoverageModel.new(
-  root: "/path/to/project",        # non-default project root
-  resultset: "build/coverage",      # file or directory containing .resultset.json
-  staleness: "error",               # enable stale checks (raise on stale)
-  tracked_globs: ["lib/**/*.rb"]    # for 'all_files' staleness: flag new/missing files
+  root: File.join(Dir.home, 'project'),          # non-default project root
+  resultset: "build/coverage",                   # file or directory containing .resultset.json
+  raise_on_stale: true,                          # enable strict staleness checks (raise on stale)
+  tracked_globs: ["lib/cov_loupe/tools/**/*.rb"] # for 'list' staleness: flag new/missing files
 )
 
 # List all files with coverage summary
-files = model.all_files
+list_result = model.list
+files = list_result['files']
 # Per-file queries
-summary = model.summary_for("lib/foo.rb")
-uncovered = model.uncovered_for("lib/foo.rb")
-detailed = model.detailed_for("lib/foo.rb")
-raw = model.raw_for("lib/foo.rb")
+
+target = 'lib/cov_loupe/base_tool.rb'
+summary = model.summary_for(target)
+uncovered = model.uncovered_for(target)
+detailed = model.detailed_for(target)
+raw = model.raw_for(target)
 ```
 
 ## Method Reference
 
-### `all_files(sort_order: :descending)`
+### `list(sort_order: :descending, raise_on_stale: nil, tracked_globs: [])`
 
 Returns coverage summary for all files in the resultset.
 
 **Parameters:**
 - `sort_order` (Symbol, optional): `:descending` (default) or `:ascending` by coverage percentage
+- `raise_on_stale` (Boolean, optional): Whether to raise error if project is stale. Defaults to model setting.
+- `tracked_globs` (Array<String>, optional): Patterns to filter files (also used for staleness checks)
 
-**Returns:** `Array<Hash>` - See [all_files return type](#all_files)
+**Returns:** `Hash` - See [list return type](#list)
 
 **Example:**
 ```ruby
-files = model.all_files
-# => [ { 'file' => '/abs/path/lib/foo.rb', 'covered' => 12, 'total' => 14, 'percentage' => 85.71, 'stale' => false }, ... ]
+list_result = model.list
+files = list_result['files']
+# => [ { 'file' => '/abs/path/lib/foo.rb', 'covered' => 12, 'total' => 14, 'percentage' => 85.71, 'stale' => "ok" }, ... ]
 
 # Get worst coverage first
-worst_files = model.all_files(sort_order: :ascending).first(10)
+worst_files = model.list(sort_order: :ascending)['files'].first(10)
+
+# Force staleness check
+model.list(raise_on_stale: true)
 ```
 
 ### `summary_for(path)`
@@ -67,7 +75,7 @@ worst_files = model.all_files(sort_order: :ascending).first(10)
 Returns coverage summary for a specific file.
 
 **Parameters:**
-- `path` (String): File path (absolute, relative to root, or basename)
+- `path` (String): File path (absolute or relative to root)
 
 **Returns:** `Hash` - See [summary_for return type](#summary_for)
 
@@ -75,8 +83,8 @@ Returns coverage summary for a specific file.
 
 **Example:**
 ```ruby
-summary = model.summary_for("lib/foo.rb")
-# => { 'file' => '/abs/.../lib/foo.rb', 'summary' => {'covered'=>12, 'total'=>14, 'percentage'=>85.71}, 'stale' => false }
+summary = model.summary_for(target)
+# => { 'file' => '/abs/.../lib/foo.rb', 'summary' => {'covered'=>12, 'total'=>14, 'percentage'=>85.71} }
 ```
 
 ### `uncovered_for(path)`
@@ -84,7 +92,7 @@ summary = model.summary_for("lib/foo.rb")
 Returns list of uncovered line numbers for a specific file.
 
 **Parameters:**
-- `path` (String): File path (absolute, relative to root, or basename)
+- `path` (String): File path (absolute or relative to root)
 
 **Returns:** `Hash` - See [uncovered_for return type](#uncovered_for)
 
@@ -93,7 +101,7 @@ Returns list of uncovered line numbers for a specific file.
 **Example:**
 ```ruby
 uncovered = model.uncovered_for("lib/foo.rb")
-# => { 'file' => '/abs/.../lib/foo.rb', 'uncovered' => [5, 9, 12], 'summary' => { ... }, 'stale' => false }
+# => { 'file' => '/abs/.../lib/foo.rb', 'uncovered' => [5, 9, 12], 'summary' => { ... } }
 ```
 
 ### `detailed_for(path)`
@@ -101,7 +109,7 @@ uncovered = model.uncovered_for("lib/foo.rb")
 Returns per-line coverage details with hit counts.
 
 **Parameters:**
-- `path` (String): File path (absolute, relative to root, or basename)
+- `path` (String): File path (absolute or relative to root)
 
 **Returns:** `Hash` - See [detailed_for return type](#detailed_for)
 
@@ -110,7 +118,7 @@ Returns per-line coverage details with hit counts.
 **Example:**
 ```ruby
 detailed = model.detailed_for("lib/foo.rb")
-# => { 'file' => '/abs/.../lib/foo.rb', 'lines' => [{'line' => 1, 'hits' => 1, 'covered' => true}, ...], 'summary' => { ... }, 'stale' => false }
+# => { 'file' => '/abs/.../lib/foo.rb', 'lines' => [{'line' => 1, 'hits' => 1, 'covered' => true}, ...], 'summary' => { ... } }
 ```
 
 ### `raw_for(path)`
@@ -118,7 +126,7 @@ detailed = model.detailed_for("lib/foo.rb")
 Returns raw SimpleCov lines array for a specific file.
 
 **Parameters:**
-- `path` (String): File path (absolute, relative to root, or basename)
+- `path` (String): File path (absolute or relative to root)
 
 **Returns:** `Hash` - See [raw_for return type](#raw_for)
 
@@ -127,16 +135,18 @@ Returns raw SimpleCov lines array for a specific file.
 **Example:**
 ```ruby
 raw = model.raw_for("lib/foo.rb")
-# => { 'file' => '/abs/.../lib/foo.rb', 'lines' => [nil, 1, 0, 3, ...], 'stale' => false }
+# => { 'file' => '/abs/.../lib/foo.rb', 'lines' => [nil, 1, 0, 3, ...] }
 ```
 
-### `format_table(rows = nil, sort_order: :descending)`
+### `format_table(rows = nil, sort_order: :descending, raise_on_stale: nil, tracked_globs: nil)`
 
 Generates formatted ASCII table string.
 
 **Parameters:**
-- `rows` (Array<Hash>, optional): Custom row data; defaults to `all_files`
+- `rows` (Array<Hash>, optional): Custom row data; defaults to `list`
 - `sort_order` (Symbol, optional): `:descending` (default) or `:ascending`
+- `raise_on_stale` (Boolean, optional): Whether to raise error if project is stale. Defaults to model setting.
+- `tracked_globs` (Array<String>, optional): Patterns to filter files.
 
 **Returns:** `String` - Formatted table with Unicode borders
 
@@ -147,29 +157,38 @@ table = model.format_table
 puts table
 
 # Custom rows
-lib_files = model.all_files.select { |f| f['file'].include?('/lib/') }
+lib_files = model.list['files'].select { |f| f['file'].include?('/lib/') }
 lib_table = model.format_table(lib_files, sort_order: :descending)
 puts lib_table
 ```
 
-### `project_totals(tracked_globs: nil)`
+### `project_totals(tracked_globs: [], raise_on_stale: nil)`
 
 Returns aggregated coverage totals across all files.
 
 **Parameters:**
 - `tracked_globs` (Array<String> or String, optional): Glob patterns to filter files
+- `raise_on_stale` (Boolean, optional): Whether to raise error if project is stale. Defaults to model setting.
 
 **Returns:** `Hash` - See [project_totals return type](#project_totals)
 
 **Example:**
 ```ruby
 totals = model.project_totals
-# => { 'lines' => { 'total' => 123, 'covered' => 100, 'uncovered' => 23 }, 'percentage' => 81.3, 'files' => { 'total' => 5, 'ok' => 4, 'stale' => 1 } }
+# => {
+#      'lines' => { 'total' => 123, 'covered' => 100, 'uncovered' => 23, 'percent_covered' => 81.3 },
+#      'tracking' => { 'enabled' => true, 'globs' => ['lib/**/*.rb'] },
+#      'files' => { 'total' => 4, 'with_coverage' => { 'total' => 4, 'ok' => 4, 'stale' => { ... } } }
+#    }
 
 # Filter to specific directory
 lib_totals = model.project_totals(tracked_globs: 'lib/**/*.rb')
 ```
 
+When `raise_on_stale: true` is set, the method raises on stale coverage instead of returning totals. Otherwise, totals exclude stale files (`M`, `T`, `L`, `E`) from line counts and report stale breakdowns under `files['with_coverage']['stale']`.
+
+Note: The `without_coverage` hash will only be present if `tracked_globs` were specified.
+
 ### `relativize(data)`
 
 Converts absolute file paths in coverage data to relative paths from project root.
@@ -182,29 +201,40 @@ Converts absolute file paths in coverage data to relative paths from project roo
 **Example:**
 ```ruby
 summary = model.summary_for('lib/cov_loupe/model.rb')
-# => { 'file' => '/home/user/project/lib/cov_loupe/model.rb', ... }
+# => { 'file' => '/path/to/project/lib/cov_loupe/model.rb', ... }
 
 relative_summary = model.relativize(summary)
 # => { 'file' => 'lib/cov_loupe/model.rb', ... }
 
 # Works with arrays too
-files = model.all_files
+list_result = model.list
+files = list_result['files']
 relative_files = model.relativize(files)
 ```
 
 ## Return Types
 
-### `all_files`
+### `list`
 
-Returns `Array<Hash>` where each hash contains:
+Returns `Hash` with file data and staleness metadata:
 
 ```ruby
 {
-  'file' => String,       # Absolute file path
-  'covered' => Integer,   # Number of covered lines
-  'total' => Integer,     # Total relevant lines
-  'percentage' => Float,  # Coverage percentage (0.00-100.00)
-  'stale' => false | String  # Staleness indicator: false, 'M', 'T', or 'L'
+  'files' => [
+    {
+      'file' => String,       # Absolute file path
+      'covered' => Integer,   # Number of covered lines
+      'total' => Integer,     # Total relevant lines
+      'percentage' => Float,  # Coverage percentage (0.00-100.00)
+      'stale' => String  # Staleness indicator: "ok", "error", "missing", "newer", or "length_mismatch"
+    }
+  ],
+  'skipped_files' => Array<String>,        # Files skipped due to coverage errors
+  'missing_tracked_files' => Array<String>,# Tracked files missing from coverage
+  'newer_files' => Array<String>,          # Files newer than coverage
+  'deleted_files' => Array<String>,        # Coverage entries for deleted files
+  'length_mismatch_files' => Array<String>,# Files whose line counts differ from coverage
+  'unreadable_files' => Array<String>      # Files that could not be read
 }
 ```
 
@@ -282,19 +312,44 @@ Returns `Hash`:
 ```ruby
 {
   'lines' => {
-    'total' => Integer,      # Total relevant lines across all files
-    'covered' => Integer,    # Total covered lines
-    'uncovered' => Integer   # Total uncovered lines
+    'total' => Integer,            # Total relevant lines across all files
+    'covered' => Integer,          # Total covered lines
+    'uncovered' => Integer,        # Total uncovered lines
+    'percent_covered' => Float     # Overall percent covered
+  },
+  'tracking' => {
+    'enabled' => Boolean,          # Whether tracked_globs are active
+    'globs' => Array<String>       # Active tracked globs (empty when disabled)
   },
-  'percentage' => Float,     # Overall coverage percentage
   'files' => {
-    'total' => Integer,      # Total number of files
-    'ok' => Integer,         # Files with fresh coverage
-    'stale' => Integer       # Files with stale coverage
+    'total' => Integer,          # Total number of files (with + without coverage)
+    'with_coverage' => {
+      'total' => Integer,        # Files with coverage entries
+      'ok' => Integer,           # Fresh coverage entries
+      'stale' => {
+        'total' => Integer,      # Stale coverage entries
+        'by_type' => {
+          'missing_from_disk' => Integer,
+          'newer' => Integer,
+          'length_mismatch' => Integer,
+          'unreadable' => Integer
+        }
+      }
+    },
+    'without_coverage' => {
+      'total' => Integer,        # Tracked files missing coverage entries
+      'by_type' => {
+        'missing_from_coverage' => Integer,
+        'unreadable' => Integer,
+        'skipped' => Integer
+      }
+    }
   }
 }
 ```
 
+Note: The `without_coverage` hash will only be present if `tracked_globs` were specified.
+
 ## Error Handling
 
 ### Exception Types
@@ -303,7 +358,7 @@ The library raises these custom exceptions:
 
 - **`CovLoupe::ResultsetNotFoundError`** - Coverage data file not found
 - **`CovLoupe::FileError`** - Requested file not in coverage data
-- **`CovLoupe::CoverageDataStaleError`** - Coverage data is stale (only when `staleness: 'error'`)
+- **`CovLoupe::CoverageDataStaleError`** - Coverage data is stale (only when `raise_on_stale: true`)
 - **`CovLoupe::CoverageDataError`** - Invalid coverage data format or structure
 
 All exceptions inherit from `CovLoupe::Error`.
@@ -331,8 +386,8 @@ end
 
 ```ruby
 # Option 1: Check staleness without raising
-model = CovLoupe::CoverageModel.new(staleness: "off")
-files = model.all_files
+model = CovLoupe::CoverageModel.new(raise_on_stale: false)
+files = model.list['files']
 
 stale_files = files.select { |f| f['stale'] }
 if stale_files.any?
@@ -344,8 +399,8 @@ end
 
 # Option 2: Raise on staleness
 begin
-  model = CovLoupe::CoverageModel.new(staleness: "error")
-  files = model.all_files
+  model = CovLoupe::CoverageModel.new(raise_on_stale: true)
+  files = model.list['files']
 rescue CovLoupe::CoverageDataStaleError => e
   puts "Stale coverage detected: #{e.message}"
   puts "Re-run tests: bundle exec rspec"
@@ -428,9 +483,9 @@ require "cov_loupe"
 
 class CoverageValidator
   THRESHOLDS = {
-    'lib/' => 90.0,      # Core library needs 90%+
-    'app/' => 80.0,      # Application code needs 80%+
-    'spec/' => 70.0,     # Test helpers need 70%+
+    'lib/api/' => 90.0,         # API layer needs 90%+
+    'app/models/' => 85.0,      # Models need 85%+
+    'app/controllers/' => 75.0, # Controllers need 75%+
   }
 
   def initialize(model)
@@ -438,7 +493,7 @@ class CoverageValidator
   end
 
   def validate!
-    files = @model.all_files
+    files = @model.list['files']
     failures = []
 
     files.each do |file|
@@ -497,7 +552,7 @@ directory_stats = 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']
   }
@@ -522,7 +577,7 @@ class CoverageDeltaTracker
   end
 
   def save_baseline
-    current = @model.all_files
+    current = @model.list['files']
     File.write(@baseline_path, JSON.pretty_generate(current))
     puts "Saved coverage baseline (#{current.length} files)"
   end
@@ -534,7 +589,7 @@ class CoverageDeltaTracker
     end
 
     baseline = JSON.parse(File.read(@baseline_path))
-    current = @model.all_files
+    current = @model.list['files']
 
     improved = []
     regressed = []
@@ -600,57 +655,64 @@ class CoverageReporter
   end
 
   def generate_markdown_report(output_path)
-    files = @model.all_files
+    files = @model.list['files']
     totals = @model.project_totals
 
-    File.open(output_path, 'w') do |f|
-      f.puts "# Coverage Report"
-      f.puts
-      f.puts "Generated: #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
-      f.puts
-
-      # Overall stats
-      overall_percentage = totals['percentage']
-      total_lines = totals['lines']['total']
-      covered_lines = totals['lines']['covered']
-      total_files = totals['files']['total']
-
-      f.puts "## Overall Coverage: #{overall_percentage}%"
-      f.puts
-      f.puts "- Total Files: #{total_files}"
-      f.puts "- Total Lines: #{total_lines}"
-      f.puts "- Covered Lines: #{covered_lines}"
-      f.puts
-
-      # Files below threshold
-      threshold = 80.0
-      low_coverage = files.select { |file| file['percentage'] < threshold }
-
-      if low_coverage.any?
-        f.puts "## Files Below #{threshold}% Coverage"
-        f.puts
-        f.puts "| File | Coverage | Missing Lines |"
-        f.puts "|------|----------|---------------|"
-
-        low_coverage.sort_by { |file| file['percentage'] }.each do |file|
-          uncovered = @model.uncovered_for(file['file'])
-          missing_count = uncovered['uncovered'].length
-          f.puts "| #{file['file']} | #{file['percentage']}% | #{missing_count} |"
-        end
-        f.puts
-      end
+    # Overall stats
+    overall_percentage = totals['lines']['percent_covered']
+    total_lines = totals['lines']['total']
+    covered_lines = totals['lines']['covered']
+    total_files = totals['files']['total']
 
-      # Top performers
-      f.puts "## Top 10 Best Covered Files"
-      f.puts
-      f.puts "| File | Coverage |"
-      f.puts "|------|----------|"
+    # Files below threshold
+    threshold = 80.0
+    low_coverage = files.select { |file| file['percentage'] < threshold }
 
-      files.sort_by { |file| -file['percentage'] }.take(10).each do |file|
-        f.puts "| #{file['file']} | #{file['percentage']}% |"
-      end
+    # Build low coverage table
+    low_coverage_section = if low_coverage.any?
+      rows = low_coverage.sort_by { |file| file['percentage'] }.map do |file|
+        uncovered = @model.uncovered_for(file['file'])
+        missing_count = uncovered['uncovered'].length
+        "| #{file['file']} | #{file['percentage']}% | #{missing_count} |"
+      end.join("\n")
+
+      <<~LOW_COVERAGE_TABLE
+
+        ## Files Below #{threshold}% Coverage
+
+        | File | Coverage | Missing Lines |
+        |------|----------|---------------|
+        #{rows}
+      LOW_COVERAGE_TABLE
+    else
+      ""
     end
 
+    # Build top performers table
+    top_rows = files.sort_by { |file| -file['percentage'] }.take(10).map do |file|
+      "| #{file['file']} | #{file['percentage']}% |"
+    end.join("\n")
+
+    # Generate report
+    report = <<~COVERAGE_REPORT
+      # Coverage Report
+
+      Generated: #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}
+
+      ## Overall Coverage: #{overall_percentage}%
+
+      - Total Files: #{total_files}
+      - Total Lines: #{total_lines}
+      - Covered Lines: #{covered_lines}
+      #{low_coverage_section}
+      ## Top 10 Best Covered Files
+
+      | File | Coverage |
+      |------|----------|
+      #{top_rows}
+    COVERAGE_REPORT
+
+    File.write(output_path, report)
     puts "Report saved to #{output_path}"
   end
 end
@@ -660,30 +722,73 @@ reporter = CoverageReporter.new(model)
 reporter.generate_markdown_report("coverage_report.md")
 ```
 
-## Staleness Detection
+### Per-Model Context (Advanced)
+
+By default, all `CoverageModel` instances share the global context for error handling and logging. For advanced scenarios where you need different models with different logging or error handling configurations in the same process, you can pass a custom context to each model.
+
+```ruby
+require "cov_loupe"
+
+# Scenario: Analyzing coverage for multiple projects in one script
+
+# Project A: Detailed logging for debugging
+context_a = CovLoupe.create_context(
+  error_handler: CovLoupe::ErrorHandlerFactory.for_library,
+  log_target: 'project_a_coverage.log'
+)
 
-The `all_files` method returns a `'stale'` field for each file with one of these values:
+model_a = CovLoupe::CoverageModel.new(
+  root: '/path/to/project_a',
+  resultset: '/path/to/project_a/coverage/.resultset.json',
+  context: context_a
+)
 
-- `false` - Coverage data is current
-- `'M'` - **Missing**: File no longer exists on disk
-- `'T'` - **Timestamp**: File modified more recently than coverage data
-- `'L'` - **Length**: Source file line count differs from coverage data
+# Project B: Different log file
+context_b = context_a.with(log_target: 'project_b_coverage.log')
 
-**Note:** Per-file methods (`summary_for`, `uncovered_for`, `detailed_for`, `raw_for`) do not include staleness information in their return values. To check staleness for individual files, use `all_files` and filter the results.
+model_b = CovLoupe::CoverageModel.new(
+  root: '/path/to/project_b',
+  resultset: '/path/to/project_b/coverage/.resultset.json',
+  context: context_b
+)
+
+# Each model logs to its own file
+summary_a = model_a.summary_for('lib/foo.rb')  # Logs to project_a_coverage.log
+summary_b = model_b.summary_for('lib/bar.rb')  # Logs to project_b_coverage.log
+
+# You can also change a model's context at runtime
+model_a.context = CovLoupe.context  # Switch to global context
+```
+
+**When to use per-model contexts:**
+- Managing coverage for multiple projects in one script
+- Different error handling strategies per model
+- Separate log files for different data sources
+- Testing scenarios requiring isolated configurations
+
+**Simple use case (most common):**
+```ruby
+# For most use cases, just configure the global context once
+CovLoupe.error_handler = CovLoupe::ErrorHandlerFactory.for_library
+CovLoupe.default_log_file = 'coverage_analysis.log'
+
+# All models automatically use the global context
+model = CovLoupe::CoverageModel.new
+```
+
+## Staleness Detection
 
-When `staleness: 'error'` mode is enabled in `CoverageModel.new`, the model will raise `CovLoupe::CoverageDataStaleError` exceptions when stale files are detected during method calls.
+The `list` method returns a `'stale'` field for each file with one of these values:
 
-## API Stability
+- `"ok"` - Coverage data is current
+- `"missing"` - **Missing**: File no longer exists on disk
+- `"newer"` - **Timestamp**: File modified more recently than coverage data
+- `"length_mismatch"` - **Length**: Source file line count differs from coverage data
+- `"error"` - **Error**: Staleness check failed
 
-Consider the following public and stable under SemVer:
-- `CovLoupe::CoverageModel.new(root:, resultset:, staleness: 'off', tracked_globs: nil)`
-- `#raw_for(path)`, `#summary_for(path)`, `#uncovered_for(path)`, `#detailed_for(path)`, `#all_files(sort_order:)`, `#format_table(rows: nil, sort_order:, check_stale:, tracked_globs:)`
-- Return shapes shown in the [Return Types](#return-types) section
-- Exception types documented in [Error Handling](#error-handling)
+**Note:** Per-file methods (`summary_for`, `uncovered_for`, `detailed_for`, `raw_for`) do not include staleness information in their return values. To check staleness for individual files, use `list` and filter the results.
 
-**Note:**
-- CLI (`CovLoupe.run(argv)`) and MCP tools remain stable but are separate surfaces
-- Internal helpers under `CovLoupe::CovUtil` may change; prefer `CoverageModel` unless you need low-level access
+When `raise_on_stale: true` is enabled in `CoverageModel.new`, the model will raise `CovLoupe::CoverageDataStaleError` exceptions when stale files are detected during method calls.
 
 ## Related Documentation