active_mutator 0.1.0

data/lib/active_mutator/scheduler.rb

@@ -0,0 +1,125 @@
+require "json"
+
+module ActiveMutator
+  # Fork pool: one fork per WorkItem, capped at `jobs` concurrent forks.
+  # Parent enforces per-item deadlines with SIGKILL (worker-side timeouts
+  # cannot interrupt all infinite loops).
+  class Scheduler
+    def initialize(jobs:, worker: Worker.method(:run), on_result: nil)
+      @jobs = jobs
+      @worker = worker
+      @on_result = on_result
+    end
+
+    def run(items)
+      previous_traps = nil
+      running = {}
+      previous_traps = install_signal_handlers(running)
+      results = []
+      # Browser-covered mutants each boot Chrome + an app server; running them
+      # concurrently melts CPUs and manufactures false timeouts. Parallel lane
+      # first at full width, then the serial lane one at a time.
+      results.concat(run_pool(items.select { |i| i.lane == :parallel }, @jobs, running))
+      results.concat(run_pool(items.select { |i| i.lane == :serial }, 1, running))
+      results
+    ensure
+      restore_traps(previous_traps) if previous_traps
+    end
+
+    private
+
+    def run_pool(items, width, running)
+      queue = items.dup
+      results = []
+      until queue.empty? && running.empty?
+        spawn(queue.shift, running) while running.size < width && !queue.empty?
+        reap(running, results)
+        sleep 0.02 unless running.empty?
+      end
+      results
+    end
+
+    def spawn(item, running)
+      reader, writer = IO.pipe
+      pid = fork do
+        reader.close
+        Process.setpgid(0, 0)          # own process group: deadline kill reaps grandchildren too
+        $stdout.reopen(File::NULL)     # app code that prints must not corrupt parent's report
+        $stderr.reopen(File::NULL)     # ditto for warnings (RSpec/app noise interleaves with reports)
+        @worker.call(item.mutation, item.example_ids, writer)
+        writer.close
+        Process.exit!(0)
+      end
+      writer.close
+      running[pid] = { reader: reader, item: item, deadline: now + item.timeout }
+    end
+
+    def reap(running, results)
+      running.to_a.each do |pid, entry|
+        done, _status = Process.waitpid2(pid, Process::WNOHANG)
+        if done
+          running.delete(pid)
+          results << finish(entry)
+        elsif now > entry[:deadline]
+          kill(pid)
+          running.delete(pid)
+          entry[:reader].close
+          results << report(Result.new(mutation: entry[:item].mutation, status: :timeout, details: nil))
+        end
+      end
+    end
+
+    def finish(entry)
+      payload = entry[:reader].read.to_s
+      entry[:reader].close
+      data = payload.empty? ? nil : JSON.parse(payload)
+      status = data ? data.fetch("status").to_sym : :error
+      details = data ? data["details"] : "worker exited without reporting"
+      report(Result.new(mutation: entry[:item].mutation, status: status, details: details))
+    end
+
+    def report(result)
+      @on_result&.call(result)
+      result
+    end
+
+    def kill(pid)
+      Process.kill("KILL", -pid) # negative pid = whole process group
+    rescue Errno::ESRCH, Errno::EPERM
+      # Group not established yet (setpgid race) or already gone — direct kill.
+      begin
+        Process.kill("KILL", pid)
+      rescue Errno::ESRCH
+        nil
+      end
+    ensure
+      begin
+        Process.waitpid(pid)
+      rescue Errno::ECHILD
+        nil
+      end
+    end
+
+    # Returns {sig => previous_handler} so #run can restore on exit —
+    # otherwise our traps permanently replace the host's (e.g. RSpec's Ctrl-C).
+    def install_signal_handlers(running)
+      %w[INT TERM].to_h do |sig|
+        previous = trap(sig) do
+          running.each_key do |pid|
+            Process.kill("KILL", -pid)
+          rescue StandardError
+            nil
+          end
+          exit(130)
+        end
+        [sig, previous]
+      end
+    end
+
+    def restore_traps(previous)
+      previous.each { |sig, handler| trap(sig, handler || "DEFAULT") }
+    end
+
+    def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/active_mutator/since_filter.rb

