saboteur 0.6.0 → 0.7.0

data/lib/saboteur/engine/diagnostics.rb

@@ -76,8 +76,9 @@ module Saboteur
       attr_reader :warnings, :invalid_mutations, :generation_events, :omissions, :discovery_failures,
                   :hazard_suppressions, :inline_suppressions
 
-      def initialize(err)
+      def initialize(err, verbose: false)
         @err = err
+        @verbose = verbose
         @warnings = []
         @invalid_mutations = 0
         @generation_events = []
@@ -102,8 +103,11 @@ module Saboteur
         @generation_events << GenerationEvent.new(*values)
       end
 
+      # The selection and the test inference each walk the same changed
+      # files in one run; a failure either of them finds is recorded once.
       def record_discovery_failure(file, reason:)
-        @discovery_failures << DiscoveryFailure.new(file: file.to_s.dup.freeze, reason: reason.to_s.dup.freeze)
+        failure = DiscoveryFailure.new(file: file.to_s.dup.freeze, reason: reason.to_s.dup.freeze)
+        @discovery_failures << failure unless @discovery_failures.include?(failure)
       end
 
       # A mutant the hazard guard refused to generate (issue #102): counted
@@ -129,6 +133,23 @@ module Saboteur
         @err.puts("saboteur: #{message}")
       end
 
+      # --verbose: one line per finished subject with its result marks, so a
+      # survivor is attributable to a method as soon as the subject
+      # completes, before the whole run ends (#262).
+      def subject_progress(subject, results)
+        return unless @verbose
+        return if results.empty?
+
+        marks = results.map { |result| MARKS.fetch(result.status, "?") }.join
+        inform("#{subject.id}  #{marks}")
+      end
+
+      # A message that is both a report warning and a stderr note.
+      def announce(message)
+        warn(message)
+        inform(message)
+      end
+
       # A heartbeat for a long phase: the supervisor's wait loop calls tick
       # in the parent after the fork, so no extra thread is ever alive at
       # fork time. Prints "<label>: N s elapsed" about every interval

data/lib/saboteur/engine/diff_scope.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "../text"
+
 module Saboteur
   class Engine
     # Review-shaped diff mode (--since). A reviewer asks "do the tests check
@@ -14,7 +16,7 @@ module Saboteur
       end
 
       def restrict(subject, candidates)
-        changed = @changed_lines.fetch(subject.file, Set.new)
+        changed = lines_for(subject)
         candidates.select do |mutation, _|
           mutation.coarse || mutation.edits.any? { |edit| edited_lines(subject, edit).any? { changed.include?(_1) } }
         end
@@ -24,22 +26,39 @@ module Saboteur
       # several lines is mutated as one piece and reported at its first line,
       # which can sit above the line that changed; this names the changed line.
       def changed_lines_for(subject, mutation)
-        changed = @changed_lines.fetch(subject.file, Set.new)
+        changed = lines_for(subject)
         mutation.edits.flat_map { |edit| edited_lines(subject, edit).to_a }.uniq.select { changed.include?(_1) }.sort
       end
 
       # Distance to the nearest changed line in this file. Unknown outside
-      # the diff is nil, not a made-up nearby location.
+      # the diff is nil, not a made-up nearby location. A range answers
+      # geometrically - 0 when the edit overlaps, else the gap to the nearer
+      # endpoint - so a whole-file range never materializes one entry per
+      # line.
       def distance_for(subject, mutation)
-        changed = @changed_lines.fetch(subject.file, Set.new)
+        changed = lines_for(subject)
         mutation.edits.map do |edit|
           first, last = edited_lines(subject, edit).minmax
-          changed.map { |line| (line - line.clamp(first, last)).abs }.min
+          if changed.is_a?(Range)
+            if last < changed.begin then changed.begin - last
+            elsif first > changed.end then first - changed.end
+            else 0
+            end
+          else
+            changed.map { |line| (line - line.clamp(first, last)).abs }.min
+          end
         end.min
       end
 
       private
 
+      # subject.file carries the locale tag under a non-UTF-8 locale
+      # while the map keys are UTF-8; retag losslessly or a non-ASCII
+      # path never matches and every fine mutant is silently dropped.
+      def lines_for(subject)
+        @changed_lines.fetch(Text.utf8_identity(subject.file), Set.new)
+      end
+
       def edited_lines(subject, edit)
         first = subject.line_of(edit.start_byte)
         last = subject.line_of([edit.end_byte - 1, edit.start_byte].max)

data/lib/saboteur/engine/distribution.rb

@@ -9,23 +9,31 @@ module Saboteur
     # candidate list, so results look the same either way.
     class Distribution
       # After run: the subjects a stop_after callable left unrun (always empty
