cov-loupe 3.0.0 → 4.0.0.pre

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cov-loupe
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0.pre
 platform: ruby
 authors:
 - Keith R. Bennett
@@ -10,33 +10,47 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: awesome_print
+  name: amazing_print
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -66,21 +80,70 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
+- CLAUDE.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- GEMINI.md
 - LICENSE
 - README.md
+- RELEASE_NOTES.md
+- dev/images/cov-loupe-icon-lores.png
+- dev/images/cov-loupe-icon-square.png
+- dev/images/cov-loupe-icon.png
+- dev/images/cov-loupe-logo.png
+- dev/prompts/README.md
+- dev/prompts/archive/architectural-review-and-actions-prompt.md
+- dev/prompts/archive/investigate-and-report-issues-prompt.md
+- dev/prompts/archive/produce-action-items-prompt.md
+- dev/prompts/guidelines/ai-code-evaluator-guidelines.md
+- dev/prompts/improve/refactor-test-suite.md
+- dev/prompts/improve/simplify-code-logic.md
+- dev/prompts/improve/update-documentation.md
+- dev/prompts/review/comprehensive-codebase-review.md
+- dev/prompts/review/identify-action-items.md
+- dev/prompts/review/verify-code-changes.md
+- dev/prompts/validate/create-screencast-outline.md
+- dev/prompts/validate/test-documentation-examples.md
+- docs/QUICKSTART.md
+- docs/assets/images/cov-loupe-logo-lores.png
+- docs/assets/images/cov-loupe-logo.png
+- docs/assets/images/favicon.png
+- docs/assets/stylesheets/branding.css
+- docs/assets/stylesheets/extra.css
+- docs/code_of_conduct.md
+- docs/contributing.md
 - docs/dev/ARCHITECTURE.md
-- docs/dev/BRANCH_ONLY_COVERAGE.md
 - docs/dev/DEVELOPMENT.md
+- docs/dev/FUTURE_ENHANCEMENTS.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/arch-decisions/application-architecture.md
+- docs/dev/arch-decisions/coverage-data-quality.md
+- docs/dev/arch-decisions/output-character-mode.md
+- docs/dev/arch-decisions/path-resolution.md
+- docs/dev/arch-decisions/policy-validation.md
+- docs/dev/arch-decisions/simplecov-integration.md
 - docs/dev/presentations/cov-loupe-presentation.md
+- docs/examples/mcp-inputs.md
+- docs/examples/prompts.md
+- docs/examples/success_predicates.md
+- docs/fixtures/demo_project/.resultset.json
 - docs/fixtures/demo_project/README.md
+- docs/fixtures/demo_project/app/controllers/admin/audit_logs_controller.rb
+- docs/fixtures/demo_project/app/controllers/orders_controller.rb
+- docs/fixtures/demo_project/app/models/order.rb
+- docs/fixtures/demo_project/app/models/user.rb
+- docs/fixtures/demo_project/lib/api/client.rb
+- docs/fixtures/demo_project/lib/ops/jobs/cleanup_job.rb
+- docs/fixtures/demo_project/lib/ops/jobs/report_job.rb
+- docs/fixtures/demo_project/lib/payments/processor.rb
+- docs/fixtures/demo_project/lib/payments/refund_service.rb
+- docs/fixtures/demo_project/lib/payments/reporting/exporter.rb
+- docs/index.md
+- docs/license.md
+- docs/release_notes.md
 - docs/user/ADVANCED_USAGE.md
 - docs/user/CLI_FALLBACK_FOR_LLMS.md
 - docs/user/CLI_USAGE.md
@@ -91,11 +154,39 @@ files:
 - docs/user/MCP_INTEGRATION.md
 - docs/user/README.md
 - docs/user/TROUBLESHOOTING.md
