mutaruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed2be021810bf506056045c9de11c188af27c0f77ba28c9cef6c124265b13aaf
-  data.tar.gz: a0789ce2a2707894ed251c13641f689d6d2456e067ce830f366d5bdb4c89cdbe
+  metadata.gz: a7881b725c1ef86850ff3a13370a7f3217bfd3a943f152d26465ff62439559ef
+  data.tar.gz: 55071854a05f0a10e85c749eb3a2984e04591ab6dcca7d69c5cc674675b01796
 SHA512:
-  metadata.gz: df30932c81a94875c7aa082c6842d78593e253febc1eade648780946266cc5207ca1293a7e0b507919ead9be542600a15a6764be45fad7034504bed593a27aaf
-  data.tar.gz: 0f9a9fc9d2a3a1eb68e6c442dcf65ff9b3f3cf692358ca1af18010e53d93a1cef8630d7652af7182cf31cd6e783910f08ed7ffe90fb028bfe1c015f864a1eaf6
+  metadata.gz: ab4e2654379b04db8da0e6ef63fedcf918f9eb2fc8632d3632ea1412b86cd43e68e0a3f85ca998b424d48d8da4bd1bc0099d19af0369a124d1687ed49cfa2db1
+  data.tar.gz: 2e26578a0581acde2d08c3ab7876a2d5868a05c91af2e1805f0609727582fdf32c2847be1571d42aa64158e0b5e5a0d4e4d5c78548e6b44a41f3513b388f453e

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
 
+## [0.1.1] - 2026-10-12
+
+mutaruby now scores 100% on its own code: every mutant is killed by a test or listed, with a checkable reason, in
+`.mutaruby-ignore.yml`. Getting there found the bugs below.
+
+### Fixed
+
+- Processes that a test run leaves behind (a server, a forked worker) are now killed when the run ends, not only on
+  timeout, so they cannot interfere with the next mutant.
+- A project root given through a symlink (for example under `/tmp` on macOS) was copied into the sandboxes as an
+  empty directory, so the baseline ran without the project.
+- An ignore entry for a removed sole argument (`mutation: "x =>"`) never matched: the mutant's change text had a
+  trailing space. Change texts are now whitespace-normalised the same way on both sides.
+- Captured baseline output is decoded as UTF-8 even when Ruby's default external encoding is something else.
+
+### Changed
+
+- `literal-string` also mutates `%q()` and `%Q[]` strings.
+- `argument-removal` no longer skips calls on the right-hand side of a multiple assignment.
+- Option parsing is available as `Mutaruby::CLI#parse`; `Runner::Options.build` supplies the defaults.
+- Each library file requires what it uses and loads on its own.
+
 ## [0.1.0] - 2026-10-11
 
 First release.
@@ -27,4 +49,5 @@ First release.
   reason, ambiguity and staleness checks, `--strict-ignore` and `--suggest-ignore`.
 - Human, JSON and JUnit XML reports, a mutation score and `--fail-under` for CI.
 
+[0.1.1]: https://github.com/Atlas-Authorization/mutaruby/releases/tag/v0.1.1
 [0.1.0]: https://github.com/Atlas-Authorization/mutaruby/releases/tag/v0.1.0

data/README.md

@@ -1,7 +1,15 @@
 # mutaruby
 
