active_mutator 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5729b9385c24e575708a5227a3838ae28e09dd2ddf3e40e1883e9e74f7399275
-  data.tar.gz: 69b41b3304c8c008f54f6c20547ff9283d26a278eea706dc7cf923466dde1b5c
+  metadata.gz: '08222e2342f45fd4c9150cd9201383231f1add08c5c5582bccf74f4350c87181'
+  data.tar.gz: ae88865c407500e7b7fcc0cb9a0ab72fe90aa2860136f9bd523203a1baae9c35
 SHA512:
-  metadata.gz: 3e0dce87a35314cb96e68e7051e3dfa8bbc329b58a3c41beef1201c7c5e8a3205d58a28593bf99382dfd1f9a9fd52859b44def8e2ee5d57dd0879e9dfcadec37
-  data.tar.gz: 5ec63925341ef8356801ee171e83af5b6323feb0f15838b1430421c9e5aaf73017d0e5ebaafb653039917a97144933e3572c2d182ba0544de27fbe60a0d7d6ca
+  metadata.gz: c0ed008b82b47bf0e70e74bd51330eafaeb02f6c7241e5a19e2a75395293db1ccf02e3f13f3810abf2da1972f5b50b678e35bae4efb946b139aac22e0faccfd0
+  data.tar.gz: dd02830ae6b56cdc687cf90dc5131d1409298ac8e5d03217a57f92a044aca4dee6731043498e1f021d9eee4ef064af8cab80fb048263046dfe28fe719bef0077

data/README.md

@@ -263,6 +263,7 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
 | `--[no-]adaptive-timeout` | on | scale timeout budgets from observed worker wall times (median utilization, grow-only, clamped 1x–4x; `--timeout-factor`/`--timeout-floor` set the starting budget) |
 | `--require FILE` | none | preload files (repeatable) |
 | `--operator FILE` | none | load a custom operator file before analysis (repeatable) |
+| `--[no-]class-level` | on | mutate class-level code (macros, constants, DSL/scope lambdas) via class-body subjects |
 | `--fail-at SCORE` | none (strict) | exit 0 if score >= SCORE even with survivors (opt-in relaxation for gradual adoption; 0 = report-only) |
 
 `--debug-plan` prints the planned mutant list as one JSON document
@@ -287,7 +288,10 @@ lists; the first `--serial-pattern` replaces them). Recognized keys:
 `requires`, `operators` (custom operator files, loaded before analysis; see
 [Custom operators](docs/guides/custom-operators.md)),
 `preload_helper` (a path, or `false` to skip preload),
-`adaptive_timeout` (`true`/`false`).
+`adaptive_timeout` (`true`/`false`),
+`class_level` (`true`/`false`, default `true` — mutate class-level code),
+`class_level_closure_cap` (integer, default `10` — max constants a
+class-body mutant may reload before it is `skipped`).
 Unknown keys and wrong types are errors, not silent no-ops.
 
 ```yaml
@@ -300,19 +304,66 @@ serial_patterns:
 fail_at: 90   # legacy suite: gate on score instead of zero-survivors
 ```
 
