mutineer 1.7.0 → 1.8.0

data/lib/mutineer/reporter.rb

@@ -25,8 +25,13 @@ module Mutineer
     # workflow, so one bad mutant never fails the gate on its own, at any size.
     BROKEN_FLOOR = 1
 
+    # Share of the mutants a run tried to score that may go unrun (unplaceable or
+    # skipped invalid) before stderr warns. A warning only: it never changes the
+    # exit code. {BROKEN_FLOOR} also applies, so one unrun mutant never warns.
+    UNRUN_SHARE_LIMIT = 0.10
+
     # The JSON report's `schema_version` (see docs/json-schema.md).
-    SCHEMA_VERSION = "1.8"
+    SCHEMA_VERSION = "1.9"
 
     # The warning both matrix renderers give under the redundant tests.
     MATRIX_REDUNDANT_NOTE = "Delete redundant tests one at a time: two of them can be the only killers of one mutant."
@@ -52,16 +57,18 @@ module Mutineer
     # `--baseline` load) knows the score covers only the changed-line mutants.
     # `legacy_id_matches` (`{ignore:, baseline:}`) counts stored ids still in the
     # old format (#126); only the JSON report records it (`summary.legacy_id_matches`).
+    # `declined` (operator name => count, from {JobPlan.collect_jobs}) counts the
+    # candidates the operators did not mutate; the JSON and human reports show it.
     def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil,
-               baseline: nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 })
+               baseline: nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 }, declined: {})
       rendered =
         if format == "json"
-          json_report(baseline, scoped: scoped, legacy_id_matches: legacy_id_matches)
+          json_report(baseline, scoped: scoped, legacy_id_matches: legacy_id_matches, declined: declined)
         elsif format == "html"
           html_report
         else
           sio = StringIO.new
-          human_report(sio, err, threshold)
+          human_report(sio, err, threshold, declined: declined, scoped: scoped)
           baseline_section(sio, baseline) if baseline
           sio.string
         end
@@ -74,6 +81,7 @@ module Mutineer
         out.print rendered
       end
 
+      warn_unrun_share(err)
       return warn_errors_without_gate(err) unless threshold&.positive?
 
       # Both ways a run can fail the gate on completeness, said here rather than in
@@ -105,20 +113,53 @@ module Mutineer
                "#{(BROKEN_SHARE_LIMIT * 100).round}% of those attempted (no_verdict[] in --format json)."
     end
 
+    # Warns when the unrun mutants (unplaceable plus skipped invalid) are more
+    # than {UNRUN_SHARE_LIMIT} of the mutants the run tried to score, and more
+    # than {BROKEN_FLOOR}. Every format, with or without --threshold; the exit
+    # code does not change.
+    #
+    # @api private
+    # @param err [IO] error stream.
+    # @return [void]
+    def warn_unrun_share(err)
+      return unless unrun_share_exceeded?
+
+      unrun = @agg.unrun_count
+      tried = attempted_count + unrun
+      parts = []
+      parts << "#{@agg.unplaceable_count} unplaceable" if @agg.unplaceable_count.positive?
+      parts << "#{@agg.skipped_invalid_count} skipped (invalid)" if @agg.skipped_invalid_count.positive?
+      pct = (unrun * 100.0 / tried).round(1)
+      message = +"[mutineer] #{unrun} of the #{tried} mutants mutineer tried to score were not run " \
+                 "(#{parts.join(', ')}; #{pct}%, limit #{(UNRUN_SHARE_LIMIT * 100).round}%). " \
+                 "The score leaves them out. This warning does not change the exit code."
+      if @agg.unplaceable_count.positive?
+        message << " See unplaceable[] in --format json; --test-command runs them."
+      end
+      if @agg.skipped_invalid_count.positive?
+        message << " A mutant skipped (invalid) did not re-parse after mutation. If its source file " \
+                   "parses on its own, that is a mutineer bug: please report it at " \
+                   "https://github.com/davidteren/mutineer/issues."
+      end
+      err.puts message
+    end
+
     # Renders the human report.
     #
     # @param out [IO] output stream.
     # @param err [IO] error stream.
     # @param threshold [Float] score threshold.
