mutineer 1.4.0 → 1.6.0

data/lib/mutineer/minitest_integration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "minitest_integration/stop_at_first_failure"
+require_relative "minitest_integration/kill_recorder"
 
 module Mutineer
   # Child-process-only: loads a test file in the current process and runs it
@@ -16,9 +17,11 @@ module Mutineer
   # boundary for unexpected errors. Swallowing those here would create a
   # second exit-2 path and break this method's 0/1 return contract.
   class MinitestIntegration
-    # The seed of a run that stops at the first failure, unless `SEED` is set.
-    # With the stop, the test order can decide `killed` vs `timeout`; a fixed
-    # order keeps the verdict stable for a `--baseline` gate.
+    # The seed of a mutant run (one that stops at the first failure, or a
+    # `--matrix` run that records every test), unless `SEED` is set. With the
+    # stop, the test order can decide `killed` vs `timeout`; a fixed order keeps
+    # the verdict stable for a `--baseline` gate. A matrix run uses the same
+    # order, so its first failure comes at the same point as the stop's.
     STOP_AT_FIRST_FAILURE_SEED = 1
 
     # Tested via runner_test.rb, not in isolation — a direct unit test
@@ -31,8 +34,15 @@ module Mutineer
     # @param test_files [String, Array<String>] one file or many files.
     # @param stop_at_first_failure [Boolean] end the run at the first failing
     #   test. Only the mutant path passes true.
+    # @param record_to [IO, nil] a `--matrix` run: send each test's outcome to
+    #   this channel (see {KillRecorder}) and run every test.
     # @return [Integer] 0 on success, 1 on failure.
-    def self.run(test_files, stop_at_first_failure: false)
+    # @raise [ArgumentError] when both options are given: a matrix run never stops.
+    def self.run(test_files, stop_at_first_failure: false, record_to: nil)
+      if stop_at_first_failure && record_to
+        raise ArgumentError, "stop_at_first_failure and record_to cannot be combined: a matrix run runs every test"
+      end
+
       begin
         require "minitest"
       rescue LoadError
@@ -52,22 +62,76 @@ module Mutineer
       # Drop runnables inherited from the parent suite (this is the child's
       # private copy — the parent is unaffected) so only the target test runs.
       Minitest::Runnable.reset
-      Array(test_files).each { |f| load f }
-
-      args = []
-      if stop_at_first_failure && StopAtFirstFailure.arm!(Minitest::Runnable.runnables)
-        # Pin the seed only when the stop is armed; an unknown Minitest shape
-        # gets the normal full, randomly ordered run.
-        args = ["--seed", STOP_AT_FIRST_FAILURE_SEED.to_s] unless ENV["SEED"]
+      # Each test class's file position: the file that first defined it.
+      rank = {}
+      Array(test_files).each_with_index do |f, i|
+        load f
+        Minitest::Runnable.runnables.each { |klass| rank[klass] ||= i }
       end
+
+      armed =
+        if record_to
+          KillRecorder.arm!(record_to, Minitest::Runnable.runnables)
+        elsif stop_at_first_failure
+          StopAtFirstFailure.arm!(Minitest::Runnable.runnables)
+        end
+      # Pin the seed only when a hook is armed; an unknown Minitest shape gets
+      # the normal full, randomly ordered run.
+      args = armed && !ENV["SEED"] ? ["--seed", STOP_AT_FIRST_FAILURE_SEED.to_s] : []
+      keep_file_order(rank) if armed
       # No silencing here: the fork boundary that calls this method has already
       # pointed stdout at File::NULL (see ChildStdout).
       passed = Minitest.run(args)
+      # Reached only when the suite returned: a test that exits the process
+      # skips it, and the parent then keeps the row incomplete.
+      KillRecorder.finish! if record_to
 
       # A plugin can replace the summary reporter, so a stop decides by itself.
       passed && !StopAtFirstFailure.stopped_here? ? 0 : 1
     ensure
       StopAtFirstFailure.disarm!
