rigortype 0.2.0 → 0.2.1

data/data/vendored_gem_sigs/rubygems/rubygems_extras.rbs

@@ -0,0 +1,226 @@
+#
+# Rigor-side supplement to the rbs gem's
+# `core/rubygems/*.rbs` declarations.
+#
+# Re-opens the rubygems classes / Gem module to ADD the
+# declarations the upstream RBS omits. Every block below adds
+# new method signatures only — it does NOT redeclare anything
+# the upstream RBS already covers, so the loader does not raise
+# `RBS::DuplicatedDeclarationError`.
+#
+# Driven by the `references/ruby/lib` survey
+# (`docs/CURRENT_WORK.md` § "Queued engine items") which
+# clusters `undefined-method` on Gem-side selectors most-touched
+# by rubygems' own source tree and by bundler. Returns are
+# `untyped` where Rigor cannot infer a precise shape — the goal
+# is to silence false positives, not to author precise sigs.
+#
+module Gem
+  # Singleton additions surfacing in the survey but absent from
+  # the upstream `core/rubygems/rubygems.rbs`. All are real
+  # methods defined in `lib/rubygems/defaults.rb`,
+  # `lib/rubygems.rb`, or the platform-specific override files.
+  def self.target_rbconfig: () -> untyped
+  def self.set_target_rbconfig: (untyped) -> untyped
+  def self.load_safe_marshal: () -> untyped
+  def self.safe_load_marshal: (untyped) -> untyped
+  def self.verbose: () -> bool
+  def self.really_verbose: () -> bool
+  def self.discover_gems_on_require: () -> bool
+  def self.discover_gems_on_require=: (bool) -> bool
+  def self.default_user_install: () -> bool
+  def self.dynamic_library_suffixes: () -> Array[String]
+  def self.extension_api_version: () -> String
+  def self.find_default_spec: (untyped) -> untyped?
+  def self.install_extension_in_lib: () -> bool
+  def self.load_bundler_extensions: () -> untyped
+  def self.load_plugin_files: (?untyped plugins) -> untyped
+  def self.open_file: (String path, String mode) { (IO) -> untyped } -> untyped
+  def self.open_file_with_lock: (String path) { (IO) -> untyped } -> untyped
+  def self.state_file: () -> String
+  def self.vendor_dir: () -> String
+  def self.activate_bin_path: (String name, ?String exec_name, ?untyped requirements) -> String
+end
+
+class Gem::Platform
+  # `Gem::Platform.new(arg)` is the canonical constructor; the
+  # upstream `core/rubygems/platform.rbs` declares the class
+  # but no `initialize`, which forces RBS to default to
+  # `(): void` and the wrong-arity rule fires for every call
+  # site. The accessor / predicate set covers the most-used
+  # surface bundler and rubygems internals touch.
+  def initialize: (*untyped) -> void
+  attr_accessor cpu: String?
+  attr_accessor os: String?
+  attr_accessor version: String?
+  def to_s: () -> String
+  def ==: (untyped) -> bool
+  def ===: (untyped) -> bool
+  def =~: (untyped) -> bool?
+  def eql?: (untyped) -> bool
+  def hash: () -> Integer
+  def match_spec?: (untyped) -> bool
+  def match_gem?: (untyped, untyped) -> bool
+
+  def self.local: () -> Platform
+  def self.match_spec?: (untyped) -> bool
+  def self.match_gem?: (untyped, untyped) -> bool
+  def self.installable?: (untyped) -> bool
+  def self.sort_priority: (untyped) -> Integer
+end
+
+class Gem::Dependency
+  # `Gem::Dependency.new(name, *requirements, type: :runtime)`.
+  # Upstream RBS declares the class shell but no constructor; a
+  # permissive splat keeps the canonical and the
+  # `(name, requirements, type)` invocation forms both silent.
+  def initialize: (*untyped) -> void
+  attr_accessor name: String
+  attr_accessor requirement: Gem::Requirement
+  attr_accessor type: Symbol
+  attr_accessor prerelease: bool
+  def matches_spec?: (untyped) -> bool
+  def match?: (*untyped) -> bool
+  def to_s: () -> String
+  def ==: (untyped) -> bool
+  def eql?: (untyped) -> bool
+  def hash: () -> Integer
+end
+
+class Gem::Specification
+  def self.find_all_by_name: (String name, *untyped requirements) -> Array[Gem::Specification]
+  def self.stubs: () -> Array[untyped]
+  def self.default_stubs: (?String pattern) -> Array[untyped]
+  def self.reset: () -> void
+  def self.from_yaml: (untyped) -> Gem::Specification
+  def self.load: (String path) -> Gem::Specification?
+  def self._all: () -> Array[Gem::Specification]
+  def self.each: () { (Gem::Specification) -> untyped } -> void
+
+  # Instance-side surface widely used by bundler / rubygems
+  # internals. `attr_accessor` mirrors the writer + reader pair
+  # so the survey's `.name=` / `.version=` / `.full_gem_path=` /
+  # `.loaded_from=` / `.post_install_message=` writes resolve too.
+  def activate: () -> untyped
+  def specification_version: () -> Integer
+  def files: () -> Array[String]
+  def default_gem?: () -> bool
+  def spec_file: () -> String
+  def runtime_dependencies: () -> Array[Gem::Dependency]
+  def required_rubygems_version: () -> Gem::Requirement
+  def required_ruby_version: () -> Gem::Requirement
+  def require_paths: () -> Array[String]
+  attr_accessor name: String
+  attr_accessor version: Gem::Version
+  attr_accessor full_gem_path: String
+  attr_accessor loaded_from: String?
+  attr_accessor post_install_message: String?
+end
+
+class Gem::BasicSpecification
+  def version: () -> Gem::Version
+  def executables: () -> Array[String]
+  def name: () -> String
+  def full_name: () -> String
+  def gem_dir: () -> String
+end
+
+class Gem::Version
+  def segments: () -> Array[untyped]
+end
+
+class Gem::Requirement
+  def requirements: () -> Array[untyped]
+  def self.create: (*untyped) -> Gem::Requirement
+end
+
+class Gem::ConfigFile
+  def []: (untyped) -> untyped
+  def []=: (untyped, untyped) -> untyped
+  def write: () -> void
+  def verbose: () -> bool
+  def verbose=: (bool) -> bool
+  def really_verbose: () -> bool
+  def ssl_ca_cert: () -> String?
+  def ssl_client_cert: () -> String?
+  def ssl_verify_mode: () -> Integer?
+  def credentials_path: () -> String
+  def api_keys: () -> Hash[String, String]
+  def cert_expiration_length_days: () -> Integer
+  def sources: () -> Array[String]
+  def update_sources=: (bool) -> bool
+  def unset_api_key!: () -> bool
+  def state_file_writable?: () -> bool
+  def set_api_key: (untyped host, untyped key) -> untyped
+  def rubygems_api_key: () -> String?
+  def rubygems_api_key=: (String?) -> String?
+  def last_update_check: () -> Integer
+  def last_update_check=: (Integer) -> Integer
+  def ipv4_fallback_enabled: () -> bool
+  def install_extension_in_lib: () -> bool
+  def each: () { ([String, untyped]) -> untyped } -> void
+end
+
+class Gem::LoadError < LoadError
+  attr_accessor name: String
+  attr_accessor requirement: Gem::Requirement
+end
+
+class Gem::SourceList
+  include Enumerable[untyped]
+  def initialize: () -> void
+  def include?: (untyped) -> bool
+  def each: () { (untyped) -> untyped } -> void
+  def to_a: () -> Array[untyped]
+  def from: (untyped) -> SourceList
+end
+
+class Gem::RequestSet
+  def initialize: (*untyped) -> void
+  def import: (untyped) -> untyped
+  def source_set: () -> untyped
+  def installed_gems: () -> Hash[String, untyped]
+  def install: (?untyped options) { (?untyped) -> untyped } -> untyped
+  def install_from_gemdeps: (untyped options) { (?untyped) -> untyped } -> untyped
+  def resolve: (?untyped) -> untyped
+  def resolve_current: () -> untyped
+  def resolve_dependencies: () -> untyped
+  def errors: () -> Array[untyped]
+  attr_accessor remote: bool
+  attr_accessor development: bool
+  attr_accessor development_shallow: bool
+  attr_accessor ignore_dependencies: bool
+  attr_accessor prerelease: bool
+  attr_accessor soft_missing: bool
+  attr_accessor without_groups: Array[Symbol]
+  attr_accessor always_install: untyped
+  attr_accessor installing: bool
+end
+
+class Gem::DependencyInstaller
+  def initialize: (*untyped) -> void
+  def install: (untyped, ?untyped) -> Array[untyped]
+  def installed_gems: () -> Array[untyped]
+  def errors: () -> Array[untyped]
+end
+
+class Gem::Uninstaller
+  def initialize: (*untyped) -> void
+  def uninstall: () -> void
+end
+
+class Gem::PathSupport
+  def initialize: (*untyped) -> void
+end
+
+class Gem::Installer
+  def initialize: (*untyped) -> void
+end
+
+class Gem::DependencyInstaller
+  def initialize: (*untyped) -> void
+end
+
+class Gem::MissingSpecError < StandardError
+  def initialize: (*untyped) -> void
+end

