mutineer 1.3.0 → 1.5.0

data/lib/mutineer/cli.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "optparse"
-require "set"
 require "open3"
 require_relative "version"
 require_relative "config"
@@ -11,6 +10,7 @@ require_relative "pairing"
 require_relative "changed_lines"
 require_relative "runner"
 require_relative "reporter"
+require_relative "kill_matrix"
 require_relative "baseline"
 require_relative "mutator_registry"
 
@@ -29,11 +29,12 @@ module Mutineer
       Usage: mutineer [options] <command> [args]
 
       Commands:
-        run [options] <source...> --test <test...>   Mutate, run, and report
+        run [options] <source...> --test <test> [--test <test>...]
+                                                     Mutate, run, and report
         run --dry-run [options] <source...>          Print candidate mutations only
 
       Run options:
-        --test FILE          Test file covering the sources (repeatable)
+        --test FILE          Test file covering the sources (one per flag; repeat it)
         --operators LIST     Comma-separated operator names (default: Tier 1 set)
         --threshold FLOAT    Fail (exit 1) when score < FLOAT (default: 0 = off)
         --baseline FILE      Fail (exit 1) on NEW survivors / score drop vs a prior
@@ -42,12 +43,22 @@ module Mutineer
         --only NAME          Restrict to one fully-qualified subject
         --since REF          Only mutate lines changed since git REF (e.g. origin/main)
         --no-since           Disable diff scoping (a typed no beats a .mutineer.yml since:)
-        --jobs N             Parallel worker count (default: processor count)
+        --jobs N             Parallel worker count (default: processor count);
+                             --test-command, --fail-fast, or --rails
+                             without --daemon forces 1
         --strategy NAME      reload (whole-file) or redefine (surgical); default: reload
+        --timeout SECONDS    Per-mutant time limit for in-process runs (default: 10;
+                             not with --daemon or --test-command); a mutant over it
+                             is a timeout, excluded from the score
+        --capture-timeout SECONDS  Time limit for each coverage-capture subprocess
+                             and the clean check (default: 120; not with --test-command)
+        --cache-dir DIR      Directory for the coverage cache (default: .mutineer;
+                             not with --test-command)
         --framework NAME     minitest or rspec (default: auto-detect from --test names)
         --boot FILE          Require FILE once in the parent to boot the app env, then
                              fork per mutant (Rails apps; requires --test)
-        --rails              Sugar for --boot config/environment --strategy redefine
+        --rails              Boot config/environment; without --daemon, defaults to
+                             redefine and serial execution
         --test-command CMD   Run the target suite in the app's own runtime as a
                              subprocess (for apps on Ruby < 3.4). CMD must contain
                              %{files}. Scrubs Mutineer Ruby PATH pins; set RAILS_ENV
@@ -58,7 +69,13 @@ module Mutineer
         --format human|json|html  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
         --dry-run            List mutations without executing
-        --fail-fast          Stop at the first surviving mutant
+        --fail-fast          Stop at the first surviving mutant (--no-fail-fast beats a
+                             .mutineer.yml fail_fast:)
+        --matrix             Run every covering test for each mutant and report blind and
+                             redundant tests; the JSON report also lists each mutant's
+                             killers (in-process only; not with --daemon, --test-command,
+                             --fail-fast or --dry-run; --no-matrix beats a .mutineer.yml
+                             matrix:)
         --verbose            Surface the real error when a fork capture fails (alias: --debug)
 
       Options:
@@ -67,19 +84,14 @@ module Mutineer
         --help            Print this help and exit
     USAGE
 
-    # Field symbols whose config-file value is suppressed when the flag is typed.
-    PRECEDENCE_FLAGS = %i[operators jobs threshold only].freeze
-
-    # Deprecated internal strategy names, mapped to their canonical equivalents.
-    STRATEGY_ALIASES = { "7a" => "reload", "7b" => "redefine" }.freeze
-
     # Parses arguments, executes the command, and exits.
     #
     # @param argv [Array<String>] raw command-line arguments.
     # @return [void]
     def self.start(argv)
-      opts = {}            # symbol => value, the CLI-provided Config fields
-      explicit = Set.new   # precedence keys the user typed
+      # The CLI layer holds only the fields the user typed, so Config.resolve
+      # can tell a typed `false`/`nil` from an absent flag by whether the key exists.
+      opts = {}
       show_operators = false
 
       parser = OptionParser.new do |o|
@@ -94,47 +106,46 @@ module Mutineer
         end
         o.on("--list-operators") { show_operators = true }
         o.on("--dry-run") { opts[:dry_run] = true }
-        o.on("--fail-fast") { opts[:fail_fast] = true; explicit << :fail_fast }
-        o.on("--only NAME") { |v| opts[:only] = v; explicit << :only }
-        o.on("--since REF") { |v| opts[:since] = v; explicit << :since }
-        # A typed "no" must beat a .mutineer.yml `since:` key (CLI-over-config
-        # precedence): marking :since explicit with a nil value blocks the fill.
-        o.on("--no-since") { opts[:since] = nil; explicit << :since }
+        # A typed --no-* beats the .mutineer.yml key, so a file key that
+        # conflicts with another flag can be turned off for one run.
+        o.on("--[no-]fail-fast") { |on| opts[:fail_fast] = on }
+        o.on("--[no-]matrix") { |on| opts[:matrix] = on }
+        o.on("--only NAME") { |v| opts[:only] = v }
+        o.on("--since REF") { |v| opts[:since] = Config.parse(:since, v) }
+        # A typed "no" must beat a .mutineer.yml `since:` key: the key is present
+        # with a nil value, and nil is a value.
+        o.on("--no-since") { opts[:since] = nil }
         o.on("--test FILE") { |v| (opts[:tests] ||= []) << v }
-        o.on("--operators LIST") { |v| opts[:operators] = v.split(",").map(&:strip); explicit << :operators }
-        o.on("--threshold FLOAT") do |v|
-          f = Float(v, exception: false)
-          if f.nil?
-            warn "mutineer: --threshold requires a number between 0 and 100 (got: #{v.inspect})"
-            exit 2
-          end
-          opts[:threshold] = f
-          explicit << :threshold
+        o.on("--operators LIST") do |v|
+          opts[:operators] = Config.parse(:operators, v.split(",").map(&:strip))
         end
-        o.on("--jobs N") { |v| opts[:jobs] = v; explicit << :jobs }
-        o.on("--strategy STRAT") { |v| opts[:strategy] = v; explicit << :strategy }
-        o.on("--framework NAME") { |v| opts[:framework] = v; explicit << :framework }
-        o.on("--boot FILE") { |v| opts[:boot] = v; explicit << :boot }
+        o.on("--threshold FLOAT") { |v| opts[:threshold] = Config.parse(:threshold, v) }
+        o.on("--jobs N") { |v| opts[:jobs] = Config.parse(:jobs, v) }
+        o.on("--timeout SECONDS") { |v| opts[:timeout] = Config.parse(:timeout, v) }
+        o.on("--capture-timeout SECONDS") { |v| opts[:capture_timeout] = Config.parse(:capture_timeout, v) }
+        o.on("--cache-dir DIR") { |v| opts[:cache_dir] = Config.parse(:cache_dir, v) }
+        o.on("--strategy STRAT") { |v| opts[:strategy] = Config.parse(:strategy, v) }
+        o.on("--framework NAME") { |v| opts[:framework] = Config.parse(:framework, v) }
+        o.on("--boot FILE") { |v| opts[:boot] = v }
         o.on("--rails") { opts[:rails] = true }
         o.on("--verbose") { opts[:verbose] = true }
         o.on("--debug") { opts[:verbose] = true } # alias of --verbose
-        o.on("--format FORMAT") { |v| opts[:format] = v }
+        o.on("--format FORMAT") { |v| opts[:format] = Config.parse(:format, v) }
         o.on("--output FILE") { |v| opts[:output] = v }
-        # --baseline is also a .mutineer.yml key, so mark it explicit when typed
-        # (CLI wins over the file). --baseline-epsilon is CLI-only.
-        o.on("--baseline FILE") { |v| opts[:baseline] = v; explicit << :baseline }
-        o.on("--baseline-epsilon FLOAT") { |v| opts[:baseline_epsilon] = v.to_f }
+        # --baseline-epsilon is CLI-only.
+        o.on("--baseline FILE") { |v| opts[:baseline] = v }
+        o.on("--baseline-epsilon FLOAT") { |v| opts[:baseline_epsilon] = Config.parse(:baseline_epsilon, v) }
         # Run the target suite as a subprocess in the app's OWN runtime so
         # mutineer (Ruby >= 3.4) can mutation-test apps pinned to an older Ruby.
-        o.on("--test-command CMD") { |v| opts[:test_command] = v; explicit << :test_command }
+        o.on("--test-command CMD") { |v| opts[:test_command] = v }
         # Boot the app ONCE in a persistent daemon and fork per mutant, with
         # per-worker DB isolation so --jobs N is safe under Rails.
-        o.on("--daemon") { opts[:daemon] = true; explicit << :daemon }
+        o.on("--daemon") { opts[:daemon] = true }
       end
 
       begin
         parser.parse!(argv)
-      rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+      rescue OptionParser::InvalidOption, OptionParser::MissingArgument, Mutineer::ConfigError => e
         warn "mutineer: #{e.message}"
         exit 2
       end
@@ -151,8 +162,8 @@ module Mutineer
 
       begin
         file_path = Config.find_file
-        file_hash = file_path ? Config.from_file(file_path) : {}
-        config = Config.resolve(opts, file_hash, explicit)
+        file_hash = file_path ? Config.from_file(file_path, defer_operators: opts.key?(:operators)) : {}
+        config = Config.resolve(opts, file_hash)
       rescue Mutineer::ConfigError => e
         # The lib layer raises instead of killing the host; the CLI maps a
         # config (usage) error to exit 2.
@@ -163,10 +174,16 @@ module Mutineer
       case argv.first
       when "run"
         warn_config_root_mismatch(file_path, config.project_root) if file_path
-        # A directory source expands to its **/*.rb files; literal files pass
-        # through. Test inference (when --test is omitted) happens in validate!.
+        tests_as_sources = argv[1..].grep(%r{(\A|/)(test|spec)/.*_(test|spec)\.rb\z})
+        if config.explicit?(:tests) && tests_as_sources.any?
+          warn "mutineer: #{tests_as_sources.join(', ')} looks like a test file, not a source. " \
+               "--test takes one file; repeat it for each test file (--test a_test.rb --test b_test.rb)"
+          exit 2
+        end
+        # A directory source expands to its **/*.rb files; a file inside the
+        # project becomes its root-relative path (#104). Test inference (when --test is omitted) happens in validate!.
         config.sources = Pairing.expand_sources(argv[1..], project_root: config.project_root)
-        run(config, explicit)
+        run(config)
       else
         warn "mutineer: unknown command '#{argv.first}'"
         exit 2
@@ -187,14 +204,13 @@ module Mutineer
     # Runs the requested command after validation.
     #
     # @param config [Mutineer::Config] run configuration.
-    # @param explicit [Set<Symbol>] explicit CLI fields.
     # @return [void]
-    def self.run(config, explicit = Set.new)
+    def self.run(config)
       if config.sources.empty?
         warn "mutineer: run requires at least one source file"
         exit 2
       end
-      validate!(config, explicit)
+      validate!(config)
 
       config.dry_run ? dry_run(config) : execute(config)
     rescue ArgumentError => e
@@ -236,39 +252,10 @@ module Mutineer
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
-    # @param explicit [Set<Symbol>] explicit CLI fields.
     # @return [void]
-    def self.validate!(config, explicit = Set.new)
-      unless (0.0..100.0).cover?(config.threshold)
-        warn "mutineer: --threshold must be between 0 and 100"
-        exit 2
-      end
-
-      jobs = Integer(config.jobs.to_s, exception: false)
-      if jobs.nil? || jobs < 1
-        warn "mutineer: --jobs requires a positive integer (got: #{config.jobs})"
-        exit 2
-      end
-      config.jobs = jobs
-
-      unless %w[human json html].include?(config.format)
-        warn %(mutineer: unknown format "#{config.format}". Expected: human, json, html)
-        exit 2
-      end
-
-      # Canonical strategies are reload|redefine; 7a/7b are accepted as deprecated
-      # aliases. Normalize to canonical so the rest of the pipeline sees one name.
-      config.strategy = STRATEGY_ALIASES.fetch(config.strategy, config.strategy)
-      unless %w[reload redefine].include?(config.strategy)
-        warn %(mutineer: unknown strategy "#{config.strategy}". Expected: reload, redefine)
-        exit 2
-      end
-
-      unless %w[minitest rspec].include?(config.framework)
-        warn %(mutineer: unknown framework "#{config.framework}". Expected: minitest, rspec)
-        exit 2
-      end
-
+    def self.validate!(config)
+      # First, so a conflict is reported before another check rewrites the config.
+      validate_matrix!(config) if config.matrix
       validate_test_command!(config) if config.test_command
 
       validate_since!(config) if config.since
@@ -277,7 +264,7 @@ module Mutineer
 
       # When --test is omitted, infer each source's test by convention. Autopair
       # also re-detects framework from inferred tests when --framework was not set.
-      autopair!(config, explicit) unless config.dry_run
+      autopair!(config) unless config.dry_run
 
       # Daemon validation runs AFTER autopair so auto-inferred *_spec.rb tests
       # cannot bypass the RSpec rejection (framework would still be minitest if we
@@ -322,6 +309,7 @@ module Mutineer
              "(surgical redefine needs a shared VM; the subprocess has its own)"
         exit 2
       end
+      warn_unused_settings(config, "--test-command", %i[timeout capture_timeout cache_dir])
       return unless config.jobs > 1
 
       warn "[mutineer] --test-command runs serially (no per-worker DB isolation yet); forcing --jobs 1."
@@ -350,6 +338,7 @@ module Mutineer
              "(rspec is not implemented on the daemon path yet)"
         exit 2
       end
+      warn_unused_settings(config, "--daemon", %i[timeout])
       return if config.strategy == "reload"
 
       # --rails defaults strategy to redefine; daemon always whole-file loads.
@@ -358,6 +347,66 @@ module Mutineer
       config.strategy = "reload"
     end
 