-- docs/user/V2-BREAKING-CHANGES.md
+- docs/user/installing-a-prelease-version-of-covloupe.md
+- docs/user/migrations/MIGRATING_TO_V2.md
+- docs/user/migrations/MIGRATING_TO_V3.md
+- docs/user/migrations/MIGRATING_TO_V4.md
+- docs/user/migrations/README.md
+- docs/user/prompts/README.md
+- docs/user/prompts/non-web-coverage-analysis-prompt.md
+- docs/user/prompts/rails-coverage-analysis-prompt.md
+- docs/user/prompts/use-cli-not-mcp-prompt.md
+- examples/cli_demo.sh
+- examples/filter_and_table_demo-output.md
+- examples/filter_and_table_demo.rb
+- examples/fixtures/demo_project/coverage/.resultset.json
+- examples/fixtures/demo_project/lib/bar.rb
+- examples/fixtures/demo_project/lib/foo.rb
+- examples/mcp-inputs/README.md
+- examples/mcp-inputs/coverage_detailed.json
+- examples/mcp-inputs/coverage_raw.json
+- examples/mcp-inputs/coverage_summary.json
+- examples/mcp-inputs/list.json
+- examples/mcp-inputs/uncovered_lines.json
+- examples/prompts/README.md
+- examples/prompts/custom_resultset.txt
+- examples/prompts/detailed_with_source.txt
+- examples/prompts/list_lowest.txt
+- examples/prompts/summary.txt
+- examples/prompts/uncovered.txt
+- examples/success_predicates/README.md
+- examples/success_predicates/all_files_above_threshold_predicate.rb
+- examples/success_predicates/directory_specific_thresholds_predicate.rb
+- examples/success_predicates/project_coverage_minimum_predicate.rb
 - exe/cov-loupe
 - lib/cov_loupe.rb
-- lib/cov_loupe/app_config.rb
-- lib/cov_loupe/app_context.rb
 - lib/cov_loupe/base_tool.rb
 - lib/cov_loupe/cli.rb
 - lib/cov_loupe/commands/base_command.rb
@@ -108,168 +199,107 @@ files:
 - lib/cov_loupe/commands/uncovered_command.rb
 - lib/cov_loupe/commands/validate_command.rb
 - lib/cov_loupe/commands/version_command.rb
-- lib/cov_loupe/config_parser.rb
-- lib/cov_loupe/constants.rb
-- lib/cov_loupe/coverage_reporter.rb
-- lib/cov_loupe/error_handler.rb
-- lib/cov_loupe/error_handler_factory.rb
-- lib/cov_loupe/errors.rb
-- lib/cov_loupe/formatters.rb
+- lib/cov_loupe/config/app_config.rb
+- lib/cov_loupe/config/app_context.rb
+- lib/cov_loupe/config/boolean_type.rb
+- lib/cov_loupe/config/config_parser.rb
+- lib/cov_loupe/config/logger.rb
+- lib/cov_loupe/config/option_normalizers.rb
+- lib/cov_loupe/config/option_parser_builder.rb
+- lib/cov_loupe/config/predicate_evaluator.rb
+- lib/cov_loupe/coverage/coverage_calculator.rb
+- lib/cov_loupe/coverage/coverage_reporter.rb
+- lib/cov_loupe/coverage/coverage_table_formatter.rb
+- lib/cov_loupe/errors/error_handler.rb
+- lib/cov_loupe/errors/error_handler_factory.rb
+- lib/cov_loupe/errors/errors.rb
+- lib/cov_loupe/formatters/formatters.rb
 - lib/cov_loupe/formatters/source_formatter.rb
+- lib/cov_loupe/formatters/table_formatter.rb
+- lib/cov_loupe/loaders/all.rb
+- lib/cov_loupe/loaders/all_cli.rb
+- lib/cov_loupe/loaders/all_mcp.rb
+- lib/cov_loupe/loaders/resultset_loader.rb
 - lib/cov_loupe/mcp_server.rb
