simplecov-mcp 1.0.1 → 2.0.1

data/spec/simplecov_mcp_model_spec.rb

@@ -3,15 +3,17 @@
 require 'spec_helper'
 
 RSpec.describe SimpleCovMcp::CoverageModel do
-  let(:root) { (FIXTURES_DIR / 'project1').to_s }
   subject(:model) { described_class.new(root: root) }
 
+  let(:root) { (FIXTURES_DIR / 'project1').to_s }
+
+
   describe 'initialization error handling' do
     it 'raises FileError when File.read raises Errno::ENOENT directly' do
       # Stub find_resultset to return a path, but File.read to raise ENOENT
       allow(SimpleCovMcp::CovUtil).to receive(:find_resultset)
         .and_return('/some/path/.resultset.json')
-      allow(File).to receive(:read).with('/some/path/.resultset.json')
+      allow(JSON).to receive(:load_file).with('/some/path/.resultset.json')
         .and_raise(Errno::ENOENT, 'No such file')
 
       expect do
@@ -35,11 +37,11 @@ RSpec.describe SimpleCovMcp::CoverageModel do
   end
 
   describe 'summary_for' do
-    it 'computes covered/total/pct' do
+    it 'computes covered/total/percentage' do
       data = model.summary_for('lib/foo.rb')
       expect(data['summary']['total']).to eq(3)
       expect(data['summary']['covered']).to eq(2)
-      expect(data['summary']['pct']).to be_within(0.01).of(66.67)
+      expect(data['summary']['percentage']).to be_within(0.01).of(66.67)
     end
   end
 
@@ -75,35 +77,46 @@ RSpec.describe SimpleCovMcp::CoverageModel do
 
   describe 'staleness_for' do
     it 'returns the staleness character for a file' do
-      allow_any_instance_of(SimpleCovMcp::StalenessChecker)
-        .to receive(:stale_for_file?) do |_, file_abs, _|
-          if file_abs == File.expand_path('lib/foo.rb', root)
-            'T'
-          else
-            false
-          end
+      checker = instance_double(SimpleCovMcp::StalenessChecker, off?: false)
+      allow(SimpleCovMcp::StalenessChecker).to receive(:new).and_return(checker)
+      allow(checker).to receive(:stale_for_file?) do |file_abs, _|
+        if file_abs == File.expand_path('lib/foo.rb', root)
+          'T'
+        else
+          false
         end
+      end
 
       expect(model.staleness_for('lib/foo.rb')).to eq('T')
-      expect(model.staleness_for('lib/bar.rb')).to eq(false)
+      expect(model.staleness_for('lib/bar.rb')).to be(false)
     end
 
     it 'returns false when an exception occurs during staleness check' do
       # Stub the checker to raise an error
-      allow_any_instance_of(SimpleCovMcp::StalenessChecker).to receive(:stale_for_file?)
+      checker = instance_double(SimpleCovMcp::StalenessChecker, off?: false)
+      allow(SimpleCovMcp::StalenessChecker).to receive(:new).and_return(checker)
+      allow(checker).to receive(:stale_for_file?)
         .and_raise(StandardError, 'Something went wrong')
 
       # The rescue clause should catch the error and return false
-      expect(model.staleness_for('lib/foo.rb')).to eq(false)
+      expect(model.staleness_for('lib/foo.rb')).to be(false)
     end
 
     it 'returns false when coverage data is not found for the file' do
       # Try to get staleness for a file that doesn't exist in coverage
-      expect(model.staleness_for('lib/nonexistent.rb')).to eq(false)
+      expect(model.staleness_for('lib/nonexistent.rb')).to be(false)
     end
   end
 
   describe 'all_files' do
+    it 'sorts descending (default) by percentage then by file path' do
+      files = model.all_files
+      # lib/foo.rb has 66.67%, lib/bar.rb has 33.33%
+      expect(files.first['file']).to eq(File.expand_path('lib/foo.rb', root))
+      expect(files.first['percentage']).to be_within(0.01).of(66.67)
+      expect(files.last['file']).to eq(File.expand_path('lib/bar.rb', root))
+    end
+
     it 'sorts ascending by percentage then by file path' do
       files = model.all_files(sort_order: :ascending)
       expect(files.first['file']).to eq(File.expand_path('lib/bar.rb', root))
