active_mutator 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35694bf66189f60b88d9761217beb3cd025e74998e0ed1a2eed69a4a002f4b04
-  data.tar.gz: e4dc5eb475d915653cf317379fa565aefacbcbe0d0f5115bd750dbb8860c74c7
+  metadata.gz: 60c123ba92745825d5041728a14144e2cad95ba814d54fcb72bba40e1d5c0089
+  data.tar.gz: b7f96c322c455aa01d4ef19e04aa017f61fecb82347b1da7e315cfdc4316708e
 SHA512:
-  metadata.gz: 8e8d6d31ef9767b5ae869b753090e8237f94442a82271fcec9aaa126ea02a2392f8c884bb978339c2cdf30210fde64948040cd226d2d0491eca3617db783e5bd
-  data.tar.gz: d4ac2c77866af4cfb2369ff7a1a8be527d2dddacbd494d28310710ba92936d2321f6b6993168e7e1aaf8dd7059a2ae91818f90c8815b2cfb95447a11ae67f800
+  metadata.gz: 134766964d548d79002d0364046d6a46cb9a3b3d14b334c7d7ee67b3581865c31f10184bd7666d59f5732122dbc74f8c8ffdd7ee14664cd610c38ba64675fc31
+  data.tar.gz: 22bd7813d2a1d061a045a3bc3c7cc2d21c31b3d34f6c8b26e0f2433921b131c124f0f652e3367657bfcc26e987dd7416763c33e05d3e074cfa688703047ec8e2

data/README.md

@@ -58,7 +58,7 @@ changed and nothing noticed. A survivor is not a hypothetical. It is the
 exact line, the exact before and after diff, and proof that no assertion
 depends on the difference.
 
-Mutation score is `(killed + timeout) / (killed + timeout + survived)`.
+Mutation score is `(killed + timeout) / (killed + timeout + survived + error)`.
 100% is usually not the right target. Some mutants are behaviorally
 *equivalent* to the original and can never be killed by any test. That is
 why active_mutator has a committed acceptance ledger. It lets you close
@@ -121,17 +121,25 @@ Each character on the progress line is one mutant, printed as it finishes:
 |---|---|---|
 | `.` | `killed` | a covering test failed. Good, the mutant is dead |
 | `S` | `survived` | every covering test passed. This is a test gap |
