saboteur 0.7.0 → 0.8.0

data/lib/saboteur/engine/test_guess.rb

@@ -6,7 +6,9 @@ require "pathname"
 module Saboteur
   class Engine
     # The specs that sit next to the mutated source files by
-    # naming convention (lib/a/b.rb -> spec/a/b_spec.rb). A guess, not a
+    # naming convention (lib/a/b.rb -> spec/a/b_spec.rb), or the explicit
+    # mapping from config/saboteur_custom_map.rb for layouts the convention
+    # cannot guess (#369). A guess, not a
     # coverage fact: a spec that only reaches the file through another one
     # is not found. Packwerk packs (a directory with a package.yml) map to the
     # spec directory inside the same pack, and controllers also map to request
@@ -19,39 +21,118 @@ module Saboteur
       # not exist; that is why the file is unmatched), for the stop-before-boot
       # error. The result also builds its own messages, so a stubbed guess in
       # the engine's specs formats exactly like a real one.
-      Result = Data.define(:specs, :unmatched, :subjectless, :changed, :hints) do
+      # changed_specs: spec files the diff adds or changes that run, already
+      # in specs; skipped_specs: spec files the diff touches that cannot run,
+      # each with the reason.
+      Result = Data.define(:specs, :unmatched, :subjectless, :changed, :hints, :changed_specs,
+                           :skipped_specs, :out_of_scope, :excluded, :near) do
+        def initialize(changed_specs: [], skipped_specs: {}, out_of_scope: [], excluded: [], near: {}, **fields)
+          super
+        end
+
         # The stop-before-boot usage error: names each expected spec and the
         # ways out as an append-only instruction - never a reconstructed
         # command, which could carry a hostile ref or a wrong source scope.
+        # When the diff deleted the expected spec or added others, it says
+        # so: a renamed spec is the usual cause.
         def unmatched_message
-          pairs = unmatched.map { |file| "#{file} (expected #{hints.fetch(file)})" }
-          "no spec found for #{pairs.join(', ')}, so nothing ran. Re-run the same command with --test " \
-            "followed by your existing spec paths, or append --all to use the whole suite without " \
+          pairs = unmatched.map { |file| pair_description(file) }
+          changed = changed_specs.any? ? " Specs the diff adds or changes: #{changed_specs.join(', ')}." : ""
+          "no spec found for #{pairs.join(', ')}, so nothing ran.#{changed} Re-run the same command with " \
+            "one --test per existing spec path, or append --all to use the whole suite without " \
             "changing the source scope."
         end
 
+        private
+
+        def pair_description(file)
+          expected = hints.fetch(file)
+          gone = skipped_specs[expected] == DELETED ? ", deleted in the diff" : ""
+          found = near.fetch(file, []).any? ? "; found: #{near.fetch(file).join(', ')}" : ""
+          "#{file} (expected #{expected}#{gone}#{found})"
+        end
+
+        public
+
+        # The spec files the diff touched that do not run, with the reasons.
+        def skipped_message
+          named = skipped_specs.map { |path, reason| "#{path} (#{reason})" }
+          "inferred specs: not running spec files changed in the diff: #{named.join(', ')}"
+        end
+
         # Why the subjectless files needed no spec.
         def subjectless_message(since:)
           detail = since ? "no changed mutation subjects" : "no mutation subjects"
           "inferred specs: no spec is required for #{subjectless.join(', ')}: they have #{detail}"
         end
 
