mutineer 0.11.4 → 1.0.1

data/lib/mutineer/file_swap.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
+require "digest"
+require "fileutils"
+
 module Mutineer
-  # Raised when a source file's backup already exists as FileSwap.with begins.
-  # A second mutineer run is racing on the same file (the backup path is shared
-  # and unlocked). Aborting beats silently leaving the tree mutated.
+  # Raised when another process already holds exclusive ownership of a source
+  # file. Aborting beats silently restoring (or capturing) the other run's mutant.
   class ConcurrentRunError < StandardError
-    def initialize(backup)
-      super("a backup already exists at #{backup} — is another mutineer run active " \
-            "in this directory? Aborting to avoid corrupting the source file.")
+    def initialize(path)
+      super("another mutineer run owns #{path} — aborting to avoid corrupting the source file.")
     end
   end
 
@@ -19,51 +20,92 @@ module Mutineer
   #
   # Defense in depth, mirroring the tempfile-orphan discipline
   # (`Runner.sweep_orphans`, `isolation.rb` tempfiles):
+  #   - exclusive OS ownership (flock) is acquired before swap or recovery;
   #   - the original bytes are held in memory AND written to a sibling backup;
   #   - `ensure` restores from memory around every mutant;
   #   - the backup survives a SIGKILL (which skips `ensure`), so `restore_orphans`
-  #     can self-heal a left-mutated tree on the next run's startup.
+  #     can self-heal a left-mutated tree on the next run's startup once the
+  #     kernel has released the dead owner's lock.
   # Only one mutant is in flight per file at a time (the external path is serial),
   # so backups never collide.
   module FileSwap
     # Suffix for the on-disk backup; fixed so `restore_orphans` finds it.
     BACKUP_SUFFIX = ".mutineer-backup"
 
+    # Subdirectory beside the source that holds flock files (stable across cwd
+    # and `cache_dir`, so concurrent runs on one inode share one lock).
+    LOCK_DIR_NAME = "file-swap-locks"
+
+    # Canonical source path => open lock File held by this process.
+    # @api private
+    OWNED = {}
+
+    # Real path when the file exists, otherwise `File.expand_path`. Symlink
+    # aliases of one inode share this identity for locks, backups, and ownership.
+    #
+    # @param path [String] source path, relative or absolute.
+    # @return [String] canonical absolute path.
+    def self.canonical_path(path)
+      expanded = File.expand_path(path)
+      File.exist?(expanded) ? File.realpath(expanded) : expanded
+    end
+
+    # Holds exclusive OS ownership of each source path for the duration of the
+    # block. Re-entrant for paths this process already owns. Raises
+    # {ConcurrentRunError} when another process holds a path (non-blocking).
+    #
+    # @param paths [Array<String>] source file paths to own.
+    # @yield the block to run while ownership is held.
+    # @return [Object] the block's return value.
+    def self.owning(paths)
+      acquired = []
+      Array(paths).map { |p| canonical_path(p) }.uniq.sort.each do |path|
+        next if OWNED.key?(path)
+
+        acquire!(path)
+        acquired << path
+      end
+      yield
+    ensure
+      acquired.reverse_each { |path| release!(path) }
+    end
+
     # Writes `mutated` to `source_file`, yields, then restores the original bytes
     # on every exit path (normal return, exception, or `ensure`). Byte-exact:
     # binary read/write preserves encoding, newlines, and trailing bytes.
+    # Acquires exclusive ownership first; a leftover backup with no live owner is
+    # treated as the original (a prior hard-killed run), not a concurrent run.
     #
     # @param source_file [String] path to the real source file.
     # @param mutated [String] mutated source text to write for the duration.
     # @yield the block to run while the mutant is on disk.
     # @return [Object] the block's return value.
     def self.with(source_file, mutated)
-      backup = source_file + BACKUP_SUFFIX
-      # A backup already on disk means either a prior hard-killed run
-      # (restore_orphans should have healed it at startup) or a SECOND mutineer
-      # run racing us on the same file. The backup path is shared and unlocked, so
-      # proceeding would let us capture the other run's mutant AS the "original"
-      # and permanently mutate the tree. Refuse loudly rather than silently
-      # corrupt, and do it BEFORE `created` is set, so the ensure below never
-      # touches a backup we don't own.
-      raise ConcurrentRunError, backup if File.exist?(backup)
-
-      original = File.binread(source_file)
-      File.binwrite(backup, original)
-      created = true
-      File.binwrite(source_file, mutated)
-      yield
-    ensure
-      if created
-        File.binwrite(source_file, original)
-        File.unlink(backup) if File.exist?(backup)
+      path = canonical_path(source_file)
+      created = false
+      original = nil
+      backup = path + BACKUP_SUFFIX
+      owning([path]) do
+        begin
+          original = File.exist?(backup) ? File.binread(backup) : File.binread(path)
+          File.binwrite(backup, original)
+          created = true
+          File.binwrite(path, mutated)
+          yield
+        ensure
+          if created
+            File.binwrite(path, original)
+            File.unlink(backup) if File.exist?(backup)
+          end
+        end
       end
     end
 
     # Startup/after-run self-heal: restore any source file left mutated by a prior
     # interrupted run (a leftover `*.mutineer-backup`), then remove the backup.