-| `T` | `timeout` | ran past its time budget. Counted as detected (likely an infinite loop) |
-| `E` | `error` | the worker crashed, or the mutated code raised outside a test assertion |
+| `T` | `timeout` | ran past its time budget. Counts as detected (the mutant likely made a loop never end), and the summary lists each one with elapsed vs budget so a tight budget is visible |
+| `E` | `error` | the worker crashed, or the mutated code raised outside a test assertion. Not detected: counts against the score and fails the run |
 | `U` | `uncovered` | no test executes the mutated line at all. This is coverage debt, worse than a survivor |
 | `A` | `accepted` | matches a known-equivalent entry in the acceptance ledger. Excluded from the score |
 
 `invalid` mutants (edits that don't even re-parse as valid Ruby) are
 discarded before scheduling and reported as a count only. Exit code is `1`
-if unaccepted survivors exist (or, with `--fail-at`, if the score is below
-the threshold), `0` otherwise, including when there are only `uncovered`,
-`accepted`, or `error` results. The JSON report's `exit_reason` field
-reflects survivor presence, independent of the `--fail-at` gate.
+if unaccepted survivors or errors exist (or, with `--fail-at`, if the score
+is below the threshold), `0` otherwise, including when there are only
+`uncovered` or `accepted` results. The JSON report's `exit_reason` field
+(`unaccepted_survivors`, `worker_errors`, `clean`, `empty_plan`) is
+independent of the `--fail-at` gate. A `--since` or `--subject` run that
+plans zero mutants skips the baseline, prints the usual count block with
+every status at `0` and no `Mutation score:` line (JSON: `score` is `null`,
+`exit_reason` is `empty_plan`), then warns with the cause and exits `1`
+unless `--allow-empty` is given. The count block is printed on every run,
+whatever the exit code, so log-scraping never has to handle a missing block.
+`--allow-empty` forgives the empty plan only when the `--since` diff touched
+no candidate source file; see [Empty plans in CI](#empty-plans-in-ci).
 
 When survivors exist, the summary also prints a per-operator table showing
 how often each operator's mutants survive, to help spot likely-equivalent
@@ -198,7 +206,7 @@ score is below the threshold). Mistyped positional paths (a file that
 doesn't exist, or a non-`.rb` file) are an error (exit 2) instead of a
 vacuous green run.
 
-Score = (killed + timeout) / (killed + timeout + survived).
+Score = (killed + timeout) / (killed + timeout + survived + error).
 
 ## The dev loop
 
@@ -242,6 +250,29 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
   residual blind spot — constant-reference detection handles the common
   newly-covering-example case since 0.2)
 
+### Empty plans in CI
+
+A `--since` PR run that plans zero mutants skips the baseline, prints the
+zero-count block, and exits `1`. Pass `--allow-empty` to let it decide for
+itself whether that emptiness is fine:
+
+- **Exit 0** when the diff contains no candidate file. A candidate is a
+  changed or untracked `.rb` file inside the scanned paths (positional args
+  or the default `app`/`lib`), not under a spec path, and not matching an
+  `--exclude` pattern. Docs-only, spec-only, and excluded-path PRs pass.
+- **Exit 0** with `--no-class-level` when every changed line in the
+  candidate files falls inside class-body code that flag dropped. The
+  warning names `--no-class-level` as the reason.
+- **Exit 1** otherwise. A candidate source file changed but produced no
+  mutants, and the warning lists the file(s). A comment-only edit in `lib/`
+  counts as a real change here.
+- With `--subject` and no `--since` there is no diff to judge, so
+  `--allow-empty` exits `0` unconditionally.
+
+`--changed` follows the same rule, and an untracked candidate `.rb` file
+counts as a candidate. This replaces the repo-side log-scraping script some
+projects used to tell a docs-only PR from a broken `--since` range.
+
 ## Flags
 
 | Flag | Default | Meaning |
@@ -253,6 +284,7 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
 | `--exclude PAT` | none | skip files matching glob during subject discovery (repeatable, gitignore-like) |
 | `--max-mutants N` | none | deterministic sample of the first N mutants (quick smoke run on huge scopes; accepted/uncovered mutants count against N) |
 | `--debug-plan` | off | print planned mutants as JSON and exit without running |
+| `--allow-empty` | off | forgive an empty `--since`/`--subject` plan, but only when the `--since` diff touched no candidate source file (default: warn and exit 1) |
 | `--format terminal\|json\|stryker-json\|github` | terminal | report format |
 | `--accept-survivors` | off | record survivors to the acceptance ledger |
 | `--force-baseline` | off | ignore cached coverage map |
@@ -401,6 +433,19 @@ change. Also run `bundle exec active_mutator --changed` on your own diff
 before sending a change that touches `lib/`. This is a good idea for the
 same reason you'd want it run on any other codebase.
 
+If a run dies with `baseline suite failed` and a `LoadError` mentioning
+`bundler-2.x/lib/gems/bundler-2.x/exe/bundle`, your Ruby manager (seen with
+mise) breaks nested `bundle exec`: the baseline shells out to `bundle exec
+rspec`, and bundler's exported `RUBYLIB` makes the inner binstub resolve the
+wrong path. Skip the outer bundler instead:
+
+```sh
+ruby -Ilib exe/active_mutator lib --since origin/main   # same as the CI mutation job
+```
+
+The `:e2e` specs nest `bundle exec` on their own inside the fixture project,
+so on such a machine they fail either way; rely on the CI `e2e` job for those.
+
 ## License
 
 [MIT](LICENSE).

data/lib/active_mutator/baseline_delta.rb

@@ -64,8 +64,13 @@ module ActiveMutator
         end
       end
 
+      # An example id passed alongside its own file makes RSpec run ONLY the
+      # listed ids from that file, so a changed spec file's new examples would
+      # never be recorded. A whole-file rerun subsumes the ids.
+      rerun_spec_files = rerun_spec_files.uniq.sort
+      rerun_example_ids = rerun_example_ids.reject { |id| rerun_spec_files.include?(spec_file_of(id)) }
       Delta.new(full: false,
-                rerun_spec_files: rerun_spec_files.uniq.sort,
+                rerun_spec_files: rerun_spec_files,
                 rerun_example_ids: rerun_example_ids.uniq.sort,
                 drop_example_ids: drop_example_ids.uniq.sort,
                 drop_source_files: drop_source_files.uniq.sort)

data/lib/active_mutator/class_shape.rb

@@ -43,5 +43,24 @@ module ActiveMutator
       node.is_a?(Prism::DefNode) || node.is_a?(Prism::ClassNode) ||
         node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
     end
+
+    # ActiveSupport::Concern DSL calls whose block body re-runs as class-level
+    # code in the includer (`included`, `prepended`) or is module_eval'd into
+    # the concern's ClassMethods module (`class_methods`). SubjectFinder gives
+    # the defs inside their own subjects; Engine's class-body walk owns the rest.
+    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
+
+    # Where the search for concern-block defs stops: a def below one of these
+    # is not on the concern's scope, so it gets no subject (same limit as
+    # SubjectFinder#visit_block_node) and stays with the class-body walk.
+    def concern_def_boundary?(node)
+      node.is_a?(Prism::BlockNode) || node.is_a?(Prism::ClassNode) ||
+        node.is_a?(Prism::ModuleNode) || node.is_a?(Prism::SingletonClassNode)
+    end
   end
 end

data/lib/active_mutator/cli.rb

@@ -32,7 +32,7 @@ module ActiveMutator
         spec_paths: ["spec"],
         browser_boot_seconds: 15.0, accept_survivors: false, exclude: [],
         max_mutants: nil, debug_plan: false, fail_at: nil, adaptive_timeout: true,
-        operators: [], class_level: true, class_level_closure_cap: 10
+        operators: [], class_level: true, class_level_closure_cap: 10, allow_empty: false
       }
       options.merge!(ConfigFile.load(Dir.pwd))
       paths = OptionParser.new do |o|
