active_mutator 0.1.1 → 0.2.0

data/lib/active_mutator/reporter/github.rb

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

data/lib/active_mutator/reporter/json.rb

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

data/lib/active_mutator/reporter/operator_stats.rb

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

data/lib/active_mutator/reporter/stryker_json.rb

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

data/lib/active_mutator/reporter/terminal.rb

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

data/lib/active_mutator/runner.rb

@@ -1,3 +1,5 @@
+require "json"
+
 module ActiveMutator
   class Runner
     def initialize(config, reporter: nil)
@@ -7,24 +9,34 @@ module ActiveMutator
 
     def call
       ENV["ACTIVE_MUTATOR"] = "1"
+      load_operators
       preload!
       preload_spec_helper!
       map = Baseline.new(root: @config.root).coverage_map(force: @config.force_baseline)
+      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
       subjects = discover_subjects
       analyses = subjects.map { |s| Engine.new.analyze(s) }
       mutations = analyses.flat_map(&:mutations)
+      mutations = mutations.first(@config.max_mutants) if @config.max_mutants
       invalid_count = analyses.sum(&:invalid_count)
 
       fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
       ledger = AcceptedLedger.load(@config.root)
-      warn_stale(ledger, fingerprints.values)
+      scanned_files = prune_scope(subjects)
+      warn_stale(ledger, fingerprints.values, scanned_files)
 
       items, pre_results = 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) }
-      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result))
+      calibrators = if @config.adaptive_timeout
+                      { parallel: TimeoutCalibrator.new, serial: TimeoutCalibrator.new }
+                    end
+      scheduler = Scheduler.new(jobs: @config.jobs, on_result: @reporter.method(:on_result),
+                                calibrators: calibrators)
       results = scheduler.run(items) + pre_results
 
-      accept_survivors!(ledger, results, fingerprints) if @config.accept_survivors
+      accept_survivors!(ledger, results, fingerprints, scanned_files) if @config.accept_survivors
 
       @reporter.summary(results, invalid_count: invalid_count)
       exit_code(results)
@@ -39,27 +51,60 @@ module ActiveMutator
           pre_results << Result.new(mutation: mutation, status: :accepted, details: nil)
           next
         end
-        example_ids = map.examples_for(mutation.subject.file, mutation.lines)
+        example_ids = map.examples_for(mutation.subject.file, coverage_lines(mutation))
         if example_ids.empty?
           pre_results << Result.new(mutation: mutation, status: :uncovered, details: nil)
         else
           lane = example_ids.any? { |id| serial_example?(id) } ? :serial : :parallel
-          timeout = map.time_for(example_ids) * @config.timeout_factor + @config.timeout_floor
-          timeout += @config.browser_boot_seconds if lane == :serial
-          items << WorkItem.new(mutation: mutation, example_ids: example_ids, timeout: timeout, lane: lane)
+          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)
         end
       end
       [items, pre_results]
     end
 
     def exit_code(results)
-      results.any? { |r| r.status == :survived } ? 1 : 0
+      survived = results.count { |r| r.status == :survived }
+      return 0 if survived.zero?
+      return 1 unless @config.fail_at
+
+      detected = results.count { |r| %i[killed timeout].include?(r.status) }
+      score = detected * 100.0 / (detected + survived)
+      score >= @config.fail_at ? 0 : 1
     end
 
     private
 
+    # 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|
+        require File.expand_path(f, @config.root)
+      rescue LoadError, SyntaxError => e
+        raise Error, "operator file not loadable: #{f}: #{e.message}"
+      end
+    end
+
+    # Line coverage attributes multi-line expressions to their statement anchor
+    # line (version-dependently), so a sub-expression mutant's own lines may
+    # carry no coverage at all. Look up the whole subject instead: a mutant must
+    # run against every example covering any line of its method.
+    def coverage_lines(mutation)
+      mutation.lines.to_a | mutation.subject.line_range.to_a
+    end
+
     def build_reporter
-      @config.format == :json ? Reporter::Json.new : Reporter::Terminal.new
+      case @config.format
+      when :json then Reporter::Json.new
+      when :stryker_json then Reporter::StrykerJson.new(root: @config.root)
+      when :github then Reporter::Github.new(root: @config.root)
+      else Reporter::Terminal.new
+      end
     end
 
     def preload!
@@ -77,9 +122,14 @@ module ActiveMutator
     def discover_subjects
       paths = @config.paths.empty? ? default_paths : @config.paths
       subjects = paths
-        .flat_map { |p| Dir[File.join(@config.root, p, "**", "*.rb")] }
+        .flat_map { |p| expand_path_arg(p) }
+        .uniq
+        .reject { |file| excluded?(file) }
         .sort.flat_map { |file| SubjectFinder.call(file) }
-      subjects = subjects.select { |s| s.name == @config.subject_filter } if @config.subject_filter
+      if @config.subject_filter
+        matcher = SubjectMatcher.new(@config.subject_filter)
+        subjects = subjects.select { |s| matcher.match?(s.name) }
+      end
       if @config.since
         filter = SinceFilter.new(ref: @config.since, root: @config.root)
         subjects = subjects.select { |s| filter.cover?(s) }