-      # without one).
-      attr_reader :unreached
+      # without one), and the subjects that started but stopped mid-list as
+      # [subject, omitted_candidate_count] pairs (a spent --max-duration
+      # breaking a subject's scheduler loop). unverified lists the subjects
+      # whose fresh kills the spent budget left unchecked (#296).
+      attr_reader :unreached, :truncated, :unverified
 
       # stop_after: nil, or a callable that gets one subject's results and
       # returns true to stop before the next subject (--fail-fast). It only
       # works on one process: parallel workers have already started the
       # other subjects.
       def initialize(jobs:, scheduler:, diagnostics:, cache:, on_start: nil, after_subject: nil,
-                     stop_after: nil)
+                     stop_after: nil, halt_check: nil,
+                     drain_timeout: 30) # seconds; two minimum-strength mutant deadlines at default settings
         @jobs = jobs
         @stop_after = stop_after
+        @halt_check = halt_check
         @unreached = []
+        @truncated = []
+        @unverified = []
         @on_start = on_start
         @scheduler = scheduler
         @diagnostics = diagnostics
         @cache = cache
         @after_subject = after_subject
+        @drain_timeout = drain_timeout
       end
 
       # lists: each subject's [[mutation, text]] candidates, in subject order.
@@ -35,23 +43,116 @@ module Saboteur
         # The watcher runs as each subject's row arrives, before the pool
         # hands out more work, so a tripped canary stops the queue (jobs>1
         # used to check only after the whole batch returned, issue #102).
-        arrival = lambda do |i, row|
-          @after_subject&.call(subjects[i], decode(row, subjects[i], lists[i]))
+        # A tool error no longer raises on sight: one wiped log dir hits
+        # every worker, and a bystander whose current job ran no mutant
+        # reports "an unknown mutant", which could land before the report
+        # of the worker whose mutant did the damage (macOS CI on #285).
+        # The pool is halted instead - no new work, and the drain is
+        # bounded by drain_timeout so a wedged worker cannot stall the
+        # abort - and the abort raises the report with the best
+        # attribution.
+        # The abort reports and the pool are run state: a Distribution
+        # runs once. @pool is only read from arrivals, which fire inside
+        # @pool.map after the assignment.
+        # A budget already spent by boot, baselines or the coverage map
+        # launches nothing: every subject comes back unreached (#245).
+        if @halt_check&.call
+          @unreached = subjects
+          return []
         end
-        pool = Execution::WorkerPool.new(jobs: @jobs, on_start: @on_start, on_result: arrival)
-        rows = pool.map(subjects.each_index.to_a, weights: lists.map(&:size)) do |i|
+
+        @abort_reports = []
+        arrival = arrival_for(subjects, lists)
+        @pool = Execution::WorkerPool.new(jobs: @jobs, on_start: @on_start, on_result: arrival,
+                                          drain_timeout: @drain_timeout)
+        rows = @pool.map(subjects.each_index.to_a, weights: lists.map(&:size)) do |i|
           work(subjects[i], lists[i])
         end
-        rows.each_with_index.flat_map { |row, i| rebuild(row, subjects[i], lists[i]) }
+        raise_preferred_tool_error(@abort_reports) if @abort_reports.any?
+        record_unreached(rows, subjects, lists)
+        rows.each_with_index.flat_map do |row, i|
+          next [] if row.nil?
+
+          raise_if_tool_error(row)
+          rebuild(row, subjects[i], lists[i])
+        end
       end
 
       private
 
+      # @pool is only read here from arrivals, which fire inside @pool.map
+      # after the assignment. A spent --max-duration budget stops the queue
+      # without the safety-abort drain: in-flight subjects finish and
+      # report, and only never-started ones come back as nil holes, so
+      # unreached never mislabels an interrupted subject as unrun (#245).
+      def arrival_for(subjects, lists)
+        lambda do |i, row|
+          if row["tool_error"]
+            collect_abort_report(row)
+          else
+            check_subject(subjects, lists, i, row)
+            @pool.halt!(drain: false) if @halt_check&.call
+          end
+        end
+      end
+
+      # nil rows never started; a short results list is a subject whose
+      # scheduler stopped mid-list at the budget deadline. Worker-level error
+      # rows synthesize an error per candidate, so they never look truncated.
+      def unverified_result?(result)
+        result.is_a?(MutantResult) && result.status == :unverified
+      end
+
+      def record_unreached(rows, subjects, lists)
+        @unreached = []
+        @truncated = []
+        @unverified = []
+        rows.each_with_index do |row, i|
+          if row.nil?
+            @unreached << subjects[i]
+            next
+          end
+          next unless row["results"] && !row["error"]
+
+          @truncated << [subjects[i], lists[i].size - row["results"].size] if row["results"].size < lists[i].size
+          @unverified << subjects[i] if row["results"].any? { |result| result["status"] == "unverified" }
+        end
+      end
+
+      # @pool is always assigned when an arrival fires: arrivals only fire
+      # from inside @pool.map, which runs after the assignment.
+      def collect_abort_report(row)
+        @abort_reports << row
+        @pool.halt!
+      end
+
+      # A canary trip from the end-of-subject check folds into the same
+      # record + halt + preferred-report path as a worker's own report:
+      # escaping the pool here would override a collected report that
+      # names the real culprit (#285 review).
+      def check_subject(subjects, lists, index, row)
+        @after_subject&.call(subjects[index], decode(row, subjects[index], lists[index]))
+      rescue Error => e
+        collect_abort_report(Execution::WorkerPool.tool_error_row(e))
+      end
+
       def run_serially(subjects, lists)
         results = []
         subjects.zip(lists).each_with_index do |(subject, list), index|