data/lib/rigor/cli/check_command.rb

@@ -5,6 +5,7 @@ require "json"
 require "optionparser"
 
 require_relative "../configuration"
+require_relative "../config_audit"
 require_relative "../analysis/result"
 require_relative "../analysis/rule_catalog"
 require_relative "coverage_scan"
@@ -38,6 +39,7 @@ module Rigor
 
         configuration = load_check_configuration(options)
         configuration = apply_bleeding_edge_override(configuration, options)
+        config_warnings = warn_unresolved_config(configuration)
         cache_root = configuration.cache_path
         handle_clear_cache(cache_root) if options.fetch(:clear_cache)
 
@@ -52,7 +54,7 @@ module Rigor
         result = apply_baseline_filter(raw_result, configuration, options)
 
         coverage = compute_coverage(runner, configuration, options)
-        write_result(result, options.fetch(:format), coverage: coverage)
+        write_result(result, options.fetch(:format), coverage: coverage, config_warnings: config_warnings)
         emit_ci_detected_output(result, options)
         write_run_stats(result.stats) if result.stats
         write_trace_appendices
@@ -412,6 +414,26 @@ module Rigor
         options
       end
 
+      # Surfaces the class of mistake where a configured value resolves
+      # to nothing — a typo'd or moved `signature_paths:` / bundler /
+      # collection path, an unknown `libraries:` name, an inert
+      # `disable:` / `severity_overrides:` rule id ({ConfigAudit}). The
+      # loader filters each one silently, and the downstream symptom is
+      # confusing: missing signatures turn calls into high-confidence
+      # `call.undefined-method` firings, and an unrecognised suppression
+      # token leaves the rule firing as if the line were never written —
+      # so a one-character mistake can read as hundreds of real errors.
+      # Each finding is emitted to STDERR (a warning, not a hard error —
+      # partial / optional bundles are a valid setup) and the returned
+      # list rides into the `--format=json` payload under `config_warnings`
+      # so CI and framework consumers can assert on it. The audits only
+      # fire on explicit, working-setup-safe signals (see {ConfigAudit}).
+      def warn_unresolved_config(configuration)
+        warnings = ConfigAudit.warnings(configuration)
+        warnings.each { |warning| @err.puts("rigor: #{warning.message}") }
+        warnings
+      end
+
       # ADR-32 WD10 carry-over — wraps `Configuration.load` so the
       # CLI's `--treat-all-as-inline-rbs` flag can inject a
       # `rigor-rbs-inline` plugin entry with
