cov-loupe 3.0.0

data/spec/MCP_INTEGRATION_TESTS_README.md

@@ -0,0 +1,111 @@
+# MCP Server Protocol Integration Tests
+
+## Overview
+
+This document describes the comprehensive integration tests added for the SimpleCov MCP server protocol in `spec/integration_spec.rb`.
+
+## Test Coverage
+
+The integration tests spawn the actual MCP server as a subprocess and communicate with it via JSON-RPC over stdio, testing the complete end-to-end protocol implementation.
+
+### Tests Added (12 total)
+
+1. **starts MCP server without errors** - Verifies the server starts and responds to basic requests without NameError or other initialization issues
+2. **handles tools/list request** - Confirms all 8 expected tools are properly registered
+3. **executes coverage_summary_tool via JSON-RPC** - Tests single-file coverage summary queries
+4. **executes all_files_coverage_tool via JSON-RPC** - Tests project-wide coverage listing
+5. **executes uncovered_lines_tool via JSON-RPC** - Tests uncovered line detection
+6. **executes help_tool via JSON-RPC** - Tests help/documentation retrieval
+7. **executes version_tool via JSON-RPC** - Tests version information queries
+8. **handles error responses for invalid tool calls** - Verifies graceful error handling
+9. **handles malformed JSON-RPC requests** - Tests robustness against invalid input
+10. **respects --log-file configuration in MCP mode** - Tests logging configuration
+11. **prohibits stdout logging in MCP mode** - Ensures stdout isn't corrupted
+12. **handles multiple sequential requests** - Tests statelessness and multi-request handling
+
+## Why These Tests Are Critical
+
+### Issue #1 from Analysis: Missing `require 'optparse'`
+
+The critical bug (missing `require 'optparse'` in `lib/cov_loupe.rb:110`) was not caught by existing tests because:
+
+- Unit tests loaded the full gem which transitively required optparse through the CLI
+- MCP tools were tested in-process without spawning the server
+- No integration tests verified the MCP server startup sequence
+
+### What These Tests Catch
+
+* ✅ **Server Initialization Errors**: NameError, LoadError, missing requires
+* ✅ **Protocol Compliance**: Valid JSON-RPC request/response format
+* ✅ **Tool Registration**: All tools properly configured and accessible
+* ✅ **Data Accuracy**: Coverage data correctly passed from fixtures
+* ✅ **Error Handling**: Graceful responses for invalid requests
+* ✅ **Configuration**: Environment variables and options properly handled
+* ✅ **Statelessness**: Multiple requests handled independently
+* ✅ **Stream Integrity**: Stdout not corrupted by logging
+
+## Test Architecture
+
+### Helper Methods
+
+- **`run_mcp_request(request_hash, timeout: 5)`**: Spawns MCP server, sends JSON-RPC request, returns stdout/stderr/status
+- **`parse_jsonrpc_response(output)`**: Extracts JSON-RPC response from output (handles mixed stderr/stdout)
+
+### Test Fixtures
+
+Uses `spec/fixtures/project1/` with known coverage data:
+- `lib/foo.rb`: 66.67% coverage (2/3 lines, line 2 uncovered)
+- `lib/bar.rb`: 33.33% coverage (1/3 lines)
+
+### Test Execution
+
+```bash
+# Run all MCP integration tests
+bundle exec rspec spec/integration_spec.rb --tag slow
+
+# Run specific integration test
+bundle exec rspec spec/integration_spec.rb:363
+```
+
+## Performance
+
+- Total execution time: ~2.1 seconds for all 12 tests
+- Tagged with `:slow` to allow exclusion from quick test runs
+- Uses `Open3.popen3` for subprocess management
+- 5-second timeout per request (configurable)
+
+## Coverage Impact
+
+These tests increased the overall test count from 272 to 284 examples and improved confidence in the MCP server mode, which is the primary use case for AI assistant integration.
+
+### Before Integration Tests
+- 272 examples
+- Missing `require 'optparse'` bug went undetected
+- MCP server mode untested end-to-end
+
+### After Integration Tests
+- 284 examples
+- MCP server startup verified
+- Full JSON-RPC protocol tested
+- Would catch Issue #1 immediately
+
+## Future Enhancements
+
+Potential additions:
+- Test connection lifecycle (startup, multiple sessions, shutdown)
+- Test concurrent requests (if supported)
+- Test large coverage datasets (performance)
+- Test network transport (if added)
+- Test authentication/authorization (if added)
+
+## Related Files
+
+- `spec/integration_spec.rb` - Main integration test file (lines 308-683)
+- `lib/cov_loupe.rb` - Entry point with mode detection
+- `lib/cov_loupe/mcp_server.rb` - MCP server implementation
+- `exe/cov-loupe` - Executable entry point
+
+## References
+
+- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)