-- lib/cov_loupe/mode_detector.rb
-- lib/cov_loupe/model.rb
-- lib/cov_loupe/option_normalizers.rb
-- lib/cov_loupe/option_parser_builder.rb
+- lib/cov_loupe/model/model.rb
+- lib/cov_loupe/model/model_data.rb
+- lib/cov_loupe/model/model_data_cache.rb
 - lib/cov_loupe/option_parsers/env_options_parser.rb
 - lib/cov_loupe/option_parsers/error_helper.rb
-- lib/cov_loupe/path_relativizer.rb
-- lib/cov_loupe/predicate_evaluator.rb
+- lib/cov_loupe/output_chars.rb
+- lib/cov_loupe/paths/glob_utils.rb
+- lib/cov_loupe/paths/path_relativizer.rb
+- lib/cov_loupe/paths/path_utils.rb
+- lib/cov_loupe/paths/volume_case_sensitivity.rb
 - lib/cov_loupe/presenters/base_coverage_presenter.rb
-- lib/cov_loupe/presenters/coverage_detailed_presenter.rb
-- lib/cov_loupe/presenters/coverage_raw_presenter.rb
-- lib/cov_loupe/presenters/coverage_summary_presenter.rb
-- lib/cov_loupe/presenters/coverage_uncovered_presenter.rb
+- lib/cov_loupe/presenters/coverage_payload_presenter.rb
+- lib/cov_loupe/presenters/payload_caching.rb
 - lib/cov_loupe/presenters/project_coverage_presenter.rb
 - lib/cov_loupe/presenters/project_totals_presenter.rb
+- lib/cov_loupe/repositories/coverage_repository.rb
 - lib/cov_loupe/resolvers/coverage_line_resolver.rb
-- lib/cov_loupe/resolvers/resolver_factory.rb
+- lib/cov_loupe/resolvers/resolver_helpers.rb
 - lib/cov_loupe/resolvers/resultset_path_resolver.rb
-- lib/cov_loupe/resultset_loader.rb
-- lib/cov_loupe/staleness_checker.rb
-- lib/cov_loupe/table_formatter.rb
-- lib/cov_loupe/tools/all_files_coverage_tool.rb
+- lib/cov_loupe/scripts/command_execution.rb
+- lib/cov_loupe/scripts/latest_ci_status.rb
+- lib/cov_loupe/scripts/pre_release_check.rb
+- lib/cov_loupe/scripts/setup_doc_server.rb
+- lib/cov_loupe/scripts/start_doc_server.rb
+- lib/cov_loupe/staleness/stale_status.rb
+- lib/cov_loupe/staleness/staleness_checker.rb
+- lib/cov_loupe/staleness/staleness_message_formatter.rb
 - lib/cov_loupe/tools/coverage_detailed_tool.rb
 - lib/cov_loupe/tools/coverage_raw_tool.rb
 - lib/cov_loupe/tools/coverage_summary_tool.rb
 - lib/cov_loupe/tools/coverage_table_tool.rb
 - lib/cov_loupe/tools/coverage_totals_tool.rb
 - lib/cov_loupe/tools/help_tool.rb
+- lib/cov_loupe/tools/list_tool.rb
 - lib/cov_loupe/tools/uncovered_lines_tool.rb
 - lib/cov_loupe/tools/validate_tool.rb
 - lib/cov_loupe/tools/version_tool.rb
-- lib/cov_loupe/util.rb
 - lib/cov_loupe/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_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_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/cov_loupe/formatters/source_formatter_spec.rb