@@ -87,6 +137,34 @@ module ActiveMutator
       subjects
     end
 
+    # Positional args may be files or directories. Anything else is an error:
+    # a mistyped path that silently matched nothing produced a false green
+    # (0 subjects, exit 0) — see #23.
+    def expand_path_arg(path)
+      full = File.expand_path(path, @config.root)
+      if File.file?(full)
+        raise Error, "not a Ruby file: #{path}" unless full.end_with?(".rb")
+
+        [full]
+      elsif Dir.exist?(full)
+        Dir[File.join(full, "**", "*.rb")]
+      else
+        raise Error, "no such file or directory: #{path}"
+      end
+    end
+
+    def excluded?(file)
+      flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+      relative = file.delete_prefix(@config.root.chomp("/") + "/")
+      @config.exclude.any? do |pattern|
+        # Gitignore-like ergonomics: "lib/gen", "lib/gen/" and "lib/gen/**"
+        # all exclude the whole subtree, not just direct children.
+        dir = pattern.sub(%r{(/\*\*)?/?\z}, "")
+        File.fnmatch?(pattern, relative, flags) ||
+          File.fnmatch?("#{dir}/**/*", relative, flags)
+      end
+    end
+
     def default_paths
       %w[app lib].select { |p| Dir.exist?(File.join(@config.root, p)) }
     end
@@ -127,17 +205,43 @@ module ActiveMutator
       SimpleCov.at_exit {} if defined?(SimpleCov)
     end
 
-    def accept_survivors!(ledger, results, fingerprints)
+    # Only a run with no subject-level narrowing has fully scanned a file;
+    # anything narrower must not prune (or warn about) out-of-scope entries.
+    # MAINTENANCE: any future flag that narrows the mutant set below "every
+    # subject in the scanned files" MUST be added to this nil-trigger list,
+    # or scoped accept runs will clobber out-of-scope ledger entries (#24).
+    def prune_scope(subjects)
+      return nil if @config.subject_filter || @config.since || @config.max_mutants
+
+      subjects.map { |s| s.file.delete_prefix("#{@config.root}/") }.uniq
+    end
+
+    def accept_survivors!(ledger, results, fingerprints, scanned_files)
       survivors = results.select { |r| r.status == :survived }.map { |r| fingerprints[r.mutation] }
       return if survivors.empty?
 
-      ledger.accept!(survivors, fingerprints.values)
+      ledger.accept!(survivors, fingerprints.values, scanned_files: scanned_files)
     end
 
-    def warn_stale(ledger, all_fingerprints)
-      ledger.stale_entries(all_fingerprints).each do |entry|
+    def debug_plan(items, pre_results)
+      plan = items.map do |i|
+        { "subject" => i.mutation.subject.name, "description" => i.mutation.description,
+          "file" => i.mutation.subject.file, "line" => i.mutation.line,
+          "lane" => i.lane.to_s, "timeout" => i.timeout.round(2),
+          "examples" => i.example_ids.size }
+      end
+      skipped = pre_results.group_by { |r| r.status.to_s }.transform_values(&:size)
+      puts JSON.pretty_generate("planned" => plan, "pre_resolved" => skipped)
+      0
+    end
+
+    def warn_stale(ledger, all_fingerprints, scanned_files)
+      ledger.stale_entries(all_fingerprints, scanned_files: scanned_files).each do |entry|
         warn "active_mutator: stale accepted fingerprint (no matching mutant): #{entry.subject}, #{entry.description}"
       end
+      ledger.missing_file_entries(@config.root).each do |entry|
+        warn "active_mutator: accepted fingerprint references missing file: #{entry.file} (#{entry.subject})"
+      end
     end
   end
 end

data/lib/active_mutator/scheduler.rb

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

data/lib/active_mutator/source_location.rb

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

data/lib/active_mutator/subject.rb

@@ -1,7 +1,13 @@
 module ActiveMutator
   # A mutable unit: one method definition.
   # byte_range/line_range cover the whole `def ... end`.
-  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind) do
+  # sclass: def lives inside `class << self` — its source slice is `def foo`,
+  # so Inserter must target the singleton class, not the constant itself.
+  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind, :sclass) do
+    def initialize(name:, file:, byte_range:, line_range:, constant_scope:, kind:, sclass: false)
+      super
+    end
+
     def singleton? = kind == :singleton
   end
 end

data/lib/active_mutator/subject_finder.rb

@@ -1,36 +1,73 @@
+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)
       finder.visit(result.value)
       finder.subjects
     end
 
     attr_reader :subjects
 
-    def initialize(file)
+    def initialize(file, skip_lines: Set.new)
       @file = file
+      @skip_lines = skip_lines
       @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)
+      return if @sclass_depth.positive?
+
       with_scope(node.constant_path.slice) { super }
     end
 
     def visit_module_node(node)
+      return if @sclass_depth.positive?
+
       with_scope(node.constant_path.slice) { super }
     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,9 +76,11 @@ 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

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