active_mutator 0.1.0

data/lib/active_mutator/coverage_map.rb

@@ -0,0 +1,55 @@
+require "json"
+
+module ActiveMutator
+  # Cache format v2: primary data is per-example `records`
+  # ({example_id => [[abs_path, line], ...]}); the inverted index is derived
+  # in memory at load. A missing/old version is simply stale — the cache is
+  # disposable, so there is no migration path, only regeneration.
+  class CoverageMap
+    def self.load(path) = new(JSON.parse(File.read(path)))
+
+    attr_reader :version, :records
+
+    def initialize(data)
+      @version = data["version"]
+      @records = data.fetch("records", {})
+      @times = data.fetch("times", {})
+      @digests = data.fetch("digests", {})
+      @map = build_map
+    end
+
+    def examples_for(file, lines)
+      lines.flat_map { |line| @map.fetch("#{file}:#{line}", []) }.uniq.sort
+    end
+
+    def time_for(example_ids)
+      # `|| 0.0`, not fetch-with-default: a key present with nil value must
+      # also coerce to zero, or Runner#plan_work explodes with TypeError.
+      example_ids.sum { |id| @times[id] || 0.0 }
+    end
+
+    def fresh?(digests) = @version == 2 && @digests == digests
+
+    def examples_covering_file(abs_path)
+      @records.filter_map do |example_id, hits|
+        example_id if hits.any? { |(path, _line)| path == abs_path }
+      end
+    end
+
+    def examples_for_spec_file(rel_spec_path)
+      @records.keys.select do |example_id|
+        example_id.sub(%r{\A\./}, "").start_with?("#{rel_spec_path}[")
+      end
+    end
+
+    private
+
+    def build_map
+      map = Hash.new { |h, k| h[k] = [] }
+      @records.each do |example_id, hits|
+        hits.each { |(path, line)| map["#{path}:#{line}"] << example_id }
+      end
+      map
+    end
+  end
+end

data/lib/active_mutator/edit.rb

@@ -0,0 +1,5 @@
+module ActiveMutator
+  # A single mutation as a text edit: replace `range` (exclusive byte Range)
+  # in the original source with `replacement`.
+  Edit = Data.define(:range, :replacement, :description)
+end

data/lib/active_mutator/engine.rb

@@ -0,0 +1,75 @@
+module ActiveMutator
+  class Engine
+    def initialize(operators: Operators::Base.all)
+      @operators = operators
+    end
+
+    def analyze(subject, source: File.read(subject.file))
+      result = Prism.parse(source)
+      raise Error, "#{subject.file} no longer parses" unless result.success?
+
+      def_node = find_def(result.value, subject.byte_range.begin)
+      raise Error, "subject not found: #{subject.name}" unless def_node
+
+      invalid = 0
+      mutations = collect_edits(def_node).filter_map do |edit|
+        mutation, valid = build_mutation(subject, source, edit)
+        invalid += 1 unless valid
+        mutation
+      end
+      Analysis.new(mutations: mutations, invalid_count: invalid)
+    end
+
+    private
+
+    def find_def(node, start_offset)
+      return node if node.is_a?(Prism::DefNode) && node.location.start_offset == start_offset
+
+      node.compact_child_nodes.each do |child|
+        found = find_def(child, start_offset)
+        return found if found
+      end
+      nil
+    end
+
+    def collect_edits(def_node)
+      edits = []
+      walk(def_node.body) do |node|
+        @operators.each { |op| edits.concat(op.edits(node)) }
+      end
+      edits
+    end
+
+    def walk(node, &blk)
+      return if node.nil?
+      return if node.is_a?(Prism::DefNode) # nested defs are separate subjects
+
+      yield node
+      node.compact_child_nodes.each { |child| walk(child, &blk) }
+    end
+
+    # Returns [mutation_or_nil, valid_boolean].
+    # valid=true with nil mutation means "skipped no-op", which is not an error.
+    def build_mutation(subject, source, edit)
+      original = source.byteslice(edit.range)
+      return [nil, true] if edit.replacement == original # no-op guard
+
+      mutated = Splicer.apply(source, [edit])
+      parsed = Prism.parse(mutated)
+      return [nil, false] unless parsed.success?
+
+      new_def = find_def(parsed.value, subject.byte_range.begin)
+      return [nil, false] unless new_def
+
+      [Mutation.new(
+        subject: subject,
+        edit: edit,
+        original_snippet: original,
+        line: source.byteslice(0, edit.range.begin).count("\n") + 1,
+        mutated_file_source: mutated,
+        mutated_def_source: new_def.slice,
+        mutated_def_line: new_def.location.start_line
+      ), true]
+    end
+  end
+end

