mutante 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5644bbc1cfc15fe2e6fe859d2ce4ee547f4780ea1215d62cb29408f48bbca591
+  data.tar.gz: 451058c2475efd8c91a90575bd8100f35672eea29431fab6d8755429af4c58d5
+SHA512:
+  metadata.gz: dda544bdea5c32ddd89486e4cb459b20a24a6cb65a7793ea1378bbeda74e83f17761b3603618d42e00b1327ed12f001cc4cafc8506797bdd9f0b335ca18c43a5
+  data.tar.gz: d961f33aaa7064aa9219fcc93d7bb98d6973a4192c19889d0232a25b84d2da9b6f7b82e2650ddd8f25805a4b9d7158c8c8535a73b150071636d3cf71e00381e3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nazareno Moresco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# Mutante
+
+Find dead code by commenting lines out and running the tests. If the suite
+still passes, that line is a strong candidate for removal.
+
+Think of it as reverse mutation testing: instead of mutating code to see if
+the suite catches the change, mutante *removes* code to see if anything
+notices.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+group :development, :test do
+  gem "mutante"
+end
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Usage
+
+Run against every candidate file in a Rails project (models, controllers,
+services, jobs, mailers, helpers, channels, serializers, and `lib/`):
+
+```bash
+bundle exec mutante
+```
+
+Limit to a single file or directory:
+
+```bash
+bundle exec mutante app/models/user.rb
+bundle exec mutante app/services/
+```
+
+Stream test output while it runs:
+
+```bash
+bundle exec mutante --verbose
+```
+
+Mutante starts by running the whole suite. If the baseline is red, it bails
+out — there's no signal in running mutated tests against an already-broken
+suite.
+
+For every line of real code it then:
+
+1. Rewrites the file with that one line commented out.
+2. Skips the line if the mutation produces a `SyntaxError` (e.g. `end`,
+   `def foo`, block headers).
+3. Runs the spec file that covers the source file. If no match is
+   configured and no mirrored spec exists, runs the entire suite.
+4. Restores the file, and flags the line if the suite stayed green.
+
+At the end you get a list of flagged `path:line` locations to review.
+
+## Configuration
+
+Drop a file at `config/initializers/mutante.rb` (or `.mutante.rb` in the
+project root):
+
+```ruby
+Mutante.configure do |config|
+  # Override the test command (default: bin/rspec or bundle exec rspec).
+  config.test_command = "bundle exec rspec --no-color"
+
+  # Narrow or widen which files are scanned.
+  config.include_globs = %w[app/services/**/*.rb app/models/**/*.rb]
+  config.exclude_globs << "app/services/legacy/**/*"
+
+  # Map a source-file glob to the spec(s) that cover it. Available
+  # placeholders in the target:
+  #   {basename}     - file name without extension
+  #   {relative}     - path below app/<layer>/ or lib/
+  #   {relative_dir} - directory portion of {relative}
+  config.map "app/services/**/*.rb",
+             to: "spec/services/{relative}_spec.rb"
+
+  config.map "app/models/concerns/*.rb",
+             to: ["spec/models/concerns/{basename}_spec.rb",
+                  "spec/shared/concerns/{basename}_spec.rb"]
+end
+```
+
+If no mapping matches, mutante falls back to the mirrored path under
+`spec/` (so `app/models/user.rb` → `spec/models/user_spec.rb`). If that
+doesn't exist either, it runs the full suite for that line.
+
+## Performance
+
+This is slow. Commenting out a single line means a full test run, and
+mutante does that once per eligible line. Use specific files or tight
+mappings to keep runs tractable on large codebases.
+
+## License
+
+MIT.

data/exe/mutante

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require "mutante"
+
+Mutante::CLI.start(ARGV)

data/lib/mutante/cli.rb

