saboteur 0.3.0 → 0.5.0

data/lib/saboteur/engine/run_fingerprint.rb

@@ -3,6 +3,7 @@
 
 require "digest"
 require "json"
+require_relative "data_inputs"
 
 module Saboteur
   class Engine
@@ -11,8 +12,8 @@ module Saboteur
     class RunFingerprint
       FORMAT_VERSION = 1
       MANIFESTS = %w[Gemfile gems.rb Gemfile.lock gems.locked .rspec .rspec-local].freeze
-      LOCATION_SETTINGS = %w[cache_dir json_report html_report].freeze
-      ENTRY_KINDS = %w[ruby manifest boot hook source_plugin extra].freeze
+      LOCATION_SETTINGS = %w[cache_dir json_report html_report score_history].freeze
+      ENTRY_KINDS = %w[ruby manifest boot hook source_plugin extra data].freeze
       EXCLUDED_DIRECTORIES = %w[.git vendor node_modules].freeze
       Entry = Data.define(:path, :kind, :state, :sha256, :required)
       Change = Data.define(:path, :reason)
@@ -178,11 +179,14 @@ module Saboteur
       end
 
       def output_overlap_issues
-        paths = required_files.map(&:first) + MANIFESTS.map { |name| File.join(@root, name) }
-        outputs = %w[json_report html_report].filter_map { |key| @config.fetch(key) }
-                                             .map { |path| canonical_path(path) }
+        paths = required_files.map(&:first) + MANIFESTS.map { |name| File.join(@root, name) } +
+                DataInputs.files(@root, extra: @config["fingerprint_extra"])
+        # Compare physical boundaries without changing declared inventory identities.
+        paths = paths.map { |path| canonical_path(path) }.uniq
+        outputs = %w[json_report html_report score_history].filter_map { |key| @config.fetch(key) }
+                                                           .map { |path| canonical_path(path) }
         issues = outputs.filter_map do |path|
-          if path.end_with?(".rb") || paths.include?(path) || File.directory?(path)
+          if path.end_with?(".rb") || paths.include?(path) || File.directory?(path) || data_input?(path)
             "output overlaps input: #{display_path(path)}"
           end
         end
@@ -192,24 +196,50 @@ module Saboteur
 
       def cache_overlap_issues(paths)
         cache = canonical_path(@config["cache_dir"])
-        protected = [@root] + %w[app lib spec].map { |name| File.join(@root, name) } + paths
-        overlaps = protected.any? do |path|
+        protected = [@root] + %w[app lib spec test/fixtures].map { |name| File.join(@root, name) } + paths
+        inside = protected.any? do |path|
           path == cache || path.start_with?("#{cache}/") || (path != @root && cache.start_with?("#{path}/"))
         end
+        overlaps = inside || data_input?(cache)
         overlaps ? ["cache directory overlaps inputs: #{display_path(cache)}"] : []
       end
 
+      # Declared fixture, schema or config input, or a path inside a fixture tree.
+      def data_input?(path)
+        DataInputs.match?(@root, path, extra: @config["fingerprint_extra"])
+      end
+
       def inventory(issues)
         paths = project_files(issues).to_h { |path| [path, "ruby"] }
         MANIFESTS.each { |name| paths[File.join(@root, name)] = "manifest" }
+        data_files(issues).each { |path| paths[path] ||= "data" }
         required = merged_required_files
         required.each { |path, (kind, _)| paths[path] = kind }
         paths.map do |path, kind|
-          needed = required.key?(path) ? required[path].last : kind != "manifest"
+          needed = required.key?(path) ? required[path].last : !%w[manifest data].include?(kind)
           read_entry(path, kind, needed, issues)
         end
       end
 
+      # Fixtures, schema dumps and database config. A pattern with no match is
+      # fine; a listed file that vanishes later shows up as "removed". Like Ruby
+      # files, data reached through a symlink (the file or a directory above it)
+      # is an undeclared boundary: its real path could be an output or lie outside
+      # the project, so the snapshot is incomplete instead of guessing.
+      def data_files(issues)
+        DataInputs.files(@root, extra: @config["fingerprint_extra"]).reject do |path|
+          next false unless symlinked?(path)
+
+          issues << "symlink input: #{display_path(path)}".freeze
+          true
+        end
+      end
+
+      def symlinked?(path)
+        current = @root
+        path.delete_prefix("#{@root}/").split("/").any? { |part| File.symlink?(current = File.join(current, part)) }
+      end
+
       def merged_required_files
         required_files.group_by(&:first).transform_values do |entries|
           roles = entries.map { |_, kind, _| kind }
