saboteur 0.7.0 → 0.8.0

data/lib/saboteur/selection/coverage_map.rb

@@ -17,28 +17,57 @@ module Saboteur
     # to every test in the file of the next test that starts. Each test's
     # duration is recorded so selected tests can run fastest first.
     class CoverageMap
-      FORMAT = 8
+      FORMAT = 11
 
       RAN_AT_LOAD = "ran at load: the code ran while the app loaded; a forked test cannot observe a change here"
 
-      attr_reader :lines, :tests, :build_seconds, :durations, :methods, :load_lines, :branches
+      attr_reader :lines, :tests, :build_seconds, :loaded_files, :durations, :methods, :load_lines, :load_methods,
+                  :branches
 
       # lines: { "/abs/file.rb" => { 12 => ["id1", "id2"] } }
       # methods: { "/abs/file.rb" => { 12 => ["id1", "id2"] } } keyed by the
       # def's first line; line coverage never counts an endless def's body,
       # so methods carry those subjects (issue #107).
       # durations: { "id1" => seconds }
-      def initialize(lines:, tests:, build_seconds: nil, durations: {}, methods: {}, load_lines: {}, branches: {})
+      def initialize(lines:, tests:, build_seconds: nil, durations: {}, methods: {}, load_lines: {}, load_methods: {},
+                     branches: {}, loaded_files: nil)
         @lines = lines
         @tests = tests
         @build_seconds = build_seconds
         @durations = durations
         @methods = methods
         @load_lines = load_lines
+        @load_methods = load_methods
         @branches = branches
+        @loaded_files = loaded_files || []
+      end
+
+      # Source files the given tests touched, sorted and deduped: the
+      # dependency set a cached verdict must watch (#197). The inversion is
+      # built once per map and memoized.
+      def files_for(test_ids)
+        by_test = @files_by_test ||= invert_coverage
+        test_ids.flat_map { |id| by_test.fetch(id, []) }.uniq.sort
+      end
+
+      # { test id => [source files it touched] }, built once per map. Line
+      # and method coverage both count: an endless def's file has only
+      # method evidence (#107), and a change there must still invalidate (#344).
+      def invert_coverage
+        [lines, methods].each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |hits, acc|
+          hits.each { |file, line_tests| line_tests.each_value { |ids| ids.each { |id| acc[id] << file } } }
+        end
+      end
+
+      # Files that ran while the app loaded: their state precedes every
+      # test, so every cached verdict depends on them (#344).
+      def boot_files
+        load_lines.keys.sort
       end
 
       def tests_for(subject)
+        return tests_for_constant(subject) if subject.is_a?(ConstantSubject)
+
         tests = tests_for_lines(subject.file, subject.coverage_lines)
         return tests unless tests.empty?
 
@@ -50,10 +79,33 @@ module Saboteur
         sort_test_ids(ids)
       end
 
+      # A constant is observable wherever it is read: the tests that ran
+      # any read of it, across every file the consumer scan found (#306).
+      # A read inside an endless def has no line coverage, so its def's
+      # per-test method-call counter stands in (#319).
+      def tests_for_constant(subject)
+        ids = subject.consumer_lines.flat_map { |file, lines| tests_for_lines(file, lines) }
+        ids += subject.consumer_defs.flat_map do |file, def_lines|
+          by_method = methods[CoverageMap.canonical(file)]
+          by_method ? def_lines.flat_map { |line| by_method.fetch(line, []) } : []
+        end
+        sort_test_ids(ids.uniq)
+      end
+
       # Attach the parent's boot counters without losing the child's method coverage.
-      def with_load_lines(load_lines)
+      def with_load_lines(load_lines, load_methods = {})
         self.class.new(lines: lines, tests: tests, build_seconds: build_seconds, durations: durations,
-                       methods: methods, load_lines: load_lines, branches: branches)
+                       methods: methods, load_lines: load_lines, load_methods: load_methods, branches: branches,
+                       loaded_files: loaded_files)
+      end
+
+      # A def the boot called (a def-time macro's class-body caller, say)
+      # and no test or hook called again: re-evaluating it post-boot
+      # changes nothing a selected test can observe, because closure
+      # consumers captured the pristine definition (#409).
+      def called_only_at_load?(file, line)
+        file = CoverageMap.canonical(file)
+        load_methods.fetch(file, []).include?(line) && methods.fetch(file, {}).fetch(line, []).empty?
       end
 
       # A requested line ran at load but no test later hit it.
