active_mutator 0.1.1 → 0.3.0

data/lib/active_mutator/subject_finder.rb

@@ -1,36 +1,88 @@
+require "set"
+
 module ActiveMutator
   class SubjectFinder < Prism::Visitor
+    SKIP_MARKER = /#\s*active_mutator:\s*skip\b/
+
     def self.call(file)
       result = Prism.parse(File.read(file))
       return [] unless result.success?
 
-      finder = new(file)
+      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,
+                   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)
+    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
       super()
     end
 
+    # Classes/modules declared inside `class << self` hang their constant on
+    # the SINGLETON class, so a lexically-joined scope like "Foo::Bar" is not
+    # reachable via Object.const_get — Inserter would crash. Skipped entirely.
     def visit_class_node(node)
-      with_scope(node.constant_path.slice) { super }
+      return if @sclass_depth.positive?
+
+      with_scope(node.constant_path.slice) do
+        add_class_body_subject(node)
+        super
+      end
     end
 
     def visit_module_node(node)
-      with_scope(node.constant_path.slice) { super }
+      return if @sclass_depth.positive?
+
+      with_scope(node.constant_path.slice) do
+        add_class_body_subject(node)
+        super
+      end
     end
 
-    # `class << self` bodies are a documented v1 limit: not visited.
-    def visit_singleton_class_node(node); end
+    # `class << self` inside a constant scope: defs there are singleton
+    # methods of the enclosing constant. `class << obj` and a top-level
+    # `class << self` (no constant to hang the method on) stay skipped.
+    def visit_singleton_class_node(node)
+      return unless node.expression.is_a?(Prism::SelfNode) && !@stack.empty?
+
+      @sclass_depth += 1
+      begin
+        super
+      ensure
+        @sclass_depth -= 1
+      end
+    end
+
+    # Defs inside blocks (`Data.define do ... end`, `class_eval do ... end`)
+    # do not live on the enclosing constant scope, so Inserter would redefine
+    # them on the wrong constant and every mutant would falsely survive.
+    # Same v1 limit as `class << self`: not visited. Note this also hides
+    # classes/modules defined inside blocks (accepted v1 limit).
+    def visit_block_node(node); end
 
     def visit_def_node(node)
-      singleton = node.receiver.is_a?(Prism::SelfNode)
+      return if @skip_lines.include?(node.location.start_line - 1)
+
+      sclass = @sclass_depth.positive?
+      singleton = sclass || node.receiver.is_a?(Prism::SelfNode)
       scope = @stack.empty? ? nil : @stack.join("::")
       loc = node.location
       @subjects << Subject.new(
@@ -39,13 +91,41 @@ module ActiveMutator
         byte_range: loc.start_offset...loc.end_offset,
         line_range: loc.start_line..loc.end_line,
         constant_scope: scope,
-        kind: singleton ? :singleton : :instance
+        kind: singleton ? :singleton : :instance,
+        sclass: sclass
       )
-      # No `super`: nested defs are out of scope for v1.
+      # No `super`: nested defs get no subject of their own -- their bodies
+      # are mutated via the OUTER def (Engine#walk descends into them).
     end
 
     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/subject_matcher.rb