+        # The per-file warning when the run proceeds with the mapped
+        # subset (#370): the file's mutants run only against the inferred
+        # specs, so lines nothing else covers surface as NoCoverage.
+        def unmatched_warning(file)
+          "inferred specs: no spec found for #{pair_description(file)}; its mutants run only " \
+            "against the inferred specs and a line they miss is reported as NoCoverage"
+        end
+
+        # The stop for a --since run whose changed source files all sit outside the
+        # include scope (#483): falling back to the whole suite would run the slowest
+        # possible suite against zero subjects, so the run refuses and names what the
+        # scope hid. Append-only recovery, like unmatched_message: extend include, or
+        # name the specs with --test.
+        def out_of_scope_message
+          named = out_of_scope.first(10).join(", ")
+          more = out_of_scope.size - 10
+          named += " and #{more} more" if more.positive?
+          "no changed source file lies inside the include scope, so nothing ran. " \
+            "Changed source files outside it: #{named}. Extend include to cover them, " \
+            "or re-run the same command with one --test per existing spec path."
+        end
+
+        # Why an empty guess mutates nothing rather than widening the run
+        # to the whole suite (#369).
+        def no_specs_message(since:)
+          return "#{excluded_message}, so there is nothing to mutate" if excluded.any?
+
+          if since
+            "inferred specs: no changed file has a mutation subject on its changed lines, " \
+              "so there is nothing to mutate"
+          else
+            "inferred specs: no source file has a mutation subject, so there is nothing to mutate"
+          end
+        end
+
+        # Why the custom-map-excluded files needed no spec (#369).
+        def excluded_message
+          "inferred specs: no spec is required for #{excluded.join(', ')}: " \
+            "intentionally untested in config/saboteur_custom_map.rb"
+        end
+
         # The warning for a guess-scoped run: the guessed specs now stand as
         # explicit tests, with the cross-file coverage caveat that brings.
         def scope_message(since:)
-          what = since ? "a changed file" : "a source file"
-          "inferred specs: running only #{specs.join(', ')}. A spec that reaches " \
-            "#{what} only through another file does not run, so a mutant only it would kill can " \
-            "survive, and a line no inferred spec executes is reported as NoCoverage"
+          who = since ? SINCE_CAVEAT_SUBJECT : CAVEAT_SUBJECT
+          added = changed_specs.any? ? " (changed in the diff: #{changed_specs.join(', ')})" : ""
+          "inferred specs: running only #{specs.join(', ')}#{added}. #{who} only through another file " \
+            "does not run, so a mutant only it would kill can survive, and a line no inferred spec " \
+            "executes is reported as NoCoverage"
         end
       end
 
+      CAVEAT_SUBJECT = "A spec that reaches a source file"
+      SINCE_CAVEAT_SUBJECT = "A spec the diff did not change that reaches a changed file"
       SOURCE_ROOTS = %w[lib app].freeze
+      DELETED = "deleted in the diff"
+      OUTSIDE_SUITE = "not loaded by the configured RSpec suite: its pattern, exclude pattern or default path " \
+                      "leaves it out"
+      NOT_REGULAR = "not a regular file"
 
-      def initialize(config, diagnostics: nil)
+      def initialize(config, diagnostics: nil, custom_map: nil)
         @diagnostics = diagnostics
-        @root = File.realpath(config.root)
+        # Retagged losslessly like Config#root, so a join with a UTF-8 git
+        # path never mixes encodings whatever the locale tagged it with.
+        @root = Text.utf8_identity(File.realpath(config.root))
         @config = config
+        @custom_map = custom_map || CustomMap.load(config.path("custom_map"), root: config.root)
       end
 
       def call
@@ -71,10 +152,13 @@ module Saboteur
       end
 
       # specs: existing spec files (relative paths) guessed for the files in
-      # scope; unmatched: such files with no guessed spec; subjectless: files
-      # with no mutation subject the run checks, which neither need nor get a
-      # spec; changed: how many source files are in scope; hints: each
-      # unmatched file's conventional spec path.
+      # scope, plus every spec file the diff adds or changes (#307): a pull
+      # request often tests a change through a request or controller spec
+      # whose name maps to no changed file. unmatched: such files with no
+      # guessed spec; subjectless: files with no mutation subject the run
+      # checks, which neither need nor get a spec; changed: how many source
+      # files are in scope; hints: each unmatched file's conventional spec
+      # path.
       def call_diff
         lines_by_file = changed_lines_by_file
         subjectless = subjectless_files(lines_by_file)
