active_mutator 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08222e2342f45fd4c9150cd9201383231f1add08c5c5582bccf74f4350c87181'
-  data.tar.gz: ae88865c407500e7b7fcc0cb9a0ab72fe90aa2860136f9bd523203a1baae9c35
+  metadata.gz: 0c97d4e4b28fb22f07d54f258e65162b4a4e9c731ab89caa851610e1ff3d1a83
+  data.tar.gz: dfd2fdddc29f209281e45001ae7a21bd6d75fce6833a5f4086f3592d36378843
 SHA512:
-  metadata.gz: c0ed008b82b47bf0e70e74bd51330eafaeb02f6c7241e5a19e2a75395293db1ccf02e3f13f3810abf2da1972f5b50b678e35bae4efb946b139aac22e0faccfd0
-  data.tar.gz: dd02830ae6b56cdc687cf90dc5131d1409298ac8e5d03217a57f92a044aca4dee6731043498e1f021d9eee4ef064af8cab80fb048263046dfe28fe719bef0077
+  metadata.gz: 983e510da62ef0a31abefd1342485e17a365013ce13eb16b9ad3a1b929ca5ff13c643c15ae9529c6b0def30215268b1a2c424d102489f4351d27b2c9cddd2ca1
+  data.tar.gz: 272643ac14e46cfba0e0ea95d4b9fe4cedc7ace3b7359eaabdf7bed60a8caf2451f84ba3986828f9528dfe402e9fe1fe4d9b20d7daa63f842ec728ebfb4ef2af

data/README.md

@@ -258,6 +258,7 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
 | `--force-baseline` | off | ignore cached coverage map |
 | `--preload-helper FILE` / `--no-preload-helper` | auto-detect | parent spec-helper preload |
 | `--serial-pattern PAT` | `spec/system/`, `spec/features/` | covering-path prefixes forced serial |
+| `--spec-path DIR` | `spec/` | where spec files live, relative to the project root (repeatable; the first use replaces the default `spec/`), e.g. `--spec-path engines/billing/spec --spec-path spec` |
 | `--browser-boot-seconds S` | 15 | serial-lane timeout bump |
 | `--timeout-factor F` / `--timeout-floor S` | 8 / 10 | mutation timeout budget |
 | `--[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) |
@@ -266,6 +267,14 @@ survivors show inline on the PR diff. Pairs with the CI recipe:
 | `--[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) |
 
+`--spec-path` tells active_mutator where spec files live (coverage
+classification, digests, escalation); RSpec's own discovery is still the
+project's job — a project with specs under `test/` also needs
+`--default-path test` in its `.rspec`. The serial-lane defaults stay
+`spec/system/` and `spec/features/` regardless of `--spec-path`; a
+custom spec root with browser specs should set `--serial-pattern`
+(e.g. `--serial-pattern test/system/`) itself.
+
 `--debug-plan` prints the planned mutant list as one JSON document
 (`{"planned": [...], "pre_resolved": {...}}`) and exits without running
 anything. A coverage baseline is still built or loaded, since timeouts
@@ -285,6 +294,8 @@ flags override file values (`--require` and `--exclude` add to the file's
 lists; the first `--serial-pattern` replaces them). Recognized keys:
 `jobs`, `format`, `timeout_factor`, `timeout_floor`,
 `browser_boot_seconds`, `fail_at`, `exclude`, `serial_patterns`,
+`spec_paths` (where spec files live, relative to the project root;
+replaces the default `spec`),
 `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),
@@ -301,6 +312,9 @@ exclude:
   - lib/generated
 serial_patterns:
   - spec/system/
+spec_paths:
+  - engines/billing/spec
+  - spec
 fail_at: 90   # legacy suite: gate on score instead of zero-survivors
 ```
 

data/lib/active_mutator/baseline.rb

@@ -5,10 +5,11 @@ require "json"
 module ActiveMutator
   # Runs the host suite once, instrumented, in a subprocess. Produces and
   # caches the CoverageMap. Invalidation is coarse: any digest change in
-  # {app,lib,spec}/**/*.rb triggers a full re-run.
+  # {app,lib}/**/*.rb or the configured spec paths triggers a full re-run.
   class Baseline
