saboteur 0.6.0 → 0.8.0

data/lib/saboteur/constant_subject_finder.rb

@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "prism"
+require_relative "subject"
+require_relative "constant_subject"
+
+module Saboteur
+  # Finds constant assignments of hash and array literals - `RULES = { ... }`,
+  # `TAGS = [ ... ]`, with a trailing `.freeze` or a similar argument-free,
+  # block-free call - as mutation subjects for --since runs (issue #306).
+  #
+  # Unsupported forms are reported with a reason, never silently skipped: a
+  # namespaced target (`A::RULES = ...`), a conditional write
+  # (`RULES ||= ...`), and a non-literal value (a method call with
+  # arguments, another constant). Class factories (`Point = Data.define(...)`)
+  # are scopes, not data: they are reported neither way, and a constant
+  # inside the factory's block binds on the enclosing lexical scope, never
+  # on the class the factory builds (#352, mirroring SubjectFinder).
+  # Constants inside any other block are found but marked skipped, like
+  # SubjectFinder's defs, so the report names them.
+  class ConstantSubjectFinder
+    Parsed = Data.define(:subjects, :unsupported, :errors)
+
+    # A constant assignment saboteur cannot mutate, with the reason why.
+    Unsupported = Data.define(:name, :owner, :file, :node, :reason) do
+      def id
+        owner ? "#{owner}::#{name}" : name.to_s
+      end
+
+      def overlaps_lines?(lines)
+        first = node.location.start_line
+        last = node.location.end_line
+        if lines.is_a?(Range)
+          lines.begin <= last && first <= lines.end
+        else
+          lines.any? { |line| line.between?(first, last) }
+        end
+      end
+    end
+
+    CLASS_FACTORIES = SubjectFinder::CLASS_FACTORIES
+
+    # source: the text to parse when it is not the file on disk (the file as
+    # it was at an earlier commit).
+    def call(file, source: File.binread(file))
+      result = Prism.parse(source)
+      return Parsed.new(subjects: [], unsupported: [], errors: result.errors.map(&:message)) if result.failure?
+
+      ctx = { file: file, source: source, frozen: frozen_literals?(result) }
+      out = { subjects: [], unsupported: [], ambiguous: [] }
+      walk(result.value, [], out, **ctx)
+      reject_duplicates(out, **ctx)
+      demote_ambiguous(out, **ctx)
+      Parsed.new(subjects: out[:subjects], unsupported: out[:unsupported], errors: [])
+    end
+
+    private
+
+    # More than one write of the same constant in one file: re-evaluating
+    # the file runs them all, the later one always wins, and a mutant of
+    # any earlier literal is never observed. EVERY write counts - a guarded
+    # or non-literal second write (`RULES = {a: 1}; RULES = build_rules`)
+    # overwrites the first just the same (#319).
+    def reject_duplicates(out, **ctx)
+      writes = Hash.new(0)
+      (out[:subjects] + out[:unsupported]).each { |entry| writes[entry.id] += 1 }
+      duplicates = out[:subjects].select { |subject| writes[subject.id] > 1 }
+      return if duplicates.empty?
+
+      out[:subjects] -= duplicates
+      duplicates.each do |subject|
+        out[:unsupported] << Unsupported.new(name: subject.name, owner: subject.owner, file: ctx[:file],
+                                             node: subject.node,
+                                             reason: "assigned more than once in this file")
+      end
+    end
+
+    def frozen_literals?(result)
+      result.magic_comments.any? do |comment|
+        comment.key.tr("-", "_").casecmp?("frozen_string_literal") && comment.value.casecmp?("true")
+      end
+    end
+
+    def walk(node, nesting, out, **ctx)
+      return if node.nil?
+
+      case node
+      when Prism::BlockNode, Prism::LambdaNode
+        walk(node.body, nesting, out, **ctx, in_block: true)
+      when Prism::ConstantWriteNode
+        constant_assignment(node, nesting, out, **ctx)
+      when Prism::IfNode, Prism::UnlessNode
+        walk_conditional(node, nesting, out, **ctx)
+      when Prism::ConstantOrWriteNode, Prism::ConstantAndWriteNode
+        record_unsupported(out, node, nesting, "a conditional assignment (#{node.operator_loc.slice})", **ctx)
+        walk_children(node, nesting, out, **ctx)
+      when Prism::ConstantPathWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathAndWriteNode
+        record_unsupported(out, node, nesting, "a namespaced target (#{node.target.slice})", **ctx)
+        walk_children(node, nesting, out, **ctx)
+      # A keyword class or module re-enters the lexical scope: its constants
+      # are ordinary subjects even inside a block, and factory scopes never
+      # join their paths (#352).
+      when Prism::ModuleNode, Prism::ClassNode
+        kind = node.is_a?(Prism::ModuleNode) ? :module : :class
+        scope = Scope.new(kind: kind, path: node.constant_path.slice)
+        walk(node.body, lexical_nesting(nesting) + [scope], out, **ctx, in_block: false)
+      when Prism::SingletonClassNode
+        walk_singleton_class(node, nesting, out, **ctx)
+      else
+        walk_children(node, nesting, out, **ctx)
+      end
+    end
+
+    # A write under a condition may never run: mutating its literal cannot
+    # change the constant when the guard skips the write (#319).
+    def walk_conditional(node, nesting, out, **ctx)
+      walk(node.predicate, nesting, out, **ctx)
+      walk(node.statements, nesting, out, **ctx, guarded: true)
+      walk(node.respond_to?(:subsequent) ? node.subsequent : node.else_clause, nesting, out, **ctx,
+           guarded: true)
+    end
+
+    def walk_children(node, nesting, out, **ctx)
+      node.compact_child_nodes.each { |child| walk(child, nesting, out, **ctx) }
+    end
+
+    # `class << self` opens the attached class's singleton scope: constants
+    # assigned there bind on the singleton class, so the scope joins the
+    # nesting and owner_path renders it "<attached>.singleton_class" (#380,
+    # mirroring SubjectFinder). Unlike a keyword class, `class << self`
+    # does not reset in_block: a block's runtime self is unknowable at
+    # parse time (an `included do` block runs with the including class as
+    # self), so its constants stay conservatively skipped inside a block.
+    # A non-self receiver, a nested singleton class or the top level has no
+    # statically nameable singleton: the enclosing nesting stays.
+    def walk_singleton_class(node, nesting, out, **ctx)
+      unless node.expression.is_a?(Prism::SelfNode) && nesting.any? && !nesting.last.sclass?
+        return walk_children(node, nesting, out, **ctx)
+      end
+
+      walk(node.body, nesting + [Scope.new(kind: :sclass, path: "self")], out, **ctx)
+    end
+
+    def constant_assignment(node, nesting, out, **ctx)
+      return walk_factory(node, nesting, out, **ctx) if factory_scope?(node)
+
+      literal = literal_value(node.value)
+      reason = unsupported_reason(node, literal, **ctx)
+      if reason
+        record_unsupported(out, node, nesting, reason, **ctx)
+        walk_children(node, nesting, out, **ctx)
+        return
+      end
+
+      subject = ConstantSubject.new(name: node.name, owner: owner_path(nesting), file: ctx[:file], node: node,
+                                    literal_node: literal, file_source: ctx[:source], nesting: nesting,
+                                    frozen_literals: ctx[:frozen])
+      subject.skip_reason = "defined inside a block" if ctx[:in_block]
+      out[:subjects] << subject
+      # Another constant can hide in the literal's values (`MAP = { x: (Y = []) }`).
+      walk_children(node, nesting, out, **ctx)
+    end
+
+    # `Point = Data.define(:x) do ... end`: the receiver and arguments stay
+    # in the enclosing scope. The block's body is walked directly, not as a
+    # block, and the factory opens no lexical constant scope: a constant
+    # inside the block binds on the enclosing lexical scope and is an
+    # ordinary subject (#352, mirroring SubjectFinder).
+    def walk_factory(node, nesting, out, **ctx)
+      call = node.value
+      (call.compact_child_nodes - [call.block]).each { |child| walk(child, nesting, out, **ctx) }
+      walk(call.block.body, lexical_nesting(nesting) + [Scope.new(kind: :factory, path: node.name.to_s)], out, **ctx)
+    end
+
+    # A factory scope names the class being built but opens no lexical
+    # constant scope, so it never joins a constant's path (#339).
+    def lexical_nesting(nesting)
+      nesting.reject(&:factory?)
+    end
+
+    def unsupported_reason(_node, literal, guarded: false, **)
+      return "guarded by a condition" if guarded
+      return "its value is not a hash or array literal" if literal.nil?
+
+      nil
+    end
+
+    # `Point = Data.define(...) do ... end`: only the four core factories
+    # count, called on the bare constant (mirrors SubjectFinder).
+    def factory_scope?(node)
+      call = node.value
+      return false unless call.is_a?(Prism::CallNode) && call.block.is_a?(Prism::BlockNode)
+      return false unless call.receiver.is_a?(Prism::ConstantReadNode)
+
+      CLASS_FACTORIES[call.receiver.name] == call.name
+    end
+
+    # The hash or array literal behind the value, looking through `.freeze`
+    # calls only: any other receiver chain transforms the value, so the
+    # literal is not what the constant holds.
+    def literal_value(value)
+      value = value.receiver while value.is_a?(Prism::CallNode) && value.name == :freeze &&
+                                   value.arguments.nil? && value.block.nil? && value.receiver
+      value if value.is_a?(Prism::HashNode) || value.is_a?(Prism::ArrayNode)
+    end
+
+    def record_unsupported(out, node, nesting, reason, **ctx)
+      # A bare target takes the lexical owner. A ROOTED qualified target names
+      # its constant absolutely ("::RULES" is RULES anywhere). An UNROOTED one
+      # resolves through the lexical scope: "Shop::RULES" inside
+      # `module Outer; module Shop` writes Outer::Shop::RULES. Every id on the
+      # write's scope chain is a candidate, so each goes on the ambiguous list
+      # for demotion after the walk; over-matching only demotes a subject.
+      if node.respond_to?(:name)
+        name = node.name
+        owner = owner_path(nesting)
+      else
+        name = node.target.slice.sub(/\A::/, "")
+        owner = nil
+        unless node.target.slice.start_with?("::")
+          nesting.length.downto(0) do |depth|
+            prefix = owner_path(nesting[0...depth])
+            out[:ambiguous] << (prefix ? "#{prefix}::#{name}" : name)
+          end
+        end
+      end
+      out[:unsupported] << Unsupported.new(name: name, owner: owner, file: ctx[:file],
+                                           node: node, reason: reason)
+    end
+
+    # A subject whose id an unrooted qualified write may resolve to cannot be
+    # mutated safely: replaying the file lets that write overwrite it.
+    def demote_ambiguous(out, **ctx)
+      return if out[:ambiguous].empty?
+
+      poisoned = out[:subjects].select { |subject| out[:ambiguous].include?(subject.id) }
+      out[:subjects] -= poisoned
+      poisoned.each do |subject|
+        out[:unsupported] << Unsupported.new(name: subject.name, owner: subject.owner, file: ctx[:file],
+                                             node: subject.node,
+                                             reason: "an unrooted qualified write may overwrite it")
+      end
+    end
+
+    # Lexical path of the enclosing class/module, or nil at the top level.
+    # A singleton-class scope renders as "<attached>.singleton_class":
+    # constants assigned in `class << self` bind on the singleton class,
+    # not on the attached class (#380). Factory scopes open no lexical
+    # constant scope, but a factory's block is class_eval'd, so a `class <<
+    # self` directly inside one attaches to the factory's class.
+    def owner_path(nesting)
+      return nil if nesting.empty?
+
+      parts = []
+      factory_path = nil
+      nesting.each do |scope|
+        if scope.sclass?
+          # `self` is the innermost named scope: the factory's class inside a
+          # factory block (its block is class_eval'd), the attached class or
+          # module otherwise.
+          if factory_path
+            # factory_path carries the full prefix already: replace, never
+            # append, or the enclosing scope doubles (#395).
+            parts = ["#{factory_path}.singleton_class"]
+          elsif parts.any?
+            parts[-1] = "#{parts.last}.singleton_class"
+          end
+          factory_path = nil
+        elsif scope.factory?
+          factory_path = (parts + [scope.path.delete_prefix("::")]).join("::")
+        else
+          parts.clear if scope.path.start_with?("::")
+          parts << scope.path.delete_prefix("::")
+          factory_path = nil
+        end
+      end
+      parts.empty? ? nil : parts.join("::")
+    end
+  end
+end