@@ -671,11 +693,12 @@ module Rigor
         format("%.1f MiB", bytes / (1024.0 * 1024.0))
       end
 
-      def write_result(result, format, coverage: nil)
+      def write_result(result, format, coverage: nil, config_warnings: [])
         case format
         when "json"
           payload = enrich_json(result.to_h)
           payload["coverage"] = coverage_payload(coverage) if coverage
+          payload["config_warnings"] = config_warnings.map(&:to_h) unless config_warnings.empty?
           @out.puts(JSON.pretty_generate(payload))
         when "text"
           write_text_result(result)

data/lib/rigor/cli/coverage_command.rb

@@ -3,6 +3,7 @@
 require "English"
 require "optionparser"
 require "prism"
+require "shellwords"
 
 require_relative "../configuration"
 require_relative "options"
@@ -11,6 +12,7 @@ require_relative "../inference/precision_scanner"
 require_relative "../inference/protection_scanner"
 require_relative "../inference/parameter_inference_collector"
 require_relative "../protection/mutation_scanner"
+require_relative "../protection/test_suite_oracle"
 require_relative "../language_server/project_context"
 require_relative "../scope"
 require_relative "coverage_report"
@@ -20,6 +22,9 @@ require_relative "protection_report"
 require_relative "protection_renderer"
 require_relative "mutation_protection_report"
 require_relative "mutation_protection_renderer"