+      KillRecorder.disarm!
+    end
+
+    # Runs the test classes in the order of their files (#203). Minitest
+    # shuffles the classes with the seed, then runs the serial classes before
+    # the parallel (`parallelize_me!`) ones. A stable sort by file position
+    # after that shuffle puts the files in the given order and keeps the
+    # seeded order within one file. The serial-then-parallel split is
+    # unchanged. Only the child's own class list gets {FileOrder}.
+    #
+    # @api private
+    # @param rank [Hash{Class => Integer}] each class's file position.
+    # @return [void]
+    def self.keep_file_order(rank)
+      FileOrder.rank = rank
+      ::Minitest::Runnable.runnables.extend(FileOrder)
+    end
+
+    # Extends the list of test classes: its `shuffle` keeps the file order.
+    module FileOrder
+      class << self
+        # Each test class's file position.
+        #
+        # @return [Hash{Class => Integer}, nil]
+        attr_accessor :rank
+      end
+
+      # The seeded shuffle, then a stable sort by file position.
+      #
+      # @return [Array<Class>]
+      def shuffle(...)
+        rank = FileOrder.rank || {}
+        super.sort_by.with_index { |klass, i| [rank.fetch(klass, rank.size), i] }
+      end
+
+      # Minitest 5.15 and older drop empty classes before the shuffle, so the
+      # filtered list keeps the file order too.
+      #
+      # @return [Array<Class>]
+      def reject(...)
+        super.extend(FileOrder)
+      end
     end
   end
 end

data/lib/mutineer/mutant_id.rb

@@ -12,9 +12,9 @@ module Mutineer
   # qualified_name (a method, not a byte position) + operator + the normalized
   # mutated token + an occurrence ordinal among same-(operator, token) twins
   # WITHIN the subject + (only when positive) the subject's ordinal among
-  # same-named subjects in its file. So it survives any edit outside the subject method,
-  # where raw start/end offsets shift on every edit earlier in the file and
-  # would silently stop matching. Moving or renaming the file changes the id.
+  # same-named subjects in its file. Unrelated edits that only shift byte offsets
+  # can preserve the id. File moves, renames, project-root changes, and changes to
+  # repeated-name or repeated-mutation order can change it.
   module MutantId
     module_function
 
@@ -38,7 +38,8 @@ module Mutineer
     #   file sharing this qualified name (two owner-less `def index` in two DSL
     #   blocks). Hashed only when positive, so a subject whose name is unique in
     #   its file keeps the id it had without it.
-    # @return [String] a 12-character hex id, stable across edits outside the subject.
+    # @return [String] a 12-character hex id, stable while its keyed identity and
+    #   occurrence order stay unchanged.
     def for(subject, mutation, source, occurrence = 0, path:, subject_ordinal: 0)
       parts = [path, subject.qualified_name, mutation.operator, normalized_token(mutation, source), occurrence]
       parts << subject_ordinal if subject_ordinal.positive?

data/lib/mutineer/mutators/array_literal.rb

@@ -19,13 +19,6 @@ module Mutineer
         super # nested arrays each get their own mutation
       end
 
-      # Skips a nested method definition. The project finds it as a subject of
-      # its own, so a visit here counts its arrays twice.
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Emits a mutation for a non-empty array with brackets.

data/lib/mutineer/mutators/base.rb

@@ -11,9 +11,6 @@ module Mutineer
     # Subclasses override `visit_*` methods to push `Mutation` objects onto
     # `@mutations`. Visiting only `def_node.body` is the body-only enforcement:
     # the def signature line is never touched.
-    #
-    # ponytail: one implementor in M1; Base earns its keep at M4 when
-    # comparison/boolean operators land and share this contract.
     class Base < Prism::Visitor
       # Walks the subject body and collects mutations.
       #
@@ -23,12 +20,74 @@ module Mutineer
       def mutations_for(subject, source)
         @source = source
         @mutations = []
-        subject.def_node.body&.accept(self)
+        @body = subject.def_node.body
+        @body&.accept(self)
+        drop_dangling_heredocs
         @mutations
       end
 
