active_mutator 0.2.0 → 0.4.0

data/lib/active_mutator/runner.rb

@@ -10,9 +10,11 @@ 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)
+      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths)
+              .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) }
@@ -25,7 +27,7 @@ module ActiveMutator
       scanned_files = prune_scope(subjects)
       warn_stale(ledger, fingerprints.values, scanned_files)
 
-      items, pre_results = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
+      items, pre_results, phase1_ids = plan_work(mutations, map, ledger: ledger, fingerprints: fingerprints)
       return debug_plan(items, pre_results) if @config.debug_plan
 
       pre_results.each { |r| @reporter.on_result(r) }
@@ -35,6 +37,8 @@ module ActiveMutator
       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, scanned_files) if @config.accept_survivors
 
@@ -42,7 +46,9 @@ module ActiveMutator
       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 = []
@@ -51,19 +57,75 @@ module ActiveMutator
           pre_results << Result.new(mutation: mutation, status: :accepted, details: nil)
           next
         end
-        example_ids = map.examples_for(mutation.subject.file, coverage_lines(mutation))
+        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
-          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
-          items << WorkItem.new(mutation: mutation, example_ids: example_ids,
-                                timeout: timeout, lane: lane, variable: variable)
+          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 = BaselineDelta.spec_file_contents(root: @config.root, spec_paths: @config.spec_paths)
+      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)
@@ -78,12 +140,45 @@ module ActiveMutator
 
     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.operator_paths.each do |f|
+      @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}"
@@ -98,6 +193,25 @@ module ActiveMutator
       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?
+
+      convention_examples = convention_spec_rels(mutation.subject.file)
+                            .flat_map { |rel| map.examples_for_spec_file(rel) }
+      (map.examples_covering_file(mutation.subject.file) | convention_examples).sort
+    end
+
+    def convention_spec_rels(file)
+      rel = file.delete_prefix(@config.root.chomp("/") + "/").delete_suffix(".rb")
+      rest = rel.sub(%r{\A[^/]+/}, "")
+      @config.spec_paths.map { |sp| "#{sp}/#{rest}_spec.rb" }
+    end
+
     def build_reporter
       case @config.format
       when :json then Reporter::Json.new
@@ -126,6 +240,7 @@ module ActiveMutator
         .uniq
         .reject { |file| excluded?(file) }
         .sort.flat_map { |file| SubjectFinder.call(file) }
+      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) }
@@ -180,7 +295,11 @@ module ActiveMutator
       helper = if @config.preload_helper
                  File.expand_path(@config.preload_helper, @config.root)
                else
-                 %w[spec/rails_helper.rb spec/spec_helper.rb]
+                 # Precedence: within each spec path rails_helper wins over
+                 # spec_helper; earlier spec paths win over later ones — same
+                 # as today for the default ["spec"].
+                 @config.spec_paths
+                   .flat_map { |sp| ["#{sp}/rails_helper.rb", "#{sp}/spec_helper.rb"] }
                    .map { |p| File.join(@config.root, p) }
                    .find { |p| File.exist?(p) }
                end
@@ -210,8 +329,11 @@ module ActiveMutator
     # 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
+      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

data/lib/active_mutator/subject.rb

@@ -1,6 +1,8 @@
 module ActiveMutator
-  # A mutable unit: one method definition.
-  # byte_range/line_range cover the whole `def ... end`.
+  # 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
@@ -9,5 +11,7 @@ module ActiveMutator
     end
 
     def singleton? = kind == :singleton
+
+    def class_body? = kind == :class_body
   end
 end

data/lib/active_mutator/subject_finder.rb

@@ -11,16 +11,25 @@ module ActiveMutator
       skip_lines = result.comments
         .select { |c| c.slice.match?(SKIP_MARKER) }
         .to_set { |c| c.location.start_line }
-      finder = new(file, skip_lines: skip_lines)
+      finder = new(file, skip_lines: skip_lines,
+                   class_level: zeitwerk_shaped?(result.value))
       finder.visit(result.value)
       finder.subjects
     end
 
+    # Class-body subjects only for Zeitwerk-shaped files: exactly one
+    # top-level constant. Multi-constant files and core-class reopens have no
+    # safe remove_const + re-eval story (issue #32). Shared with ClosureReload.
+    def self.zeitwerk_shaped?(program)
+      ClassShape.single_top_level_constant?(program)
+    end
+
     attr_reader :subjects
 
-    def initialize(file, skip_lines: Set.new)
+    def initialize(file, skip_lines: Set.new, class_level: true)
       @file = file
       @skip_lines = skip_lines
+      @class_level = class_level
       @stack = []
       @subjects = []
       @sclass_depth = 0
@@ -33,13 +42,19 @@ module ActiveMutator
     def visit_class_node(node)
       return if @sclass_depth.positive?
 
-      with_scope(node.constant_path.slice) { super }
+      with_scope(node.constant_path.slice) do
+        add_class_body_subject(node)
+        super
+      end
     end
 
     def visit_module_node(node)
       return if @sclass_depth.positive?
 
-      with_scope(node.constant_path.slice) { super }
+      with_scope(node.constant_path.slice) do
+        add_class_body_subject(node)
+        super
+      end
     end
 
     # `class << self` inside a constant scope: defs there are singleton
@@ -85,6 +100,32 @@ module ActiveMutator
 
     private
 
+    # One subject for the class-level code of this class/module. Only if the
+    # body has at least one statement the class-body walk can mutate: defs
+    # and nested class/modules are owned by other subjects.
+    def add_class_body_subject(node)
+      return unless @class_level
+      return if @skip_lines.include?(node.location.start_line - 1)
+
+      body = node.body
+      return unless body.is_a?(Prism::StatementsNode)
+      return if body.body.all? { |s| owned_by_other_subject?(s) }
+
+      scope = @stack.join("::")
+      loc = node.location
+      @subjects << Subject.new(
+        name: "#{scope} (class body)",
+        file: @file,
+        byte_range: loc.start_offset...loc.end_offset,
+        line_range: loc.start_line..loc.end_line,
+        constant_scope: scope,
+        kind: :class_body,
+        sclass: false
+      )
+    end
+
+    def owned_by_other_subject?(node) = ClassShape.owned_by_other_subject?(node)
+
     def with_scope(name)
       @stack.push(name)
       yield

data/lib/active_mutator/version.rb

@@ -1,3 +1,3 @@
 module ActiveMutator
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/active_mutator/worker.rb

@@ -2,12 +2,32 @@ 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.
+  # Runs INSIDE a fork. Insertion order relative to RSpec's setup (which loads
+  # the spec files, and with them the app) DIFFERS by mutant kind:
+  #
+  #   Class-body: insert BEFORE setup. `RSpec.describe SomeClass` binds
+  #   `metadata[:described_class]` to the constant AT LOAD TIME, and a class-body
+  #   mutant reloads the constant to a NEW object via ClosureReload; a group
+  #   loaded first would keep the pre-mutation object and falsely survive. So we
+  #   require the subject file, reload, THEN let setup load the groups — every
+  #   group binds to the mutated object.
+  #
+  #   Def: insert AFTER setup. A def mutant class_evals the live method in
+  #   place, so it must be the LAST thing to touch that method. Inserting before
+  #   setup let a file loaded during spec-load (a concern/decorator/monkeypatch
+  #   that reopens the class but isn't transitively required by the subject
+  #   file) silently redefine the method back to the original, reporting a false
+  #   survivor. Loading everything first, then inserting, closes that window.
+  #   Requiring the subject after setup also means spec_helper's load-time setup
+  #   runs first, so a subject that depends on it still loads in non-preloaded
+  #   projects.
+  #
+  # The explicit `require` of the subject file guarantees the target constant
+  # exists before insertion regardless of preload: preloaded projects
+  # (Rails/Zeitwerk, or a preloaded spec helper) already have it in
+  # $LOADED_FEATURES so it's a no-op, while non-preloaded projects (plain
+  # gems whose spec files require the lib themselves, or --no-preload-helper)
+  # get it loaded rather than relying on spec-load to define it.
   class Worker
     def self.run(mutation, example_ids, writer)
       new(mutation, example_ids, writer).run
@@ -23,20 +43,42 @@ module ActiveMutator
       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
+      if @mutation.subject.class_body?
+        require @mutation.subject.file # no-op if already loaded; guarantees the constant exists
+        insert_mutation                # BEFORE setup: groups bind described_class to the mutated object
+        runner.setup(devnull, devnull) # loads spec files
+      else
+        runner.setup(devnull, devnull) # loads spec files -> the app, in dependency order
+        require @mutation.subject.file # no-op if already loaded; guarantees the constant exists
+        insert_mutation                # AFTER load: nothing left can redefine the method back
+      end
       # One failure kills the mutant; running the rest of the covering set
       # is pure waste inside the fork.
       RSpec.configuration.fail_fast = 1
-      Inserter.new.insert(@mutation)   # now the target constant exists
       after_fork_hygiene
       code = runner.run_specs(covering_groups)
       emit(code.zero? ? "survived" : "killed")
+    rescue ClosureReload::Skip => e
+      emit("skipped", details: e.message)
+    rescue ClosureReload::MutantLoadError => e
+      # The mutation made the class unloadable; a real suite would fail on it.
+      emit("killed", details: "mutated class failed to load: #{e.message}")
     rescue StandardError, ScriptError => e
       emit("error", details: "#{e.class}: #{e.message}")
     end
 
     private
 
+    # Def mutants class_eval over the live constant; class-body mutants
+    # cannot (macros accumulate) and go through whole-file closure reload.
+    def insert_mutation
+      if @mutation.subject.class_body?
+        ClosureReload.new(@mutation.subject, @mutation.mutated_file_source).call
+      else
+        Inserter.new.insert(@mutation)
+      end
+    end
+
     def after_fork_hygiene
       srand
       if defined?(ActiveRecord::Base)

data/lib/active_mutator.rb

@@ -10,6 +10,7 @@ end
 require_relative "active_mutator/edit"
 require_relative "active_mutator/splicer"
 require_relative "active_mutator/subject"
+require_relative "active_mutator/class_shape"
 require_relative "active_mutator/subject_finder"
 require_relative "active_mutator/subject_matcher"
 require_relative "active_mutator/operators/base"
@@ -30,6 +31,7 @@ require_relative "active_mutator/baseline"
 require_relative "active_mutator/baseline_delta"
 require_relative "active_mutator/defined_constants"
 require_relative "active_mutator/inserter"
+require_relative "active_mutator/closure_reload"
 require_relative "active_mutator/worker"
 require_relative "active_mutator/result"
 require_relative "active_mutator/work_item"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_mutator
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel John
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.30'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,18 +27,21 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.30'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !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
@@ -72,7 +78,9 @@ files:
 - lib/active_mutator/baseline.rb
 - lib/active_mutator/baseline_delta.rb
 - lib/active_mutator/baseline_hooks.rb
+- lib/active_mutator/class_shape.rb
 - lib/active_mutator/cli.rb
+- lib/active_mutator/closure_reload.rb
 - lib/active_mutator/config.rb
 - lib/active_mutator/config_file.rb
 - lib/active_mutator/coverage_map.rb
@@ -114,7 +122,6 @@ 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