+    # @param declined [Hash{String => Integer}] operator name => declined count.
+    # @param scoped [Boolean] the run was diff-scoped (`--since`).
     # @return [void]
-    def human_report(out, err, threshold)
+    def human_report(out, err, threshold, declined: {}, scoped: false)
       # The CLI explains an empty run for every format (CLI.warn_empty_run).
       return if @agg.total.zero?
 
       out.puts "Mutineer — Mutation Results"
       out.puts "========================="
       out.puts
-      summary(out)
+      summary(out, declined: declined, scoped: scoped)
       out.puts
       score_line(out, err)
       per_source(out)
@@ -149,7 +190,7 @@ module Mutineer
       # reports 90% and exits 0, so CI cannot tell a complete run from a broken one.
       return 1 if broken_share_exceeded?
 
-      score >= threshold ? 0 : 1
+      @agg.meets_threshold?(threshold) ? 0 : 1
     end
 
     private
@@ -166,7 +207,10 @@ module Mutineer
     #   old-format ignore entries that matched, and survivors matched in an
     #   old-format baseline only through their old id (#126).
     # @return [String] JSON text.
-    def json_report(baseline = nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 })
+    # @param declined [Hash{String => Integer}] operator name => count of
+    #   candidates that operator did not mutate (additive `summary.declined`
+    #   and `summary.declined_by_operator` keys).
+    def json_report(baseline = nil, scoped: false, legacy_id_matches: { ignore: 0, baseline: 0 }, declined: {})
       killed = @agg.killed_count
       survived = @agg.survived_count
       # null (not 0.0) on an empty denominator, matching the nil-vs-0.0
@@ -199,7 +243,11 @@ module Mutineer
           # Additive (1.4, #126): stored ids still in the old format. `ignore` is
           # the number of old-format ignore entries that matched; `baseline` the
           # survivors matched in the baseline only through their old id.
-          legacy_id_matches: legacy_id_matches
+          legacy_id_matches: legacy_id_matches,
+          # Additive (1.9, #291): candidates the operators found and did not
+          # mutate (a heredoc split or an equivalent skip), so not in `total`.
+          declined: declined.values.sum,
+          declined_by_operator: declined
         },
         survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
                        .sort_by { |h| [h[:file], h[:line], h[:operator]] },
@@ -521,7 +569,7 @@ module Mutineer
       file = result.subject&.file
       return unless result.mutation && file
 
-      source = @source_map[file] || File.read(file)
+      source = source_for(file)
       source.byteslice(0, result.mutation.start_offset).count("\n") + 1
     end
 
@@ -608,7 +656,7 @@ module Mutineer
     def survivor_json(result)
       m = result.mutation
       file = result.subject.file
-      source = @source_map[file] || File.read(file)
+      source = source_for(file)
       start_line, original_block, mutated_block, token = diff_for(m, source)
       # A block at the end of the file has no newline after it; elsewhere the
       # file's next byte is one. Each side's own text decides its marker.
@@ -689,7 +737,7 @@ module Mutineer
     def mutant_json(result)
       m = result.mutation
       file = result.subject.file
