saboteur 0.5.0 → 0.7.0

data/lib/saboteur/result.rb

@@ -12,7 +12,10 @@ module Saboteur
   # test can observe a change there, so it is outside the score.
   # unreachable: a Method object captured before re-evaluation still calls
   # the original body, so no test can observe the mutant. Outside the score.
-  STATUSES = %i[killed survived timeout resource_limit error skipped ran_at_load unreachable].freeze
+  # unverified: the --max-duration budget ran out before the verdict check
+  # or timeout calibration could run, so the kill or timeout proves
+  # nothing. Outside the score; the run reports budget-partial.
+  STATUSES = %i[killed survived timeout resource_limit error skipped ran_at_load unreachable unverified].freeze
 
   # Outcome of one mutation. reason carries the skip reason, the error
   # message or the timeout limit. ignored is the ignore-list reason, if any.
@@ -40,6 +43,14 @@ module Saboteur
       @ignored = nil
     end
 
+    # The same mutant, marked unverified: the budget ran out before its
+    # verdict could be checked, so it must not count as detected (#296).
+    def as_unverified(reason)
+      MutantResult.new(subject: subject, mutation: mutation, status: :unverified, mutated_source: mutated_source,
+                       reason: reason, runtime: runtime, killed_by: killed_by, covered_by: covered_by,
+                       kill_cause: kill_cause, executed: executed)
+    end
+
     # The same mutant, marked as an error: its verdict did not hold up.
     def as_error(reason, rejected_kill: false)
       MutantResult.new(subject: subject, mutation: mutation, status: :error, mutated_source: mutated_source,
@@ -100,10 +111,13 @@ module Saboteur
     end
   end
 
-  # A run that stopped before every selected subject was mutated (--fail-fast).
-  # unreached lists the subject ids that never ran; the verdict covers only
-  # the subjects that did.
-  EarlyStop = Data.define(:reason, :unreached)
+  # A run that stopped before every selected subject was mutated (--fail-fast,
+  # --max-duration), or whose budget ran out before every verdict check.
+  # unreached lists the subject ids that never ran; truncated lists the
+  # subjects that started but stopped mid-way as {subject:, omitted:}
+  # entries; unverified lists the subjects whose kills the budget left
+  # unchecked. The verdict covers only completed, verified work.
+  EarlyStop = Data.define(:reason, :unreached, :truncated, :unverified)
 
   # Everything one run produced.
   class Report
@@ -112,13 +126,15 @@ module Saboteur
     MAX_ERROR_FRACTION = 0.5
 
     attr_reader :results, :subjects, :wall_time, :invalid_mutations, :warnings, :root, :seed, :skipped_subjects,
-                :generation_events, :omissions, :run_evidence, :hazard_suppressions, :early_stop, :inline_suppressions
+                :generation_events, :omissions, :run_evidence, :hazard_suppressions, :early_stop, :inline_suppressions,
+                :operator_policy, :discovery_failures
 
     # REVIEW: diff mode; the terminal then shows one survivor per line.
     # seed: the random seed every test run started from (nil when unknown).
     def initialize(results:, subjects:, wall_time:, root:, invalid_mutations: 0, warnings: [], review: false,
                    seed: nil, skipped_subjects: {}, diff_scope: nil, generation_events: [], omissions: [],
-                   run_evidence: nil, hazard_suppressions: 0, early_stop: nil, matrix: false, inline_suppressions: [])
+                   run_evidence: nil, hazard_suppressions: 0, early_stop: nil, matrix: false, inline_suppressions: [],
+                   operator_policy: nil, discovery_failures: [])
       @results = results
       @subjects = subjects
       @wall_time = wall_time
@@ -136,6 +152,8 @@ module Saboteur
       @early_stop = early_stop
       @matrix = matrix
       @inline_suppressions = inline_suppressions.dup.freeze
+      @operator_policy = operator_policy
+      @discovery_failures = discovery_failures.dup.freeze
     end
 
     # A --matrix run: every covering test ran per mutant.

data/lib/saboteur/selection/coverage_map.rb

@@ -5,6 +5,7 @@ require "coverage"
 require "digest"
 require "fileutils"
 require "json"
+require_relative "../text"
 
 module Saboteur
   module Selection
@@ -168,7 +169,7 @@ module Saboteur
       end
 
       def self.load(path)
-        from_json(File.read(path)) if File.file?(path)
+        from_json(Text.utf8_strict(File.read(path))) if File.file?(path)
       rescue JSON::ParserError, Error
         nil
       end

data/lib/saboteur/selection/git_diff.rb

@@ -2,6 +2,8 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../text"
+require_relative "untracked_changes"
 
 module Saboteur
   module Selection
@@ -39,12 +41,18 @@ module Saboteur
         status.success? ? out.b : nil
       end
 