@@ -0,0 +1,63 @@
+require "optparse"
+
+module Mutante
+  class CLI
+    DEFAULT_INITIALIZER_PATHS = [
+      "config/initializers/mutante.rb",
+      ".mutante.rb"
+    ].freeze
+
+    def self.start(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      @argv    = argv.dup
+      @options = { verbose: false, config: nil }
+    end
+
+    def run
+      target = parse!
+      load_configuration
+      ok = Runner.new(verbose: @options[:verbose]).call(target)
+      exit(ok ? 0 : 1)
+    end
+
+    private
+
+    def parse!
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: mutante [options] [FILE_OR_DIRECTORY]"
+
+        o.on("-c", "--config PATH", "Load configuration from PATH") do |v|
+          @options[:config] = v
+        end
+
+        o.on("-v", "--verbose", "Stream test output to the terminal") do
+          @options[:verbose] = true
+        end
+
+        o.on("--version", "Print version and exit") do
+          puts "mutante #{Mutante::VERSION}"
+          exit 0
+        end
+
+        o.on("-h", "--help", "Show this help message") do
+          puts o
+          exit 0
+        end
+      end
+
+      remainder = parser.parse(@argv)
+      remainder.first
+    end
+
+    def load_configuration
+      candidates = [@options[:config], *DEFAULT_INITIALIZER_PATHS].compact
+      path = candidates.find { |p| File.exist?(File.expand_path(p)) }
+      return unless path
+
+      load File.expand_path(path)
+    end
+  end
+end

data/lib/mutante/configuration.rb

@@ -0,0 +1,62 @@
+module Mutante
+  class Configuration
+    DEFAULT_RAILS_GLOBS = %w[
+      app/models/**/*.rb
+      app/controllers/**/*.rb
+      app/services/**/*.rb
+      app/jobs/**/*.rb
+      app/mailers/**/*.rb
+      app/helpers/**/*.rb
+      app/channels/**/*.rb
+      app/serializers/**/*.rb
+      lib/**/*.rb
+    ].freeze
+
+    DEFAULT_EXCLUDE_GLOBS = %w[
+      spec/**/*
+      test/**/*
+      config/**/*
+      db/**/*
+      vendor/**/*
+      tmp/**/*
+    ].freeze
+
+    attr_accessor :include_globs,
+                  :exclude_globs,
+                  :test_command,
+                  :test_mappings,
+                  :root
+
+    def initialize
+      @include_globs  = DEFAULT_RAILS_GLOBS.dup
+      @exclude_globs  = DEFAULT_EXCLUDE_GLOBS.dup
+      @test_command   = default_test_command
+      @test_mappings  = {}
+      @root           = Dir.pwd
+    end
+
+    # Map a source-file glob to the spec file(s) that cover it.
+    #
+    #   config.map "app/services/**/*.rb", to: "spec/services/{basename}_spec.rb"
+    #
+    # Placeholders in the target:
+    #   {basename}     - file name without extension
+    #   {relative}     - path relative to app/ or lib/
+    #   {relative_dir} - directory part of {relative}
+    def map(source_glob, to:)
+      test_mappings[source_glob] = to
+    end
+
+    private
+
+    def default_test_command
+      if File.exist?(File.join(Dir.pwd, "bin", "rspec"))
+        "bin/rspec"
+      elsif File.exist?(File.join(Dir.pwd, "Gemfile"))
+        "bundle exec rspec"
+      else
+        "rspec"
+      end
+    end
+  end
+end

data/lib/mutante/file_finder.rb

@@ -0,0 +1,41 @@
+module Mutante
+  class FileFinder
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Given an optional explicit path (file or directory), returns an
+    # array of absolute file paths to analyze.
+    def call(target = nil)
+      files =
+        if target && File.file?(target)
+          [File.expand_path(target)]
+        elsif target && File.directory?(target)
+          glob_in(target, "**/*.rb")
+        else
+          from_include_globs
+        end
+
+      exclude!(files)
+    end
+
+    private
+
+    def from_include_globs
+      @configuration.include_globs.flat_map do |pattern|
+        glob_in(@configuration.root, pattern)
+      end
+    end
+
+    def glob_in(root, pattern)
+      Dir.glob(File.join(root, pattern)).map { |f| File.expand_path(f) }
+    end
+
+    def exclude!(files)
+      excludes = @configuration.exclude_globs.flat_map do |pattern|
+        Dir.glob(File.join(@configuration.root, pattern)).map { |f| File.expand_path(f) }
+      end
+      (files - excludes).uniq.sort
+    end
+  end
+end

data/lib/mutante/line_analyzer.rb

@@ -0,0 +1,85 @@
+module Mutante
+  # Walks a file line-by-line, yielding an opportunity to comment each
+  # eligible line out. The file is rewritten for each trial and restored
+  # afterwards — callers get a block that runs while the file is mutated.
+  class LineAnalyzer
+    # Lines that are pure structural keywords would break the syntax the
+    # moment they are commented out, so we skip them up front.
+    SKIP_EXACT = %w[
+      end else elsif ensure rescue begin do then
+    ].freeze
+
+    def initialize(path)
+      @path          = path
+      @original_lines = File.readlines(path)
+    end
+
+    # Yields |line_number, line_text| for each line worth trying.
+    # Inside the block, the file on disk has that line commented out.
+    # After the block returns, the file is restored to its original form.
+    def each_candidate
+      @original_lines.each_with_index do |line, index|
+        next unless candidate?(line)
+
+        commented = commented_version(line)
+        next unless still_valid_ruby?(index, commented)
+
+        write_with_substitution(index, commented)
+        begin
+          yield(index + 1, line.chomp)
+        ensure
+          restore_original
+        end
+      end
+    end
+
+    private
+
+    def candidate?(line)
+      stripped = line.strip
+      return false if stripped.empty?
+      return false if stripped.start_with?("#")
+      return false if SKIP_EXACT.include?(stripped)
+      return false if stripped =~ /\A(end|else|elsif|ensure|rescue|begin|do|then)\b.*\z/ && stripped !~ /[=.({]/
+      true
+    end
+
+    def commented_version(line)
+      leading = line[/\A\s*/]
+      rest    = line[leading.length..] || ""
+      "#{leading}# #{rest}".sub(/(?<!\n)\z/, "\n")
+    end
+
+    def still_valid_ruby?(index, replacement_line)
+      candidate = @original_lines.dup
+      candidate[index] = replacement_line
+      source = candidate.join
+
+      silence_stderr do
+        RubyVM::InstructionSequence.compile(source)
+      end
+      true
+    rescue SyntaxError
+      false
+    end
+
+    def silence_stderr
+      original = $stderr
+      $stderr = File.open(File::NULL, "w")
+      yield
+    ensure
+      $stderr.close if $stderr && $stderr != original
+      $stderr = original
+    end
+
+    def write_with_substitution(index, replacement_line)
+      mutated = @original_lines.dup
+      mutated[index] = replacement_line
+      File.write(@path, mutated.join)
+    end
+
+    def restore_original
+      File.write(@path, @original_lines.join)
+    end
+  end
+end

data/lib/mutante/reporter.rb

@@ -0,0 +1,265 @@
+module Mutante
+  class Reporter
+    SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+    COLORS = {
+      reset:   "\e[0m",
+      bold:    "\e[1m",
+      dim:     "\e[2m",
+      red:     "\e[31m",
+      green:   "\e[32m",
+      yellow:  "\e[33m",
+      blue:    "\e[34m",
+      magenta: "\e[35m",
+      cyan:    "\e[36m",
+      gray:    "\e[90m"
+    }.freeze
+
+    CLEAR_LINE = "\e[2K\r".freeze
+
+    def initialize(io: $stdout, force_plain: false)
+      @io            = io
+      @flagged       = []
+      @tty           = !force_plain && io.respond_to?(:tty?) && io.tty?
+      @total_files   = 0
+      @file_index    = 0
+      @current_file  = nil
+      @counts        = nil
+      @file_started  = nil
+      @started_at    = nil
+      @spinner_index = 0
+    end
+
+    def starting(files)
+      @total_files = files.size
+      @started_at  = monotonic_now
+      plural       = files.size == 1 ? "file" : "files"
+      subtitle     = "analyzing #{files.size} #{plural} · reverse mutation testing"
+
+      if @tty
+        draw_header("mutante v#{Mutante::VERSION}", subtitle)
+      else
+        @io.puts "mutante: #{subtitle}"
+        @io.puts
+      end
+    end
+
+    def baseline_starting
+      if @tty
+        @io.puts
+        @io.print "  #{color(:cyan)}◆#{color(:reset)} running baseline test suite..."
+        @io.flush
+      else
+        @io.puts "mutante: running baseline test suite..."
+      end
+    end
+
+    def baseline_result(ok)
+      if @tty
+        @io.print CLEAR_LINE
+        if ok
+          @io.puts "  #{color(:green)}●#{color(:reset)} baseline #{color(:green)}green#{color(:reset)}"
+        else
+          @io.puts "  #{color(:red)}●#{color(:reset)} baseline #{color(:red)}RED#{color(:reset)} — fix the suite before running mutante."
+        end
+      else
+        @io.puts(ok ? "  baseline green." : "  baseline RED.")
+        @io.puts
+      end
+    end
+
+    def file_starting(path)
+      @file_index  += 1
+      @current_file = path
+      @counts       = { tested: 0, flagged: 0, skipped: 0 }
+      @file_started = monotonic_now
+
+      if @tty
+        @io.puts
+        @io.puts "#{color(:cyan)}▸#{color(:reset)} " \
+                 "#{color(:bold)}#{path}#{color(:reset)} " \
+                 "#{color(:gray)}[#{@file_index}/#{@total_files}]#{color(:reset)}"
+        redraw_status
+      else
+        @io.puts path
+      end
+    end
+
+    def line_flagged(path, line_number, line_text)
+      @flagged << { path: path, line: line_number, text: line_text }
+      @counts[:flagged] += 1 if @counts
+      @counts[:tested]  += 1 if @counts
+
+      if @tty
+        @io.print CLEAR_LINE
+        @io.puts "  #{color(:red)}⚑#{color(:reset)} " \
+                 "#{color(:red)}#{path}:#{line_number}#{color(:reset)}  " \
+                 "#{color(:dim)}#{line_text.strip}#{color(:reset)}"
+        redraw_status
+      else
+        @io.puts "  flagged #{path}:#{line_number}  #{line_text.strip}"
+      end
+    end
+
+    def line_safe(_path, _line_number)
+      @counts[:tested] += 1 if @counts
+
+      if @tty
+        redraw_status
+      else
+        @io.print "."
+        @io.flush
+      end
+    end
+
+    def line_skipped(_path, _line_number, _reason)
+      @counts[:skipped] += 1 if @counts
+
+      if @tty
+        redraw_status
+      else
+        @io.print "-"
+        @io.flush
+      end
+    end
+
+    def file_finished
+      if @tty
+        @io.print CLEAR_LINE
+        elapsed = format_duration(monotonic_now - (@file_started || monotonic_now))
+        icon    = @counts && @counts[:flagged].positive? ? "#{color(:yellow)}⚑#{color(:reset)}" : "#{color(:green)}✓#{color(:reset)}"
+        parts   = []
+        parts << "#{@counts[:tested]} tested" if @counts
+        parts << "#{color(:red)}#{@counts[:flagged]} flagged#{color(:reset)}" if @counts && @counts[:flagged].positive?
+        parts << "#{@counts[:skipped]} skipped" if @counts && @counts[:skipped].positive?
+        parts << "#{color(:gray)}#{elapsed}#{color(:reset)}"
+        @io.puts "  #{icon} #{parts.join(color(:gray) + ' · ' + color(:reset))}"
+      else
+        @io.puts
+      end
+    end
+
+    def finished
+      if @tty
+        draw_summary
+      else
+        @io.puts
+        @io.puts "=" * 60
+        if @flagged.empty?
+          @io.puts "mutante: no dead-code candidates found."
+        else
+          plural = @flagged.size == 1 ? "candidate line" : "candidate lines"
+          @io.puts "mutante: #{@flagged.size} #{plural} flagged:"
+          @flagged.each do |entry|
+            @io.puts "  #{entry[:path]}:#{entry[:line]}  #{entry[:text].strip}"
+          end
+        end
+      end
+    end
+
+    attr_reader :flagged
+
+    private
+
+    def color(name)
+      return "" unless @tty
+
+      COLORS.fetch(name, "")
+    end
+
+    def redraw_status
+      return unless @tty && @counts
+
+      @spinner_index = (@spinner_index + 1) % SPINNER_FRAMES.size
+      spinner = SPINNER_FRAMES[@spinner_index]
+
+      parts = []
+      parts << "#{@counts[:tested]} tested"
+      parts << "#{color(:red)}⚑ #{@counts[:flagged]}#{color(:reset)}" if @counts[:flagged].positive?
+      parts << "#{color(:gray)}#{@counts[:skipped]} skipped#{color(:reset)}" if @counts[:skipped].positive?
+
+      line = "  #{color(:cyan)}#{spinner}#{color(:reset)} " \
+             "#{parts.join(color(:gray) + ' · ' + color(:reset))}"
+
+      @io.print CLEAR_LINE
+      @io.print line
+      @io.flush
+    end
+
+    def draw_header(title, subtitle)
+      width   = [title.length, subtitle.length].max + 4
+      top     = "╭#{"─" * width}╮"
+      middle1 = "│  #{color(:bold)}#{color(:magenta)}#{title}#{color(:reset)}#{" " * (width - title.length - 2)}│"
+      middle2 = "│  #{color(:gray)}#{subtitle}#{color(:reset)}#{" " * (width - subtitle.length - 2)}│"
+      bottom  = "╰#{"─" * width}╯"
+
+      @io.puts top
+      @io.puts middle1
+      @io.puts middle2
+      @io.puts bottom
+    end
+
+    def draw_summary
+      elapsed = format_duration(monotonic_now - (@started_at || monotonic_now))
+
+      @io.puts
+      if @flagged.empty?
+        line1 = "#{color(:green)}✓#{color(:reset)} " \
+                "#{color(:bold)}no dead-code candidates found#{color(:reset)} " \
+                "#{color(:gray)}(#{elapsed})#{color(:reset)}"
+        @io.puts draw_box([line1], :green)
+      else
+        plural = @flagged.size == 1 ? "candidate line" : "candidate lines"
+        header = "#{color(:yellow)}⚑#{color(:reset)} " \
+                 "#{color(:bold)}#{@flagged.size} #{plural} flagged#{color(:reset)} " \
+                 "#{color(:gray)}(#{elapsed})#{color(:reset)}"
+
+        path_width = @flagged.map { |e| "#{e[:path]}:#{e[:line]}".length }.max
+        entries = @flagged.map do |entry|
+          locator = "#{entry[:path]}:#{entry[:line]}".ljust(path_width)
+          "  #{color(:red)}#{locator}#{color(:reset)}  " \
+            "#{color(:dim)}#{entry[:text].strip}#{color(:reset)}"
+        end
+
+        lines = [header, ""] + entries
+        @io.puts draw_box(lines, :yellow)
+      end
+    end
+
+    def draw_box(lines, border_color)
+      visible_widths = lines.map { |l| visible_length(l) }
+      width = visible_widths.max + 2
+
+      out = []
+      out << "#{color(border_color)}╭#{'─' * width}╮#{color(:reset)}"
+      lines.each_with_index do |line, i|
+        padding = " " * (width - visible_widths[i] - 1)
+        out << "#{color(border_color)}│#{color(:reset)} #{line}#{padding}#{color(border_color)}│#{color(:reset)}"
+      end
+      out << "#{color(border_color)}╰#{'─' * width}╯#{color(:reset)}"
+      out.join("\n")
+    end
+
+    def visible_length(str)
+      str.gsub(/\e\[[0-9;]*m/, "").length
+    end
+
+    def format_duration(seconds)
+      return "0s" if seconds.nil? || seconds.negative?
+
+      if seconds < 1
+        "#{(seconds * 1000).round}ms"
+      elsif seconds < 60
+        "#{seconds.round(1)}s"
+      else
+        minutes = (seconds / 60).to_i
+        rem     = (seconds - minutes * 60).round
+        "#{minutes}m#{rem}s"
+      end
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/mutante/runner.rb

@@ -0,0 +1,59 @@
+module Mutante
+  class Runner
+    def initialize(configuration: Mutante.configuration,
+                   reporter: nil,
+                   verbose: false,
+                   test_runner: nil,
+                   file_finder: nil,
+                   spec_finder: nil)
+      @configuration = configuration
+      @reporter      = reporter || Reporter.new(force_plain: verbose)
+      @verbose       = verbose
+      @finder        = file_finder || FileFinder.new(configuration)
+      @spec_finder   = spec_finder || SpecFinder.new(configuration)
+      @test_runner   = test_runner || TestRunner.new(configuration, verbose: verbose)
+    end
+
+    def call(target = nil)
+      files = @finder.call(target)
+      @reporter.starting(files)
+
+      return false unless baseline_passes?
+
+      files.each { |f| analyze_file(f) }
+      @reporter.finished
+      true
+    end
+
+    private
+
+    def baseline_passes?
+      @reporter.baseline_starting if @reporter.respond_to?(:baseline_starting)
+      result = @test_runner.call(nil)
+      @reporter.baseline_result(result) if @reporter.respond_to?(:baseline_result)
+      result
+    end
+
+    def analyze_file(path)
+      relative = relative_path(path)
+      @reporter.file_starting(relative)
+
+      spec_files = @spec_finder.call(path)
+
+      analyzer = LineAnalyzer.new(path)
+      analyzer.each_candidate do |line_number, line_text|
+        if @test_runner.call(spec_files)
+          @reporter.line_flagged(relative, line_number, line_text)
+        else
+          @reporter.line_safe(relative, line_number)
+        end
+      end
+
+      @reporter.file_finished
+    end
+
+    def relative_path(path)
+      path.sub(/\A#{Regexp.escape(@configuration.root)}\/?/, "")
+    end
+  end
+end

data/lib/mutante/spec_finder.rb

@@ -0,0 +1,75 @@
+module Mutante
+  # Resolves which spec file(s) to run for a given source file.
+  #
+  # Priority:
+  #   1. Explicit mapping from Configuration#test_mappings.
+  #   2. Mirrored path under spec/ (app/foo/bar.rb -> spec/foo/bar_spec.rb).
+  #   3. Nil, meaning "fall back to the whole suite".
+  class SpecFinder
+    PLACEHOLDER_RE = /\{(basename|relative|relative_dir)\}/
+
+    def initialize(configuration)
+      @configuration = configuration
+      @root          = configuration.root
+    end
+
+    # Returns an Array of spec file paths (relative to the project root),
+    # or nil to indicate the whole test suite should be used.
+    def call(source_file)
+      rel = relative(source_file)
+
+      mapping = matching_mapping(rel)
+      if mapping
+        paths = expand(mapping, rel)
+        existing = paths.select { |p| File.exist?(File.join(@root, p)) }
+        return existing unless existing.empty?
+      end
+
+      mirror = mirrored_spec(rel)
+      return [mirror] if mirror && File.exist?(File.join(@root, mirror))
+
+      nil
+    end
+
+    private
+
+    def relative(path)
+      abs = File.expand_path(path)
+      abs.sub(/\A#{Regexp.escape(@root)}\/?/, "")
+    end
+
+    def matching_mapping(rel)
+      @configuration.test_mappings.each do |glob, target|
+        return target if File.fnmatch?(glob, rel, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+      end
+      nil
+    end
+
+    def expand(target, rel)
+      basename     = File.basename(rel, ".rb")
+      stripped     = rel.sub(%r{\A(app/[^/]+/|lib/)}, "")
+      relative_rb  = stripped.sub(/\.rb\z/, "")
+      relative_dir = File.dirname(relative_rb)
+      relative_dir = "" if relative_dir == "."
+
+      Array(target).map do |t|
+        t.gsub(PLACEHOLDER_RE) do
+          case Regexp.last_match(1)
+          when "basename"     then basename
+          when "relative"     then relative_rb
+          when "relative_dir" then relative_dir
+          end
+        end
+      end
+    end
+
+    def mirrored_spec(rel)
+      case rel
+      when %r{\Aapp/(.+)\.rb\z}
+        "spec/#{Regexp.last_match(1)}_spec.rb"
+      when %r{\Alib/(.+)\.rb\z}
+        "spec/lib/#{Regexp.last_match(1)}_spec.rb"
+      end
+    end
+  end
+end

data/lib/mutante/test_runner.rb

@@ -0,0 +1,34 @@
+require "open3"
+require "shellwords"
+
+module Mutante
+  class TestRunner
+    def initialize(configuration, verbose: false)
+      @configuration = configuration
+      @verbose       = verbose
+    end
+
+    # Runs the configured test command, scoped to `spec_files` when provided
+    # (otherwise runs the whole suite). Returns true if the suite passed.
+    def call(spec_files = nil)
+      command = build_command(spec_files)
+
+      if @verbose
+        puts "  $ #{command}"
+        system(command, chdir: @configuration.root)
+      else
+        _out, _err, status = Open3.capture3(command, chdir: @configuration.root)
+        status.success?
+      end
+    end
+
+    private
+
+    def build_command(spec_files)
+      base = @configuration.test_command
+      return base if spec_files.nil? || spec_files.empty?
+
+      "#{base} #{Array(spec_files).map { |f| Shellwords.escape(f) }.join(' ')}"
+    end
+  end
+end

data/lib/mutante/version.rb

@@ -0,0 +1,3 @@
+module Mutante
+  VERSION = "0.1.0"
+end

data/lib/mutante.rb

@@ -0,0 +1,25 @@
+require "mutante/version"
+require "mutante/configuration"
+require "mutante/file_finder"
+require "mutante/spec_finder"
+require "mutante/line_analyzer"
+require "mutante/test_runner"
+require "mutante/reporter"
+require "mutante/runner"
+require "mutante/cli"
+
+module Mutante
+  class Error < StandardError; end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: mutante
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nazareno Moresco
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Mutante iterates through lines of code, comments each one out, runs the
+  associated tests, and flags lines whose removal leaves the suite green — strong
+  candidates for dead code.
+email:
+executables:
+- mutante
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/mutante
+- lib/mutante.rb
+- lib/mutante/cli.rb
+- lib/mutante/configuration.rb
+- lib/mutante/file_finder.rb
+- lib/mutante/line_analyzer.rb
+- lib/mutante/reporter.rb
+- lib/mutante/runner.rb
+- lib/mutante/spec_finder.rb
+- lib/mutante/test_runner.rb
+- lib/mutante/version.rb
+homepage: https://github.com/alliants/mutante
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Find dead code by commenting lines out and running tests.
+test_files: []