-    def initialize(root:, cache_dir: File.join(root, ".active_mutator"))
+    def initialize(root:, spec_paths: ["spec"], cache_dir: File.join(root, ".active_mutator"))
       @root = root
+      @spec_paths = spec_paths
       @cache_dir = cache_dir
       @out_path = File.join(cache_dir, "coverage.json")
     end
@@ -19,13 +20,19 @@ module ActiveMutator
       digests = current_digests
       if !force && File.exist?(@out_path)
         map = CoverageMap.load(@out_path)
-        if map.fresh?(digests)
+        # A spec_paths change silently degrades the delta classifier: files
+        # under a removed spec path just vanish from the digest scan, so
+        # BaselineDelta treats their stale example records as untouched
+        # source coverage instead of dropping them. Force a full rebuild
+        # whenever the configured spec_paths differ from what the cache was
+        # stamped with.
+        if stored_spec_paths(map) == @spec_paths && map.fresh?(digests)
           @last_refresh = :cached
           return map
         end
-        if map.version == 2
+        if stored_spec_paths(map) == @spec_paths && map.version == 2
           delta = BaselineDelta.compute(old_digests: stored_digests(map), new_digests: digests,
-                                        coverage_map: map, root: @root)
+                                        coverage_map: map, root: @root, spec_paths: @spec_paths)
           unless delta.full?
             run_partial!(delta)
             stamp_digests(digests)
@@ -59,6 +66,25 @@ module ActiveMutator
       ok = system(env, "bundle", "exec", "rspec", chdir: @root, out: :err)
       raise BaselineFailed, "baseline suite failed, fix the suite before mutating" unless ok
       raise BaselineFailed, "baseline produced no coverage output" unless File.exist?(@out_path)
+
+      verify_complete!(@out_path)
+    end
+
+    # An aborted subprocess can still exit 0 with a partial map (RSpec
+    # rescues Errno::EPIPE and runs after(:suite)); stamping that as fresh
+    # silently reports every mutant uncovered. Payloads without the count
+    # predate this check and are accepted as-is.
+    def verify_complete!(out_path)
+      payload = JSON.parse(File.read(out_path))
+      expected = payload["expected_examples"]
+      return unless expected
+
+      recorded = payload.fetch("records", {}).size
+      return if recorded >= expected
+
+      raise BaselineFailed,
+            "baseline aborted early: #{recorded} of #{expected} examples recorded — " \
+            "re-run without interrupting the suite"
     end
 
     def baseline_env(out_path)
@@ -66,6 +92,7 @@ module ActiveMutator
         "ACTIVE_MUTATOR" => "1",
         "ACTIVE_MUTATOR_ROOT" => @root,
         "ACTIVE_MUTATOR_BASELINE_OUT" => out_path,
+        "ACTIVE_MUTATOR_SPEC_PATHS" => @spec_paths.join(":"),
         # RUBYOPT, not `rspec --require`: project .rspec requires (spec_helper
         # → app code) run before command-line requires, and Coverage misses
         # everything loaded before Coverage.start. -r fires before rspec boots.
@@ -83,6 +110,12 @@ module ActiveMutator
       JSON.parse(File.read(@out_path)).fetch("digests", {})
     end
 
+    # A pre-0.4.0 cache predates spec_paths and has no key; treat that as the
+    # old implicit default so existing default-config caches stay valid.
+    def stored_spec_paths(map)
+      JSON.parse(File.read(@out_path)).fetch("spec_paths", ["spec"])
+    end
+
     def run_partial!(delta)
       targets = delta.rerun_spec_files + delta.rerun_example_ids
       partial_out = File.join(@cache_dir, "partial.json")
@@ -91,6 +124,8 @@ module ActiveMutator
         ok = system(env, "bundle", "exec", "rspec", *targets, chdir: @root, out: :err)
         raise BaselineFailed, "partial baseline run failed, fix the suite before mutating" unless ok
         raise BaselineFailed, "partial baseline produced no output" unless File.exist?(partial_out)
+
+        verify_complete!(partial_out)
       end
       merge_partial!(partial_out, delta)
     ensure
@@ -122,11 +157,14 @@ module ActiveMutator
     def stamp_digests(digests)
       data = JSON.parse(File.read(@out_path))
       data["digests"] = digests