-## Known limits (v1.1)
-
-Method bodies only (no class-macro/constant mutation). RSpec only.
-Plain heredoc bodies ARE mutated (emptied); interpolated heredocs are
-skipped. `class << self` bodies are mutated as singleton subjects
-(`class << obj` and top-level `class << self` are skipped). Nested defs
-mutate as part of the enclosing method's body — they get no subject of
-their own (a directly-inserted mutant would be reverted whenever the
-outer method re-runs the `def`). The incremental baseline recovers the residual blind spot —
-constant-reference detection handles the common case since 0.2, and a few
-residual cases (pure indirection, partially-covering files, leaf-only or
-wrapper-only references, `class ::Foo`, `Data.define`/`Struct.new` value
-objects) are caught by nightly `--force-baseline`.
+## Class-level mutation
+
+Class-level code — macros (`validates`, `scope`, `has_many`), constants,
+and DSL/scope lambdas — IS mutated. Each Zeitwerk-shaped file gets a
+`… (class body)` subject alongside its method subjects, and the same
+operator set runs over its class-level statements. Because re-running a
+macro *accumulates* rather than replaces (calling `validates` twice adds a
+second validator), a class-body mutant can't be inserted with `class_eval`
+the way a `def` mutant is. Instead active_mutator removes the target
+constant and re-evaluates the whole mutated file, reloading anything
+attached to it (includers, subclasses, extenders) in dependency order. See
+[`docs/guides/how-it-works.md`](docs/guides/how-it-works.md) for the full
+closure-reload pipeline.
+
+Disable it with `--no-class-level` (or `class_level: false` in the config
+file). A class-body mutant whose closure can't be reloaded faithfully — the
+closure exceeds `class_level_closure_cap` (default `10`), the constant was
+reopened elsewhere, or an attacher is anonymous/native — is reported
+`skipped` (progress char `-`): listed but **not counted in the score**,
+because a mutant we can't insert faithfully must not be called survived or
+killed.
+
+## Known limits
+
+Method bodies **and** Zeitwerk-shaped class bodies are mutated; the
+remaining limits are:
+
+- **Class-body mutation requires a Zeitwerk-shaped file** — exactly one
+  top-level class/module per file. Multi-constant files and core-class
+  monkey-patches/reopens are not class-body-mutated (issue #32). Their
+  method bodies still are.
+- **Most code inside blocks is not mutated.** `ActiveSupport::Concern` DSL
+  blocks (`included`/`prepended`/`class_methods do … end`) ARE mutated — their
+  bodies re-run as class-level code in the includer (issue #31). Every other
+  block (`has_many :x do … end` and any `do … end`/`{ … }` body) is pruned to
+  avoid false survivors from mutating code whose run-time context is unknown.
+- **Constants captured by value go stale.** A reference that holds the
+  target *by value* rather than by ancestry — an alias (`ALIAS = SomeClass`),
+  a registry the class was pushed into, a memoized instance, a class
+  variable captured at load — keeps pointing at the pre-reload object after
+  the closure reload. Such stale references can produce false survivors.
+- **Whole-file re-eval re-runs class-body side effects.** The reload
+  re-evaluates the target and every attacher's class body, so non-idempotent
+  load-time side effects (global self-registration, descendant tracking) run
+  twice — which can double or mask a count a spec asserts on.
+- **`refine`-based modules are not discovered or reloaded.** Refinements
+  are anonymous and don't appear in normal `ancestors`.
+- **RSpec only.** Test selection, worker setup, and the world-group filter
+  are all RSpec-API-shaped.
+- **Method-body scope details:** plain heredoc bodies ARE mutated (emptied);
+  interpolated heredocs are skipped. `class << self` bodies are mutated as
+  singleton subjects (`class << obj` and top-level `class << self` are
+  skipped). Nested defs mutate as part of the enclosing method's body — they
+  get no subject of their own (a directly-inserted mutant would be reverted
+  whenever the outer method re-runs the `def`).
+- **The incremental baseline's residual blind spot:** constant-reference
+  detection handles the common case since 0.2; a few residual cases (pure
+  indirection, partially-covering files, leaf-only or wrapper-only
+  references, `class ::Foo`, `Data.define`/`Struct.new` value objects) are
+  caught by nightly `--force-baseline`.
 
 ## Guides
 

data/lib/active_mutator/baseline_delta.rb

@@ -84,21 +84,13 @@ module ActiveMutator
       abs = File.join(root, rel)
       return [] unless File.exist?(abs)
 
-      constants = DefinedConstants.in_source(File.read(abs))
-      return [] if constants.empty?
+      pattern = constant_reference_pattern(File.read(abs))
+      return [] unless pattern
 
       all_specs = spec_contents.keys
 
       covering_specs = coverage_map.examples_covering_file(abs)
                                    .map { |id| spec_file_of(id) }.to_a.uniq
-      # Escaping is required: dynamic-namespace class definitions (e.g.
-      # `class (a)::Baz`, `class foo.bar::Baz`) make constant_path.slice carry
-      # regex metachars. Unescaped, "(a)::Baz" would match the literal text
-      # "a::Baz" — a false candidate.
-      # TODO(#11, Task 10 residual gap): a top-level `class ::Foo` yields the
-      # slice "::Foo", and /\b::Foo\b/ can never match (no word boundary
-      # before ":"), so such files are silently unscanned.
-      pattern = /\b(?:#{constants.map { |c| Regexp.escape(c) }.join("|")})\b/
       candidates = all_specs.filter_map do |spec_abs|
         spec_rel = spec_abs.delete_prefix(root).delete_prefix("/")
         next if covering_specs.include?(spec_rel)
@@ -119,5 +111,24 @@ module ActiveMutator
     def self.spec_file_of(example_id)
       example_id.sub(%r{\A\./}, "").sub(/\[.*\]\z/, "")
     end
+
+    # Regexp matching any textual reference to a constant DEFINED in `source`,
+    # or nil when the source defines none. Shared by newly_covering_candidates
+    # and Runner's phase-2 escalation so the escaping/word-boundary rules live
+    # in one place.
+    #
+    # Escaping is required: dynamic-namespace class definitions (e.g.
+    # `class (a)::Baz`, `class foo.bar::Baz`) make constant_path.slice carry
+    # regex metachars. Unescaped, "(a)::Baz" would match the literal text
+    # "a::Baz" — a false candidate.
+    # TODO(#11, Task 10 residual gap): a top-level `class ::Foo` yields the
+    # slice "::Foo", and /\b::Foo\b/ can never match (no word boundary before
+    # ":"), so such files are silently unscanned.
+    def self.constant_reference_pattern(source)
+      constants = DefinedConstants.in_source(source)
+      return nil if constants.empty?
+
+      /\b(?:#{constants.map { |c| Regexp.escape(c) }.join("|")})\b/
+    end
   end
 end

data/lib/active_mutator/class_shape.rb

@@ -0,0 +1,47 @@
+module ActiveMutator
+  # Structural predicates over a parsed file that the class-level machinery
+  # must apply IDENTICALLY in more than one place. Centralized so the gates
+  # cannot drift:
+  #   - SubjectFinder decides which files get a class-body subject.
+  #   - ClosureReload decides which dependent files are safe to remove_const
+  #     and re-eval.
+  # Both need the same "is this file a single reloadable constant?" rule, and
+  # both need the same "does this class-body statement belong to another
+  # subject?" rule.
+  # `extend self`, not `module_function`: module_function copies each method
+  # onto the singleton at definition time, so a def-level mutant (which
+  # redefines the INSTANCE method in the fork) would never reach the singleton
+  # copy that callers invoke — an untestable false survivor. `extend self`
+  # keeps ONE method object, dispatched to via the singleton's ancestry.
+  module ClassShape
+    extend self
+
+    # Zeitwerk-shaped: the file defines exactly one top-level constant, so
+    # remove_const + whole-file re-eval reinstates precisely that constant
+    # (issue #32). A file with more than one would re-run macros on / reassign
+    # the constants that were NOT removed (accumulation and "already
+    # initialized constant" bugs).
+    #
+    # Counts every top-level constant-DEFINING form, not just `class`/`module`
+    # blocks: `Adapter = Class.new`, `Point = Struct.new(...)`,
+    # `Config = Data.define(...)`, and plain `CONST = ...` are ConstantWriteNodes
+    # (or ConstantPathWriteNodes) that a class/module-only count missed, letting
+    # a two-constant file slip through and get reassigned on re-eval.
+    def single_top_level_constant?(program)
+      program.statements.body.count { |s| defines_constant?(s) } == 1
+    end
+
+    def defines_constant?(node)
+      node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode) ||
+        node.is_a?(Prism::ConstantWriteNode) || node.is_a?(Prism::ConstantPathWriteNode)
+    end
+
+    # A class-body statement that is owned by a DIFFERENT subject — its own
+    # def, or a nested class/module/singleton-class that gets its own subjects.
+    # The class-body walk must neither collect edits for it nor delete it.
+    def owned_by_other_subject?(node)
+      node.is_a?(Prism::DefNode) || node.is_a?(Prism::ClassNode) ||
+        node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
+    end
+  end
+end

data/lib/active_mutator/cli.rb

@@ -24,7 +24,7 @@ module ActiveMutator
         preload_helper: nil, serial_patterns: ["spec/system/", "spec/features/"],
         browser_boot_seconds: 15.0, accept_survivors: false, exclude: [],
         max_mutants: nil, debug_plan: false, fail_at: nil, adaptive_timeout: true,
-        operator_paths: []
+        operators: [], class_level: true, class_level_closure_cap: 10
       }
       options.merge!(ConfigFile.load(Dir.pwd))
       paths = OptionParser.new do |o|
@@ -35,7 +35,8 @@ module ActiveMutator
         o.on("--jobs N", Integer, "Concurrent workers (default: half the CPU count)") { |v| options[:jobs] = v }
         o.on("--format FMT", ConfigFile::FORMATS, "Output format") { |v| options[:format] = v.tr("-", "_").to_sym }
         o.on("--require FILE", "File to require before mutating (repeatable; adds to config-file requires)") { |v| options[:requires] << v }
-        o.on("--operator FILE", "Ruby file defining a custom operator, loaded before analysis (repeatable)") { |v| options[:operator_paths] << v }
+        o.on("--operator FILE", "Ruby file defining a custom operator, loaded before analysis (repeatable)") { |v| options[:operators] << v }
+        o.on("--[no-]class-level", "Mutate class-level code: macros, constants, DSL lambdas (default: on)") { |v| options[:class_level] = v }
         o.on("--force-baseline", "Ignore cached coverage map") { options[:force_baseline] = true }
         o.on("--timeout-factor F", Float, "Timeout = baseline time * F + floor") { |v| options[:timeout_factor] = v }
         o.on("--timeout-floor S", Float, "Minimum timeout seconds") { |v| options[:timeout_floor] = v }

data/lib/active_mutator/closure_reload.rb

@@ -0,0 +1,202 @@
+module ActiveMutator
+  # Fork-side insertion for class-body mutants. A def mutant can be
+  # class_eval'd over the live constant; class-level code cannot (re-running
+  # `validates` ADDS a validator, it doesn't replace one). So: remove the
+  # constant and re-eval the whole mutated file. Anything already attached to
+  # the OLD object — classes that include the module, subclasses, extend
+  # sites — would go stale, so they are removed and re-evaled too (pristine
+  # sources), dependency-first. The fork dies after the run; nothing is
+  # restored.
+  #
+  # Every guard failure raises Skip; the Worker reports the mutant as
+  # `skipped` with the reason. Skipping is honest: a mutant we cannot insert
+  # faithfully must not be counted as survived OR killed.
+  #
+  # Known limitations (inherent to remove-and-reload; accepted trade-offs):
+  #   - References that hold the target BY VALUE rather than by ancestry are
+  #     not discovered and keep pointing at the pre-remove_const object:
+  #     aliases (`ALIAS = MyClass`), arrays/registries the target was pushed
+  #     into, memoized instances, class variables captured at load time.
+  #   - `refine`-based modules are anonymous and do not appear in normal
+  #     `ancestors`, so refinements of the target are not discovered/reloaded.
+  #   - Re-evaling the target AND each attacher re-runs their class-body side
+  #     effects. Non-idempotent load-time effects (self-registration into a
+  #     global registry, DescendantsTracker-style hooks) therefore run twice; a
+  #     spec asserting such a count can see it doubled (false kill) or masked
+  #     (false survival).
+  #   - The re-eval order pins the target first (every attacher depends on it)
+  #     then sorts the rest by instance-ancestor depth. An `extend`
+  #     relationship BETWEEN two non-target attachers can still re-eval out of
+  #     order (rare); a full topological sort is deliberately not attempted.
+  class ClosureReload
+    Skip = Class.new(StandardError)
+
+    # The MUTATED target source could not be re-evaled — the mutation broke the
+    # class so it no longer loads. Every covering spec loads the class, so the
+    # suite would fail: the Worker maps this to a kill, not an error.
+    MutantLoadError = Class.new(StandardError)
+
+    DEFAULT_CAP = 10
+
+    class << self
+      # Assigned by Runner from config before scheduling; forks inherit it.
+      attr_writer :cap
+
+      def cap = @cap || DEFAULT_CAP
+    end
+
+    def initialize(subject, mutated_source)
+      @subject = subject
+      @mutated_source = mutated_source
+    end
+
+    def call(cap: self.class.cap)
+      target = resolve_target
+      closure = compute_closure(target)
+      if closure.size > cap
+        raise Skip, "reload closure (#{closure.size} constants) exceeds cap (#{cap})"
+      end
+
+      # Re-eval must load dependencies before dependents. Every closure member
+      # carries the target directly (single-pass discovery invariant), so the
+      # target must be re-eval'd first — pin it to the front. `ancestors.size`
+      # can't do this alone: an `extend` puts the target in the extender's
+      # SINGLETON ancestry, so a module that extends the target has an instance
+      # ancestry SMALLER than the target's and would sort before it (NameError
+      # on re-eval). For the remaining attachers, ascending instance-ancestor
+      # depth is a valid order among include/subclass relationships (a
+      # superclass before its subclass, an included module before its
+      # includer); depth is captured while the constants are still live, since
+      # it can't be read after remove_const.
+      rest = closure.reject { |m| m.equal?(target) }
+      ordered = [target, *rest.sort_by { |m| m.ancestors.size }]
+      sources = ordered.map { |mod| [mod.name, source_for(mod)] }
+      sources.each { |name, _| remove_constant(name) }
+      sources.each_with_index do |(_, (file, src)), idx|
+        eval(src, TOPLEVEL_BINDING, file, 1) # rubocop:disable Security/Eval
+      rescue ScriptError, StandardError => e
+        # idx.zero? is the MUTATED target, which by construction depends on
+        # nothing else in the closure (every other member carries the target,
+        # not vice versa). Its source failing to load is therefore the
+        # mutation's own doing — a kill, not a tool error.
+        #
+        # A PRISTINE dependent (idx > 0) failing means the ancestry-depth order
+        # couldn't satisfy a cross-attacher reference (see the ordering note
+        # above): we can't faithfully reinstate the closure, so this is an
+        # honest Skip, not a survived/killed verdict and not a bare error.
+        raise MutantLoadError, e.message if idx.zero?
+
+        raise Skip, "reload re-eval failed (#{e.message}); closure could not be reinstated in dependency order"
+      end
+      nil
+    end
+
+    private
+
+    def resolve_target
+      scope = @subject.constant_scope
+      target = begin
+        Object.const_get(scope)
+      rescue NameError
+        raise Skip, "constant #{scope} not loaded"
+      end
+      file, = Object.const_source_location(scope)
+      unless file && File.identical?(file, @subject.file)
+        raise Skip, "#{scope} defined at #{file || "?"}, not #{@subject.file} (reopened constant)"
+      end
+      target
+    end
+
+    # Single discovery pass. Ruby's `ancestors` is transitive, so one scan for
+    # everything carrying the target already yields every transitive attacher:
+    # an attacher-of-an-attacher (a subclass of an includer, an includer of an
+    # includer) carries the target directly too. No BFS/dedup is needed — the
+    # re-eval order is imposed later by pinning the target first and sorting the
+    # rest by ancestry depth (see #call), not by discovery order and not by a
+    # full topological sort (deliberately not attempted; see class docstring).
+    def compute_closure(target)
+      [target, *attachers(target)]
+    end
+
+    # Everything stale after removing `mod`: includers and subclasses carry
+    # it in `ancestors`; extend-sites carry it in their singleton class's
+    # ancestors, so singleton classes map back through attached_object. `.uniq`
+    # collapses a member found both ways (a class that both includes and
+    # extends the target).
+    def attachers(mod)
+      ObjectSpace.each_object(Module).filter_map do |m|
+        next if m.equal?(mod)
+        next unless carries?(m, mod)
+
+        if m.singleton_class?
+          m = m.attached_object
+          unless m.is_a?(Module)
+            raise Skip, "an object instance is extended with #{mod.name || mod.inspect}; not reloadable"
+          end
+        end
+
+        m
+      end.uniq
+    end
+
+    # ObjectSpace hands back every Module in the VM, including ones we cannot
+    # introspect — e.g. a module whose #ancestors is overridden to raise. A
+    # module we cannot read is not a reloadable dependency of the target, so
+    # treat it as unrelated rather than aborting the whole scan. Trade-off: a
+    # genuine attacher whose #ancestors raises would be silently dropped
+    # (acceptable — pathological).
+    #
+    # The rescue is deliberately broader than StandardError: #ancestors on a
+    # foreign object can raise Exception-level errors that are NOT StandardError
+    # — the canonical case is an expired RSpec verifying double
+    # (ExpiredTestDoubleError < MockExpectationError < Exception) left in
+    # ObjectSpace by another spec. Control-flow errors (a signal such as an
+    # interrupt, or an explicit exit) are re-raised so a run stays
+    # interruptible; everything else means "not a dependency, skip it".
+    def carries?(mod, target)
+      mod.ancestors.include?(target)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      raise if e.is_a?(SignalException) || e.is_a?(SystemExit)
+
+      false
+    end
+
+    def source_for(mod)
+      name = mod.name
+      raise Skip, "anonymous #{mod.is_a?(Class) ? "class" : "module"} in reload closure" unless name
+
+      return [@subject.file, @mutated_source] if name == @subject.constant_scope
+
+      file, = Object.const_source_location(name)
+      raise Skip, "#{name}: no source file (native or dynamically defined)" unless file && File.exist?(file)
+
+      src = File.read(file)
+      unless single_constant_file?(src)
+        raise Skip, "#{name}: #{file} defines multiple top-level constants; not reloadable"
+      end
+
+      [file, src]
+    end
+
+    # Same Zeitwerk-shape rule the SubjectFinder gate applies to the target
+    # file: re-evaling a multi-constant file would re-run macros on constants
+    # that were NOT removed (accumulation bugs). Shared with SubjectFinder.
+    def single_constant_file?(source)
+      result = Prism.parse(source)
+      return false unless result.success?
+
+      ClassShape.single_top_level_constant?(result.value)
+    end
+
+    def remove_constant(name)
+      parts = name.split("::")
+      leaf = parts.pop
+      parent = parts.empty? ? Object : Object.const_get(parts.join("::"))
+      parent.send(:remove_const, leaf)
+    rescue NameError
+      # Either a parent namespace earlier in the closure was already removed
+      # (taking this nested constant with it), or the leaf is already gone.
+      # Nothing to remove — the re-eval pass reinstates it from its own file.
+    end
+  end
+end

data/lib/active_mutator/config.rb

@@ -5,5 +5,6 @@ module ActiveMutator
                        :timeout_factor, :timeout_floor, :force_baseline, :root,
                        :preload_helper, :serial_patterns, :browser_boot_seconds,
                        :accept_survivors, :exclude, :max_mutants, :debug_plan,
-                       :fail_at, :adaptive_timeout, :operator_paths)
+                       :fail_at, :adaptive_timeout, :operators,
+                       :class_level, :class_level_closure_cap)
 end