+      # Skips a nested method definition. The project finds it as a subject of
+      # its own, so a visit here counts its mutations twice. Inside
+      # `class << obj`, the project finds no subject, so the visit continues.
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
+      def visit_def_node(node)
+        super if @in_undiscovered
+      end
+
+      # Tracks a `class << obj` whose `obj` is not `self`. The project does not
+      # recurse into it, so its defs are no subjects (see
+      # `Project::SubjectVisitor#visit_singleton_class_node`).
+      #
+      # @param node [Prism::SingletonClassNode] singleton-class node.
+      # @return [void]
+      def visit_singleton_class_node(node)
+        return super if node.expression.is_a?(Prism::SelfNode)
+
+        outer, @in_undiscovered = @in_undiscovered, true
+        super
+        @in_undiscovered = outer
+      end
+
       private
 
+      # Drops a mutation that deletes a heredoc opener and leaves its body.
+      #
+      # The body sits past the opener's node. Replacing the opener with text
+      # that does not contain it turns the body into Ruby, which parses and
+      # then raises. A replacement that still contains the opener keeps the
+      # body attached, so that mutation stays.
+      #
+      # @return [void]
+      def drop_dangling_heredocs
+        @mutations.reject! { |mutation| dangling_heredoc?(mutation) }
+      end
+
+      # Returns whether the mutation removes a heredoc opener whose body hangs
+      # past the replaced range.
+      #
+      # @param mutation [Mutineer::Mutation] candidate edit.
+      # @param node [Prism::Node, nil] subtree to search. Defaults to the body.
+      # @return [Boolean] true when the edit would leave a heredoc body behind.
+      def dangling_heredoc?(mutation, node = @body)
+        return false if node.nil? || !node.is_a?(Prism::Node)
+
+        if node.respond_to?(:heredoc?) && node.heredoc? && node.respond_to?(:opening_loc)
+          opening = node.opening_loc
+          if opening && opening.start_offset >= mutation.start_offset && opening.start_offset < mutation.end_offset
+            closing = node.respond_to?(:closing_loc) ? node.closing_loc : nil
+            hangs = closing.nil? || closing.end_offset > mutation.end_offset
+            if hangs
+              opener = @source.byteslice(opening.start_offset, opening.end_offset - opening.start_offset)
+              return true if opener.empty? || !mutation.replacement.include?(opener)
+            end
+          end
+        end
+
+        node.compact_child_nodes.any? { |child| dangling_heredoc?(mutation, child) }
+      end
+
       # Returns whether a node is, or contains, a heredoc.
       #
       # A heredoc's body lies outside its node's byte range. A mutation that

data/lib/mutineer/mutators/chain_link.rb

@@ -88,13 +88,6 @@ module Mutineer
         super
       end
 
-      # Nested method definitions are discovered as their own subjects; do not
-      # recurse into them (prevents double-counting their chains).
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Walks a final call's receiver chain, recording each link so it is not

data/lib/mutineer/mutators/collection_method.rb

@@ -12,7 +12,7 @@ module Mutineer
       # Method-name swaps. All targets are core-Ruby Enumerable/Array methods so
       # the mutant exercises real behaviour rather than always raising.
       #