@@ -151,6 +164,24 @@ RSpec.describe SimpleCovMcp::CoverageModel do
     end
   end
 
+  describe '#project_totals' do
+    it 'aggregates coverage totals across all files' do
+      totals = model.project_totals
+
+      expect(totals['lines']).to include('total' => 6, 'covered' => 3, 'uncovered' => 3)
+      expect(totals['percentage']).to be_within(0.01).of(50.0)
+      expect(totals['files']).to include('total' => 2)
+      expect(totals['files']['ok'] + totals['files']['stale']).to eq(totals['files']['total'])
+    end
+
+    it 'respects tracked_globs filtering' do
+      totals = model.project_totals(tracked_globs: ['lib/foo.rb'])
+
+      expect(totals['lines']).to include('total' => 3, 'covered' => 2, 'uncovered' => 1)
+      expect(totals['files']).to include('total' => 1)
+    end
+  end
+
   describe 'resolve method error handling' do
     it 'raises FileError when coverage_lines is nil after lookup' do
       # Stub lookup_lines to return nil without raising
@@ -164,16 +195,27 @@ RSpec.describe SimpleCovMcp::CoverageModel do
     it 'converts Errno::ENOENT to FileNotFoundError during resolve' do
       # We need to trigger Errno::ENOENT inside the resolve method
       # Stub the checker's check_file! method to raise Errno::ENOENT
-      allow_any_instance_of(SimpleCovMcp::StalenessChecker).to receive(:check_file!)
+      checker = instance_double(SimpleCovMcp::StalenessChecker, off?: false)
+      allow(SimpleCovMcp::StalenessChecker).to receive(:new).and_return(checker)
+      allow(checker).to receive(:check_file!)
         .and_raise(Errno::ENOENT, 'No such file or directory')
 
       # Create a model with staleness checking enabled to trigger the check_file! call
-      stale_model = described_class.new(root: root, staleness: 'error')
+      stale_model = described_class.new(root: root, staleness: :error)
 
       expect do
         stale_model.summary_for('lib/foo.rb')
       end.to raise_error(SimpleCovMcp::FileNotFoundError, /File not found/)
     end
+
+    it 'raises FileError when lookup_lines raises RuntimeError' do
+      allow(SimpleCovMcp::CovUtil).to receive(:lookup_lines)
+        .and_raise(RuntimeError, 'Could not find coverage data')
+
+      expect do
+        model.summary_for('lib/some_file.rb')
+      end.to raise_error(SimpleCovMcp::FileError, /No coverage data found for file/)
+    end
   end
 
   describe 'resultset directory handling' do
@@ -194,7 +236,7 @@ RSpec.describe SimpleCovMcp::CoverageModel do
 
       expect(data['summary']['total']).to eq(5)
       expect(data['summary']['covered']).to eq(3)
-      expect(data['summary']['pct']).to be_within(0.01).of(60.0)
+      expect(data['summary']['percentage']).to be_within(0.01).of(60.0)
     end
 
     it 'returns detailed data using branch-derived hits' do
@@ -234,6 +276,40 @@ RSpec.describe SimpleCovMcp::CoverageModel do
 
   describe 'multiple suites in resultset' do
     let(:resultset_path) { '/tmp/multi_suite_resultset.json' }