data/lib/saboteur/coverage_reads.rb

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # Every Coverage.result read goes through here. With the methods report
+  # on, the C call hashes each method owner and trusts the return type, so
+  # a loaded class whose `hash` does not return an Integer (forem's
+  # ReactionCategory, #564) makes every read raise TypeError - a "please
+  # report it" crash for what is a bug in the application's code. Refuse
+  # instead. The handler runs no app code (an ObjectSpace scan would call
+  # #hash/#name on hostile classes) and the error's backtrace names no
+  # owning class, so the message stays generic rather than accusing one.
+  module CoverageReads
+    module_function
+
+    def result(stop:, clear:)
+      Coverage.result(stop:, clear:)
+    rescue TypeError => e
+      raise Error, diagnostic(e)
+    end
+
+    def diagnostic(error)
+      "Coverage.result raised TypeError (#{error.message}): Coverage's method report hashes every " \
+        "method owner and trusts the result, and a loaded class whose #hash does not return an " \
+        "Integer (Ruby's #hash contract) breaks it. This is a bug in the application's code, " \
+        "not in saboteur."
+    end
+  end
+end

data/lib/saboteur/crash_report.rb

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+require "pathname"
+
+module Saboteur
+  # Last-resort crash reporting, shared by the CLI's StandardError rescue
+  # and the exe-level wrapper: one bounded line on stderr, the full
+  # backtrace in a log file the line names, the backtrace on stderr with
+  # --verbose, and the same failure as agent JSON when an agent listens.
+  # Always returns EXIT_TOOL.
+  module CrashReport
+    ISSUES_URL = "https://github.com/vamsipavanmahesh/saboteur/issues"
+
+    # Same value as CLI::EXIT_TOOL, kept local so the reporter still works
+    # when the CLI itself never finished loading.
+    EXIT_TOOL = 3
+
+    # The crash log's file name under the run's cache dir; the runner reads
+    # it back to explain a nested run's crash in the failure detail (#296).
+    LOG_NAME = "internal-error.log"
+
+    module_function
+
+    def call(error, verbose:, agent:, err:, out:, log_path: nil)
+      summary = "internal error (#{error.class}: #{one_line(error.message)})"
+      line = "saboteur: #{summary} - please report it: #{ISSUES_URL}"
+      written = write_log(log_path, error)
+      line = "#{line}; full backtrace: #{display_path(written)}" if written
+      err.puts(line)
+      err.puts(full_text(error)) if verbose
+      out.print(agent_json(summary)) if agent
+      EXIT_TOOL
+    end
+
+    # A crash message can span lines or carry bytes that are invalid in
+    # UTF-8 (a LANG=C failure, say); the one-line diagnostic must survive
+    # both, and stay one bounded line.
+    def one_line(message)
+      text = scrub(message).gsub(/\s+/, " ").strip
+      text.length > 160 ? "#{text[0...160]}..." : text
+    end
+
+    # Class, full message and backtrace, scrubbed so locale-invalid bytes
+    # cannot corrupt the log or the terminal.
+    def full_text(error)
+      (["#{error.class}: #{scrub(error.message)}"] + Array(error.backtrace).map { |frame| scrub(frame) }).join("\n")
+    end
+
+    # Writes the log next to the other run state; returns the written path,
+    # or nil when the log cannot be written - the crash itself must still
+    # be reported, so an unwritable directory is not a second failure.
+    # Reporter::Agent.failure's payload, reproduced minimally for crashes
+    # before the CLI's reporter files load: same schema and pretty rendering;
+    # the summary is already normalized, so no message cap is needed here.
+    def agent_json(summary)
+      payload =
+        if defined?(Reporter::Agent)
+          Reporter::Agent.failure(summary, EXIT_TOOL)
+        else
+          { version: 1, status: "error", verdict: "tool_failure", exitCode: EXIT_TOOL,
+            message: summary, next: { help: "saboteur help run" } }
+        end
+      "#{JSON.pretty_generate(payload)}\n"
+    end
+
+    def write_log(log_path, error)
+      return nil unless log_path
+
+      # The primary path is user-configured but still predictable: without
+      # O_NOFOLLOW a planted symlink would redirect the truncate/chmod, and
+      # without O_NONBLOCK a planted FIFO would block the open. Where the
+      # platform lacks either, only the EXCL-created temp fallback is safe
+      # (#296).
+      if safe_log_io?
+        begin
+          FileUtils.mkdir_p(File.dirname(log_path))
+          # Private like the temp fallback: the runner only reads logs with
+          # no group/other bits, from the same no-follow fd (#296).
+          flags = File::CREAT | File::WRONLY | File::TRUNC | nofollow_flag | nonblock_flag
+          File.open(log_path, flags, 0o600) do |file|
+            file.chmod(0o600)
+            file.write("#{full_text(error)}\n")
+          end
+          return log_path
+        rescue SystemCallError, IOError
+          # Fall through to the temp fallback.
+        end
+      end
+      write_tmp_log(error)
+    end
+
+    # The fallback is computed lazily, only once the primary write failed:
+    # an eager tmp_log_path call could itself raise (Dir.tmpdir finds no
+    # usable dir) and mask the crash it was meant to log (#296).
+    #
+    # The fallback path is predictable and lives in a shared directory, so
+    # it is created privately: CREAT|EXCL|WRONLY|NOFOLLOW never follows or
+    # overwrites a pre-existing file or symlink, and the mode pins the log
+    # to 0600. A taken or hostile path means no log - the crash report
+    # itself must still go out, so every failure here degrades to nil.
+    def write_tmp_log(error)
+      File.open(tmp_log_path, File::CREAT | File::EXCL | File::WRONLY | nofollow_flag, 0o600) do |file|
+        file.write("#{full_text(error)}\n")
+      end
+      tmp_log_path
+    rescue SystemCallError, IOError, ArgumentError
+      nil
+    end
+
+    # O_NOFOLLOW where the platform has it (every CI target does).
+    def nofollow_flag
+      File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0
+    end
+
+    # O_NONBLOCK where the platform has it (every CI target does).
+    def nonblock_flag
+      File.const_defined?(:NONBLOCK) ? File::NONBLOCK : 0
+    end
+
+    # The private crash-log write/read needs both flags: without O_NOFOLLOW
+    # a planted symlink redirects the open, without O_NONBLOCK a planted
+    # FIFO blocks it. Where either is missing, the log is omitted rather
+    # than opened unsafely (#296).
+    def safe_log_io?
+      File.const_defined?(:NOFOLLOW) && File.const_defined?(:NONBLOCK)
+    end
+
+    # Where the log lands when a configured cache dir is not writable - a
+    # sandboxed child holds the project read-only, but the system temp dir is
+    # granted (#296). Only a configured log path falls back: cache_dir = nil
+    # still means no log at all. Keyed by pid so parallel children never
+    # share a file; the runner reads the same path back in the same process.
+    def tmp_log_path(pid: Process.pid)
+      File.join(Dir.tmpdir, "saboteur-#{pid}-#{LOG_NAME}")
+    end
+
+    # The message names the log; relative to the working directory when it
+    # sits inside it, so the line stays short.
+    def display_path(path)
+      relative = Pathname(path).relative_path_from(Pathname(Dir.pwd)).to_s
+      relative.start_with?("..") ? path : relative
+    rescue ArgumentError
+      path
+    end
+
+    def scrub(string)
+      string.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?")
+    end
+  end
+end