+          # Same pre-dispatch budget check as the parallel first wave: an
+          # already-spent baseline starts no further subjects (#245).
+          if @halt_check&.call
+            @unreached = subjects.drop(index)
+            break
+          end
+
           subject_results = @scheduler.call(subject, list)
           results.concat(subject_results)
+          # A scheduler that stopped mid-list at the budget deadline: the
+          # completed results stay, the omitted candidates are accounted.
+          omitted = list.size - subject_results.size
+          @truncated << [subject, omitted] if omitted.positive?
+          @unverified << subject if subject_results.any? { |result| unverified_result?(result) }
           @after_subject&.call(subject, subject_results)
           next unless @stop_after&.call(subject_results)
 
@@ -91,6 +192,21 @@ module Saboteur
 
       # Turns a worker row back into results, without diagnostics or caching:
       # used both at result arrival (the canary) and at rebuild time.
+      # A tool error from the worker (a vanished cache dir, ...) aborts
+      # the whole run with exit 3; it is not a per-mutant outcome (#283).
+      def raise_if_tool_error(row)
+        raise Error, row["tool_error"] if row["tool_error"]
+      end
+
+      # The abort names a culprit when any report can, ranked by
+      # attribution quality (#285 review): a report carrying its mutant's
+      # per-mutant digest first, then a canary trip (the hazard report
+      # still beats a bare report, #283), then the first bare report.
+      def raise_preferred_tool_error(rows)
+        row = rows.find { |r| r["culprit"] } || rows.find { |r| r["canary"] } || rows.first
+        raise Error, row["tool_error"]
+      end
+
       def decode(row, subject, list)
         return failed(row["error"], subject, list) if row["error"]
 

data/lib/saboteur/engine/early_stop_recording.rb

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Records the subjects an early stop left behind - whole subjects that
+    # never started and candidates skipped mid-way through a subject - so
+    # the report says the verdict covers less than the selection.
+    module EarlyStopRecording
+      private
+
+      # The subjects a stop left unrun or mid-way: the verdict covers less than the selection.
+      def record_early_stop(distribution)
+        return if distribution.unreached.empty? && distribution.truncated.empty? && distribution.unverified.empty?
+
+        truncated = distribution.truncated.map { |subject, omitted| { subject: subject.id, omitted: omitted } }
+        @early_stop = EarlyStop.new(reason: stop_reason(distribution), unreached: distribution.unreached.map(&:id),
+                                    truncated: truncated, unverified: distribution.unverified.map(&:id))
+      end
+
+      # Mid-subject omissions and skipped checks are budget work: only a
+      # stop that left whole subjects unreached can be fail_fast's.
+      def stop_reason(distribution)
+        return "max_duration" if distribution.truncated.any? || distribution.unverified.any?
+
+        run_early_stop_reason
+      end
+
+      # max_duration was announced before fail_fast could stop the run: a
+      # budget stop overrides a failure stop announced later.
+      def run_early_stop_reason
+        @budget_announced ? "max_duration" : "fail_fast"
+      end
+
+      # A baseline or coverage phase stopped because --max-duration ate its
+      # allowance: budget exhaustion, not a broken suite. The run reports
+      # partial with every selected subject unreached (exit 4) (#296).
+      def budget_phase_stop(error, subjects)
+        @diagnostics.warn(error.message)
+        @early_stop = EarlyStop.new(reason: "max_duration", unreached: subjects.map(&:id), truncated: [],
+                                    unverified: [])
+        []
+      end
+    end
+  end
+end

data/lib/saboteur/engine/result_cache.rb

@@ -4,6 +4,7 @@
 require "digest"
 require "fileutils"
 require "json"
+require_relative "../text"
 
 module Saboteur
   class Engine
@@ -65,7 +66,7 @@ module Saboteur
       private
 
       def load
-        data = JSON.parse(File.read(@path))
+        data = JSON.parse(Text.utf8_strict(File.read(@path)))
         data["format"] == FORMAT ? data["entries"] : {}
       rescue SystemCallError, JSON::ParserError
         {}

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
@@ -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)