@@ -66,6 +66,9 @@ module ActiveMutator
         o.on("--exclude PAT", "Skip files matching glob, relative to root (repeatable)") { |v| options[:exclude] << v }
         o.on("--max-mutants N", Integer, "Deterministically sample the first N mutants") { |v| options[:max_mutants] = v }
         o.on("--debug-plan", "Print the planned mutant list as JSON and exit") { options[:debug_plan] = true }
+        o.on("--allow-empty",
+             "Exit 0 when --since/--subject plan no mutants and the --since diff touched no mutable " \
+             "source file (default: exit 1)") { options[:allow_empty] = true }
         o.on("--fail-at SCORE", Float, "Exit 0 if mutation score >= SCORE even with survivors (default: any survivor fails)") do |v|
           raise OptionParser::InvalidArgument, "--fail-at must be within 0..100" unless (0..100).cover?(v)
           options[:fail_at] = v

data/lib/active_mutator/config.rb

@@ -7,5 +7,5 @@ module ActiveMutator
                        :browser_boot_seconds,
                        :accept_survivors, :exclude, :max_mutants, :debug_plan,
                        :fail_at, :adaptive_timeout, :operators,
-                       :class_level, :class_level_closure_cap)
+                       :class_level, :class_level_closure_cap, :allow_empty)
 end

data/lib/active_mutator/config_file.rb

@@ -25,7 +25,8 @@ module ActiveMutator
       "preload_helper" => :preload_helper,
       "adaptive_timeout" => :boolean,
       "class_level" => :boolean,
-      "class_level_closure_cap" => :positive_integer
+      "class_level_closure_cap" => :positive_integer,
+      "allow_empty" => :boolean
     }.freeze
 
     def self.load(root)

data/lib/active_mutator/engine.rb

@@ -77,14 +77,7 @@ module ActiveMutator
 
     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
+    def concern_dsl_block?(node) = ClassShape.concern_dsl_block?(node)
 
     # No nil guard needed (unlike #walk): the entry node is the class body's
     # StatementsNode, guaranteed present for a class-body subject, and
@@ -95,20 +88,33 @@ module ActiveMutator
       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)
+        # 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.
+        concern_walk(node.block.body, owned, &blk)
       else
         yield node
         node.compact_child_nodes.each { |child| class_walk(child, owned, &blk) }
       end
     end
 
