cov-loupe 3.0.0 → 4.0.0.pre

data/docs/user/prompts/non-web-coverage-analysis-prompt.md

@@ -0,0 +1,103 @@
+# Test Coverage Analysis Prompt for Ruby Applications
+
+[Back to main README](../../index.md)
+
+Use the cov-loupe MCP server tool to analyze the test coverage data generated by simplecov for this Ruby project. 
+
+Generate a detailed coverage analysis report and output it to a markdown file named `test_coverage_analysis.md`.
+
+The report should include:
+
+## 1. Executive Summary
+- Overall coverage percentage and trend direction
+- High-level assessment of testing health across the application
+- Key strengths and critical gaps at a glance
+
+## 2. Coverage by Application Component
+Detailed analysis of coverage across different application layers:
+- **Core Domain Logic**: Business logic classes, domain models, and entities
+- **Services/Commands**: Service objects, command patterns, and use cases
+- **Data Access Layer**: Repository patterns, data mappers, database interactions
+- **External Integrations**: API clients, third-party service wrappers
+- **Utilities/Helpers**: Helper modules, utility classes, and shared functions
+- **CLI Components**: Command-line interface handlers and argument parsers (if applicable)
+- **Configuration**: Configuration classes and initialization logic
+- **Lib files**: Custom libraries and reusable modules
+- **Concerns/Mixins**: Shared modules and concerns
+
+## 3. Well-Tested Areas
+- What's working well and why
+- Testing patterns and practices to replicate
+- Examples of strong test coverage with specific file references
+
+## 4. Poorly-Tested Areas
+Organize by:
+- **Complexity to Test**: Simple/Moderate/Complex (considering dependencies, I/O operations, external services, etc.)
+- **Risk Level**: High/Medium/Low (impact on data integrity, system reliability, business logic correctness)
+- **Coverage Gap Size**: Percentage of uncovered lines and number of untested methods
+
+## 5. Priority Issues Table
+Create a markdown table with these columns:
+- File/Module Path
+- Component Type (Service/Domain/Integration/etc.)
+- Current Coverage %
+- Uncovered Lines Count
+- Risk Level (High/Medium/Low)
+- Complexity to Fix (High/Medium/Low)
+- Priority Score (1-10, with 10 being highest priority)
+- Recommended Action (specific next steps)
+
+Sort by Priority Score descending.
+
+## 6. Ruby Application Testing Analysis
+- **Domain Logic Testing**: Coverage of business rules, validations, calculations, state transitions
+- **Service Layer Testing**: Coverage of orchestration logic, error handling, transaction boundaries
+- **Data Access Testing**: Coverage of queries, data transformations, persistence operations
+- **Integration Testing**: Testing of interactions between components and external systems
+- **API Client Testing**: Coverage of HTTP requests, response parsing, error handling
+- **File I/O Operations**: Testing of file reading/writing, parsing, serialization
+- **Concurrency/Threading**: Coverage of thread-safe operations, race conditions (if applicable)
+- **Error Handling**: Testing of exception handling, retry logic, fallback mechanisms
+- **Security**: Testing of input validation, data sanitization, authentication/authorization
+- **Missing Test Types**: Identify gaps in unit/integration/end-to-end tests
+
+## 7. Common Ruby Testing Anti-Patterns Detected
+- Over-mocking leading to brittle tests
+- Missing edge case coverage in core domain logic
+- Untested error handling and failure scenarios
+- Missing tests for external service integrations
+- Lack of integration tests for critical workflows
+- Untested concurrency or threading logic (if applicable)
+- Insufficient testing of data transformation pipelines
+- Missing tests for CLI argument parsing and validation
+
+## 8. Actionable Testing Roadmap
+Prioritized list of specific issues to resolve, organized by effort level:
+- **Quick Wins** (< 2 hours): Simple tests with high impact
+- **Sprint 1** (2-8 hours): Medium complexity, high priority
+- **Sprint 2** (1-2 days): Complex but critical coverage gaps
+- **Long-term** (> 2 days): Large refactoring or architectural test improvements
+
+Include specific file paths, method names, and recommended testing approaches for each item.
+
+## 9. Metrics Dashboard
+Key numbers:
+- Overall coverage percentage
+- Number of files at 0% coverage
+- Number of files at 100% coverage
+- Number of files above 90% coverage
+- Number of files below 50% coverage
+- Coverage by component type (Domain %, Services %, Integrations %, etc.)
+- Trend direction (if historical data available)
+- Lines of code vs lines of test code ratio
+- Average cyclomatic complexity of untested methods (if available)
+
+## 10. Risk Assessment
+- **Critical Paths**: Identify core business workflows and their test coverage
+- **High-Risk Untested Code**: Data processing, financial calculations, authentication, data deletion, etc.
+- **Security Implications**: Areas where lack of tests could lead to vulnerabilities
+- **Technical Debt**: Old code with no tests that should be prioritized for coverage
+- **External Dependencies**: Integration points with poor test coverage
+- **Data Integrity Risks**: Operations that modify or delete data without adequate test coverage
+
+Include specific file paths, line numbers, and code examples where relevant. Focus on actionable insights rather than just reporting numbers. Provide concrete recommendations for improving the test suite architecture and coverage strategy.