data/lib/active_mutator/fingerprint.rb

@@ -0,0 +1,21 @@
+module ActiveMutator
+  # Line-number-independent identity for a mutant, used by the acceptance
+  # ledger. `ordinal` disambiguates byte-identical mutants within one subject
+  # (e.g. the two `>` in `a > 0 && b > 0`) by source order — without it,
+  # accepting one would silently accept both.
+  Fingerprint = Data.define(:file, :subject, :description, :original_snippet, :ordinal) do
+    def self.for_mutations(mutations, root:)
+      counters = Hash.new(0)
+      mutations.sort_by { |m| [m.subject.name, m.edit.range.begin] }.to_h do |m|
+        key = [m.subject.name, m.description, m.original_snippet]
+        ordinal = counters[key]
+        counters[key] += 1
+        [m, new(file: m.subject.file.delete_prefix("#{root}/"),
+                subject: m.subject.name,
+                description: m.description,
+                original_snippet: m.original_snippet,
+                ordinal: ordinal)]
+      end
+    end
+  end
+end

data/lib/active_mutator/inserter.rb

@@ -0,0 +1,18 @@
+module ActiveMutator
+  # Redefines the subject's method with its mutated source. `class_eval` of a
+  # `def` handles instance methods; a `def self.x` source string defines the
+  # singleton method the same way. Top-level subjects eval at main scope.
+  class Inserter
+    def insert(mutation)
+      subject = mutation.subject
+      if subject.constant_scope
+        Object.const_get(subject.constant_scope)
+              .class_eval(mutation.mutated_def_source, subject.file, mutation.mutated_def_line)
+      else
+        eval(mutation.mutated_def_source, TOPLEVEL_BINDING, # rubocop:disable Security/Eval
+             subject.file, mutation.mutated_def_line)
+      end
+      nil
+    end
+  end
+end

data/lib/active_mutator/mutation.rb

@@ -0,0 +1,11 @@
+module ActiveMutator
+  # One concrete mutant. `line` is the 1-based line of the edit in the
+  # ORIGINAL file (used for coverage lookup and reporting).
+  Mutation = Data.define(:subject, :edit, :original_snippet, :line,
+                         :mutated_file_source, :mutated_def_source, :mutated_def_line) do
+    def description = edit.description
+
+    # Original-file lines the edit touches (edit may span lines).
+    def lines = line..(line + original_snippet.count("\n"))
+  end
+end

data/lib/active_mutator/operators/base.rb

@@ -0,0 +1,25 @@
+module ActiveMutator
+  module Operators
+    class Base
+      REGISTRY = []
+
+      def self.inherited(klass)
+        super
+        REGISTRY << klass
+      end
+
+      def self.all = REGISTRY.map(&:new)
+
+      # Returns [Edit] for this node, or [] when the operator does not apply.
+      def edits(node) = []
+
+      private
+
+      def loc_range(loc) = loc.start_offset...loc.end_offset
+
+      def edit(range, replacement, description)
+        Edit.new(range: range, replacement: replacement, description: description)
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/call_swap.rb

@@ -0,0 +1,28 @@
+module ActiveMutator
+  module Operators
+    class CallSwap < Base
+      # One-directional where the reverse is usually an equivalent mutant
+      # (e.g. each→map when return value is unused).
+      MAP = {
+        map: "each",
+        select: "reject", reject: "select",
+        min: "max", max: "min",
+        first: "last", last: "first",
+        any?: "none?", none?: "any?",
+        # Rails-aware pack:
+        present?: "blank?", blank?: "present?",
+        save: "save!", save!: "save"
+      }.freeze
+
+      def edits(node)
+        return [] unless node.is_a?(Prism::CallNode) && node.receiver && node.message_loc
+
+        replacement = MAP[node.name]
+        return [] unless replacement
+
+        [edit(loc_range(node.message_loc), replacement,
+              "replace `.#{node.name}` with `.#{replacement}`")]
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/condition_forcing.rb