+    # Inside a concern block, defs are subjects of their own (SubjectFinder
+    # emits them; mirrors ClassShape.concern_dsl_block?), so they are owned
+    # here. Everything else mutates like the def-level #walk, including the
+    # interior of nested blocks, exactly as before defs got their own subjects.
+    def concern_walk(node, owned, &blk)
+      return if node.nil?
+
+      if node.is_a?(Prism::DefNode)
+        owned << (node.location.start_offset...node.location.end_offset)
+      elsif ClassShape.concern_def_boundary?(node)
+        walk(node, &blk)
+      else
+        yield node
+        node.compact_child_nodes.each { |child| concern_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

data/lib/active_mutator/reporter/github.rb

@@ -12,8 +12,8 @@ module ActiveMutator
 
       def on_result(result) = @terminal.on_result(result)
 
-      def summary(results, invalid_count:)
-        @terminal.summary(results, invalid_count: invalid_count)
+      def summary(results, invalid_count:, empty_plan: false)
+        @terminal.summary(results, invalid_count: invalid_count, empty_plan: empty_plan)
         results.select { |r| r.status == :survived }.each { |r| annotate(r) }
       end
 

data/lib/active_mutator/reporter/json.rb

@@ -9,20 +9,30 @@ module ActiveMutator
 
       def on_result(result); end
 
-      def summary(results, invalid_count:)
-        counts = results.group_by(&:status).transform_values(&:size)
+      # An empty plan has no score (null) and its own exit_reason, so a CI
+      # consumer can tell "nothing to mutate" from "everything was killed" (#45).
+      def summary(results, invalid_count:, empty_plan: false)
+        counts = Terminal.counts(results)
         @out.puts JSON.pretty_generate(
-          "score" => Terminal.score(counts),
+          "score" => empty_plan ? nil : 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"
+          "exit_reason" => exit_reason(counts, empty_plan)
         )
       end
 
       private
 
+      def exit_reason(counts, empty_plan)
+        return "empty_plan" if empty_plan
+        return "unaccepted_survivors" if counts[:survived].positive?
+        return "worker_errors" if counts[:error].positive?
+
+        "clean"
+      end
+
       def serialize(result)
         m = result.mutation
         {

data/lib/active_mutator/reporter/stryker_json.rb

@@ -1,4 +1,5 @@
 require "json"
+require "fileutils"
 
 module ActiveMutator
   module Reporter
@@ -31,9 +32,13 @@ module ActiveMutator
         @out.print(Terminal::CHARS.fetch(result.status))
       end
 
-      def summary(results, invalid_count:)
+      # A zero-mutant report is valid schema output, so an empty plan writes the
+      # same file with no files/mutants; the flag is accepted for contract parity.
+      def summary(results, invalid_count:, empty_plan: false)
         report = build_report(results, invalid_count)
         path = File.join(@root, REPORT_PATH)
+        # An empty plan skips the baseline, which used to create this dir.
+        FileUtils.mkdir_p(File.dirname(path))
         AtomicFile.write(path, JSON.pretty_generate(report))
         @out.puts "", "", "Stryker report written to #{REPORT_PATH}"
       end

data/lib/active_mutator/reporter/terminal.rb

@@ -12,16 +12,24 @@ module ActiveMutator
         @out.print(CHARS.fetch(result.status))
       end
 
-      def summary(results, invalid_count:)
-        counts = results.group_by(&:status).transform_values(&:size)
+      # Every status key is present (zero when absent) so the block has the same
+      # shape on every run, including an empty plan.
+      def self.counts(results)
+        tallies = results.group_by(&:status).transform_values(&:size)
+        CHARS.keys.to_h { |status| [status, tallies.fetch(status, 0)] }
+      end
+
+      # `empty_plan: true` means a --since/--subject scope planned nothing: the
+      # count block still prints, but there is no score to report (#45).
+      def summary(results, invalid_count:, empty_plan: false)
+        counts = self.class.counts(results)
         @out.puts "", ""
-        CHARS.each_key do |status|
-          @out.puts "#{status}: #{counts.fetch(status, 0)}"
-        end
+        counts.each { |status, count| @out.puts "#{status}: #{count}" }
         @out.puts "invalid (discarded): #{invalid_count}"
-        @out.puts format("Mutation score: %.1f%%", score(counts) * 100)
-        survivors = results.select { |r| r.status == :survived }
-        print_survivors(survivors) unless survivors.empty?
+        @out.puts format("Mutation score: %.1f%%", score(counts) * 100) unless empty_plan
+        print_group("Surviving mutants:", results.select { |r| r.status == :survived })
+        print_group("Errored mutants (not detected):", results.select { |r| r.status == :error })
+        print_group("Timed-out mutants (counted as detected):", results.select { |r| r.status == :timeout })
         skipped = results.select { |r| r.status == :skipped }
         print_skipped(skipped) unless skipped.empty?
         stats = OperatorStats.call(results)
@@ -29,9 +37,12 @@ module ActiveMutator
         print_operator_stats(noisy) unless noisy.empty?
       end
 
+      # A timeout is a detection (the mutant changed behavior enough to hang,
+      # the same convention as Stryker and PIT). An error is a non-verdict:
+      # scoring it as a pass let a broken worker read as 100%.
       def self.score(counts)
         detected = counts.fetch(:killed, 0) + counts.fetch(:timeout, 0)
-        denominator = detected + counts.fetch(:survived, 0)
+        denominator = detected + counts.fetch(:survived, 0) + counts.fetch(:error, 0)
         return 1.0 if denominator.zero?
 
         detected.to_f / denominator
@@ -49,9 +60,11 @@ module ActiveMutator
         end
       end
 
-      def print_survivors(survivors)
-        @out.puts "", "Surviving mutants:"
-        survivors.each do |result|
+      def print_group(title, group)
+        return if group.empty?
+
+        @out.puts "", title
+        group.each do |result|
           m = result.mutation
           @out.puts "", "  #{m.subject.name} (#{m.subject.file}:#{m.line})"
           @out.puts "    #{m.description}"

data/lib/active_mutator/runner.rb

@@ -2,6 +2,13 @@ require "json"
 
 module ActiveMutator
   class Runner
+    # What discovery saw, beyond the final subject list. `scanned_files` are
+    # root-relative source files after path expansion and excludes, minus
+    # spec_paths; `since_candidates` are the --since diff's files among them;
+    # `since_matched_all` are the since-covered subjects before --no-class-level
+    # drops class bodies. The last two feed the --allow-empty verdict (#46).
+    Discovery = Data.define(:subjects, :scanned_files, :since_candidates, :since_matched_all)
+
     def initialize(config, reporter: nil)
       @config = config
       @reporter = reporter || build_reporter
@@ -13,14 +20,24 @@ module ActiveMutator
       ClosureReload.cap = @config.class_level_closure_cap
       preload!
       preload_spec_helper!
-      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths)
-              .coverage_map(force: @config.force_baseline)
-      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
-      subjects = discover_subjects
+      discovery = discover
+      subjects = discovery.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)
+      # Decide emptiness before the baseline: a scoped run that plans nothing
+      # has no use for a coverage map, and building one spawns the whole spec
+      # suite (#47).
+      if mutations.empty? && (@config.since || @config.subject_filter)
+        return debug_plan([], []) if @config.debug_plan
+
+        return empty_plan_exit(invalid_count, discovery)
+      end
+
+      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths)
+              .coverage_map(force: @config.force_baseline)
+      @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
 
       fingerprints = Fingerprint.for_mutations(mutations, root: @config.root)
       ledger = AcceptedLedger.load(@config.root)