data/lib/active_mutator/config_file.rb

@@ -22,12 +22,11 @@ module ActiveMutator
       "requires" => :string_list,
       "operators" => :string_list,
       "preload_helper" => :preload_helper,
-      "adaptive_timeout" => :boolean
+      "adaptive_timeout" => :boolean,
+      "class_level" => :boolean,
+      "class_level_closure_cap" => :positive_integer
     }.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)
@@ -40,7 +39,7 @@ module ActiveMutator
         validator = KEYS[key]
         raise Error, "#{FILENAME}: unknown config key: #{key}" unless validator
 
-        [RENAMES.fetch(key, key.to_sym), coerce(key, validator, value)]
+        [key.to_sym, coerce(key, validator, value)]
       end
     end
 
@@ -55,6 +54,10 @@ module ActiveMutator
       when :integer
         raise Error, "#{FILENAME}: #{key} must be an integer" unless value.is_a?(Integer)
         value
+      when :positive_integer
+        raise Error, "#{FILENAME}: #{key} must be an integer" unless value.is_a?(Integer)
+        raise Error, "#{FILENAME}: #{key} must be >= 1" unless value >= 1
+        value
       when :number
         raise Error, "#{FILENAME}: #{key} must be a number" unless value.is_a?(Numeric)
         value.to_f