@@ -0,0 +1,23 @@
+module ActiveMutator
+  # Tiny subject-expression grammar for --subject:
+  #   Foo::Bar#baz  exact          Foo::Bar   all methods of the constant
+  #   Foo::Bar*     namespace      Foo::Bar#* instance-only   Foo::Bar.* singleton-only
+  class SubjectMatcher
+    def initialize(expression)
+      @regexp = compile(expression)
+    end
+
+    def match?(name) = @regexp.match?(name)
+
+    private
+
+    def compile(expr)
+      case expr
+      when /\A(.+)([#.])\*\z/ then /\A#{Regexp.escape($1)}#{Regexp.escape($2)}[^#.]+\z/
+      when /\A(.+)\*\z/       then /\A#{Regexp.escape($1)}/
+      when /[#.]/             then /\A#{Regexp.escape(expr)}\z/
+      else                         /\A#{Regexp.escape(expr)}[#.][^#.]+\z/
+      end
+    end
+  end
+end

data/lib/active_mutator/timeout_calibrator.rb

@@ -0,0 +1,75 @@
+module ActiveMutator
+  # Adaptive timeout budgets (#9). Static budgets derive from baseline times
+  # measured warm and unloaded; under parallel load they misclassify
+  # slow-but-honest kills as timeouts. The Scheduler feeds this with the
+  # observed wall time of every KILLED fork (errors exit artificially fast,
+  # survivors run their whole covering set — both would bias the median;
+  # timed-out forks have no known wall time at all). One instance per lane:
+  # parallel and serial run under different load regimes.
+  #
+  # Utilization is elapsed / the EFFECTIVE budget the fork ran under (the
+  # value budget_for returned at its spawn), not the static item.timeout —
+  # otherwise a pinned-high scale could never observe recovery (ratchet).
+  # Once WARMUP observations exist, remaining budgets' variable part is
+  # scaled by the clamped median utilization. The fixed part (timeout_floor
+  # + browser boot) is never scaled: fork boot cost does not shrink because
+  # examples run fast.
+  #
+  # The scale is grow-only (MIN_SCALE = 1.0): budgets may only extend beyond
+  # the static value, never fall below it. Downscaling has no recovery signal
+  # because timeouts are CENSORED samples — the scheduler skips them (they have
+  # no known wall time), so only killed forks feed the window. A low median
+  # utilization would shrink the budget, causing a legitimately slow kill to be
+  # reaped as a timeout; that censored kill never enters the window, so nothing
+  # ever pushes utilization back up. The shrink self-sustains — an asymmetric
+  # ratchet. Growing is safe (a too-large budget still records a real kill and
+  # relaxes); shrinking is not, so we forbid it.
+  class TimeoutCalibrator
+    WARMUP = 5
+    # A real sliding window, not full-run history: a 500-mutant run's early
+    # load regime must age out completely instead of anchoring the median
+    # forever. 30 samples is enough for a stable median and small enough to
+    # track load changes within a few dozen finishes.
+    WINDOW = 30
+    TARGET_UTILIZATION = 0.25
+    MIN_SCALE = 1.0
+    MAX_SCALE = 4.0
+
+    def initialize
+      @utilizations = []
+    end
+
+    def record(elapsed_seconds, budget)
+      return unless budget.positive?
+
+      @utilizations << elapsed_seconds / budget
+      @utilizations.shift while @utilizations.size > WINDOW
+    end
+
+    def warmed? = @utilizations.size >= WARMUP
+
+    def budget_for(item)
+      return item.timeout unless warmed?
+
+      fixed = item.timeout - item.variable
+      item.variable * scale + fixed
+    end
+
+    def scale
+      # An empty window has no median; a caller invoking scale without warmed?
+      # (median of [] is nil) would otherwise raise. Neutral scale = no change.
+      return 1.0 if @utilizations.empty?
+
+      s = median(@utilizations) / TARGET_UTILIZATION
+      s.clamp(MIN_SCALE, MAX_SCALE)
+    end
+
+    private
+
+    def median(values)
+      sorted = values.sort
+      mid = sorted.size / 2
+      sorted.size.odd? ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0
+    end
+  end
+end

data/lib/active_mutator/version.rb

@@ -1,3 +1,3 @@
 module ActiveMutator
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/active_mutator/work_item.rb

@@ -1,4 +1,11 @@
 module ActiveMutator
   # lane: :parallel (default pool) | :serial (browser-covered, one at a time)
-  WorkItem = Data.define(:mutation, :example_ids, :timeout, :lane)
+  # timeout:    static total budget (variable + fixed), kept for --debug-plan and compat
+  # variable:   the baseline-estimate-derived part (estimate * timeout_factor) — the
+  #             only part the TimeoutCalibrator scales
+  WorkItem = Data.define(:mutation, :example_ids, :timeout, :lane, :variable) do
+    def initialize(mutation:, example_ids:, timeout:, lane:, variable: 0.0)
+      super
+    end
+  end
 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,17 +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
-      Inserter.new.insert(@mutation)   # now the target constant exists
+      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
       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,7 +10,9 @@ 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"
 require_relative "active_mutator/operators/conditional_boundary"
 require_relative "active_mutator/operators/condition_forcing"
@@ -27,16 +29,24 @@ require_relative "active_mutator/atomic_file"
 require_relative "active_mutator/coverage_map"
 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"
+require_relative "active_mutator/timeout_calibrator"
 require_relative "active_mutator/scheduler"
+require_relative "active_mutator/reporter/operator_stats"
 require_relative "active_mutator/reporter/terminal"
+require_relative "active_mutator/reporter/github"
 require_relative "active_mutator/reporter/json"
+require_relative "active_mutator/source_location"
 require_relative "active_mutator/since_filter"
 require_relative "active_mutator/fingerprint"
 require_relative "active_mutator/accepted_ledger"
+require_relative "active_mutator/reporter/stryker_json"
 require_relative "active_mutator/config"
 require_relative "active_mutator/runner"
+require_relative "active_mutator/config_file"
 require_relative "active_mutator/cli"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_mutator
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Daniel John
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-14 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,9 +78,13 @@ 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
+- lib/active_mutator/defined_constants.rb
 - lib/active_mutator/edit.rb
 - lib/active_mutator/engine.rb
 - lib/active_mutator/fingerprint.rb
@@ -89,15 +99,21 @@ files:
 - lib/active_mutator/operators/logical_operator.rb
 - lib/active_mutator/operators/negation_removal.rb
 - lib/active_mutator/operators/statement_deletion.rb
+- lib/active_mutator/reporter/github.rb
 - lib/active_mutator/reporter/json.rb
+- lib/active_mutator/reporter/operator_stats.rb
+- lib/active_mutator/reporter/stryker_json.rb
 - lib/active_mutator/reporter/terminal.rb
 - lib/active_mutator/result.rb
 - lib/active_mutator/runner.rb
 - lib/active_mutator/scheduler.rb
 - lib/active_mutator/since_filter.rb
+- lib/active_mutator/source_location.rb
 - lib/active_mutator/splicer.rb
 - lib/active_mutator/subject.rb
 - lib/active_mutator/subject_finder.rb
+- lib/active_mutator/subject_matcher.rb
+- lib/active_mutator/timeout_calibrator.rb
 - lib/active_mutator/version.rb
 - lib/active_mutator/work_item.rb
 - lib/active_mutator/worker.rb
@@ -106,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