+require_relative "fused_protection_report"
+require_relative "fused_protection_renderer"
+require_relative "coverage_mutation"
 require_relative "command"
 
 module Rigor
@@ -38,12 +43,20 @@ module Rigor
     #   1  — precision ratio < threshold, or parse errors encountered
     #   64 — usage error
     class CoverageCommand < Command
+      include CoverageMutation
+
       USAGE = "Usage: rigor coverage [options] PATH..."
 
+      # ADR-70 — the default test runner hook for `--with-tests`. The
+      # conventional Ruby test task; override with `--test-command`.
+      DEFAULT_TEST_COMMAND = %w[bundle exec rake].freeze
+
       # @return [Integer] CLI exit status.
       def run
         options = parse_options
         return mutation_misuse_error if options[:mutation] && !options[:protection]
+        return with_tests_misuse_error if options[:with_tests] && !options[:mutation]
+        return include_dynamic_misuse_error if options[:include_dynamic] && !options[:with_tests]
         return run_mutation_protection(options) if options[:mutation]
 
         paths = collect_paths(@argv, command_name: "coverage")
@@ -60,36 +73,69 @@ module Rigor
       private
 
       def parse_options
-        options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false }
-
-        OptionParser.new do |opts|
-          opts.banner = USAGE
-          opts.on("--format=FORMAT", "Output format: text or json") { |v| options[:format] = v }
-          Options.add_config(opts, options)
-          opts.on(
-            "--protection",
-            "Report type-protection coverage (ADR-63 Tier 1) instead of type precision"
-          ) { options[:protection] = true }
-          opts.on(
-            "--mutation",
-            "With --protection: measure actual mutation effectiveness (ADR-63 Tier 2). " \
-            "Scopes to git-changed files when no paths are given; explicit paths override."
-          ) { options[:mutation] = true }
-          opts.on(
-            "--threshold=RATIO", Float,
-            "Exit 1 when the precision (or, with --protection, protection/effectiveness) ratio is below RATIO (0.0–1.0)"
-          ) { |v| options[:threshold] = v }
-        end.parse!(@argv)
-
+        options = { format: "text", threshold: nil, config: nil, protection: false, mutation: false,
+                    with_tests: false, test_command: DEFAULT_TEST_COMMAND, include_dynamic: false,
+                    limit: nil, seed: 1 }
+        OptionParser.new { |opts| define_options(opts, options) }.parse!(@argv)
         options
       end
 
