active_mutator 0.1.1 → 0.3.0

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,128 @@
+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",
+                 skipped: "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
+
+        subject = result.mutation.subject
+        # Class-body lines execute at load time, so per-line coverage never
+        # attributes examples to them (see Runner#examples_for_mutation). Mirror
+        # the scheduling substitution — every example that loaded the file — so
+        # the viewer shows real test linkage instead of an empty coveredBy.
+        if subject.class_body?
+          examples = @coverage_map.examples_covering_file(subject.file)
+          return examples.empty? ? nil : examples.sort
+        end
+
+        @coverage_map.examples_for(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

@@ -1,7 +1,8 @@
 module ActiveMutator
   module Reporter
     class Terminal
-      CHARS = { killed: ".", survived: "S", timeout: "T", error: "E", uncovered: "U", accepted: "A" }.freeze
+      CHARS = { killed: ".", survived: "S", timeout: "T", error: "E", uncovered: "U", accepted: "A",
+                skipped: "-" }.freeze
 
       def initialize(out: $stdout)
         @out = out
@@ -21,6 +22,11 @@ module ActiveMutator
         @out.puts format("Mutation score: %.1f%%", score(counts) * 100)
         survivors = results.select { |r| r.status == :survived }
         print_survivors(survivors) unless survivors.empty?
+        skipped = results.select { |r| r.status == :skipped }
+        print_skipped(skipped) unless skipped.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 +41,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|
@@ -43,6 +57,15 @@ module ActiveMutator
           @out.puts "    #{m.description}"
           @out.puts "    - #{m.original_snippet}"
           @out.puts "    + #{m.edit.replacement}"
+          @out.puts "    (#{result.details})" if result.details
+        end
+      end
+
+      def print_skipped(skipped)
+        @out.puts "", "Skipped mutants (not counted in the score):"
+        skipped.each do |result|
+          m = result.mutation
+          @out.puts "  #{m.subject.name} (#{m.subject.file}:#{m.line}): #{result.details}"
         end
       end
     end

data/lib/active_mutator/result.rb

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

data/lib/active_mutator/runner.rb

@@ -1,3 +1,5 @@
+require "json"
+
 module ActiveMutator
   class Runner
     def initialize(config, reporter: nil)
@@ -7,30 +9,45 @@ module ActiveMutator
 
     def call
       ENV["ACTIVE_MUTATOR"] = "1"
+      load_operators
+      ClosureReload.cap = @config.class_level_closure_cap
       preload!
       preload_spec_helper!
       map = Baseline.new(root: @config.root).coverage_map(force: @config.force_baseline)
+      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
       subjects = discover_subjects
       analyses = subjects.map { |s| Engine.new.analyze(s) }
       mutations = analyses.flat_map(&:mutations)
+      mutations = mutations.first(@config.max_mutants) if @config.max_mutants
       invalid_count = analyses.sum(&:invalid_count)
 
       fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
       ledger = AcceptedLedger.load(@config.root)
-      warn_stale(ledger, fingerprints.values)
+      scanned_files = prune_scope(subjects)
+      warn_stale(ledger, fingerprints.values, scanned_files)
+
+      items, pre_results, phase1_ids = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
+      return debug_plan(items, pre_results) if @config.debug_plan
 
-      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))
+      calibrators = if @config.adaptive_timeout
+                      { parallel: TimeoutCalibrator.new, serial: TimeoutCalibrator.new }
+                    end
+      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result),
+                                calibrators: calibrators)
       results = scheduler.run(items) + pre_results
+      # Phase 2 runs on its own scheduler (built lazily inside), so pass nil.
+      results = escalate_class_body_survivors(results, nil, map, phase1_ids: phase1_ids)
 
-      accept_survivors!(ledger, results, fingerprints) if @config.accept_survivors
+      accept_survivors!(ledger, results, fingerprints, scanned_files) if @config.accept_survivors
 
       @reporter.summary(results, invalid_count: invalid_count)
       exit_code(results)
     end
 
-    # Returns [work_items, pre_results]. Public for unit testing.
+    # Returns [work_items, pre_results, phase1_ids]. phase1_ids maps each
+    # planned mutation to the example ids it was scheduled against, so phase 2
+    # escalation can subtract what was already run. Public for unit testing.
     def plan_work(mutations, map, ledger: nil, fingerprints: {})
       items = []
       pre_results = []