@@ -69,6 +121,11 @@ module Saboteur
       # "no coverage" skip, but a subject whose lines never record at all
       # (an endless def) falls back to its method coverage (issue #107).
       def tests_for_edit(subject, line_numbers)
+        # An edit to a constant literal is observable at every read of the
+        # constant, not on the literal's own (load-time) lines: narrowing
+        # by edit lines is meaningless (#306).
+        return tests_for(subject) if subject.is_a?(ConstantSubject)
+
         tests = tests_for_lines(subject.file, line_numbers)
         return tests unless tests.empty?
         return [] unless tests_for_lines(subject.file, subject.coverage_lines).empty?
@@ -100,6 +157,17 @@ module Saboteur
         [lines, methods, load_lines].all? { |hits| hits.none? { |_file, values| values.any? } }
       end
 
+      # True when none of these files recorded a line hit, a method call, or
+      # a load-time hit. The recorder's map also holds the suite's spec
+      # files, so whole-map emptiness cannot tell a build that recorded test
+      # code only while the included files stayed dark.
+      def empty_for?(files)
+        wanted = files.map { |file| CoverageMap.canonical(file) }
+        [lines, methods, load_lines].all? do |hits|
+          wanted.none? { |file| hits[file]&.any? }
+        end
+      end
+
       # Tests that executed any of the lines, fastest first (suite order breaks
       # ties), no duplicates. With fail-fast, a mutant is killed by its
       # cheapest killing test.
@@ -124,15 +192,19 @@ module Saboteur
           hits.transform_values { |by_line| by_line.to_h { |line, ids| [line.to_s, ids.map { |id| index.fetch(id) }] } }
         end
         JSON.generate(format: FORMAT, tests: tests, build_seconds: build_seconds, lines: encode.call(lines),
-                      methods: encode.call(methods), load_lines: load_lines,
+                      methods: encode.call(methods), load_lines: load_lines, load_methods: load_methods,
                       branches: encode_branches(index),
-                      durations: tests.map { |id| durations[id]&.round(6) })
+                      durations: tests.map { |id| durations[id]&.round(6) }, loaded_files: loaded_files)
       end
 
       def self.from_json(json)
         data = JSON.parse(json)
         raise Error, "coverage map format #{data['format']} is not #{FORMAT}" unless data["format"] == FORMAT
 
+        from_data(data)
+      end
+
+      def self.from_data(data)
         tests = data["tests"]
         decode = lambda do |hits|
           hits.transform_values do |by_line|
@@ -140,10 +212,14 @@ module Saboteur
           end
         end
         durations = tests.zip(data["durations"]).to_h.compact
-        load_lines = (data["load_lines"] || {}).transform_values { |list| list.map(&:to_i) }
         new(lines: decode.call(data["lines"]), tests: tests, build_seconds: data["build_seconds"],
-            durations: durations, methods: decode.call(data["methods"] || {}), load_lines: load_lines,
-            branches: decode_branches(data.fetch("branches", {}), tests))
+            durations: durations, methods: decode.call(data["methods"] || {}),
+            load_lines: int_lists(data, "load_lines"), load_methods: int_lists(data, "load_methods"),
+            branches: decode_branches(data.fetch("branches", {}), tests), loaded_files: data["loaded_files"])
+      end
+
+      def self.int_lists(data, key)
+        (data[key] || {}).transform_values { |list| list.map(&:to_i) }
       end
 
       def self.decode_branches(branches, tests)
@@ -168,6 +244,25 @@ module Saboteur
         File.expand_path(path)
       end
 
+      # Every spelling the root can have in $LOADED_FEATURES: a symlink on
+      # the root path (macOS /var -> /private/var) gives the same directory
+      # both the resolved and the spelled form, and canonical() resolves a
+      # loaded feature only while its file exists. Match membership against
+      # both, each with a trailing slash so prefix siblings stay out.
+      def self.root_prefixes(root)
+        [File.realpath(root), File.expand_path(root)].uniq.map { |path| "#{path}/" }
+      end
+
+      # The dependency universe a cached verdict watches when coverage
+      # cannot speak: every project file the booted process loaded, plus
+      # the run's own files (#344).
+      def self.loaded_project_files(files, prefixes:)
+        $LOADED_FEATURES.filter_map do |file|
+          path = Text.utf8_strict(canonical(file))
+          path if path.end_with?(".rb") && prefixes.any? { |prefix| path.start_with?(prefix) }
+        end | files
+      end
+
       def self.load(path)
         from_json(Text.utf8_strict(File.read(path))) if File.file?(path)
       rescue JSON::ParserError, Error