data/spec/TIMESTAMPS.md

@@ -0,0 +1,48 @@
+# Test Timestamp Documentation
+
+This document explains the timestamp constants used throughout the test suite for consistent and documented test data.
+
+## Constants (defined in `spec_helper.rb`)
+
+### `FIXTURE_COVERAGE_TIMESTAMP = 1_720_000_000`
+- **Human readable**: 2024-07-03 16:26:40 UTC (July 3rd, 2024)
+- **Purpose**: The "generated" timestamp for coverage data in `spec/fixtures/project1/coverage/.resultset.json`
+- **Usage**: Used in tests that verify timestamp parsing and calculations with realistic coverage data
+
+### `VERY_OLD_TIMESTAMP = 0`
+- **Human readable**: 1970-01-01 00:00:00 UTC (Unix epoch)
+- **Purpose**: Simulates extremely stale coverage data (much older than any real file)
+- **Usage**: Used in staleness tests to force stale coverage scenarios
+
+### `TEST_FILE_TIMESTAMP = 1_000`
+- **Human readable**: 1970-01-01 00:16:40 UTC (16 minutes and 40 seconds after epoch)
+- **Purpose**: Used for stale error formatting tests to create predictable time deltas
+- **Usage**: Creates a 1000-second (16m 40s) difference from `VERY_OLD_TIMESTAMP` for delta calculations
+
+## Conversion Reference
+
+To convert timestamps for debugging:
+
+```bash
+# Unix timestamp to human readable
+date -d @1720000000
+# Wed Jul  3 16:26:40 UTC 2024
+
+# Human readable to Unix timestamp  
+date -d "2024-07-03 16:26:40 UTC" +%s
+# 1720000000
+```
+
+## Why These Values?
+
+- **Realistic but static**: `FIXTURE_COVERAGE_TIMESTAMP` is a realistic recent date that won't change
+- **Predictable deltas**: The differences between timestamps create predictable test scenarios
+- **Clear intent**: Named constants make it obvious what each timestamp represents in tests
+
+## Files Using These Constants
+
+- `spec/util_spec.rb` - Tests timestamp parsing from fixture
+- `spec/model_staleness_spec.rb` - Tests staleness detection logic
+- `spec/errors_stale_spec.rb` - Tests stale error message formatting
+- `spec/cli_error_spec.rb` - Tests CLI error handling for stale coverage
+- `spec/fixtures/project1/coverage/.resultset.json` - Contains the actual timestamp data

data/spec/all_files_coverage_tool_spec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'cov_loupe/tools/all_files_coverage_tool'
+
+RSpec.describe CovLoupe::Tools::AllFilesCoverageTool do
+  subject(:call_tool) { described_class.call(root: root, server_context: server_context) }
+
+  let(:root) { (FIXTURES_DIR / 'project1').to_s }
+  let(:server_context) { instance_double('ServerContext').as_null_object }
+
+  before do
+    setup_mcp_response_stub
+    model = instance_double(CovLoupe::CoverageModel)
+    allow(CovLoupe::CoverageModel).to receive(:new).and_return(model)
+
+    payload = {
+      'files' => [
+        { 'file' => 'lib/foo.rb', 'percentage' => 100.0, 'covered' => 10, 'total' => 10,
+          'stale' => false },
+        { 'file' => 'lib/bar.rb', 'percentage' => 50.0,  'covered' => 5,  'total' => 10,
+          'stale' => true }
+      ],
+      'counts' => { 'total' => 2, 'ok' => 1, 'stale' => 1 }
+    }
+
+    presenter = instance_double(CovLoupe::Presenters::ProjectCoveragePresenter)
+    allow(CovLoupe::Presenters::ProjectCoveragePresenter).to receive(:new).and_return(presenter)
+    allow(presenter).to receive(:relativized_payload).and_return(payload)
+  end
+
+
+  it_behaves_like 'an MCP tool that returns text JSON'
+
+  it 'returns all files coverage data with counts' do
+    response = call_tool
+    data, _item = expect_mcp_text_json(response, expected_keys: ['files', 'counts'])
+
+    files = data['files']
+    counts = data['counts']
+
+    expect(files.length).to eq(2)
+    expect(counts).to include('total' => 2).or include(total: 2)
+    expect(files.map { |f| f['file'] }).to eq(['lib/foo.rb', 'lib/bar.rb'])
+
+    # ok + stale equals total
+    ok = counts[:ok] || counts['ok']
+    stale = counts[:stale] || counts['stale']
+    total = counts[:total] || counts['total']
+    expect(ok + stale).to eq(total)
+    expect(stale).to eq(1)
+  end
+end