-    # Prints one line to stderr when it actually heals something, so a developer
-    # knows their working tree was auto-restored (a file they did not touch).
+    # Skips a backup whose source is owned by a live process. Prints one line to
+    # stderr when it actually heals something, so a developer knows their working
+    # tree was auto-restored (a file they did not touch).
     #
     # @param dirs [Array<String>] directories to sweep for orphaned backups.
     # @return [void]
@@ -72,19 +114,10 @@ module Mutineer
       dirs.uniq.each do |dir|
         Dir.glob(File.join(dir, "*#{BACKUP_SUFFIX}")).each do |backup|
           source_file = backup.delete_suffix(BACKUP_SUFFIX)
-          backup_bytes = File.binread(backup)
-          if !File.exist?(source_file)
-            # A real user file that merely ends in our suffix, with no sibling to
-            # restore. Leave it untouched (never create a file from it).
+          begin
+            owning([source_file]) { healed += restore_one(backup, source_file) }
+          rescue ConcurrentRunError
             next
-          elsif File.binread(source_file) == backup_bytes
-            # Redundant backup (e.g. a crash between restore and unlink): nothing
-            # to heal, just clear the orphan so the next run does not see a false race.
-            File.unlink(backup)
-          else
-            File.binwrite(source_file, backup_bytes)
-            File.unlink(backup)
-            healed += 1
           end
         end
       end
@@ -92,5 +125,68 @@ module Mutineer
 
       warn "[mutineer] restored #{healed} source file(s) left mutated by a previous interrupted run."
     end
+
+    # Exclusive non-blocking flock for canonical `path`.
+    #
+    # @api private
+    # @param path [String] canonical source path.
+    # @return [void]
+    # @raise [Mutineer::ConcurrentRunError] when the lock is held elsewhere.
+    def self.acquire!(path)
+      file = File.open(lock_file(path), File::RDWR | File::CREAT, 0o644)
+      unless file.flock(File::LOCK_EX | File::LOCK_NB)
+        file.close
+        raise ConcurrentRunError, path
+      end
+      OWNED[path] = file
+    end
+
+    # Flock path for a canonical source: `<dir>/.mutineer/file-swap-locks/<sha>`.
+    # Derived only from the source path so cwd and `cache_dir` cannot split a lock.
+    #
+    # @api private
+    # @param path [String] canonical source path.
+    # @return [String] lock file path.
+    def self.lock_file(path)
+      dir = File.join(File.dirname(path), ".mutineer", LOCK_DIR_NAME)
+      FileUtils.mkdir_p(dir)
+      File.join(dir, Digest::SHA256.hexdigest(path))
+    end
+
+    # Releases a lock acquired by {acquire!}.
+    #
+    # @api private
+    # @param path [String] expanded source path.
+    # @return [void]
+    def self.release!(path)
+      file = OWNED.delete(path)
+      return unless file
+
+      file.flock(File::LOCK_UN)
+      file.close
+    rescue StandardError
+      nil
+    end
+
+    # Restores one backup if the sibling source exists. Returns 1 when bytes
+    # were written back, 0 when the backup was redundant or had no sibling.
+    #
+    # @api private
+    # @param backup [String] path to the `*.mutineer-backup` file.
+    # @param source_file [String] corresponding source path.
+    # @return [Integer] 1 if healed, otherwise 0.
+    def self.restore_one(backup, source_file)
+      return 0 unless File.exist?(source_file)
+
+      backup_bytes = File.binread(backup)
+      if File.binread(source_file) == backup_bytes
+        File.unlink(backup)
+        0
+      else
+        File.binwrite(source_file, backup_bytes)
+        File.unlink(backup)
+        1
+      end
+    end
   end
 end

