simplecov-mcp 1.0.0 → 2.0.0

data/spec/tools_error_handling_spec.rb

@@ -7,60 +7,30 @@ require 'simplecov_mcp/tools/coverage_summary_tool'
 require 'simplecov_mcp/tools/coverage_raw_tool'
 require 'simplecov_mcp/tools/uncovered_lines_tool'
 require 'simplecov_mcp/tools/coverage_detailed_tool'
+require 'simplecov_mcp/tools/coverage_totals_tool'
 
-RSpec.describe 'MCP Tool error handling' do
+RSpec.describe SimpleCovMcp::Tools do
   let(:server_context) { instance_double('ServerContext').as_null_object }
 
   before do
     setup_mcp_response_stub
   end
 
-  # Note: VersionTool error handling is difficult to test because the tool is so simple
+  # NOTE: VersionTool error handling is difficult to test because the tool is so simple
   # and doesn't have any complex logic that could fail. The rescue clause in the tool
   # exists for consistency with other tools but is unlikely to be triggered in practice.
 
   describe SimpleCovMcp::Tools::HelpTool do
-    it 'handles errors during query processing' do
-      # Simulate an error during filter_entries
-      allow(described_class).to receive(:filter_entries).and_raise(StandardError, 'Filter error')
+    it 'returns tool information without errors' do
+      response = described_class.call(error_mode: 'log', server_context: server_context)
 
-      response = described_class.call(query: 'test', error_mode: 'on',
-        server_context: server_context)
-
-      # Should return error response
       expect(response).to be_a(MCP::Tool::Response)
       item = response.payload.first
       expect(item[:type] || item['type']).to eq('text')
-      expect(item[:text] || item['text']).to include('Error')
-    end
-
-    it 'returns empty array when tokens are empty after filtering' do
-      # Test the edge case where query contains only non-word characters
-      response = described_class.call(query: '!!!', server_context: server_context)
-
-      data = JSON.parse(response.payload.first['text'])
-      # With empty tokens, should return all entries (no filtering applied)
-      expect(data['tools']).not_to be_empty
-    end
 
-    it 'handles non-string, non-array values in filter' do
-      # Test value_matches? with values that are neither strings nor arrays
-      # This exercises the 'else false' branch
-      allow(described_class).to receive(:format_entry).and_return({
-        'tool' => 'test_tool',
-        'label' => nil, # Neither string nor array
-        'use_when' => 123, # Neither string nor array
-        'avoid_when' => true, # Neither string nor array
-        'inputs' => {}, # Neither string nor array
-        'example' => 'example'
-      })
-
-      response = described_class.call(query: 'test', server_context: server_context)
-
-      # Should not crash, should return response
-      expect(response).to be_a(MCP::Tool::Response)
-      data = JSON.parse(response.payload.first['text'])
+      data = JSON.parse(item['text'])
       expect(data).to have_key('tools')
+      expect(data['tools']).not_to be_empty
     end
   end
 
@@ -70,7 +40,7 @@ RSpec.describe 'MCP Tool error handling' do
 
       response = described_class.call(
         path: 'lib/foo.rb',
-        error_mode: 'on',
+        error_mode: 'log',
         server_context: server_context
       )
 
@@ -78,7 +48,7 @@ RSpec.describe 'MCP Tool error handling' do
       expect(response).to be_a(MCP::Tool::Response)
       item = response.payload.first
       expect(item[:type] || item['type']).to eq('text')
-      expect(item[:text] || item['text']).to include('Error')
+      expect(item['text']).to include('Error')
     end
   end
 
@@ -88,9 +58,9 @@ RSpec.describe 'MCP Tool error handling' do
       allow(SimpleCovMcp::CoverageModel).to receive(:new).and_return(model)
       allow(model).to receive(:raw_for).and_raise(StandardError, 'Raw data error')
 
-      response = SimpleCovMcp::Tools::CoverageRawTool.call(
+      response = described_class.call(
         path: 'lib/foo.rb',
-        error_mode: 'on',
+        error_mode: 'log',
         server_context: server_context
       )
 
@@ -98,7 +68,7 @@ RSpec.describe 'MCP Tool error handling' do
       expect(response).to be_a(MCP::Tool::Response)
       item = response.payload.first
       expect(item[:type] || item['type']).to eq('text')
-      expect(item[:text] || item['text']).to include('Error')
+      expect(item['text']).to include('Error')
     end
   end
 
@@ -108,9 +78,9 @@ RSpec.describe 'MCP Tool error handling' do
       allow(SimpleCovMcp::CoverageModel).to receive(:new).and_return(model)
       allow(model).to receive(:uncovered_for).and_raise(StandardError, 'Uncovered error')
 
-      response = SimpleCovMcp::Tools::UncoveredLinesTool.call(
+      response = described_class.call(
         path: 'lib/foo.rb',
-        error_mode: 'on',
+        error_mode: 'log',
         server_context: server_context
       )
 
@@ -118,7 +88,7 @@ RSpec.describe 'MCP Tool error handling' do
       expect(response).to be_a(MCP::Tool::Response)
       item = response.payload.first
       expect(item[:type] || item['type']).to eq('text')
-      expect(item[:text] || item['text']).to include('Error')
+      expect(item['text']).to include('Error')
     end
   end
 
@@ -128,9 +98,9 @@ RSpec.describe 'MCP Tool error handling' do
       allow(SimpleCovMcp::CoverageModel).to receive(:new).and_return(model)
       allow(model).to receive(:detailed_for).and_raise(StandardError, 'Detailed error')
 
-      response = SimpleCovMcp::Tools::CoverageDetailedTool.call(
+      response = described_class.call(
         path: 'lib/foo.rb',
-        error_mode: 'on',
+        error_mode: 'log',
         server_context: server_context
       )
 
@@ -138,7 +108,23 @@ RSpec.describe 'MCP Tool error handling' do
       expect(response).to be_a(MCP::Tool::Response)
       item = response.payload.first
       expect(item[:type] || item['type']).to eq('text')
-      expect(item[:text] || item['text']).to include('Error')
+      expect(item['text']).to include('Error')
+    end
+  end
+
+  describe SimpleCovMcp::Tools::CoverageTotalsTool do
+    it 'handles errors during totals calculation' do
+      allow(SimpleCovMcp::CoverageModel).to receive(:new).and_raise(StandardError, 'Model error')
+
+      response = described_class.call(
+        error_mode: 'log',
+        server_context: server_context
+      )
+
+      expect(response).to be_a(MCP::Tool::Response)
+      item = response.payload.first
+      expect(item[:type] || item['type']).to eq('text')
+      expect(item['text']).to include('Error')
     end
   end
 end

data/spec/util_spec.rb

@@ -35,11 +35,12 @@ RSpec.describe SimpleCovMcp::CovUtil do
   end
 
   it 'summary handles edge cases and coercion' do
-    expect(described_class.summary([])).to include('pct' => 100.0, 'total' => 0, 'covered' => 0)
+    expect(described_class.summary([]))
+      .to include('percentage' => 100.0, 'total' => 0, 'covered' => 0)
     expect(described_class.summary([nil, nil]))
-      .to include('pct' => 100.0, 'total' => 0, 'covered' => 0)
+      .to include('percentage' => 100.0, 'total' => 0, 'covered' => 0)
     expect(described_class.summary(['1', '0', nil]))
-      .to include('pct' => 50.0, 'total' => 2, 'covered' => 1)
+      .to include('percentage' => 50.0, 'total' => 2, 'covered' => 1)
   end
 
   it 'uncovered and detailed ignore nils' do
@@ -65,7 +66,7 @@ RSpec.describe SimpleCovMcp::CovUtil do
   describe 'logging configuration' do
     let(:test_message) { 'test log message' }
 
-    around(:each) do |example|
+    around do |example|
       # Reset logging settings so each example starts clean.
       old_default = SimpleCovMcp.default_log_file
       old_active = SimpleCovMcp.active_log_file

data/spec/version_spec.rb

@@ -27,12 +27,12 @@ RSpec.describe 'SimpleCovMcp::VERSION' do
         (?<major>0|[1-9]\d*)\.
         (?<minor>0|[1-9]\d*)\.
         (?<patch>0|[1-9]\d*)
-        (?:-(?<prerelease>[0-9A-Za-z.-]+))?
+        (?:[.-](?<prerelease>[0-9A-Za-z.-]+))?
         (?:\+(?<buildmetadata>[0-9A-Za-z.-]+))?
       \z}x
     end
 
-    it 'follows semantic versioning format' do
+    it 'follows semantic versioning format (accepting hyphen or dot pre-release separator)' do
       expect(version).to match(semver_regex)
     end
 
@@ -105,19 +105,19 @@ RSpec.describe 'SimpleCovMcp::VERSION' do
 
   describe 'standalone version file load' do
     it 'defines the module and VERSION constant when only version.rb is loaded' do
-      original_module = SimpleCovMcp
       original_version = SimpleCovMcp::VERSION
 
-      Object.send(:remove_const, :SimpleCovMcp)
+      stub_const('SimpleCovMcp', Module.new do
+        class << self
+          attr_accessor :default_log_file, :active_log_file
+        end
+      end)
 
       version_path = File.expand_path('../lib/simplecov_mcp/version.rb', __dir__)
       load version_path
 
       expect(Object.const_defined?(:SimpleCovMcp)).to be true
       expect(SimpleCovMcp::VERSION).to eq(original_version)
-    ensure
-      Object.send(:remove_const, :SimpleCovMcp) if Object.const_defined?(:SimpleCovMcp)
-      Object.const_set(:SimpleCovMcp, original_module)
     end
   end
 end

data/spec/version_tool_spec.rb

@@ -15,14 +15,14 @@ RSpec.describe SimpleCovMcp::Tools::VersionTool do
       response = described_class.call(server_context: server_context)
       item = response.payload.first
       expect(item[:type] || item['type']).to eq('text')
-      text = item[:text] || item['text']
+      text = item['text']
       expect(text).to eq("SimpleCovMcp version: #{SimpleCovMcp::VERSION}")
     end
 
     it 'includes the exact version constant value' do
       response = described_class.call(server_context: server_context)
       item = response.payload.first
-      text = item[:text] || item['text']
+      text = item['text']
       expect(text).to include(SimpleCovMcp::VERSION)
     end
 
@@ -30,7 +30,7 @@ RSpec.describe SimpleCovMcp::Tools::VersionTool do
       expected_format = "SimpleCovMcp version: #{SimpleCovMcp::VERSION}"
       response = described_class.call(server_context: server_context)
       item = response.payload.first
-      text = item[:text] || item['text']
+      text = item['text']
       expect(text).to eq(expected_format)
     end
 
@@ -49,18 +49,18 @@ RSpec.describe SimpleCovMcp::Tools::VersionTool do
       it 'accepts error_mode parameter without affecting output' do
         response = described_class.call(error_mode: 'off', server_context: server_context)
         item = response.payload.first
-        text = item[:text] || item['text']
+        text = item['text']
         expect(text).to eq("SimpleCovMcp version: #{SimpleCovMcp::VERSION}")
       end
 
-      it 'accepts error_mode "on" (default)' do
-        response = described_class.call(error_mode: 'on', server_context: server_context)
+      it 'accepts error_mode "log" (default)' do
+        response = described_class.call(error_mode: 'log', server_context: server_context)
         item = response.payload.first
         expect(item[:type] || item['type']).to eq('text')
       end
 
-      it 'accepts error_mode "trace"' do
-        response = described_class.call(error_mode: 'trace', server_context: server_context)
+      it 'accepts error_mode "debug"' do
+        response = described_class.call(error_mode: 'debug', server_context: server_context)
         item = response.payload.first
         expect(item[:type] || item['type']).to eq('text')
       end
@@ -74,28 +74,26 @@ RSpec.describe SimpleCovMcp::Tools::VersionTool do
           another: { nested: 'data' }
         )
         item = response.payload.first
-        text = item[:text] || item['text']
+        text = item['text']
         expect(text).to eq("SimpleCovMcp version: #{SimpleCovMcp::VERSION}")
       end
     end
 
     context 'when an error occurs' do
       it 'handles VERSION constant access errors and returns structured error response' do
-        # Force an error by overriding const_get to raise an error when VERSION is accessed
-        allow(SimpleCovMcp).to receive(:const_missing).with(:VERSION).and_raise(StandardError,
-          'Version access error')
+        # Force an error by hiding VERSION so const_missing is triggered
+        hide_const('SimpleCovMcp::VERSION')
+        allow(SimpleCovMcp).to receive(:const_missing).with(:VERSION)
+          .and_raise(StandardError, 'Version access error')
 
-        # Clear the cached VERSION constant to trigger const_missing
-        SimpleCovMcp.send(:remove_const, :VERSION) if SimpleCovMcp.const_defined?(:VERSION)
-
-        response = described_class.call(error_mode: 'on', server_context: server_context)
+        response = described_class.call(error_mode: 'log', server_context: server_context)
 
         # Should return error response in MCP format
         expect(response).to be_a(MCP::Tool::Response)
         item = response.payload.first
         expect(item[:type] || item['type']).to eq('text')
 
-        error_text = item[:text] || item['text']
+        error_text = item['text']
         expect(error_text).to include('Error')
       end
 
@@ -107,14 +105,14 @@ RSpec.describe SimpleCovMcp::Tools::VersionTool do
         # Replace VERSION with our mock object
         stub_const('SimpleCovMcp::VERSION', version_obj)
 
-        response = described_class.call(error_mode: 'on', server_context: server_context)
+        response = described_class.call(error_mode: 'log', server_context: server_context)
 
         # Should return error response in MCP format via the rescue block
         expect(response).to be_a(MCP::Tool::Response)
         item = response.payload.first
         expect(item[:type] || item['type']).to eq('text')
 
-        error_text = item[:text] || item['text']
+        error_text = item['text']
         expect(error_text).to include('Error')
       end
 
@@ -130,12 +128,12 @@ RSpec.describe SimpleCovMcp::Tools::VersionTool do
         item = response.payload.first
         expect(item[:type] || item['type']).to eq('text')
 
-        # Test error_mode 'trace' (should include more detail)
-        response = described_class.call(error_mode: 'trace', server_context: server_context)
+        # Test error_mode 'debug' (should include more detail)
+        response = described_class.call(error_mode: 'debug', server_context: server_context)
         expect(response).to be_a(MCP::Tool::Response)
         item = response.payload.first
         expect(item[:type] || item['type']).to eq('text')
-        error_text = item[:text] || item['text']
+        error_text = item['text']
         expect(error_text).to include('Error')
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simplecov-mcp
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Keith R. Bennett
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -54,42 +68,53 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- docs/ADVANCED_USAGE.md
-- docs/ARCHITECTURE.md
-- docs/BRANCH_ONLY_COVERAGE.md
-- docs/CLI_USAGE.md
-- docs/DEVELOPMENT.md
-- docs/ERROR_HANDLING.md
-- docs/EXAMPLES.md
-- docs/INSTALLATION.md
-- docs/LIBRARY_API.md
-- docs/MCP_INTEGRATION.md
-- docs/TROUBLESHOOTING.md
-- docs/arch-decisions/001-x-arch-decision.md
-- docs/arch-decisions/002-x-arch-decision.md
-- docs/arch-decisions/003-x-arch-decision.md
-- docs/arch-decisions/004-x-arch-decision.md
-- docs/arch-decisions/005-x-arch-decision.md
-- docs/arch-decisions/README.md
-- docs/presentations/simplecov-mcp-presentation.md
+- docs/dev/ARCHITECTURE.md
+- docs/dev/BRANCH_ONLY_COVERAGE.md
+- docs/dev/DEVELOPMENT.md
+- docs/dev/README.md
+- docs/dev/RELEASING.md
+- docs/dev/arch-decisions/001-x-arch-decision.md
+- docs/dev/arch-decisions/002-x-arch-decision.md
+- docs/dev/arch-decisions/003-x-arch-decision.md
+- docs/dev/arch-decisions/004-x-arch-decision.md
+- docs/dev/arch-decisions/005-x-arch-decision.md
+- docs/dev/arch-decisions/README.md
+- docs/dev/presentations/simplecov-mcp-presentation.md
+- docs/fixtures/demo_project/README.md
+- docs/user/ADVANCED_USAGE.md
+- docs/user/CLI_FALLBACK_FOR_LLMS.md
+- docs/user/CLI_USAGE.md
+- docs/user/ERROR_HANDLING.md
+- docs/user/EXAMPLES.md
+- docs/user/INSTALLATION.md
+- docs/user/LIBRARY_API.md
+- docs/user/MCP_INTEGRATION.md
+- docs/user/README.md
+- docs/user/TROUBLESHOOTING.md
+- docs/user/V2-BREAKING-CHANGES.md
 - exe/simplecov-mcp
 - lib/simplecov_mcp.rb
+- lib/simplecov_mcp/app_config.rb
 - lib/simplecov_mcp/app_context.rb
 - lib/simplecov_mcp/base_tool.rb
 - lib/simplecov_mcp/cli.rb
-- lib/simplecov_mcp/cli_config.rb
 - lib/simplecov_mcp/commands/base_command.rb
 - lib/simplecov_mcp/commands/command_factory.rb
 - lib/simplecov_mcp/commands/detailed_command.rb
 - lib/simplecov_mcp/commands/list_command.rb
 - lib/simplecov_mcp/commands/raw_command.rb
 - lib/simplecov_mcp/commands/summary_command.rb
+- lib/simplecov_mcp/commands/totals_command.rb
 - lib/simplecov_mcp/commands/uncovered_command.rb
+- lib/simplecov_mcp/commands/validate_command.rb
 - lib/simplecov_mcp/commands/version_command.rb
+- lib/simplecov_mcp/config_parser.rb
 - lib/simplecov_mcp/constants.rb
+- lib/simplecov_mcp/coverage_reporter.rb
 - lib/simplecov_mcp/error_handler.rb
 - lib/simplecov_mcp/error_handler_factory.rb
 - lib/simplecov_mcp/errors.rb
+- lib/simplecov_mcp/formatters.rb
 - lib/simplecov_mcp/formatters/source_formatter.rb
 - lib/simplecov_mcp/mcp_server.rb
 - lib/simplecov_mcp/mode_detector.rb
@@ -99,48 +124,60 @@ files:
 - lib/simplecov_mcp/option_parsers/env_options_parser.rb
 - lib/simplecov_mcp/option_parsers/error_helper.rb
 - lib/simplecov_mcp/path_relativizer.rb
+- lib/simplecov_mcp/predicate_evaluator.rb
 - lib/simplecov_mcp/presenters/base_coverage_presenter.rb
 - lib/simplecov_mcp/presenters/coverage_detailed_presenter.rb
 - lib/simplecov_mcp/presenters/coverage_raw_presenter.rb
 - lib/simplecov_mcp/presenters/coverage_summary_presenter.rb
 - lib/simplecov_mcp/presenters/coverage_uncovered_presenter.rb
 - lib/simplecov_mcp/presenters/project_coverage_presenter.rb
+- lib/simplecov_mcp/presenters/project_totals_presenter.rb
 - lib/simplecov_mcp/resolvers/coverage_line_resolver.rb
 - lib/simplecov_mcp/resolvers/resolver_factory.rb
 - lib/simplecov_mcp/resolvers/resultset_path_resolver.rb
 - lib/simplecov_mcp/resultset_loader.rb
 - lib/simplecov_mcp/staleness_checker.rb
+- lib/simplecov_mcp/table_formatter.rb
 - lib/simplecov_mcp/tools/all_files_coverage_tool.rb
 - lib/simplecov_mcp/tools/coverage_detailed_tool.rb
 - lib/simplecov_mcp/tools/coverage_raw_tool.rb
 - lib/simplecov_mcp/tools/coverage_summary_tool.rb
 - lib/simplecov_mcp/tools/coverage_table_tool.rb
+- lib/simplecov_mcp/tools/coverage_totals_tool.rb
 - lib/simplecov_mcp/tools/help_tool.rb
 - lib/simplecov_mcp/tools/uncovered_lines_tool.rb
+- lib/simplecov_mcp/tools/validate_tool.rb
 - lib/simplecov_mcp/tools/version_tool.rb
 - lib/simplecov_mcp/util.rb
 - lib/simplecov_mcp/version.rb
 - spec/MCP_INTEGRATION_TESTS_README.md
 - spec/TIMESTAMPS.md
 - spec/all_files_coverage_tool_spec.rb
+- spec/app_config_spec.rb
 - spec/base_tool_spec.rb
 - spec/cli/show_default_report_spec.rb
-- spec/cli_config_spec.rb
 - spec/cli_enumerated_options_spec.rb
 - spec/cli_error_spec.rb
+- spec/cli_format_spec.rb
+- spec/cli_json_options_spec.rb
 - spec/cli_source_spec.rb
 - spec/cli_spec.rb
-- spec/cli_success_predicate_spec.rb
 - spec/cli_table_spec.rb
 - spec/cli_usage_spec.rb
 - spec/commands/base_command_spec.rb
 - spec/commands/command_factory_spec.rb
 - spec/commands/detailed_command_spec.rb
+- spec/commands/list_command_spec.rb
 - spec/commands/raw_command_spec.rb
 - spec/commands/summary_command_spec.rb
+- spec/commands/totals_command_spec.rb
 - spec/commands/uncovered_command_spec.rb
+- spec/commands/validate_command_spec.rb
+- spec/commands/version_command_spec.rb
 - spec/constants_spec.rb
+- spec/coverage_reporter_spec.rb
 - spec/coverage_table_tool_spec.rb
+- spec/coverage_totals_tool_spec.rb
 - spec/error_handler_spec.rb
 - spec/error_mode_spec.rb
 - spec/errors_edge_cases_spec.rb
@@ -166,6 +203,7 @@ files:
 - spec/presenters/coverage_summary_presenter_spec.rb
 - spec/presenters/coverage_uncovered_presenter_spec.rb
 - spec/presenters/project_coverage_presenter_spec.rb
+- spec/presenters/project_totals_presenter_spec.rb
 - spec/resolvers/coverage_line_resolver_spec.rb
 - spec/resolvers/resolver_factory_spec.rb
 - spec/resolvers/resultset_path_resolver_spec.rb
@@ -173,14 +211,26 @@ files:
 - spec/shared_examples/README.md
 - spec/shared_examples/coverage_presenter_examples.rb
 - spec/shared_examples/file_based_mcp_tools.rb
+- spec/shared_examples/formatted_command_examples.rb
 - spec/shared_examples/mcp_tool_text_json_response.rb
 - spec/simple_cov_mcp_module_spec.rb
+- spec/simplecov_mcp/formatters/source_formatter_spec.rb
+- spec/simplecov_mcp/formatters_spec.rb
+- spec/simplecov_mcp/presenters/base_coverage_presenter_spec.rb
 - spec/simplecov_mcp_model_spec.rb
 - spec/simplecov_mcp_opts_spec.rb
 - spec/spec_helper.rb
 - spec/staleness_checker_spec.rb
 - spec/staleness_more_spec.rb
+- spec/support/cli_helpers.rb
+- spec/support/control_flow_helpers.rb
+- spec/support/fake_mcp.rb
+- spec/support/io_helpers.rb
+- spec/support/mcp_helpers.rb
 - spec/support/mcp_runner.rb
+- spec/support/mocking_helpers.rb
+- spec/table_format_spec.rb
+- spec/tools/validate_tool_spec.rb
 - spec/tools_error_handling_spec.rb
 - spec/util_spec.rb
 - spec/version_spec.rb
@@ -190,6 +240,23 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message: |
+  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+  ┃ V2.0.0 BREAKING CHANGES                                                 ┃
+  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+  ┃                                                                         ┃
+  ┃ V2.0.0 brings several breaking changes to this gem:                     ┃
+  ┃                                                                         ┃
+  ┃  • Options must now come BEFORE subcommands                             ┃
+  ┃  • --stale renamed to --staleness (-S still works)                      ┃
+  ┃  • --json replaced with --format json                                   ┃
+  ┃  • Error modes renamed: 'on' → 'log', 'trace' → 'debug'                 ┃
+  ┃  • --success-predicate moved to 'validate' subcommand                   ┃
+  ┃  • Default sort order changed from ascending to descending              ┃
+  ┃                                                                         ┃
+  ┃ See docs/user/V2-BREAKING-CHANGES.md for complete migration guide.      ┃
+  ┃                                                                         ┃
+  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 rdoc_options: []
 require_paths:
 - lib
@@ -204,7 +271,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: MCP server + CLI for SimpleCov coverage data
 test_files: []

data/docs/BRANCH_ONLY_COVERAGE.md

@@ -1,81 +0,0 @@
-# Branch-Only Coverage Handling
-
-SimpleCov can collect *line* coverage, *branch* coverage, or both. Projects that
-enable the `:branch` mode without `:line` produce a `.resultset.json` where the
-per-file entries contain a `branches` hash while the legacy `lines` array is
-`null`. This document explains that format and why SimpleCov MCP synthesizes a
-line array on the fly so downstream consumers continue to work.
-
-## SimpleCov branch payloads
-
-Each resultset groups coverage by absolute (or project-relative) path. A branch
-only entry looks like:
-
-```json
-{
-  "lib/example.rb": {
-    "lines": null,
-    "branches": {
-      "[:if, 0, 12, 4, 20, 29]": {
-        "[:then, 1, 13, 6, 13, 18]": 4,
-        "[:else, 2, 15, 6, 15, 16]": 0
-      }
-    }
-  }
-}
-```
-
-Key observations:
-
-- The outer hash key is either a stringified Ruby array or the raw array itself:
-  `[:if, branch_id, line, column, end_line, end_column]`. Array structure:
-  - index 0: branch type (`:if`, `:case`, `:unless`, etc.)
-  - index 1: internal branch identifier
-  - **index 2: line where the branch starts** (the field we care about for coverage)
-  - index 3: column where the branch starts
-  - index 4: line where the branch expression ends
-  - index 5: column where the branch expression ends
-- SimpleCov reuses a single branch tuple for all recorded runs.
-- The nested hash contains targets (`[:then, …]`, `[:else, …]`, `[:when, …]`, etc.)
-  Each target tuple mirrors the same shape—branch type at index 0, an internal
-  identifier at 1, then the start/end positions for that branch leg.
-  The integer value is the execution count for that branch leg. SimpleCov MCP
-  sums these counts per line when synthesizing fallback line data.
-
-## Synthesizing line coverage
-
-SimpleCov MCP exposes APIs and CLI tooling built around line-oriented coverage.
-To support branch-only projects, we reconstruct a minimal line array by summing
-branch hits per line. The resolver:
-
-1. Normalizes branch tuples, whether they arrive as arrays or strings.
-2. Extracts the line token (element `2`) and converts it to an integer.
-3. Aggregates hit counts across all branch targets for that line.
-4. Builds a dense array up to the highest line seen. Each populated slot stores
-   the total branch hits recorded for that line. Slots remain `nil` when a line
-   never appeared in the branch data.
-
-This produces the familiar SimpleCov shape (array index → line number - 1), so
-utilities like `summary`, `uncovered`, and staleness checks keep working.
-
-## Code map
-
-Relevant implementation points:
-
-- `lib/simplecov_mcp/resolvers/coverage_line_resolver.rb` — entry point that
-  synthesizes the array when `lines` is missing.
-- Specs covering branch-only behaviour live in
-  `spec/resolvers/coverage_line_resolver_spec.rb` and
-  `spec/simplecov_mcp_model_spec.rb`.
-- Fixture data resides at
-  `spec/fixtures/branch_only_project/coverage/.resultset.json`.
-
-Implementation notes:
-
-- The resolver must return `nil` when a path fails to match. `CovUtil.lookup_lines`
-  tries alternate keys (absolute, project-relative, cwd-stripped). Returning
-  `nil` allows those attempts to continue, ultimately raising the expected
-  `FileError` only after every variant is exhausted.
-- SimpleCov may evolve the branch tuple format. When that happens, extend
-  `extract_line_number` to recognize the new shape and refresh this document so
-  future maintainers understand which forms are supported.