@@ -39,27 +56,167 @@ module ActiveMutator
           pre_results << Result.new(mutation: mutation, status: :accepted, details: nil)
           next
         end
-        example_ids = map.examples_for(mutation.subject.file, mutation.lines)
+        example_ids = examples_for_mutation(mutation, map)
         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)
+          items << build_work_item(mutation, example_ids, map)
+        end
+      end
+      phase1_ids = items.to_h { |i| [i.mutation, i.example_ids] }
+      [items, pre_results, phase1_ids]
+    end
+
+    # Phase 2 of the class-body kill pipeline (public for unit testing).
+    # A class-body survivor is only DECLARED after every spec file that
+    # references the constant has had its shot: re-enqueue against the
+    # referencing files phase 1 didn't run, and take the escalated verdict.
+    #
+    # `scheduler` is injectable for unit tests; in the normal run it is nil and
+    # a dedicated escalation scheduler is built lazily (only when there is
+    # phase-2 work) with NO on_result — escalation is a refinement pass, and
+    # reporting through the live callback would print a second status char for a
+    # mutant already streamed in phase 1. The final summary reflects the
+    # escalated verdicts regardless.
+    def escalate_class_body_survivors(results, scheduler, map, phase1_ids:)
+      candidates = results.select { |r| r.status == :survived && r.mutation.subject.class_body? }
+      # Perf gate: skip reading the whole spec suite into memory in the common
+      # case of no class-body survivors. (Deleting this line is a behavioral
+      # no-op — the later `items.empty?` return still guards correctness — so
+      # its mutant is a known equivalent.)
+      return results if candidates.empty?
+
+      spec_contents = Dir[File.join(@config.root, "spec/**/*_spec.rb")].to_h { |f| [f, File.read(f)] }
+      patterns = {} # subject file => constant-reference pattern (parsed once per file)
+      items = {}
+      candidates.each do |r|
+        file = r.mutation.subject.file
+        pattern = patterns.fetch(file) do
+          patterns[file] = BaselineDelta.constant_reference_pattern(File.read(file))
+        end
+        next unless pattern
+
+        ids = escalation_examples(map, spec_contents, phase1_ids.fetch(r.mutation, []), pattern)
+        next if ids.empty?
+
+        items[r.mutation] = build_work_item(r.mutation, ids, map)
+      end
+      return results if items.empty?
+
+      scheduler ||= Scheduler.new(jobs: @config.jobs)
+      escalated = scheduler.run(items.values).to_h { |res| [res.mutation, res] }
+      results.map do |r|
+        # A replacement only ever exists for a survived candidate (items is
+        # built solely from those), so no redundant status re-check is needed.
+        replacement = escalated[r.mutation]
+        next r unless replacement
+
+        case replacement.status
+        when :killed
+          replacement
+        when :survived
+          extra = items[r.mutation].example_ids.map { |id| BaselineDelta.spec_file_of(id) }.uniq.size
+          replacement.with(details: "escalated (+#{extra} spec files)")
+        else
+          # A timeout/error/skip in phase 2 did NOT prove a kill — the mutant
+          # already survived phase 1, so keep that verdict rather than letting
+          # an inconclusive escalation inflate the score (a :timeout counts as
+          # detected in exit_code/score).
+          r
         end
       end
-      [items, pre_results]
     end
 
     def exit_code(results)
-      results.any? { |r| r.status == :survived } ? 1 : 0
+      survived = results.count { |r| r.status == :survived }
+      return 0 if survived.zero?
+      return 1 unless @config.fail_at
+
+      detected = results.count { |r| %i[killed timeout].include?(r.status) }
+      score = detected * 100.0 / (detected + survived)
+      score >= @config.fail_at ? 0 : 1
     end
 
     private
 