@@ -0,0 +1,17 @@
+module ActiveMutator
+  module Operators
+    class ConditionForcing < Base
+      def edits(node)
+        predicate =
+          case node
+          when Prism::IfNode, Prism::UnlessNode then node.predicate
+          end
+        return [] unless predicate
+
+        %w[true false].reject { |lit| predicate.slice == lit }.map do |lit|
+          edit(loc_range(predicate.location), lit, "force condition to `#{lit}`")
+        end
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/conditional_boundary.rb

@@ -0,0 +1,16 @@
+module ActiveMutator
+  module Operators
+    class ConditionalBoundary < Base
+      MAP = { :> => ">=", :>= => ">", :< => "<=", :<= => "<" }.freeze
+
+      def edits(node)
+        return [] unless node.is_a?(Prism::CallNode) && MAP.key?(node.name)
+        return [] unless node.receiver && node.arguments&.arguments&.size == 1
+
+        replacement = MAP.fetch(node.name)
+        [edit(loc_range(node.message_loc), replacement,
+              "replace `#{node.name}` with `#{replacement}`")]
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/early_return.rb

@@ -0,0 +1,16 @@
+module ActiveMutator
+  module Operators
+    class EarlyReturn < Base
+      def edits(node)
+        return [] unless node.is_a?(Prism::ReturnNode) && node.arguments
+
+        value = node.arguments.slice
+        out = [edit(loc_range(node.location), value, "unwrap `return`")]
+        unless value == "nil"
+          out << edit(loc_range(node.location), "return nil", "return nil instead")
+        end
+        out
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/literal.rb

@@ -0,0 +1,37 @@
+module ActiveMutator
+  module Operators
+    class Literal < Base
+      def edits(node)
+        case node
+        when Prism::IntegerNode then integer_edits(node)
+        when Prism::StringNode then string_edits(node)
+        when Prism::TrueNode
+          [edit(loc_range(node.location), "false", "replace `true` with `false`")]
+        when Prism::FalseNode
+          [edit(loc_range(node.location), "true", "replace `false` with `true`")]
+        else []
+        end
+      end
+
+      private
+
+      def integer_edits(node)
+        [0, node.value + 1].uniq.reject { |v| v == node.value }.map do |v|
+          edit(loc_range(node.location), v.to_s, "replace `#{node.value}` with `#{v}`")
+        end
+      end
+
+      def string_edits(node)
+        opening = node.opening_loc&.slice
+        return [] unless opening                  # quote-less parts (interpolation)
+        return [] if opening.start_with?("<<")    # heredocs: v1 limit
+
+        if node.unescaped.empty?
+          [edit(loc_range(node.location), %("active_mutator"), %(replace "" with "active_mutator"))]
+        else
+          [edit(loc_range(node.location), %(""), %(replace string with ""))]
+        end
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/logical_operator.rb

@@ -0,0 +1,24 @@
+module ActiveMutator
+  module Operators
+    class LogicalOperator < Base
+      def edits(node)
+        case node
+        when Prism::AndNode then variants(node, "||")
+        when Prism::OrNode then variants(node, "&&")
+        else []
+        end
+      end
+
+      private
+
+      def variants(node, swapped)
+        [
+          edit(loc_range(node.operator_loc), swapped,
+               "replace `#{node.operator_loc.slice}` with `#{swapped}`"),
+          edit(loc_range(node.location), node.left.slice, "keep only left operand"),
+          edit(loc_range(node.location), node.right.slice, "keep only right operand")
+        ]
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/negation_removal.rb

@@ -0,0 +1,11 @@
+module ActiveMutator
+  module Operators
+    class NegationRemoval < Base
+      def edits(node)
+        return [] unless node.is_a?(Prism::CallNode) && node.name == :! && node.receiver
+
+        [edit(loc_range(node.location), node.receiver.slice, "remove negation")]
+      end
+    end
+  end
+end

data/lib/active_mutator/operators/statement_deletion.rb

@@ -0,0 +1,15 @@
+module ActiveMutator
+  module Operators
+    class StatementDeletion < Base
+      def edits(node)
+        return [] unless node.is_a?(Prism::StatementsNode)
+        return [] if node.body.size < 2
+
+        node.body.map do |stmt|
+          edit(loc_range(stmt.location), "",
+               "delete `#{stmt.slice.lines.first.strip}`")
+        end
+      end
+    end
+  end
+end

data/lib/active_mutator/reporter/json.rb