+      data["spec_paths"] = @spec_paths
       AtomicFile.write(@out_path, JSON.generate(data))
     end
 
     def current_digests
-      files = Dir[File.join(@root, "{app,lib,spec}/**/*.rb")].sort
+      files = Dir[File.join(@root, "{app,lib}/**/*.rb")]
+      files += @spec_paths.flat_map { |sp| Dir[File.join(@root, sp, "**", "*.rb")] }
+      files = files.uniq.sort
       files += [File.join(@root, "Gemfile.lock"), File.join(@root, ".rspec")].select { |f| File.exist?(f) }
       files.to_h { |f| [f.delete_prefix("#{@root}/"), Digest::SHA256.file(f).hexdigest] }
     end

data/lib/active_mutator/baseline_delta.rb

@@ -15,10 +15,10 @@ module ActiveMutator
     # files, a full re-run is cheaper and simpler than a giant partial one.
     REFERENCE_FULL_RATIO = 0.5
 
-    def self.compute(old_digests:, new_digests:, coverage_map:, root:)
+    def self.compute(old_digests:, new_digests:, coverage_map:, root:, spec_paths: ["spec"])
       changed = (old_digests.keys | new_digests.keys)
                 .reject { |k| old_digests[k] == new_digests[k] }
-      return FULL if changed.any? { |k| full_trigger?(k) }
+      return FULL if changed.any? { |k| full_trigger?(k, spec_paths: spec_paths) }
 
       rerun_spec_files = []
       rerun_example_ids = []
@@ -35,7 +35,7 @@ module ActiveMutator
       changed.each do |rel|
         added = !old_digests.key?(rel)
         deleted = !new_digests.key?(rel)
-        if rel.start_with?("spec/")
+        if spec_paths.any? { |sp| rel.start_with?("#{sp}/") }
           owned = coverage_map.examples_for_spec_file(rel)
           if deleted
             # A deleted spec file with no records is support-like: other spec
@@ -54,7 +54,7 @@ module ActiveMutator
             rerun_example_ids.concat(coverage_map.examples_covering_file(abs))
           end
           unless deleted
-            spec_contents ||= Dir[File.join(root, "spec/**/*_spec.rb")].to_h { |f| [f, File.read(f)] }
+            spec_contents ||= spec_file_contents(root: root, spec_paths: spec_paths)
             candidates = newly_covering_candidates(root: root, rel: rel, coverage_map: coverage_map,
                                                    spec_contents: spec_contents)
             return FULL if candidates == :full
@@ -71,8 +71,17 @@ module ActiveMutator
                 drop_source_files: drop_source_files.uniq.sort)
     end
 
-    def self.full_trigger?(rel)
-      rel.start_with?("spec/support/") || !rel.end_with?(".rb")
+    def self.full_trigger?(rel, spec_paths: ["spec"])
+      spec_paths.any? { |sp| rel.start_with?("#{sp}/support/") } || !rel.end_with?(".rb")
+    end
+
+    # All *_spec.rb files under the configured spec paths, absolute path =>
+    # file content. Shared by the delta scan and Runner's phase-2 escalation
+    # so "where do specs live" is answered in exactly one place (#35).
+    def self.spec_file_contents(root:, spec_paths:)
+      spec_paths
+        .flat_map { |sp| Dir[File.join(root, sp, "**", "*_spec.rb")] }
+        .uniq.to_h { |f| [f, File.read(f)] }
     end
 
     # #11: an unchanged spec file can START covering a changed source file

data/lib/active_mutator/baseline_hooks.rb

@@ -9,7 +9,8 @@ module ActiveMutator
     RECORDS = {}
     TIMES = {}
 
-    def self.diff_coverage(before, after, root)
+    def self.diff_coverage(before, after, root, spec_paths: ["spec"])
+      prefixes = spec_paths.map { |sp| "/#{sp}/" }
       hits = []
       after.each do |path, data|
         next unless path.start_with?(root)
@@ -19,7 +20,7 @@ module ActiveMutator
         # spec/fixtures/ tree), which would otherwise falsely exclude every
         # file under it.
         relative = path.delete_prefix(root)