+    # Single source of truth for lane/timeout/variable derivation, shared by
+    # phase-1 planning and phase-2 escalation so the two never drift.
+    def build_work_item(mutation, example_ids, map)
+      lane = example_ids.any? { |id| serial_example?(id) } ? :serial : :parallel
+      variable = map.time_for(example_ids) * @config.timeout_factor
+      boot_extra = lane == :serial ? @config.browser_boot_seconds : 0.0
+      timeout = variable + @config.timeout_floor + boot_extra
+      WorkItem.new(mutation: mutation, example_ids: example_ids,
+                   timeout: timeout, lane: lane, variable: variable)
+    end
+
+    # Spec files that textually match `pattern` (a constant-reference pattern
+    # for the subject's file, built via BaselineDelta.constant_reference_pattern
+    # so the escaping/word-boundary rules stay shared), minus everything phase 1
+    # already ran; returned as example ids.
+    #
+    # Two deliberate choices: (a) matching is TEXTUAL, so a constant named in a
+    # comment or string still counts — intentional, since the worst case is a
+    # wasted run and the verdict stays correct; (b) unlike
+    # BaselineDelta.newly_covering_candidates there is intentionally NO fan-out
+    # ceiling here — a class-body survivor gets every referencing spec its shot
+    # before being declared.
+    def escalation_examples(map, spec_contents, phase1_example_ids, pattern)
+      phase1_files = phase1_example_ids.map { |id| BaselineDelta.spec_file_of(id) }.uniq
+      spec_contents.filter_map do |abs, content|
+        rel = abs.delete_prefix(@config.root.chomp("/") + "/")
+        next if phase1_files.include?(rel)
+        next unless content.match?(pattern)
+
+        map.examples_for_spec_file(rel)
+      end.flatten.uniq.sort
+    end
+
+    # Custom operators must exist in the PARENT before Engine analysis:
+    # subclassing Operators::Base self-registers, and forks inherit the
+    # loaded class. `requires` can't serve — those load inside the fork's
+    # setup, after mutations are already planned.
+    def load_operators
+      @config.operators.each do |f|
+        require File.expand_path(f, @config.root)
+      rescue LoadError, SyntaxError => e
+        raise Error, "operator file not loadable: #{f}: #{e.message}"
+      end
+    end
+
+    # Line coverage attributes multi-line expressions to their statement anchor
+    # line (version-dependently), so a sub-expression mutant's own lines may
+    # carry no coverage at all. Look up the whole subject instead: a mutant must
+    # run against every example covering any line of its method.
+    def coverage_lines(mutation)
+      mutation.lines.to_a | mutation.subject.line_range.to_a
+    end
+
+    # Class-body lines execute at load time, so line coverage never
+    # attributes examples to them. Substitute: every example that covers ANY
+    # line of the file (it must have loaded the class), plus the convention
+    # spec file's examples. Phase 2 (escalation) widens further before a
+    # survivor is declared.
+    def examples_for_mutation(mutation, map)
+      return map.examples_for(mutation.subject.file, coverage_lines(mutation)) unless mutation.subject.class_body?
+
+      (map.examples_covering_file(mutation.subject.file) |
+        map.examples_for_spec_file(convention_spec_rel(mutation.subject.file))).sort
+    end
+
+    def convention_spec_rel(file)
+      rel = file.delete_prefix(@config.root.chomp("/") + "/").delete_suffix(".rb")
+      rest = rel.sub(%r{\A[^/]+/}, "")
+      "spec/#{rest}_spec.rb"
+    end
+
     def build_reporter
-      @config.format == :json ? Reporter::Json.new : Reporter::Terminal.new
+      case @config.format
+      when :json then Reporter::Json.new
+      when :stryker_json then Reporter::StrykerJson.new(root: @config.root)
+      when :github then Reporter::Github.new(root: @config.root)
+      else Reporter::Terminal.new
+      end
     end
 
     def preload!
@@ -77,9 +234,15 @@ module ActiveMutator
     def discover_subjects
       paths = @config.paths.empty? ? default_paths : @config.paths
       subjects = paths
-        .flat_map { |p| Dir[File.join(@config.root, p, "**", "*.rb")] }
+        .flat_map { |p| expand_path_arg(p) }
+        .uniq
+        .reject { |file| excluded?(file) }
         .sort.flat_map { |file| SubjectFinder.call(file) }
-      subjects = subjects.select { |s| s.name == @config.subject_filter } if @config.subject_filter
+      subjects = subjects.reject(&:class_body?) unless @config.class_level
+      if @config.subject_filter
+        matcher = SubjectMatcher.new(@config.subject_filter)
+        subjects = subjects.select { |s| matcher.match?(s.name) }
+      end
       if @config.since
         filter = SinceFilter.new(ref: @config.since, root: @config.root)
         subjects = subjects.select { |s| filter.cover?(s) }
@@ -87,6 +250,34 @@ module ActiveMutator
       subjects
     end
 
+    # Positional args may be files or directories. Anything else is an error:
+    # a mistyped path that silently matched nothing produced a false green
+    # (0 subjects, exit 0) — see #23.
+    def expand_path_arg(path)
+      full = File.expand_path(path, @config.root)
+      if File.file?(full)
+        raise Error, "not a Ruby file: #{path}" unless full.end_with?(".rb")
+
+        [full]
+      elsif Dir.exist?(full)
+        Dir[File.join(full, "**", "*.rb")]
+      else
+        raise Error, "no such file or directory: #{path}"
+      end
+    end
+
+    def excluded?(file)
+      flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+      relative = file.delete_prefix(@config.root.chomp("/") + "/")
+      @config.exclude.any? do |pattern|
+        # Gitignore-like ergonomics: "lib/gen", "lib/gen/" and "lib/gen/**"
+        # all exclude the whole subtree, not just direct children.
+        dir = pattern.sub(%r{(/\*\*)?/?\z}, "")
+        File.fnmatch?(pattern, relative, flags) ||
+          File.fnmatch?("#{dir}/**/*", relative, flags)
+      end
+    end
+
     def default_paths
       %w[app lib].select { |p| Dir.exist?(File.join(@config.root, p)) }
     end
@@ -127,17 +318,46 @@ module ActiveMutator
       SimpleCov.at_exit {} if defined?(SimpleCov)
     end
 
-    def accept_survivors!(ledger, results, fingerprints)
+    # Only a run with no subject-level narrowing has fully scanned a file;
+    # anything narrower must not prune (or warn about) out-of-scope entries.
+    # MAINTENANCE: any future flag that narrows the mutant set below "every
+    # subject in the scanned files" MUST be added to this nil-trigger list,
+    # or scoped accept runs will clobber out-of-scope ledger entries (#24).
+    # --no-class-level drops every class_body subject (discover_subjects), so a
+    # file's class-body fingerprint is absent even though the file is scanned;
+    # without this guard its accepted ledger entry looks stale and gets pruned.
+    def prune_scope(subjects)
+      return nil if @config.subject_filter || @config.since || @config.max_mutants || !@config.class_level
+
+      subjects.map { |s| s.file.delete_prefix("#{@config.root}/") }.uniq
+    end
+
+    def accept_survivors!(ledger, results, fingerprints, scanned_files)
       survivors = results.select { |r| r.status == :survived }.map { |r| fingerprints[r.mutation] }
       return if survivors.empty?
 
-      ledger.accept!(survivors, fingerprints.values)
+      ledger.accept!(survivors, fingerprints.values, scanned_files: scanned_files)
     end
 
-    def warn_stale(ledger, all_fingerprints)
-      ledger.stale_entries(all_fingerprints).each do |entry|
+    def debug_plan(items, pre_results)
+      plan = items.map do |i|
+        { "subject" => i.mutation.subject.name, "description" => i.mutation.description,
+          "file" => i.mutation.subject.file, "line" => i.mutation.line,
+          "lane" => i.lane.to_s, "timeout" => i.timeout.round(2),
+          "examples" => i.example_ids.size }
+      end
+      skipped = pre_results.group_by { |r| r.status.to_s }.transform_values(&:size)
+      puts JSON.pretty_generate("planned" => plan, "pre_resolved" => skipped)
+      0
+    end
+
+    def warn_stale(ledger, all_fingerprints, scanned_files)
+      ledger.stale_entries(all_fingerprints, scanned_files: scanned_files).each do |entry|
         warn "active_mutator: stale accepted fingerprint (no matching mutant): #{entry.subject}, #{entry.description}"
       end
+      ledger.missing_file_entries(@config.root).each do |entry|
+        warn "active_mutator: accepted fingerprint references missing file: #{entry.file} (#{entry.subject})"
+      end
     end
   end
 end

data/lib/active_mutator/scheduler.rb

@@ -8,11 +8,13 @@ module ActiveMutator
     OrphanedError = Class.new(Error)
 
     def initialize(jobs:, worker: Worker.method(:run), on_result: nil,
-                   orphaned: -> { Process.ppid == 1 })
+                   calibrators: nil, orphaned: -> { Process.ppid == 1 })
       @jobs = jobs
       @worker = worker
       @on_result = on_result
+      @calibrators = calibrators
       @orphaned = orphaned
+      @last_logged_scale = {} # lane => last scale logged for that lane
     end
 
     def run(items)
@@ -72,7 +74,12 @@ module ActiveMutator
         Process.exit!(0)
       end
       writer.close
-      running[pid] = { reader: reader, item: item, deadline: now + item.timeout }
+      calibrator = calibrator_for(item)
+      budget = calibrator ? calibrator.budget_for(item) : item.timeout
+      log_scale(calibrator, item.lane)
+      started = now
+      running[pid] = { reader: reader, item: item, started: started,
+                       budget: budget, deadline: started + budget }
     end
 
     def reap(running, results)
@@ -80,7 +87,11 @@ module ActiveMutator
         done, _status = Process.waitpid2(pid, Process::WNOHANG)
         if done
           running.delete(pid)
-          results << finish(entry)
+          result = finish(entry)
+          if result.status == :killed
+            calibrator_for(entry[:item])&.record(now - entry[:started], entry[:budget])
+          end
+          results << result
         elsif now > entry[:deadline]
           kill(pid)
           running.delete(pid)
@@ -94,8 +105,16 @@ module ActiveMutator
       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"
+      # A self-mutation of Worker#emit can produce well-formed JSON without a
+      # "status" key (or with a non-Hash root); treat any unusable payload as
+      # a worker error instead of crashing the whole run.
+      reported = data.is_a?(Hash) && data.key?("status")
+      status = reported ? data["status"].to_sym : :error
+      details = reported ? data["details"] : "worker exited without reporting"
+    rescue JSON::ParserError
+      report(Result.new(mutation: entry[:item].mutation, status: :error,
+                        details: "worker emitted unparseable payload"))
+    else
       report(Result.new(mutation: entry[:item].mutation, status: status, details: details))
     end
 
@@ -141,6 +160,23 @@ module ActiveMutator
       previous.each { |sig, handler| trap(sig, handler || "DEFAULT") }
     end
 
+    def calibrator_for(item)
+      @calibrators && @calibrators[item.lane]
+    end
+
+    # Effective budgets are otherwise invisible (--debug-plan shows static
+    # ones by design). One stderr line per scale CHANGE per lane, not per
+    # spawn — the two lanes calibrate independently, so the lane is named.
+    def log_scale(calibrator, lane)
+      return unless calibrator&.warmed?
+
+      scale = calibrator.scale.round(2)
+      return if scale == @last_logged_scale[lane]
+
+      @last_logged_scale[lane] = scale
+      warn "active_mutator: adaptive timeout scale (#{lane}): #{scale}"
+    end
+
     def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 end

data/lib/active_mutator/source_location.rb

@@ -0,0 +1,21 @@
+module ActiveMutator
+  # 1-based line/column (never 0 — the Stryker schema rejects 0) for an
+  # exclusive byte range within a source string.
+  module SourceLocation
+    def self.locate(source, byte_range)
+      {
+        start: position(source, byte_range.begin),
+        end: position(source, byte_range.end)
+      }
+    end
+
+    def self.position(source, offset)
+      prefix = source.byteslice(0, offset)
+      last_newline = prefix.rindex("\n")
+      {
+        line: prefix.count("\n") + 1,
+        column: offset - (last_newline ? last_newline + 1 : 0) + 1
+      }
+    end
+  end
+end

data/lib/active_mutator/subject.rb

@@ -1,7 +1,17 @@
 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
+  # A mutable unit. kind :instance/:singleton = one method definition
+  # (byte_range/line_range cover the whole `def ... end`). kind :class_body =
+  # the class-level code of one class/module (byte_range covers the whole
+  # class/module node; Engine only mutates non-def body statements).
+  # sclass: def lives inside `class << self` — its source slice is `def foo`,
+  # so Inserter must target the singleton class, not the constant itself.
+  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind, :sclass) do
+    def initialize(name:, file:, byte_range:, line_range:, constant_scope:, kind:, sclass: false)
+      super
+    end
+
     def singleton? = kind == :singleton
+
+    def class_body? = kind == :class_body
   end
 end