-      # ponytail: include? -> exclude? was specced but skipped — exclude? is not
+      # include? -> exclude? is left out: exclude? is not
       # core Ruby, so that mutant would always NoMethodError (a weak mutant).
       REPLACEMENTS = {
         map: "each", each: "map",

data/lib/mutineer/mutators/condition_forcing.rb

@@ -50,13 +50,6 @@ module Mutineer
         super
       end
 
-      # Nested method definitions are discovered as their own subjects; do not
-      # recurse into them (prevents double-counting their conditions).
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Emits the forced condition unless the condition is a literal or holds a

data/lib/mutineer/mutators/operand_removal.rb

@@ -33,13 +33,6 @@ module Mutineer
         super
       end
 
-      # Skips a nested method definition. The project finds it as a subject of
-      # its own, so a visit here counts its connectors twice.
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Emits one mutation that keeps the left operand, then one that keeps

data/lib/mutineer/mutators/operator_assignment.rb

@@ -90,13 +90,6 @@ module Mutineer
         super
       end
 
-      # Skips a nested method definition. The project finds it as a subject of
-      # its own, so a visit here counts its compound assignments twice.
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Emits a mutation when the node's operator has a replacement.

data/lib/mutineer/mutators/return_nil.rb

@@ -16,11 +16,12 @@ module Mutineer
       def mutations_for(subject, source)
         @source = source
         @mutations = []
-        body = subject.def_node.body
-        if body
-          body.accept(self)       # rule 1 (explicit return nodes in this body)
-          final_expression_nil(body) # rule 2 (method's final expression)
+        @body = subject.def_node.body
+        if @body
+          @body.accept(self)       # rule 1 (explicit return nodes in this body)
+          final_expression_nil(@body) # rule 2 (method's final expression)
         end
+        drop_dangling_heredocs
         @mutations
       end
 
@@ -39,13 +40,6 @@ module Mutineer
         super
       end
 
-      # Nested method definitions are discovered as their own subjects; do not
-      # recurse into them (prevents double-counting their statements).
-      #
-      # @param node [Prism::DefNode] nested definition node.
-      # @return [void]
-      def visit_def_node(node); end
-
       private
 
       # Mutates a method's final expression to nil when eligible.

data/lib/mutineer/mutators/string_literal.rb

@@ -15,7 +15,7 @@ module Mutineer
       # @param node [Prism::StringNode] node to inspect.
       # @return [void]
       def visit_string_node(node)
-        # ponytail: only plain "..." / '...' quotes. opening is nil for
+        # Only plain "..." / '...' quotes. opening is nil for
         # interpolation parts and %w[] elements; heredocs/%-literals use a
         # different opening token. Skipping them keeps mutants re-parseable.
         if %w[" '].include?(node.opening)

data/lib/mutineer/orphan_guard.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Ends a forked child's process group once the process that forked it is
+  # gone (#101). A mutant or capture child leads its own process group, so a
+  # parent that dies, or is killed by a client that gave up on it, does not
+  # take the child's tests with it; without this, a hung test would run on and
+  # keep its worker database open. Needs no other part of Mutineer, so the
+  # app-side daemon can load it.
+  module OrphanGuard
+    # Seconds between checks. A forked child gets no signal on parent death.
+    POLL = 0.5
+
+    # Starts the watchdog in the current (child) process.
+    #
+    # @param parent [Integer] the parent's pid, read in the parent before
+    #   `fork`, so a parent that dies before this call is still noticed.
+    # @return [Thread]
+    def self.start(parent)
+      Thread.new do
+        sleep(POLL) while Process.ppid == parent
+        # Group 0 only when this child leads its own group: a failed setpgid
+        # leaves it in the parent's group, which must not be killed.
+        Process.kill(:KILL, Process.getpgrp == Process.pid ? 0 : Process.pid)
+      end
+    end
+  end
+end

data/lib/mutineer/pairing.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
+require_relative "project_path"
+
 module Mutineer
   # Source -> test pairing by path convention (#11). Pure stdlib path logic:
   # no Rails, no class loading, no process. Two jobs:
-  #   * expand_sources — a directory argument becomes its sorted **/*.rb files.
-  #   * infer_test     — a source's test file by convention (app/ and lib/
-  #                     sources map to test/.../_test.rb, test/.../test_*.rb
-  #                     or spec/.../_spec.rb), preserving namespaced
-  #                     subdirectories. First EXISTING candidate wins.
+  #   * expand_sources — a directory argument becomes its sorted **/*.rb files;
+  #                     a file inside the root becomes its root-relative path.
+  #   * infer_tests    — a source's test files by convention (app/ and lib/
+  #                     sources map to test/.../_test.rb, test/.../<name>_*_test.rb,
+  #                     test/.../test_*.rb or spec/.../_spec.rb), preserving
+  #                     namespaced subdirectories. The first EXISTING exact
+  #                     candidate stays first. Split Minitest files join a
+  #                     Minitest match. A matched spec is left as that one file.
   #
   # Independently unit-testable: every method is pure in/out over the
   # filesystem, so the pairing contract is exercised with plain fixtures, no
@@ -17,37 +22,88 @@ module Mutineer
 
     # Expand each positional source: a directory -> its sorted **/*.rb files
     # (relative to project_root); a file (or glob, or anything non-directory)
-    # -> itself. Flattened, deduped, order-stable.
+    # -> its path relative to project_root, so `./lib/x.rb` and an absolute
+    # path pair like `lib/x.rb` (#104). A missing file, or one outside the
+    # root, stays as typed. Flattened, deduped, order-stable.
     #
     # @param args [Array<String>] source paths or directories.
     # @param project_root [String] repository root for relative expansion.
     # @return [Array<String>] flattened, deduped source file list.
     def expand_sources(args, project_root:)
       root = File.expand_path(project_root)
+      # The root as typed and as its real path (macOS `/var` vs `/private/var`),
+      # resolved once for every file below.
+      roots = [root, ProjectPath.root_real(root)].uniq
       Array(args).flat_map do |arg|
         abs = File.expand_path(arg, root)
         if File.directory?(abs)
-          Dir.glob(File.join(abs, "**", "*.rb")).sort.map { |f| f.delete_prefix("#{root}/") }
+          Dir.glob(File.join(abs, "**", "*.rb")).sort.map { |f| existing_relative(f, roots) || f }
         else
-          [arg]
+          # `..` resolves as text, as FileSwap and the daemon already read it.
+          [(existing_relative(abs, roots) if File.exist?(abs)) || arg]
         end
       end.uniq
     end
 
-    # The first EXISTING candidate test path for a source (relative to
-    # project_root), or nil. `prefer` is the resolved framework ("minitest" |
-    # "rspec"): its candidates are tried first, the other framework's as
-    # fallback, so a minitest default still finds a spec and vice-versa.
+    # An existing file's root-relative path, or nil outside the root. Tries the
+    # path as given, then with its directory resolved, so a path typed through
+    # a symlinked parent (or macOS `/var` under a `/private/var` root) matches.
+    # The file's own name is kept, so a symlinked file is not renamed.
+    #
+    # @param abs [String] expanded absolute path of an existing file.
+    # @param roots [Array<String>] the project root, expanded and real.
+    # @return [String, nil] root-relative path, or nil outside the root.
+    def existing_relative(abs, roots)
+      root_relative(abs, roots) ||
+        root_relative(File.join(File.realpath(File.dirname(abs)), File.basename(abs)), roots)
+    end
+
+    # `abs` relative to the first of `roots` it is under, or nil. Text only: a
+    # symlinked source keeps its own name (realpath would rename it to its
+    # target and pair the wrong test). `roots` holds the root's real path too,
+    # so the macOS `/var` vs `/private/var` alias still matches.
+    #
+    # @param abs [String] expanded absolute path.
+    # @param roots [Array<String>] the project root, expanded and real.
+    # @return [String, nil] root-relative path, or nil outside the root.
+    def root_relative(abs, roots)
+      roots.each do |r|
+        prefix = r.end_with?("/") ? r : "#{r}/"
+        return abs.delete_prefix(prefix) if abs.start_with?(prefix)
+      end
+      nil
+    end
+
+    # The first test path {#infer_tests} would run for a source, or nil.
+    # `prefer` is the resolved framework ("minitest" | "rspec"): its candidates
+    # are tried first, the other framework's as fallback, so a minitest default
+    # still finds a spec and vice-versa.
     #
     # @param source_rel [String] relative source path.
     # @param project_root [String] repository root for existence checks.
     # @param prefer [String] preferred framework name.
     # @return [String, nil] existing test path or nil.
     def infer_test(source_rel, project_root:, prefer: "minitest")
+      infer_tests(source_rel, project_root: project_root, prefer: prefer).first
+    end
+
+    # Every test file convention pairs with a source. The first existing exact
+    # candidate from {#candidates} stays first. Each `<basename>_*_test.rb` in
+    # the mirrored test directory is added after it (#87). A spec that the exact
+    # rules already found is left alone: split Minitest names do not join it
+    # and do not replace it.
+    #
+    # @param source_rel [String] relative source path.
+    # @param project_root [String] repository root for existence checks.
+    # @param prefer [String] preferred framework name.
+    # @return [Array<String>] existing test paths, exact candidate first.
+    def infer_tests(source_rel, project_root:, prefer: "minitest")
       base, lib = logical_path(source_rel)
-      candidates(base, lib, prefer).find do |rel|
-        File.exist?(File.expand_path(rel, project_root))
-      end
+      root = File.expand_path(project_root)
+      exact = candidates(base, lib, prefer).find { |rel| File.exist?(File.expand_path(rel, root)) }
+      return [exact] if exact&.end_with?("_spec.rb")
+
+      ([exact] + split_test_files(base, lib, root)).compact.uniq
     end
 
     # Strip the source root to a logical path (no ".rb") and flag lib/
@@ -87,5 +143,156 @@ module Mutineer
       rspec << "spec/lib/#{base}_spec.rb" if lib
       prefer == "rspec" ? rspec + minitest : minitest + rspec
     end
+
+    # `<basename>_*_test.rb` files in each mirrored test directory (#87). The
+    # exact `<basename>_test.rb` name is not included. `lib/` sources also look
+    # under `test/lib/`. Names are matched as text, not as a glob, so a basename
+    # that contains `*` stays literal. `test/` comes before `test/lib/`, and
+    # each directory is sorted.
+    #
+    # @param base [String] logical source path without extension.
+    # @param lib [Boolean] whether the source originated from lib/.
+    # @param root [String] expanded project root.
+    # @return [Array<String>] relative split-test paths.
+    def split_test_files(base, lib, root)
+      name = File.basename(base)
+      dirs = [mirror_dir("test", base)]
+      dirs << mirror_dir("test/lib", base) if lib
+      dirs.flat_map { |dir| split_tests_in(root, dir, name, base) }
+    end
+
+    # Relative test directory for a logical source path. A source with no
+    # subdirectory (`calc`) maps to `prefix` itself, not `prefix/.`.
+    #
+    # @param prefix [String] `test` or `test/lib`.
+    # @param base [String] logical source path without extension.
+    # @return [String] relative directory.
+    def mirror_dir(prefix, base)
+      dir = File.dirname(base)
+      dir == "." ? prefix : File.join(prefix, dir)
+    end
+
+    # Split test files directly inside `dir_rel` (not in subdirectories).
+    #
+    # @param root [String] expanded project root.
+    # @param dir_rel [String] relative directory.
+    # @param name [String] source basename without extension.
+    # @param base [String] logical source path without extension.
+    # @return [Array<String>] sorted relative paths.
+    def split_tests_in(root, dir_rel, name, base)
+      root_abs = File.expand_path(root)
+      dir_abs = File.expand_path(dir_rel, root_abs)
+      return [] unless inside_project?(dir_abs, root_abs)
+      return [] unless File.directory?(dir_abs)
+
+      Dir.children(dir_abs).filter_map do |entry|
+        next unless split_entry?(entry, name)
+        next unless File.file?(File.join(dir_abs, entry))
+        next if claimed_by_longer_source?(root, base, entry, dir_rel)
+
+        File.join(dir_rel, entry)
+      end.sort
+    end
+
+    # True when `dir_abs` is the project root or a directory inside it.
+    # A source path such as `../../evil.rb` must not list tests outside the project.
+    #
+    # @param dir_abs [String] expanded directory.
+    # @param root_abs [String] expanded project root.
+    # @return [Boolean]
+    def inside_project?(dir_abs, root_abs)
+      prefix = root_abs == File::SEPARATOR ? File::SEPARATOR : "#{root_abs}#{File::SEPARATOR}"
+      dir_abs == root_abs || dir_abs.start_with?(prefix)
+    end
+
+    # True when `entry` is `<name>_<piece>_test.rb` and not the exact
+    # `<name>_test.rb` file.
+    #
+    # @param entry [String] test file basename.
+    # @param name [String] source basename without extension.
+    # @return [Boolean]
+    def split_entry?(entry, name)
+      return false unless entry.end_with?("_test.rb")
+
+      rest = entry.delete_prefix("#{name}_")
+      rest != entry && rest.match?(/\A.+_test\.rb\z/)
+    end
+
+    # True when a longer source file on disk owns this split test. `user.rb`
+    # does not take `user_session_test.rb` when `user_session.rb` exists in the
+    # same directory, under `app/`, or under `lib/`. An intermediate file
+    # counts: `bar_upsert.rb` owns `bar_upsert_guards_test.rb`, so `bar.rb`
+    # does not.
+    #
+    # @param root [String] expanded project root.
+    # @param base [String] logical source path without extension.
+    # @param entry [String] test file basename.
+    # @param scanned_dir [String, nil] relative test directory being scanned.
+    #   When set, a longer source claims the file only if that source searches
+    #   this directory. An `app/` source does not take a `test/lib/` file.
+    # @return [Boolean]
+    def claimed_by_longer_source?(root, base, entry, scanned_dir = nil)
+      name = File.basename(base)
+      stem = entry.sub(/_test\.rb\z/, "")
+      return false unless stem.start_with?("#{name}_")
+
+      rest = stem.delete_prefix("#{name}_")
+      return false if rest.empty?
+
+      dir = File.dirname(base)
+      parts = rest.split("_", -1)
+      (1..parts.length).any? do |i|
+        longer = "#{name}_#{parts.first(i).join("_")}"
+        next false unless longer_owns_entry?(entry, longer)
+
+        longer_source_exists?(root, dir, longer, scanned_dir)
+      end
+    end
+
+    # True when `entry` is the exact test, or a split test with a non-empty
+    # piece, for `stem`. `user_session__test.rb` is neither for
+    # `user_session`, so that source does not take it from `user.rb`.
+    #
+    # @param entry [String] test file basename.
+    # @param stem [String] longer source basename without extension.
+    # @return [Boolean]
+    def longer_owns_entry?(entry, stem)
+      entry == "#{stem}_test.rb" || split_entry?(entry, stem)
+    end
+
+    # True when a longer source file exists beside this logical path.
+    # The logical directory itself is checked, so `src/user_session.rb` owns
+    # `test/src/user_session_test.rb`. `app/` and `lib/` are checked too, so an
+    # `app/` source still yields the name to a `lib/` sibling and the reverse.
+    #
+    # @param root [String] expanded project root.
+    # @param dir [String] logical directory, or `.` when the source has none.
+    # @param stem [String] longer source basename without extension.
+    # @param scanned_dir [String, nil] relative test directory being scanned.
+    # @return [Boolean]
+    def longer_source_exists?(root, dir, stem, scanned_dir = nil)
+      file = "#{stem}.rb"
+      folders = [dir == "." ? nil : dir]
+      %w[app lib].each { |prefix| folders << (dir == "." ? prefix : File.join(prefix, dir)) }
+      folders.uniq.any? do |folder|
+        rel = folder ? File.join(folder, file) : file
+        next false unless File.file?(File.join(root, rel))
+        next false if scanned_dir && !source_searches_dir?(rel, scanned_dir)
+
+        true
+      end
+    end
+
+    # True when pairing this source looks in `scanned_dir`.
+    #
+    # @param source_rel [String] project-relative source path.
+    # @param scanned_dir [String] relative test directory.
+    # @return [Boolean]
+    def source_searches_dir?(source_rel, scanned_dir)
+      base, lib = logical_path(source_rel)
+      dirs = [mirror_dir("test", base)]
+      dirs << mirror_dir("test/lib", base) if lib
+      dirs.include?(scanned_dir)
+    end
   end
 end