-        next if relative.start_with?("/spec/")
+        next if prefixes.any? { |p| relative.start_with?(p) }
 
         before_lines = before.dig(path, :lines)
         data[:lines].each_with_index do |count, idx|
@@ -32,8 +33,10 @@ module ActiveMutator
       hits
     end
 
-    def self.build_payload(records, times)
-      { "version" => 2, "records" => records, "times" => times }
+    def self.build_payload(records, times, expected_examples: nil)
+      payload = { "version" => 2, "records" => records, "times" => times }
+      payload["expected_examples"] = expected_examples if expected_examples
+      payload
     end
   end
 end
@@ -51,16 +54,22 @@ if ENV["ACTIVE_MUTATOR_BASELINE_OUT"]
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
       after = Coverage.peek_result
       root = ENV.fetch("ACTIVE_MUTATOR_ROOT")
+      spec_paths = ENV.fetch("ACTIVE_MUTATOR_SPEC_PATHS", "spec").split(":")
       ActiveMutator::BaselineHooks::RECORDS[example.id] =
-        ActiveMutator::BaselineHooks.diff_coverage(before, after, root)
+        ActiveMutator::BaselineHooks.diff_coverage(before, after, root, spec_paths: spec_paths)
       # NOT example.execution_result.run_time: that is nil until after
       # around hooks complete.
       ActiveMutator::BaselineHooks::TIMES[example.id] = elapsed
     end
 
     config.after(:suite) do
+      # The expected count lets the parent detect an aborted run: RSpec
+      # swallows some mid-suite failures (e.g. Errno::EPIPE on a closed
+      # stdout) yet still runs after(:suite) and exits 0, which would stamp
+      # a partial coverage map as a fresh, trusted baseline.
       payload = ActiveMutator::BaselineHooks.build_payload(
-        ActiveMutator::BaselineHooks::RECORDS, ActiveMutator::BaselineHooks::TIMES
+        ActiveMutator::BaselineHooks::RECORDS, ActiveMutator::BaselineHooks::TIMES,
+        expected_examples: RSpec.world.example_count
       )
       File.write(ENV.fetch("ACTIVE_MUTATOR_BASELINE_OUT"), JSON.generate(payload))
     end

data/lib/active_mutator/cli.rb

@@ -3,6 +3,13 @@ require "optparse"
 module ActiveMutator
   module CLI
     def self.run(argv)
+      # Handled before OptionParser: its built-in --version handler prints
+      # "version unknown" and exits the process.
+      if argv.include?("--version")
+        puts "active_mutator #{VERSION}"
+        return 0
+      end
+
       Runner.new(parse(argv)).call
     rescue OptionParser::ParseError, Error => e
       warn "active_mutator: #{e.message}"
@@ -22,6 +29,7 @@ module ActiveMutator
         # boot cost (RSpec setup + spec file loading).
         requires: [], timeout_factor: 8.0, timeout_floor: 10.0, force_baseline: false,
         preload_helper: nil, serial_patterns: ["spec/system/", "spec/features/"],
+        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
@@ -47,6 +55,11 @@ module ActiveMutator
           options[:serial_patterns_replaced] = true
           options[:serial_patterns] << v
         end
+        o.on("--spec-path DIR", "Directory holding spec files, relative to root (repeatable; replaces the default spec/ on first use)") do |v|
+          options[:spec_paths] = [] unless options[:spec_paths_replaced]
+          options[:spec_paths_replaced] = true
+          options[:spec_paths] << v
+        end
         o.on("--browser-boot-seconds S", Float, "Extra timeout budget for serial-lane mutants") { |v| options[:browser_boot_seconds] = v }
         o.on("--[no-]adaptive-timeout", "Scale timeout budgets from observed worker wall times (default: on)") { |v| options[:adaptive_timeout] = v }
         o.on("--accept-survivors", "Record surviving mutants into the acceptance ledger") { options[:accept_survivors] = true }
@@ -59,6 +72,12 @@ module ActiveMutator
         end
       end.parse(argv)
       options.delete(:serial_patterns_replaced)