-      source = @source_map[file] || File.read(file)
+      source = source_for(file)
       start_line, _orig, _mut, token = diff_for(m, source)
       {
         subject: result.subject.qualified_name,
@@ -742,8 +790,11 @@ module Mutineer
     # Writes the summary block.
     #
     # @param out [IO] output stream.
+    # @param declined [Hash{String => Integer}] operator name => declined count.
+    # @param scoped [Boolean] the run was diff-scoped (`--since`), which does not
+    #   narrow the declined count.
     # @return [void]
-    def summary(out)
+    def summary(out, declined: {}, scoped: false)
       out.puts "Summary"
       out.puts "-------"
       out.puts format("Total:        %-6d  Killed:        %d", @agg.total, @agg.killed_count)
@@ -753,12 +804,16 @@ module Mutineer
       # A broken harness, not a coverage gap: report it distinctly from No coverage.
       out.puts format("Uncapturable: %-6d  (tests failed to run)", @agg.uncapturable_count)
       # Not broken: the strategy cannot load these where the tests call them (no
-      # named class under redefine, or a concern's `included` or `prepended` block).
+      # named class under redefine, or some methods in a concern's `included` or
+      # `prepended` block; see docs/json-schema.md).
       out.puts format("Unplaceable:  %-6d  (not loadable where the tests call it; verify with --test-command)",
                       @agg.unplaceable_count)
       # Not a verdict: the line ran before the mutant was applied (#187).
       out.puts format("Ran at load:  %-6d  (ran while the app or class loaded; mutineer cannot re-run that; " \
                       "verify with --test-command)", @agg.ran_at_load_count)
+      # Not mutants: candidates an operator chose not to mutate (#291).
+      out.puts format("Declined:     %-6d  (candidates an operator did not mutate; --dry-run shows the count " \
+                      "per operator%s)", declined.values.sum, scoped ? "; not narrowed by --since" : "")
       # Equivalent mutants the user suppressed; excluded from the denominator.
       out.puts format("Ignored:      %-6d  (equivalent, suppressed)", @agg.ignored_count)
     end
@@ -824,8 +879,8 @@ module Mutineer
     #
     # skipped-invalid is excluded from both sides: it means a mutant did not
     # re-parse and was correctly never run, which is a validity outcome rather
-    # than a broken harness. Cost: an overwhelmingly-skipped run still scores on
-    # what little ran; that is our operator misbehaving and wants its own signal.
+    # than a broken harness. Its own signal is the unrun-share warning
+    # ({#warn_unrun_share}), together with unplaceable.
     #
     # @api private
     # @return [Integer] killed + survived + no-verdict.
@@ -833,6 +888,16 @@ module Mutineer
       @agg.killed_count + @agg.survived_count + no_verdict_count
     end
 
+    # Whether the unrun mutants (unplaceable plus skipped invalid) are more than
+    # {BROKEN_FLOOR} and more than {UNRUN_SHARE_LIMIT} of attempted plus unrun.
+    #
+    # @api private
+    # @return [Boolean] true when the unrun-share warning applies.
+    def unrun_share_exceeded?
+      unrun = @agg.unrun_count
+      unrun > BROKEN_FLOOR && unrun > UNRUN_SHARE_LIMIT * (attempted_count + unrun)
+    end
+
     # The sentence both the verdict line and the stderr note are built from, so a
     # user cannot read one number in the report and a different one beside it.
     #
@@ -887,10 +952,10 @@ module Mutineer
       out.puts "-------------------"
       out.puts "killed #{@agg.killed_count}, #{delta.new_survivors.size} new survivors vs baseline"
       delta.new_survivors
-           .sort_by { |r| [r.subject.file, r.mutation.start_offset] }
+           .sort_by { |r| [r.subject.file, *tie_key(r)] }
            .each do |r|
         file = r.subject.file
-        source = @source_map[file] || File.read(file)
+        source = source_for(file)
         line, = diff_for(r.mutation, source)
         out.puts "  + #{printable(r.subject.qualified_name)} (#{printable(file)}:#{line}) #{r.mutation.operator}"
       end
@@ -901,6 +966,16 @@ module Mutineer
       out.puts(delta.regressed ? "REGRESSION vs baseline" : "OK: no regression vs baseline")
     end
 
+    # Orders mutants in one file: by offset, then operator and replacement, so
+    # mutants at the same offset list the same way whatever order they ran in.
+    #
+    # @param result [Mutineer::Result] a result with a mutation.
+    # @return [Array] the sort key.
+    def tie_key(result)
+      m = result.mutation
+      [m.start_offset, m.operator.to_s, m.replacement.to_s]
+    end
+
     # Writes the survivors block.
     #
     # @param out [IO] output stream.
@@ -915,7 +990,7 @@ module Mutineer
       mutants.group_by { |r| r.subject.file }.sort.each do |file, group|
         out.puts
         out.puts printable(file)
-        group.sort_by { |r| r.mutation.start_offset }.each { |r| survivor(out, file, r) }
+        group.sort_by { |r| tie_key(r) }.each { |r| survivor(out, file, r) }
       end
     end
 
@@ -927,7 +1002,7 @@ module Mutineer
     # @return [void]
     def survivor(out, file, result)
       m = result.mutation
-      source = @source_map[file] || File.read(file)
+      source = source_for(file)
       start_line, original_block, mutated_block, token = diff_for(m, source)
 
       out.puts "  #{printable(result.subject.qualified_name)} (#{printable(File.basename(file))}:#{start_line})"
@@ -936,6 +1011,14 @@ module Mutineer
       mutated_block.each_line  { |l| out.puts "  + #{printable(l.chomp)}" }
     end
 
+    # The source text of `file`: the run's copy when it has one, else the file
+    # read as UTF-8 whatever the locale (#303).
+    #
+    # @api private
+    # @param file [String] source file path.
+    # @return [String] source text.
+    def source_for(file) = @source_map[file] || File.read(file, encoding: "UTF-8")
+
     # Source text, a method name or a file path made safe for a terminal (#163):
     # each control character except tab becomes its Ruby escape (ESC prints as
     # `\e`). The text is read as UTF-8 whatever the locale, and each byte that is
@@ -968,9 +1051,14 @@ module Mutineer
 
       # Same rule as exit_code, or the report says PASSED on a run that exits 1 —
       # and with --output that wrong verdict is what gets archived.
+      passed = @agg.meets_threshold?(threshold)
       if broken_share_exceeded?
         out.puts "FAILED: #{no_verdict_ratio}; #{score}% covers only part of the run"
-      elsif score >= threshold
+      elsif passed != (score >= threshold)
+        # The rounded score points the other way, so give the exact counts.
+        out.puts "#{passed ? 'PASSED' : 'FAILED'}: #{@agg.killed_count} of #{@agg.covered_count} killed " \
+                 "#{passed ? 'meets' : 'is below'} threshold #{threshold}% (the #{score}% score is rounded)"
+      elsif passed
         out.puts "PASSED: #{score}% >= threshold #{threshold}%"
       else
         out.puts "FAILED: #{score}% < threshold #{threshold}%"

data/lib/mutineer/result.rb

@@ -4,13 +4,18 @@ module Mutineer
   # Immutable outcome of running one mutant. Ten distinct states:
   #   killed       - a test failed/errored, so the mutation was caught.
   #   survived     - every test passed, so the mutation went undetected.
-  #   error        - the child crashed (unhandled exception): exit status 2.
+  #   error        - the child crashed (unhandled exception), or a Minitest
+  #                  run's first failure was a database connection or lock
+  #                  error (#296): exit status 2.
   #   timeout      - the parent SIGKILLed a child that overran its wall clock.
   #   skipped      - the mutated source failed to re-parse (invalid); no fork.
   #   no_coverage  - no test exercises the mutated line; not run, not scored.
   #                  Also a mutant on a later line of a multi-line statement,
   #                  in code that runs only sometimes, that the statement's
   #                  tests ran but did not kill (#254): they may not reach it.
+  #                  Also a mutant on a later line of a statement whose first
+  #                  or last line holds other code (a call inside a one-line
+  #                  block), that the tests of that line did not kill (#289).
   #   uncapturable - the line's would-be covering test errored during capture,
   #                  so coverage was lost. Excluded from the denominator exactly
   #                  like no_coverage, but reported separately: it signals a
@@ -20,9 +25,11 @@ module Mutineer
   #                  it, so it is not run. Under `--strategy redefine` the
   #                  method belongs to a class or module that cannot be named
   #                  statically (for example each class that includes a
-  #                  concern). Under either strategy the method is in a
-  #                  concern's `included` or `prepended` block, which does not
-  #                  run again in a class that already includes it (#256).
+  #                  concern), and every method in a concern's `included` or
+  #                  `prepended` block is one (#256). Under `--strategy reload`
+  #                  only some methods in such a block are: those it cannot
+  #                  load into each class that has them (#297; the cases are
+  #                  listed in docs/json-schema.md).
   #                  Excluded from the denominator and, unlike uncapturable,
   #                  from the no-verdict gate: nothing is broken.
   #                  `--test-command` runs these mutants.
@@ -162,7 +169,8 @@ module Mutineer
   # cleanly (see Isolation.finish). It is false when the child timed out,
   # errored or exited the process early, when the recorder never armed, when
   # its lines arrived out of order, when Minitest returned after an Interrupt
-  # with tests unseen, or when the row does not agree with the verdict.
+  # with tests unseen, when a test had a database connection or lock failure,
+  # or when the row does not agree with the verdict.
   Kills = Data.define(:killed_by, :ran, :complete)
 
   # Aggregates a flat list of Results into counts, the mutation score, and the
@@ -203,6 +211,11 @@ module Mutineer
     def timeout_count         = count(:timeout)
     # @return [Integer] ignored count.
     def ignored_count         = count(:ignored)
+    # Mutants that exist but did not run: unplaceable plus skipped invalid.
+    # Neither is in the score; the reporter warns when they pass a share of the run.
+    #
+    # @return [Integer] unplaceable plus skipped-invalid count.
+    def unrun_count           = unplaceable_count + skipped_invalid_count
 
     # Every generated, classified mutation. NOT the score denominator.
     #
@@ -223,6 +236,21 @@ module Mutineer
       (killed_count.to_f / covered_count * 100).round(1)
     end
 
+    # Checks the unrounded score against a threshold. `mutation_score` is
+    # rounded for display, so 1999 of 2000 killed reads 100.0; a gate that
+    # compared it would pass `--threshold 100` with a survivor. The comparison
+    # is exact: integer counts against the threshold as the decimal it prints
+    # as, so a float product such as `64.4 * 250` cannot tip a run at the
+    # boundary. `to_s.to_r` keeps that decimal; `rationalize` could round a
+    # long threshold such as 66.66666666666667 down to 200/3.
+    #
+    # @param threshold [Numeric] threshold percentage.
+    # @return [Boolean] true when killed / covered * 100 >= threshold; false
+    #   when nothing was covered.
+    def meets_threshold?(threshold)
+      covered_count.positive? && killed_count * 100 >= threshold.to_s.to_r * covered_count
+    end
+
     # Returns the surviving mutants.
     #
     # @return [Array<Mutineer::Result>] surviving results.

data/lib/mutineer/runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require "rbconfig"
 require_relative "parser"
 require_relative "project"
 require_relative "result"
@@ -17,8 +18,27 @@ require_relative "external_backend"
 require_relative "daemon_backend"
 require_relative "job_plan"
 require_relative "rails_run_env"
+require_relative "redaction"
 
 module Mutineer
+  # Raised when the tool process cannot load a project file: the boot file, a
+  # standalone source, or a `--require` path. The message is redacted and the
+  # original exception is not kept as `cause`, so neither can show the
+  # DATABASE_URL password. The CLI maps it to a runtime error (exit 1).
+  class ProjectLoadError < StandardError
+    # @return [Array<String>] the redacted `Class: message` of each exception
+    #   in the original `cause` chain, outermost first.
+    attr_reader :causes
+
+    # @param message [String] the redacted message.
+    # @param causes [Array<String>] see {#causes}.
+    # @return [ProjectLoadError]
+    def initialize(message, causes: [])
+      super(message)
+      @causes = causes
+    end
+  end
+
   # Orchestrates one mutation end-to-end: apply it textually, validate the
   # result, select its covering test files from the coverage map, then run only
   # those against the mutated source in an isolated child process (strategy
@@ -32,7 +52,8 @@ module Mutineer
     # Full orchestration: resolve operators, discover subjects, build the
     # coverage map, run every mutation, and aggregate. Returns
     # [AggregateResult, source_map, extras], where extras is the hash
-    # {JobPlan.collect_jobs} returns (`:legacy_ignore_matches`, `:id_map`), unchanged.
+    # {JobPlan.collect_jobs} returns (`:legacy_ignore_matches`, `:id_map`,
+    # `:dropped_id_map`, `:declined`), plus `:unscoped_mutants` under `--since`.
     # The CLI then reports + applies the exit code; the integration test asserts
     # directly on the AggregateResult.
     #
@@ -58,16 +79,32 @@ module Mutineer
       # Daemon backend: boot the app ONCE in a persistent subprocess under the
       # app's bundle and fork per mutant. Tool-side we only discover jobs + build
       # payloads (Prism), so branch before any in-process boot.
-      return DaemonBackend.execute(config, operator_classes) if config.daemon
+      if config.daemon
+        # The daemon loads these files itself and would report a missing one as
+        # a boot failure (exit 1). Check here so it stays a usage error (exit 2),
+        # as it is in process.
+        [config.boot, *config.require_paths].compact.each { |f| project_file!(config.project_root, f) }
+        return DaemonBackend.execute(config, operator_classes)
+      end
 
-      # Whole-file reload writes .mutineer_mutant*.rb into each source dir (so
-      # require_relative resolves). A SIGKILL'd child skips the tempfile's
+      # Both strategies (whole-file reload and redefine, #279) write
+      # .mutineer_mutant*.rb into each source dir (so require_relative and
+      # __dir__ resolve). Redefine falls back to the system temp dir for a
+      # read-only source dir, which this sweep does not reach; the OS cleans
+      # it, as in 1.x. A SIGKILL'd child skips the tempfile's
       # ensure-unlink, orphaning it. `ensure` is unreliable vs SIGKILL, so the
       # PARENT sweeps each source dir before and after the run. Orphans are
       # impossible after a normal run. The first sweep runs before the boot: a
       # file an older version left without the dot would stop Zeitwerk (#253).
       dirs = JobPlan.source_dirs(config)
       JobPlan.sweep_orphans(dirs)
+      if config.strategy == "redefine"
+        dirs.reject { |d| File.writable?(d) }.each do |d|
+          warn "[mutineer] #{d} is not writable: redefine loads its mutants from the system temp dir, " \
+               "so a method there that uses __dir__ or require_relative can be falsely killed. " \
+               "Make the directory writable to avoid this (#339)."
+        end
+      end
 
       # Boot mode: require the boot file ONCE so the app env (e.g. Rails) is booted
       # in the parent and inherited by every fork. Do NOT manually require the
@@ -92,11 +129,11 @@ module Mutineer
         when :idle then Coverage.start(lines: true, methods: true)
         when :suspended then Coverage.resume
         end
-        require File.expand_path(config.boot, config.project_root)
+        require_project_file(config.project_root, config.boot)
       else
-        config.sources.each { |f| require File.expand_path(f, config.project_root) }
+        config.sources.each { |f| require_project_file(config.project_root, f) }
       end
-      config.require_paths.each { |f| require File.expand_path(f, config.project_root) }
+      config.require_paths.each { |f| require_project_file(config.project_root, f) }
       preload_owners(config) if config.boot && config.strategy == "redefine"
 
       if config.boot
@@ -133,11 +170,11 @@ module Mutineer
           source_paths: config.sources, test_paths: config.tests,
           cache_dir: File.expand_path(config.cache_dir, config.project_root), project_root: config.project_root,
           load_paths: config.load_paths + rel_roots, framework: config.framework,
-          require_paths: config.require_paths,
+          require_paths: config.require_paths, verbose: config.verbose,
           capture_timeout: config.capture_timeout || CoverageMap::DEFAULT_CAPTURE_TIMEOUT
         ).build_or_load
       end