data/lib/mutineer/progress.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Coarse run progress on stderr: one line per 10% step of completed mutants
+  # (which means every completion on a run smaller than ten). Shared by every
+  # backend so a long run is never silent between config resolution and the
+  # report. Thread-safe so the daemon's parallel workers can share one instance.
+  # Writes only to stderr, keeping `--format json` stdout and `--output` files
+  # byte-exact per the Reporter's stream contract.
+  class Progress
+    # Builds a progress counter for a run of `total` mutants.
+    #
+    # @param total [Integer] number of mutants that will run.
+    # @param io [IO] destination stream (defaults to stderr; injectable for tests).
+    def initialize(total, io: $stderr)
+      @total = total
+      @done = 0
+      @last_step = 0
+      @mutex = Mutex.new
+      @io = io
+    end
+
+    # Records one completed mutant and prints when a 10% boundary is crossed.
+    # A zero-total counter never prints (guards the division, and an empty run
+    # has nothing to report).
+    #
+    # @return [void]
+    def tick
+      @mutex.synchronize do
+        return if @total.zero?
+
+        @done += 1
+        step = (@done * 10) / @total
+        return if step <= @last_step
+
+        @last_step = step
+        @io.puts "[mutineer] #{@done}/#{@total} mutants (#{(@done * 100) / @total}%)"
+      end
+    rescue IOError, Errno::EPIPE
+      # Progress is best-effort: a closed stderr (piped consumer went away) must
+      # never kill the run — in the daemon's worker threads a raise here would
+      # propagate through Thread#join and abort scoring.
+      nil
+    end
+  end
+end

data/lib/mutineer/reporter.rb

@@ -32,11 +32,14 @@ module Mutineer
 
     # Single entry point. Branches on `format` ("human" | "json" | "html") and
     # routes the rendered report to `output` (a file, with a stderr confirmation)
-    # or to `out`. Diagnostics always go to `err`.
-    def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil, baseline: nil)
+    # or to `out`. Diagnostics always go to `err`. `scoped` marks a diff-scoped
+    # (`--since`) run; the JSON report records it so a consumer (or a later
+    # `--baseline` load) knows the score covers only the changed-line mutants.
+    def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil,
+               baseline: nil, scoped: false)
       rendered =
         if format == "json"
-          json_report(baseline)
+          json_report(baseline, scoped: scoped)
         elsif format == "html"
           html_report
         else
@@ -126,8 +129,10 @@ module Mutineer
     #
     # @api private
     # @param baseline [Mutineer::Baseline::Delta, nil] baseline delta.
+    # @param scoped [Boolean] the run was diff-scoped (`--since`), so its score
+    #   covers only the changed-line mutants (additive `summary.scoped` key).
     # @return [String] JSON text.
-    def json_report(baseline = nil)
+    def json_report(baseline = nil, scoped: false)
       killed = @agg.killed_count
       survived = @agg.survived_count
       # null (not 0.0) on an empty denominator, matching the nil-vs-0.0
@@ -136,7 +141,7 @@ module Mutineer
       score = @agg.mutation_score
 
       doc = {
-        schema_version: "1.2",
+        schema_version: "1.3",
         summary: {
           total: @agg.total, killed: killed, survived: survived,
           no_coverage: @agg.no_coverage_count,
@@ -146,7 +151,11 @@ module Mutineer
           ignored: @agg.ignored_count,
           # The gate is computed from these two, so a consumer never re-derives them.
           attempted: attempted_count, no_verdict: no_verdict_count,
-          score: score
+          score: score,
+          # Additive: true when the run was diff-scoped (--since). The score then
+          # covers only the changed-line mutants, so it is not comparable to a
+          # full-run score; Baseline#diff reads this to skip the score-drop gate.
+          scoped: scoped
         },
         survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
                        .sort_by { |h| [h[:file], h[:line], h[:operator]] },
@@ -306,6 +315,10 @@ module Mutineer
         score_before: delta.score_before,
         score_after: delta.score_after,
         score_dropped: delta.score_drop,
+        # Additive: false when the score-drop check was skipped (a nil score or
+        # a diff-scoped side), so a consumer knows not to render the two scores
+        # as a comparison.
+        score_comparable: delta.score_comparable,
         new_survivors: delta.new_survivors.map { |r| ignored_json(r) }
                             .sort_by { |h| [h[:file], h[:line], h[:operator]] },
         fixed_survivors: delta.fixed_survivors.map do |h|
@@ -577,6 +590,9 @@ module Mutineer
         out.puts "  + #{r.subject.qualified_name} (#{file}:#{line}) #{r.mutation.operator}"
       end
       out.puts "score dropped #{delta.score_before}% -> #{delta.score_after}%" if delta.score_drop
+      # An OK verdict must not imply a check that never ran: say when the score
+      # comparison was skipped (a diff-scoped side or a nil score).
+      out.puts "score-drop check skipped (scores not comparable)" unless delta.score_comparable
       out.puts(delta.regressed ? "REGRESSION vs baseline" : "OK: no regression vs baseline")
     end
 

data/lib/mutineer/runner.rb

@@ -10,6 +10,7 @@ require_relative "coverage_map"
 require_relative "changed_lines"
 require_relative "mutator_registry"
 require_relative "worker_pool"
+require_relative "progress"
 require_relative "mutant_id"
 require_relative "file_swap"
 require_relative "external_backend"
@@ -98,6 +99,7 @@ module Mutineer
           load_paths: config.load_paths, framework: config.framework
         ).build_or_load
       end