@@ -119,7 +136,7 @@ module ActiveMutator
           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
+          # 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).
@@ -129,17 +146,66 @@ module ActiveMutator
     end
 
     def exit_code(results)
-      survived = results.count { |r| r.status == :survived }
-      return 0 if survived.zero?
+      undetected = results.count { |r| %i[survived error].include?(r.status) }
+      return 0 if undetected.zero?
       return 1 unless @config.fail_at
 
       detected = results.count { |r| %i[killed timeout].include?(r.status) }
-      score = detected * 100.0 / (detected + survived)
+      score = detected * 100.0 / (detected + undetected)
       score >= @config.fail_at ? 0 : 1
     end
 
     private
 
+    # A scoped run that plans nothing must not report "100%" and pass --fail-at:
+    # the usual cause is a --since range or --subject filter that matched no
+    # mutable code, or class-body code dropped by --no-class-level (#23 covers
+    # the zero-subject case for explicit paths).
+    def empty_plan_exit(invalid_count, discovery)
+      @reporter.summary([], invalid_count: invalid_count, empty_plan: true)
+      causes = []
+      causes << "--since #{@config.since} matched no mutable code" if @config.since
+      causes << "--subject #{@config.subject_filter} matched no subjects" if @config.subject_filter
+      causes << "--no-class-level excludes class-body code" unless @config.class_level
+      warn "active_mutator: no mutants planned (#{causes.join("; ")})"
+      unless @config.allow_empty
+        warn "active_mutator: exiting 1; pass --allow-empty if an empty plan is expected"
+        return 1
+      end
+
+      allow_empty_exit(discovery)
+    end
+
+    # --allow-empty forgives an empty plan only when the --since diff touched no
+    # candidate source file (docs-only, spec-only, excluded paths). A changed
+    # candidate that planned nothing is the case worth failing on, unless the
+    # only code it touched is class-body code that --no-class-level dropped.
+    # --subject alone has no diff to judge, so it stays an unconditional 0.
+    def allow_empty_exit(discovery)
+      return 0 unless @config.since
+
+      candidates = discovery.since_candidates
+      return 0 if candidates.empty?
+
+      if !@config.class_level && class_body_only?(discovery.since_matched_all, candidates)
+        warn "active_mutator: forgiving empty plan: changed lines are class-body code and --no-class-level is set"
+        return 0
+      end
+
+      warn "active_mutator: exiting 1; --allow-empty forgives an empty plan only when no candidate " \
+           "source file changed. Changed: #{candidates.join(", ")}"
+      1
+    end
+
+    # Every matched subject is a class body AND every candidate file has one:
+    # a candidate that matched nothing (comment-only edit, deletion) must not
+    # hide behind a class-body change in a different file. Candidates are
+    # non-empty here, so no matches at all fails the second test on its own.
+    def class_body_only?(subjects, candidates)
+      matched_files = subjects.map { |s| relative(s.file) }
+      subjects.all?(&:class_body?) && candidates.all? { |file| matched_files.include?(file) }
+    end
+
     # 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)