@@ -82,7 +166,9 @@ module Saboteur
         # subjectless file mutates nothing, so its spec would only narrow the
         # run for no reason.
         guesses = lines_by_file.except(*subjectless).to_h { |file| [file, guess_for(file)] }
-        result(guesses, subjectless, lines_by_file.size)
+        # Nothing in scope: name the changed source the include hid (#483).
+        out_of_scope = lines_by_file.empty? ? out_of_scope_source_files : []
+        result(guesses, subjectless, lines_by_file.size, out_of_scope: out_of_scope)
       end
 
       # Without --since every included file is in scope: a file needs its
@@ -110,11 +196,12 @@ module Saboteur
         lines_by_file = changed_lines_by_file
         comparison = UnchangedSyntax.new(Selection::GitDiff.merge_base(@config["since"], root: @root), root: @root)
         finder = SubjectFinder.new
+        constant_finder = ConstantSubjectFinder.new
         files.select do |file|
           lines = lines_by_file[file]
           next false unless lines
 
-          finder.call(File.join(@root, file)).subjects.any? do |subject|
+          subjects_in(finder, constant_finder, file).any? do |subject|
             patterns.any? { |pattern| SubjectSelection.match?(subject.id, pattern) } &&
               subject.overlaps_lines?(lines) &&
               !comparison.unchanged?(subject)
@@ -122,13 +209,146 @@ module Saboteur
         end
       end
 