+    let(:suite_a_cov) do
+      {
+        File.join(root, 'lib', 'foo.rb') => { 'lines' => [1, 0, nil, 2] }
+      }
+    end
+    let(:suite_b_cov) do
+      {
+        File.join(root, 'lib', 'bar.rb') => { 'lines' => [0, 1, 1] }
+      }
+    end
+    let(:resultset) do
+      {
+        'RSpec' => { 'timestamp' => 100, 'coverage' => suite_a_cov },
+        'Cucumber' => { 'timestamp' => 200, 'coverage' => suite_b_cov }
+      }
+    end
+
+    let(:shared_file) { File.join(root, 'lib', 'foo.rb') }
+    let(:suite_a_cov_combined) do
+      {
+        shared_file => { 'lines' => [1, 0, nil, 0] }
+      }
+    end
+    let(:suite_b_cov_combined) do
+      {
+        shared_file => { 'lines' => [0, 3, nil, 1] }
+      }
+    end
+    let(:resultset_combined) do
+      {
+        'RSpec' => { 'timestamp' => 100, 'coverage' => suite_a_cov_combined },
+        'Cucumber' => { 'timestamp' => 150, 'coverage' => suite_b_cov_combined }
+      }
+    end
 
     before do
       allow(SimpleCovMcp::CovUtil).to receive(:find_resultset).and_wrap_original do
@@ -246,23 +322,11 @@ RSpec.describe SimpleCovMcp::CoverageModel do
           original.call(search_root, resultset: resultset)
         end
       end
-      allow(File).to receive(:read).and_call_original
+      # This line might need to be removed as we now mock JSON.load_file directly
     end
 
     it 'merges coverage data from multiple suites while keeping latest timestamp' do
-      suite_a_cov = {
-        File.join(root, 'lib', 'foo.rb') => { 'lines' => [1, 0, nil, 2] }
-      }
-      suite_b_cov = {
-        File.join(root, 'lib', 'bar.rb') => { 'lines' => [0, 1, 1] }
-      }
-
-      resultset = {
-        'RSpec' => { 'timestamp' => 100, 'coverage' => suite_a_cov },
-        'Cucumber' => { 'timestamp' => 200, 'coverage' => suite_b_cov }
-      }
-
-      allow(File).to receive(:read).with(resultset_path).and_return(resultset.to_json)
+      allow(JSON).to receive(:load_file).with(resultset_path).and_return(resultset)
 
       model = described_class.new(root: root)
       files = model.all_files(sort_order: :ascending)
@@ -274,20 +338,7 @@ RSpec.describe SimpleCovMcp::CoverageModel do
     end
 
     it 'combines coverage arrays when the same file appears in multiple suites' do
-      shared_file = File.join(root, 'lib', 'foo.rb')
-      suite_a_cov = {
-        shared_file => { 'lines' => [1, 0, nil, 0] }
-      }
-      suite_b_cov = {
-        shared_file => { 'lines' => [0, 3, nil, 1] }
-      }
-
-      resultset = {
-        'RSpec' => { 'timestamp' => 100, 'coverage' => suite_a_cov },
-        'Cucumber' => { 'timestamp' => 150, 'coverage' => suite_b_cov }
-      }
-
-      allow(File).to receive(:read).with(resultset_path).and_return(resultset.to_json)
+      allow(JSON).to receive(:load_file).with(resultset_path).and_return(resultset_combined)
 
       model = described_class.new(root: root)
       detailed = model.detailed_for('lib/foo.rb')
@@ -367,7 +418,6 @@ RSpec.describe SimpleCovMcp::CoverageModel do
 
     it 'accepts sort_order parameter' do
       # Test that sort_order parameter is passed through correctly
-      rows_desc = model.all_files(sort_order: :descending)
       output_asc = model.format_table(sort_order: :ascending)
       output_desc = model.format_table(sort_order: :descending)
 

data/spec/simplecov_mcp_opts_spec.rb

@@ -14,42 +14,45 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
 
   describe 'CLI option parsing from environment' do
     it 'parses simple options from SIMPLECOV_MCP_OPTS' do
-      ENV['SIMPLECOV_MCP_OPTS'] = '--error-mode off --json'
+      ENV['SIMPLECOV_MCP_OPTS'] = '--error-mode off --format json'
+      env_opts = SimpleCovMcp.send(:extract_env_opts)
 