+[![CI](https://github.com/Atlas-Authorization/mutaruby/actions/workflows/ci.yml/badge.svg)](https://github.com/Atlas-Authorization/mutaruby/actions/workflows/ci.yml)
+![mutation score on its own code: 100%](https://img.shields.io/badge/self%20mutation%20score-100%25-brightgreen)
+
 Free, MIT-licensed mutation testing for Ruby.
 
+mutaruby is mutation-tested with itself. In version 0.1.1, all 3,619 mutants of its own code are accounted for:
+3,613 are killed by its tests (499 of them by timeout), and the other 6 are true equivalents, each listed in
+[`.mutaruby-ignore.yml`](.mutaruby-ignore.yml) with a reason you can check. `bundle exec rake mutate` reproduces the
+run; it fails on any surviving mutant or stale ignore entry.
+
 mutaruby makes small, deliberate changes to your code, one at a time, and runs your test command against each change.
 If your tests still pass, the change (the *mutant*) **survived**, and that points to code your tests do not really check.
 
@@ -207,7 +215,7 @@ mutant's, are dropped before anything runs. `--list-operators` prints this list.
 | `loop-condition-false` | a `while` loop never runs | `while i < n` to `while false` |
 | `literal-int` | an integer becomes n+1, n-1, 0 and 1 (each distinct value once) | `retries = 3` to `4`, `2`, `0`, `1` |
 | `literal-float` | a float becomes 0.0 and x+1.0 | `0.5` to `0.0`, `1.5` |
-| `literal-string` | a quoted string becomes `""`; an empty one becomes `"mutaruby"` | `'admin'` to `''` |
+| `literal-string` | a quoted string (`'...'`, `"..."`, `%q()`, `%Q[]`) becomes empty; an empty one becomes `"mutaruby"` | `'admin'` to `''` |
 | `literal-symbol` | a `:symbol` becomes `:__mutaruby__` | `:read` to `:__mutaruby__` |
 | `literal-boolean` | `true` and `false` | `strict = true` to `strict = false` |
 | `literal-nil` | `nil` becomes `true` | `cache = nil` to `cache = true` |
@@ -376,9 +384,10 @@ text. If it is not, the run aborts rather than testing a mutant in the wrong pla
 mutant would be "killed" and the score would mean nothing, so mutaruby stops with exit status 2 and shows the tail of
 the output. The baseline's duration also sets the default timeout.
 
-**Timeouts kill the whole process group.** Each run is the leader of its own process group. On timeout the group gets
-`SIGTERM`, then `SIGKILL` two seconds later, so a hung child (a forked server, a parallel test worker) does not
-outlive its mutant.
+**No run outlives its mutant.** Each run is the leader of its own process group. When the run times out, and also
+when it finishes normally, whatever is left of the group (a hung test, a forked server, a parallel test worker) gets
+`SIGTERM`, then `SIGKILL` if it is still there two seconds later. Nothing from one mutant's run can interfere with
+the next one.
 
 **Site keys instead of line numbers** for the ignore file; see [above](#equivalent-mutants-the-ignore-file).
 

data/lib/mutaruby/cli.rb

@@ -2,6 +2,8 @@
 
 require 'optparse'
 require 'etc'
+require_relative 'runner'
+require_relative 'reporters'
 
 module Mutaruby
   # Command line interface. Exit status: 0 success, 1 score below --fail-under (or stale ignore entries with
@@ -10,13 +12,16 @@ module Mutaruby
     EXIT_OK = 0
     EXIT_FAIL = 1
     EXIT_ERROR = 2
+    EXIT_INTERRUPTED = 130
+
+    attr_reader :options, :flags
 
     def initialize(argv, stdout: $stdout, stderr: $stderr)
       @argv = argv.dup
       @stdout = stdout
       @stderr = stderr
-      @o = Runner::Options.new(jobs: Etc.nprocessors, patterns: [], methods: [], exclude_methods: [], lines: [],
-                               exclude_lines: [], copy_excludes: [], progress: true)
+      @options = Runner::Options.build(jobs: Etc.nprocessors, progress: true)
+      @flags = {}
       @include_ops = []
       @exclude_ops = []
     end
@@ -26,78 +31,83 @@ module Mutaruby
       EXIT_OK # --help / --version
     end
 
+    # Parses the arguments into `options` (and `flags`); the remaining arguments are the file patterns.
+    def parse
+      parser.parse!(@argv)
+      @options.patterns = @argv
+      @options.operators = operators
+      self
+    end
+
     private
 
     def execute
-      parser.parse!(@argv)
-      @o.patterns = @argv
-      return list_operators if @list_operators
-
-      @o.operators = operators
-      raise Error, 'missing --test COMMAND (the command that runs your tests; exit 0 = pass)' if @o.command.nil? && !@list
+      parse
+      return list_operators if @flags[:list_operators]
 
-      runner = Runner.new(@o, out: @stderr)
-      return list(runner.plan) if @list
+      runner = Runner.new(@options, out: @stderr)
+      return list(runner.plan) if @flags[:list]
+      raise Error, 'missing --test COMMAND (the command that runs your tests; exit 0 = pass)' unless @options.command
 
       report = runner.run
       emit(report)
       status(report)
     rescue OptionParser::ParseError, Error, IgnoreFile::Invalid, SpliceError => e
-      @stderr.puts "mutaruby: #{e.message}"
+      @stderr.puts "mutaruby: #{e}"
       EXIT_ERROR
     rescue Interrupt
       @stderr.puts "\nmutaruby: interrupted"
-      130
+      EXIT_INTERRUPTED
     end
 
     def parser
-      OptionParser.new do |o|
-        o.banner = 'Usage: mutaruby --test COMMAND [options] [FILE|GLOB ...]   (default: lib/**/*.rb)'
-        o.separator ''
-        o.separator 'Test oracle:'
-        o.on('-t', '--test COMMAND', 'Shell command that runs the tests; exit 0 = mutant survived, non-zero = killed') { |v| @o.command = v }
-        o.on('-C', '--root DIR', 'Project root (copied for every worker; default: current directory)') { |v| @o.root = v }
-        o.on('-j', '--jobs N', Integer, "Parallel workers (default: #{Etc.nprocessors})") { |v| @o.jobs = v }
-        o.on('--timeout SECONDS', Float, 'Per-mutant timeout (default: baseline time x factor + 5s)') { |v| @o.timeout = v }
-        o.on('--timeout-factor F', Float, 'Multiplier on the baseline time for the default timeout (default: 3)') { |v| @o.timeout_factor = v }
-        o.on('--copy-exclude GLOB', 'Do not copy matching paths into the sandboxes (repeatable; .git and coverage are always skipped)') { |v| @o.copy_excludes << v }
-        o.separator ''
-        o.separator 'Selection:'
-        o.on('--since REF', 'Only files changed since a git ref (committed, staged, unstaged, untracked)') { |v| @o.since = v }
-        o.on('--method PATTERN', 'Only mutants inside matching methods ("Calc#add", "Calc#*", "add"; repeatable)') { |v| @o.methods << v }
-        o.on('--exclude-method PATTERN', 'Skip mutants inside matching methods (repeatable)') { |v| @o.exclude_methods << v }
-        o.on('--line SPEC', 'Only mutants on these lines: [FILE:]LINE or [FILE:]FROM-TO (repeatable)') { |v| @o.lines << Selection.parse_line_spec(v) }
-        o.on('--exclude-line SPEC', 'Skip mutants on these lines (repeatable)') { |v| @o.exclude_lines << Selection.parse_line_spec(v) }
-        o.on('--operators LIST', Array, 'Only these operators (comma-separated; globs allowed, e.g. condition-*)') { |v| @include_ops.concat(v) }
-        o.on('--exclude-operators LIST', Array, 'Skip these operators (comma-separated; globs allowed)') { |v| @exclude_ops.concat(v) }
-        o.on('--shard I/N', 'Run only shard I of N (1-based) of the selected mutants') { |v| @o.shard = Selection.parse_shard(v) }
-        o.separator ''
-        o.separator 'Equivalent mutants:'
-        o.on('--ignore-file PATH', 'Ignore file (default: .mutaruby-ignore.yml in the root, if present)') { |v| @o.ignore_file = v }
-        o.on('--strict-ignore', 'Fail (exit 1) when an ignore entry matches no surviving mutant') { @strict = true }
-        o.on('--suggest-ignore', 'Print ignore-file stubs for the surviving mutants (fill in each reason)') { @suggest = true }
-        o.separator ''
-        o.separator 'Output:'
-        o.on('--json PATH', 'Write a JSON report ("-" = stdout)') { |v| @json = v }
-        o.on('--junit PATH', 'Write a JUnit-style XML report ("-" = stdout)') { |v| @junit = v }
-        o.on('--fail-under PERCENT', Float, 'Exit 1 when the mutation score is below PERCENT') { |v| @fail_under = v }
-        o.on('--list', 'List the selected mutants without running anything') { @list = true }
-        o.on('--list-operators', 'List the mutation operators') { @list_operators = true }
-        o.on('-q', '--quiet', 'No progress marks') { @o.progress = false }
-        o.on('-v', '--verbose', 'Also list timeouts and equivalent mutants') { @verbose = true }
-        o.on('--version', 'Print the version') do
+      o = @options
+      OptionParser.new do |op|
+        op.banner = 'Usage: mutaruby --test COMMAND [options] [FILE|GLOB ...]   (default: lib/**/*.rb)'
+        op.separator ''
+        op.separator 'Test oracle:'
+        op.on('-t', '--test COMMAND', 'Shell command that runs the tests; exit 0 = mutant survived, non-zero = killed') { |v| o.command = v }
+        op.on('-C', '--root DIR', 'Project root (copied for every worker; default: current directory)') { |v| o.root = v }
+        op.on('-j', '--jobs N', Integer, "Parallel workers (default: #{Etc.nprocessors})") { |v| o.jobs = v }
+        op.on('--timeout SECONDS', Float, 'Per-mutant timeout (default: baseline time x factor + 5s)') { |v| o.timeout = v }
+        op.on('--timeout-factor F', Float, 'Multiplier on the baseline time for the default timeout (default: 3)') { |v| o.timeout_factor = v }
+        op.on('--copy-exclude GLOB', 'Do not copy matching paths into the sandboxes (repeatable; .git and coverage are always skipped)') { |v| o.copy_excludes += [v] }
+        op.separator ''
+        op.separator 'Selection:'
+        op.on('--since REF', 'Only files changed since a git ref (committed, staged, unstaged, untracked)') { |v| o.since = v }
+        op.on('--method PATTERN', 'Only mutants inside matching methods ("Calc#add", "Calc#*", "add"; repeatable)') { |v| o.methods += [v] }
+        op.on('--exclude-method PATTERN', 'Skip mutants inside matching methods (repeatable)') { |v| o.exclude_methods += [v] }
+        op.on('--line SPEC', 'Only mutants on these lines: [FILE:]LINE or [FILE:]FROM-TO (repeatable)') { |v| o.lines += [Selection.parse_line_spec(v)] }
+        op.on('--exclude-line SPEC', 'Skip mutants on these lines (repeatable)') { |v| o.exclude_lines += [Selection.parse_line_spec(v)] }
+        op.on('--operators LIST', Array, 'Only these operators (comma-separated; globs allowed, e.g. condition-*)') { |v| @include_ops += v }
+        op.on('--exclude-operators LIST', Array, 'Skip these operators (comma-separated; globs allowed)') { |v| @exclude_ops += v }
+        op.on('--shard I/N', 'Run only shard I of N (1-based) of the selected mutants') { |v| o.shard = Selection.parse_shard(v) }
+        op.separator ''
+        op.separator 'Equivalent mutants:'
+        op.on('--ignore-file PATH', 'Ignore file (default: .mutaruby-ignore.yml in the root, if present)') { |v| o.ignore_file = v }
+        op.on('--strict-ignore', 'Fail (exit 1) when an ignore entry matches no surviving mutant') { @flags[:strict] = true }
+        op.on('--suggest-ignore', 'Print ignore-file stubs for the surviving mutants (fill in each reason)') { @flags[:suggest] = true }
+        op.separator ''
+        op.separator 'Output:'
+        op.on('--json PATH', 'Write a JSON report ("-" = stdout)') { |v| @flags[:json] = v }
+        op.on('--junit PATH', 'Write a JUnit-style XML report ("-" = stdout)') { |v| @flags[:junit] = v }
+        op.on('--fail-under PERCENT', Float, 'Exit 1 when the mutation score is below PERCENT') { |v| @flags[:fail_under] = v }
+        op.on('--list', 'List the selected mutants without running anything') { @flags[:list] = true }
+        op.on('--list-operators', 'List the mutation operators') { @flags[:list_operators] = true }
+        op.on('-q', '--quiet', 'No progress marks') { o.progress = false }
+        op.on('-v', '--verbose', 'Also list timeouts and equivalent mutants') { @flags[:verbose] = true }
+        op.on('--version', 'Print the version') do
           @stdout.puts "mutaruby #{VERSION}"
           throw :done
         end
-        o.on('-h', '--help', 'Show this help') do
-          @stdout.puts o
+        op.on('-h', '--help', 'Show this help') do
+          @stdout.puts op
           throw :done
         end
       end
     end
 
-    private
-
+    # nil (every operator) unless --operators / --exclude-operators narrowed the set.
     def operators
       return nil if @include_ops.empty? && @exclude_ops.empty?
 
@@ -124,33 +134,31 @@ module Mutaruby
     end
 
     def emit(report)
-      human_io = [@json, @junit].include?('-') ? @stderr : @stdout
-      Reporters.human(report, human_io, verbose: @verbose)
-      write(@json) { |io| Reporters.json(report, io) } if @json
-      write(@junit) { |io| Reporters.junit(report, io) } if @junit
-      return unless @suggest
-
+      human_io = [@flags[:json], @flags[:junit]].include?('-') ? @stderr : @stdout
+      Reporters.human(report, human_io, verbose: @flags[:verbose])
+      write(@flags[:json]) { |io| Reporters.json(report, io) } if @flags[:json]
+      write(@flags[:junit]) { |io| Reporters.junit(report, io) } if @flags[:junit]
       survivors = report.outcomes.select { |o| o.status == :survived }.map(&:mutation)
+      return unless @flags[:suggest] && survivors.any?
+
       @stderr.puts '# ignore-file stubs (add a reason to each; keep only true equivalents):'
-      @stderr.puts IgnoreFile.stub_for(survivors, report.sources) if survivors.any?
+      @stderr.puts IgnoreFile.stub_for(survivors, report.sources)
     end
 
     def write(path, &block)
-      if path == '-'
-        block.call(@stdout)
-      else
-        File.open(path, 'w', &block)
-      end
+      path == '-' ? block.call(@stdout) : File.open(path, 'w', &block)
     end
 
     def status(report)
       code = EXIT_OK
-      if @fail_under && (report.score || 100.0) < @fail_under
-        @stderr.puts format('mutaruby: score %s is below --fail-under %.2f%%', Reporters.score_text(report), @fail_under)
+      score = report.score
+      if @flags[:fail_under] && score && score < @flags[:fail_under]
+        @stderr.puts format('mutaruby: score %s is below --fail-under %.2f%%', Reporters.score_text(report), @flags[:fail_under])
         code = EXIT_FAIL
       end
-      if @strict && report.stale.any?
-        @stderr.puts "mutaruby: #{report.stale.size} stale ignore entr#{report.stale.size == 1 ? 'y' : 'ies'} (--strict-ignore)"
+      n = report.stale.size
+      if @flags[:strict] && n.positive?
+        @stderr.puts "mutaruby: #{n} stale ignore entr#{n == 1 ? 'y' : 'ies'} (--strict-ignore)"
         code = EXIT_FAIL
       end
       code

data/lib/mutaruby/command.rb

@@ -12,55 +12,61 @@ module Mutaruby
     end
 
     OUTPUT_TAIL = 4000
+    # After SIGTERM, a process group gets this many seconds to exit before SIGKILL.
+    KILL_GRACE = 2
+    POLL = 0.05
 
-    def initialize(command, root:, env: {})
+    def initialize(command, root:, kill_grace: KILL_GRACE)
       @command = command
+      @kill_grace = kill_grace
       @root = File.expand_path(root)
-      @env = env
-      @live = {}
+      @live = []
       @lock = Mutex.new
     end
 
     # Kills every run still in progress (used when mutaruby itself is interrupted: the runs live in their own process
     # groups, so a Ctrl-C in the terminal does not reach them).
     def kill_all
-      pids = @lock.synchronize { @live.keys }
-      pids.each { |pid| kill_group(pid) }
+      @lock.synchronize { @live.each { |pid| kill_group(pid) } }
     end
 
     # dir: sandbox project dir. timeout: seconds (nil = none). capture: keep an output tail (for the baseline report).
     def run(dir, timeout: nil, env: {}, capture: false)
-      log = capture ? Tempfile.new('mutaruby-out') : nil
-      out = log ? log.path : File::NULL
+      return execute(dir, timeout, env, File::NULL) unless capture
+
+      Tempfile.create do |log|
+        result = execute(dir, timeout, env, log)
+        log.rewind
+        result.output = tail(log.read)
+        result
+      end
+    end
+
+    private
+
+    def execute(dir, timeout, env, out)
       started = monotonic
-      pid = Process.spawn(child_env(dir).merge(@env).merge(env), '/bin/sh', '-c', @command,
+      pid = Process.spawn(child_env(dir).merge(env), '/bin/sh', '-c', @command,
                           chdir: dir, pgroup: true, in: File::NULL, out: out, err: out)
-      @lock.synchronize { @live[pid] = true }
+      @lock.synchronize { @live << pid }
       waiter = Process.detach(pid)
-      timed_out = waiter.join(timeout).nil? if timeout
-      if timed_out
-        kill_group(pid)
-        waiter.join
-      end
+      timed_out = waiter.join(timeout).nil?
+      # A timed-out run, and anything a finished run left behind (a server, a forked worker), must not outlive it.
+      kill_group(pid)
       st = waiter.value
       @lock.synchronize { @live.delete(pid) }
       status = if timed_out then :timeout
                elsif st.success? then :passed
                else :failed
                end
-      Result.new(status: status, exitstatus: st.exitstatus, seconds: monotonic - started,
-                 output: log ? tail(log.path) : nil)
-    ensure
-      log&.close!
+      Result.new(status: status, exitstatus: st.exitstatus, seconds: monotonic - started)
     end
 
-    private
-
     # Bundler exports the ORIGINAL Gemfile path to child processes. Left as is, `bundle exec` in the sandbox would
     # resolve the Gemfile (and a `gemspec` line's lib/ directory) from the user's checkout and test the unmutated code.
+    # The per-mutant variables are always set or cleared explicitly, so a mutaruby run nested inside another one's
+    # test command does not inherit the outer run's values.
     def child_env(dir)
-      # The per-mutant variables are always set or cleared explicitly, so a mutaruby run nested inside another one's
-      # test command does not inherit the outer run's mutant id.
       env = { 'MUTARUBY' => '1', 'MUTARUBY_MUTANT_ID' => nil, 'MUTARUBY_FILE' => nil }
       %w[BUNDLE_GEMFILE BUNDLE_APP_CONFIG].each do |k|
         v = ENV.fetch(k, nil)
@@ -72,13 +78,18 @@ module Mutaruby
       env
     end
 
+    # SIGTERM to the whole group, up to kill_grace seconds to exit, then SIGKILL.
     def kill_group(pid)
-      Process.kill('TERM', -pid)
-      deadline = monotonic + 2
-      sleep 0.05 while monotonic < deadline && alive?(pid)
-      Process.kill('KILL', -pid)
+      signal_group('TERM', pid)
+      deadline = monotonic + @kill_grace
+      sleep POLL while monotonic < deadline && alive?(pid)
+      signal_group('KILL', pid)
+    end
+
+    def signal_group(sig, pid)
+      Process.kill(sig, -pid)
     rescue Errno::ESRCH, Errno::EPERM
-      nil
+      # the group is already gone
     end
 
     def alive?(pid)
@@ -88,10 +99,8 @@ module Mutaruby
       false
     end
 
-    def tail(path)
-      s = File.binread(path)
-      s = s[-OUTPUT_TAIL..] if s.bytesize > OUTPUT_TAIL
-      s.force_encoding(Encoding::UTF_8).scrub
+    def tail(bytes)
+      bytes.byteslice([bytes.bytesize - OUTPUT_TAIL, 0].max..).force_encoding(Encoding::UTF_8).scrub
     end
 
     def monotonic

data/lib/mutaruby/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Mutaruby
+  # A user-facing error: bad options, an invalid ignore file, a failing baseline. The CLI prints the message and exits 2.
+  class Error < StandardError; end
+end