+      def define_options(opts, options)
+        opts.banner = USAGE
+        opts.on("--format=FORMAT", "Output format: text or json") { |v| options[:format] = v }
+        Options.add_config(opts, options)
+        opts.on("--protection", "Report type-protection coverage (ADR-63 Tier 1) instead of type precision") do
+          options[:protection] = true
+        end
+        define_mutation_options(opts, options)
+        opts.on("--threshold=RATIO", Float, "Exit 1 when the precision (or, with --protection, " \
+                                            "protection/effectiveness) ratio is below RATIO (0.0–1.0)") do |v|
+          options[:threshold] = v
+        end
+      end
+
+      def define_mutation_options(opts, options)
+        opts.on("--mutation", "With --protection: measure actual mutation effectiveness (ADR-63 Tier 2). " \
+                              "Scopes to git-changed files when no paths are given; explicit paths override.") do
+          options[:mutation] = true
+        end
+        opts.on("--with-tests", "With --mutation: also measure dynamic (test-suite) protection (ADR-70). " \
+                                "Runs --test-command against each type-survivor; reports the fused map.") do
+          options[:with_tests] = true
+        end
+        opts.on("--test-command=CMD", "The test runner hook for --with-tests " \
+                                      "(default: #{DEFAULT_TEST_COMMAND.join(' ')})") do |v|
+          options[:test_command] = Shellwords.split(v)
+        end
+        opts.on("--include-dynamic", "With --with-tests: also mutate Dynamic-receiver (untyped) sites, where a " \
+                                     "test is the only protection (ADR-69 Seam 2). Completes the map, runs more.") do
+          options[:include_dynamic] = true
+        end
+        opts.on("--limit=N", Integer,
+                "Sample at most N mutations/file under --mutation (caps cost; ratios become estimates)") do |v|
+          options[:limit] = v
+        end
+        opts.on("--seed=N", Integer, "RNG seed for --limit sampling (default 1)") { |v| options[:seed] = v }
+      end
+
       def mutation_misuse_error
         @err.puts("coverage: --mutation requires --protection")
         @err.puts(USAGE)
         CLI::EXIT_USAGE
       end
 
+      def with_tests_misuse_error
+        @err.puts("coverage: --with-tests requires --mutation (and --protection)")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
+      def include_dynamic_misuse_error
+        @err.puts("coverage: --include-dynamic requires --with-tests (a Dynamic site's only protection is a test)")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
       def run_protection(paths, options)
         report = scan_protection(paths, options)
         ProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
@@ -133,77 +179,6 @@ module Rigor
         report.ratio < threshold ? 1 : 0
       end
 
