active_mutator 0.1.0 → 0.2.0

data/lib/active_mutator/config_file.rb

@@ -0,0 +1,89 @@
+require "yaml"
+
+module ActiveMutator
+  # Project config file, layered UNDER CLI flags: CLI.parse seeds its option
+  # defaults from this before OptionParser runs, so any flag given on the
+  # command line wins. Strict on unknown keys and types — a typo silently
+  # ignored would be a config that silently doesn't apply.
+  class ConfigFile
+    FILENAME = ".active_mutator.yml"
+
+    FORMATS = %w[terminal json stryker-json github].freeze
+
+    KEYS = {
+      "jobs" => :integer,
+      "format" => :format,
+      "timeout_factor" => :number,
+      "timeout_floor" => :number,
+      "browser_boot_seconds" => :number,
+      "fail_at" => :score,
+      "exclude" => :string_list,
+      "serial_patterns" => :string_list,
+      "requires" => :string_list,
+      "operators" => :string_list,
+      "preload_helper" => :preload_helper,
+      "adaptive_timeout" => :boolean
+    }.freeze
+
+    # YAML keys that don't match their Config member name.
+    RENAMES = { "operators" => :operator_paths }.freeze
+
+    def self.load(root)
+      path = File.join(root, FILENAME)
+      return {} unless File.exist?(path)
+
+      data = parse(path)
+      return {} if data.nil?
+      raise Error, "#{FILENAME}: top level must be a mapping" unless data.is_a?(Hash)
+
+      data.to_h do |key, value|
+        validator = KEYS[key]
+        raise Error, "#{FILENAME}: unknown config key: #{key}" unless validator
+
+        [RENAMES.fetch(key, key.to_sym), coerce(key, validator, value)]
+      end
+    end
+
+    def self.parse(path)
+      YAML.safe_load_file(path, aliases: true)
+    rescue Psych::Exception => e
+      raise Error, "#{FILENAME}: #{e.message}"
+    end
+
+    def self.coerce(key, validator, value)
+      case validator
+      when :integer
+        raise Error, "#{FILENAME}: #{key} must be an integer" unless value.is_a?(Integer)
+        value
+      when :number
+        raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
+        value.to_f
+      when :score
+        raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
+        raise Error, "#{FILENAME}: #{key} must be within 0..100" unless (0..100).cover?(value)
+        value.to_f
+      when :format
+        unless FORMATS.include?(value)
+          raise Error, "#{FILENAME}: format must be one of #{FORMATS.join(", ")}"
+        end
+        value.tr("-", "_").to_sym
+      when :string_list
+        unless value.is_a?(Array) && value.all?(String)
+          raise Error, "#{FILENAME}: #{key} must be a list of strings"
+        end
+        value
+      when :boolean
+        unless [true, false].include?(value)
+          raise Error, "#{FILENAME}: #{key} must be true or false"
+        end
+        value
+      when :preload_helper
+        return :none if value == false
+        raise Error, "#{FILENAME}: preload_helper must be a path or false" unless value.is_a?(String)
+        value
+      else
+        raise Error, "unhandled validator #{validator}"
+      end
+    end
+  end
+end

data/lib/active_mutator/coverage_map.rb

@@ -3,7 +3,7 @@ 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
+  # 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)))

data/lib/active_mutator/defined_constants.rb

@@ -0,0 +1,48 @@
+require "prism"
+
+module ActiveMutator
+  # Deepest fully qualified names of classes/modules a source file defines
+  # ("Billing::Invoice"). Two shorthands are deliberately never emitted,
+  # because either would let a single common token match half of any real
+  # spec suite and trip BaselineDelta's full-run fallback on every edit:
+  #   - bare leaves ("Config" for MyApp::Config)
+  #   - pure namespace wrappers ("MyApp" for `module MyApp; class Config`):
+  #     every file in a namespaced app reopens the top module, and every
+  #     spec mentions it.
+  # A wrapper is a node whose non-empty direct body contains ONLY nested
+  # class/module definitions. A module with its own defs/macros/constants is
+  # a real edit target and IS emitted; so is an empty or def-less leaf class
+  # (macro-only ActiveRecord models).
+  #
+  # Guard is errors.any?, not warnings: Prism produces a complete AST for
+  # warnings-only input (`if a = 2`), and those definitions are real.
+  module DefinedConstants
+    def self.in_source(source)
+      result = Prism.parse(source)
+      return [] if result.errors.any?
+
+      names = []
+      walk(result.value, [], names)
+      names.uniq
+    end
+
+    # The walk intentionally descends into block bodies (unlike SubjectFinder,
+    # which skips them): over-inclusion is the safe direction for spec-file
+    # matching, so a constant defined inside a block is still emitted.
+    def self.walk(node, scope, names)
+      if node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+        scope = scope + [node.constant_path.slice]
+        names << scope.join("::") unless namespace_wrapper?(node)
+      end
+      node.compact_child_nodes.each { |child| walk(child, scope, names) }
+    end
+    private_class_method :walk
+
+    def self.namespace_wrapper?(node)
+      statements = node.body.is_a?(Prism::StatementsNode) ? node.body.body : []
+      statements.any? &&
+        statements.all? { |s| s.is_a?(Prism::ClassNode) || s.is_a?(Prism::ModuleNode) }
+    end
+    private_class_method :namespace_wrapper?
+  end
+end

