mutineer 0.2.0

data/lib/mutineer/runner.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "project"
+require_relative "result"
+require_relative "isolation"
+require_relative "minitest_integration"
+require_relative "coverage_map"
+require_relative "mutator_registry"
+require_relative "worker_pool"
+
+module Mutineer
+  # Orchestrates one mutation end-to-end: apply it textually, validate the
+  # result, select its covering test files from the coverage map, then run only
+  # those against the mutated source in an isolated child process (strategy 7a —
+  # whole-file reload via `load`).
+  #
+  # The source file path is passed explicitly because Mutation carries only byte
+  # offsets, not its file. M3 replaces M2's hardcoded `test_file:` with coverage-
+  # map selection: a mutation whose line no test exercises is :no_coverage (no
+  # fork); otherwise exactly the covering test files run in the child.
+  class Runner
+    # Full Phase B orchestration: resolve operators, discover subjects, build the
+    # coverage map, run every mutation, and aggregate. Returns
+    # [AggregateResult, source_map]. The CLI then reports + applies the exit code;
+    # the integration test asserts directly on the AggregateResult.
+    #
+    # The parent process `require`s each source file so its classes exist; forked
+    # children inherit them, so a covering test file's own require_relative of the
+    # source is a no-op and does not clobber the mutated `load` (spec §7).
+    def self.execute(config)
+      operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
+
+      # Boot mode: require the boot file ONCE so the app env (e.g. Rails) is booted
+      # in the parent and inherited by every fork. Do NOT manually require the
+      # sources — under Zeitwerk a manual require of an autoloadable file raises;
+      # the booted env autoloads them, and subject discovery is a static Prism
+      # parse that needs nothing loaded. Standalone mode requires the sources as
+      # before so their classes exist for the children to inherit.
+      if config.boot
+        require File.expand_path(config.boot, config.project_root)
+      else
+        config.sources.each { |f| require File.expand_path(f, config.project_root) }
+      end
+      config.require_paths.each { |f| require File.expand_path(f, config.project_root) }
+
+      # Boot mode skips coverage selection entirely: every mutant runs the given
+      # --test files (precomputed absolute here, used directly by Runner.run).
+      if config.boot
+        coverage_map = nil
+        boot_tests = config.tests.map { |t| File.expand_path(t, config.project_root) }
+        # Rails/Minitest test files do `require "test_helper"`, which needs the
+        # test root on $LOAD_PATH (`bin/rails test` adds it). Prepend each test
+        # file's helper root here in the parent so loading them in the fork
+        # children resolves. Inherited by every fork.
+        test_load_roots(boot_tests).each { |d| $LOAD_PATH.unshift(d) unless $LOAD_PATH.include?(d) }
+      else
+        coverage_map = CoverageMap.new(
+          source_paths: config.sources, test_paths: config.tests,
+          cache_dir: config.cache_dir, project_root: config.project_root,
+          load_paths: config.load_paths
+        ).build_or_load
+        boot_tests = nil
+      end
+
+      # Collect every (subject, mutation) up front so the pool can fan them out.
+      source_map = {}
+      jobs = []
+      Project.discover(config.sources, only: config.only).each do |subject|
+        source = (source_map[subject.file] ||= File.read(subject.file))
+        operator_classes.each do |klass|
+          klass.new.mutations_for(subject, source).each do |mutation|
+            jobs << [subject, mutation]
+          end
+        end
+      end
+
+      # C3: 7a writes mutineer_mutant*.rb into each source dir (so require_relative
+      # resolves). A SIGKILL'd child skips the tempfile's ensure-unlink, orphaning
+      # it. `ensure` is unreliable vs SIGKILL, so the PARENT sweeps each source dir
+      # before and after the run — orphans are impossible after a normal run.
+      source_dirs = config.sources
+                          .map { |f| File.dirname(File.expand_path(f, config.project_root)) }.uniq
+      sweep_orphans(source_dirs)
+
+      strategy = config.strategy
+      results =
+        begin
+          bare = WorkerPool.new(config.jobs).run(jobs) do |subject, mutation|
+            run(mutation, source_file: subject.file, coverage_map: coverage_map,
+                subject: subject, strategy: strategy,
+                test_files: boot_tests, rails: config.rails)
+          end
+          # The bare Results carry only status (Subjects hold live AST nodes that
+          # do not marshal); reattach subject+mutation in the parent, in order.
+          bare.each_with_index.map { |r, i| r.with(subject: jobs[i][0], mutation: jobs[i][1]) }
+        ensure
+          sweep_orphans(source_dirs)
+        end
+
+      [AggregateResult.new(results), source_map]
+    end
+
+    # For each test file, the directory to add to $LOAD_PATH so its
+    # `require "test_helper"` (or spec_helper) resolves: the nearest ancestor
+    # holding that helper, plus the file's own dir as a fallback.
+    def self.test_load_roots(test_files)
+      test_files.flat_map do |f|
+        dir = File.dirname(f)
+        root = nil
+        loop do
+          if File.exist?(File.join(dir, "test_helper.rb")) || File.exist?(File.join(dir, "spec_helper.rb"))
+            root = dir
+            break
+          end
+          parent = File.dirname(dir)
+          break if parent == dir
+
+          dir = parent
+        end
+        [root, File.dirname(f)].compact
+      end.uniq
+    end
+
+    def self.sweep_orphans(dirs)
+      dirs.each do |dir|
+        Dir.glob(File.join(dir, "mutineer_mutant*.rb")).each do |f|
+          File.unlink(f) rescue nil # rubocop:disable Style/RescueModifier
+        end
+      end
+    end
+
+    def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
+                 timeout: Isolation::DEFAULT_TIMEOUT, test_files: nil, rails: false)
+      source  = File.read(source_file)
+      mutated = mutation.apply(source)
+
+      # Validity rule: a mutant that doesn't re-parse is skipped before forking.
+      return Result.skipped if Parser.parse_string(mutated).errors.any?
+
+      # Boot mode passes its tests directly (already absolute); standalone mode
+      # selects covering tests from the map and is :no_coverage when none cover it.
+      if test_files
+        abs_tests = test_files
+      else
+        line   = source.byteslice(0, mutation.start_offset).count("\n") + 1
+        chosen = coverage_map.tests_for(source_file, line)
+        return Result.no_coverage if chosen.empty?
+
+        abs_tests = chosen.map { |t| File.expand_path(t, coverage_map.project_root) }
+      end
+
+      Isolation.run(timeout: timeout) do
+        # Forking inherits the parent's live DB connection; sharing one socket
+        # across processes corrupts it. Drop it so AR reconnects per child.
+        reconnect_active_record if rails
+        if strategy == "redefine"
+          Isolation.apply_surgical(mutation, subject, source)
+        else
+          Isolation.apply_whole_file(mutated, source_file)
+        end
+        MinitestIntegration.run(abs_tests)
+      end
+    end
+
+    def self.reconnect_active_record
+      return unless defined?(ActiveRecord::Base)
+
+      ActiveRecord::Base.connection_handler.clear_all_connections!
+    rescue StandardError
+      nil
+    end
+    private_class_method :reconnect_active_record
+  end
+end

data/lib/mutineer/subject.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # One discoverable method: its location, namespace context, and the live
+  # Prism::DefNode mutators walk. Struct (not Data) because def_node is a live
+  # AST node — value-equality would be hollow, so we don't promise it.
+  Subject = Struct.new(:file, :namespace, :name, :singleton, :def_node, keyword_init: true) do
+    # e.g. "Billing::Invoice#total", "Billing::Invoice.build".
+    # Top-level (empty namespace) -> "#name" (no :: prefix).
+    def qualified_name
+      namespace.join("::") + (singleton ? "." : "#") + name.to_s
+    end
+
+    # nil for empty methods (def empty; end).
+    def body_loc
+      def_node.body&.location
+    end
+  end
+end

data/lib/mutineer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mutineer
+  VERSION = "0.2.0"
+end

data/lib/mutineer/worker_pool.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module Mutineer
+  # Fixed-size fork pool (KTD1/KTD2). `run` forks up to `size` children at once;
+  # each child runs the block on one work item, marshals its Result to a private
+  # pipe, and exits. The parent reaps any finished child with Process.wait2(-1),
+  # opening exactly one slot per reap, then refills. Results are returned in the
+  # SAME ORDER as `items` regardless of finish order, so verdicts are identical to
+  # a serial run (R4) and downstream output is stable.
+  #
+  # The block is evaluated inside the child via `yield(*items[i])`; whatever it
+  # returns (a Result) is the marshaled payload. Per-mutant timeout is handled one
+  # level down by Isolation (KTD2) — the pool adds no separate wall clock.
+  class WorkerPool
+    def initialize(size)
+      @size = [size.to_i, 1].max
+    end
+
+    def run(items)
+      results = Array.new(items.size)
+      queue   = (0...items.size).to_a
+      running = {} # pid => [index, read_io]
+
+      until queue.empty? && running.empty?
+        fill(items, queue, running) { |*args| yield(*args) }
+        reap(results, running)
+      end
+
+      results
+    end
+
+    private
+
+    def fill(items, queue, running)
+      while running.size < @size && !queue.empty?
+        idx = queue.shift
+        rd, wr = IO.pipe
+        begin
+          pid = fork do
+            rd.close
+            # R1: the child must ALWAYS hard-exit. If yield raises, marshal an
+            # error Result and exit! in `ensure` — otherwise the child unwinds
+            # normally and our Minitest at_exit autorun re-runs the parent suite
+            # inside the worker, losing the real error.
+            payload =
+              begin
+                yield(*items[idx])
+              rescue Exception => e # rubocop:disable Lint/RescueException
+                Result.error("worker crashed: #{e.class}: #{e.message}")
+              end
+            begin
+              wr.write(Marshal.dump(payload))
+            rescue StandardError # rubocop:disable Lint/SuppressedException
+              # pipe gone; parent will record "no result"
+            ensure
+              wr.close
+              exit!(0)
+            end
+          end
+        rescue Errno::EAGAIN
+          # Process table is full. Put the item back and reap before retrying;
+          # if nothing is running we cannot make progress, so re-raise.
+          rd.close
+          wr.close
+          raise if running.empty?
+
+          queue.unshift(idx)
+          return
+        end
+        wr.close
+        running[pid] = [idx, rd]
+      end
+    end
+
+    # R6: reap exactly one of OUR children. wait2(-1) would reap (steal) any of
+    # the host process's children — fatal when the pool runs under a forking test
+    # suite. Poll our known pids with WNOHANG instead.
+    def reap(results, running)
+      return if running.empty?
+
+      loop do
+        running.each_key do |pid|
+          reaped, = Process.waitpid2(pid, Process::WNOHANG)
+          next unless reaped
+
+          return collect(results, running, pid)
+        end
+        sleep 0.005
+      end
+    end
+
+    def collect(results, running, pid)
+      idx, rd = running.delete(pid)
+      data = rd.read
+      rd.close
+      results[idx] =
+        if data.empty?
+          Result.error("worker produced no result")
+        else
+          # R6: a partial/garbage Marshal stream (dead worker) must not crash the
+          # pool — degrade to an error Result.
+          begin
+            Marshal.load(data)
+          rescue StandardError => e
+            Result.error("worker result unreadable: #{e.class}: #{e.message}")
+          end
+        end
+    end
+  end
+end

data/lib/mutineer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "mutineer/version"
+require_relative "mutineer/config"
+require_relative "mutineer/parser"
+require_relative "mutineer/subject"
+require_relative "mutineer/mutation"
+require_relative "mutineer/project"
+require_relative "mutineer/result"
+require_relative "mutineer/coverage_map"
+require_relative "mutineer/isolation"
+require_relative "mutineer/minitest_integration"
+require_relative "mutineer/mutators/base"
+require_relative "mutineer/mutators/arithmetic"
+require_relative "mutineer/mutators/comparison"
+require_relative "mutineer/mutators/boolean_connector"
+require_relative "mutineer/mutators/boolean_literal"
+require_relative "mutineer/mutators/statement_removal"
+require_relative "mutineer/mutators/return_nil"
+require_relative "mutineer/mutators/literal_mutation"
+require_relative "mutineer/mutators/condition_negation"
+require_relative "mutineer/mutator_registry"
+require_relative "mutineer/worker_pool"
+require_relative "mutineer/runner"
+require_relative "mutineer/reporter"
+require_relative "mutineer/cli"
+
+module Mutineer
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: mutineer
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- David Teren
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Mutineer mutates your source one change at a time and runs your Minitest
+  suite against each mutant to find tests that don't actually test anything. Prism-based,
+  fork-isolated, zero runtime dependencies.
+email:
+- dteren@gmail.com
+executables:
+- mutineer
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/mutineer
+- lib/mutineer.rb
+- lib/mutineer/cli.rb
+- lib/mutineer/config.rb
+- lib/mutineer/coverage_map.rb
+- lib/mutineer/isolation.rb
+- lib/mutineer/minitest_integration.rb
+- lib/mutineer/mutation.rb
+- lib/mutineer/mutator_registry.rb
+- lib/mutineer/mutators/arithmetic.rb
+- lib/mutineer/mutators/base.rb
+- lib/mutineer/mutators/boolean_connector.rb
+- lib/mutineer/mutators/boolean_literal.rb
+- lib/mutineer/mutators/comparison.rb
+- lib/mutineer/mutators/condition_negation.rb
+- lib/mutineer/mutators/literal_mutation.rb
+- lib/mutineer/mutators/return_nil.rb
+- lib/mutineer/mutators/statement_removal.rb
+- lib/mutineer/parser.rb
+- lib/mutineer/project.rb
+- lib/mutineer/reporter.rb
+- lib/mutineer/result.rb
+- lib/mutineer/runner.rb
+- lib/mutineer/subject.rb
+- lib/mutineer/version.rb
+- lib/mutineer/worker_pool.rb
+homepage: https://github.com/davidteren/mutineer
+licenses:
+- MIT
+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
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A clean-room mutation-testing tool for Ruby (Prism + stdlib only).
+test_files: []