-      begin
-        silence_output { cli.send(:run, ['summary', 'lib/foo.rb']) }
-      rescue Exception => e
-        # Expected to fail due to missing file, but options should be parsed
-        puts "DEBUG: Caught exception: #{e.class}: #{e.message}" if ENV['DEBUG']
+      swallow_system_exit do
+        silence_output do
+          cli.send(:run, env_opts + ['summary', 'lib/foo.rb'])
+        end
       end
-
+    rescue SimpleCovMcp::Error => e
+      # Expected to fail due to missing file, but options should be parsed
+      puts "DEBUG: Caught exception: #{e.class}: #{e.message}" if ENV['DEBUG']
+    ensure
       expect(cli.config.error_mode).to eq(:off)
-      expect(cli.config.json).to be true
+      expect(cli.config.format).to eq(:json)
     end
 
     it 'handles quoted options with spaces' do
       test_path = File.join(Dir.tmpdir, 'test path with spaces', '.resultset.json')
       ENV['SIMPLECOV_MCP_OPTS'] = "--resultset \"#{test_path}\""
+      env_opts = SimpleCovMcp.send(:extract_env_opts)
 
-      # Stub exit method to prevent process termination
-      allow_any_instance_of(Object).to receive(:exit)
-
-      # silence_output captures the expected error message from the CLI trying to
-      # load the (non-existent) resultset, preventing it from leaking to the console.
-      silence_output do
-        cli.send(:run, ['--help'])
+      exit_status = swallow_system_exit do
+        silence_output do
+          cli.send(:run, env_opts + ['--help'])
+        end
       end
 
+      expect(exit_status).to eq(0) # --help exits cleanly
       expect(cli.config.resultset).to eq(test_path)
     end
 
     it 'supports setting log-file to stdout from environment' do
       ENV['SIMPLECOV_MCP_OPTS'] = '--log-file stdout'
+      env_opts = SimpleCovMcp.send(:extract_env_opts)
 
-      allow_any_instance_of(Object).to receive(:exit)
-
-      silence_output do
-        cli.send(:run, ['--help'])
+      swallow_system_exit do
+        silence_output do
+          cli.send(:run, env_opts + ['--help'])
+        end
       end
 
       expect(cli.config.log_file).to eq('stdout')
@@ -57,15 +60,17 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
 
     it 'command line arguments override environment options' do
       ENV['SIMPLECOV_MCP_OPTS'] = '--error-mode off'
+      env_opts = SimpleCovMcp.send(:extract_env_opts)
 
       begin
-        silence_output { cli.send(:run, ['--error-mode', 'trace', 'summary', 'lib/foo.rb']) }
+        args = env_opts + ['--error-mode', 'debug', 'summary', 'lib/foo.rb']
+        silence_output { cli.send(:run, args) }
       rescue SystemExit, SimpleCovMcp::Error
         # Expected to fail, but options should be parsed
       end
 
       # Command line should override environment
-      expect(cli.config.error_mode).to eq(:trace)
+      expect(cli.config.error_mode).to eq(:debug)
     end
 
     it 'handles malformed SIMPLECOV_MCP_OPTS gracefully' do
@@ -78,13 +83,13 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
 
     it 'returns empty array when SIMPLECOV_MCP_OPTS is not set' do
       # ENV is already cleared by around block
-      opts = cli.send(:parse_env_opts)
+      opts = SimpleCovMcp.send(:extract_env_opts)
       expect(opts).to eq([])
     end
 
     it 'returns empty array when SIMPLECOV_MCP_OPTS is empty' do
       ENV['SIMPLECOV_MCP_OPTS'] = ''
-      opts = cli.send(:parse_env_opts)
+      opts = SimpleCovMcp.send(:extract_env_opts)
       expect(opts).to eq([])
     end
   end
@@ -96,7 +101,7 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
       # This would normally be MCP mode (no TTY, no subcommand)
       stdin = double('stdin', tty?: false)
 
-      env_opts = SimpleCovMcp.send(:parse_env_opts_for_mode_detection)
+      env_opts = SimpleCovMcp.send(:extract_env_opts)
       full_argv = env_opts + []
 
       expect(SimpleCovMcp::ModeDetector.cli_mode?(full_argv, stdin: stdin)).to be true
@@ -106,7 +111,7 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
       ENV['SIMPLECOV_MCP_OPTS'] = '--option "unclosed quote'
 
       # Should return empty array and not crash
-      opts = SimpleCovMcp.send(:parse_env_opts_for_mode_detection)
+      opts = SimpleCovMcp.send(:extract_env_opts)
       expect(opts).to eq([])
     end
 
@@ -114,15 +119,14 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
       ENV['SIMPLECOV_MCP_OPTS'] = '--force-cli'
 
       # Mock STDIN to not be a TTY (would normally trigger MCP server mode)
-      allow(STDIN).to receive(:tty?).and_return(false)
-
-      # Stub exit to prevent process termination
-      allow_any_instance_of(Object).to receive(:exit)
+      allow($stdin).to receive(:tty?).and_return(false)
 
       # Run with --help which should produce help output
       output = nil
       silence_output do |out, err|
-        SimpleCovMcp.run(['--help'])
+        swallow_system_exit do
+          SimpleCovMcp.run(['--help'])
+        end
         output = out.string + err.string
       end
 
@@ -135,7 +139,7 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
       ENV['SIMPLECOV_MCP_OPTS'] = ''
 
       # Mock STDIN to not be a TTY and to provide valid JSON-RPC
-      allow(STDIN).to receive(:tty?).and_return(false)
+      allow($stdin).to receive(:tty?).and_return(false)
 
       # Provide a minimal JSON-RPC request that the server can handle
       json_request = JSON.generate({
@@ -149,7 +153,7 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
         }
       })
 
-      allow(STDIN).to receive(:gets).and_return(json_request, nil)
+      allow($stdin).to receive(:gets).and_return(json_request, nil)
 
       # Capture output to verify MCP server response
       output = nil
@@ -167,16 +171,15 @@ RSpec.describe 'SIMPLECOV_MCP_OPTS Environment Variable' do
   describe 'integration with actual CLI usage' do
     it 'works end-to-end with --resultset option' do
       test_resultset = File.join(Dir.tmpdir, 'test_coverage', '.resultset.json')
-      ENV['SIMPLECOV_MCP_OPTS'] = "--resultset #{test_resultset} --json"
-
-      allow_any_instance_of(Object).to receive(:exit)
+      ENV['SIMPLECOV_MCP_OPTS'] = "--resultset #{test_resultset} --format json"
+      env_opts = SimpleCovMcp.send(:extract_env_opts)
 
-      expect do
-        silence_output { cli.send(:run, ['--help']) }
-      end.not_to raise_error
+      swallow_system_exit do
+        silence_output { cli.send(:run, env_opts + ['--help']) }
+      end
 
       expect(cli.config.resultset).to eq(test_resultset)
-      expect(cli.config.json).to be true
+      expect(cli.config.format).to eq(:json)
     end
   end
 end

data/spec/spec_helper.rb

@@ -5,9 +5,17 @@ begin
   require 'simplecov'
   SimpleCov.start do
     enable_coverage :branch if SimpleCov.respond_to?(:enable_coverage)
-    add_filter %r{^/spec/}
+    add_filter(/^\/spec\//)
     track_files 'lib/**/*.rb'
   end
+
+  # Report lowest coverage files at the end of the test run
+  SimpleCov.at_exit do
+    SimpleCov.result.format!
+    require 'simplecov_mcp'
+    report = SimpleCovMcp::CoverageReporter.report(threshold: 80, count: 5)
+    puts report if report
+  end
 rescue LoadError
   warn 'SimpleCov not available; skipping coverage'
 end
@@ -57,14 +65,16 @@ def mock_resultset_with_metadata(root, metadata, coverage: nil)
     File.join(root, 'lib', 'bar.rb') => { 'lines' => [0, 0, 1] }
   }
 