data/lib/active_mutator/edit.rb

@@ -1,5 +1,11 @@
 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)
+  # in the original source with `replacement`. `operator` is the producing
+  # operator's demodulized class name ("CallSwap"), "Unknown" outside the
+  # operator pipeline.
+  Edit = Data.define(:range, :replacement, :description, :operator) do
+    def initialize(range:, replacement:, description:, operator: "Unknown")
+      super
+    end
+  end
 end

data/lib/active_mutator/engine.rb

@@ -35,14 +35,27 @@ module ActiveMutator
     def collect_edits(def_node)
       edits = []
       walk(def_node.body) do |node|
-        @operators.each { |op| edits.concat(op.edits(node)) }
+        @operators.each do |op|
+          edits.concat(op.edits(node))
+        rescue StandardError => e
+          # Fail loud but attributed: a buggy (likely third-party) operator
+          # should point at itself, not surface as a bare crash mid-analysis.
+          raise Error, "operator #{op.class.name} failed on #{node.class.name}: #{e.message}"
+        end
       end
       edits
     end
 
     def walk(node, &blk)
       return if node.nil?
-      return if node.is_a?(Prism::DefNode) # nested defs are separate subjects
+      # Descend into nested DefNodes rather than treating them as separate
+      # subjects. Giving a nested def its own subject identity is a trap:
+      # every call of the outer method re-executes the nested `def`, which
+      # would silently revert a directly-inserted mutant mid-run (phantom
+      # survivors). Instead we mutate the nested body as part of the outer
+      # def's re-evaled source. (SubjectFinder still emits no subject for
+      # nested defs.) walk is called as walk(def_node.body), so the outer
+      # DefNode itself never passes through here.
 
       yield node
       node.compact_child_nodes.each { |child| walk(child, &blk) }

data/lib/active_mutator/fingerprint.rb

@@ -1,7 +1,7 @@
 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,
+  # (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:)

data/lib/active_mutator/inserter.rb

@@ -1,13 +1,16 @@
 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.
+  # singleton method the same way. An sclass subject's source is a plain
+  # `def foo` that must land on the constant's singleton class, so we route it
+  # through `.singleton_class.class_eval`. 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)
+        target = Object.const_get(subject.constant_scope)
+        target = target.singleton_class if subject.sclass
+        target.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)

data/lib/active_mutator/operators/base.rb

@@ -18,7 +18,8 @@ module ActiveMutator
       def loc_range(loc) = loc.start_offset...loc.end_offset
 
       def edit(range, replacement, description)
-        Edit.new(range: range, replacement: replacement, description: description)
+        Edit.new(range: range, replacement: replacement, description: description,
+                 operator: self.class.name.split("::").last)
       end
     end
   end

data/lib/active_mutator/operators/call_swap.rb

@@ -9,6 +9,22 @@ module ActiveMutator
         min: "max", max: "min",
         first: "last", last: "first",
         any?: "none?", none?: "any?",
+        # all? is one-way: any? already pairs with none?, so all?→any? adds a
+        # distinct mutant without a redundant reverse edge.
+        all?: "any?",
+        take: "drop", drop: "take",
+        min_by: "max_by", max_by: "min_by",
+        # sort→reverse is one-way by design: reverse already has a strong
+        # forward mutant here, and reverse→sort would double-map `reverse`
+        # against nothing useful (reverse has no MAP entry to preserve).
+        sort: "reverse",
+        # detect/find→first is one-way: first ignores the retained block, so
+        # the mutant usually differs (equivalent only when element 0 already
+        # satisfies the predicate). No reverse edge: `first` is taken by
+        # first→last above.
+        detect: "first", find: "first",
+        # Evaluated and rejected: sum (initial-arg arity mismatch),
+        # find_index (no safe partner — rindex is Array-only).
         # Rails-aware pack:
         present?: "blank?", blank?: "present?",
         save: "save!", save!: "save"

data/lib/active_mutator/operators/literal.rb

@@ -23,8 +23,8 @@ module ActiveMutator
 
       def string_edits(node)
         opening = node.opening_loc&.slice
-        return [] unless opening                  # quote-less parts (interpolation)
-        return [] if opening.start_with?("<<")    # heredocs: v1 limit
+        return [] unless opening                # quote-less parts (interpolation)
+        return heredoc_edits(node) if opening.start_with?("<<")
 
         if node.unescaped.empty?
           [edit(loc_range(node.location), %("active_mutator"), %(replace "" with "active_mutator"))]
@@ -32,6 +32,18 @@ module ActiveMutator
           [edit(loc_range(node.location), %(""), %(replace string with ""))]
         end
       end
+
+      # The node span covers the `<<~X` opening token; splicing there breaks
+      # the source. Mutate the body content range instead: nonempty body →
+      # empty heredoc (opening line directly followed by the terminator).
+      # The guard is on the DEDENTED VALUE (unescaped), not content_loc: a
+      # squiggly body that dedents to "" would only lose whitespace bytes —
+      # an equivalent mutant — so it is skipped even though content is nonempty.
+      def heredoc_edits(node)
+        return [] if node.unescaped.empty?
+
+        [edit(loc_range(node.content_loc), "", "empty heredoc body")]
+      end
     end
   end
 end

data/lib/active_mutator/reporter/github.rb

@@ -0,0 +1,36 @@
+module ActiveMutator
+  module Reporter
+    # GitHub Actions workflow-command projection (issue #19): one ::warning
+    # annotation per surviving mutant, inlined on the PR diff. Everything
+    # else mirrors the terminal reporter so CI logs stay readable.
+    class Github
+      def initialize(root:, out: $stdout)
+        @root = root
+        @terminal = Terminal.new(out: out)
+        @out = out
+      end
+
+      def on_result(result) = @terminal.on_result(result)
+
+      def summary(results, invalid_count:)
+        @terminal.summary(results, invalid_count: invalid_count)
+        results.select { |r| r.status == :survived }.each { |r| annotate(r) }
+      end
+
+      private
+
+      def annotate(result)
+        m = result.mutation
+        file = m.subject.file.delete_prefix(@root.chomp("/") + "/")
+        message = "#{m.subject.name}: #{m.description} | - #{m.original_snippet} | + #{m.edit.replacement}"
+        @out.puts "::warning file=#{file},line=#{m.line},title=Surviving mutant::#{encode(message)}"
+      end
+
+      # GitHub workflow commands terminate at a raw newline; percent-encode
+      # per https://github.com/actions/toolkit runner rules.
+      def encode(message)
+        message.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+      end
+    end
+  end
+end

data/lib/active_mutator/reporter/json.rb

@@ -15,6 +15,7 @@ module ActiveMutator
           "score" => Terminal.score(counts),
           "counts" => counts.transform_keys(&:to_s),
           "invalid" => invalid_count,
+          "operators" => OperatorStats.call(results),
           "results" => results.map { |r| serialize(r) },
           "exit_reason" => counts.fetch(:survived, 0).positive? ? "unaccepted_survivors" : "clean"
         )

data/lib/active_mutator/reporter/operator_stats.rb

@@ -0,0 +1,20 @@
+module ActiveMutator
+  module Reporter
+    # Per-operator noise signal (issue #20): equivalent_rate =
+    # survived / (killed + survived). Every :survived result is covered by
+    # construction (uncovered mutants never reach the scheduler), so this is
+    # the covered-survivor rate. It deliberately conflates true equivalents
+    # with weak assertions — it is an aggregate signal, not a score.
+    module OperatorStats
+      def self.call(results)
+        results.group_by { |r| r.mutation.edit.operator }.to_h do |operator, group|
+          killed = group.count { |r| r.status == :killed }
+          survived = group.count { |r| r.status == :survived }
+          denominator = killed + survived
+          rate = denominator.zero? ? 0.0 : (survived.to_f / denominator).round(3)
+          [operator, { "killed" => killed, "survived" => survived, "equivalent_rate" => rate }]
+        end
+      end
+    end
+  end
+end

data/lib/active_mutator/reporter/stryker_json.rb

@@ -0,0 +1,117 @@
+require "json"
+
+module ActiveMutator
+  module Reporter
+    # mutation-testing-report-schema v2 (the Stryker ecosystem format).
+    # Load the written file in https://microsoft.github.io/mutation-testing-elements/
+    # for the interactive per-file mutant viewer.
+    #
+    # Schema constraints honored here: 1-based positive line/column, integer
+    # thresholds, tool-specific data only under config.active_mutator.
+    # Invalid mutants are discarded before results exist, so they appear as a
+    # count in the extras, never as CompileError mutants.
+    class StrykerJson
+      SCHEMA_URL = "https://git.io/mutation-testing-schema"
+      STATUS = { killed: "Killed", survived: "Survived", timeout: "Timeout",
+                 error: "RuntimeError", uncovered: "NoCoverage", accepted: "Ignored" }.freeze
+      ACCEPTED_REASON = "Accepted as equivalent in #{AcceptedLedger::FILENAME}".freeze
+      REPORT_PATH = File.join(".active_mutator", "mutation-report.json")
+
+      # Injected by Runner once the baseline map exists; nil in unit tests.
+      attr_writer :coverage_map
+
+      def initialize(root:, out: $stdout)
+        @root = root
+        @out = out
+        @coverage_map = nil
+      end
+
+      def on_result(result)
+        @out.print(Terminal::CHARS.fetch(result.status))
+      end
+
+      def summary(results, invalid_count:)
+        report = build_report(results, invalid_count)
+        path = File.join(@root, REPORT_PATH)
+        AtomicFile.write(path, JSON.pretty_generate(report))
+        @out.puts "", "", "Stryker report written to #{REPORT_PATH}"
+      end
+
+      private
+
+      def build_report(results, invalid_count)
+        mutants_by_file = results.group_by { |r| r.mutation.subject.file }
+        report = {
+          "$schema" => SCHEMA_URL,
+          "schemaVersion" => "2",
+          "thresholds" => { "high" => 80, "low" => 60 },
+          "projectRoot" => @root,
+          "config" => { "active_mutator" => { "invalid_discarded" => invalid_count,
+                                              "version" => VERSION } },
+          "files" => mutants_by_file.to_h { |file, rs| [relative(file), file_entry(file, rs)] }
+        }
+        tests = referenced_examples(results)
+        report["testFiles"] = test_files(tests) unless tests.empty?
+        report
+      end
+
+      def file_entry(file, results)
+        source = File.read(file)
+        { "language" => "ruby", "source" => source,
+          "mutants" => results.map { |r| mutant(r, source) } }
+      end
+
+      def mutant(result, source)
+        loc = SourceLocation.locate(source, result.mutation.edit.range)
+        entry = {
+          "id" => next_id,
+          "mutatorName" => result.mutation.edit.operator,
+          "location" => { "start" => stringify(loc[:start]), "end" => stringify(loc[:end]) },
+          "status" => STATUS.fetch(result.status),
+          "replacement" => result.mutation.edit.replacement,
+          "description" => result.mutation.description
+        }
+        reason = status_reason(result)
+        entry["statusReason"] = reason if reason
+        covered = covered_by(result)
+        entry["coveredBy"] = covered if covered
+        entry
+      end
+
+      def status_reason(result)
+        return ACCEPTED_REASON if result.status == :accepted
+
+        result.details&.to_s
+      end
+
+      def covered_by(result)
+        return nil unless @coverage_map
+
+        @coverage_map.examples_for(result.mutation.subject.file, result.mutation.lines)
+      end
+
+      def referenced_examples(results)
+        results.flat_map { |r| covered_by(r) || [] }.uniq.sort
+      end
+
+      # Group example ids by spec path (the id up to the trailing "[...]")
+      # so the viewer's test panel resolves coveredBy references.
+      def test_files(example_ids)
+        example_ids
+          .group_by { |id| id.sub(%r{\A\./}, "").sub(/\[.*\]\z/, "") }
+          .transform_values do |ids|
+            { "tests" => ids.map { |id| { "id" => id, "name" => id } } }
+          end
+      end
+
+      def next_id
+        @next_id = (@next_id || -1) + 1
+        @next_id.to_s
+      end
+
+      def stringify(position) = { "line" => position[:line], "column" => position[:column] }
+
+      def relative(file) = file.delete_prefix(@root.chomp("/") + "/")
+    end
+  end
+end

data/lib/active_mutator/reporter/terminal.rb

@@ -21,6 +21,9 @@ module ActiveMutator
         @out.puts format("Mutation score: %.1f%%", score(counts) * 100)
         survivors = results.select { |r| r.status == :survived }
         print_survivors(survivors) unless survivors.empty?
+        stats = OperatorStats.call(results)
+        noisy = stats.select { |_, s| s["survived"].positive? }
+        print_operator_stats(noisy) unless noisy.empty?
       end
 
       def self.score(counts)
@@ -35,6 +38,14 @@ module ActiveMutator
 
       def score(counts) = self.class.score(counts)
 
+      def print_operator_stats(stats)
+        @out.puts "", "Equivalent-rate by operator (survived / (killed + survived)):"
+        stats.sort_by { |_, s| -s["equivalent_rate"] }.each do |operator, s|
+          @out.puts format("  %-24s %5.1f%%  (%d survived / %d killed)",
+                           operator, s["equivalent_rate"] * 100, s["survived"], s["killed"])
+        end
+      end
+
       def print_survivors(survivors)
         @out.puts "", "Surviving mutants:"
         survivors.each do |result|