-      # ADR-63 Tier 2 — the mutation-effectiveness deep dive. Builds the RBS
-      # environment + project pre-pass once (the warm loop), then re-analyses
-      # each target file's mutants against its clean baseline. Defaults to the
-      # git-changed `.rb` files; explicit paths override (and enable the
-      # whole-project opt-in, which is minutes).
-      def run_mutation_protection(options)
-        explicit = collect_paths(@argv, command_name: "coverage")
-        return CLI::EXIT_USAGE if explicit.nil?
-
-        target_files = explicit.empty? ? changed_ruby_files : explicit
-        if target_files.empty?
-          @out.puts("No changed Ruby files to measure — pass paths to measure explicitly.")
-          return 0
-        end
-
-        report = scan_mutation_protection(target_files, options)
-        MutationProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
-        determine_protection_exit(report, options)
-      end
-
-      def scan_mutation_protection(paths, options)
-        configuration = Configuration.load(options.fetch(:config))
-        context = LanguageServer::ProjectContext.new(configuration: configuration)
-        scanner = Protection::MutationScanner.new(
-          configuration: configuration, environment: context.environment, project_scan: context.project_scan
-        )
-        accumulator = MutationProtectionAccumulator.new
-
-        paths.each { |path| scan_mutation_one(path, scanner, accumulator, configuration) }
-        accumulator.to_report
-      end
-
-      def scan_mutation_one(path, scanner, accumulator, configuration)
-        source = File.read(path)
-        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
-        if parse_result.errors.any?
-          accumulator.record_parse_error(path, parse_result.errors)
-          return
-        end
-
-        accumulator.absorb(scanner.scan_file(path, source: source))
-      end
-
-      # The git-changed (modified / added / untracked) `.rb` files that exist on
-      # disk — the default Tier 2 scope. Returns [] outside a git work tree or
-      # when git is unavailable; the caller then reports "nothing to measure".
-      def changed_ruby_files
-        output = git_status_porcelain
-        return [] if output.nil?
-
-        output.each_line.filter_map { |line| changed_path(line) }.uniq.select { |p| File.file?(p) }
-      end
-
-      # Parse one `git status --porcelain` line (`XY <path>`, or `R  old -> new`)
-      # into a candidate `.rb` path, or nil.
-      def changed_path(line)
-        path = line[3..]&.chomp
-        return nil if path.nil? || path.empty?
-
-        path = path.split(" -> ", 2).last if path.include?(" -> ")
-        path = path.delete_prefix('"').delete_suffix('"')
-        path.end_with?(".rb") ? path : nil
-      end
-
-      def git_status_porcelain
-        output = IO.popen(%w[git status --porcelain --untracked-files=all], err: File::NULL, &:read)
-        $CHILD_STATUS&.success? ? output : nil
-      rescue SystemCallError
-        nil
-      end
-
       def usage_error
         @err.puts("coverage: at least one path is required")
         @err.puts(USAGE)