data/lib/active_mutator/engine.rb

@@ -8,7 +8,9 @@ module ActiveMutator
       result = Prism.parse(source)
       raise Error, "#{subject.file} no longer parses" unless result.success?
 
-      def_node = find_def(result.value, subject.byte_range.begin)
+      return analyze_class_body(subject, source, result) if subject.class_body?
+
+      def_node = find_node(result.value, subject.byte_range.begin, Prism::DefNode)
       raise Error, "subject not found: #{subject.name}" unless def_node
 
       invalid = 0
@@ -22,16 +24,115 @@ module ActiveMutator
 
     private
 
-    def find_def(node, start_offset)
-      return node if node.is_a?(Prism::DefNode) && node.location.start_offset == start_offset
+    def analyze_class_body(subject, source, result)
+      class_node = find_node(result.value, subject.byte_range.begin, Prism::ClassNode, Prism::ModuleNode)
+      raise Error, "subject not found: #{subject.name}" unless class_node
+
+      invalid = 0
+      mutations = collect_class_body_edits(class_node).filter_map do |edit|
+        mutation, valid = build_class_body_mutation(subject, source, edit)
+        invalid += 1 unless valid
+        mutation
+      end
+      Analysis.new(mutations: mutations, invalid_count: invalid)
+    end
+
+    # Depth-first search for the node of one of `types` whose byte range starts
+    # at `start_offset`. Def-level and class-body subject location share this;
+    # only the node type(s) differ (DefNode vs Class/ModuleNode).
+    def find_node(node, start_offset, *types)
+      return node if types.any? { |t| node.is_a?(t) } && node.location.start_offset == start_offset
 
       node.compact_child_nodes.each do |child|