@@ -0,0 +1,48 @@
+module ActiveMutator
+  # Restricts subjects to methods overlapping lines changed since a git ref.
+  # Known v1 limit: `git diff <ref>` omits untracked files, so brand-new
+  # uncommitted files are skipped.
+  class SinceFilter
+    HUNK = /\A@@ [^+]*\+(\d+)(?:,(\d+))? @@/
+
+    def self.parse(diff_text)
+      changed = Hash.new { |h, k| h[k] = [] }
+      current = nil
+      diff_text.each_line do |line|
+        if line.start_with?("+++ b/")
+          current = line.delete_prefix("+++ b/").strip
+        elsif current && (match = HUNK.match(line))
+          start = match[1].to_i
+          count = (match[2] || "1").to_i
+          count.times { |i| changed[current] << start + i }
+        end
+      end
+      changed.reject { |_, lines| lines.empty? }
+    end
+
+    def initialize(ref:, root:)
+      @root = root
+      diff = IO.popen(
+        ["git", "-C", root, "diff", "--unified=0", ref, "--", "*.rb"], &:read
+      )
+      raise Error, "git diff #{ref} failed" unless $?.success?
+
+      @changed = self.class.parse(diff)
+      untracked = IO.popen(
+        ["git", "-C", root, "ls-files", "--others", "--exclude-standard", "--", "*.rb"], &:read
+      )
+      # Untracked files are invisible to `git diff` but are agentic TDD's most
+      # common case (brand-new file + spec). Whole-file sentinel: every line
+      # counts as changed.
+      untracked.each_line { |l| @changed[l.strip] = :all unless l.strip.empty? }
+    end
+
+    def cover?(subject)
+      lines = @changed[subject.file.delete_prefix("#{@root}/")]
+      return false unless lines
+      return true if lines == :all
+
+      lines.any? { |line| subject.line_range.cover?(line) }
+    end
+  end
+end

data/lib/active_mutator/splicer.rb

@@ -0,0 +1,13 @@
+module ActiveMutator
+  module Splicer
+    # Applies edits to source by byte offset. Edits are applied back-to-front
+    # so earlier offsets never drift.
+    def self.apply(source, edits)
+      bytes = source.b
+      edits.sort_by { |e| -e.range.begin }.each do |e|
+        bytes[e.range] = e.replacement.b
+      end
+      bytes.force_encoding(source.encoding)
+    end
+  end
+end

data/lib/active_mutator/subject.rb

@@ -0,0 +1,7 @@
+module ActiveMutator
+  # A mutable unit: one method definition.
+  # byte_range/line_range cover the whole `def ... end`.
+  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind) do
+    def singleton? = kind == :singleton
+  end
+end

data/lib/active_mutator/subject_finder.rb

@@ -0,0 +1,56 @@
+module ActiveMutator
+  class SubjectFinder < Prism::Visitor
+    def self.call(file)
+      result = Prism.parse(File.read(file))
+      return [] unless result.success?
+
+      finder = new(file)
+      finder.visit(result.value)
+      finder.subjects
+    end
+
+    attr_reader :subjects
+
+    def initialize(file)
+      @file = file
+      @stack = []
+      @subjects = []
+      super()
+    end
+
+    def visit_class_node(node)
+      with_scope(node.constant_path.slice) { super }
+    end
+
+    def visit_module_node(node)
+      with_scope(node.constant_path.slice) { super }
+    end
+
+    # `class << self` bodies are a documented v1 limit: not visited.
+    def visit_singleton_class_node(node); end
+
+    def visit_def_node(node)
+      singleton = node.receiver.is_a?(Prism::SelfNode)
+      scope = @stack.empty? ? nil : @stack.join("::")
+      loc = node.location
+      @subjects << Subject.new(
+        name: "#{scope || "Object"}#{singleton ? "." : "#"}#{node.name}",
+        file: @file,
+        byte_range: loc.start_offset...loc.end_offset,
+        line_range: loc.start_line..loc.end_line,
+        constant_scope: scope,
+        kind: singleton ? :singleton : :instance
+      )
+      # No `super`: nested defs are out of scope for v1.
+    end
+
+    private
+
+    def with_scope(name)
+      @stack.push(name)
+      yield
+    ensure
+      @stack.pop
+    end
+  end
+end