data/spec/app_config_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe CovLoupe::AppConfig do
+  describe '#initialize' do
+    it 'creates a config with default values' do
+      config = described_class.new
+      expect(config.root).to eq('.')
+      expect(config.format).to eq(:table)
+      expect(config.sort_order).to eq(:descending)
+      expect(config.source_context).to eq(2)
+      expect(config.error_mode).to eq(:log)
+      expect(config.staleness).to eq(:off)
+      expect(config.resultset).to be_nil
+      expect(config.source_mode).to be_nil
+      expect(config.tracked_globs).to be_nil
+      expect(config.log_file).to be_nil
+    end
+
+    it 'allows overriding defaults via keyword arguments' do
+      config = described_class.new(
+        root: '/custom',
+        format: :json,
+        sort_order: :descending,
+        staleness: :error
+      )
+      expect(config.root).to eq('/custom')
+      expect(config.format).to eq(:json)
+      expect(config.sort_order).to eq(:descending)
+      expect(config.staleness).to eq(:error)
+    end
+
+    it 'is mutable (struct fields can be changed)' do
+      config = described_class.new
+      config.root = '/new/root'
+      config.format = :json
+      expect(config.root).to eq('/new/root')
+      expect(config.format).to eq(:json)
+    end
+  end
+
+  describe '#model_options' do
+    it 'returns hash suitable for CoverageModel.new' do
+      config = described_class.new(
+        root: '/custom/root',
+        resultset: '/custom/.resultset.json',
+        staleness: :error,
+        tracked_globs: ['lib/**/*.rb']
+      )
+
+      options = config.model_options
+      expect(options).to eq({
+        root: '/custom/root',
+        resultset: '/custom/.resultset.json',
+        staleness: :error,
+        tracked_globs: ['lib/**/*.rb']
+      })
+    end
+
+    it 'handles nil values correctly' do
+      config = described_class.new
+      options = config.model_options
+      expect(options[:root]).to eq('.')
+      expect(options[:resultset]).to be_nil
+      expect(options[:staleness]).to eq(:off)
+      expect(options[:tracked_globs]).to be_nil
+    end
+  end
+
+  describe '#formatter_options' do
+    it 'returns hash suitable for SourceFormatter.new' do
+      config = described_class.new(color: true)
+      options = config.formatter_options
+      expect(options).to eq({ color_enabled: true })
+    end
+
+    it 'handles false color setting' do
+      config = described_class.new(color: false)
+      options = config.formatter_options
+      expect(options).to eq({ color_enabled: false })
+    end
+  end
+
+  describe 'struct behavior' do
+    it 'supports equality comparison' do
+      config1 = described_class.new(root: '/foo', format: :json)
+      config2 = described_class.new(root: '/foo', format: :json)
+      config3 = described_class.new(root: '/bar', format: :json)
+
+      expect(config1).to eq(config2)
+      expect(config1).not_to eq(config3)
+    end
+
+    it 'provides readable inspect output' do
+      config = described_class.new(root: '/test', format: :json)
+      output = config.inspect
+      expect(output).to include('root="/test"')
+      expect(output).to include('format=:json')
+    end
+
+    it 'converts to hash' do
+      config = described_class.new(root: '/test', format: :json)
+      hash = config.to_h
+      expect(hash).to be_a(Hash)
+      expect(hash[:root]).to eq('/test')
+      expect(hash[:format]).to eq(:json)
+    end
+  end
+
+  describe 'symbol enumerated values' do
+    it 'uses symbols for format' do
+      config = described_class.new(format: :json)
+      expect(config.format).to eq(:json)
+      expect(config.format).to be_a(Symbol)
+    end
+
+    it 'uses symbols for sort_order' do
+      config = described_class.new(sort_order: :descending)
+      expect(config.sort_order).to eq(:descending)
+      expect(config.sort_order).to be_a(Symbol)
+    end
+
+    it 'uses symbols for staleness' do
+      config = described_class.new(staleness: :error)
+      expect(config.staleness).to eq(:error)
+      expect(config.staleness).to be_a(Symbol)
+    end
+
+    it 'uses symbols for error_mode' do
+      config = described_class.new(error_mode: :debug)
+      expect(config.error_mode).to eq(:debug)
+      expect(config.error_mode).to be_a(Symbol)
+    end
+
+    it 'uses symbols for source_mode' do
+      config = described_class.new(source_mode: :uncovered)
+      expect(config.source_mode).to eq(:uncovered)
+      expect(config.source_mode).to be_a(Symbol)
+    end
+  end
+end

