mutineer 1.6.0 → 1.7.0

data/lib/mutineer/cli.rb

@@ -13,7 +13,10 @@ require_relative "job_plan"
 require_relative "reporter"
 require_relative "kill_matrix"
 require_relative "baseline"
+require_relative "migrate"
 require_relative "mutator_registry"
+require_relative "triage"
+require_relative "init"
 
 module Mutineer
   # Command-line entry point. `start` is the single public method called by
@@ -21,7 +24,8 @@ module Mutineer
   #
   # Exit codes:
   #   0  success / requested output (--version, --help, score >= threshold)
-  #   1  survivors below threshold, or a runtime error
+  #   1  survivors below threshold, a runtime error, or an ignore id
+  #      `migrate` could not map
   #   2  usage / flag error (unknown subcommand, invalid flag, unknown operator,
   #      out-of-range threshold)
   class CLI
@@ -33,6 +37,15 @@ module Mutineer
         run [options] <source...> --test <test> [--test <test>...]
                                                      Mutate, run, and report
         run --dry-run [options] <source...>          Print candidate mutations only
+        triage REPORT.json --reason TEXT
+            (--id ID ... | --all)                    Print ignore: entries for
+                                                     survivors. Does not edit files.
+        migrate [options] <source...>                Rewrite old ignore ids in
+                                                     .mutineer.yml. --dry-run prints
+                                                     each change and writes nothing
+        init [--rails] [--force]                     Write .mutineer.yml and print
+                                                     the first run command.
+                                                     --force replaces an existing file.
 
       Run options:
         --test FILE          Test file covering the sources (one per flag; repeat it)
@@ -55,6 +68,9 @@ module Mutineer
                              and the clean check (default: 120; not with --test-command)
         --cache-dir DIR      Directory for the coverage cache (default: .mutineer;
                              not with --test-command)
+        --coverage-from FILE Reuse the coverage.json of a --rails/--boot capture over
+                             these sources or more; runs alone only the tests that
+                             cover these sources
         --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)
@@ -66,7 +82,9 @@ module Mutineer
                              on the mutineer command (not as KEY=val inside CMD)
         --daemon             Boot the app ONCE in a persistent daemon and fork per
                              mutant, with per-worker DB isolation so --jobs N is safe
-                             under Rails (needs --rails/--boot; not with --test-command)
+                             under Rails (needs --rails/--boot; not with --test-command).
+                             --no-daemon beats a .mutineer.yml daemon: (2.0 will default
+                             --rails to --daemon; --no-daemon keeps it serial)
         --format human|json|html  Report format (default: human)
         --output FILE        Write the report to FILE instead of stdout
         --dry-run            List mutations without executing
@@ -77,6 +95,8 @@ module Mutineer
                              killers (in-process only; not with --daemon, --test-command,
                              --fail-fast or --dry-run; --no-matrix beats a .mutineer.yml
                              matrix:)
+        --allow-empty        A run with no mutants is expected; do not warn (--no-allow-empty
+                             beats a .mutineer.yml allow_empty:)
         --verbose            Surface the real error when a fork capture fails (alias: --debug)
 
       Options:
@@ -90,6 +110,14 @@ module Mutineer
     # @param argv [Array<String>] raw command-line arguments.
     # @return [void]
     def self.start(argv)
+      if argv.first == "triage"
+        exit Triage.run(argv[1..])
+      end
+
+      if argv.first == "init"
+        exit Init.run(argv[1..])
+      end
+
       # 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 = {}
@@ -111,6 +139,7 @@ module Mutineer
         # 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("--[no-]allow-empty") { |on| opts[:allow_empty] = 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
@@ -125,6 +154,7 @@ module Mutineer
         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("--coverage-from FILE") { |v| opts[:coverage_from] = Config.parse(:coverage_from, 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 }
@@ -141,7 +171,9 @@ module Mutineer
         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 }
+        # A typed --no-daemon beats a .mutineer.yml `daemon: true`, and pins the
+        # serial --rails path before 2.0 makes the daemon the default.
+        o.on("--[no-]daemon") { |on| opts[:daemon] = on }
       end
 
       begin
@@ -185,12 +217,99 @@ module Mutineer
         # 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)
+      when "migrate"
+        warn_config_root_mismatch(file_path, config.project_root) if file_path
+        unless file_path
+          warn "mutineer: migrate needs a .mutineer.yml (none found from #{Dir.pwd})"
+          exit 2
+        end
+        if argv[1..].empty?
+          warn "mutineer: migrate requires at least one source file"
+          exit 2
+        end
+        config.sources = Pairing.expand_sources(argv[1..], project_root: config.project_root)
+        migrate(config, file_path)
       else
         warn "mutineer: unknown command '#{argv.first}'"
         exit 2
       end
     end
 