-      JobPlan.abort_if_unclean!(coverage_map)
+      JobPlan.abort_if_unclean!(coverage_map, framework: config.framework)
 
       # Collect every (subject, mutation) up front so the pool can fan them out.
       jobs, ignored_results, source_map, extras = JobPlan.collect_jobs(config, operator_classes)
@@ -227,15 +264,23 @@ module Mutineer
         # 3x the clean run, floor 30s, ceiling 300s: a heuristic. The floor covers
         # a fast suite; the ceiling bounds a hung mutant (infinite loop) so a
         # handful cannot stall a serial run for ~45min on a slow suite.
-        smoke_elapsed = ExternalBackend.smoke_check!(config.test_command, abs_tests)
+        smoke_elapsed, check_summary = ExternalBackend.smoke_check!(config.test_command, abs_tests)
         timeout = [[smoke_elapsed * 3, 30].max, 300].min.ceil
+        # #292: the summary check needs a summary line to look for. Without one
+        # on the clean run, keep the exit-code rule and say what that costs.
+        unless check_summary
+          warn "[mutineer] the clean run of --test-command printed no Minitest or RSpec summary line " \
+               "(such as \"3 runs, 3 assertions, 0 failures, 0 errors\" or \"3 examples, 0 failures\"), " \
+               "so the crash check is off: an exit 1 counts as a kill even when the suite crashed " \
+               "before its tests ran. Use the default Minitest or RSpec progress output to turn it on."
+        end
 
         results = []
         progress = Progress.new(jobs.size)
         begin
           jobs.each do |subject, mutation, id|
             r = run_external(subject, mutation, config.test_command, abs_tests,
-                             timeout: timeout, verbose: config.verbose)
+                             timeout: timeout, verbose: config.verbose, check_summary: check_summary)
             results << r.with(subject: subject, mutation: mutation, id: id)
             progress.tick
             break if config.fail_fast && r.survived? # stop at the first survivor
@@ -250,18 +295,19 @@ module Mutineer
 
     # Runs one mutant through the external backend: apply the whole-file mutation
     # on disk, run the command, restore. An invalid (non-reparsing) mutant would
-    # fail to load and score a false `killed`, so skip it tool-side (Prism, already
-    # cheap) and never write the file, preserving the `skipped` verdict the
+    # fail to load (scored `error`, or a false `killed` without the summary
+    # check), so skip it tool-side (Prism, already cheap) and never write the file, preserving the `skipped` verdict the
     # in-process path gives at the pre-fork check.
     #
+    # @param check_summary [Boolean] passed to {ExternalBackend.run}.
     # @return [Mutineer::Result] verdict for this mutant.
-    def self.run_external(subject, mutation, command, abs_tests, timeout:, verbose:)
-      source  = File.read(subject.file)
+    def self.run_external(subject, mutation, command, abs_tests, timeout:, verbose:, check_summary:)
+      source  = File.read(subject.file, encoding: "UTF-8")
       mutated = mutation.apply(source)
       return Result.skipped if Parser.parse_string(mutated).errors.any?
 
       FileSwap.with(subject.file, mutated) do
-        ExternalBackend.run(command, abs_tests, timeout: timeout, verbose: verbose)
+        ExternalBackend.run(command, abs_tests, timeout: timeout, verbose: verbose, check_summary: check_summary)
       end
     end
 
@@ -304,7 +350,8 @@ module Mutineer
     # @param mutation [Mutineer::Mutation] mutation to run.
     # @param source_file [String] source file path.
     # @param coverage_map [Mutineer::CoverageMap, nil] coverage map.
-    # @param subject [Mutineer::Subject, nil] subject for surgical strategy.
+    # @param subject [Mutineer::Subject, nil] subject for surgical strategy;
+    #   redefine also loads each of its enclosing subjects.
     # @param strategy [String] mutation strategy.
     # @param timeout [Integer] child timeout in seconds.
     # @param rails [Boolean] whether Rails reconnect handling is enabled.
@@ -314,7 +361,7 @@ module Mutineer
     # @return [Mutineer::Result] mutant result.
     def self.run(mutation, source_file:, coverage_map: nil, subject: nil, strategy: "reload",
                  timeout: Isolation::DEFAULT_TIMEOUT, rails: false, framework: "minitest", matrix: false)
-      source  = File.read(source_file)
+      source  = File.read(source_file, encoding: "UTF-8")
       mutated = mutation.apply(source)
 
       # Validity rule: a mutant that does not re-parse is skipped before forking.
@@ -336,7 +383,16 @@ module Mutineer
         # across processes corrupts it. Drop it so AR reconnects per child.
         reconnect_active_record if rails
         if strategy == "redefine"