+      options.delete(:spec_paths_replaced)
+      options[:spec_paths] = options[:spec_paths].map { |sp| sp.sub(%r{/+\z}, "") }
+      raise OptionParser::InvalidArgument, "--spec-path list must not be empty" if options[:spec_paths].empty?
+      if options[:spec_paths].any? { |sp| sp.strip.empty? }
+        raise OptionParser::InvalidArgument, "--spec-path entries must not be blank"
+      end
 
       Config.new(paths: paths, root: Dir.pwd, **options)
     end

data/lib/active_mutator/config.rb

@@ -3,7 +3,8 @@ require "etc"
 module ActiveMutator
   Config = Data.define(:paths, :since, :subject_filter, :jobs, :format, :requires,
                        :timeout_factor, :timeout_floor, :force_baseline, :root,
-                       :preload_helper, :serial_patterns, :browser_boot_seconds,
+                       :preload_helper, :serial_patterns, :spec_paths,
+                       :browser_boot_seconds,
                        :accept_survivors, :exclude, :max_mutants, :debug_plan,
                        :fail_at, :adaptive_timeout, :operators,
                        :class_level, :class_level_closure_cap)

data/lib/active_mutator/config_file.rb

@@ -19,6 +19,7 @@ module ActiveMutator
       "fail_at" => :score,
       "exclude" => :string_list,
       "serial_patterns" => :string_list,
+      "spec_paths" => :nonempty_string_list,
       "requires" => :string_list,
       "operators" => :string_list,
       "preload_helper" => :preload_helper,
@@ -75,6 +76,12 @@ module ActiveMutator
           raise Error, "#{FILENAME}: #{key} must be a list of strings"
         end
         value
+      when :nonempty_string_list
+        unless value.is_a?(Array) && value.all?(String)
+          raise Error, "#{FILENAME}: #{key} must be a list of strings"
+        end
+        raise Error, "#{FILENAME}: #{key} must not be empty" if value.empty?
+        value
       when :boolean
         unless [true, false].include?(value)
           raise Error, "#{FILENAME}: #{key} must be true or false"

data/lib/active_mutator/runner.rb

@@ -13,7 +13,8 @@ module ActiveMutator
       ClosureReload.cap = @config.class_level_closure_cap
       preload!
       preload_spec_helper!
-      map = Baseline.new(root: @config.root).coverage_map(force: @config.force_baseline)
+      map = Baseline.new(root: @config.root, spec_paths: @config.spec_paths)
+              .coverage_map(force: @config.force_baseline)
       @reporter.coverage_map = map if @reporter.respond_to?(:coverage_map=)
       subjects = discover_subjects
       analyses = subjects.map { |s| Engine.new.analyze(s) }
@@ -86,7 +87,7 @@ module ActiveMutator
       # 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)] }
+      spec_contents = BaselineDelta.spec_file_contents(root: @config.root, spec_paths: @config.spec_paths)
       patterns = {} # subject file => constant-reference pattern (parsed once per file)
       items = {}
       candidates.each do |r|
@@ -200,14 +201,15 @@ module ActiveMutator
     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
+      convention_examples = convention_spec_rels(mutation.subject.file)
+                            .flat_map { |rel| map.examples_for_spec_file(rel) }
+      (map.examples_covering_file(mutation.subject.file) | convention_examples).sort
     end
 
-    def convention_spec_rel(file)
+    def convention_spec_rels(file)
       rel = file.delete_prefix(@config.root.chomp("/") + "/").delete_suffix(".rb")
       rest = rel.sub(%r{\A[^/]+/}, "")
-      "spec/#{rest}_spec.rb"
+      @config.spec_paths.map { |sp| "#{sp}/#{rest}_spec.rb" }
     end
 
     def build_reporter
@@ -293,7 +295,11 @@ module ActiveMutator
       helper = if @config.preload_helper
                  File.expand_path(@config.preload_helper, @config.root)
                else
-                 %w[spec/rails_helper.rb spec/spec_helper.rb]
+                 # Precedence: within each spec path rails_helper wins over
+                 # spec_helper; earlier spec paths win over later ones — same
+                 # as today for the default ["spec"].
+                 @config.spec_paths
+                   .flat_map { |sp| ["#{sp}/rails_helper.rb", "#{sp}/spec_helper.rb"] }
                    .map { |p| File.join(@config.root, p) }
                    .find { |p| File.exist?(p) }
                end

data/lib/active_mutator/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_mutator
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Daniel John
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-30 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism