saboteur 0.8.0 → 0.9.0

data/lib/saboteur/engine/scheduler.rb

@@ -64,7 +64,7 @@ module Saboteur
         results = run_candidates(candidates) do |mutation, text|
           reuse(plan, mutation, text) || execute(plan, mutation, text)
         end
-        checked(plan, results)
+        checked(plan, results, truncated: results.size < candidates.size)
       end
 
       # The per-mutant timeout: timeout_factor times what the tests took
@@ -81,14 +81,21 @@ module Saboteur
 
       # Verdicts that did not hold up are warned about once per subject;
       # only checked verdicts are stored for --incremental.
-      # A spent budget admits no check: forking the unchanged run with no
-      # time left would turn genuine kills into fabricated errors and cache
-      # them. Fresh kills stand unverified instead - outside the score,
-      # never cached - and the distribution marks the subject so the run
-      # reports budget-partial.
-      def checked(plan, results)
-        return results.map { |result| unverifiable(result) } if budget_spent?
-
+      # A spent budget admits no check for a subject that finished its
+      # mutants: forking the unchanged run with no time left would turn
+      # genuine kills into fabricated errors and cache them. Fresh kills
+      # stand unverified instead - outside the score, never cached - and
+      # the distribution marks the subject so the run reports
+      # budget-partial.
+      # A subject the budget stopped mid-list is different (#588): its
+      # completed mutants were already measured, so their checks still
+      # run, uncapped - the budget stops new mutation work, not the
+      # confirmation of work already done. The overshoot stays bounded by
+      # the subject's distinct killing sequences.
+      def checked(plan, results, truncated: false)
+        return results.map { |result| unverifiable(result) } if budget_spent? && !truncated
+
+        @confirming_truncation = truncated
         subject = plan.subject
         check = VerdictCheck.new(run_unchanged: unchanged_runner(subject, plan),
                                  baseline_timeout: @config["baseline_timeout"])
@@ -101,6 +108,8 @@ module Saboteur
           @diagnostics.warn("#{subject.id}: #{overturned} verdict(s) failed with the method unchanged")
         end
         final
+      ensure
+        @confirming_truncation = false
       end
 
       # A kill rejected because its covering examples fail with the method
@@ -111,10 +120,12 @@ module Saboteur
       # mutant's run on the same examples. Otherwise the error stays.
       #
       # Cost bound: at most two extra forks per rejected kill, the unchanged
-      # prefix run and one mutant run. Both spend --max-duration like every
-      # other fork: neither starts once the budget is spent, and neither gets
-      # more than the time left. A retry the budget stops is unverified, not
-      # an error or a kill. Keep this bound if the retry ever grows.
+      # prefix run and one mutant run. Ordinarily both spend --max-duration
+      # like every other fork: neither starts once the budget is spent, and
+      # neither gets more than the time left. A retry the budget stops is
+      # unverified, not an error or a kill. The exception is a truncated
+      # subject (#588): its completed kills still retry, at the full
+      # timeout. Keep this bound if the retry ever grows.
       def retried_in_defined_order(plan, result)
         return result unless result.rejected_kill? && !result.reused? && result.covered_by.any?
 
@@ -129,10 +140,10 @@ module Saboteur
       end
 
       def rerun_in_prefix(plan, result, tests)
-        return result.as_unverified(BUDGET_RETRY_REASON) if budget_spent?
+        return result.as_unverified(BUDGET_RETRY_REASON) if budget_spent? && !@confirming_truncation
 
         full = timeout_for(tests, plan.slowdown)
-        capped = budget_capped(full)
+        capped = @confirming_truncation ? full : budget_capped(full)
         outcome = @runner.run(subject: plan.subject, text: result.mutated_source, test_ids: tests,
                               timeout: capped, mutation: result.mutation, eval_prefix: eval_prefix(plan))
         return result.as_unverified(BUDGET_RETRY_REASON) if outcome.status == :timeout && capped < full