@@ -233,23 +299,38 @@ module ActiveMutator
       end
     end
 
-    def discover_subjects
+    def discover
       paths = @config.paths.empty? ? default_paths : @config.paths
-      subjects = paths
+      files = paths
         .flat_map { |p| expand_path_arg(p) }
         .uniq
         .reject { |file| excluded?(file) }
-        .sort.flat_map { |file| SubjectFinder.call(file) }
-      subjects = subjects.reject(&:class_body?) unless @config.class_level
+        .sort
+      scanned_files = files.map { |f| relative(f) }.reject { |rel| under_spec_paths?(rel) }
+      subjects = files.flat_map { |file| SubjectFinder.call(file) }
       if @config.subject_filter
         matcher = SubjectMatcher.new(@config.subject_filter)
         subjects = subjects.select { |s| matcher.match?(s.name) }
       end
+      since_candidates = []
       if @config.since
         filter = SinceFilter.new(ref: @config.since, root: @config.root)
         subjects = subjects.select { |s| filter.cover?(s) }
+        since_candidates = filter.changed_files & scanned_files
       end
-      subjects
+      # Class bodies drop out LAST so since_matched_all still knows about them.
+      since_matched_all = subjects
+      subjects = subjects.reject(&:class_body?) unless @config.class_level
+      Discovery.new(subjects: subjects, scanned_files: scanned_files,
+                    since_candidates: since_candidates, since_matched_all: since_matched_all)
+    end
+
+    def relative(file) = file.delete_prefix(@config.root.chomp("/") + "/")
+
+    # Scanned entries are files, so only the "inside this directory" test
+    # matters; the trailing slash keeps `spec` from swallowing `spec_tools/`.
+    def under_spec_paths?(rel)
+      @config.spec_paths.any? { |sp| rel.start_with?("#{sp.chomp("/")}/") }
     end
 
     # Positional args may be files or directories. Anything else is an error:
@@ -329,7 +410,7 @@ 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
+    # --no-class-level drops every class_body subject (discover), 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)

data/lib/active_mutator/scheduler.rb

@@ -1,4 +1,5 @@
 require "json"
+require "tempfile"
 
 module ActiveMutator
   # Fork pool: one fork per WorkItem, capped at `jobs` concurrent forks.
@@ -62,13 +63,20 @@ module ActiveMutator
       raise OrphanedError, "parent process died; aborting mutation run"
     end
 
+    STDERR_TAIL_LINES = 20
+
     def spawn(item, running)
       reader, writer = IO.pipe
+      stderr_file = Tempfile.new("active_mutator-worker")
       pid = fork do
         reader.close
         Process.setpgid(0, 0)          # own process group: deadline kill reaps grandchildren too
         $stdout.reopen(File::NULL)     # app code that prints must not corrupt parent's report
-        $stderr.reopen(File::NULL)     # ditto for warnings (RSpec/app noise interleaves with reports)
+        $stderr.reopen(stderr_file.path, "w") # kept for the crash report, never shown otherwise
+        # After fork(), libpq's GSS encryption negotiation touches Apple
+        # frameworks and segfaults the child on macOS; disabling it is
+        # harmless everywhere else.
+        ENV["PGGSSENCMODE"] ||= "disable"
         @worker.call(item.mutation, item.example_ids, writer)
         writer.close
         Process.exit!(0)