data/spec/base_tool_spec.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe CovLoupe::BaseTool do
+  let(:handler) { CovLoupe::ErrorHandler.new(error_mode: :log, logger: test_logger) }
+  let(:test_logger) do
+    Class.new do
+      attr_reader :messages
+
+      def initialize = @messages = []
+      def error(msg) = @messages << msg
+    end.new
+  end
+
+  let(:orig_handler) do
+    CovLoupe.error_handler
+  rescue
+    nil
+  end
+
+  before do
+    CovLoupe.error_handler = handler
+    setup_mcp_response_stub
+  end
+
+  after do
+    CovLoupe.error_handler = orig_handler if orig_handler
+  end
+
+  shared_examples 'friendly response and logged' do
+    it 'returns friendly text' do
+      resp = described_class.handle_mcp_error(error, tool, error_mode: :log)
+      expect(resp).to be_a(MCP::Tool::Response)
+      expect(resp.payload.first['text']).to match(expected_pattern)
+    end
+
+    it 'respects error_mode :off' do
+      resp = described_class.handle_mcp_error(error, tool, error_mode: :off)
+      expect(resp).to be_a(MCP::Tool::Response)
+      expect(resp.payload.first['text']).to match(expected_pattern)
+    end
+  end
+
+  context 'with CovLoupe::Error' do
+    let(:error) { CovLoupe::UsageError.new('invalid args') }
+    let(:tool) { 'coverage_summary' }
+    let(:expected_pattern) { /Error: invalid args/ }
+    let(:log_fragment) { 'invalid args' }
+
+    it_behaves_like 'friendly response and logged'
+  end
+
+  context 'with standard error' do
+    let(:error) { Errno::ENOENT.new('No such file or directory @ rb_sysopen - missing.rb') }
+    let(:tool) { 'coverage_raw' }
+    let(:expected_pattern) { /Error: .*File not found: missing.rb/ }
+    let(:log_fragment) { 'File not found' }
+
+    it_behaves_like 'friendly response and logged'
+  end
+end

data/spec/cli/show_default_report_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe CovLoupe::CoverageCLI do
+  let(:root) { (FIXTURES_DIR / 'project1').to_s }
+  let(:cli) { described_class.new }
+
+  before do
+    cli.config.root = root
+    cli.config.resultset = 'coverage'
+    cli.config.staleness = :off
+    cli.config.tracked_globs = nil
+  end
+
+  describe '#show_default_report' do
+    it 'prints JSON summary using relativized payload when json mode is enabled' do
+      cli.config.format = :json
+
+      output = nil
+      silence_output do |stdout, _stderr|
+        cli.show_default_report(sort_order: :ascending, output: stdout)
+        output = stdout.string
+      end
+
+      payload = JSON.parse(output)
+
+      expect(payload['files']).to be_an(Array)
+      expect(payload['files'].first['file']).to eq('lib/bar.rb').or eq('lib/foo.rb')
+      expect(payload['counts']).to include('total', 'ok', 'stale')
+    end
+  end
+end