-- spec/cov_loupe/formatters_spec.rb
-- spec/cov_loupe/presenters/base_coverage_presenter_spec.rb
-- spec/cov_loupe_model_spec.rb
-- spec/cov_loupe_module_spec.rb
-- spec/cov_loupe_opts_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
-- spec/errors_stale_spec.rb
-- spec/file_based_mcp_tools_spec.rb
-- spec/fixtures/project1/lib/bar.rb
-- spec/fixtures/project1/lib/foo.rb
-- spec/help_tool_spec.rb
-- spec/integration_spec.rb
-- spec/logging_fallback_spec.rb
-- spec/mcp_logging_spec.rb
-- spec/mcp_server_integration_spec.rb
-- spec/mcp_server_spec.rb
-- spec/mode_detector_spec.rb
-- spec/model_error_handling_spec.rb
-- spec/model_staleness_spec.rb
-- spec/option_normalizers_spec.rb
-- spec/option_parsers/env_options_parser_spec.rb
-- spec/option_parsers/error_helper_spec.rb
-- spec/path_relativizer_spec.rb
-- spec/presenters/coverage_detailed_presenter_spec.rb
-- spec/presenters/coverage_raw_presenter_spec.rb
-- 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
-- spec/resultset_loader_spec.rb
-- 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/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
-- spec/version_tool_spec.rb
 homepage: https://github.com/keithrbennett/cov-loupe
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: |
-  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
-  ┃ V3.0.0 - GEM RENAMED: simplecov-mcp → cov-loupe                         ┃
-  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
-  ┃                                                                         ┃
-  ┃ This gem has been renamed! If upgrading from simplecov-mcp:             ┃
-  ┃                                                                         ┃
-  ┃  • Executable: simplecov-mcp → cov-loupe                                ┃
-  ┃  • Environment: SIMPLECOV_MCP_OPTS → COV_LOUPE_OPTS                     ┃
-  ┃  • Log file: simplecov_mcp.log → cov_loupe.log                          ┃
-  ┃  • Alias: smcp → clp (in documentation)                                 ┃
-  ┃                                                                         ┃
-  ┃ Module name (CovLoupe) and require path (cov_loupe) unchanged.          ┃
-  ┃                                                                         ┃
-  ┃ Uninstall old gem: gem uninstall simplecov-mcp                          ┃
-  ┃                                                                         ┃
-  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
-  ┃ V2.0.0 BREAKING CHANGES (if upgrading from v1.x)                        ┃
-  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
-  ┃                                                                         ┃
-  ┃  • 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.      ┃
-  ┃                                                                         ┃
-  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+post_install_message: "┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓\n┃
+  V4.0.0 BREAKING CHANGES                                                   ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫\n┃
+  \                                                                          ┃\n┃
+  \ ⚠️  MCP MODE NOW REQUIRES -m/--mode mcp FLAG (AUTO-DETECTION REMOVED)    ┃\n┃
+  \                                                                          ┃\n┃
+  \ If you use cov-loupe as an MCP server, you MUST update your config.      ┃\n┃
+  \ Without -m mcp, the server will run in CLI mode and hang.                ┃\n┃
+  \                                                                          ┃\n┃
+  \ \U0001F4D6 Migration instructions: docs/user/migrations/MIGRATING_TO_V4.md       ┃\n┃
+  \                                                                          ┃\n┃
+  Other breaking changes:                                                   ┃\n┃  •
+  --force-mode removed → use -m/--mode cli|mcp instead                   ┃\n┃  • --staleness
+  removed → use --raise-on-stale (boolean) instead           ┃\n┃  • Ruby API: check_stale
+  removed → use raise_on_stale (boolean) instead   ┃\n┃  • Model #all_files_coverage
+  method renamed to #list                      ┃\n┃                                                                           ┃\n┃
+  See RELEASE_NOTES.md for full migration details.                          ┃\n┃                                                                           ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫\n┃
+  V3.0.0 - GEM RENAMED: simplecov-mcp → cov-loupe                           ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫\n┃
+  \                                                                          ┃\n┃
+  This gem has been renamed! If upgrading from simplecov-mcp:               ┃\n┃                                                                           ┃\n┃
+  \ • Executable: simplecov-mcp → cov-loupe                                  ┃\n┃
+  \ • Environment: SIMPLECOV_MCP_OPTS → COV_LOUPE_OPTS                       ┃\n┃
+  \ • Log file: simplecov_mcp.log → cov_loupe.log                            ┃\n┃
+  \ • Alias: smcp → clp (in documentation)                                   ┃\n┃
+  \                                                                          ┃\n┃
+  Module name (CovLoupe) and require path (cov_loupe) unchanged.            ┃\n┃                                                                           ┃\n┃
+  Uninstall old gem: gem uninstall simplecov-mcp                            ┃\n┃                                                                           ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫\n┃
+  V2.0.0 BREAKING CHANGES (if upgrading from v1.x)                          ┃\n┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫\n┃
+  \                                                                          ┃\n┃
+  \ • Options must now come BEFORE subcommands                               ┃\n┃
+  \ • --stale renamed to --staleness (-S still works)                        ┃\n┃
+  \ • --json replaced with --format json                                     ┃\n┃
+  \ • Error modes renamed: 'on' → 'log', 'trace' → 'debug'                   ┃\n┃
+  \ • --success-predicate moved to 'validate' subcommand                     ┃\n┃
+  \ • Default sort order changed from ascending to descending                ┃\n┃
+  \                                                                          ┃\n┃
+  See docs/user/migrations/MIGRATING_TO_V2.md for complete migration guide. ┃\n┃                                                                           ┃\n┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\n"
 rdoc_options: []
 require_paths:
 - lib