-      def changed_lines(ref, root:)
+      def changed_lines(ref, root:, include: nil, diagnostics: nil)
         verify_ref!(ref, root: root)
         base = merge_base(ref, root: root)
-        top = git(root, "rev-parse", "--show-toplevel").strip
-        parse(git(root, "-c", "core.quotePath=false", "diff", "--unified=0", "--no-color", "--no-ext-diff", base,
-                  "--"), top)
+        # Root and paths are filesystem identity: strip as bytes and retag
+        # losslessly (strip raises on locale-tagged high bytes; a scrub
+        # 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)
+        UntrackedChanges.union(changes, top, include: include, diagnostics: diagnostics)
+        changes
       end
 
       def parse(diff, top)
@@ -52,8 +60,10 @@ module Saboteur
         file = nil
         diff.each_line do |line|
           if line.start_with?("+++ ")
-            path = unquote(line.chomp.delete_prefix("+++ ").delete_suffix("\t"))
+            path = Text.utf8_identity(unquote(line.chomp.delete_prefix("+++ ").delete_suffix("\t")))
             file = path == NO_FILE ? nil : File.join(top, path.delete_prefix("b/"))
+          # 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

data/lib/saboteur/selection/untracked_changes.rb

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require_relative "../text"
+
+module Saboteur
+  module Selection
+    # Untracked files as changed-line coverage for --since.
+    #
+    # A diff cannot see untracked files, so a never-committed source file
+    # would silently contribute no changed lines - and, being in no map,
+    # not even the changed-files-without-subjects warning (#295). Union
+    # every untracked file that could hold subjects (the include set the
+    # run will mutate) as fully changed: a new file is the strongest
+    # possible "changed since ref" signal. Ignored files stay invisible
+    # (--exclude-standard), and binary or empty files carry no lines,
+    # matching how a committed binary diffs to no hunks.
+    #
+    # Each file is opened RDONLY|NOFOLLOW|NONBLOCK and validated on that
+    # one descriptor, closing the listing-to-read race: a symlink swapped
+    # in after the listing fails the open, a FIFO opens without blocking
+    # and fails the regular-file stat, and a vanished or unreadable file
+    # is reported. Where a platform lacks either flag the union is skipped
+    # with a warning rather than done unsafely (the crash log makes the
+    # same trade, #296). The binary sniff reads only the first few
+    # kilobytes (git's own heuristic window) and the count streams, so a
+    # huge untracked source costs one pass, not its content in memory; the
+    # map holds a range, not one Set entry per line.
+    module UntrackedChanges
+      BINARY_SNIFF_BYTES = 8000
+      READ_CHUNK_BYTES = 64 * 1024
+
+      module_function
+
+      # Add every include-eligible untracked file to CHANGES as a full
+      # range. Eligible files that cannot be read are warned about and
+      # recorded as discovery failures, not dropped silently, so the run is
+      # reported incomplete instead of clean over mixed source.
+      def union(changes, top, include:, diagnostics:)
+        unless File.const_defined?(:NOFOLLOW) && File.const_defined?(:NONBLOCK)
+          diagnostics&.warn("--since: untracked files are not included: this platform lacks " \
+                            "O_NOFOLLOW/O_NONBLOCK, so they cannot be opened race-free")
+          return
+        end
+
+        flags = File::RDONLY | File::NOFOLLOW | File::NONBLOCK
+        unreadable = []
+        files(top).each do |name|
+          file = File.join(top, name)
+          # Membership is lexical first: an included path swapped to a
+          # symlink must reach the safe open, which rejects it, so the swap
+          # is reported instead of filtered out on the resolved target. The
+          # canonical fallback keeps a symlinked ROOT in scope, because the
+          # include set is realpath'd.
+          next if include && !include.include?(file) && !include.include?(CoverageMap.canonical(file))
+
+          case (lines = line_count(file, flags))
+          when :unreadable then unreadable << name
+          when Integer then changes[file] = (1..lines)
+          end
+        end
+        unreadable.each do |name|
+          diagnostics&.record_discovery_failure(File.join(top, name), reason: "unreadable")
+        end
+        warn_unreadable(unreadable, diagnostics)
+      end
+
+      # Absolute paths of untracked, non-ignored files under ROOT: they
+      # never appear in the diff but can still sit in excluded territory.
+      def paths(root)
+        top = Text.utf8_identity(GitDiff.git(root, "rev-parse", "--show-toplevel").b.strip)
+        files(top).map { |name| File.join(top, name) }
+      end
+
+      def files(top)
+        GitDiff.git(top, "ls-files", "-z", "--others", "--exclude-standard").b.split("\0").map do |name|
+          Text.utf8_identity(name)
+        end
+      end
+
+      # An included untracked file that cannot be read (vanished,
+      # unreadable or replaced after the listing) is missing source
+      # coverage: a clean --since must not hide it.
+      def warn_unreadable(names, diagnostics)
+        return if names.empty? || diagnostics.nil?
+
+        shown = names.sort.first(5).join(", ")
+        shown += ", ..." if names.size > 5
+        diagnostics.warn("--since: #{names.size} included untracked file(s) could not be read (vanished, " \
+                         "unreadable or replaced), so their subjects are not covered: #{shown}")
+      end
+
+      # Line count of an untracked file opened race-free: nil when the
+      # file stays out of the map by content (empty, or binary inside the
+      # sniff window), or :unreadable when it could not be validated
+      # (vanished, unreadable, a symlink, not a regular file).
+      def line_count(file, flags)
+        File.open(file, flags) do |io|
+          next :unreadable unless io.stat.file?
+
+          count_lines(io)
+        end
+      rescue SystemCallError, IOError
+        :unreadable
+      end
+
+      # Every read is bounded: the binary sniff takes only the first few
+      # kilobytes (git's own heuristic window; read of an empty file is
+      # nil, never ""), then the count streams in fixed chunks.
+      def count_lines(io)
+        first = io.read(BINARY_SNIFF_BYTES)
+        return if first.nil? || first.include?("\0")
+
+        lines = first.count("\n")
+        trailing_newline = first.end_with?("\n")
+        # A no-arg read returns "" at EOF, never nil - guard the loop so a
+        # mutant that drops the chunk size spins zero times, not forever.
+        while (chunk = io.read(READ_CHUNK_BYTES)) && !chunk.empty?
+          lines += chunk.count("\n")
+          trailing_newline = chunk.end_with?("\n")
+        end
+        trailing_newline ? lines : lines + 1
+      end
+    end
+  end
+end