data/lib/saboteur/selection/dependency_shield.rb

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Selection
+    # Dependency trees are never changed source (#504): a vendored bundle
+    # or node_modules, tracked or untracked, git-ignored or not, is
+    # rejected at enumeration, so --since never lists, reads or warns on
+    # it. The project-local bundler path (.bundle/config's BUNDLE_PATH)
+    # joins the shield when set - the standard CI layout vendor/bundle is
+    # already under vendor/. The config file itself is project
+    # configuration, not vendored source, and stays visible.
+    module DependencyShield
+      TREES = %w[vendor/ node_modules/].freeze
+      BUNDLER_CONFIG = ".bundle/config"
+
+      module_function
+
+      def reject_trees(paths, root)
+        bundler = bundler_path(root)
+        paths.reject do |path|
+          next false if path == BUNDLER_CONFIG
+
+          TREES.any? { |tree| path.start_with?(tree) } || (bundler && path.start_with?(bundler))
+        end
+      end
+
+      # .bundle/config's BUNDLE_PATH as a relative directory prefix, or
+      # nil when no project-local config sets one (an absolute path is the
+      # system bundle, outside the tree, so nothing to shield).
+      def bundler_path(root)
+        config = File.join(root, ".bundle", "config")
+        return unless File.file?(config)
+
+        line = File.foreach(config).find { |entry| entry.start_with?("BUNDLE_PATH:") }
+        return unless line
+
+        value = scalar(line.split(":", 2).last.strip)
+        return if value.empty?
+
+        # BUNDLE_PATH: . (or ./) is the project root itself - the empty
+        # prefix would match every path and shield the whole tree (#580) -
+        # and anything outside the root is the system bundle, not project
+        # source. The prefix is the normalized path, not the raw scalar:
+        # ./deps/../deps shields deps/.
+        base = File.expand_path(root)
+        expanded = File.expand_path(value, base)
+        return if expanded == base || !expanded.start_with?("#{base}/")
+
+        "#{expanded.delete_prefix("#{base}/")}/"
+      # ArgumentError too: a NUL byte in the value makes File.expand_path
+      # raise it, and a config that cannot be read means no shield.
+      rescue SystemCallError, ArgumentError
+        nil
+      end
+
+      # The scalar after "BUNDLE_PATH:": bundler writes a bare word, but
+      # YAML also allows it quoted - surrounding matching quotes are not
+      # part of the path.
+      def scalar(raw)
+        quote = raw[0]
+        value = if raw.length >= 2 && raw[-1] == quote && ["'", '"'].include?(quote)
+                  raw[1..-2]
+                else
+                  raw
+                end
+        strip_comment(value)
+      end
+
+      # Bundler::YAMLSerializer#strip_comment, which parses .bundle/config
+      # for Bundler itself: a # after the first character starts a comment
+      # even inside quotes, while a leading # is data.
+      def strip_comment(value)
+        return value unless value.include?("#") && !value.start_with?("#")
+
+        value.split("#", 2).first.strip
+      end
+    end
+  end
+end

data/lib/saboteur/selection/external_test_map.rb

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Selection
+    # The --test-command mode has no coverage map (#140): the command runs
+    # the whole suite per mutant, so every subject reads as covered by the
+    # one pseudo-test and no recorded timing exists, leaving the per-mutant
+    # timeout to the config's baseline_timeout.
+    class ExternalTestMap
+      def tests = [Execution::ExternalRunner::PSEUDO_TEST]
+
+      def tests_for(_subject) = tests
+
+      def tests_for_edit(_subject, _lines) = tests
+
+      def tests_for_branches(_subject, _edits) = tests
+
+      def ran_at_load?(_file, _lines) = false
+
+      # No boot happens in this mode, so nothing can have run only at load.
+      def called_only_at_load?(_file, _line) = false
+
+      def recorded_runtime(_tests) = nil
+    end
+  end
+end

data/lib/saboteur/selection/git_diff.rb

@@ -3,6 +3,8 @@
 
 require "open3"
 require_relative "../text"
+require_relative "dependency_shield"
+require_relative "layout_only_lines"
 require_relative "untracked_changes"
 
 module Saboteur
@@ -11,7 +13,7 @@ module Saboteur
     # changes, as { "/abs/path.rb" => Set[line numbers in the current file] }.
     module GitDiff
       NO_FILE = "/dev/null" # rubocop:disable Style/FileNull -- literal in git diff output