data/lib/active_mutator/version.rb

@@ -0,0 +1,3 @@
+module ActiveMutator
+  VERSION = "0.1.0"
+end

data/lib/active_mutator/work_item.rb

@@ -0,0 +1,4 @@
+module ActiveMutator
+  # lane: :parallel (default pool) | :serial (browser-covered, one at a time)
+  WorkItem = Data.define(:mutation, :example_ids, :timeout, :lane)
+end

data/lib/active_mutator/worker.rb

@@ -0,0 +1,64 @@
+require "json"
+require "set"
+
+module ActiveMutator
+  # Runs INSIDE a fork. Order is critical: RSpec's setup phase loads the spec
+  # files, whose spec_helper/rails_helper loads the application — only THEN
+  # can the mutation be inserted over the loaded original. Insert-first would
+  # NameError on any project not preloaded in the parent (all non-Rails
+  # projects), and loading app code after insertion would silently restore
+  # the original method.
+  class Worker
+    def self.run(mutation, example_ids, writer)
+      new(mutation, example_ids, writer).run
+    end
+
+    def initialize(mutation, example_ids, writer)
+      @mutation = mutation
+      @example_ids = example_ids
+      @writer = writer
+    end
+
+    def run
+      require "rspec/core"
+      devnull = File.open(File::NULL, "w")
+      runner = RSpec::Core::Runner.new(RSpec::Core::ConfigurationOptions.new(@example_ids))
+      runner.setup(devnull, devnull)   # loads spec files -> loads the app
+      Inserter.new.insert(@mutation)   # now the target constant exists
+      after_fork_hygiene
+      code = runner.run_specs(covering_groups)
+      emit(code.zero? ? "survived" : "killed")
+    rescue StandardError, ScriptError => e
+      emit("error", details: "#{e.class}: #{e.message}")
+    end
+
+    private
+
+    def after_fork_hygiene
+      srand
+      if defined?(ActiveRecord::Base)
+        ActiveRecord::Base.connection_handler.clear_all_connections!
+        ActiveRecord::Base.establish_connection
+      end
+    end
+
+    def emit(status, details: nil)
+      @writer.puts(JSON.generate("status" => status, "details" => details))
+      @writer.flush if @writer.respond_to?(:flush)
+    end
+
+    # RSpec.world holds every group registered in the process — including any
+    # top-level groups evaluated while the PARENT preloaded the spec helper
+    # (spec/support files with RSpec.describe at load time are common). Those
+    # leak into the fork; running them would report their failures as false
+    # kills. Run only groups that belong to the covering spec files.
+    def covering_groups
+      covering = @example_ids
+                 .map { |id| File.expand_path(id[/\A(.+?)\[/, 1]) }
+                 .to_set
+      RSpec.world.ordered_example_groups.select do |group|
+        covering.include?(group.metadata[:absolute_file_path])
+      end
+    end
+  end
+end

data/lib/active_mutator.rb

@@ -0,0 +1,42 @@
+require "prism"
+
+require_relative "active_mutator/version"
+
+module ActiveMutator
+  Error = Class.new(StandardError)
+  BaselineFailed = Class.new(Error)
+end
+
+require_relative "active_mutator/edit"
+require_relative "active_mutator/splicer"
+require_relative "active_mutator/subject"
+require_relative "active_mutator/subject_finder"
+require_relative "active_mutator/operators/base"
+require_relative "active_mutator/operators/conditional_boundary"
+require_relative "active_mutator/operators/condition_forcing"
+require_relative "active_mutator/operators/logical_operator"
+require_relative "active_mutator/operators/literal"
+require_relative "active_mutator/operators/statement_deletion"
+require_relative "active_mutator/operators/early_return"
+require_relative "active_mutator/operators/call_swap"
+require_relative "active_mutator/operators/negation_removal"
+require_relative "active_mutator/mutation"
+require_relative "active_mutator/analysis"
+require_relative "active_mutator/engine"
+require_relative "active_mutator/atomic_file"
+require_relative "active_mutator/coverage_map"
+require_relative "active_mutator/baseline"
+require_relative "active_mutator/baseline_delta"
+require_relative "active_mutator/inserter"
+require_relative "active_mutator/worker"
+require_relative "active_mutator/result"
+require_relative "active_mutator/work_item"
+require_relative "active_mutator/scheduler"
+require_relative "active_mutator/reporter/terminal"
+require_relative "active_mutator/reporter/json"
+require_relative "active_mutator/since_filter"
+require_relative "active_mutator/fingerprint"
+require_relative "active_mutator/accepted_ledger"
+require_relative "active_mutator/config"
+require_relative "active_mutator/runner"
+require_relative "active_mutator/cli"

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: active_mutator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel John
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.30'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.30'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: 'Mutation testing for Ruby and Rails: Prism-based source-span mutations
+  (no unparser), coverage-mapped test selection, and a fork-per-mutant kill pipeline.
+  Scopes to changed methods for a fast dev loop, or a diff for CI, with an incremental
+  coverage baseline and a committed acceptance ledger for equivalent mutants.'
+email:
+executables:
+- active_mutator
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/active_mutator
+- lib/active_mutator.rb
+- lib/active_mutator/accepted_ledger.rb
+- lib/active_mutator/analysis.rb
+- lib/active_mutator/atomic_file.rb
+- lib/active_mutator/baseline.rb
+- lib/active_mutator/baseline_delta.rb
+- lib/active_mutator/baseline_hooks.rb
+- lib/active_mutator/cli.rb
+- lib/active_mutator/config.rb
+- lib/active_mutator/coverage_map.rb
+- lib/active_mutator/edit.rb
+- lib/active_mutator/engine.rb
+- lib/active_mutator/fingerprint.rb
+- lib/active_mutator/inserter.rb
+- lib/active_mutator/mutation.rb
+- lib/active_mutator/operators/base.rb
+- lib/active_mutator/operators/call_swap.rb
+- lib/active_mutator/operators/condition_forcing.rb
+- lib/active_mutator/operators/conditional_boundary.rb
+- lib/active_mutator/operators/early_return.rb
+- lib/active_mutator/operators/literal.rb
+- lib/active_mutator/operators/logical_operator.rb
+- lib/active_mutator/operators/negation_removal.rb
+- lib/active_mutator/operators/statement_deletion.rb
+- lib/active_mutator/reporter/json.rb
+- lib/active_mutator/reporter/terminal.rb
+- lib/active_mutator/result.rb
+- lib/active_mutator/runner.rb
+- lib/active_mutator/scheduler.rb
+- lib/active_mutator/since_filter.rb
+- lib/active_mutator/splicer.rb
+- lib/active_mutator/subject.rb
+- lib/active_mutator/subject_finder.rb
+- lib/active_mutator/version.rb
+- lib/active_mutator/work_item.rb
+- lib/active_mutator/worker.rb
+homepage: https://github.com/drj613/active_mutator
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/drj613/active_mutator
+  source_code_uri: https://github.com/drj613/active_mutator
+  changelog_uri: https://github.com/drj613/active_mutator/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/drj613/active_mutator/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Mutation testing for Ruby, built on Prism
+test_files: []