+    # Where each setting a backend may ignore applies, for the warning.
+    UNUSED_SETTING_SCOPE = {
+      timeout: "in-process runs only",
+      capture_timeout: "in-process and --daemon coverage capture",
+      cache_dir: "the in-process and --daemon coverage cache"
+    }.freeze
+
+    # A backend that never reads a setting the user set would silently do
+    # nothing with it, so say so. `--test-command` builds no coverage map and
+    # has its own runtime, so it reads none of {UNUSED_SETTING_SCOPE}; the
+    # daemon reads the capture limit and the cache directory but keeps its own
+    # per-mutant limit.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @param backend [String] the backend's flag.
+    # @param keys [Array<Symbol>] the settings that backend ignores.
+    # @return [void]
+    def self.warn_unused_settings(config, backend, keys)
+      keys.each do |key|
+        next unless config.explicit?(key)
+
+        applies = UNUSED_SETTING_SCOPE.fetch(key)
+        warn "[mutineer] #{config.origin(key)} has no effect with #{backend} (it applies to #{applies}); ignoring it."
+      end
+    end
+
+    # --matrix runs on the in-process backend and needs every mutant's whole
+    # covering run, so a backend that cannot name the failing test, or a run that
+    # stops early, is a usage error (exit 2), never a quietly partial matrix.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
+    def self.validate_matrix!(config)
+      conflict, reason =
+        if config.dry_run
+          [:dry_run, "a dry run runs no tests, so it has no matrix"]
+        elsif config.daemon
+          [:daemon, "the kill matrix runs on the in-process backend only"]
+        elsif config.test_command
+          [:test_command, "the external suite reports pass or fail, not which test failed"]
+        elsif config.fail_fast
+          [:fail_fast, "a fail-fast run is partial, so blind and redundant tests would be wrong"]
+        end
+      return unless conflict
+
+      # Say how to turn off whichever side came from the file, for this run.
+      hint =
+        if config.origin(:matrix) != "--matrix"
+          "; pass --no-matrix to run without it"
+        elsif conflict == :fail_fast && config.origin(:fail_fast) != "--fail-fast"
+          "; pass --no-fail-fast to run without it"
+        else
+          ""
+        end
+      warn "mutineer: #{config.origin(:matrix)} cannot be combined with #{config.origin(conflict)} (#{reason}#{hint})"
+      exit 2
+    end
+
     # --since needs a real git repo and a resolvable ref; either failure is a
     # usage error (exit 2) so CI sees "bad invocation," not "tests too weak."
     #
@@ -399,30 +448,30 @@ module Mutineer
     end
 
     # Auto-pair sources to tests by path convention when no --test was given
-    # (explicit --test wins). Each source with an inferred test on disk joins the
-    # run; a source with none is dropped with a one-line stderr warning and the
-    # run continues with the rest. If every source is dropped: in boot mode the
+    # (explicit --test wins). Each source with at least one inferred test on
+    # disk joins the run; a source with none is dropped with a one-line stderr
+    # warning and the run continues with the rest. Split files for one source
+    # are all kept (#87). If every source is dropped: in boot mode the
     # dedicated --boot/--rails-requires-test check reports it; otherwise exit 2
     # with a usage message. The framework is re-detected from the inferred set
     # unless it was set explicitly (a spec-only project loads/reports as rspec).
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
-    # @param explicit [Set<Symbol>] explicit CLI fields.
     # @return [void]
-    def self.autopair!(config, explicit)
+    def self.autopair!(config)
       return unless config.tests.empty?
 
       paired = config.sources.filter_map do |s|
-        t = Pairing.infer_test(s, project_root: config.project_root, prefer: config.framework)
-        [s, t] if t
+        tests = Pairing.infer_tests(s, project_root: config.project_root, prefer: config.framework)
+        [s, tests] unless tests.empty?
       end
       (config.sources - paired.map(&:first)).each do |s|
         warn "[mutineer] no test found by convention for #{s}; skipping"
       end
       config.sources = paired.map(&:first)
-      config.tests   = paired.map(&:last).uniq
-      config.framework = Config.detect_framework(config.tests) unless explicit.include?(:framework)
+      config.tests   = paired.flat_map(&:last).uniq
+      config.framework = Config.detect_framework(config.tests) unless config.explicit?(:framework)
 
       return unless config.sources.empty?
       return if config.boot # let the --boot/--rails-requires-test check report it
@@ -472,7 +521,8 @@ module Mutineer
 
       aggregate, source_map, extras = Runner.execute(config)
       warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
-      reporter = Reporter.new(aggregate, source_map)
+      matrix = KillMatrix.new(aggregate.results) if config.matrix
+      reporter = Reporter.new(aggregate, source_map, matrix: matrix)
 
       # Diff the current run against the baseline (preflighted above) by the
       # stable survivor id. The delta is rendered inline (human section / additive