-      HUNK = /\A@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/
+      HUNK = /\A@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
 
       module_function
 
@@ -41,7 +43,61 @@ module Saboteur
         status.success? ? out.b : nil
       end
 
+      # Paths under ROOT, relative to it, that differ between the merge base
+      # of REF and the working tree: { present: [...], deleted: [...] }.
+      # present holds added, modified and untracked files; deleted holds
+      # files gone from the working tree. A rename counts as a deletion of
+      # the old path and an addition of the new one.
+      def changed_paths(ref, root:)
+        verify_ref!(ref, root: root)
+        base = merge_base(ref, root: root)
+        diff = %w[diff -z --name-only --relative --no-renames]
+        {
+          # An untracked file is never in the diff, so the two lists are disjoint.
+          present: DependencyShield.reject_trees(names(root, *diff, "--diff-filter=d", base, "--") +
+                                                 names(root, "ls-files", "-z", "--others",
+                                                       "--exclude-standard"), root).sort,
+          deleted: DependencyShield.reject_trees(names(root, *diff, "--diff-filter=D", base, "--"),
+                                                 root).sort
+        }
+      end
+
+      def names(root, *args)
+        git(root, *args).b.split("\0").map { |name| Text.utf8_identity(name) }
+      end
+
+      # The two line maps of a --since diff (#313). changed holds every line
+      # the text diff touches: subject admission and the formatting-only
+      # skip read it, so a method that was only re-indented is still found
+      # and reported as unchanged. behavior drops the layout-only lines:
+      # only it narrows a changed method's fine-grained mutants.
+      LineMaps = Data.define(:changed, :behavior)
+
       def changed_lines(ref, root:, include: nil, diagnostics: nil)
+        line_maps(ref, root: root, include: include, diagnostics: diagnostics).changed
+      end
+
+      # Tracked files whose diff deletes lines without adding any, as
+      # canonical absolute paths (realpath'd toplevel joined to each diff
+      # path), so callers compare in the same space as
+      # CoverageMap.canonical keys whatever the project-root layout: a
+      # monorepo root below the git toplevel must not silently disable the
+      # exclusion (#484). A pure deletion adds no new code to mutate - the
+      # change itself is what the suite covers - so the file yields no
+      # subject and no fine-grained mutant, and a spec-less such file must
+      # not stop the run. The neighbor lines a pure deletion touches
+      # (touched_lines) are context, not change. Untracked files are
+      # all-additions and never listed.
+      def deletion_only_files(ref, root:) # rubocop:disable Metrics/ModuleLength -- one focused addition to an exactly-full module
+        top = File.realpath(Text.utf8_identity(git(root, "rev-parse", "--show-toplevel").b.strip))
+        diff = git(root, "-c", "core.quotePath=false", "diff", "--unified=0", "--no-color", "--no-ext-diff",
+                   merge_base(ref, root: root), "--").b
+        added = Hash.new { |hash, file| hash[file] = false }
+        each_hunk(diff, top) { |file, (_, _, _, count)| added[file] ||= count.positive? }
+        added.reject { |_, yes| yes }.keys
+      end
+
+      def line_maps(ref, root:, include: nil, diagnostics: nil)
         verify_ref!(ref, root: root)
         base = merge_base(ref, root: root)
         # Root and paths are filesystem identity: strip as bytes and retag
@@ -49,14 +105,30 @@ module Saboteur
         # would rename a raw-byte path). Parse the diff body as bytes and
         # tag each extracted path UTF-8 at the boundary.
         top = Text.utf8_identity(git(root, "rev-parse", "--show-toplevel").b.strip)
-        changes = parse(git(root, "-c", "core.quotePath=false", "diff", "--unified=0", "--no-color",
-                            "--no-ext-diff", base, "--").b, top)
+        diff = %w[-c core.quotePath=false diff --unified=0 --no-color --no-ext-diff]
+        changes = parse(git(root, *diff, base, "--").b, top)
         UntrackedChanges.union(changes, top, include: include, diagnostics: diagnostics)
-        changes
+        behavior = drop_layout_only_lines(changes, git(root, *diff, "--ignore-space-change", base, "--").b, base,
+                                          top, include: include)
+        LineMaps.new(changed: changes, behavior: behavior)
       end
 
       def parse(diff, top)
         changes = Hash.new { |hash, file| hash[file] = Set.new }