data/lib/saboteur/subject.rb

@@ -114,6 +114,17 @@ module Saboteur
       line.between?(start_line, end_line)
     end
 
+    # True when a changed-lines set intersects this subject's span. A
+    # whole-file range answers by interval overlap in O(1) instead of a
+    # per-line scan from line 1 for every subject.
+    def overlaps_lines?(lines)
+      if lines.is_a?(Range)
+        lines.begin <= end_line && start_line <= lines.end
+      else
+        lines.any? { |line| contains_line?(line) }
+      end
+    end
+
     # Applies the mutation's edits to this method's text and returns the
     # mutated method text. Raises ArgumentError for edits outside the method
     # or overlapping each other.

data/lib/saboteur/text.rb

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "json"
+
+module Saboteur
+  # Bytes arriving from outside the process (git output, cache and log files,
+  # worker pipes) are tagged with the process locale. Under a non-UTF-8
+  # locale such as LANG=C that tag is US-ASCII, where any non-ASCII byte
+  # raises on use. Re-tag everything crossing the boundary as UTF-8.
+  module Text
+    module_function
+
+    # Lossy: bytes that are not valid UTF-8 become the replacement
+    # character. For log and message display only - never feed the result
+    # back into filesystem, cache or protocol identity: scrubbing rewrites
+    # raw bytes, which can alias two different names or make a path vanish
+    # from a File.exist? probe.
+    def utf8(string)
+      string.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    # Lossless: every byte survives; only the encoding tag changes. Use for
+    # paths and identity-bearing fields. File.* calls and String == then
+    # work on the exact bytes git reported; only rendering (regexes over
+    # arbitrary content, JSON, terminal output) needs #utf8.
+    def utf8_identity(string)
+      string.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    # Lossless + strict: retag without scrubbing, then reject bytes
+    # that are not valid UTF-8 with JSON::ParserError, so a JSON
+    # boundary's existing parse-error handling rejects corrupt input
+    # instead of silently accepting a rewritten version of it.
+    def utf8_strict(string)
+      tagged = utf8_identity(string)
+      raise JSON::ParserError, "invalid UTF-8" unless tagged.valid_encoding?
+
+      tagged
+    end
+  end
+end

data/lib/saboteur/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Saboteur
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/saboteur.rb

@@ -6,11 +6,26 @@ require_relative "saboteur/version"
 module Saboteur
   class Error < StandardError; end
 
+  # A phase timeout that --max-duration shortened: budget exhaustion, not a
+  # broken suite. The engine turns it into the budget partial-report path
+  # instead of a phase error (#296).
+  class BudgetPhaseTimeout < Error; end
+
   # Invalid configuration or input files (exit code 2).
   class ConfigError < Error; end
 
   # Files vanished from the working tree while mutants ran (exit code 3).