@@ -150,11 +161,11 @@ module Saboteur
       # the check never got its answer (#296).
       def unchanged_runner(subject, plan)
         lambda do |tests, timeout|
-          if budget_spent?
+          if budget_spent? && !@confirming_truncation
             Execution::Runner::Outcome.new(status: :unverified, runtime: 0.0,
                                            message: "the --max-duration budget is spent")
           else
-            capped = budget_capped(timeout)
+            capped = @confirming_truncation ? timeout : budget_capped(timeout)
             outcome = @runner.run(subject: subject, text: subject.source, test_ids: tests, timeout: capped,
                                   eval_prefix: eval_prefix(plan))
             note_leftovers(subject, "verdict check", outcome)
@@ -238,17 +249,14 @@ module Saboteur
         [@config["timeout_factor"] * runtime, @config["timeout_min"]].max
       end
 
-      # What a subject no test ran gets. Code that only ran while the app
-      # loaded is not "no coverage" - it ran - but no forked test can re-run
-      # it, so it gets its own status, out of the score, with a hint.
+      # What a subject no test ran gets. Load-only code is not "no coverage":
+      # it ran, but no forked test can re-run it, so it gets its own status.
       def unloadable(candidates, subject, line_numbers = nil)
+        return skip_all(candidates, subject, Selection::CoverageMap::PRELOADED) if @map.preloaded?(subject.file)
         return skip_all(candidates, subject, "no coverage") unless
           @map.ran_at_load?(subject.file, line_numbers || subject.coverage_lines)
 
-        candidates.map do |mutation, text|
-          MutantResult.new(subject: subject, mutation: mutation, status: :ran_at_load, mutated_source: text,
-                           reason: Selection::CoverageMap::RAN_AT_LOAD)
-        end
+        load_time_results(candidates, subject)
       end
 
       # A def-time macro's only callers ran while the app loaded: the
@@ -329,7 +337,7 @@ module Saboteur
       # Each mutant is checked separately: changing a body can change which
       # definition a test reaches, so one unreachable verdict cannot skip later work.
       def note_unreachable(plan, outcome)
-        @diagnostics.warn("#{plan.subject.id}: #{outcome.message}")
+        @diagnostics.warn("#{plan.subject.id}: a mutant never ran and is not scored\n  #{outcome.message}")
       end
 
       # The text a known def-time wrapper needs re-evaluated with the def.

data/lib/saboteur/engine/selection_announcement.rb

@@ -10,10 +10,15 @@ module Saboteur
     module SelectionAnnouncement
       private
 
+      # A --since diff with no changed source file (a spec-only or docs-only
+      # change) yields zero subjects, so the suite never runs: say there is
+      # nothing to test rather than promise a whole-suite run that does not
+      # happen (#607).
       def selection_message(guess)
-        if guess.changed.zero?
-          target = config["since"] ? "no changed source file" : "no source file"
-          "inferred specs: #{target} to infer a spec for, so the whole suite runs"
+        if guess.changed.zero? && config["since"]
+          "inferred specs: no changed source file to infer a spec for, so there is nothing to test"
+        elsif guess.changed.zero?
+          "inferred specs: no source file to infer a spec for, so the whole suite runs"
         elsif guess.specs.empty?
           guess.no_specs_message(since: config["since"])
         else
@@ -47,6 +52,7 @@ module Saboteur
         # opt-out and would warn.
         @config = config.with({ "tests" => guess.specs }, except: ["guess_tests"])
         @guessed_tests = guess.specs
+        @guessed_referenced = guess.referenced
         guess.scope_message(since: config["since"])
       end
     end