data/docs/user/prompts/rails-coverage-analysis-prompt.md

@@ -0,0 +1,94 @@
+# Test Coverage Analysis Prompt for Ruby on Rails Project
+
+[Back to main README](../../index.md)
+
+Use the cov-loupe MCP server tool to analyze the test coverage data generated by simplecov for this Ruby on Rails project. Generate a detailed coverage analysis report and output it to a markdown file named `test_coverage_analysis.md`.
+
+The report should include:
+
+## 1. Executive Summary
+- Overall coverage percentage and trend direction
+- High-level assessment of testing health across the Rails application
+- Key strengths and critical gaps at a glance
+
+## 2. Coverage by Rails Component
+Detailed analysis of coverage across different Rails layers:
+- **Models**: ActiveRecord models, validations, scopes, associations, callbacks
+- **Controllers**: Actions, before_actions, strong parameters, response handling
+- **Views**: View helpers, partials, component logic
+- **Mailers**: Email templates and delivery logic
+- **Jobs**: ActiveJob background jobs and queue handlers
+- **Services/POROs**: Business logic classes and service objects
+- **Concerns**: Shared modules and mixins
+- **Lib files**: Custom libraries and utilities
+- **Configuration**: Initializers and config files (if applicable)
+
+## 3. Well-Tested Areas
+- What's working well and why
+- Testing patterns and practices to replicate
+- Examples of strong test coverage with specific file references
+
+## 4. Poorly-Tested Areas
+Organize by:
+- **Complexity to Test**: Simple/Moderate/Complex (considering Rails dependencies, database setup, external services, etc.)
+- **Risk Level**: High/Medium/Low (impact on user experience, data integrity, security)
+- **Coverage Gap Size**: Percentage of uncovered lines and number of untested methods
+
+## 5. Priority Issues Table
+Create a markdown table with these columns:
+- File/Module Path
+- Component Type (Model/Controller/Job/etc.)
+- Current Coverage %
+- Uncovered Lines Count
+- Risk Level (High/Medium/Low)
+- Complexity to Fix (High/Medium/Low)
+- Priority Score (1-10, with 10 being highest priority)
+- Recommended Action (specific next steps)
+
+Sort by Priority Score descending.
+
+## 6. Rails-Specific Testing Analysis
+- **Model Testing**: Coverage of validations, associations, scopes, callbacks, custom methods
+- **Controller Testing**: Coverage of happy paths vs error handling, authentication/authorization
+- **Integration Testing**: Request specs, feature specs, system tests
+- **API Testing**: Coverage of JSON/XML responses, API versioning
+- **Database Operations**: Testing of migrations, seeds, complex queries
+- **Background Jobs**: Coverage of job execution, retry logic, error handling
+- **Security**: Testing of authentication, authorization, input sanitization, CSRF protection
+- **Missing Test Types**: Identify gaps in unit/integration/system/feature tests
+
+## 7. Common Rails Testing Anti-Patterns Detected
+- Over-reliance on controller tests vs request specs
+- Missing edge case coverage in models
+- Untested error handling and failure scenarios
+- Missing tests for background jobs and mailers
+- Lack of integration tests for critical user flows
+- Untested authorization/permission logic
+
+## 8. Actionable Testing Roadmap
+Prioritized list of specific issues to resolve, organized by effort level:
+- **Quick Wins** (< 2 hours): Simple tests with high impact
+- **Sprint 1** (2-8 hours): Medium complexity, high priority
+- **Sprint 2** (1-2 days): Complex but critical coverage gaps
+- **Long-term** (> 2 days): Large refactoring or architectural test improvements
+
+Include specific file paths, method names, and recommended testing approaches for each item.
+
+## 9. Metrics Dashboard
+Key numbers:
+- Overall coverage percentage
+- Number of files at 0% coverage
+- Number of files at 100% coverage
+- Number of files above 90% coverage
+- Number of files below 50% coverage
+- Coverage by component type (Models %, Controllers %, etc.)
+- Trend direction (if historical data available)
+- Lines of code vs lines of test code ratio
+
+## 10. Risk Assessment
+- **Critical Paths**: Identify core user journeys and their test coverage
+- **High-Risk Untested Code**: Payment processing, authentication, data deletion, etc.
+- **Security Implications**: Areas where lack of tests could lead to vulnerabilities
+- **Technical Debt**: Old code with no tests that should be prioritized for coverage
+
+Include specific file paths, line numbers, and code examples where relevant. Focus on actionable insights rather than just reporting numbers. Provide concrete recommendations for improving the test suite architecture and coverage strategy.