@@ -78,7 +86,7 @@ module ActiveMutator
       budget = calibrator ? calibrator.budget_for(item) : item.timeout
       log_scale(calibrator, item.lane)
       started = now
-      running[pid] = { reader: reader, item: item, started: started,
+      running[pid] = { reader: reader, item: item, started: started, stderr_file: stderr_file,
                        budget: budget, deadline: started + budget }
     end
 
@@ -96,7 +104,9 @@ module ActiveMutator
           kill(pid)
           running.delete(pid)
           entry[:reader].close
-          results << report(Result.new(mutation: entry[:item].mutation, status: :timeout, details: nil))
+          entry[:stderr_file].close!
+          details = format("timed out after %.1fs (budget %.1fs)", now - entry[:started], entry[:budget])
+          results << report(Result.new(mutation: entry[:item].mutation, status: :timeout, details: details))
         end
       end
     end
@@ -104,13 +114,14 @@ module ActiveMutator
     def finish(entry)
       payload = entry[:reader].read.to_s
       entry[:reader].close
+      stderr_tail = stderr_tail(entry[:stderr_file])
       data = payload.empty? ? nil : JSON.parse(payload)
       # 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"
+      details = reported ? data["details"] : unreported_details(stderr_tail)
     rescue JSON::ParserError
       report(Result.new(mutation: entry[:item].mutation, status: :error,
                         details: "worker emitted unparseable payload"))
@@ -123,6 +134,20 @@ module ActiveMutator
       result
     end
 
+    # The child wrote through its own descriptor (reopened by path), so this
+    # handle is still at offset 0: no rewind needed.
+    def stderr_tail(file)
+      file.read.to_s.lines.last(STDERR_TAIL_LINES).join.strip
+    ensure
+      file.close!
+    end
+
+    def unreported_details(stderr_tail)
+      return "worker exited without reporting" if stderr_tail.empty?
+
+      "worker exited without reporting; stderr tail:\n#{stderr_tail}"
+    end
+
     def kill(pid)
       Process.kill("KILL", -pid) # negative pid = whole process group
     rescue Errno::ESRCH, Errno::EPERM

data/lib/active_mutator/since_filter.rb

@@ -20,6 +20,15 @@ module ActiveMutator
       changed.reject { |_, lines| lines.empty? }
     end
 
+    # Every file the diff touched on the new side, including deletion-only
+    # files that `parse` drops (they add no lines, so nothing to cover, but
+    # the file still changed and must count as a --since candidate).
+    def self.touched_files(diff_text)
+      diff_text.each_line.filter_map do |line|
+        line.delete_prefix("+++ b/").strip if line.start_with?("+++ b/")
+      end.uniq
+    end
+
     def initialize(ref:, root:)
       @root = root
       diff = IO.popen(
@@ -28,15 +37,22 @@ module ActiveMutator
       raise Error, "git diff #{ref} failed" unless $?.success?
 
       @changed = self.class.parse(diff)
+      @touched = self.class.touched_files(diff)
       untracked = IO.popen(
         ["git", "-C", root, "ls-files", "--others", "--exclude-standard", "--", "*.rb"], &:read
       )
       # Untracked files are invisible to `git diff` but are agentic TDD's most
       # common case (brand-new file + spec). Whole-file sentinel: every line
       # counts as changed.
-      untracked.each_line { |l| @changed[l.strip] = :all unless l.strip.empty? }
+      untracked.split("\n").each { |l| @changed[l] = :all }
+      @touched |= @changed.keys
     end
 
+    # Root-relative paths of every .rb file the diff touched (tracked files,
+    # including deletion-only ones, plus untracked files). Pure accessor: no
+    # further git calls.
+    def changed_files = @touched
+
     def cover?(subject)
       lines = @changed[subject.file.delete_prefix("#{@root}/")]
       return false unless lines

data/lib/active_mutator/subject.rb

@@ -5,13 +5,18 @@ module ActiveMutator
   # class/module node; Engine only mutates non-def body statements).
   # sclass: def lives inside `class << self` — its source slice is `def foo`,
   # so Inserter must target the singleton class, not the constant itself.
-  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind, :sclass) do
-    def initialize(name:, file:, byte_range:, line_range:, constant_scope:, kind:, sclass: false)
+  # reload: def lives inside a concern's `included`/`prepended` block, so it
+  # lands on the includer, not on the constant; the only faithful insertion is
+  # the same whole-file closure reload a class-body mutant gets.
+  Subject = Data.define(:name, :file, :byte_range, :line_range, :constant_scope, :kind, :sclass, :reload) do
+    def initialize(name:, file:, byte_range:, line_range:, constant_scope:, kind:, sclass: false, reload: false)
       super
     end
 
     def singleton? = kind == :singleton
 
     def class_body? = kind == :class_body
+
+    def reload? = class_body? || reload
   end
 end

data/lib/active_mutator/subject_finder.rb

@@ -79,6 +79,31 @@ module ActiveMutator
     def visit_block_node(node); end
 
     def visit_def_node(node)
+      add_def_subject(node)
+      # No `super`: nested defs get no subject of their own -- their bodies
+      # are mutated via the OUTER def (Engine#walk descends into them).
+    end
+
+    # ActiveSupport::Concern blocks are the exception to visit_block_node.
+    # `class_methods do` is module_eval'd into `Scope::ClassMethods`, so its
+    # defs are plain subjects on that constant, exactly as if written in
+    # `module ClassMethods`. `included`/`prepended` defs land on the includer,
+    # which Inserter cannot target; they are reload subjects (whole-file
+    # closure reload), which needs the same Zeitwerk-shape gate as class-body
+    # subjects.
+    def visit_call_node(node)
+      return super unless @sclass_depth.zero? && !@stack.empty? && ClassShape.concern_dsl_block?(node)
+
+      if node.name == :class_methods
+        with_scope("ClassMethods") { each_concern_def(node.block.body) { |d| add_def_subject(d) } }
+      elsif @class_level
+        each_concern_def(node.block.body) { |d| add_def_subject(d, reload: true) }
+      end
+    end
+
+    private
+
+    def add_def_subject(node, reload: false)
       return if @skip_lines.include?(node.location.start_line - 1)
 
       sclass = @sclass_depth.positive?
@@ -92,13 +117,20 @@ module ActiveMutator
         line_range: loc.start_line..loc.end_line,
         constant_scope: scope,
         kind: singleton ? :singleton : :instance,
-        sclass: sclass
+        sclass: sclass,
+        reload: reload
       )
