saboteur 0.5.0 → 0.7.0

data/lib/saboteur/engine/run_budget.rb

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # The --max-duration wall-clock budget (#245). The clock anchors at
+    # engine entry, so boot, baselines and the coverage map spend it too;
+    # schedulers get an absolute deadline so a spent budget also stops a
+    # long subject between mutants.
+    module RunBudget
+      private
+
+      def start_budget_clock(started)
+        @run_started = started
+      end
+
+      # The whole run is budgeted, baselines included: an oversized
+      # baseline spends the budget by itself.
+      def budget_exceeded?
+        return false unless config["max_duration"]
+
+        exceeded = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @run_started >= config["max_duration"]
+        announce_budget_once if exceeded
+        exceeded
+      end
+
+      # A phase admitted inside the budget still gets only the time left
+      # in it: baseline passes and coverage builds cap at the deadline.
+      def budget_capped_timeout(timeout)
+        deadline = budget_deadline
+        return timeout unless deadline
+
+        (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)).clamp(0.0, timeout)
+      end
+
+      # Absolute monotonic deadline shared with the schedulers (forked
+      # workers inherit it): a subject's remaining mutants stop once it
+      # passes, so the overshoot after a spent budget stays under one
+      # mutant deadline.
+      def budget_deadline
+        config["max_duration"] && (@run_started + config["max_duration"])
+      end
+
+      # Boot and baselines can spend the budget by themselves: stop before
+      # an expensive cold coverage build and mark every selected subject
+      # unrun.
+      def abandon_for_budget?(subjects)
+        return false unless budget_exceeded?
+
+        @early_stop = EarlyStop.new(reason: "max_duration", unreached: subjects.map(&:id), truncated: [],
+                                    unverified: [])
+        true
+      end
+
+      def announce_budget_once
+        return if @budget_announced
+
+        @budget_announced = true
+        @diagnostics.inform("--max-duration reached: stopping before the next subject; the report marks it partial")
+      end
+    end
+  end
+end

data/lib/saboteur/engine/run_fingerprint.rb

@@ -3,6 +3,7 @@
 
 require "digest"
 require "json"
+require_relative "../text"
 require_relative "data_inputs"
 
 module Saboteur
@@ -127,7 +128,7 @@ module Saboteur
         issues = output_overlap_issues
         entries = inventory(issues).sort_by(&:path).freeze
         issues = issues.uniq.sort
-        settings_digest = hash_value(@config.to_h.except(*LOCATION_SETTINGS))
+        settings_digest = hash_value(@config.selection_settings.except(*LOCATION_SETTINGS))
         runtime_digest = hash_value(@runtime_identity)
         digest = hash_value(format: FORMAT_VERSION, files: entries.map(&:to_h),
                             settings: settings_digest, runtime: runtime_digest)
@@ -252,6 +253,9 @@ module Saboteur
       # undeclared dependency boundary, not a silently omitted source tree.
       def project_files(issues, directory = @root)
         Dir.children(directory).sort.flat_map do |name|
+          # Child names arrive locale-tagged; retag losslessly before
+          # joining with the UTF-8 root (#231).
+          name = Text.utf8_identity(name)
           path = File.join(directory, name)
           next [] if excluded?(path, name)
 

data/lib/saboteur/engine/sandbox_policy.rb

@@ -16,7 +16,10 @@ module Saboteur
       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
+      # read-only except tmp/ and the system temp dir - the cache dir stays
+      # read-only too, so a mutant cannot delete the baseline, the reports
+      # or other children's logs; its own log arrives as an inherited open
+      # descriptor (#234). 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",
@@ -28,14 +31,15 @@ module Saboteur
         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 " \
+          raise Error, "sandbox is strict but #{self.class.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")
+          @diagnostics.warn("sandbox is on but #{self.class.sandbox_gap(abi)}; children run with the hazard guard " \
+                            "and canary only")
         end
         nil
       end
@@ -49,7 +53,7 @@ module Saboteur
                      "unsandboxed - set c.sandbox = false to proceed without it"
       end
 
-      def sandbox_gap(abi)
+      def self.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()"
@@ -62,20 +66,23 @@ module Saboteur
 
       # c.sandbox_writable adds the dirs a suite genuinely needs (db/, log/,
       # ...): without a grant, writes there fail with EACCES in the child.
+      # Only the user grants are created: the project tmp is granted when it
+      # already exists, never made for it (#236).
       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) }
+        user_dirs.each { |dir| FileUtils.mkdir_p(dir) }
+        tmp = File.join(@root, "tmp")
+        dirs = Dir.exist?(tmp) ? [tmp] + user_dirs : user_dirs
         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
+      # The effective write set - every grant realpath'd, the project tmp
+      # and the system temp dir included - must not contain the project
+      # root: 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)