data/docs/user/prompts/use-cli-not-mcp-prompt.md

@@ -0,0 +1,53 @@
+# Use the 'cov-loupe' application as a command line utility.
+
+[Back to main README](../../index.md)
+
+The `cov-loupe` application provides precise test coverage information for your Ruby application.
+
+It reads the `.resultset.json` file generated by SimpleCov, and offers multiple ways to analyze and display its information.
+
+Below is the help for version 4.0.0.pre, but run `cov-loupe --help` to make sure you get the most up-to-date information.
+
+----
+```bash
+-------------------------------------------------------------------------------
+Usage:                 cov-loupe [options] [subcommand] [args]  (default subcommand: list)
+Repository:            https://github.com/keithrbennett/cov-loupe
+Documentation (Web):   https://keithrbennett.github.io/cov-loupe/
+Documentation (Local): /home/kbennett/code/cov-loupe/**/*.md
+Version:               4.0.0.pre
+-------------------------------------------------------------------------------
+
+Subcommands:
+  detailed <path>          Show per-line rows with hits/covered
+  list                     Show files coverage (default: table, or use --format)
+  raw <path>               Show the SimpleCov 'lines' array
+  summary <path>           Show covered/total/% for a file
+  totals                   Show aggregated line totals and average %
+  uncovered <path>         Show uncovered lines and a summary
+  validate <file>          Evaluate coverage policy from file (exit 0=pass, 1=fail, 2=error)
+  validate -i <code>       Evaluate coverage policy from code string
+  version                  Show version information
+
+Options:
+    -r, --resultset PATH             Path or directory that contains .resultset.json (default: coverage/.resultset.json)
+    -R, --root PATH                  Project root (default: .)
+    -f, --format FORMAT              Output format: t[able]|j[son]|pretty-json|y[aml]|a[wesome-print] (default: table)
+    -o, --sort-order ORDER           Sort order for list: a[scending]|d[escending] (default descending)
+    -s, --source MODE                Source display: f[ull]|u[ncovered]
+    -c, --context-lines N            Context lines around uncovered lines (non-negative, default: 2)
+    -C, --color BOOLEAN              Enable/disable ANSI colors for source output (default: true). Accepts: yes/no/y/n/true/false/t/f/on/off/+/-/1/0
+    -S, --raise-on-stale BOOLEAN     Raise error if coverage is stale (default: false). Accepts: yes/no/y/n/true/false/t/f/on/off/+/-/1/0
+    -g, --tracked-globs x,y,z        Globs for filtering files (list/totals subcommands)
+    -h, --help                       Show help
+    -l, --log-file PATH              Log file path (default ./cov_loupe.log, use stdout/stderr for streams)
+    -m, --mode MODE                  Execution mode: cli|mcp (default: cli)
+    -e, --error-mode MODE            Error handling mode: o[ff]|l[og]|d[ebug] (default log). off (silent), log (log errors to file), debug (verbose with backtraces)
+    -v, --version                    Show version information and exit.
+
+Examples:
+  cov-loupe --resultset coverage list
+  cov-loupe --format json --resultset coverage summary lib/foo.rb
+  cov-loupe --source uncovered --context-lines 2 uncovered lib/foo.rb
+  cov-loupe totals --format json
+```

data/examples/cli_demo.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Demo script for cov-loupe CLI subcommands and options
+# Runs against the included fixture project at spec/fixtures/project1.
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+CLI=("exe/cov-loupe")
+PROJ="examples/fixtures/demo_project"
+RESULTSET_DIR="coverage" # directory containing .resultset.json under PROJ
+
+run() {
+  cat <<BANNER
+
+
+
+-------------------------------------------------------------------------------
++ ${CLI[*]} $*
+-------------------------------------------------------------------------------
+
+BANNER
+  "${CLI[@]}" "$@"
+
+}
+
+cat <<INTRO
+== cov-loupe CLI demo ==
+
+Note: Project root and resultset JSON file normally do not need to be specified.
+We set --root here to use the examples/fixtures/demo_project nondefault location,
+and later demonstrate a nondefault resultset via the --resultset option.
+
+Project root:     $PROJ
+Resultset (dir):  $RESULTSET_DIR
+
+INTRO
+
+# 1) List all files (table)
+run list --root "$PROJ"
+
+# 2) List as JSON, descending sort
+run list --root "$PROJ" --sort-order descending --json
+
+# 3) Summary for a file (text and JSON)
+run summary lib/foo.rb --root "$PROJ"
+run summary lib/foo.rb --root "$PROJ" --json
+
+# 4) Include source with summary (full and uncovered-only with context)
+run summary lib/foo.rb --root "$PROJ" --source
+run summary lib/foo.rb --root "$PROJ" --source=uncovered --source-context 1
+
+# 5) Uncovered lines (text with source and JSON)
+run uncovered lib/foo.rb --root "$PROJ" --source=uncovered --source-context 2
+run uncovered lib/foo.rb --root "$PROJ" --json
+
+# 6) Detailed per-line data (text and JSON), with source
+run detailed lib/foo.rb --root "$PROJ" --source -C false
+run detailed lib/foo.rb --root "$PROJ" --json
+
+# 7) Raw lines array (JSON)
+run raw lib/foo.rb --root "$PROJ" --json
+
+# 8) Using environment variable for a NONDEFAULT resultset location
+#    Copy the default resultset into a simple alt directory to simulate a custom layout.
+ALT_DIR="$PROJ/alt_resultset"
+mkdir -p "$ALT_DIR"
+cp -f "$PROJ/coverage/.resultset.json" "$ALT_DIR/.resultset.json"
+echo 
+echo "+ ${CLI[*]} list --root $PROJ --resultset $PROJ/alt_resultset"
+"${CLI[@]}" list --root "$PROJ" --resultset "$PROJ/alt_resultset"
+
+echo
+echo "== Done =="
+
+# Cleanup files created for the nondefault resultset demo
+rm -rf "$ALT_DIR"