+        each_hunk(diff, top) { |file, (_, _, start, count)| changes[file].merge(touched_lines(start, count)) }
+        changes.default_proc = nil
+        changes
+      end
+
+      # The new-side lines a hunk touches. A pure deletion touches the lines
+      # on either side of it.
+      def touched_lines(start, count)
+        count.zero? ? [start, start + 1] : (start...(start + count)).to_a
+      end
+
+      # Each hunk header of a zero-context diff as the absolute path of the
+      # file and [old_start, old_count, new_start, new_count].
+      def each_hunk(diff, top)
         file = nil
         diff.each_line do |line|
           if line.start_with?("+++ ")
@@ -65,15 +137,25 @@ module Saboteur
           # HUNK is anchored, so a non-hunk line - including a raw-byte
           # content line - fails the match at its first byte.
           elsif file && (match = HUNK.match(line))
-            start = match[1].to_i
-            count = (match[2] || "1").to_i
-            # A pure deletion touches the lines on either side of it.
-            lines = count.zero? ? [start, start + 1] : (start...(start + count)).to_a
-            changes[file].merge(lines)
+            old_start, old_count, new_start, new_count = match.captures
+            yield file, [old_start.to_i, (old_count || "1").to_i, new_start.to_i, (new_count || "1").to_i]
           end
         end
-        changes.default_proc = nil
-        changes
+      end
+
+      # Only files the run could mutate are lexed; a file new at the base
+      # has nothing to compare with and keeps every line.
+      def drop_layout_only_lines(changes, spaced_diff, base, top, include:)
+        hunks = Hash.new { |hash, file| hash[file] = [] }
+        each_hunk(spaced_diff, top) { |file, hunk| hunks[file] << hunk }
+        changes.to_h do |file, lines|
+          mutable = include.nil? || include.include?(file)
+          base_source = mutable && file_at(base, file.delete_prefix("#{top}/"), root: top)
+          next [file, lines] unless base_source
+
+          [file, LayoutOnlyLines.new(hunks[file], base_source: base_source, current_source: File.binread(file))
+                                .restrict(lines)]
+        end
       end
 
       ESCAPES = { "n" => "\n", "t" => "\t", '"' => '"', "\\" => "\\", "a" => "\a", "b" => "\b",

data/lib/saboteur/selection/layout_only_lines.rb

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+
+module Saboteur
+  module Selection
+    # Drops changed lines whose only change is layout (#313). Wrapping
+    # existing statements in a block re-indents them; a plain diff marks
+    # every one as changed, so their mutants run as if the change touched
+    # them.
+    #
+    # A whitespace-insensitive diff (git diff -b) finds the lines that
+    # differ by more than spacing and pairs every other line with its line
+    # at the base. A changed line outside that diff is dropped only when
+    # Prism lexes it to the same tokens as its base line: whitespace inside
+    # a string, heredoc or regexp is part of a token, so it still counts as
+    # a change. A `__LINE__` on a line that moved names another number, so
+    # that line counts too.
+    class LayoutOnlyLines
+      LINE_KEYWORD = :KEYWORD___LINE__
+
+      # hunks: [[old_start, old_count, new_start, new_count], ...] of the
+      # whitespace-insensitive diff of one file, in order.
+      def initialize(hunks, base_source:, current_source:)
+        @hunks = hunks
+        @base_tokens = tokens_by_line(base_source)
+        @current_tokens = tokens_by_line(current_source)
+      end
+
+      # The -b diff's own lines, with its deletion markers, plus every line
+      # of CHANGED whose tokens differ from its base line.
+      def restrict(changed)
+        spaced_lines | changed.reject { |line| same_tokens?(line) }
+      end
+
+      private
+
+      def spaced_lines
+        @hunks.each_with_object(Set.new) do |(_, _, start, count), lines|
+          lines.merge(GitDiff.touched_lines(start, count))
+        end
+      end
+
+      def same_tokens?(line)
+        base_line = base_line_of(line)
+        tokens = @current_tokens[line]
+        return false if base_line != line && tokens.any? { |type, _| type == LINE_KEYWORD }
+
+        tokens == @base_tokens[base_line]
+      end
+
+      # A line outside every hunk sits at its base position shifted by the
+      # lines the hunks above it added or removed. A line inside a hunk is
+      # one of the -b diff's own lines and is kept whatever this answers.
+      def base_line_of(line)
+        line - @hunks.sum { |_, old_count, start, count| start + count <= line ? count - old_count : 0 }
+      end
+
+      # Every token on each line it spans, as type and text. Every line has
+      # one (a blank line its newline, text after __END__ that token), and a
+      # missing line reads as [] through the default. A token that
+      # spans lines (a heredoc body, a multi-line string) belongs to each.
+      # A token's location ends after its last byte, so one that ends in a
+      # newline would reach into the next line without this.
+      def tokens_by_line(source)
+        Prism.lex(source).value.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |(token, _), lines|
+          next if token.type == :EOF
+
+          token.location.start_line.upto(last_line(token)) { |line| lines[line] << [token.type, token.value] }
+        end
+      end
+
+      def last_line(token)
+        location = token.location
+        token.value.end_with?("\n") ? location.end_line - 1 : location.end_line
+      end
+    end
+  end
+end

data/lib/saboteur/selection/recorder.rb

@@ -25,7 +25,7 @@ module Saboteur
 
       def start
         Coverage.resume if Coverage.state == :suspended
-        Coverage.result(stop: false, clear: true)
+        CoverageReads.result(stop: false, clear: true)
       end
 
       def test_started(id, test_file)
@@ -44,14 +44,15 @@ module Saboteur
         end
       end
 
-      def result(build_seconds: nil)
+      def result(build_seconds: nil, loaded_files: [])
         assign_outside(@outside, @lines)
         assign_outside(@outside_methods, @methods)
         assign_outside(@outside_branches, @branches)
         lines = @lines.transform_values { |by_line| by_line.transform_values(&:uniq) }
         methods = @methods.transform_values { |by_line| by_line.transform_values(&:uniq) }
+        branches = @branches.transform_values { |arms| arms.transform_values(&:uniq) }
         CoverageMap.new(lines: lines, tests: @tests, build_seconds: build_seconds, durations: @durations,
-                        methods: methods, branches: @branches.transform_values { |arms| arms.transform_values(&:uniq) })
+                        methods: methods, branches: branches, loaded_files: loaded_files)
       end
 
       private