@@ -284,7 +314,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.4
 specification_version: 4
 summary: MCP server + CLI for SimpleCov coverage data
 test_files: []

data/docs/dev/BRANCH_ONLY_COVERAGE.md

@@ -1,158 +0,0 @@
-# Branch-Only Coverage Handling
-
-[Back to main README](../README.md)
-
-> **Note:** This document is for **developers working on SimpleCov MCP**, not for users of the gem.
-> If you're a user, you don't need to read this - branch-only coverage "just works" automatically.
-> This explains the internal implementation for contributors who need to maintain or modify the code.
-
-## The Problem This Solves for SimpleCov MCP
-
-SimpleCov can be configured to track different types of coverage:
-- **Line coverage**: Which lines of code were executed
-- **Branch coverage**: Which paths through if/else, case/when, etc. were taken
-- **Both**: Track both lines and branches together
-
-When users configure SimpleCov to track **only branch coverage** (without line coverage),
-the `.resultset.json` file has a different structure: the `lines` array is `null`,
-and only the `branches` data exists.
-
-**This breaks SimpleCov MCP** because our entire tool is designed around the `lines` array:
-- Our MCP tools (`coverage_summary_tool`, `uncovered_lines_tool`, etc.) expect line data
-- Our CLI commands expect line data
-- Our `CoverageModel` API expects line data
-
-Rather than failing with "no coverage data found" errors, SimpleCov MCP **automatically
-converts branch coverage into line coverage** so all our tools continue to work seamlessly
-for projects using branch-only configuration.
-
-## What Branch-Only Coverage Data Looks Like
-
-When SimpleCov writes branch-only coverage, the `.resultset.json` file looks different
-from the normal line coverage format. Here's an example:
-
-```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
-      }
-    }
-  }
-}
-```
-
-### Understanding the Branch Data Structure
-
-The `branches` hash uses a nested structure:
-
-**Outer key** (e.g., `"[:if, 0, 12, 4, 20, 29]"`):
-- This is either a Ruby array or its stringified version
-- It describes where the branch decision happens (the `if` statement itself)
-- Format: `[type, id, start_line, start_col, end_line, end_col]`
-  - Position 0: Branch type (`:if`, `:case`, `:unless`, etc.)
-  - Position 1: SimpleCov's internal ID for this branch
-  - **Position 2: The line number** ← This is what we need for line coverage!
-  - Position 3: Starting column
-  - Position 4: Ending line
-  - Position 5: Ending column
-
-**Nested hash** (the value of the outer key):
-- Contains each possible path through the branch
-- Keys are branch targets like `"[:then, 1, 13, 6, 13, 18]"` or `"[:else, 2, 15, 6, 15, 16]"`
-- Each target has the same array format as the outer key
-- Values are integers showing how many times that path was executed
-  - `4` means the `then` branch ran 4 times
-  - `0` means the `else` branch never ran
-
-**Why this matters for our conversion:**
-- We extract the line number (position 2) from each branch target
-- We sum up all the execution counts for branches on the same line
-- This gives us enough information to build a line coverage array
-
-## How SimpleCov MCP Converts Branch Coverage to Line Coverage
-
-Since all of SimpleCov MCP's tools expect a `lines` array, we need to build one from
-the `branches` data. This happens automatically in the `CoverageLineResolver` whenever
-it detects that `lines` is `null` but `branches` exists.
-
-### The Conversion Algorithm
-
-Here's how we transform branch data into line data:
-
-**Step 1: Parse the branch keys**
-- Branch keys can be either raw Ruby arrays or stringified (e.g., `"[:if, 0, 12, 4, 20, 29]"`)
-- We handle both formats by parsing the string format when needed
-
-**Step 2: Extract line numbers**
-- From each branch target tuple, we pull out position 2 (the line number)
-- Invalid or malformed tuples are silently skipped
-
-**Step 3: Sum hits per line**
-- Multiple branches can exist on the same line (e.g., nested ifs, ternaries)
-- We add up all the execution counts for branches on the same line
-- Example: if line 15 has a `then` branch hit 4 times and an `else` branch hit 2 times,
-  that line gets a total of 6 hits
-
-**Step 4: Build the line array**
-- We create an array with length equal to the highest line number found
-- Each array position represents a line: `array[0]` = line 1, `array[1]` = line 2, etc.
-- Positions get the summed hit count for that line, or `nil` if no branches appeared there
-
-**Result:** We now have a `lines` array that looks exactly like SimpleCov's normal
-format, so all our tools (`summary`, `uncovered`, staleness checks, etc.) work without
-knowing branch coverage was involved.
-
-## Where to Find the Code
-
-If you need to modify or debug the branch coverage conversion, here's where everything lives:
-
-### Implementation
-**`lib/cov_loupe/resolvers/coverage_line_resolver.rb`**
-- Line 59-66: `lines_from_entry` - Detects when to synthesize line data
-- Line 68-103: `synthesize_lines_from_branches` - The main conversion logic
-- Line 105-123: `extract_line_number` - Parses line numbers from branch tuples
-
-This file is referenced in the code comments at line 79.
-
-### Tests
-**`spec/resolvers/coverage_line_resolver_spec.rb`**
-- Contains tests specifically for the resolver and branch synthesis
-
-**`spec/cov_loupe_model_spec.rb`**
-- Integration tests showing how the model uses synthesized line data
-
-### Test Data
-**`spec/fixtures/branch_only_project/coverage/.resultset.json`**
-- Example of real branch-only coverage data used in tests
-- Useful reference when debugging issues or adding new test cases
-
-## Important Implementation Notes
-
-### Why the resolver returns `nil` for missing files
-
-When `CoverageLineResolver.lookup_lines` can't find a file, it returns `nil` rather
-than immediately raising an error. This is deliberate:
-
-- The lookup tries multiple strategies: exact path match, relative path, path without
-  working directory prefix
-- Each strategy calls `lines_from_entry` which may return `nil`
-- Only after **all strategies fail** does the resolver raise a `FileError`
-- This ensures we try every possible way to find the file before giving up
-
-If you change `lines_from_entry` to raise an error immediately, the multi-strategy
-lookup will break!
-
-### Future-proofing for SimpleCov changes
-
-SimpleCov's branch tuple format could change in future versions. If that happens:
-
-1. Update `extract_line_number` to recognize the new tuple format
-2. Add test fixtures with the new format
-3. Update this documentation with the new structure
-4. Keep backward compatibility with the old format if possible
-
-This way, SimpleCov MCP continues working even when SimpleCov evolves.