data/examples/filter_and_table_demo-output.md

@@ -0,0 +1,114 @@
+# cov-loupe Library Usage Examples
+=============================================
+
+## 1. Full Coverage Table
+```
+┌────────────────────────────────────────────────┬──────────┬───────────┬─────────┬───────┐
+│ File                                           │        % │   Covered │   Total │ Stale │
+├────────────────────────────────────────────────┼──────────┼───────────┼─────────┼───────┤
+│ /home/kbennett/code/cov-loupe/lib/bar.rb   │   33.33% │         1 │       3 │   !   │
+│ /home/kbennett/code/cov-loupe/lib/foo.rb   │   66.67% │         2 │       3 │   !   │
+└────────────────────────────────────────────────┴──────────┴───────────┴─────────┴───────┘
+Files: total 2, ok 0, stale 2
+```
+
+## 2. Filter by Directory (lib/ only)
+```ruby
+# Filter files by directory (e.g., only show files in lib/)
+files_data = model.list
+lib_files = files_data.select { |file| file["file"].include?("/lib/") }
+lib_files_table = model.format_table(lib_files)
+# => formatted table showing only files from lib/ directory
+```
+
+Result:
+```
+┌────────────────────────────────────────────────┬──────────┬───────────┬─────────┬───────┐
+│ File                                           │        % │   Covered │   Total │ Stale │
+├────────────────────────────────────────────────┼──────────┼───────────┼─────────┼───────┤
+│ /home/kbennett/code/cov-loupe/lib/bar.rb   │   33.33% │         1 │       3 │   !   │
+│ /home/kbennett/code/cov-loupe/lib/foo.rb   │   66.67% │         2 │       3 │   !   │
+└────────────────────────────────────────────────┴──────────┴───────────┴─────────┴───────┘
+Files: total 2, ok 0, stale 2
+```
+
+  ## 3. Filter by Pattern (files with specific naming)
+  ```ruby
+  # Filter by pattern (e.g., only show files with "foo" in name)
+  foo_files = files_data.select { |file| file["file"].include?("foo") }
+  foo_table = model.format_table(foo_files)
+  # => formatted table showing only files with 'foo' in filename
+  ```
+check_coverage_data
+
+Result:
+```
+┌────────────────────────────────────────────────┬──────────┬───────────┬─────────┬───────┐
+│ File                                           │        % │   Covered │   Total │ Stale │
+├────────────────────────────────────────────────┼──────────┼───────────┼─────────┼───────┤
+│ /home/kbennett/code/cov-loupe/lib/foo.rb   │   66.67% │         2 │       3 │   !   │
+└────────────────────────────────────────────────┴──────────┴───────────┴─────────┴───────┘
+Files: total 1, ok 0, stale 1
+```
+
+## 4. Filter by Coverage Threshold (only high-coverage files)
+```ruby
+# Filter by coverage percentage (e.g., only files >= 50% coverage)
+high_coverage_files = files_data.select { |file| file["percentage"] >= 50.0 }
+high_coverage_table = model.format_table(high_coverage_files)
+# => formatted table showing only well-covered files
+```
+
+Result:
+```
+┌────────────────────────────────────────────────┬──────────┬───────────┬─────────┬───────┐
+│ File                                           │        % │   Covered │   Total │ Stale │
+├────────────────────────────────────────────────┼──────────┼───────────┼─────────┼───────┤
+│ /home/kbennett/code/cov-loupe/lib/foo.rb   │   66.67% │         2 │       3 │   !   │
+└────────────────────────────────────────────────┴──────────┴───────────┴─────────┴───────┘
+Files: total 1, ok 0, stale 1
+```
+
+## 5. Staleness Analysis
+```ruby
+# Analyze coverage staleness to find potentially problematic files
+stale_files, healthy_files = files_data.partition { |file| file["stale"] }
+
+puts "## Potentially Stale Coverage Files"
+puts model.format_table(stale_files, sort_order: :descending)
+
+puts "## Healthy Coverage Files"
+puts model.format_table(healthy_files, sort_order: :descending)
+```
+
+Result:
+```
+## Potentially Stale Coverage Files
+┌────────────────────────────────────────────────┬──────────┬───────────┬─────────┬───────┐
+│ File                                           │        % │   Covered │   Total │ Stale │
+├────────────────────────────────────────────────┼──────────┼───────────┼─────────┼───────┤
+│ /home/kbennett/code/cov-loupe/lib/foo.rb   │   66.67% │         2 │       3 │   !   │
+│ /home/kbennett/code/cov-loupe/lib/bar.rb   │   33.33% │         1 │       3 │   !   │
+└────────────────────────────────────────────────┴──────────┴───────────┴─────────┴───────┘
+Files: total 2, ok 0, stale 2
+
+## Healthy Coverage Files
+(No healthy files found)
+```
+
+NOTE: To see staleness analysis in action with both stale and healthy files,
+try modifying file timestamps:
+  - Make one file appear older: `touch -t 202401010000 spec/fixtures/project1/lib/foo.rb`
+  - Or make one file appear newer: `touch spec/fixtures/project1/lib/bar.rb`
+Then run this script again to see partition results change.
+
+## Summary
+This example demonstrates how cov-loupe can be used as a library to:
+- Load and query coverage data
+- Filter files by various criteria (directory, filename, coverage threshold)
+- Perform staleness analysis to identify potentially problematic files
+- Generate CI/CD integration reports with exit codes for monitoring
+- Create custom reports tailored to specific needs
+
+The table formatting functionality (format_table) is now accessible
+directly in library mode, not just through the CLI!

data/examples/filter_and_table_demo.rb

@@ -0,0 +1,174 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Using cov-loupe as a library to filter and format coverage tables
+# This demonstrates filtering files by directory and other criteria, then generating tables
+
+require_relative '../lib/cov_loupe'
+
+def check_coverage_data
+  unless File.exist?('spec/fixtures/project1/coverage/.resultset.json')
+    puts <<~DOC
+      Error: Coverage data file not found.
+
+      Please run this script from project root directory:
+
+          examples/filter_and_table_demo.rb
+
+      If coverage data is missing, run tests first to generate it:
+
+          bundle exec rspec
+    DOC
+    exit 1
+  end
+end
+
+def output_examples
+  puts <<~DOC
+    # cov-loupe Library Usage Examples
+    =============================================
+
+  DOC
+
+  # Initialize coverage model
+  # Using the built-in coverage data from running specs
+  model = CovLoupe::CoverageModel.new(
+    root: '.',
+    resultset: 'spec/fixtures/project1/coverage'
+  )
+
+  puts <<~DOC
+    ## 1. Full Coverage Table
+    ```
+    #{model.format_table}
+    ```
+
+  DOC
+
+  puts <<~DOC
+    ## 2. Filter by Directory (lib/ only)
+    ```ruby
+    # Filter files by directory (e.g., only show files in lib/)
+    files_data = model.list['files']
+    lib_files = files_data.select { |file| file["file"].include?("/lib/") }
+    lib_files_table = model.format_table(lib_files)
+    # => formatted table showing only files from lib/ directory
+    ```
+
+  DOC
+
+  # Execute the code
+  files_data = model.list['files']
+  lib_files = files_data.select { |file| file['file'].include?('/lib/') }
+  lib_files_table = model.format_table(lib_files)
+  puts <<~DOC
+    Result:
+    ```
+    #{lib_files_table}
+    ```
+
+  DOC
+
+  puts <<~DOC
+    ## 3. Filter by Pattern (files with specific naming)
+    ```ruby
+    # Filter by pattern (e.g., only show files with "foo" in name)
+    # Note: files_data is the array from model.list['files']
+    foo_files = files_data.select { |file| file["file"].include?("foo") }
+    foo_table = model.format_table(foo_files)
+    # => formatted table showing only files with 'foo' in filename
+    ```
+
+  DOC
+
+  # Execute the code
+  foo_files = files_data.select { |file| file['file'].include?('foo') }
+  foo_table = model.format_table(foo_files)
+  puts <<~DOC
+    Result:
+    ```
+    #{foo_table}
+    ```
+
+  DOC
+
+  puts <<~DOC
+    ## 4. Filter by Coverage Threshold (only high-coverage files)
+    ```ruby
+    # Filter by coverage percentage (e.g., only files >= 50% coverage)
+    # Note: files_data is the array from model.list['files']
+    high_coverage_files = files_data.select { |file| file["percentage"] >= 50.0 }
+    high_coverage_table = model.format_table(high_coverage_files)
+    # => formatted table showing only well-covered files
+    ```
+
+  DOC
+
+  # Execute the code
+  high_coverage_files = files_data.select { |file| file['percentage'] >= 50.0 }
+  high_coverage_table = model.format_table(high_coverage_files)
+  puts <<~DOC
+    Result:
+    ```
+    #{high_coverage_table}
+    ```
+
+  DOC
+
+  puts <<~DOC
+    ## 5. Staleness Analysis
+    ```ruby
+    # Analyze coverage staleness to find potentially problematic files
+    # Note: files_data is the array from model.list['files']
+    stale_files, healthy_files = files_data.partition { |file| file["stale"] }
+
+    puts "## Potentially Stale Coverage Files"
+    puts model.format_table(stale_files, sort_order: :descending)
+
+    puts "## Healthy Coverage Files"
+    puts model.format_table(healthy_files, sort_order: :descending)
+    ```
+
+  DOC
+
+  # Execute the stale analysis
+  stale_files, healthy_files = files_data.partition { |file| file['stale'] }
+
+  puts 'Result:'
+  puts '```'
+  puts '## Potentially Stale Coverage Files'
+  puts model.format_table(stale_files, sort_order: :descending) if stale_files.any?
+  puts '(No stale files found)' if stale_files.empty?
+  puts
+  puts '## Healthy Coverage Files'
+  puts model.format_table(healthy_files, sort_order: :descending) if healthy_files.any?
+  puts '(No healthy files found)' if healthy_files.empty?
+  puts '```'
+  puts
+  puts 'NOTE: To see staleness analysis in action with both stale and healthy files,'
+  puts 'try modifying file timestamps:'
+  puts '  - Make one file appear older: `touch -t 202401010000 spec/fixtures/project1/lib/foo.rb`'
+  puts '  - Or make one file appear newer: `touch spec/fixtures/project1/lib/bar.rb`'
+  puts 'Then run this script again to see partition results change.'
+  puts
+
+  puts <<~DOC
+    ## Summary
+    This example demonstrates how cov-loupe can be used as a library to:
+    - Load and query coverage data
+    - Filter files by various criteria (directory, filename, coverage threshold)
+    - Perform staleness analysis to identify potentially problematic files
+    - Generate CI/CD integration reports with exit codes for monitoring
+    - Create custom reports tailored to specific needs
+
+    The table formatting functionality (format_table) is now accessible
+    directly in library mode, not just through the CLI!
+  DOC
+end
+
+def main
+  check_coverage_data
+  output_examples
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/fixtures/demo_project/coverage/.resultset.json

@@ -0,0 +1,10 @@
+{
+  "RSpec": {
+    "timestamp": 1720000000,
+    "coverage": {
+      "lib/foo.rb": { "lines": [1, 0, null, 2] },
+      "lib/bar.rb": { "lines": [0, 0, 1] }
+    }
+  }
+}
+