+    # Rewrites old-format ids in the loaded `.mutineer.yml` `ignore:` list.
+    # Prints each change. With `--dry-run`, writes nothing. Exits 1 when any
+    # id matched no mutant in these sources and operators, or when an id in a
+    # `{ id:, reason: }` entry now matches several mutants (split it by hand).
+    # Those ids stay in the file. Exits 0 when every id is current or was
+    # rewritten.
+    # An unsupported `ignore:` shape exits 2 and leaves the file unchanged.
+    #
+    # @param config [Mutineer::Config] run configuration, sources already set.
+    # @param file_path [String] the `.mutineer.yml` to edit.
+    # @return [void]
+    def self.migrate(config, file_path)
+      current, old_to_new = Migrate.id_maps(config)
+      text = File.read(file_path)
+      outcome = Migrate.rewrite(text, current, old_to_new)
+      outcome.replacements.each do |rep|
+        puts "[mutineer] #{rep.old_id} -> #{rep.new_ids.join(', ')}"
+      end
+      outcome.unmapped.each do |id|
+        warn "[mutineer] ignore entry #{id} matched no mutant in these sources and operators. " \
+             "It was left in place."
+      end
+      outcome.split.each do |rep|
+        warn "[mutineer] ignore entry #{rep.old_id} has a reason and now matches several mutants " \
+             "(#{rep.new_ids.join(', ')}). Split it into one entry per id by hand. It was left in place."
+      end
+      warn "[mutineer] dry run: .mutineer.yml was not changed" if config.dry_run
+      replace_file(file_path, outcome.text) if !config.dry_run && outcome.text != text
+      exit(outcome.unmapped.empty? && outcome.split.empty? ? 0 : 1)
+    rescue ArgumentError => e
+      warn "mutineer: #{e.message}"
+      exit 2
+    rescue Mutineer::ParseError => e
+      warn "mutineer: error reading: #{e.message}"
+      exit 1
+    rescue SystemCallError => e
+      warn "mutineer: #{e.message}"
+      exit 2
+    end
+
+    # Replaces `path` with `contents` without truncating the original first.
+    # The new bytes go to a temporary file in the same directory. That file
+    # is closed before it is renamed over the target, and it keeps the
+    # target's mode. A symlink is followed, so the target file changes and
+    # the link stays. If the write fails, the temporary file is removed and
+    # the original file is left as it was.
+    #
+    # @api private
+    # @param path [String] the configuration file to replace.
+    # @param contents [String] the full new text.
+    # @return [void]
+    def self.replace_file(path, contents)
+      target = File.symlink?(path) ? File.realpath(path) : path
+      directory = File.dirname(target)
+      base = File.basename(target)
+      temp = nil
+      100.times do
+        candidate = File.join(directory, ".#{base}.migrate-#{Process.pid}-#{rand(1_000_000_000)}.tmp")
+        next if File.exist?(candidate)
+
+        temp = candidate
+        break
+      end
+      raise Errno::EEXIST, target unless temp
+
+      mode = File.stat(target).mode & 0o7777
+      # `perm` is still masked by the umask, so chmod restores the exact mode.
+      File.write(temp, contents, perm: mode)
+      File.chmod(mode, temp)
+      File.rename(temp, target)
+    rescue StandardError
+      File.unlink(temp) if temp && File.exist?(temp)
+      raise
+    end
+
     # Lists available operators.
     #
     # @return [void]
@@ -212,6 +331,7 @@ module Mutineer
         exit 2
       end
       validate!(config)
+      Config.warn_rails_default_change(config)
 
       config.dry_run ? dry_run(config) : execute(config)
     rescue ArgumentError => e
@@ -241,6 +361,9 @@ module Mutineer
       # backtrace: the working tree is still the other run's responsibility.
       warn "mutineer: #{e.message}"
       exit 1
+    rescue Mutineer::CoverageFromError => e
+      warn "mutineer: #{e.message}"
+      exit 2
     rescue Mutineer::DaemonBootError => e
       # The daemon is gone for good, so the run ended rather than scoring the rest
       # against it. A deliberate stop deserves a message, not a raw backtrace.
@@ -271,6 +394,7 @@ module Mutineer
       # cannot bypass the RSpec rejection (framework would still be minitest if we
       # validated before discovery).
       validate_daemon!(config) if config.daemon
+      warn_unused_coverage_from(config)
 
       # Boot mode needs at least one --test file (nothing to select from otherwise).
       if config.boot && config.tests.empty?
@@ -318,9 +442,10 @@ module Mutineer
     end
 
     # --daemon selects the persistent-daemon backend (boot once, fork per mutant,
-    # per-worker DB isolation on SQLite). Usage errors exit 2: cannot combine with
-    # --test-command; requires --rails or --boot; minitest only; reload strategy only
-    # (redefine needs a shared VM surgical path the daemon does not ship).
+    # per-worker DB isolation on SQLite, Postgres, and MySQL). Usage errors exit 2:
+    # cannot combine with --test-command; requires --rails or --boot; minitest only;
+    # reload strategy only (redefine needs a shared VM surgical path the daemon
+    # does not ship).
     #
     # @api private
     # @param config [Mutineer::Config] run configuration.
@@ -352,9 +477,24 @@ module Mutineer
     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"
+      cache_dir: "the in-process and --daemon coverage cache",
+      coverage_from: "in-process --rails/--boot runs"
     }.freeze
 
+    # Warns when `--coverage-from` is set on a run that captures no coverage.
+    #
+    # @api private
+    # @param config [Mutineer::Config] run configuration.
+    # @return [void]
+    def self.warn_unused_coverage_from(config)
+      mode = if config.test_command then "--test-command"
+             elsif config.daemon then "--daemon"
+             elsif config.dry_run then "--dry-run"
+             elsif !config.boot then "a run without --rails/--boot"
+             end
+      warn_unused_settings(config, mode, %i[coverage_from]) if mode
+    end
+
     # 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
@@ -544,16 +684,17 @@ module Mutineer
       reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
                       format: config.format, output: config.output, baseline: delta,
                       scoped: !config.since.nil?, legacy_id_matches: legacy_id_matches)
+      warn_empty_run(config, extras) if aggregate.total.zero?
 
       # Warn (stderr, so it never pollutes json/html) that an external run's score
       # is not comparable to an in-process run: no coverage narrowing (uncovered
-      # mutants count as survivors), and an infra failure is scored as a kill
-      # (upper bound). Daemon coverage fallback warnings are emitted from the runner
+      # mutants count as survivors), and an infra failure that still starts the
+      # suite is scored as a kill (exit 126/127 are scored error). Daemon coverage fallback warnings are emitted from the runner
       # only when the map is unavailable, not on every --daemon run.
       if config.test_command
         warn "[mutineer] --test-command score is an upper bound, not comparable to an " \
              "in-process run: no coverage narrowing (uncovered mutants count as survivors) " \
-             "and an infra failure is scored as a kill."
+             "and an infra failure is scored as a kill (except exit 126 and 127, scored error)."
       end
 
       # Nudge toward the opt-in tier-2 operators (human report only: never
@@ -568,6 +709,27 @@ module Mutineer
       exit [reporter.exit_code(threshold: config.threshold), baseline_exit].max
     end
 
+    # Says why a run has no mutants, on stderr for every format. A --since run
+    # whose sources had mutants before scoping is a stated success: the changes
+    # held no mutable Ruby code. Any other empty run is a likely mistake (wrong
+    # path, operators that never match), which 2.0 fails unless --allow-empty
+    # says it is expected.
+    #
+    # @param config [Mutineer::Config] run configuration.
+    # @param extras [Hash] the run extras; `:unscoped_mutants` counts the mutants (run and
+    #   suppressed) before --since.
+    # @return [void]
+    def self.warn_empty_run(config, extras)
+      # Mutants existed before --since narrowed them: the changes held none.
+      if config.since && extras[:unscoped_mutants].to_i.positive?
+        warn "mutineer: nothing to test in the changes since #{config.since}"
+      elsif !config.allow_empty
+        warn "mutineer: no mutants were generated. Check that the sources contain code the " \
+             "operators mutate. The run exits 0, and #{BECOMES_ERROR_IN_2_0}. " \
+             "Pass --allow-empty (or allow_empty: true) if an empty run is expected."
+      end
+    end
+
     # The tier-2 operators not in the active set, as a one-line hint (or nil when
     # they are all already enabled). `active` nil means the default (Tier-1) set.
     #
@@ -624,7 +786,8 @@ module Mutineer
         warn "[mutineer] ignore entry #{old} uses the old id format, which did not include the " \
              "file path. It matched these new ids: #{listed}. This list covers only mutants in " \
              "this run's sources and operators; a run over every source gives the complete " \
-             "replacement. #{advice}"
+             "replacement. #{advice} To update the file, run `mutineer migrate`. " \
+             "#{BECOMES_ERROR_IN_2_0}."
       end
     end
 
@@ -635,12 +798,12 @@ module Mutineer
     # @return [void]
     def self.warn_legacy_baseline
       warn "[mutineer] the baseline uses the old id format, which did not include the file " \
-           "path, so survivors were matched on their old ids and files. Regenerate the baseline " \
-           "(run with --format json and save the output), but only after every gate that reads " \
-           "it runs this mutineer version or later."
+           "path, so survivors were matched on their old ids and files. Please generate a new " \
+           "baseline with `--format json`, but only after every gate that reads it runs this " \
+           "mutineer version or later. #{BECOMES_ERROR_IN_2_0}."
     end
 
-    # Runs dry-run mode. Reuses JobPlan.collect_jobs (+ filter_since) so the
+    # Runs dry-run mode. Reuses JobPlan.collect_jobs (+ scope_since) so the
     # candidate list cannot drift from a real run's job selection.
     #
     # @param config [Mutineer::Config] run configuration.
@@ -649,14 +812,10 @@ module Mutineer
       operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
       jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
       warn_legacy_ignore_matches(extras[:legacy_ignore_matches])
-      # Narrow jobs and ignored the same way so the summary matches the printed list.
-      if config.since
-        jobs = JobPlan.filter_since(jobs, source_map, config)
-        ignored_jobs = ignored_results.map { |r| [r.subject, r.mutation, r.id] }
-        ignored = JobPlan.filter_since(ignored_jobs, source_map, config).size
-      else
-        ignored = ignored_results.size
-      end
+      # Narrow jobs and ignored the same way a real run does, so the summary
+      # matches the printed list.
+      jobs, ignored_results, = JobPlan.scope_since(jobs, ignored_results, source_map, config)
+      ignored = ignored_results.size
 
       per_operator = Hash.new(0)
       skipped = 0

data/lib/mutineer/concern_blocks.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Lets the reload strategy load a concern file a second time (#256).
+  #
+  # ActiveSupport::Concern stores an `included` or `prepended` block once. A
+  # second block with another `source_location` raises
+  # `MultipleIncludedBlocks` (or `MultiplePrependBlocks`). Rails reloads keep
+  # the file's path, but a mutant loads from a temp file beside it, so every
+  # mutant of a concern with such a block would error. {.forget} removes the
+  # stored blocks that the source file defined, so the mutant's load stores
+  # its own. {.replace} wraps the load and puts back any block the load did not
+  # store again, such as one under an `unless defined?` guard. A class that
+  # already includes the concern keeps what the original block defined in it:
+  # ActiveSupport does not run the block there again.
+  # Discovery marks the defs in these blocks (see {Subject#unplaceable?}).
+  #
+  # Call it only in a forked child that loads the mutant. Without
+  # ActiveSupport it does nothing.
+  #
+  # Stdlib-only, so the app-side daemon can load it.
+  module ConcernBlocks
+    # Where ActiveSupport::Concern stores each block.
+    STORED_BLOCKS = %i[@_included_block @_prepended_block].freeze
+
+    # Forgets the source file's stored blocks, runs the block that loads the
+    # mutant, then puts back each forgotten block the load did not store again.
+    # A concern the mutant's load skips (an `unless defined?` guard) keeps its
+    # original block, so a class that includes it during the tests still gets it.
+    #
+    # @param source_file [String] the file the mutant replaces.
+    # @yield the mutant's load.
+    # @return [Object] what the block returns.
+    def self.replace(source_file)
+      forgotten = forget(source_file)
+      yield
+    ensure
+      forgotten&.each do |concern, name, block|
+        concern.instance_variable_set(name, block) unless concern.instance_variable_defined?(name)
+      end
+    end
+
+    # Removes every stored `included` and `prepended` block that the source
+    # file defined, from every concern. Blocks from other files stay.
+    #
+    # @param source_file [String] the file the mutant replaces.
+    # @return [Array<Array(Module, Symbol, Proc)>] each concern, where it stored
+    #   the block, and the block removed.
+    def self.forget(source_file)
+      return [] unless defined?(::ActiveSupport::Concern)
+
+      path = real_path(source_file)
+      forgotten = []
+      ObjectSpace.each_object(::ActiveSupport::Concern) do |concern|
+        STORED_BLOCKS.each do |name|
+          next unless concern.instance_variable_defined?(name)
+
+          block = concern.instance_variable_get(name)
+          file = block.source_location&.first
+          next unless file && real_path(file) == path
+
+          concern.remove_instance_variable(name)
+          forgotten << [concern, name, block]
+        end
+      end
+      forgotten
+    end
+
+    # The file's real path, so a symlinked or relative path matches the path
+    # Ruby recorded when it loaded the file.
+    #
+    # @param file [String] a file path.
+    # @return [String]
+    def self.real_path(file)
+      File.realpath(file)
+    rescue SystemCallError
+      File.expand_path(file)
+    end
+  end
+end