@@ -0,0 +1,40 @@
+require "json"
+
+module ActiveMutator
+  module Reporter
+    class Json
+      def initialize(out: $stdout)
+        @out = out
+      end
+
+      def on_result(result); end
+
+      def summary(results, invalid_count:)
+        counts = results.group_by(&:status).transform_values(&:size)
+        @out.puts JSON.pretty_generate(
+          "score" => Terminal.score(counts),
+          "counts" => counts.transform_keys(&:to_s),
+          "invalid" => invalid_count,
+          "results" => results.map { |r| serialize(r) },
+          "exit_reason" => counts.fetch(:survived, 0).positive? ? "unaccepted_survivors" : "clean"
+        )
+      end
+
+      private
+
+      def serialize(result)
+        m = result.mutation
+        {
+          "subject" => m.subject.name,
+          "status" => result.status.to_s,
+          "description" => m.description,
+          "file" => m.subject.file,
+          "line" => m.line,
+          "original" => m.original_snippet,
+          "replacement" => m.edit.replacement,
+          "details" => result.details
+        }
+      end
+    end
+  end
+end

data/lib/active_mutator/reporter/terminal.rb

@@ -0,0 +1,50 @@
+module ActiveMutator
+  module Reporter
+    class Terminal
+      CHARS = { killed: ".", survived: "S", timeout: "T", error: "E", uncovered: "U", accepted: "A" }.freeze
+
+      def initialize(out: $stdout)
+        @out = out
+      end
+
+      def on_result(result)
+        @out.print(CHARS.fetch(result.status))
+      end
+
+      def summary(results, invalid_count:)
+        counts = results.group_by(&:status).transform_values(&:size)
+        @out.puts "", ""
+        CHARS.each_key do |status|
+          @out.puts "#{status}: #{counts.fetch(status, 0)}"
+        end
+        @out.puts "invalid (discarded): #{invalid_count}"
+        @out.puts format("Mutation score: %.1f%%", score(counts) * 100)
+        survivors = results.select { |r| r.status == :survived }
+        print_survivors(survivors) unless survivors.empty?
+      end
+
+      def self.score(counts)
+        detected = counts.fetch(:killed, 0) + counts.fetch(:timeout, 0)
+        denominator = detected + counts.fetch(:survived, 0)
+        return 1.0 if denominator.zero?
+
+        detected.to_f / denominator
+      end
+
+      private
+
+      def score(counts) = self.class.score(counts)
+
+      def print_survivors(survivors)
+        @out.puts "", "Surviving mutants:"
+        survivors.each do |result|
+          m = result.mutation
+          @out.puts "", "  #{m.subject.name} (#{m.subject.file}:#{m.line})"
+          @out.puts "    #{m.description}"
+          @out.puts "    - #{m.original_snippet}"
+          @out.puts "    + #{m.edit.replacement}"
+        end
+      end
+    end
+  end
+end

data/lib/active_mutator/result.rb

@@ -0,0 +1,6 @@
+module ActiveMutator
+  # status: :killed | :survived | :timeout | :error | :uncovered | :accepted
+  Result = Data.define(:mutation, :status, :details) do
+    def detected? = %i[killed timeout].include?(status)
+  end
+end

data/lib/active_mutator/runner.rb

@@ -0,0 +1,143 @@
+module ActiveMutator
+  class Runner
+    def initialize(config, reporter: nil)
+      @config = config
+      @reporter = reporter || build_reporter
+    end
+
+    def call
+      ENV["ACTIVE_MUTATOR"] = "1"
+      preload!
+      preload_spec_helper!
+      map = Baseline.new(root: @config.root).coverage_map(force: @config.force_baseline)
+      subjects = discover_subjects
+      analyses = subjects.map { |s| Engine.new.analyze(s) }
+      mutations = analyses.flat_map(&:mutations)
+      invalid_count = analyses.sum(&:invalid_count)
+
+      fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
+      ledger = AcceptedLedger.load(@config.root)
+      warn_stale(ledger, fingerprints.values)
+
+      items, pre_results = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
+      pre_results.each { |r| @reporter.on_result(r) }
+      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result))
+      results = scheduler.run(items) + pre_results
+
+      accept_survivors!(ledger, results, fingerprints) if @config.accept_survivors
+
+      @reporter.summary(results, invalid_count: invalid_count)
+      exit_code(results)
+    end
+
+    # Returns [work_items, pre_results]. Public for unit testing.
+    def plan_work(mutations, map, ledger: nil, fingerprints: {})
+      items = []
+      pre_results = []
+      mutations.each do |mutation|
+        if ledger&.accepted?(fingerprints[mutation])
+          pre_results << Result.new(mutation: mutation, status: :accepted, details: nil)
+          next
+        end
+        example_ids = map.examples_for(mutation.subject.file, mutation.lines)
+        if example_ids.empty?
+          pre_results << Result.new(mutation: mutation, status: :uncovered, details: nil)
+        else
+          lane = example_ids.any? { |id| serial_example?(id) } ? :serial : :parallel
+          timeout = map.time_for(example_ids) * @config.timeout_factor + @config.timeout_floor
+          timeout += @config.browser_boot_seconds if lane == :serial
+          items << WorkItem.new(mutation: mutation, example_ids: example_ids, timeout: timeout, lane: lane)
+        end
+      end
+      [items, pre_results]
+    end
+
+    def exit_code(results)
+      results.any? { |r| r.status == :survived } ? 1 : 0
+    end
+
+    private
+
+    def build_reporter
+      @config.format == :json ? Reporter::Json.new : Reporter::Terminal.new
+    end
+
+    def preload!
+      # Workers run the test suite, so the app must boot in the test
+      # environment (the development database may not even exist).
+      ENV["RAILS_ENV"] ||= "test"
+      @config.requires.each { |f| require File.expand_path(f, @config.root) }
+      environment = File.join(@config.root, "config", "environment.rb")
+      if @config.requires.empty? && File.exist?(environment)
+        require environment
+        Rails.application.eager_load! if defined?(Rails)
+      end
+    end
+
+    def discover_subjects
+      paths = @config.paths.empty? ? default_paths : @config.paths
+      subjects = paths
+        .flat_map { |p| Dir[File.join(@config.root, p, "**", "*.rb")] }
+        .sort.flat_map { |file| SubjectFinder.call(file) }
+      subjects = subjects.select { |s| s.name == @config.subject_filter } if @config.subject_filter
+      if @config.since
+        filter = SinceFilter.new(ref: @config.since, root: @config.root)
+        subjects = subjects.select { |s| filter.cover?(s) }
+      end
+      subjects
+    end
+
+    def default_paths
+      %w[app lib].select { |p| Dir.exist?(File.join(@config.root, p)) }
+    end
+
+    def serial_example?(example_id)
+      path = example_id.sub(%r{\A\./}, "")
+      @config.serial_patterns.any? { |pattern| path.start_with?(pattern) }
+    end
+
+    def preload_spec_helper!
+      return if @config.preload_helper == :none
+
+      helper = if @config.preload_helper
+                 File.expand_path(@config.preload_helper, @config.root)
+               else
+                 %w[spec/rails_helper.rb spec/spec_helper.rb]
+                   .map { |p| File.join(@config.root, p) }
+                   .find { |p| File.exist?(p) }
+               end
+      return unless helper && File.exist?(helper)
+
+      # Mirror what `bundle exec rspec` provides before a helper loads:
+      # rspec-core itself (helpers call RSpec.configure at the top level) and
+      # the default path (spec/) on $LOAD_PATH (rails_helper.rb relies on it
+      # for its bare `require "spec_helper"`).
+      require "rspec/core"
+      spec_dir = File.dirname(helper)
+      $LOAD_PATH.unshift(spec_dir) unless $LOAD_PATH.include?(spec_dir)
+      require helper
+      disarm_simplecov
+    end
+
+    # A preloaded helper commonly starts SimpleCov. Its at_exit would fire in
+    # THIS parent process at the end of the mutation run, clobbering the
+    # project's real coverage data — and minimum_coverage would exit(1) for a
+    # bogus reason. Neutralize it.
+    def disarm_simplecov
+      SimpleCov.at_exit {} if defined?(SimpleCov)
+    end
+
+    def accept_survivors!(ledger, results, fingerprints)
+      survivors = results.select { |r| r.status == :survived }.map { |r| fingerprints[r.mutation] }
+      return if survivors.empty?
+
+      ledger.accept!(survivors, fingerprints.values)
+    end
+
+    def warn_stale(ledger, all_fingerprints)
+      ledger.stale_entries(all_fingerprints).each do |entry|
+        warn "active_mutator: stale accepted fingerprint (no matching mutant): #{entry.subject} — #{entry.description}"
+      end
+    end
+  end
+end