data/lib/saboteur/custom_map.rb

@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: MIT
 # frozen_string_literal: true
 
+require_relative "text"
+
 module Saboteur
   # Explicit source-file -> spec-file mapping from config/saboteur_custom_map.rb:
   #
@@ -109,7 +111,7 @@ module Saboteur
     def duplicate_keys(path)
       seen = Hash.new(0)
       File.readlines(path).each do |line|
-        seen[::Regexp.last_match(1)] += 1 if line =~ /^\s*"(.+?)"\s*=>/
+        seen[::Regexp.last_match(1)] += 1 if Text.utf8(line) =~ /^\s*"(.+?)"\s*=>/
       end
       seen.select { |_, count| count > 1 }.keys
     end

data/lib/saboteur/dirty_tree_warning.rb

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# frozen_string_literal: true
+
+module Saboteur
+  # The warning shown before a run on a tree with uncommitted changes
+  # (#309, #316). Mutants run your code and can change the tree, so the
+  # warning stays; it splits the raw count so a tree full of notes or trial
+  # setup files does not read like application edits about to be mutated.
+  #
+  # Each change lands in exactly one group, so the groups add up to the
+  # count: saboteur setup files first (the config file the run reads, a
+  # trial Gemfile and its lock), then the mutation scope (a file the
+  # configured include and exclude select, the way Config#included_files
+  # does), then the rest. A path the patterns match also counts, so a
+  # deleted source is still inside the scope. The scope is the configured
+  # one: --since, --subject and source operands narrow a run further, after
+  # this warning.
+  class DirtyTreeWarning
+    SHOWN_PATHS = 5
+    MATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+    ADVICE = "Mutants run your code and could alter or delete files; " \
+             "run on a clean, committed tree or a CI checkout."
+
+    # The warning text for the run's working tree, or nil on a clean or
+    # unknown tree. The root is physical (realpath), like the paths
+    # Config#included_files returns.
+    def self.for(config, config_path:, gemfile: ENV.fetch("BUNDLE_GEMFILE", nil))
+      state = WorkingTree.new(config.root, ignored: config.output_paths).state
+      root = File.realpath(config.root)
+      new(state, included: relative(config.included_files, root), include: config["include"],
+                 exclude: config["exclude"], root: root,
+                 setup_files: setup_files(root, config_path: config_path, gemfile: gemfile)).to_s
+    end
+
+    # Files a trial of saboteur adds, relative to the root: the config file
+    # the run reads and, when BUNDLE_GEMFILE names a Gemfile other than the
+    # root's own, that Gemfile and its lock. Each file is compared by its
+    # physical path, so a /var spelling of a /private/var root still
+    # matches (#503).
+    def self.setup_files(root, config_path:, gemfile:)
+      files = [physical(File.expand_path(config_path || Config::FILE, root))]
+      trial = gemfile && physical(File.expand_path(gemfile, root))
+      files.push(trial, lockfile_for(trial)) if trial && trial != File.join(root, "Gemfile")
+      relative(files, root)
+    end
+
+    # Bundler's own rule, the same one preflight's execution inputs check
+    # against Bundler.default_lockfile: a gems.rb trial locks to gems.locked
+    # next to it; every other name gets ".lock" appended.
+    def self.lockfile_for(gemfile)
+      return File.join(File.dirname(gemfile), "gems.locked") if File.basename(gemfile) == "gems.rb"
+
+      "#{gemfile}.lock"
+    end
+
+    # git status paths are relative to the root, so the patterns are too:
+    # Dir.glob accepts a leading ./ or an absolute path under the root and
+    # File.fnmatch? does not (#503). A pattern outside the root stays
+    # absolute and matches no git path.
+    def self.relative_patterns(patterns, root)
+      patterns.map { |pattern| File.expand_path(pattern, root).delete_prefix(File.join(root, "")) }
+    end
+
+    # The path with its directory resolved, so a file that does not exist
+    # yet still gets the physical spelling of where it would be.
+    def self.physical(path)
+      File.join(File.realpath(File.dirname(path)), File.basename(path))
+    rescue SystemCallError
+      path
+    end
+
+    # A file outside the root keeps its absolute path, which no
+    # root-relative git path can equal.
+    def self.relative(files, root)
+      prefix = File.join(root, "")
+      files.map { |file| file.delete_prefix(prefix) }
+    end
+
+    private_class_method :physical, :relative
+
+    def initialize(state, included:, include:, exclude:, setup_files:, root:)
+      @state = state
+      @included = included.to_set
+      @include = self.class.relative_patterns(include, root)
+      @exclude = self.class.relative_patterns(exclude, root)
+      @setup_files = setup_files
+    end
+
+    def to_s
+      return unless @state.dirty
+
+      setup, rest = @state.changes.partition { |change| @setup_files.include?(change.path) }
+      scope, outside = rest.partition { |change| in_scope?(change.path) }
+      [summary(setup, scope, outside), named("inside the mutation scope", scope), named("setup files", setup),
+       "  #{ADVICE}"].compact.join("\n")
+    end
+
+    private
+
+    def summary(setup, scope, outside)
+      groups = [scope.empty? ? "none inside the mutation scope" : counted("inside the mutation scope", scope),
+                counted("outside it", outside)]
+      groups << counted("saboteur setup file(s)", setup) unless setup.empty?
+      "saboteur: warning: #{@state.changed_files} uncommitted change(s) in the working tree: #{groups.join(', ')}."
+    end
+
+    def counted(label, changes)
+      tracked = changes.count(&:tracked)
+      "#{changes.size} #{label} (#{tracked} tracked, #{changes.size - tracked} untracked)"
+    end
+
+    def named(label, changes)
+      return if changes.empty?
+
+      paths = changes.first(SHOWN_PATHS).map(&:path).join(", ")
+      more = changes.size - SHOWN_PATHS
+      "  #{label}: #{paths}#{" and #{more} more" if more.positive?}"
+    end
+
+    def in_scope?(path)
+      @included.include?(path) || (path.end_with?(".rb") && matches?(@include, path) && !matches?(@exclude, path))
+    end
+
+    def matches?(patterns, path)
+      patterns.any? { |pattern| File.fnmatch?(pattern, path, MATCH_FLAGS) }
+    end
+  end
+end