mutineer-mongoid 2.0.0

data/lib/mutineer/pairing.rb

@@ -0,0 +1,298 @@
+# 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;
+  #                     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
+  # Rails, no fork.
+  module Pairing
+    module_function
+
+    # Expand each positional source: a directory -> its sorted **/*.rb files
+    # (relative to project_root); a file (or glob, or anything non-directory)
+    # -> 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| existing_relative(f, roots) || f }
+        else
+          # `..` resolves as text, as FileSwap and the daemon already read it.
+          [(existing_relative(abs, roots) if File.exist?(abs)) || arg]
+        end
+      end.uniq
+    end
+
+    # 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)
+      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/
+    # sources. app/foo/bar.rb and lib/foo/bar.rb both -> "foo/bar"; anything
+    # else -> the path minus ".rb" (still attempted). Namespaced subdirs are
+    # preserved verbatim — structural, never constant resolution.
+    #
+    # @param source_rel [String] relative source path.
+    # @return [Array(String, Boolean)] logical base path and whether it came from lib/.
+    def logical_path(source_rel)
+      no_ext = source_rel.sub(/\.rb\z/, "")
+      if no_ext.start_with?("app/")
+        [no_ext.sub(%r{\Aapp/}, ""), false]
+      elsif no_ext.start_with?("lib/")
+        [no_ext.sub(%r{\Alib/}, ""), true]
+      else
+        [no_ext, false]
+      end
+    end
+
+    # Ordered candidate test paths: _test.rb, then Minitest's test_*.rb, then
+    # _spec.rb. lib/ sources also get the test/lib/... and spec/lib/... layouts.
+    #
+    # @param base [String] logical source path without extension.
+    # @param lib [Boolean] whether the source originated from lib/.
+    # @param prefer [String] preferred framework name.
+    # @return [Array<String>] candidate test paths in preferred order.
+    def candidates(base, lib, prefer)
+      minitest = ["test/#{base}_test.rb"]
+      minitest << "test/lib/#{base}_test.rb" if lib
+      unless File.basename(base) == "helper" # test/test_helper.rb is Minitest's support file, not a test
+        prefixed = base.sub(%r{[^/]+\z}) { |name| "test_#{name}" }
+        minitest << "test/#{prefixed}.rb"
+        minitest << "test/lib/#{prefixed}.rb" if lib
+      end
+      rspec = ["spec/#{base}_spec.rb"]
+      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

data/lib/mutineer/parser.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Mutineer
+  # Raised only for I/O failures while reading a source file.
+  #
+  # Prism syntax errors are NOT raised — they are in-band via ParseResult#errors.
+  class ParseError < StandardError; end
+
+  # Thin boundary around Prism.
+  #
+  # The parse methods return a Prism::ParseResult so all callers use
+  # result.value, result.source.source (raw bytes), and result.errors
+  # uniformly. No wrapping struct.
+  class Parser
+    # Parses a file with Prism.
+    #
+    # @param path [String] source file path.
+    # @return [Prism::ParseResult] Prism parse result.
+    # @raise [Mutineer::ParseError] when file I/O fails.
+    def self.parse_file(path)
+      Prism.parse_file(path)
+    rescue SystemCallError => e
+      raise ParseError, e.message
+    end
+
+    # Parses source text with Prism.
+    #
+    # @param source [String] source text.
+    # @return [Prism::ParseResult] Prism parse result.
+    def self.parse_string(source)
+      Prism.parse(source)
+    end
+
+    # The comments of source text, without building its syntax tree: a few
+    # times cheaper than {.parse_string} for a caller that needs only these.
+    #
+    # @param source [String] source text.
+    # @return [Array<Prism::Comment>] its comments, in source order.
+    def self.comments(source)
+      Prism.parse_comments(source)
+    end
+  end
+end

data/lib/mutineer/progress.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Coarse run progress on stderr: one line per 10% step of completed mutants
+  # (which means every completion on a run smaller than ten). Shared by every
+  # backend so a long run is never silent between config resolution and the
+  # report. Thread-safe so the daemon's parallel workers can share one instance.
+  # Writes only to stderr, keeping `--format json` stdout and `--output` files
+  # byte-exact per the Reporter's stream contract.
+  class Progress
+    # Builds a progress counter for a run of `total` mutants.
+    #
+    # @param total [Integer] number of mutants that will run.
+    # @param io [IO] destination stream (defaults to stderr; injectable for tests).
+    def initialize(total, io: $stderr)
+      @total = total
+      @done = 0
+      @last_step = 0
+      @mutex = Mutex.new
+      @io = io
+    end
+
+    # Records one completed mutant and prints when a 10% boundary is crossed.
+    # A zero-total counter never prints (guards the division, and an empty run
+    # has nothing to report).
+    #
+    # @return [void]
+    def tick
+      @mutex.synchronize do
+        return if @total.zero?
+
+        @done += 1
+        step = (@done * 10) / @total
+        return if step <= @last_step
+
+        @last_step = step
+        @io.puts "[mutineer] #{@done}/#{@total} mutants (#{(@done * 100) / @total}%)"
+      end
+    rescue IOError, Errno::EPIPE
+      # Progress is best-effort: a closed stderr (piped consumer went away) must
+      # never kill the run — in the daemon's worker threads a raise here would
+      # propagate through Thread#join and abort scoring.
+      nil
+    end
+  end
+end