data/lib/rigor/cli/coverage_mutation.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "English"
+require "prism"
+
+module Rigor
+  class CLI
+    # ADR-63 Tier 2 + ADR-70 — the mutation-effectiveness and fused static∪dynamic
+    # protection paths, factored out of {CoverageCommand} to keep that command
+    # focused on dispatch. Mixed in, so each method runs in the command instance
+    # (using `@out` / `@err` / `@argv` / `collect_paths` / `determine_protection_exit`
+    # and the Protection + LanguageServer collaborators the command requires).
+    module CoverageMutation
+      private
+
+      # ADR-63 Tier 2 — the mutation-effectiveness deep dive. Builds the RBS
+      # environment + project pre-pass once (the warm loop), then re-analyses
+      # each target file's mutants against its clean baseline. Defaults to the
+      # git-changed `.rb` files; explicit paths override (and enable the
+      # whole-project opt-in, which is minutes).
+      def run_mutation_protection(options)
+        explicit = collect_paths(@argv, command_name: "coverage")
+        return CLI::EXIT_USAGE if explicit.nil?
+
+        target_files = explicit.empty? ? changed_ruby_files : explicit
+        if target_files.empty?
+          @out.puts("No changed Ruby files to measure — pass paths to measure explicitly.")
+          return 0
+        end
+
+        note_sampling(options)
+        return run_fused_protection(target_files, options) if options[:with_tests]
+
+        report = scan_mutation_protection(target_files, options)
+        MutationProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        determine_protection_exit(report, options)
+      end
+
+      # A `--limit` sample makes the report an estimate (per-file ratios over a
+      # random N of the mutations). Say so on stderr — stdout stays clean for JSON.
+      def note_sampling(options)
+        return unless options[:limit]
+
+        @err.puts(
+          "coverage: sampling at most #{options[:limit]} mutations/file " \
+          "(seed #{options[:seed]}); ratios are estimates."
+        )
+      end
+
+      # ADR-70 — the fused static∪dynamic deep dive. The type pass is the ADR-63
+      # Tier 2 warm loop; each type-survivor is then run against the project's
+      # test suite (the runner hook). The suite MUST pass on clean code first, or
+      # "a mutant survived" is meaningless — abort with a clear message if not.
+      def run_fused_protection(paths, options)
+        configuration = Configuration.load(options.fetch(:config))
+        test_oracle = Protection::TestSuiteOracle.new(command: options.fetch(:test_command))
+        return suite_not_green_error(options) unless test_oracle.green?
+
+        context = LanguageServer::ProjectContext.new(configuration: configuration)
+        scanner = Protection::MutationScanner.new(
+          configuration: configuration, environment: context.environment, project_scan: context.project_scan,
+          limit: options[:limit], seed: options[:seed],
+          site_selector: options[:include_dynamic] ? :all : :biteable
+        )
+        accumulator = FusedProtectionAccumulator.new
+        paths.each { |path| scan_fused_one(path, scanner, accumulator, test_oracle, configuration) }
+        report = accumulator.to_report
+        FusedProtectionRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        determine_protection_exit(report, options)
+      end
+
+      def scan_fused_one(path, scanner, accumulator, test_oracle, configuration)
+        source = File.read(path)
+        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
+        if parse_result.errors.any?
+          accumulator.record_parse_error(path, parse_result.errors)
+          return
+        end
+
+        accumulator.absorb(scanner.scan_file_fused(path, source: source, test_oracle: test_oracle))
+      end
+
+      def suite_not_green_error(options)
+        @err.puts(
+          "coverage: the test suite must pass on clean code to measure test protection " \
+          "(ran: #{options.fetch(:test_command).join(' ')})"
+        )
+        @err.puts(
+          "  the command must exit 0 on a clean tree. A non-zero exit on otherwise-passing " \
+          "tests also trips this — e.g. a SimpleCov coverage floor on a file-scoped run; " \
+          "point --test-command at a plain pass/fail runner."
+        )
+        1
+      end
+
+      def scan_mutation_protection(paths, options)
+        configuration = Configuration.load(options.fetch(:config))
+        context = LanguageServer::ProjectContext.new(configuration: configuration)
+        scanner = Protection::MutationScanner.new(
+          configuration: configuration, environment: context.environment, project_scan: context.project_scan,
+          limit: options[:limit], seed: options[:seed]
+        )
+        accumulator = MutationProtectionAccumulator.new
+
+        paths.each { |path| scan_mutation_one(path, scanner, accumulator, configuration) }
+        accumulator.to_report
+      end
+
+      def scan_mutation_one(path, scanner, accumulator, configuration)
+        source = File.read(path)
+        parse_result = Prism.parse(source, filepath: path, version: configuration.target_ruby)
+        if parse_result.errors.any?
+          accumulator.record_parse_error(path, parse_result.errors)
+          return
+        end
+
+        accumulator.absorb(scanner.scan_file(path, source: source))
+      end
+
+      # The git-changed (modified / added / untracked) `.rb` files that exist on
+      # disk — the default Tier 2 scope. Returns [] outside a git work tree or
+      # when git is unavailable; the caller then reports "nothing to measure".
+      def changed_ruby_files
+        output = git_status_porcelain
+        return [] if output.nil?
+
+        output.each_line.filter_map { |line| changed_path(line) }.uniq.select { |p| File.file?(p) }
+      end
+
+      # Parse one `git status --porcelain` line (`XY <path>`, or `R  old -> new`)
+      # into a candidate `.rb` path, or nil.
+      def changed_path(line)
+        path = line[3..]&.chomp
+        return nil if path.nil? || path.empty?
+
+        path = path.split(" -> ", 2).last if path.include?(" -> ")
+        path = path.delete_prefix('"').delete_suffix('"')
+        path.end_with?(".rb") ? path : nil
+      end
+
+      def git_status_porcelain
+        output = IO.popen(%w[git status --porcelain --untracked-files=all], err: File::NULL, &:read)
+        $CHILD_STATUS&.success? ? output : nil
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end