-        found = find_def(child, start_offset)
+        found = find_node(child, start_offset, *types)
         return found if found
       end
       nil
     end
 
+    # Class-level code only: defs, nested class/modules and `class << self`
+    # bodies are owned by other subjects. Lambdas (scope bodies, if: procs) ARE
+    # descended, as are the ActiveSupport::Concern DSL blocks (`included`,
+    # `prepended`, `class_methods`) whose bodies re-run as class-level code in
+    # the includer (issue #31). Every OTHER block (association extensions,
+    # custom DSLs that run in an unknown context) stays pruned — mutating those
+    # risks false survivors. Edits that would delete a whole owned statement
+    # (StatementDeletion sees the enclosing StatementsNode) are discarded.
+    # Owned ranges are collected recursively while walking, not just from the
+    # class body's direct children: a def can nest inside class-level control
+    # flow (`if`/`unless`/`begin`), and deleting it there is equally out of
+    # scope.
+    def collect_class_body_edits(class_node)
+      owned = []
+      edits = []
+      class_walk(class_node.body, owned) do |node|
+        @operators.each do |op|
+          edits.concat(op.edits(node))
+        rescue StandardError => e
+          raise Error, "operator #{op.class.name} failed on #{node.class.name}: #{e.message}"
+        end
+      end
+      edits.reject { |e| owned.include?(e.range) }
+    end
+
+    def owned_statement?(node) = ClassShape.owned_by_other_subject?(node)
+
+    # ActiveSupport::Concern DSL calls whose block body re-runs as class-level
+    # code in the includer, so it is in scope for class-body mutation.
+    CONCERN_BLOCK_CALLS = %i[included prepended class_methods].freeze
+
+    def concern_dsl_block?(node)
+      node.is_a?(Prism::CallNode) && node.receiver.nil? &&
+        CONCERN_BLOCK_CALLS.include?(node.name) && node.block.is_a?(Prism::BlockNode)
+    end
+
+    # No nil guard needed (unlike #walk): the entry node is the class body's
+    # StatementsNode, guaranteed present for a class-body subject, and
+    # compact_child_nodes never yields nil.
+    def class_walk(node, owned, &blk)
+      if owned_statement?(node)
+        owned << (node.location.start_offset...node.location.end_offset)
+      elsif node.is_a?(Prism::BlockNode)
+        # Pruned: a block's run-time context is unknown (see collect comment).
+      elsif concern_dsl_block?(node)
+        # Inside a concern block the statements have no subject of their own, so
+        # mutate everything (including nested def bodies) exactly like the
+        # def-level #walk — do NOT recurse via class_walk (it would prune the
+        # block) and do NOT mark the interior defs owned. The concern call node
+        # itself is not yielded: the whole-block deletion edit already comes
+        # from the enclosing StatementsNode, and no operator targets a bare
+        # receiverless call.
+        walk(node.block.body, &blk)
+      else
+        yield node
+        node.compact_child_nodes.each { |child| class_walk(child, owned, &blk) }
+      end
+    end
+
+    # The mutant is the whole file. The def-shaped fields are filled with the
+    # file source so the Mutation shape stays uniform; Worker routes
+    # class-body mutants through ClosureReload (whole-file re-eval), never
+    # through Inserter's class_eval.
+    def build_class_body_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?
+      return [nil, false] unless find_node(parsed.value, subject.byte_range.begin, Prism::ClassNode, Prism::ModuleNode)
+
+      [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: mutated,
+        mutated_def_line: 1
+      ), true]
+    end
+
     def collect_edits(def_node)
       edits = []
       walk(def_node.body) do |node|