-      def result(guesses, subjectless, changed)
-        unmatched = guesses.select { |_, spec| spec.nil? }.keys
-        Result.new(specs: guesses.values.compact.uniq.sort,
+      # Changed specs join only a run that mutates something: with no file
+      # in scope there is nothing for them to kill.
+      def result(guesses, subjectless, changed, out_of_scope: [])
+        unmatched = guesses.select { |_, specs| specs.nil? }.keys
+        excluded = guesses.select { |_, specs| specs == :excluded }.keys.sort
+        inferred = guesses.values.grep(Array).flatten
+        diff = @config["since"] && guesses.any? ? specs_in_diff(inferred) : { run: [], skipped: {} }
+        unmatched -= covered_by_changed_specs(unmatched, diff[:run])
+        Result.new(specs: (inferred + diff[:run]).uniq.sort,
                    unmatched: unmatched,
                    subjectless: subjectless,
                    changed: changed,
-                   hints: unmatched.to_h { |file| [file, candidates_for(file).first] })
+                   hints: unmatched.to_h { |file| [file, expected_spec(file, diff[:skipped])] },
+                   near: unmatched.to_h { |file| [file, nearby_specs(file)] },
+                   changed_specs: diff[:run],
+                   skipped_specs: diff[:skipped],
+                   out_of_scope: out_of_scope,
+                   excluded: excluded)
+      end
+
+      # Changed Ruby files the include scope hides (#483), relative to the
+      # root: the diff touched source, but none of it lands inside include.
+      # A changed spec is a test, not hidden source; a spec-only diff keeps
+      # the whole-suite fallback it always had.
+      def out_of_scope_source_files
+        included = included_files.to_set
+        Selection::GitDiff.changed_paths(@config["since"], root: @root)[:present]
+                          .select { |path| path.end_with?(".rb") && !spec?(path) && !included.include?(path) }
+      end
+
+      # Spec files under the root that the diff since the base adds, changes
+      # or deletes. A changed file runs when the configured suite loads it
+      # and it is a regular file; RSpec applies its pattern only to the
+      # directories it scans, never to a file named as a test, so the suite's
+      # own list decides (a fixture under an excluded directory must not
+      # run). A changed *_spec.rb that cannot run is named with the reason.
+      # An inferred spec is left to inference, which runs it as before
+      # #307, so it is neither added again nor reported as skipped.
+      def specs_in_diff(inferred)
+        paths = Selection::GitDiff.changed_paths(@config["since"], root: @root)
+        skipped = paths[:deleted].select { |path| spec?(path) }.to_h { |path| [path, DELETED] }
+        candidates = paths[:present] - inferred
+        run = candidates.select { |path| spec?(path) || in_suite?(path) }.select do |path|
+          reason = unrunnable_reason(path)
+          skipped[path] = reason if reason
+          reason.nil?
+        end
+        { run: run, skipped: skipped.sort.to_h }
+      end
+
+      # A consolidated spec (claims_spec.rb style) never matches the
+      # per-file guess, but when the diff itself changes that spec and the
+      # spec reads a constant the unmatched file defines, the file is
+      # covered: the spec already runs via changed_specs, so stopping would
+      # block a run that had something to kill (#538). A mutable change no
+      # changed spec exercises still stops.
+      def covered_by_changed_specs(unmatched, changed_specs)
+        return [] if unmatched.empty? || changed_specs.empty?
+
+        specs = changed_specs.map { |path| File.join(@root, path) }
+        unmatched.select do |file|
+          defined_constants(file).any? { |constant| ConstantReads.across(specs, constant).any? }
+        end
+      end
+
+      # The constants a file defines: owners of its def subjects
+      # ("JWT::Claims::DecodeVerifier" from "...#call") and its constant
+      # literal subjects. Shaped for ConstantReads, which matches a bare
+      # read under the owner's scope or the constant's full path.
+      DefinedConstant = Data.define(:name, :owner, :id)
+
+      def defined_constants(file)
+        path = File.join(@root, file)
+        owners = SubjectFinder.new.call(path).subjects.filter_map { |subject| subject.id.split(/[#.]/).first }
+        literals = ConstantSubjectFinder.new.call(path).subjects.map(&:id)
+        (owners + literals).uniq.map do |id|
+          owner, _, name = id.rpartition("::")
+          DefinedConstant.new(name: name.to_sym, owner: owner.empty? ? nil : owner, id: id)
+        end
+      end
+
+      # The spec the stop names for an unmatched file: a candidate the diff
+      # deleted (a renamed request spec is not always the first), else the
+      # most specific one.
+      def expected_spec(file, skipped)
+        candidates = candidates_for(file)
+        candidates.find { |path| skipped[path] == DELETED } || candidates.first
+      end
+
+      # Existing spec files with the same basename anywhere under the spec
+      # root: the stop and the warning point at them so the user can
+      # --test without hunting (#370). Bounded; computed only for
+      # unmatched files, which are about to stop or warn.
+      def nearby_specs(file)
+        # The basename is data, not a pattern: [, ], {, }, ?, * and \ are
+        # glob metacharacters and must be escaped to match literally.
+        basename = File.basename(file, ".rb").gsub(/[\[\]{}?*\\]/) { |char| "\\#{char}" }
+        Dir.glob("spec/**/#{basename}_spec.rb", base: @root)
+           .select { |path| File.file?(File.join(@root, path)) }.sort.first(3)
+      end
+
+      # lstat, not stat: a symlink can point anywhere, including a spec of
+      # another application or a fixture the suite excludes.
+      def unrunnable_reason(path)
+        return NOT_REGULAR unless File.lstat(File.join(@root, path)).file?
+        return @suite_error if suite_files.nil?
+
+        OUTSIDE_SUITE unless in_suite?(path)
+      rescue SystemCallError
+        NOT_REGULAR
+      end
+
+      # macOS git reports a precomposed (NFC) name, while the directory
+      # entry RSpec lists can be decomposed (NFD): the same spec spelled two
+      # ways. Valid UTF-8 compares in NFC (unicode_normalize's default);
+      # other bytes compare as they are.
+      def in_suite?(path)
+        suite = suite_files
+        suite ? suite.include?(comparable(path)) : false
+      end
+
+      def comparable(path)
+        path.valid_encoding? ? path.unicode_normalize : path
+      end
+
+      # nil when RSpec cannot list the suite: under a non-UTF-8 locale its
+      # own path expansion can mix encodings for a non-ASCII root. A changed
+      # spec is then not run, never guessed into the run.
+      def suite_files
+        return @suite_files if defined?(@suite_files)
+
+        listed = Integration.fetch(@config["integration"]).new(@config).configured_spec_files(@root)
+        @suite_files = listed.to_set { |path| comparable(path) }
+      rescue EncodingError => e
+        @suite_error = "the configured RSpec suite's files could not be listed (#{e.class})"
+        @suite_files = nil
+      end
+
+      def spec?(path)
+        path.end_with?("_spec.rb")
       end
 
       # Included files relative to the root, sorted for stable output.
@@ -157,15 +377,67 @@ module Saboteur
       def subjectless_files(lines_by_file)
         comparison = UnchangedSyntax.new(Selection::GitDiff.merge_base(@config["since"], root: @root), root: @root)
         finder = SubjectFinder.new
+        constant_finder = ConstantSubjectFinder.new
+        # A file whose diff only deletes lines has no new code to mutate:
+        # the deletion is the change the suite itself covers. Its marked
+        # neighbor lines would otherwise demand a spec the file never had
+        # (#484). Subject selection reads the same list, so both layers
+        # agree: no subject, no mutant, no spec demand. The list is
+        # canonical-absolute; the line map's keys are root-relative, so
+        # compare in absolute space (a monorepo root below the git
+        # toplevel must not silently disable this).
+        deletion_only = Selection::GitDiff.deletion_only_files(@config["since"], root: @root)
         lines_by_file.reject do |file, lines|
-          subjects = finder.call(File.join(@root, file)).subjects
-          subjects.select { |subject| subject.overlaps_lines?(lines) }
-                  .any? { |subject| !comparison.unchanged?(subject) }
+          # (reject keeps the files WITH a changed subject; subjectless
+          # is what remains)
+          next false if deletion_only.include?(File.join(@root, file))
+
+          subjects_in(finder, constant_finder, file)
+            .select { |subject| subject.overlaps_lines?(lines) }
+            .any? { |subject| !comparison.unchanged?(subject) }
         end.keys
       end
 
+      # Def subjects and changed constant literal subjects (#306): both
+      # need a spec to run against. Only the --since route asks.
+      def subjects_in(finder, constant_finder, file)
+        path = File.join(@root, file)
+        finder.call(path).subjects + constant_finder.call(path).subjects
+      end
+
+      # The custom map wins over the naming convention: it exists for the
+      # layouts the convention cannot guess (#369). Its entries come back as
+      # an array of spec paths, or :excluded for a file the map marks
+      # intentionally untested - such a file needs no guessed spec, so it is
+      # neither unmatched nor given one. Returns the guessed spec paths, nil
+      # when neither the map nor the convention names an existing spec.
       def guess_for(file)
-        candidates_for(file).find { |path| File.file?(File.join(@root, path)) }
+        mapped = @custom_map.specs_for(file)
+        return :excluded if mapped == :excluded
+        return expand_mapped(file, mapped) if mapped
+
+        conventional = candidates_for(file).find { |path| File.file?(File.join(@root, path)) }
+        conventional && [conventional]
+      end
+
+      # A mapped spec can be a glob (expanded against the root) or a regexp
+      # backreference filled at match time, and neither is validated to
+      # exist when the map loads. Only specs that exist run; the literal
+      # glob string never reaches RSpec. When the winning entry's specs all
+      # vanish the mapping is broken: stop naming it rather than silently
+      # guessing on and running the wrong specs (#369).
+      def expand_mapped(file, specs)
+        expanded = specs.flat_map do |spec|
+          if spec.match?(/[*?\[{]/)
+            Dir.glob(File.join(@root, spec)).map { |path| path.delete_prefix("#{@root}/") }
+          else
+            [spec]
+          end
+        end
+        expanded = expanded.select { |path| File.file?(File.join(@root, path)) }
+        return expanded unless expanded.empty?
+
+        raise ConfigError, "custom map entry for #{file} names spec(s) #{specs.join(', ')}, which match no file"
       end
 
       # Candidate specs for a source file, most specific first: the nearest
@@ -181,9 +453,27 @@ module Saboteur
         rooted = rest.size == 2 && SOURCE_ROOTS.include?(rest.first)
         names = rooted ? [rest.last, "lib/#{rest.last}", stem] : [stem]
         names = names.flat_map { |name| [name, *request_names(name)] }.uniq
+        # A dashed gem name keeps dashes under lib/ but its specs live under
+        # the underscored require name: lib/acts-as-taggable-on/x.rb tests in
+        # spec/acts_as_taggable_on/x_spec.rb. The literal name still wins
+        # when both exist (#383).
+        names = names.flat_map { |name| [name, name.tr("-", "_")] }.uniq
+        names = layout_variants(names) if rooted
         names.map { |name| "#{spec_root}/#{name}_spec.rb" }
       end
 
+      # Layouts that mirror less of the source path, after every mirrored
+      # guess (#394): a spec/unit/ prefix (shoulda-matchers mirrors below
+      # it, #393), the basename at the spec root (pundit), and both
+      # together (aasm, #370). Weaker guesses come last: the first
+      # candidate that exists wins. A file outside the source roots
+      # keeps its literal guess only: dropping directories from a path
+      # the roots never anchored would guess any same-named spec.
+      def layout_variants(names)
+        flat = names.map { |name| name.split("/").last }.uniq
+        (names + names.map { |name| "unit/#{name}" } + flat + flat.map { |name| "unit/#{name}" }).uniq
+      end
+
       # Rails tests controllers as request specs: spec/requests/users_spec.rb
       # or spec/requests/users_controller_spec.rb for controllers/users_controller.rb.
       def request_names(name)

data/lib/saboteur/engine/unchanged_syntax.rb

@@ -3,6 +3,7 @@
 
 require "prism"
 require_relative "../inline_suppression"
+require_relative "../constant_subject_finder"
 
 module Saboteur
   class Engine
@@ -37,6 +38,18 @@ module Saboteur
           self.class.digest(before.node) == self.class.digest(subject.node)
       end
 
+      # Subjects the diff deleted from a changed file: defined once at the
+      # base of the --since ref and gone from the working tree. A method
+      # that moved but still exists keeps its id and is not a deletion.
+      def deleted_subjects(files)
+        files.flat_map do |file|
+          next [] unless file.end_with?(".rb") && File.file?(file)
+
+          current_ids = unique_by_id(File.read(file), file).keys
+          base_subjects(file).values.reject { |subject| current_ids.include?(subject.id) }
+        end
+      end
+
       # The node as plain data: type and fields, never locations (except
       # the line a `__LINE__` stands for).
       def self.digest(value)
@@ -64,9 +77,11 @@ module Saboteur
       end
 
       # Only the names defined once: with two defs of a name, which one a
-      # change belongs to is a guess.
+      # change belongs to is a guess. Constant literal subjects compare the
+      # same way (#306): a comment-only change to the literal prunes them.
       def unique_by_id(source, file)
-        subjects = SubjectFinder.new.call(file, source: source).subjects
+        subjects = SubjectFinder.new.call(file, source: source).subjects +
+                   ConstantSubjectFinder.new.call(file, source: source).subjects
         counts = subjects.map(&:id).tally
         subjects.select { |subject| counts[subject.id] == 1 }.to_h { |subject| [subject.id, subject] }
       end