@@ -240,7 +270,7 @@ module Saboteur
 
       def excluded?(path, name)
         EXCLUDED_DIRECTORIES.include?(name) || path == canonical_path(@config["cache_dir"]) ||
-          %w[json_report html_report].filter_map { |key| @config.fetch(key) }.any? do |output|
+          %w[json_report html_report score_history].filter_map { |key| @config.fetch(key) }.any? do |output|
             path == canonical_path(output)
           end
       end

data/lib/saboteur/engine/sandbox_policy.rb

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Saboteur
+  class Engine
+    # Decides what each mutant child's Landlock sandbox grants (#152), and
+    # notes once per run when the kernel cannot honor it.
+    class SandboxPolicy
+      def initialize(config:, root:, diagnostics:)
+        @config = config
+        @root = root
+        @diagnostics = diagnostics
+      end
+
+      # The third C1 layer (#152): each mutant child makes the project tree
+      # read-only except tmp/, the cache dir and the system temp dir. The
+      # claim needs Landlock ABI 3 (Linux 6.2+): earlier ABIs cannot restrict
+      # truncate(), so the run degrades honestly - children run with the
+      # guard and canary only, noted once - unless c.sandbox = "strict",
+      # which refuses instead.
+      def hook
+        return nil unless @config["sandbox"]
+
+        abi = sandbox_abi
+        return restrict_hook if abi >= 3
+
+        if @config["sandbox"] == "strict"
+          raise Error, "sandbox is strict but #{sandbox_gap(abi)}; refusing to run without the promised " \
+                       "sandbox - set c.sandbox = true to run degraded, or false to opt out"
+        end
+        # Once, through the report's warnings only: warn + inform printed the
+        # same line twice (D's review, #178).
+        unless @sandbox_note_given
+          @sandbox_note_given = true
+          @diagnostics.warn("sandbox is on but #{sandbox_gap(abi)}; children run with the hazard guard and canary only")
+        end
+        nil
+      end
+
+      # ENOSYS/EOPNOTSUPP are a clean "no Landlock here"; any other probe
+      # error (EPERM under seccomp, ...) must not silently run unsandboxed.
+      def sandbox_abi
+        Execution::Sandbox.abi_version
+      rescue SystemCallError => e
+        raise Error, "sandbox is on but the Landlock probe failed (#{e.message}); refusing to run " \
+                     "unsandboxed - set c.sandbox = false to proceed without it"
+      end
+
+      def sandbox_gap(abi)
+        return "this kernel lacks Landlock (needs Linux 6.2+)" if abi.zero?
+
+        "this kernel's Landlock ABI is #{abi} but ABI 3 (Linux 6.2+) is needed to restrict truncate()"
+      end
+
+      def restrict_hook
+        writable = sandbox_writable_dirs
+        ->(keep_fds) { Execution::Sandbox.restrict!(writable: writable, keep_fds: keep_fds) }
+      end
+
+      # c.sandbox_writable adds the dirs a suite genuinely needs (db/, log/,
+      # ...): without a grant, writes there fail with EACCES in the child.
+      def sandbox_writable_dirs
+        user_dirs = @config["sandbox_writable"].map { |dir| File.expand_path(dir, @root) }
+        dirs = [File.join(@root, "tmp"), @config.path("cache_dir")] + user_dirs
+        dirs.each { |dir| FileUtils.mkdir_p(dir) }
+        real = (dirs.map { |dir| File.realpath(dir) } + [File.realpath(Dir.tmpdir)]).uniq
+        check_sandbox_write_set(real, user_dirs.map { |dir| File.realpath(dir) })
+        real
+      end
+
+      # The effective write set - every grant realpath'd, cache_dir, the
+      # project tmp and the system temp dir included - must not contain the
+      # project root: cache_dir = ".", a tmp symlink or a checkout inside the
+      # system temp dir would otherwise leave the whole tree writable without
+      # a word. c.sandbox = "strict" refuses: strict guards the effective
+      # policy, not only the kernel ABI. A user grant containing another
+      # grant only makes the narrower one redundant, so that stays a warning.
+      def check_sandbox_write_set(all_dirs, user_dirs)
+        holder = all_dirs.find { |dir| path_contains?(dir, @root) }
+        if holder
+          message = "sandbox grant #{holder} contains the project root; mutant children can write the whole tree"
+          raise Error, %(#{message} - refusing under c.sandbox = "strict") if @config["sandbox"] == "strict"
+
+          @diagnostics.warn(message)
+        end
+        user_dirs.each do |dir|
+          (all_dirs - [dir]).each do |other|
+            next unless path_contains?(dir, other)
+
+            @diagnostics.warn("sandbox grant #{dir} contains the granted dir #{other}; " \
+                              "the narrower grant is redundant")
+          end
+        end
+      end
+
+      # Both sides are realpath'd, so a plain "#{dir}/" prefix test would miss
+      # dir == "/" (every path is under it; "//" prefixes nothing).
+      def path_contains?(dir, path)
+        return true if dir == "/"
+
+        path == dir || path.start_with?("#{dir}/")
+      end
+    end
+  end
+end

data/lib/saboteur/engine/scheduler.rb

@@ -7,16 +7,20 @@ module Saboteur
     # unit of work parallel workers will share out.
     #
     # Order of business: skip what cannot be run (refinements, not loaded,
-    # shadowed, no covering test); coarse mutants; fine mutants only if no
-    # coarse mutant survived; then check every kill and timeout against the
-    # unchanged method (VerdictCheck). Each mutant runs only the tests that
-    # executed its edit, likeliest killers first, with a timeout from those
-    # tests' recorded durations.
+    # shadowed, no covering test); coarse mutants; all eligible fine mutants;
+    # then check every kill and timeout against the unchanged method
+    # (VerdictCheck). Each mutant runs only the tests that executed its edit,
+    # likeliest killers first, with a timeout from their recorded durations.
     class Scheduler
+      WHOLE_FILE_HINT = "; add it to c.whole_file to re-evaluate the whole file"
+
       # A subject to run, with what its mutants need. killers counts the
       # tests that killed earlier mutants of this subject; slowdown is how
       # much slower than recorded its tests ran in a child (see calibrate).
-      Plan = Struct.new(:subject, :tests, :killers, :slowdown, keyword_init: true)
+      # wrapper names a known def-time wrapper (Execution::Wrapper), so the
+      # child re-evaluates it together with the def.
+      Plan = Struct.new(:subject, :tests, :killers, :slowdown, :wrapper,
+                        keyword_init: true)
 
       # Tests that killed more earlier mutants first; otherwise keep the order.
       def self.prioritize(tests, killers)
@@ -35,20 +39,24 @@ module Saboteur
       def call(subject, candidates)
         return [] if candidates.empty?
 
-        reason = subject.skip_reason || load_problem(subject)
+        reason, wrapper = subject.skip_reason ? [subject.skip_reason, nil] : load_problem(subject)
         return skip_all(candidates, subject, reason) if reason
+        if wrapper == :sorbet && !subject.sig_source
+          return skip_all(candidates, subject,
+                          "sorbet sig not found next to the def; cannot preserve runtime type checks")
+        end
 
         tests = @map.tests_for(subject)
-        return skip_all(candidates, subject, "no coverage") if tests.empty?
+        return unloadable(candidates, subject) if tests.empty?
 
-        plan = Plan.new(subject:, tests:, killers: Hash.new(0), slowdown: 1.0)
+        plan = Plan.new(subject:, tests:, killers: Hash.new(0), slowdown: 1.0, wrapper: wrapper)
         reused = all_reused(plan, candidates)
         return reused if reused
 
-        results = run_candidates(plan, candidates) do |mutation, text|
+        results = run_candidates(candidates) do |mutation, text|
           reuse(plan, mutation, text) || execute(plan, mutation, text)
         end
-        checked(subject, results)
+        checked(plan, results)
       end
 
       # The per-mutant timeout: timeout_factor times what the tests took
@@ -65,9 +73,11 @@ module Saboteur
 
       # Verdicts that did not hold up are warned about once per subject;
       # only checked verdicts are stored for --incremental.
-      def checked(subject, results)
+      def checked(plan, results)
+        subject = plan.subject
         run_unchanged = lambda do |tests, timeout|
-          @runner.run(subject: subject, text: subject.source, test_ids: tests, timeout: timeout)
+          @runner.run(subject: subject, text: subject.source, test_ids: tests, timeout: timeout,
+                      eval_prefix: eval_prefix(plan))
                  .tap { |outcome| note_leftovers(subject, "verdict check", outcome) }
         end
         check = VerdictCheck.new(run_unchanged: run_unchanged, baseline_timeout: @config["baseline_timeout"])
@@ -86,21 +96,13 @@ module Saboteur
         return nil unless @cache
 
         catch(:must_run) do
-          run_candidates(plan, candidates) { |mutation, text| reuse(plan, mutation, text) || throw(:must_run) }
+          run_candidates(candidates) { |mutation, text| reuse(plan, mutation, text) || throw(:must_run) }
         end
       end
 
-      def run_candidates(plan, candidates, &run_one)
+      def run_candidates(candidates, &run_one)
         coarse, fine = candidates.partition { |mutation, _| mutation.coarse }
         results = coarse.map { |mutation, text| run_one.call(mutation, text) }
-        # A surviving coarse mutant means nothing checks the body, so the fine
-        # mutants would only add noise. Not so when a rescue or else can
-        # return a value of its own: fine mutants that make the body raise
-        # can still be caught.
-        if results.any?(&:survived?) && !plan.subject.recovers?
-          return results + skip_all(fine, plan.subject, "coarse mutant survived", covered_by: plan.tests)
-        end
-
         results + fine.map { |mutation, text| run_one.call(mutation, text) }
       end
 
@@ -109,7 +111,7 @@ module Saboteur
         return nil unless @cache
 
         tests = tests_for(plan, mutation)
-        return skip_all([[mutation, text]], plan.subject, "no coverage").first if tests.empty?
+        return uncoverable(plan, mutation, text) if tests.empty?
 
         hit = @cache.lookup(plan.subject, mutation, tests)
         return nil unless hit
@@ -121,14 +123,14 @@ module Saboteur
 
       def execute(plan, mutation, text)
         tests = tests_for(plan, mutation)
-        return skip_all([[mutation, text]], plan.subject, "no coverage").first if tests.empty?
+        return uncoverable(plan, mutation, text) if tests.empty?
 
-        timeout = timeout_for(tests, plan.slowdown)
-        outcome = @runner.run(subject: plan.subject, text: text, test_ids: tests, timeout: timeout, mutation: mutation)
-        outcome = calibrate(plan, mutation, text, tests, timeout) if outcome.status == :timeout
+        outcome = run_mutant(plan, mutation, text, tests)
+        note_unreachable(plan, outcome) if outcome.status == :unreachable
         result = MutantResult.new(subject: plan.subject, mutation: mutation, status: outcome.status,
                                   mutated_source: text, reason: outcome.message, runtime: outcome.runtime,
-                                  killed_by: outcome.failed_ids, covered_by: tests, kill_cause: outcome.kill_cause)
+                                  killed_by: outcome.failed_ids, covered_by: tests, kill_cause: outcome.kill_cause,
+                                  executed: outcome.executed_ids)
         outcome.failed_ids.each { |id| plan.killers[id] += 1 }
         note_leftovers(plan.subject, "#{mutation.operator} #{result.digest}", outcome)
         @diagnostics.progress(result)
@@ -139,8 +141,12 @@ module Saboteur
       # body, so it gets every test of the method), prior killers first, then
       # fastest-first.
       def tests_for(plan, mutation)
+        return self.class.prioritize(plan.tests, plan.killers) if mutation.coarse
+
         line_numbers = mutation.edits.flat_map { |edit| plan.subject.coverage_lines_for(edit) }.uniq
-        tests = plan.tests & @map.tests_for_lines(plan.subject.file, line_numbers)
+        tests = plan.tests & @map.tests_for_edit(plan.subject, line_numbers)
+        branch_tests = @map.tests_for_branches(plan.subject, mutation.edits)
+        tests &= branch_tests if branch_tests
         self.class.prioritize(tests, plan.killers)
       end
 
@@ -148,6 +154,52 @@ module Saboteur
         [@config["timeout_factor"] * runtime, @config["timeout_min"]].max
       end
 
+      # What a subject no test ran gets. Code that only ran while the app
+      # loaded is not "no coverage" - it ran - but no forked test can re-run
+      # it, so it gets its own status, out of the score, with a hint.
+      def unloadable(candidates, subject, line_numbers = nil)
+        return skip_all(candidates, subject, "no coverage") unless
+          @map.ran_at_load?(subject.file, line_numbers || subject.coverage_lines)
+
+        candidates.map do |mutation, text|
+          MutantResult.new(subject: subject, mutation: mutation, status: :ran_at_load, mutated_source: text,
+                           reason: Selection::CoverageMap::RAN_AT_LOAD)
+        end
+      end
+
+      # One mutation whose edited lines no test ran (see unloadable).
+      def uncoverable(plan, mutation, text)
+        line_numbers = mutation.edits.flat_map { |edit| plan.subject.coverage_lines_for(edit) }.uniq
+        result, = unloadable([[mutation, text]], plan.subject, line_numbers)
+        return result if result.status == :ran_at_load
+        return result unless @map.tests_for_branches(plan.subject, mutation.edits) == []
+
+        skipped, = skip_all([[mutation, text]], plan.subject, "no coverage (branch not taken)")
+        skipped
+      end
+
+      def run_mutant(plan, mutation, text, tests)
+        timeout = timeout_for(tests, plan.slowdown)
+        outcome = @runner.run(subject: plan.subject, text: text, test_ids: tests, timeout: timeout,
+                              mutation: mutation, eval_prefix: eval_prefix(plan))
+        outcome.status == :timeout ? calibrate(plan, mutation, text, tests, timeout) : outcome
+      end
+
+      # Each mutant is checked separately: changing a body can change which
+      # definition a test reaches, so one unreachable verdict cannot skip later work.
+      def note_unreachable(plan, outcome)
+        @diagnostics.warn("#{plan.subject.id}: #{outcome.message}")
+      end
+
+      # The text a known def-time wrapper needs re-evaluated with the def.
+      # Sorbet's sig sits on the lines right before it; without it the def
+      # evaluates alone and runtime type checks silently drop for the child.
+      def eval_prefix(plan)
+        return nil unless plan.wrapper == :sorbet
+
+        plan.subject.sig_source
+      end
+
       # Recorded durations come from one warm process; a fresh child can be
       # slower (lazy loading, first queries). So a timeout is checked at
       # once: the unchanged method runs the same tests with
@@ -156,7 +208,7 @@ module Saboteur
       # the measured slowdown. A timeout that remains is the mutant's own.
       def calibrate(plan, mutation, text, tests, timeout)
         unchanged = @runner.run(subject: plan.subject, text: plan.subject.source, test_ids: tests,
-                                timeout: @config["baseline_timeout"])
+                                timeout: @config["baseline_timeout"], eval_prefix: eval_prefix(plan))
         note_leftovers(plan.subject, "timeout check", unchanged)
         return unchanged_failed(unchanged) unless unchanged.status == :survived
 
@@ -165,7 +217,8 @@ module Saboteur
         longer = deadline(unchanged.runtime)
         return Execution::Runner::Outcome.new(status: :timeout, runtime: timeout) if longer <= timeout
 
-        @runner.run(subject: plan.subject, text: text, test_ids: tests, timeout: longer, mutation: mutation)
+        @runner.run(subject: plan.subject, text: text, test_ids: tests, timeout: longer, mutation: mutation,
+                    eval_prefix: eval_prefix(plan))
       end
 
       def unchanged_failed(unchanged)
@@ -176,18 +229,28 @@ module Saboteur
       end
 
       # The method saboteur would redefine must be the one Ruby is running.
+      # Returns [skip reason, wrapper]: a known def-time wrapper (sorbet's
+      # sig is one, see Execution::Wrapper) is not a shadowing - the child
+      # re-evaluates it together with the def, so the check passes.
       def load_problem(subject)
+        return [nil, nil] if @reevaluator.whole_file?(subject)
+
         owner = @reevaluator.resolve_owner(subject)
         target = subject.singleton ? owner.singleton_class : owner
         method = own_method(target, subject.name)
-        return "method not loaded" unless method
+        return ["method not loaded", nil] unless method
 
         file, line = method.source_location
-        return nil if file && Selection::CoverageMap.canonical(file) == subject.file && line == subject.start_line
+        if file && Selection::CoverageMap.canonical(file) == subject.file && line == subject.start_line
+          return [nil, nil]
+        end
+
+        wrapper = Execution::Wrapper.around(method, file)
+        return [nil, wrapper] if wrapper
 
-        "shadowed definition (runtime method at #{file}:#{line})"
+        ["shadowed definition (runtime method at #{file}:#{line})#{WHOLE_FILE_HINT}", nil]
       rescue Error => e
-        "owner not loaded: #{e.message}"
+        ["owner not loaded: #{e.message}#{WHOLE_FILE_HINT}", nil]
       end
 
       def own_method(target, name)

data/lib/saboteur/engine/subject_selection.rb

@@ -33,7 +33,9 @@ module Saboteur
       def find(files)
         finder = SubjectFinder.new
         files.flat_map do |file|
+          InlineSuppression.new(file, File.read(file))
           parsed = finder.call(file)
+          @diagnostics.record_discovery_failure(file, reason: "invalid_file_syntax") unless parsed.errors.empty?
           parsed.errors.first(1).each do |message|
             @diagnostics.warn("#{file.delete_prefix("#{@root}/")} does not parse: #{message}")
           end
@@ -54,9 +56,30 @@ module Saboteur
       def by_change(subjects, ref)
         @changed_lines = Selection::GitDiff.changed_lines(ref, root: @root)
                                            .transform_keys { |file| Selection::CoverageMap.canonical(file) }
-        subjects.select do |subject|
+        changed = subjects.select do |subject|
           @changed_lines[subject.file]&.any? { |line| subject.contains_line?(line) }
         end
+        drop_unchanged_syntax(changed, ref)
+      end
+
+      # A method whose only changes are comments, blank lines or spacing has
+      # nothing new to test.
+      def drop_unchanged_syntax(subjects, ref)
+        return subjects if subjects.empty?
+
+        comparison = UnchangedSyntax.new(Selection::GitDiff.merge_base(ref, root: @root), root: @root)
+        same, kept = subjects.partition { |subject| comparison.unchanged?(subject) }
+        report_unchanged_syntax(same)
+        kept
+      end
+
+      def report_unchanged_syntax(subjects)
+        return if subjects.empty?
+
+        names = subjects.first(5).map(&:id).join(", ")
+        more = subjects.size > 5 ? ", ..." : ""
+        @diagnostics.inform("#{subjects.size} changed method(s) differ only in comments or formatting, " \
+                            "so they are skipped: #{names}#{more}")
       end
     end
   end

data/lib/saboteur/engine/suite_files.rb

@@ -3,6 +3,7 @@
 
 require "digest"
 require "shellwords"
+require_relative "data_inputs"
 
 module Saboteur
   class Engine
@@ -22,7 +23,7 @@ module Saboteur
       end
 
       def files
-        (shared_spec_files + boot_and_hook_files + option_files + required_by_options).uniq.sort
+        (shared_spec_files + boot_and_hook_files + option_files + required_by_options + data_files).uniq.sort
       end
 
       def digest
@@ -33,6 +34,12 @@ module Saboteur
 
       private
 
+      # Fixtures, schema dumps and database config: not Ruby, but they change
+      # what the tests see, so a stale cache must not survive an edit to them.
+      def data_files
+        DataInputs.files(@root, extra: @config["fingerprint_extra"])
+      end
+
       def shared_spec_files
         Dir.glob("spec/**/*.rb", base: @root).reject { |file| file.end_with?("_spec.rb") }
            .map { |file| File.join(@root, file) }

data/lib/saboteur/engine/test_guess.rb

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # --guess-tests: the specs that sit next to the changed source files by
+    # naming convention (lib/a/b.rb -> spec/a/b_spec.rb). A guess, not a
+    # coverage fact: a spec that only reaches the file through another one
+    # is not found. The run scopes to the guesses only when every changed
+    # file has one.
+    class TestGuess
+      Result = Data.define(:specs, :unmatched, :changed)
+
+      SOURCE_ROOTS = %w[lib app].freeze
+
+      def initialize(config)
+        @root = File.realpath(config.root)
+        @config = config
+      end
+
+      # specs: existing spec files (relative paths); unmatched: changed
+      # source files with no guessed spec; changed: how many source files
+      # changed.
+      def call
+        changed = changed_sources
+        guesses = changed.to_h { |file| [file, guess_for(file)] }
+        Result.new(specs: guesses.values.compact.uniq.sort, unmatched: guesses.select { |_, spec| spec.nil? }.keys,
+                   changed: changed.size)
+      end
+
+      private
+
+      # Changed files that saboteur would mutate, relative to the root.
+      def changed_sources
+        included = @config.included_files.to_set
+        changed = Selection::GitDiff.changed_lines(@config["since"], root: @root).keys
+        changed.map { |file| Selection::CoverageMap.canonical(file) }
+               .select { |file| included.include?(file) }
+               .map { |file| file.delete_prefix("#{@root}/") }.sort
+      end
+
+      def guess_for(file)
+        stem = file.delete_suffix(".rb")
+        rest = stem.split("/", 2)
+        candidates = ["spec/#{stem}_spec.rb"]
+        candidates.unshift("spec/#{rest.last}_spec.rb", "spec/lib/#{rest.last}_spec.rb") if
+          rest.size == 2 && SOURCE_ROOTS.include?(rest.first)
+        candidates.find { |path| File.file?(File.join(@root, path)) }
+      end
+    end
+  end
+end

data/lib/saboteur/engine/unchanged_syntax.rb

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../inline_suppression"
+
+module Saboteur
+  class Engine
+    # Tells whether a method still has, in the working tree, the syntax it had
+    # at the merge base of the --since ref. A change to a comment, a blank
+    # line or spacing leaves it the same, so no mutant of it asks a question
+    # the change raised. Comparison is of the Prism tree without locations
+    # and comments, plus the frozen_string_literal magic comment and the
+    # `sig` in front of the def, which both change what runs. `__LINE__` is
+    # the one node whose value is its location, so it keeps its line: a
+    # method that moved, or one with a line added above its `__LINE__`, is
+    # not the same.
+    #
+    # Anything that cannot be compared says the method changed: a file or
+    # method that is new at the base, a base that does not parse, a method
+    # name defined twice in a file.
+    class UnchangedSyntax
+      def initialize(base, root:)
+        @base = base
+        @root = root
+        @base_subjects = {}
+        @current_subjects = {}
+      end
+
+      def unchanged?(subject)
+        before = base_subject(subject)
+        return false unless before
+
+        return false unless suppression_signature(before) == suppression_signature(subject)
+
+        before.frozen_literals == subject.frozen_literals && before.sig_source == subject.sig_source &&
+          self.class.digest(before.node) == self.class.digest(subject.node)
+      end
+
+      # The node as plain data: type and fields, never locations (except
+      # the line a `__LINE__` stands for).
+      def self.digest(value)
+        case value
+        when Prism::SourceLineNode then [value.type, value.location.start_line]
+        when Prism::Node
+          fields = value.deconstruct_keys(nil).except(:node_id)
+          [value.type, fields.transform_values { |field| digest(field) }]
+        when Array then value.map { |item| digest(item) }
+        when Prism::Location then nil
+        else value
+        end
+      end
+
+      private
+
+      def suppression_signature(subject)
+        InlineSuppression.new(subject.file, subject.file_source).signature(subject)
+      end
+
+      def base_subject(subject)
+        return nil unless current_subjects(subject).key?(subject.id)
+
+        base_subjects(subject.file)[subject.id]
+      end
+
+      # Only the names defined once: with two defs of a name, which one a
+      # change belongs to is a guess.
+      def unique_by_id(source, file)
+        subjects = SubjectFinder.new.call(file, source: source).subjects
+        counts = subjects.map(&:id).tally
+        subjects.select { |subject| counts[subject.id] == 1 }.to_h { |subject| [subject.id, subject] }
+      end
+
+      def current_subjects(subject)
+        file = subject.file
+        @current_subjects.fetch(file) { @current_subjects[file] = unique_by_id(subject.file_source, file) }
+      end
+
+      def base_subjects(file)
+        @base_subjects.fetch(file) do
+          text = Selection::GitDiff.file_at(@base, file.delete_prefix("#{@root}/"), root: @root)
+          @base_subjects[file] = text ? unique_by_id(text, file) : {}
+        end
+      end
+    end
+  end
+end