-  class CanaryTripped < Error; end
+  class CanaryTripped < Error
+    # Set by the per-mutant probe (the mutant whose run just ended, #235);
+    # nil for a subject-end check, whose "most recent mutant" is only the
+    # likely cause and must not outrank a per-mutant report (#285).
+    attr_reader :culprit_digest
+
+    def initialize(message = nil, culprit_digest: nil)
+      @culprit_digest = culprit_digest
+      super(message)
+    end
+  end
 
   class << self
     # Set while hook files from config load, so they can call Saboteur.hook.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: saboteur
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Vamsi Pavan Mahesh Gunturu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiddle
@@ -73,9 +73,13 @@ files:
 - lib/saboteur/baseline_health.rb
 - lib/saboteur/cli.rb
 - lib/saboteur/cli/exit_status.rb
+- lib/saboteur/cli/help_options.rb
+- lib/saboteur/cli/presets.rb
+- lib/saboteur/cli/run_budget_options.rb
 - lib/saboteur/cli/run_reporting.rb
 - lib/saboteur/config.rb
 - lib/saboteur/config_file.rb
+- lib/saboteur/crash_report.rb
 - lib/saboteur/custom_map.rb
 - lib/saboteur/doctor.rb
 - lib/saboteur/engine.rb
@@ -85,19 +89,24 @@ files:
 - lib/saboteur/engine/canary.rb
 - lib/saboteur/engine/candidate_selection.rb
 - lib/saboteur/engine/candidates.rb
+- lib/saboteur/engine/coverage_guard.rb
 - lib/saboteur/engine/coverage_store.rb
 - lib/saboteur/engine/data_inputs.rb
 - lib/saboteur/engine/diagnostics.rb
 - lib/saboteur/engine/diff_scope.rb
 - lib/saboteur/engine/distribution.rb
+- lib/saboteur/engine/early_stop_recording.rb
 - lib/saboteur/engine/result_cache.rb
+- lib/saboteur/engine/run_budget.rb
 - lib/saboteur/engine/run_fingerprint.rb
 - lib/saboteur/engine/sandbox_policy.rb
 - lib/saboteur/engine/scheduler.rb
 - lib/saboteur/engine/subject_selection.rb
 - lib/saboteur/engine/suite_files.rb
 - lib/saboteur/engine/test_guess.rb
+- lib/saboteur/engine/thread_warnings.rb
 - lib/saboteur/engine/unchanged_syntax.rb
+- lib/saboteur/engine/unscoped_suite_warning.rb
 - lib/saboteur/engine/verdict_check.rb
 - lib/saboteur/execution/fork_readiness.rb
 - lib/saboteur/execution/process_table.rb
@@ -110,6 +119,7 @@ files:
 - lib/saboteur/execution/supervisor.rb
 - lib/saboteur/execution/worker_pool.rb
 - lib/saboteur/execution/wrapper.rb
+- lib/saboteur/frameworks/database_hosts.rb
 - lib/saboteur/frameworks/rails.rb
 - lib/saboteur/gates.rb
 - lib/saboteur/help.rb
@@ -129,10 +139,15 @@ files:
 - lib/saboteur/mutation_source/endpoint_replacement.rb
 - lib/saboteur/mutation_source/filter_replacement.rb
 - lib/saboteur/mutation_source/hazard_guard.rb
+- lib/saboteur/mutation_source/interpolation_removal.rb
 - lib/saboteur/mutation_source/literal_replacement.rb
+- lib/saboteur/mutation_source/method_swap.rb
 - lib/saboteur/mutation_source/mutation.rb
+- lib/saboteur/mutation_source/operand_replacement.rb
 - lib/saboteur/mutation_source/operator_assignment.rb
+- lib/saboteur/mutation_source/operator_examples.rb
 - lib/saboteur/mutation_source/operator_registry.rb
+- lib/saboteur/mutation_source/operator_visit.rb
 - lib/saboteur/mutation_source/pair_removal.rb
 - lib/saboteur/mutation_source/range_replacement.rb
 - lib/saboteur/preview.rb
@@ -145,6 +160,7 @@ files:
 - lib/saboteur/reporter/diff.rb
 - lib/saboteur/reporter/findings.rb
 - lib/saboteur/reporter/history_paths.rb
+- lib/saboteur/reporter/history_policy.rb
 - lib/saboteur/reporter/history_record.rb
 - lib/saboteur/reporter/html.rb
 - lib/saboteur/reporter/mutation_text.rb
@@ -164,8 +180,10 @@ files:
 - lib/saboteur/selection/coverage_map.rb
 - lib/saboteur/selection/git_diff.rb
 - lib/saboteur/selection/recorder.rb
+- lib/saboteur/selection/untracked_changes.rb
 - lib/saboteur/subject.rb
 - lib/saboteur/subject_finder.rb
+- lib/saboteur/text.rb
 - lib/saboteur/version.rb
 - lib/saboteur/working_tree.rb
 homepage: https://github.com/vamsipavanmahesh/saboteur