+          # Load each enclosing def too: its body holds the original nested def,
+          # which a call to it would define again over the mutant (#290).
           Isolation.apply_surgical(mutation, subject, source)
+          s = subject
+          Isolation.apply_surgical(mutation, s, source) while (s = s.enclosing_subject)
+        elsif subject&.reload_hook_call
+          # #297: a def in a concern's hook block reaches each class that has it.
+          code, hook_def = JobPlan.hook_mutant(mutated, mutation, subject, source)
+          Isolation.apply_whole_file(code, source_file)
+          ConcernBlocks.place_hook_def(source_file: source_file, **hook_def)
         else
           Isolation.apply_whole_file(mutated, source_file)
         end
@@ -415,6 +471,58 @@ module Mutineer
     end
     private_class_method :reconnect_active_record
 
+    # The absolute path of a project file `require` can load: as given, or
+    # with `.rb` or the native-extension suffix.
+    #
+    # @api private
+    # @param root [String] the project root.
+    # @param path [String] the path as the user gave it.
+    # @raise [Errno::ENOENT] when the requested file does not exist.
+    # @raise [ArgumentError] when Ruby cannot expand the path.
+    # @return [String]
+    def self.project_file!(root, path)
+      file = File.expand_path(path, root)
+      suffixes = ["", ".rb", ".#{RbConfig::CONFIG.fetch('DLEXT')}"]
+      raise Errno::ENOENT, path unless suffixes.any? { |suffix| File.file?("#{file}#{suffix}") }
+
+      file
+    end
+    private_class_method :project_file!
+
+    # Require one project file in the tool process. A failure becomes a
+    # {ProjectLoadError} whose message, and each cause in its list, is
+    # redacted. The original backtrace is kept; the cause is not, because
+    # Ruby would print its raw message.
+    #
+    # @api private
+    # @param root [String] the project root.
+    # @param path [String] the path as the user gave it.
+    # @raise [Errno::ENOENT] when the requested file does not exist.
+    # @raise [ProjectLoadError] when the file raises while it loads.
+    # @return [void]
+    def self.require_project_file(root, path)
+      # Outside the rescue: a path Ruby cannot expand (`~nosuchuser/boot.rb`)
+      # stays a usage error (exit 2), not a load failure.
+      file = project_file!(root, path)
+
+      begin
+        require file
+      rescue StandardError, ScriptError => e
+        # Every part is redacted on its own, so the message build cannot raise
+        # on mixed encodings and leave the raw error as the new one's cause.
+        causes = []
+        cause = e.cause
+        while cause
+          causes << Redaction.describe(cause)
+          cause = cause.cause
+        end
+        error = ProjectLoadError.new("cannot load #{Redaction.text(path)}: #{Redaction.describe(e)}", causes: causes)
+        error.set_backtrace(e.backtrace)
+        raise error, cause: nil
+      end
+    end
+    private_class_method :require_project_file
+
     # Pure, injectable predicate: true when a transactional-fixture transaction is
     # already open on the connection. Keys off open_transactions so it is correct
     # whenever the transaction exists, regardless of when it opened. Any probe

data/lib/mutineer/statement_lines.rb

@@ -12,16 +12,20 @@ module Mutineer
     # @param def_node [Prism::DefNode] the method that holds the position.
     # @param source [String] the source text of the file.
     # @param offset [Integer] byte offset of the position.
-    # @param loose [Boolean] also return the lines when the position is in
-    #   code that runs only sometimes when the statement runs (the right side of
-    #   `a && b`, a branch, the body of `x if c`). The tests that ran the
-    #   statement then include every test that ran the position, but may not
-    #   have run it (#254).
+    # @param loose [Boolean] return the lines also when their tests may not
+    #   have run the position: when it is in code that runs only sometimes
+    #   when the statement runs (the right side of `a && b`, a branch, the body
+    #   of `x if c`, #254), and with a first or last line that holds other code
+    #   (the opener of a one-line block, #289). The `def` line is never
+    #   given, because it counts when the file loads. So every test that ran
+    #   the position is among the tests of these lines, unless the statement
+    #   starts on the `def` line.
     # @return [Array<Integer>] the lines of the statement, with the body of each
     #   heredoc in it. Empty when no statement in the body holds the position.
-    #   A first or last line that holds other code is left out, because Ruby
-    #   can count that line without the statement: the `def` line counts when
-    #   the file loads, and `x if done; y(` counts when `y` does not run.
+    #   Unless `loose`, a first or last line that holds other code is left out,
+    #   because Ruby can count that line without the statement: the `def` line
+    #   counts when the file loads, and `x if done; y(` counts when `y` does
+    #   not run.
     def self.for(def_node, source, offset, loose: false)
       return [] unless def_node.body
 
@@ -42,6 +46,8 @@ module Mutineer
 
       location = statement.location
       lines = (location.start_line..last_line(statement)).to_a
+      return lines - [def_node.location.start_line] if loose
+
       lines.delete(location.start_line) unless before(source, location).strip.empty?
       after = after(source, location).strip
       lines.delete(location.end_line) unless after.empty? || after.start_with?("#")