-  fake_resultset = {
+  fake_resultset_hash = {
     'RSpec' => {
       'coverage' => coverage || default_coverage
     }.merge(metadata)
   }
 
-  allow(File).to receive(:read).and_call_original
-  allow(File).to receive(:read).with(end_with('.resultset.json')).and_return(fake_resultset.to_json)
+  allow(JSON).to receive(:load_file).and_call_original # Allow real JSON.load_file for other calls
+
+  allow(JSON).to receive(:load_file).with(end_with('.resultset.json'))
+    .and_return(fake_resultset_hash)
   allow(SimpleCovMcp::CovUtil).to receive(:find_resultset)
     .and_wrap_original do |method, search_root, resultset: nil|
     if File.absolute_path(search_root) == abs_root && (resultset.nil? || resultset.to_s.empty?)
@@ -76,8 +86,8 @@ def mock_resultset_with_metadata(root, metadata, coverage: nil)
 end
 
 # Automatically require all files in spec/support and spec/shared_examples
-Dir[File.join(__dir__, 'support', '**', '*.rb')].sort.each { |f| require f }
-Dir[File.join(__dir__, 'shared_examples', '**', '*.rb')].sort.each { |f| require f }
+Dir[File.join(__dir__, 'support', '**', '*.rb')].each { |f| require f }
+Dir[File.join(__dir__, 'shared_examples', '**', '*.rb')].each { |f| require f }
 
 RSpec.configure do |config|
   config.example_status_persistence_file_path = '.rspec_status'
@@ -85,107 +95,32 @@ RSpec.configure do |config|
   config.order = :defined
   Kernel.srand config.seed
 
-  # Suppress logging during tests by redirecting to a null device
-  SimpleCovMcp.default_log_file = File::NULL
-  SimpleCovMcp.active_log_file = File::NULL
-end
+  # Suppress logging during tests by redirecting to /dev/null
+  # This is cheap and doesn't break tests that verify logging behavior
+  SimpleCovMcp.default_log_file = 'stderr'
+  SimpleCovMcp.active_log_file = 'stderr'
 
-# Shared test helpers
-module TestIOHelpers
-  # Suppress stdout/stderr within the given block, yielding the StringIOs
-  def silence_output
-    original_stdout = $stdout
-    original_stderr = $stderr
-    $stdout = StringIO.new
-    $stderr = StringIO.new
-    yield $stdout, $stderr
-  ensure
-    $stdout = original_stdout
-    $stderr = original_stderr
+  # Reset log file after each test to ensure tests that change it don't pollute others
+  config.after do
+    SimpleCovMcp.active_log_file = File::NULL
   end
 
-  # Stub staleness checking to return a specific value
-  # @param value [String, false] The staleness value to return ('L', 'T', 'M', or false)
-  def stub_staleness_check(value)
-    checker_double = instance_double(SimpleCovMcp::StalenessChecker)
-    allow(checker_double).to receive_messages(stale_for_file?: value, off?: false)
-    allow(checker_double).to receive(:check_file!)
-    allow(SimpleCovMcp::StalenessChecker).to receive(:new).and_return(checker_double)
-  end
-end
-
-# CLI test helpers
-module CLITestHelpers
-  # Run CLI with the given arguments and return [stdout, stderr, exit_status]
-  def run_cli_with_status(*argv)
-    cli = SimpleCovMcp::CoverageCLI.new
-    status = nil
-    out_str = err_str = nil
-    silence_output do |out, err|
-      begin
-        cli.run(argv.flatten)
-        status = 0
-      rescue SystemExit => e
-        status = e.status
-      end
-      out_str = out.string
-      err_str = err.string
-    end
-    [out_str, err_str, status]
-  end
-end
-
-# MCP Tool shared examples and helpers
-module MCPToolTestHelpers
-  def setup_mcp_response_stub
-    # Standardized MCP::Tool::Response stub that works for all tools
-    response_class = Class.new do
-      attr_reader :payload, :meta
-
-      def initialize(payload, meta: nil)
-        @payload = payload
-        @meta = meta
-      end
-    end
-    stub_const('MCP::Tool::Response', response_class)
-  end
-
-  def expect_mcp_text_json(response, expected_keys: [])
-    item = response.payload.first
-
-    # Check for a 'text' part
-    expect(item['type']).to eq('text')
-    expect(item).to have_key('text')
-
-    # Parse and validate JSON content
-    data = JSON.parse(item['text'])
-
-    # Check for expected keys
-    expected_keys.each do |key|
-      expect(data).to have_key(key)
-    end
-
-    [data, item] # Return for additional custom assertions
-  end
-end
-
-
-
-RSpec.configure do |config|
   config.include TestIOHelpers
   config.include CLITestHelpers
   config.include MCPToolTestHelpers
+  config.include MockingHelpers
+  config.include ControlFlowHelpers
 end
 
 # Custom matchers
 RSpec::Matchers.define :show_source_table_or_fallback do
   match do |output|
-    has_table_header = output.match?(/(^|\n)\s*Line\s+\|\s+Source/)
+    has_table_header = output.match?(/(^|\n)\s*Line\s*\|\s+Source/)
     has_fallback = output.include?('[source not available]')
     has_table_header || has_fallback
   end
 
-  failure_message do |output|
+  failure_message do |_output|
     "expected output to include a source table header (e.g., 'Line | Source') " \
       "or the fallback '[source not available]'"
   end

data/spec/staleness_checker_spec.rb

@@ -5,6 +5,7 @@ require 'fileutils'
 
 RSpec.describe SimpleCovMcp::StalenessChecker do
   let(:tmpdir) { Dir.mktmpdir('scmcp-stale') }
+
   after { FileUtils.remove_entry(tmpdir) if tmpdir && File.directory?(tmpdir) }
 
   def write_file(path, lines)
@@ -57,8 +58,8 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
     end
   end
 
-  context 'compute_file_staleness_details' do
-    include_examples 'a staleness check',
+  context 'when computing file staleness details' do
+    it_behaves_like 'a staleness check',
       description: 'detects newer file vs coverage timestamp',
       file_lines: ['a', 'b'],
       coverage_lines: [1, 1],
@@ -75,7 +76,7 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
       expected_stale_char: 'T',
       expected_error: SimpleCovMcp::CoverageDataStaleError
 
-    include_examples 'a staleness check',
+    it_behaves_like 'a staleness check',
       description: 'detects length mismatch between source and coverage',
       file_lines: ['a', 'b', 'c', 'd'],
       coverage_lines: [1, 1],
@@ -92,7 +93,7 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
       expected_stale_char: 'L',
       expected_error: SimpleCovMcp::CoverageDataStaleError
 
-    include_examples 'a staleness check',
+    it_behaves_like 'a staleness check',
       description: 'treats missing file as stale',
       file_lines: nil,
       coverage_lines: [1, 1, 1],
@@ -107,7 +108,7 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
       expected_stale_char: 'M',
       expected_error: SimpleCovMcp::CoverageDataStaleError
 
-    include_examples 'a staleness check',
+    it_behaves_like 'a staleness check',
       description: 'is not stale when timestamps and lengths match',
       file_lines: ['a', 'b', 'c'],
       coverage_lines: [1, 0, nil],
@@ -123,7 +124,7 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
       expected_error: nil
   end
 
-  context 'missing_trailing_newline? edge cases' do
+  context 'when handling missing_trailing_newline? edge cases' do
     let(:checker) do
       described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
     end
@@ -192,7 +193,7 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
     end
   end
 
-  context 'line count adjustment with missing trailing newline' do
+  context 'when adjusting line count with missing trailing newline' do
     let(:checker) do
       described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
     end
@@ -246,7 +247,7 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
     end
   end
 
-  context 'safe_count_lines edge cases' do
+  context 'when handling safe_count_lines edge cases' do
     let(:checker) do
       described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
     end
@@ -287,7 +288,7 @@ RSpec.describe SimpleCovMcp::StalenessChecker do
     end
   end
 
-  context 'rel method with path prefix mismatches' do
+  context 'when rel has path prefix mismatches' do
     let(:checker) do
       described_class.new(root: tmpdir, resultset: nil, mode: 'off', timestamp: Time.now)
     end