-      # 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
+    def each_concern_def(node, &blk)
+      return if node.nil?
+
+      if node.is_a?(Prism::DefNode)
+        yield node
+      elsif !ClassShape.concern_def_boundary?(node)
+        node.compact_child_nodes.each { |child| each_concern_def(child, &blk) }
+      end
+    end
 
     # 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

data/lib/active_mutator/version.rb

@@ -1,3 +1,3 @@
 module ActiveMutator
-  VERSION = "0.4.1"
+  VERSION = "0.6.0"
 end

data/lib/active_mutator/worker.rb

@@ -43,7 +43,7 @@ module ActiveMutator
       require "rspec/core"
       devnull = File.open(File::NULL, "w")
       runner = RSpec::Core::Runner.new(RSpec::Core::ConfigurationOptions.new(@example_ids))
-      if @mutation.subject.class_body?
+      if @mutation.subject.reload?
         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
@@ -70,9 +70,10 @@ module ActiveMutator
     private
 
     # Def mutants class_eval over the live constant; class-body mutants
-    # cannot (macros accumulate) and go through whole-file closure reload.
+    # cannot (macros accumulate) and go through whole-file closure reload, as
+    # do defs inside `included`/`prepended` blocks (they live on the includer).
     def insert_mutation
-      if @mutation.subject.class_body?
+      if @mutation.subject.reload?
         ClosureReload.new(@mutation.subject, @mutation.mutated_file_source).call
       else
         Inserter.new.insert(@mutation)

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_mutator
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel John
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -62,7 +61,6 @@ description: Mutation testing for Ruby and Rails. Uses Prism-based source-span m
   (no unparser), coverage-mapped test selection, and a fork-per-mutant kill pipeline.
   Scopes to changed methods for a fast dev loop, or to a diff for CI. Includes an
   incremental coverage baseline and a committed acceptance ledger for equivalent mutants.
-email:
 executables:
 - active_mutator
 extensions: []
@@ -125,7 +123,6 @@ metadata:
   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
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -140,8 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Mutation testing for Ruby, built on Prism
 test_files: []