+      abort_if_unclean!(coverage_map)
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
       jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
@@ -121,7 +123,9 @@ module Mutineer
         begin
           framework = config.framework
           stop_when = config.fail_fast ? ->(r) { r.survived? } : nil
-          bare = WorkerPool.new(jobs_n).run(jobs, stop_when: stop_when) do |subject, mutation|
+          progress  = Progress.new(jobs.size)
+          bare = WorkerPool.new(jobs_n).run(jobs, stop_when: stop_when,
+                                                  on_result: ->(_r) { progress.tick }) do |subject, mutation|
             run(mutation, source_file: subject.file, coverage_map: coverage_map,
                 subject: subject, strategy: strategy, rails: config.rails, framework: framework)
           end
@@ -181,42 +185,50 @@ module Mutineer
     # @return [Array(Mutineer::AggregateResult, Hash<String,String>)] aggregate and source map.
     def self.execute_external(config, operator_classes)
       abs_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
-      dirs      = source_dirs(config)
+      sources   = config.sources.map { |s| FileSwap.canonical_path(File.expand_path(s, config.project_root)) }
+      dirs      = sources.map { |s| File.dirname(s) }.uniq
+
+      # Own every source before healing leftovers or reading bytes for mutation.
+      # A backup file alone is not ownership; flock is. Canonical paths so
+      # symlink aliases of one inode share one lock, independent of cache_dir.
+      FileSwap.owning(sources) do
+        # Heal any file a prior hard-killed run left mutated BEFORE reading source.
+        # collect_jobs computes mutation offsets/ids from the on-disk bytes, so a
+        # still-mutated file would yield garbage offsets against the later-healed
+        # source. Heal first, then discover jobs from the clean tree.
+        FileSwap.restore_orphans(dirs)
 
-      # Heal any file a prior hard-killed run left mutated BEFORE reading source.
-      # collect_jobs computes mutation offsets/ids from the on-disk bytes, so a
-      # still-mutated file would yield garbage offsets against the later-healed
-      # source. Heal first, then discover jobs from the clean tree.
-      FileSwap.restore_orphans(dirs)
+        jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
+        jobs = filter_since(jobs, source_map, config) if config.since
 
-      jobs, ignored_results, source_map = collect_jobs(config, operator_classes)
-      jobs = filter_since(jobs, source_map, config) if config.since
+        # Nothing to mutate: return before the smoke check, which runs the whole
+        # --test set to calibrate a timeout no mutant would use (#76).
+        next [AggregateResult.new(ignored_results), source_map] if jobs.empty?
+
+        # Calibrate the per-mutant timeout from the clean run (a real suite far
+        # outlasts the 10s in-process fork budget), and abort if it is not green.
+        # 3x the clean run, floor 30s, ceiling 300s: a heuristic. The floor covers
+        # a fast suite; the ceiling bounds a hung mutant (infinite loop) so a
+        # handful cannot stall a serial run for ~45min on a slow suite.
+        smoke_elapsed = ExternalBackend.smoke_check!(config.test_command, abs_tests)
+        timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
 
-      # Nothing to mutate: return before the smoke check, which runs the whole
-      # --test set to calibrate a timeout no mutant would use (#76).
-      return [AggregateResult.new(ignored_results), source_map] if jobs.empty?
-
-      # Calibrate the per-mutant timeout from the clean run (a real suite far
-      # outlasts the 10s in-process fork budget), and abort if it is not green.
-      # 3x the clean run, floor 30s, ceiling 300s: a heuristic. The floor covers
-      # a fast suite; the ceiling bounds a hung mutant (infinite loop) so a
-      # handful cannot stall a serial run for ~45min on a slow suite.
-      smoke_elapsed = ExternalBackend.smoke_check!(config.test_command, abs_tests)
-      timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
-
-      results = []
-      begin
-        jobs.each do |subject, mutation, id|
-          r = run_external(subject, mutation, config.test_command, abs_tests,
-                           timeout: timeout, verbose: config.verbose)
-          results << r.with(subject: subject, mutation: mutation, id: id)
-          break if config.fail_fast && r.survived? # stop at the first survivor
+        results = []
+        progress = Progress.new(jobs.size)
+        begin
+          jobs.each do |subject, mutation, id|
+            r = run_external(subject, mutation, config.test_command, abs_tests,
+                             timeout: timeout, verbose: config.verbose)
+            results << r.with(subject: subject, mutation: mutation, id: id)
+            progress.tick
+            break if config.fail_fast && r.survived? # stop at the first survivor
+          end
+        ensure
+          FileSwap.restore_orphans(dirs)
         end