data/lib/saboteur/engine/shadow_comparison.rb

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # Compares the map a partial rebuild produced with the full map (#46,
+    # step 3). The full map is the one a run uses; this only says whether the
+    # partial path would have been right.
+    #
+    # Two things are compared, and both must match:
+    # - the semantic evidence: which tests exist and, per source file, which
+    #   tests hit which lines, methods and branch arms, and which lines ran
+    #   while the app loaded. Durations, build time and the order of ids are
+    #   left out, as are entries with no test.
+    # - what the result cache would watch: for every test the source files
+    #   it touched, plus the boot files and the loaded files nothing
+    #   observed. Evidence that matches line by line but yields another
+    #   dependency set is worse than a line mismatch, since the set decides
+    #   whether an old verdict is reused.
+    module ShadowComparison
+      MAX_DIFFERENCES = 50
+      KINDS = %i[lines methods branches].freeze
+
+      module_function
+
+      # { result: :match | :superset | :mismatch, match: bool, total: Integer, extra: Integer,
+      #   gained: Integer,
+      #   differences: [{kind:, name:}] } with at most MAX_DIFFERENCES entries,
+      # sorted by kind and name.
+      #
+      # :superset means the partial map credits tests the full map does not,
+      # on lines the full map also credits, and never lacks a credit the
+      # full map has. Anything else that differs is :mismatch, including an
+      # extra credit on a line the full map calls uncovered: it would turn
+      # "no test covers this" into "covered". Those are counted apart, in
+      # gained. extra counts the other extra credits (one per file, line and
+      # test) in lines, methods and branches.
+      def call(partial, full, fallback_files: [])
+        maps = [partial, full]
+        found = evidence_differences(maps) + dependency_differences(maps, fallback_files)
+        counted = found.select { |item| KINDS.map(&:to_s).include?(item[:kind]) }
+        extra = counted.sum { |item| item[:extra] }
+        gained = counted.sum { |item| item[:gained] }
+        result = if found.empty? then :match
+                 elsif gained.positive? || found.any? { |item| item[:missing] } then :mismatch
+                 else :superset
+                 end
+        shown = found.sort_by { |item| [item[:kind], item[:name]] }.first(MAX_DIFFERENCES)
+        { result: result, match: result == :match, total: found.size, extra: extra, gained: gained,
+          differences: shown.map { |item| item.slice(:kind, :name) } }
+      end
+
+      def evidence_differences(maps)
+        partial, full = maps
+        found = []
+        unless partial.tests.sort == full.tests.sort
+          found << { kind: "tests", name: "the set of test ids", missing: true }
+        end
+        KINDS.each { |kind| found.concat(hit_differences(kind.to_s, hits(partial, kind), hits(full, kind))) }
+        found.concat(exact_differences("load", load_hits(partial), load_hits(full)))
+      end
+
+      # Per name: the credits only the partial map has (extra) and the ones
+      # only the full map has (missing).
+      def hit_differences(kind, left, right)
+        (left.keys | right.keys).filter_map do |name|
+          extra, gained, missing = credits(left[name] || {}, right[name] || {})
+          next if extra.zero? && gained.zero? && !missing
+
+          { kind: kind, name: name, extra: extra, gained: gained, missing: missing }
+        end
+      end
+
+      def credits(left, right)
+        extra = gained = 0
+        missing = false
+        (left.keys | right.keys).each do |line|
+          mine = left[line] || []
+          theirs = right[line] || []
+          (theirs.empty? ? gained += mine.size : extra += (mine - theirs).size)
+          missing ||= (theirs - mine).any?
+        end
+        [extra, gained, missing]
+      end
+
+      def exact_differences(kind, left, right)
+        (left.keys | right.keys).reject { |name| left[name] == right[name] }
+                                .map { |name| { kind: kind, name: name, missing: true } }
+      end
+
+      # {file => {line-or-span => sorted ids}} without empty entries.
+      def hits(map, kind)
+        map.public_send(kind).each_with_object({}) do |(file, by_line), acc|
+          kept = by_line.transform_values(&:sort).reject { |_line, ids| ids.empty? }
+          acc[file] = kept unless kept.empty?
+        end
+      end
+
+      def load_hits(map)
+        [map.load_lines, map.load_methods].flat_map(&:to_a).each_with_object({}) do |(file, lines), acc|
+          acc[file] = (acc.fetch(file, []) | lines).sort unless lines.empty?
+        end
+      end
+
+      # The files every verdict depends on must match exactly. What each
+      # test depends on follows from its line and method credits, which are
+      # compared above, so it is not compared again.
+      def dependency_differences(maps, fallback_files)
+        partial, full = maps
+        left = dependencies(partial, fallback_files)
+        right = dependencies(full, fallback_files)
+        left.keys.reject { |name| left[name] == right[name] }.map { |name| { kind: "deps", name: name, missing: true } }
+      end
+
+      def dependencies(map, fallback_files)
+        unobserved = (fallback_files | map.loaded_files).select { |file| map.empty_for?([file]) }.sort
+        { "(boot files)" => map.boot_files, "(unobserved files)" => unobserved }
+      end
+    end
+  end
+end

data/lib/saboteur/engine/shadow_run.rb

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  class Engine
+    # One shadow comparison (#46, step 3): would a partial rebuild from the
+    # last map have matched the full map this run just built? The run uses
+    # the full map either way; this only produces the report.
+    #
+    # The report always carries the share threshold and, when the partial
+    # path was possible, the observed stale share, so the constant can be
+    # fitted from data later.
+    module ShadowRun
+      module_function
+
+      # base: the earlier inputs snapshot and its map. current: the inputs
+      # snapshot of this run. rerun.call(stale_spec_files, seed) builds a map
+      # over just those files. clean turns a name into a line-safe string.
+      def call(base:, base_map:, current:, full_map:, invalidation:, fallback_files:, rerun:, clean:)
+        report = { "threshold" => PartialInvalidation::THRESHOLD, "base_map" => base["map_key"] }
+        stale = invalidation.stale_specs(base, current)
+        return report.merge("result" => "skipped", "reason" => "a full rebuild is needed") if stale == :full
+
+        merged = stale.empty? ? base_map : PartialMerge.call(base_map, rerun.call(stale, base["seed"]), stale)
+        verdict = ShadowComparison.call(merged, full_map, fallback_files: fallback_files)
+        report.merge("result" => verdict[:result].to_s, "extra_credits" => verdict[:extra],
+                     "gained_credits" => verdict[:gained],
+                     "stale" => stale.map(&clean),
+                     "stale_share" => invalidation.share(stale), "total" => verdict[:total],
+                     "differences" => verdict[:differences].map do |item|
+                       item.to_h do |key, value|
+                         [key.to_s, clean.call(value)]
+                       end
+                     end)
+      end
+    end
+  end
+end

data/lib/saboteur/engine/subject_selection.rb

@@ -4,12 +4,39 @@
 require_relative "../text"
 require_relative "../constant_subject"
 require_relative "../constant_subject_finder"
+require_relative "../attribute_finder"
 require_relative "../constant_reads"
 
 module Saboteur
   class Engine
     # The subjects to mutate: every def in the included files, narrowed by
     # --subject patterns and by --since (methods with a changed line).
+    # A heredoc body is code the static subject walk cannot see: methods
+    # defined by class_eval'ing the string, or behavior living in a
+    # template constant, exist only when the string is evaluated (#467).
+    module HeredocSpans
+      module_function
+
+      def changed_lines_inside?(file, changed_lines)
+        result = Prism.parse(File.binread(file))
+        return false if result.failure?
+
+        spans = collect(result.value)
+        changed_lines.any? { |line| spans.any? { |span| span.cover?(line) } }
+      end
+
+      def collect(node, spans = [])
+        if (node.is_a?(Prism::StringNode) || node.is_a?(Prism::InterpolatedStringNode)) &&
+           node.opening_loc&.slice&.start_with?("<<")
+          # The node location of an interpolated string stops at the opening
+          # marker; opening through closing covers the whole heredoc body.
+          spans << (node.opening_loc.start_line..node.closing_loc.end_line)
+        end
+        node.compact_child_nodes.each { |child| collect(child, spans) }
+        spans
+      end
+    end
+
     class SubjectSelection
       # Lines changed since the --since ref, by file; nil without --since.
       attr_reader :changed_lines
@@ -33,12 +60,36 @@ module Saboteur
           subjects += constant_subjects
         end
         @discovered = subjects
+        warn_unmatched_whole_file(subjects) if @config["since"]
         subjects = by_pattern(subjects, @config["subjects"]) if @config["subjects"].any?
         subjects = by_change(subjects, @config["since"]) if @config["since"]
         subjects = drop_intentionally_untested(subjects)
+        inform_nothing_to_test(subjects)
         attach_consumers(subjects)
       end
 
+      # A --since run can legitimately select nothing: the range is empty
+      # (a checkout AT the base, #643) or its changes carry no mutable Ruby
+      # (a docs-only diff, #659). Exit 0 with a notice, not a silent green:
+      # name the base, the changed-file count and why nothing was selected.
+      def inform_nothing_to_test(subjects)
+        ref = @config["since"]
+        return unless ref && subjects.empty?
+
+        changed = Selection::GitDiff.changed_paths(ref, root: @root)
+        count = changed[:present].size + changed[:deleted].size
+        reason = if count.zero?
+                   "the resolved range has no changes"
+                 elsif !@raw_changed_files.intersect?(@files)
+                   "#{count} changed file#{'s' unless count == 1}, none in mutation scope " \
+                     "(docs-only, excluded, or non-Ruby)"
+                 else
+                   "no subject covers the changed lines (layout-only edits, deletions, " \
+                     "or intentionally untested code)"
+                 end
+        @diagnostics.inform("--since #{ref}: nothing to test - #{reason}")
+      end
+
       # "Klass#meth", "Klass.meth", or a namespace prefix ("Klass", "A::B").
       def self.match?(id, pattern)
         id == pattern || %w[# . ::].any? { |separator| id.start_with?("#{pattern}#{separator}") }
@@ -83,7 +134,8 @@ module Saboteur
             else
               @diagnostics.record_discovery_failure(file, reason: "invalid_file_syntax")
               parsed.errors.first(1).each do |message|
-                @diagnostics.warn("#{file.delete_prefix("#{@root}/")} does not parse: #{message}")
+                @diagnostics.warn("fix the syntax in #{Text.display_safe(file.delete_prefix("#{@root}/"))}: " \
+                                  "does not parse (#{Text.display_safe(message)})")
               end
             end
           end
@@ -96,16 +148,12 @@ module Saboteur
           subjects.any? { |subject| self.class.match?(subject.id, pattern) }
         end
         missed.each do |pattern|
-          @diagnostics.warn("--subject #{pattern} matches no subject (patterns are names like " \
-                            "Klass, Klass#meth or Klass.meth, not globs)")
+          @diagnostics.warn(missed_pattern_message(pattern))
         end
         # A total miss is a typo: refuse instead of a green zero-subject
         # summary (#379). A partial miss runs, but the matched count is
         # on the record.
-        if missed.size == patterns.size
-          raise ConfigError, "--subject #{patterns.join(', ')} matches no subject (patterns are names like " \
-                             "Klass, Klass#meth or Klass.meth, not globs)"
-        end
+        raise ConfigError, total_miss_message(missed) if missed.size == patterns.size
 
         if missed.any?
           @diagnostics.warn("#{patterns.size - missed.size} of #{patterns.size} --subject patterns matched")
@@ -113,6 +161,37 @@ module Saboteur
         subjects.select { |subject| patterns.any? { |pattern| self.class.match?(subject.id, pattern) } }
       end
 
+      # The refusal when every pattern missed (#379). A pattern naming an
+      # attribute-macro method gets the real reason - the method exists but
+      # has no body to mutate (#373) - instead of the pattern-format hint.
+      def total_miss_message(missed)
+        if missed.all? { |pattern| attribute_macro_for(pattern) }
+          return missed.map { |pattern| missed_pattern_message(pattern) }.join("; ")
+        end
+
+        "--subject #{missed.join(', ')} matches no subject (patterns are names like " \
+          "Klass, Klass#meth or Klass.meth, not globs)"
+      end
+
+      # Why one missed pattern matched nothing: when it names a method an
+      # attribute macro generated, say so (#373); otherwise the pattern
+      # itself is suspect.
+      def missed_pattern_message(pattern)
+        macro = attribute_macro_for(pattern)
+        return "--subject #{pattern} is defined by #{macro} and has no body to mutate" if macro
+
+        "fix the --subject pattern \"#{pattern}\": it matches no subject (patterns are names like " \
+          "Klass, Klass#meth or Klass.meth, not globs)"
+      end
+
+      # The attribute macro that generated the method a pattern names, if
+      # any. The files are parsed for macros once, only when a pattern
+      # missed.
+      def attribute_macro_for(pattern)
+        attributes = @attributes ||= @files.flat_map { |file| AttributeFinder.new.call(file) }
+        attributes.find { |found| found.id == pattern }&.macro
+      end
+
       def by_change(subjects, ref)
         changed = changed_subjects(subjects)
         warn_changed_files_without_subjects
@@ -188,12 +267,14 @@ module Saboteur
         return subjects if reasons.empty?
 
         constant_warned_files << canonical
-        path = file.delete_prefix("#{@root}/")
+        path = Text.display_safe(file.delete_prefix("#{@root}/"))
         listed = reasons.first(2).join(", ")
-        @diagnostics.warn("--since: constant subject(s) in #{path} are not mutated: the file runs code at " \
-                          "load (#{listed}) that every constant mutant would run again, and saboteur " \
-                          "cannot vet what re-running it does. List the constant in c.whole_file to " \
-                          "replay the file anyway, or move the literal into its own file.")
+        listed += ", and #{reasons.size - 2} more" if reasons.size > 2
+        @diagnostics.warn("#{path}: list the constant in c.whole_file to replay it anyway, or move the " \
+                          "literal into its own file\n  --since: constant subject(s) in this file are not " \
+                          "mutated: it runs code at load (#{listed}) that every constant mutant would run " \
+                          "again, and saboteur cannot vet what re-running it does. " \
+                          "#{whole_file_id_hint(rest)}")
         opted_in
       end
 
@@ -203,10 +284,36 @@ module Saboteur
         Array(@config["whole_file"]).any? { |pattern| File.fnmatch?(pattern.to_s, subject.id) }
       end
 
+      # A bare constant name only ever matches a top-level constant's id -
+      # never a nested one - so name the exact ids to copy into c.whole_file.
+      # The glob example carries its blast radius: it opts in every matching
+      # subject project-wide, so the exact id(s) are the safer pick (#635).
+      def whole_file_id_hint(subjects)
+        ids = subjects.map(&:id)
+        named = ids.first(3).map { |id| "\"#{id}\"" }.join(", ")
+        named += ", +#{ids.size - 3} more" if ids.size > 3
+        "Exact id(s): #{named} (preferred); a glob like \"*#{ids.first.split('::').last}*\" also " \
+          "works but opts in every matching subject project-wide."
+      end
+
+      # A whole_file pattern that matches nothing silently does nothing (#635):
+      # name the pattern and what subject ids look like, so a bare constant
+      # name for a nested constant (which never matches its qualified id)
+      # stands out. Scoped to this run: a pattern for a file outside the
+      # current include set also matches nothing.
+      def warn_unmatched_whole_file(subjects)
+        @config["whole_file"].each do |pattern|
+          next if subjects.any? { |subject| File.fnmatch?(pattern.to_s, subject.id) }
+
+          @diagnostics.warn("fix the whole_file entry \"#{Text.display_safe(pattern.to_s)}\": it matches no " \
+                            "discovered subject in this run (subject ids look like RULES, A::B::C or A::B#m)")
+        end
+      end
+
       def warn_unsupported_constant(found)
-        path = found.file.delete_prefix("#{@root}/")
-        @diagnostics.warn("--since: changed constant #{found.id} in #{path} is not mutated: #{found.reason}. " \
-                          "Only hash and array literal entries are mutated.")
+        path = Text.display_safe(found.file.delete_prefix("#{@root}/"))
+        @diagnostics.warn("--since: changed constant #{found.id} in #{path} is not mutated\n  " \
+                          "#{found.reason}; only hash and array literal entries are mutated")
       end
 
       # The tests that can observe a constant mutant are the ones covering a
@@ -225,9 +332,9 @@ module Saboteur
           subject.consumer_defs = reads.transform_values(&:defs)
           if subject.consumer_lines.empty? && reads.any? { |_file, r| r.load.any? }
             path = subject.file.delete_prefix("#{@root}/")
-            @diagnostics.warn("--since: changed constant #{subject.id} in #{path} is not mutated: its only " \
-                              "reads capture the value at load time in another file, so no test can " \
-                              "observe a change to it.")
+            @diagnostics.warn("--since: changed constant #{subject.id} in #{path} is not mutated\n  " \
+                              "its only reads capture the value at load time in another file, so no test " \
+                              "can observe a change to it")
             next
           end
           subject
@@ -290,11 +397,10 @@ module Saboteur
         unmatched = (@changed_lines.keys.select { |file| file.end_with?(".rb") } & included) - matched
         return if unmatched.empty?
 
-        names = unmatched.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
-        more = unmatched.size > 5 ? ", ..." : ""
+        names = Text.name_list(unmatched.map { |file| file.delete_prefix("#{@root}/") })
         note = constant_note(unmatched)
         @diagnostics.warn("--since: #{unmatched.size} changed Ruby file(s) have no subjects covering " \
-                          "the changed lines, so nothing is mutated from them: #{names}#{more}. " \
+                          "the changed lines, so nothing is mutated from them: #{names}\n  " \
                           "#{subjectless_hint(unmatched)}#{note}")
       end
 
@@ -305,7 +411,7 @@ module Saboteur
         constants = unmatched.count { |file| constant_warned_files.include?(file) }
         return "" if constants.zero?
 
-        " #{constants} of these #{constants == 1 ? 'file has' : 'files have'} changes inside " \
+        "\n  #{constants} of these #{constants == 1 ? 'file has' : 'files have'} changes inside " \
           "a constant literal that is not mutated (the constant warnings above name them)."
       end
 
@@ -318,37 +424,15 @@ module Saboteur
         embedded = unmatched.select { |file| changed_lines_inside_heredoc?(file) }
         return "The file may not parse, or every change may sit outside a method." if embedded.empty?
 
-        names = embedded.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
-        more = embedded.size > 5 ? ", ..." : ""
-        "In #{names}#{more} the changed lines are code embedded in a string (a heredoc, often the " \
+        names = Text.name_list(embedded.map { |file| file.delete_prefix("#{@root}/") })
+        "In #{names}, the changed lines are code embedded in a string (a heredoc, often the " \
           "argument to class_eval/module_eval or a template constant); methods defined by evaluating " \
           "strings are not mutation subjects, so this run cannot see that behavior."
       end
 
-      # A heredoc body is code the static subject walk cannot see: methods
-      # defined by class_eval'ing the string, or behavior living in a
-      # template constant, exist only when the string is evaluated (#467).
-      # Changed lines inside one deserve the specific warning, not the
-      # generic parse/method guess. A file that does not parse keeps the
-      # generic hint: its problem is named there already.
-      def changed_lines_inside_heredoc?(file)
-        result = Prism.parse(File.binread(file))
-        return false if result.failure?
-
-        spans = heredoc_spans(result.value)
-        @changed_lines[file].any? { |line| spans.any? { |span| span.cover?(line) } }
-      end
-
-      def heredoc_spans(node, spans = [])
-        if (node.is_a?(Prism::StringNode) || node.is_a?(Prism::InterpolatedStringNode)) &&
-           node.opening_loc&.slice&.start_with?("<<")
-          # The node location of an interpolated string stops at the opening
-          # marker; opening through closing covers the whole heredoc body.
-          spans << (node.opening_loc.start_line..node.closing_loc.end_line)
-        end
-        node.compact_child_nodes.each { |child| heredoc_spans(child, spans) }
-        spans
-      end
+      # Changed lines inside a heredoc deserve the specific warning, not the
+      # generic parse/method guess (#467); the scan lives in HeredocSpans.
+      def changed_lines_inside_heredoc?(file) = HeredocSpans.changed_lines_inside?(file, @changed_lines[file])
 
       # A changed Ruby file that an include pattern covers but c.exclude
       # removes yields zero candidates with no other sign - this repo's own
@@ -359,12 +443,11 @@ module Saboteur
         hits = excluded_territory & (@changed_lines.keys + untracked)
         return if hits.empty?
 
-        names = hits.sort.first(5).map { |file| file.delete_prefix("#{@root}/") }.join(", ")
-        more = hits.size > 5 ? ", ..." : ""
-        @diagnostics.warn("--since: #{hits.size} changed Ruby file(s) are covered by c.include but removed by " \
-                          "c.exclude, so nothing is mutated from them: #{names}#{more}. Narrow or remove the " \
-                          "c.exclude entry, or pass the file as a positional source operand (configured " \
-                          "excludes are then ignored).")
+        names = Text.name_list(hits.sort.map { |file| file.delete_prefix("#{@root}/") })
+        @diagnostics.warn("narrow or remove the c.exclude entry, or pass the file as a positional source " \
+                          "operand: #{hits.size} changed Ruby file(s) are covered by c.include but removed " \
+                          "by c.exclude\n  --since: nothing is mutated from them: #{names} (configured " \
+                          "excludes are then ignored)")
       end
 
       # Ruby files an include pattern and an exclude pattern both match,
@@ -389,10 +472,9 @@ module Saboteur
         end
         return subjects if dropped.empty?
 
-        names = dropped.first(5).map(&:id).join(", ")
-        more = dropped.size > 5 ? ", ..." : ""
+        names = Text.name_list(dropped)
         @diagnostics.inform("#{dropped.size} subject(s) skipped: intentionally untested in " \
-                            "config/saboteur_custom_map.rb: #{names}#{more}")
+                            "config/saboteur_custom_map.rb: #{names}")
         kept
       end
 
@@ -417,19 +499,17 @@ module Saboteur
       def report_deleted(deleted)
         return if deleted.empty?
 
-        names = deleted.first(5).map(&:id).join(", ")
-        more = deleted.size > 5 ? ", ..." : ""
+        names = Text.name_list(deleted)
         verb = deleted.one? ? "subject was" : "subjects were"
-        @diagnostics.inform("#{deleted.size} changed #{verb} deleted, nothing to mutate: #{names}#{more}")
+        @diagnostics.inform("#{deleted.size} changed #{verb} deleted, nothing to mutate: #{names}")
       end
 
       def report_unchanged_syntax(subjects)
         return if subjects.empty?
 
-        names = subjects.first(5).map(&:id).join(", ")
-        more = subjects.size > 5 ? ", ..." : ""
+        names = Text.name_list(subjects)
         @diagnostics.inform("#{subjects.size} changed subject(s) differ only in comments or formatting, " \
-                            "so they are skipped: #{names}#{more}")
+                            "so they are skipped: #{names}")
       end
 
       def canonical_path(file)