data/spec/cli_enumerated_options_spec.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'CLI enumerated option parsing' do
+  def parse!(argv)
+    cli = CovLoupe::CoverageCLI.new
+    cli.send(:parse_options!, argv.dup)
+    cli
+  end
+
+  describe 'accepts short and long forms' do
+    cases = [
+      { argv: ['--sort-order', 'a', 'list'], accessor: :sort_order, expected: :ascending },
+      { argv: ['--sort-order', 'd', 'list'], accessor: :sort_order, expected: :descending },
+      { argv: ['--sort-order', 'ascending', 'list'], accessor: :sort_order, expected: :ascending },
+      { argv: ['--sort-order', 'descending', 'list'], accessor: :sort_order,
+        expected: :descending },
+
+      { argv: ['--source', 'f', 'summary', 'lib/foo.rb'], accessor: :source_mode, expected: :full },
+      { argv: ['--source', 'u', 'summary', 'lib/foo.rb'], accessor: :source_mode,
+        expected: :uncovered },
+      { argv: ['--source', 'full', 'summary', 'lib/foo.rb'], accessor: :source_mode,
+        expected: :full },
+      { argv: ['--source', 'uncovered', 'summary', 'lib/foo.rb'], accessor: :source_mode,
+        expected: :uncovered },
+
+      { argv: ['-S', 'e', 'list'], accessor: :staleness, expected: :error },
+      { argv: ['-S', 'o', 'list'], accessor: :staleness, expected: :off },
+      { argv: ['--staleness', 'e', 'list'], accessor: :staleness, expected: :error },
+      { argv: ['--staleness', 'o', 'list'], accessor: :staleness, expected: :off },
+
+      { argv: ['--error-mode', 'off', 'list'], accessor: :error_mode, expected: :off },
+      { argv: ['--error-mode', 'o', 'list'], accessor: :error_mode, expected: :off },
+      { argv: ['--error-mode', 'log', 'list'], accessor: :error_mode, expected: :log },
+      { argv: ['--error-mode', 'debug', 'list'], accessor: :error_mode, expected: :debug }
+    ]
+
+    cases.each do |c|
+      it "parses #{c[:argv].join(' ')}" do
+        cli = parse!(c[:argv])
+        expect(cli.config.public_send(c[:accessor])).to eq(c[:expected])
+      end
+    end
+  end
+
+  describe 'rejects invalid values' do
+    invalid_cases = [
+      { argv: ['--sort-order', 'asc', 'list'] },
+      { argv: ['--source', 'x', 'summary', 'lib/foo.rb'] },
+      { argv: ['-S', 'x', 'list'] },
+      { argv: ['--staleness', 'x', 'list'] },
+      { argv: ['--error-mode', 'bad', 'list'] },
+      { argv: ['--error-mode', 'on', 'list'] },
+      { argv: ['--error-mode', 'trace', 'list'] }
+    ]
+
+    invalid_cases.each do |c|
+      it "exits 1 for #{c[:argv].join(' ')}" do
+        _out, err, status = run_cli_with_status(*c[:argv])
+        expect(status).to eq(1)
+        expect(err).to include('Error:')
+        expect(err).to include('invalid argument')
+      end
+    end
+  end
+
+  describe 'missing value hints' do
+    it 'exits 1 when -S is provided without a value' do
+      _out, err, status = run_cli_with_status('-S', 'list')
+      expect(status).to eq(1)
+      expect(err).to include('invalid argument')
+    end
+
+    it 'exits 1 when --staleness is provided without a value' do
+      _out, err, status = run_cli_with_status('--staleness', 'list')
+      expect(status).to eq(1)
+      expect(err).to include('invalid argument')
+    end
+
+    it 'exits 1 when --source is provided without a value' do
+      _out, err, status = run_cli_with_status('--source', 'summary', 'lib/foo.rb')
+      expect(status).to eq(1)
+      # Depending on OptParse implementation for required argument, it might say "missing argument"
+      # But usually it consumes next arg. If 'summary' is consumed as argument for source:
+      # normalize_source_mode('summary') -> raises InvalidArgument.
+      expect(err).to include('invalid argument')
+    end
+  end
+end