@@ -71,7 +172,7 @@ module ActiveMutator
       parsed = Prism.parse(mutated)
       return [nil, false] unless parsed.success?
 
-      new_def = find_def(parsed.value, subject.byte_range.begin)
+      new_def = find_node(parsed.value, subject.byte_range.begin, Prism::DefNode)
       return [nil, false] unless new_def
 
       [Mutation.new(

data/lib/active_mutator/reporter/stryker_json.rb

@@ -13,7 +13,8 @@ module ActiveMutator
     class StrykerJson
       SCHEMA_URL = "https://git.io/mutation-testing-schema"
       STATUS = { killed: "Killed", survived: "Survived", timeout: "Timeout",
-                 error: "RuntimeError", uncovered: "NoCoverage", accepted: "Ignored" }.freeze
+                 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")
 
@@ -87,7 +88,17 @@ module ActiveMutator
       def covered_by(result)
         return nil unless @coverage_map
 
-        @coverage_map.examples_for(result.mutation.subject.file, result.mutation.lines)
+        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)

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,8 @@ 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?
@@ -54,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

@@ -10,6 +10,7 @@ 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)
@@ -25,7 +26,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 +36,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 +45,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 +56,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 = 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)
@@ -78,12 +139,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 +192,24 @@ 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?
+
+      (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
       case @config.format
       when :json then Reporter::Json.new
@@ -126,6 +238,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) }
@@ -210,8 +323,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.3.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.3.0
 platform: ruby
 authors:
 - Daniel John
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-30 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