evilution 1.1.0 → 1.3.0

data/lib/evilution/ast/pattern/parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../pattern"
 require_relative "matcher"
 
 class Evilution::AST::Pattern::Parser

data/lib/evilution/ast/pattern.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../ast"
+
 module Evilution::AST::Pattern
 end

data/lib/evilution/ast/sorbet_sig_detector.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "prism"
+require_relative "../ast"
 
 class Evilution::AST::SorbetSigDetector
   def call(source)

data/lib/evilution/baseline.rb

@@ -15,13 +15,24 @@ class Evilution::Baseline
     end
   end
 
+  # spec_selector: the object `run` resolves with (integration layout plus
+  # spec_mappings / spec_pattern), returning every spec covering a source.
+  # Without one, the bare spec_resolver is used. spec_resolver also supplies
+  # the best-guess hint for an unresolved source.
+  #
+  # fallback_to_full_suite: whether an unresolved source runs the whole
+  # fallback_dir. When false its mutations are reported unresolved, so the
+  # baseline skips it rather than running -- and often timing out on -- the
+  # entire test directory.
   def initialize(spec_resolver: Evilution::SpecResolver.new, timeout: 30, runner: nil,
-                 fallback_dir: "spec", test_files: nil)
+                 fallback_dir: "spec", test_files: nil, spec_selector: nil, fallback_to_full_suite: true)
     @spec_resolver = spec_resolver
     @timeout = timeout
     @runner = runner
     @fallback_dir = fallback_dir
     @test_files = test_files
+    @spec_selector = spec_selector
+    @fallback_to_full_suite = fallback_to_full_suite
   end
 
   def call(subjects)
@@ -43,7 +54,7 @@ class Evilution::Baseline
     read_io, write_io = IO.pipe
     pid = fork_spec_runner(spec_file, read_io, write_io)
     write_io.close
-    read_result(read_io, pid)
+    read_result(read_io, pid, spec_file)
   rescue Evilution::Error
     raise
   rescue StandardError
@@ -69,7 +80,7 @@ class Evilution::Baseline
 
   GRACE_PERIOD = 0.5
 
-  def read_result(read_io, pid)
+  def read_result(read_io, pid, spec_file)
     if read_io.wait_readable(@timeout)
       data = read_io.read
       Process.wait(pid)
@@ -79,10 +90,15 @@ class Evilution::Baseline
       result[:passed]
     else
       terminate_child(pid)
+      warn_timeout(spec_file)
       false
     end
   end
 
+  def warn_timeout(spec_file)
+    warn "[evilution] Baseline for #{spec_file} timed out after #{@timeout}s; treating it as failing."
+  end
+
   def terminate_child(pid)
     Evilution::ProcessCleanup.safe_kill("TERM", pid)
     _, status = Process.waitpid2(pid, Process::WNOHANG)
@@ -98,11 +114,6 @@ class Evilution::Baseline
 
   private
 
-  # When --spec was provided, run those files only. Auto-discovery is skipped
-  # entirely — the user has declared what covers their subjects and any
-  # mismatch between auto-discovery and their declaration is what produced
-  # the misleading "No matching test found" warning users have reported even
-  # while passing --spec.
   def baseline_spec_files(subjects)
     return Array(@test_files).uniq if @test_files && !@test_files.empty?
 
@@ -111,20 +122,31 @@ class Evilution::Baseline
 
   def resolve_unique_spec_files(subjects)
     warned = Set.new
-    subjects.map do |s|
-      resolved = @spec_resolver.call(s.file_path)
-      warn_no_matching_test(s.file_path) if resolved.nil? && warned.add?(s.file_path)
-      resolved || @fallback_dir
+    subjects.flat_map do |s|
+      specs = specs_for(s.file_path)
+      next specs unless specs.empty?
+
+      warn_no_matching_test(s.file_path) if warned.add?(s.file_path)
+      @fallback_to_full_suite ? [@fallback_dir] : []
     end.uniq
   end
 
+  def specs_for(file_path)
+    Array(@spec_selector ? @spec_selector.call(file_path) : @spec_resolver.call(file_path))
+  end
+
   def warn_no_matching_test(file_path)
+    action = @fallback_to_full_suite ? "running full suite" : "marking its mutations unresolved"
+    warn "[evilution] No matching test found for #{file_path}, #{action}. #{no_match_hint(file_path)}"
+  end
+
+  def no_match_hint(file_path)
     suggestion = @spec_resolver.suggest(file_path)
     hint = if suggestion
-             "Pass --spec #{suggestion} (best guess) or the correct test file."
+             "Pass --spec #{suggestion} (best guess) or the correct test file"
            else
-             "Use --spec to specify the test file."
+             "Use --spec to specify the test file"
            end
-    warn "[evilution] No matching test found for #{file_path}, running full suite. #{hint}"
+    @fallback_to_full_suite ? "#{hint}." : "#{hint}, or --fallback-full-suite to run the whole suite."
   end
 end

data/lib/evilution/child_output.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../evilution"
+require_relative "version"
 
 module Evilution::ChildOutput
   module_function

data/lib/evilution/cli/command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../cli"
 require_relative "result"
 
 class Evilution::CLI::Command

data/lib/evilution/cli/commands/tests_list.rb

@@ -5,7 +5,6 @@ require_relative "../command"
 require_relative "../dispatcher"
 require_relative "../printers/tests_list"
 require_relative "../../config"
-require_relative "../../spec_resolver"
 require_relative "../../git/changed_files"
 
 class Evilution::CLI::Commands::TestsList < Evilution::CLI::Command
@@ -25,8 +24,10 @@ class Evilution::CLI::Commands::TestsList < Evilution::CLI::Command
       return 0
     end
 
-    resolver = Evilution::SpecResolver.new
-    entries = source_files.map { |source| { source: source, spec: resolver.call(source) } }
+    # The same selector `run` uses: the integration's test layout (test/*_test.rb
+    # for minitest and test-unit) plus spec_mappings and spec_pattern, so the
+    # two commands cannot disagree about which specs cover a source (GH #1596).
+    entries = source_files.map { |source| { source: source, specs: Array(config.spec_selector.call(source)) } }
     Evilution::CLI::Printers::TestsList.new(mode: :resolved, entries: entries).render(@stdout)
     0
   end

data/lib/evilution/cli/commands.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../cli"
+
 module Evilution::CLI::Commands
 end

data/lib/evilution/cli/dispatcher.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../cli"
+
 module Evilution::CLI::Dispatcher
   @commands = {}
 

data/lib/evilution/cli/exit_guard.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../cli"
+
+# Gives evilution the final word on the process exit status.
+#
+# `--preload` loads the project's own spec helper into the parent process, and
+# whatever that helper installs comes along with it. SimpleCov's at_exit hook
+# calls `exit` with its own status when coverage is below the configured
+# minimum, which replaces the status evilution computed and breaks a CI step
+# reading it (EV-g8ya / GH #1608).
+#
+# at_exit hooks run last-registered-first, so a hook installed before the
+# preload is the last one standing. It exits with `exit!`, which is immediate
+# and cannot be overridden by anything left in the queue — by then every other
+# hook, evilution's own temp-directory cleanup included, has already run.
+#
+# With no status recorded, evilution did not finish normally: an exception is on
+# its way out, and Ruby's own handling decides the status instead.
+#
+# The hook belongs to the process that installed it. Evilution forks workers,
+# and a fork inherits its parent's at_exit hooks; a worker running this one
+# would exit with the parent's status and skip its own ending. The guard
+# therefore remembers its process and stands down anywhere else.
+class Evilution::CLI::ExitGuard
+  attr_accessor :status
+
+  def initialize(register: nil, exiter: nil, pid_source: nil, streams: nil)
+    @register = register || ->(&hook) { at_exit(&hook) }
+    @exiter = exiter || ->(code) { exit!(code) }
+    @streams = streams || -> { [$stdout, $stderr] }
+    @pid_source = pid_source || -> { Process.pid }
+    @status = nil
+  end
+
+  def install
+    @pid = @pid_source.call
+    @register.call { fire }
+    self
+  end
+
+  private
+
+  def fire
+    return if @status.nil?
+    return unless @pid_source.call == @pid
+
+    flush_streams
+    @exiter.call(@status)
+  end
+
+  # `exit!` leaves buffered output where it stands, so anything written by the
+  # report, or by a hook that ran before this one, has to be pushed out first.
+  def flush_streams
+    @streams.call.each do |stream|
+      stream.flush
+    rescue IOError, Errno::EBADF
+      nil
+    end
+  end
+end

data/lib/evilution/cli/parsed_args.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../cli"
+
 class Evilution::CLI
   ParsedArgs = Struct.new(
     :command, :options, :files, :line_ranges, :stdin_error, :parse_error,

data/lib/evilution/cli/parser/command_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../parser"
+
 class Evilution::CLI::Parser::CommandExtractor
   SIMPLE_COMMANDS = {
     "version" => :version,

data/lib/evilution/cli/parser/file_args.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../parser"
+
 module Evilution::CLI::Parser::FileArgs
   ParsedPaths = Data.define(:files, :ranges)
 

data/lib/evilution/cli/parser/options_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "optparse"
+require_relative "../parser"
 require_relative "../../version"
 require_relative "file_args"
 
@@ -55,6 +56,7 @@ class Evilution::CLI::Parser::OptionsBuilder
 
   def add_spec_filter_options(opts)
     opts.on("--min-score FLOAT", Float, "Minimum mutation score to pass") { |s| @options[:min_score] = s }
+    opts.on("--output FILE", "Write the report to FILE instead of stdout") { |f| @options[:output] = f }
     opts.on("--spec FILES", Array, "Spec files to run (comma-separated)") { |f| @options[:spec_files] = f }
     opts.on("--spec-dir DIR", "Include all specs in DIR") { |d| expand_spec_dir(d) }
     opts.on("--spec-pattern GLOB",
@@ -118,6 +120,8 @@ class Evilution::CLI::Parser::OptionsBuilder
                               "(default: auto-detect spec/rails_helper.rb -> spec/spec_helper.rb -> " \
                               "test/test_helper.rb for Rails projects)") { |f| @options[:preload] = f }
     opts.on("--no-preload", "Disable parent-process preload even for Rails projects") { @options[:preload] = false }
+    opts.on("--warmup NAME", "After preload, warm lazily-initialised framework state once " \
+                             "in the parent: none, rails (default: none)") { |w| @options[:warmup] = w }
   end
 
   def add_output_options(opts)

data/lib/evilution/cli/parser/stdin_reader.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../parser"
 require_relative "file_args"
 
 class Evilution::CLI::Parser::StdinReader

data/lib/evilution/cli/parser.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../cli"
 require_relative "parsed_args"
 
 class Evilution::CLI::Parser

data/lib/evilution/cli/printers/tests_list.rb

@@ -24,16 +24,17 @@ class Evilution::CLI::Printers::TestsList
     io.puts(@specs.length == 1 ? "1 spec file" : "#{@specs.length} spec files")
   end
 
+  # Each entry is `{ source:, specs: [...] }`; a source can resolve to several
+  # spec files (spec_mappings), and each gets its own line.
   def render_resolved(io)
     unique_specs = []
     @entries.each do |entry|
       source = entry[:source]
-      spec = entry[:spec]
-      if spec
+      specs = entry[:specs]
+      io.puts("  #{source}  (no spec found)") if specs.empty?
+      specs.each do |spec|
         unique_specs << spec
         io.puts("  #{spec}  (#{source})")
-      else
-        io.puts("  #{source}  (no spec found)")
       end
     end
 

data/lib/evilution/cli/printers.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../cli"
+
 module Evilution::CLI::Printers
 end

data/lib/evilution/cli/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../cli"
+
 class Evilution::CLI
   Result = Struct.new(:exit_code, :error, :error_rendered, keyword_init: true) do
     def initialize(exit_code:, error: nil, error_rendered: false)

data/lib/evilution/cli.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "version"
+
+# Declared before the children are required: each child requires this file
+# and nests under Evilution::CLI, so the namespace must exist first.
+class Evilution::CLI; end # rubocop:disable Lint/EmptyClass
+
 require_relative "cli/parser"
 require_relative "cli/parsed_args"
 require_relative "cli/printers/subjects"
@@ -18,6 +23,7 @@ require_relative "cli/commands/session_diff"
 require_relative "cli/commands/session_gc"
 require_relative "cli/commands/compare"
 require_relative "cli/commands/run"
+require_relative "cli/exit_guard"
 
 # @api private
 class Evilution::CLI

data/lib/evilution/config/builders.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../config"
+
 module Evilution::Config::Builders
 end

data/lib/evilution/config/env_loader.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../config"
+
 module Evilution::Config::EnvLoader
   module_function
 

data/lib/evilution/config/file_loader.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "yaml"
+require_relative "../config"
 
 module Evilution::Config::FileLoader
   module_function

data/lib/evilution/config/sources.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../config"
 require_relative "file_loader"
 require_relative "env_loader"
 

data/lib/evilution/config/validators/example_targeting_cache.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::ExampleTargetingCache < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/example_targeting_fallback.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::ExampleTargetingFallback < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/example_targeting_strategy.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::ExampleTargetingStrategy < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/fail_fast.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::FailFast < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/hooks.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::Hooks < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/ignore_patterns.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::IgnorePatterns < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/integration.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::Integration < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/isolation.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::Isolation < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/jobs.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::Jobs < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/preload.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::Preload < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/profile.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::Profile < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/spec_mappings.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::SpecMappings < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/spec_pattern.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../validators"
 require_relative "base"
 
 class Evilution::Config::Validators::SpecPattern < Evilution::Config::Validators::Base

data/lib/evilution/config/validators/warmup.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "../validators"
+require_relative "base"
+
+# `warmup: rails` warms Rails' lazily-initialised state in the parent after
+# the preload; `none` (the default) skips it. `false` is accepted as `none`
+# so `warmup: false` reads naturally in .evilution.yml.
+class Evilution::Config::Validators::Warmup < Evilution::Config::Validators::Base
+  ALLOWED = %i[none rails].freeze
+
+  def self.call(value)
+    return :none if value == false
+
+    coerce_symbol!(value, allowed: ALLOWED, name: "warmup")
+  end
+end

data/lib/evilution/config/validators.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../config"
+
 module Evilution::Config::Validators
 end

data/lib/evilution/config.rb

@@ -17,15 +17,15 @@ class Evilution::Config
     save_session: false, line_ranges: {}, spec_files: [], ignore_patterns: [],
     show_disabled: false, baseline_session: nil, skip_heredoc_literals: false,
     related_specs_heuristic: false, fallback_to_full_suite: false, preload: nil,
-    spec_mappings: {}, spec_pattern: nil, example_targeting: true,
+    output: nil, spec_mappings: {}, spec_pattern: nil, example_targeting: true,
     example_targeting_fallback: :full_file, example_targeting_strategy: :lexical,
     example_targeting_cache: { max_files: 50, max_blocks: 10_000 },
     quiet_children: false, quiet_children_dir: "tmp/evilution_children",
-    profile: :default, canary: true
+    profile: :default, canary: true, warmup: :none
   }.freeze
 
   attr_reader :target_files, :schema_version, :timeout, :format,
-              :target, :min_score, :integration, :verbose, :quiet,
+              :target, :min_score, :integration, :verbose, :quiet, :output,
               :jobs, :fail_fast, :baseline, :isolation, :incremental, :suggest_tests,
               :progress, :save_session, :line_ranges, :spec_files, :hooks,
               :ignore_patterns, :show_disabled, :baseline_session,
@@ -33,7 +33,7 @@ class Evilution::Config
               :fallback_to_full_suite, :preload, :spec_mappings, :spec_pattern,
               :example_targeting, :example_targeting_fallback, :example_targeting_strategy,
               :example_targeting_cache,
-              :spec_selector, :quiet_children, :quiet_children_dir, :profile, :canary
+              :spec_selector, :quiet_children, :quiet_children_dir, :profile, :canary, :warmup
 
   def initialize(**options)
     skip_file = options.delete(:skip_config_file) ? true : false
@@ -243,6 +243,7 @@ class Evilution::Config
     format: :to_sym.to_proc,
     target: nil,
     min_score: :to_f.to_proc,
+    output: nil,
     verbose: nil,
     quiet: nil,
     baseline: nil,
@@ -273,7 +274,7 @@ class Evilution::Config
 
   VALIDATED_ATTRS = %i[
     integration jobs fail_fast isolation ignore_patterns
-    hooks preload spec_mappings spec_pattern profile
+    hooks preload spec_mappings spec_pattern profile warmup
   ].freeze
   private_constant :VALIDATED_ATTRS
 
@@ -310,6 +311,7 @@ require_relative "config/validators/example_targeting_fallback"
 require_relative "config/validators/example_targeting_strategy"
 require_relative "config/validators/example_targeting_cache"
 require_relative "config/validators/profile"
+require_relative "config/validators/warmup"
 require_relative "config/builders"
 require_relative "config/builders/spec_resolver"
 require_relative "config/builders/spec_selector"

data/lib/evilution/coverage.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../evilution"
+require_relative "version"
 
 # Per-example line-coverage support: build a `source file:line -> [examples]`
 # map so mutation targeting can run exactly the examples that execute a line.

data/lib/evilution/coverage_example_filter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../evilution"
+require_relative "version"
 require_relative "coverage/map"
 
 # Per-mutation example targeting backed by a real line-coverage Map (EV-ndjd).

data/lib/evilution/diagnostic.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+# Evilution's own advisory messages -- "no matching spec found", and the like.
+#
+# These deliberately bypass Kernel#warn. That routes through Warning.warn,
+# which a project is free to replace: the `warning` gem with a raising handler
+# turns every Ruby warning into an exception, and both dry-schema and
+# dry-monads configure exactly that in their spec_helper. Under such a project
+# our advisory message would be promoted to a fatal error, so a mutation we
+# meant to classify :unresolved would be reported :error instead -- 239 of
+# dry-monads' 240 mutations, in the run that found this.
+#
+# A message about how evilution is behaving must never be able to fail a
+# user's mutation. Writing straight to the stream keeps it a diagnostic.
+# EV-df7u / GH #1588.
+module Evilution::Diagnostic
+  def self.warn(message, stream: $stderr)
+    stream.puts(message)
+  end
+end

data/lib/evilution/example_filter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "prism"
-require_relative "../evilution"
+require_relative "version"
 require_relative "spec_ast_cache"
 
 class Evilution::ExampleFilter