data/lib/saboteur/engine/scheduler.rb

@@ -27,8 +27,9 @@ module Saboteur
         tests.sort_by.with_index { |id, index| [-killers.fetch(id, 0), index] }
       end
 
-      def initialize(config:, runner:, map:, reevaluator:, diagnostics:, cache: nil)
+      def initialize(config:, runner:, map:, reevaluator:, diagnostics:, cache: nil, deadline: nil)
         @config = config
+        @deadline = deadline
         @runner = runner
         @map = map
         @reevaluator = reevaluator
@@ -73,23 +74,53 @@ module Saboteur
 
       # Verdicts that did not hold up are warned about once per subject;
       # only checked verdicts are stored for --incremental.
+      # A spent budget admits no check: forking the unchanged run with no
+      # time left would turn genuine kills into fabricated errors and cache
+      # them. Fresh kills stand unverified instead - outside the score,
+      # never cached - and the distribution marks the subject so the run
+      # reports budget-partial.
       def checked(plan, results)
+        return results.map { |result| unverifiable(result) } if budget_spent?
+
         subject = plan.subject
-        run_unchanged = lambda do |tests, 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"])
+        check = VerdictCheck.new(run_unchanged: unchanged_runner(subject, plan),
+                                 baseline_timeout: @config["baseline_timeout"])
         final = check.call(results)
-        final.reject(&:reused?).each { |result| @cache&.record(result) }
-        overturned = final.zip(results).count { |after, before| !after.equal?(before) }
+        # Unverified verdicts are never cached: a budget-cut check proves
+        # nothing, and a stored copy would read as confirmed next run.
+        final.reject { |result| result.reused? || result.status == :unverified }.each { |r| @cache&.record(r) }
+        overturned = final.zip(results).count { |after, before| after.status == :error && !after.equal?(before) }
         if overturned.positive?
           @diagnostics.warn("#{subject.id}: #{overturned} verdict(s) failed with the method unchanged")
         end
         final
       end
 
+      # Admission is per sequence, not just at checked() entry: a check
+      # admitted with time left can hit its capped timeout mid-check, and a
+      # later sequence can arrive after the budget is spent. Neither may
+      # fork with no time left, and neither outcome is a rejected kill -
+      # the check never got its answer (#296).
+      def unchanged_runner(subject, plan)
+        lambda do |tests, timeout|
+          if budget_spent?
+            Execution::Runner::Outcome.new(status: :unverified, runtime: 0.0,
+                                           message: "the --max-duration budget is spent")
+          else
+            capped = budget_capped(timeout)
+            outcome = @runner.run(subject: subject, text: subject.source, test_ids: tests, timeout: capped,
+                                  eval_prefix: eval_prefix(plan))
+            note_leftovers(subject, "verdict check", outcome)
+            if outcome.status == :timeout && capped < timeout
+              Execution::Runner::Outcome.new(status: :unverified, runtime: outcome.runtime,
+                                             message: "the --max-duration budget cut the verdict check short")
+            else
+              outcome
+            end
+          end
+        end
+      end
+
       # When every verdict can be reused, nothing forks: not even the neutral
       # check. Returns the results, or nil at the first one that must run.
       def all_reused(plan, candidates)
@@ -100,10 +131,16 @@ module Saboteur
         end
       end
 
+      # The budget deadline is checked between mutants, so a spent
+      # --max-duration stops inside a long subject too; completed results
+      # are kept and the distribution marks what follows as unreached.
       def run_candidates(candidates, &run_one)
         coarse, fine = candidates.partition { |mutation, _| mutation.coarse }
-        results = coarse.map { |mutation, text| run_one.call(mutation, text) }
-        results + fine.map { |mutation, text| run_one.call(mutation, text) }
+        (coarse + fine).each_with_object([]) do |(mutation, text), results|
+          break results if @deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @deadline
+
+          results << run_one.call(mutation, text)
+        end
       end
 
       # A stored verdict that still holds, as a result; nil when it must run.
@@ -206,19 +243,78 @@ module Saboteur
       # baseline_timeout. If the deadline from that real runtime is longer,
       # the mutant runs again with it, and later mutants of the subject get
       # the measured slowdown. A timeout that remains is the mutant's own.
+      # A --max-duration deadline caps every admission the scheduler makes:
+      # verdict checks and timeout calibrations get only the time left.
+      def budget_capped(timeout)
+        return timeout unless @deadline
+
+        remaining = @deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        remaining.clamp(0.0, timeout)
+      end
+
+      def budget_spent?
+        @deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @deadline
+      end
+
+      # A fresh kill whose check the budget skipped proves nothing yet: it
+      # becomes unverified, outside the score, and is never cached.
+      def unverifiable(result)
+        return result if result.reused? || result.status != :killed
+
+        result.as_unverified("verdict check skipped: the --max-duration budget is spent")
+      end
+
+      # A timeout the budget keeps the calibration from judging proves
+      # nothing either: no zero-time forks, and a retry cut short does not
+      # count as detected.
       def calibrate(plan, mutation, text, tests, timeout)
-        unchanged = @runner.run(subject: plan.subject, text: plan.subject.source, test_ids: tests,
-                                timeout: @config["baseline_timeout"], eval_prefix: eval_prefix(plan))
-        note_leftovers(plan.subject, "timeout check", unchanged)
+        if budget_spent?
+          return unverified_outcome(timeout, "timeout calibration skipped: the --max-duration budget is spent")
+        end
+
+        unchanged, shortened = unchanged_timing(plan, tests)
+        if unchanged.status == :timeout && shortened
+          return unverified_outcome(unchanged.runtime, "the --max-duration budget cut the timeout calibration short")
+        end
         return unchanged_failed(unchanged) unless unchanged.status == :survived
 
+        retry_longer(plan, mutation, text, tests, [timeout, unchanged.runtime])
+      end
+
+      # The unchanged method under the budget-capped baseline timeout, and
+      # whether the cap shortened it.
+      def unchanged_timing(plan, tests)
+        capped = budget_capped(@config["baseline_timeout"])
+        outcome = @runner.run(subject: plan.subject, text: plan.subject.source, test_ids: tests,
+                              timeout: capped, eval_prefix: eval_prefix(plan))
+        note_leftovers(plan.subject, "timeout check", outcome)
+        [outcome, capped < @config["baseline_timeout"]]
+      end
+
+      def retry_longer(plan, mutation, text, tests, limit)
+        timeout, unchanged_runtime = limit
         recorded = @map.recorded_runtime(tests)
-        plan.slowdown = [plan.slowdown, unchanged.runtime / recorded].max if recorded&.positive?
-        longer = deadline(unchanged.runtime)
+        plan.slowdown = [plan.slowdown, unchanged_runtime / recorded].max if recorded&.positive?
+        longer = deadline(unchanged_runtime)
         return Execution::Runner::Outcome.new(status: :timeout, runtime: timeout) if longer <= timeout
+        # The unchanged timing may have used the final allowance: no
+        # zero-time retry fork (#296).
+        if budget_spent?
+          return unverified_outcome(timeout, "the --max-duration budget is spent before the mutant retry")
+        end
+
+        retry_timeout = budget_capped(longer)
+        retried = @runner.run(subject: plan.subject, text: text, test_ids: tests, timeout: retry_timeout,
+                              mutation: mutation, eval_prefix: eval_prefix(plan))
+        return retried unless retried.status == :timeout && retry_timeout < longer
+
+        unverified_outcome(retried.runtime, "the --max-duration budget cut the mutant retry short")
+      end
 
-        @runner.run(subject: plan.subject, text: text, test_ids: tests, timeout: longer, mutation: mutation,
-                    eval_prefix: eval_prefix(plan))
+      # A budget-cut calibration proves nothing about the mutant: outside
+      # the score, and never cached.
+      def unverified_outcome(runtime, message)
+        Execution::Runner::Outcome.new(status: :unverified, runtime: runtime, message: message)
       end
 
       def unchanged_failed(unchanged)

data/lib/saboteur/engine/subject_selection.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "../text"
+
 module Saboteur
   class Engine
     # The subjects to mutate: every def in the included files, narrowed by
@@ -13,11 +15,12 @@ module Saboteur
         @config = config
         @diagnostics = diagnostics
         @root = File.realpath(config.root)
-        @changed_lines = nil
       end
 
       def select(files)
+        @files = files
         subjects = find(files)
+        @discovered = subjects
         subjects = by_pattern(subjects, @config["subjects"]) if @config["subjects"].any?
         subjects = by_change(subjects, @config["since"]) if @config["since"]
         subjects
@@ -28,6 +31,22 @@ module Saboteur
         id == pattern || %w[# . ::].any? { |separator| id.start_with?("#{pattern}#{separator}") }
       end
 
+      # The files (absolute paths) holding a subject matching any pattern,
+      # returned relative to root. --subject inference guesses specs for
+      # exactly these, so one unrelated spec-less file cannot block a
+      # one-method run.
+      def self.files_matching(root, files, patterns)
+        finder = SubjectFinder.new
+        prefix = "#{root}/"
+        files.filter_map do |file|
+          parsed = finder.call(file)
+          matching = parsed.subjects.any? do |subject|
+            patterns.any? { |pattern| match?(subject.id, pattern) }
+          end
+          file.delete_prefix(prefix) if matching
+        end.sort
+      end
+
       private
 
       def find(files)
@@ -54,14 +73,74 @@ module Saboteur
       end
 
       def by_change(subjects, ref)
-        @changed_lines = Selection::GitDiff.changed_lines(ref, root: @root)
+        @changed_lines = Selection::GitDiff.changed_lines(ref, root: @root, include: @files.to_set,
+                                                               diagnostics: @diagnostics)
                                            .transform_keys { |file| Selection::CoverageMap.canonical(file) }
-        changed = subjects.select do |subject|
-          @changed_lines[subject.file]&.any? { |line| subject.contains_line?(line) }
-        end
+        changed = changed_subjects(subjects)
+        warn_changed_files_without_subjects
+        warn_excluded_changed_files
         drop_unchanged_syntax(changed, ref)
       end
 
+      # subject.file carries the locale tag under a non-UTF-8 locale
+      # while the diff keys are UTF-8; retag losslessly before lookup so
+      # a non-ASCII path matches by its exact bytes (#231).
+      def changed_subjects(subjects)
+        subjects.select do |subject|
+          key = Selection::CoverageMap.canonical(Text.utf8_identity(subject.file))
+          lines = @changed_lines[key]
+          lines && subject.overlaps_lines?(lines)
+        end
+      end
+
+      # A changed Ruby file in scope whose changed lines cover no subject
+      # silently contributes nothing to the run (#232): warn, or a typo, an
+      # unparseable file or a selection bug passes as a clean selection.
+      # Comment-only changes stay quiet: their file matched subjects before
+      # drop_unchanged_syntax pruned them, and that prune is reported. A
+      # diff touching no included Ruby file is a legitimate empty scope.
+      def warn_changed_files_without_subjects
+        canonical = ->(file) { Selection::CoverageMap.canonical(Text.utf8_identity(file)) }
+        included = @files.map(&canonical)
+        matched = changed_subjects(@discovered).map { |subject| canonical.call(subject.file) }
+        unmatched = (@changed_lines.keys.select { |file| file.end_with?(".rb") } & included) - matched
+        return if unmatched.empty?
+
+        names = unmatched.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
+        more = unmatched.size > 5 ? ", ..." : ""
+        @diagnostics.warn("--since: #{unmatched.size} changed Ruby file(s) have no subjects covering " \
+                          "the changed lines, so nothing is mutated from them: #{names}#{more}. The " \
+                          "file may not parse, or every change may sit outside a method.")
+      end
+
+      # A changed Ruby file that an include pattern covers but c.exclude
+      # removes yields zero candidates with no other sign - this repo's own
+      # config excludes lib/saboteur/execution/**, so harness changes once
+      # dogfooded as a clean empty scope (#282). Names at most five.
+      def warn_excluded_changed_files
+        untracked = Selection::UntrackedChanges.paths(@root)
+        hits = excluded_territory & (@changed_lines.keys + untracked)
+        return if hits.empty?
+
+        names = hits.sort.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
+        more = hits.size > 5 ? ", ..." : ""
+        @diagnostics.warn("--since: #{hits.size} changed Ruby file(s) are covered by c.include but removed by " \
+                          "c.exclude, so nothing is mutated from them: #{names}#{more}. Narrow or remove the " \
+                          "c.exclude entry, or pass the file as a positional source operand (configured " \
+                          "excludes are then ignored).")
+      end
+
+      # Ruby files an include pattern and an exclude pattern both match,
+      # canonicalized the way the diff map keys are.
+      def excluded_territory
+        canonical = lambda do |file|
+          Selection::CoverageMap.canonical(File.expand_path(Text.utf8_identity(file), @config.root))
+        end
+        territory = @config["include"].flat_map { |pattern| Dir.glob(pattern, base: @config.root) }
+        excluded = @config["exclude"].flat_map { |pattern| Dir.glob(pattern, base: @config.root) }
+        (territory & excluded).select { |file| file.end_with?(".rb") }.map(&canonical)
+      end
+
       # A method whose only changes are comments, blank lines or spacing has
       # nothing new to test.
       def drop_unchanged_syntax(subjects, ref)

data/lib/saboteur/engine/suite_files.rb

@@ -3,6 +3,7 @@
 
 require "digest"
 require "shellwords"
+require_relative "../text"
 require_relative "data_inputs"
 
 module Saboteur
@@ -56,7 +57,8 @@ module Saboteur
       # `--require name` resolves through RSpec's load path: spec/, lib/ and
       # any -I directory.
       def required_by_options
-        tokens = option_files.flat_map { |file| Shellwords.split(File.read(file)) } + @config["rspec_args"]
+        tokens = option_files.flat_map { |file| Shellwords.split(Text.utf8_identity(File.read(file))) } +
+                 @config["rspec_args"]
         load_path = LOAD_PATH + option_values(tokens, "-I", "--include")
         option_values(tokens, *REQUIRE_FLAGS).filter_map { |name| resolve(name, load_path) }
       end