@@ -65,8 +66,15 @@ module Saboteur
 
       def record_branches(file, data)
         data.fetch(:branches, {}).each do |(_kind, _id, *parent_span), arms|
+          spans = arms.map { |(_arm_kind, _arm_id, *span), _count| span }
           arms.each do |(_arm_kind, _arm_id, *span), count|
             next if span == parent_span
+            # Ruby spans a `when X` arm with a bare `nil` body from the
+            # `when` to the case's end, containing the sibling arms.
+            # Sibling arms are disjoint by definition, so a containing span
+            # is bogus; recording it would let it intersect and narrow
+            # selection for edits inside the siblings it swallows.
+            next if spans.any? { |other| span != other && contains?(span, other) }
 
             @branches[file][span] # Keep zero-hit arms as evidence, not as covered code.
             yield span if count.positive?
@@ -74,6 +82,16 @@ module Saboteur
         end
       end
 
+      # [line, column] pairs compare lexically, like CoverageMap#position.
+      # Both endpoints come from one slice per side: a separate slice per
+      # comparand would make its size irrelevant on the right-hand side of
+      # `<=>` (a prefix decides first), hiding an equivalent mutant.
+      def contains?(outer, inner)
+        outer_start, inner_start = [outer, inner].map { |span| span.first(2) }
+        inner_end, outer_end = [inner, outer].map { |span| span.last(2) }
+        (outer_start <=> inner_start) <= 0 && (inner_end <=> outer_end) <= 0
+      end
+
       def hit_table
         Hash.new { |hash, file| hash[file] = Hash.new { |by_line, line| by_line[line] = [] } }
       end
@@ -89,7 +107,7 @@ module Saboteur
       # Coverage is suspended while the delta is processed, so the recorder's
       # own work (and anything it calls) is never attributed to a test.
       def each_hit
-        snapshot = Coverage.result(stop: false, clear: true)
+        snapshot = CoverageReads.result(stop: false, clear: true)
         suspended = Coverage.running?
         Coverage.suspend if suspended
         snapshot.each do |path, data|

data/lib/saboteur/selection/source_scope.rb

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  module Selection
+    # Positional source-scope arguments from the command line.
+    module SourceScope
+      module_function
+
+      # "One --test, several paths" lands the extra paths in the source
+      # scope; specs are never subjects, so the run would mutate nothing
+      # and still exit 0. Refuse them as a usage error before any boot.
+      def verify_no_specs!(paths)
+        spec_files = paths.select { |path| path.end_with?("_spec.rb") }
+        return if spec_files.empty?
+
+        raise ConfigError,
+              "spec files are not mutated - pass them with --test, one path per use: #{spec_files.join(', ')}"
+      end
+    end
+  end
+end