-      ensure
-        FileSwap.restore_orphans(dirs)
-      end
 
-      [AggregateResult.new(results + ignored_results), source_map]
+        [AggregateResult.new(results + ignored_results), source_map]
+      end
     end
 
     # Runs one mutant through the external backend: apply the whole-file mutation
@@ -236,6 +248,21 @@ module Mutineer
       end
     end
 
+    # Aborts the run when coverage capture saw a red unmutated suite. Scoring
+    # those results would treat existing assertion failures as killed mutants.
+    #
+    # @param coverage_map [Mutineer::CoverageMap] the built or loaded map.
+    # @return [void]
+    # @raise [Mutineer::SmokeCheckError] when any captured test failed clean.
+    def self.abort_if_unclean!(coverage_map)
+      files = coverage_map.failed_clean_tests
+      return if files.empty?
+
+      raise SmokeCheckError,
+            "the unmutated suite is not green (#{files.join(', ')}) — " \
+            "#{ExternalBackend.generic_env_hint}."
+    end
+
     # Coverage-based test selection, shared by the in-process ({run}) and daemon
     # paths so both narrow identically (score parity). Returns
     # `[:run, abs_test_paths]` when some test covers the mutant's line, or

data/lib/mutineer/version.rb

@@ -2,5 +2,5 @@
 
 module Mutineer
   # Current Mutineer release version.
-  VERSION = "0.11.4"
+  VERSION = "1.0.1"
 end

data/lib/mutineer/worker_pool.rb

@@ -28,10 +28,15 @@ module Mutineer
     # @param stop_when [Proc, nil] called with each collected Result; when it
     #   returns truthy, no further items are scheduled and the run drains and
     #   returns early (--fail-fast). Unscheduled slots stay nil.
+    # @param on_result [Proc, nil] called in the parent with each collected
+    #   Result as it is reaped, in finish order (progress reporting); its
+    #   return value is ignored. Must be fast and non-blocking: it runs on the
+    #   pool's single reap thread, so a slow callback stalls draining the other
+    #   in-flight children's pipes (the #4 deadlock discipline).
     # @yieldparam item [Array] one work item.
     # @return [Array<Mutineer::Result>] results in input order (nil for any item
     #   left unscheduled by an early stop).
-    def run(items, stop_when: nil)
+    def run(items, stop_when: nil, on_result: nil)
       results  = Array.new(items.size)
       queue    = (0...items.size).to_a
       running  = {} # pid => [index, read_io, buffer]
@@ -40,6 +45,7 @@ module Mutineer
       until queue.empty? && running.empty?
         fill(items, queue, running) { |*args| yield(*args) } unless stopping
         result = reap(results, running)
+        on_result&.call(result) if result
         if !stopping && stop_when && result && stop_when.call(result)
           stopping = true
           queue.clear # schedule no more; let in-flight workers drain

data/lib/mutineer.rb

@@ -27,6 +27,7 @@ require_relative "mutineer/mutators/regex_literal"
 require_relative "mutineer/mutators/collection_method"
 require_relative "mutineer/mutator_registry"
 require_relative "mutineer/worker_pool"
+require_relative "mutineer/progress"
 require_relative "mutineer/runner"
 require_relative "mutineer/reporter"
 require_relative "mutineer/baseline"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutineer
 version: !ruby/object:Gem::Version
-  version: 0.11.4
+  version: 1.0.1
 platform: ruby
 authors:
 - David Teren
@@ -95,6 +95,7 @@ files:
 - lib/mutineer/mutators/string_literal.rb
 - lib/mutineer/pairing.rb
 - lib/mutineer/parser.rb
+- lib/mutineer/progress.rb
 - lib/mutineer/project.rb
 - lib/mutineer/rails_worker_db.rb
 - lib/mutineer/reporter.rb
@@ -113,6 +114,7 @@ metadata:
   source_code_uri: https://github.com/davidteren/mutineer
   changelog_uri: https://github.com/davidteren/mutineer/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/davidteren/mutineer/issues
+  documentation_uri: https://davidteren.github.io/mutineer/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: