mutaruby 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7881b725c1ef86850ff3a13370a7f3217bfd3a943f152d26465ff62439559ef
-  data.tar.gz: 55071854a05f0a10e85c749eb3a2984e04591ab6dcca7d69c5cc674675b01796
+  metadata.gz: 0fb14367f23f77c599ae74ba8f36f1d5e0e71c73ab8fa8267378569a3a359655
+  data.tar.gz: 036b55cb7754d44886e7056f0d63dda5725a0caf7037dc8eff50d49bf7df73fb
 SHA512:
-  metadata.gz: ab4e2654379b04db8da0e6ef63fedcf918f9eb2fc8632d3632ea1412b86cd43e68e0a3f85ca998b424d48d8da4bd1bc0099d19af0369a124d1687ed49cfa2db1
-  data.tar.gz: 2e26578a0581acde2d08c3ab7876a2d5868a05c91af2e1805f0609727582fdf32c2847be1571d42aa64158e0b5e5a0d4e4d5c78548e6b44a41f3513b388f453e
+  metadata.gz: 718044deb537125a73dfc0864aeea698594711196ecf12ba16655fac80e6fa23e6c5ef2ef478d360b270da7f3264e7fccc7d8f5bff2bf88e2863cbe61e937d8c
+  data.tar.gz: 7fb23d15489c6dae51343866c850e7e4a9ccf049f966e8521fa20fbe92a3eaca1f52bde4014a5387151d1aa36febbc44c92c20708e83fbf22e573dbddbd09f9e

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.2.0] - 2026-10-12
+
+### Added
+
+- Windows support. The test command runs under `cmd.exe` in a new process group; on timeout the whole process tree
+  is stopped with `taskkill /T` (graceful first, then `/F` after the grace period). Sandboxes get short names, writes
+  and deletes are retried while a file is locked, and symlinks fall back to copies where Windows does not allow
+  them. See "Windows notes" in the README.
+- `Mutaruby::Platform`, which holds everything that differs between POSIX systems and Windows. The POSIX behaviour is
+  unchanged.
+- CI on Linux, macOS and Windows (Ruby 3.1 to 3.4), including a fixture run whose infinite-loop mutant must be
+  stopped by the timeout.
+
+### Fixed
+
+- Files with CRLF line endings aborted the run with a splice self-check error: `parser` reads `\r\n` as `\n`, so its
+  offsets did not match the file. Offsets are now mapped back to the file's own characters, and a mutant keeps the
+  file's line endings (mixed endings included).
+- Sources are read as bytes and decoded as UTF-8, with no newline conversion on Windows; ignore files are read as
+  UTF-8 whatever the default external encoding.
+- Sandbox removal no longer silently leaves files behind when one is locked.
+
 ## [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
@@ -49,5 +71,6 @@ 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.2.0]: https://github.com/Atlas-Authorization/mutaruby/releases/tag/v0.2.0
 [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

@@ -5,8 +5,8 @@
 
 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 is mutation-tested with itself. In version 0.2.0, all 3,812 mutants of its own code are accounted for:
+3,806 are killed by its tests (521 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.
 
@@ -48,6 +48,7 @@ The survivor above tells you that no test checks a total of exactly 100.
 - [Output formats](#output-formats)
 - [How it compares with mutant](#how-it-compares-with-mutant)
 - [Design notes](#design-notes)
+- [Windows notes](#windows-notes)
 - [Limitations](#limitations)
 - [Contributing, security, licence](#contributing-security-licence)
 
@@ -84,7 +85,7 @@ end
 ```
 
 mutaruby needs Ruby 3.1 or newer and depends only on the [`parser`](https://github.com/whitequark/parser) gem. It runs
-on Linux and macOS (it uses process groups and `/bin/sh`).
+on Linux, macOS and Windows (see [Windows notes](#windows-notes)); CI tests all three.
 
 ## Quickstart
 
@@ -134,7 +135,7 @@ Positional arguments are files or globs relative to the project root. The defaul
 
 | Option | Meaning |
 |---|---|
-| `-t`, `--test COMMAND` | **Required.** Shell command (run with `/bin/sh -c`) that runs your tests. Exit 0 means the mutant survived, non-zero means killed. |
+| `-t`, `--test COMMAND` | **Required.** Shell command that runs your tests: run with `/bin/sh -c` on Linux and macOS, with `cmd.exe` on Windows. Exit 0 means the mutant survived, non-zero means killed. |
 | `-C`, `--root DIR` | Project root (default: the current directory). This is the directory copied into each sandbox, and the command runs there. |
 | `-j`, `--jobs N` | Parallel workers (default: the number of CPUs). Each worker has its own copy of the project. |
 | `--timeout SECONDS` | Per-mutant time limit. A mutant that exceeds it (an infinite loop, say) is killed together with every process it started and counted as **killed, by timeout**. The default is `baseline time x factor + 5` seconds. |
@@ -360,7 +361,7 @@ at any project with one command, mutaruby is for you.
 
 ## Design notes
 
-**A fresh process per mutant.** Every run, the baseline and each mutant, is a new `/bin/sh -c COMMAND` with its
+**A fresh process per mutant.** Every run, the baseline and each mutant, is a new shell (`/bin/sh -c COMMAND`; `cmd.exe` on Windows) with its
 own Ruby. Nothing loaded by one run can leak into the next. This matters more than it looks. When mutants are
 evaluated inside one long-lived process, deleting a `require` cannot be detected because the library is already loaded,
 and a deleted method or constant can quietly keep its old definition. Those mutants then "survive" and report test
@@ -391,9 +392,33 @@ the next one.
 
 **Site keys instead of line numbers** for the ignore file; see [above](#equivalent-mutants-the-ignore-file).
 
+## Windows notes
+
+mutaruby works the same way on Windows, with these differences:
+
+- **The shell is `cmd.exe`.** Quote with double quotes, not single quotes: `mutaruby -t "bundle exec rspec"` works in
+  both shells, but `-t 'ruby -e "exit 1"'` is POSIX-only quoting. In `cmd.exe` the inner quotes have to be escaped
+  (or put the command in a `.bat` file, or in a Rake task, and call that). Variables are written `%NAME%`, not
+  `$NAME`.
+- **Stopping a run.** Each run starts in a new process group. On timeout its whole process tree is stopped with
+  `taskkill /T` (first without `/F`, then, after the same two-second grace period, with `/F`). Unlike on POSIX
+  systems, processes that a run leaves behind after it exits normally are not stopped: Windows finds a tree through
+  the parent process, which is gone by then, and its id may already belong to an unrelated process. Make test
+  helpers that start servers stop them.
+- **Sandboxes** are named `mr…` (shorter than `mutaruby-…`) under `%TEMP%`, because classic Windows paths are
+  limited to 260 characters. For a deeply nested project, enable long paths or point `TMP`/`TEMP` at a short
+  directory such as `C:\t`.
+- **Locked files.** A process that is still exiting, or a virus scanner, can hold a file open for a moment. Writes
+  into the sandbox and its removal are retried (10 times, 0.1 s apart) before mutaruby gives up.
+- **Symlinks** in the project are copied as symlinks when Windows allows it (Developer Mode or the symlink
+  privilege), and otherwise replaced by a copy of what they point to.
+- **Line endings.** Files with CRLF (or mixed) line endings are mutated in place without changing their line endings.
+  Sources are read as UTF-8 regardless of the console code page.
+
 ## Limitations
 
-- Linux and macOS only (process groups, `/bin/sh`). Windows is not supported.
+- On Windows, processes that a test run leaves running after it exits normally are not stopped (see
+  [Windows notes](#windows-notes)).
 - The test command is run as is for every mutant; mutaruby does not work out which tests cover which code.
 - The parser grammar is chosen to match the running Ruby, up to the newest grammar the installed `parser` gem knows.
   Files that `parser` cannot read (for example syntax newer than it supports) are skipped with a warning.

data/lib/mutaruby/command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'tempfile'
+require_relative 'platform'
 
 module Mutaruby
   # Runs the user's test command once, in a fresh process (a new shell and everything it starts), inside a sandbox.
@@ -16,18 +17,19 @@ module Mutaruby
     KILL_GRACE = 2
     POLL = 0.05
 
-    def initialize(command, root:, kill_grace: KILL_GRACE)
+    def initialize(command, root:, kill_grace: KILL_GRACE, platform: Platform.current)
       @command = command
+      @platform = platform
       @kill_grace = kill_grace
       @root = File.expand_path(root)
-      @live = []
+      @live = {} # pid => the thread reaping it
       @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
-      @lock.synchronize { @live.each { |pid| kill_group(pid) } }
+      @lock.synchronize { @live.each { |pid, waiter| kill_group(pid, waiter) } }
     end
 
     # dir: sandbox project dir. timeout: seconds (nil = none). capture: keep an output tail (for the baseline report).
@@ -46,13 +48,13 @@ module Mutaruby
 
     def execute(dir, timeout, env, out)
       started = monotonic
-      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 }
+      pid = Process.spawn(child_env(dir).merge(env), *@platform.spawn_args(@command),
+                          chdir: dir, in: File::NULL, out: out, err: out, **@platform.spawn_options)
       waiter = Process.detach(pid)
+      @lock.synchronize { @live[pid] = waiter }
       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)
+      # A timed-out run, and (where the platform allows) anything a finished run left behind, must not outlive it.
+      kill_group(pid, waiter) if timed_out || @platform.stop_leftovers?
       st = waiter.value
       @lock.synchronize { @live.delete(pid) }
       status = if timed_out then :timeout
@@ -78,25 +80,12 @@ module Mutaruby
       env
     end
 
-    # SIGTERM to the whole group, up to kill_grace seconds to exit, then SIGKILL.
-    def kill_group(pid)
-      signal_group('TERM', pid)
+    # Stop the whole tree gracefully, give it up to kill_grace seconds, then force it.
+    def kill_group(pid, waiter)
+      @platform.stop_tree(pid, graceful: true)
       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
-      # the group is already gone
-    end
-
-    def alive?(pid)
-      Process.kill(0, -pid)
-      true
-    rescue Errno::ESRCH, Errno::EPERM
-      false
+      sleep POLL while monotonic < deadline && @platform.alive?(pid, waiter)
+      @platform.stop_tree(pid, graceful: false)
     end
 
     def tail(bytes)

data/lib/mutaruby/generator.rb

@@ -97,7 +97,7 @@ module Mutaruby
         @errors << "#{@path}: cannot parse (not valid #{@src.encoding}); skipped"
         return []
       end
-      ast = Parsing.parse(@path, @src)
+      ast = Parsing.parse(@path, normalize_newlines)
       @out = []
       @seen = {}
       @scope = []   # namespace names ("Foo", "Bar")
@@ -109,6 +109,28 @@ module Mutaruby
       []
     end
 
+    # `parser` reads every "\r\n" as "\n", so its offsets count one character per CRLF line break. The source is
+    # parsed in that form; @crlf records where (in parser offsets) a "\n" stands for "\r\n" in the file, so every
+    # splice is made at the file's own character offsets and the file keeps its line endings.
+    def normalize_newlines
+      @crlf = {}
+      norm = @src.gsub("\r\n") do
+        @crlf[$~.begin(0) - @crlf.size] = true
+        "\n"
+      end
+      @newline = @crlf.empty? ? "\n" : "\r\n"
+      norm
+    end
+
+    def original_offset(pos)
+      pos + @crlf.count { |q, _| q < pos }
+    end
+
+    # A slice of the parsed source as it reads in the file.
+    def with_crlf(slice, start)
+      slice.each_char.with_index.map { |c, i| @crlf[start + i] ? "\r\n" : c }.join
+    end
+
     # lineno => 1-based index of that line among the identical (stripped) lines of the file.
     def occurrence_index(lines)
       seen = Hash.new(0)
@@ -130,7 +152,9 @@ module Mutaruby
       line = @lines[lineno - 1]
       return if line.include?(DISABLE_MARK)
 
-      text = Splicer.splice(@src, range.begin_pos, range.end_pos, orig, repl)
+      b = range.begin_pos
+      text = Splicer.splice(@src, original_offset(b), original_offset(range.end_pos), with_crlf(orig, b),
+                            repl.gsub("\n", @newline))
       return if @seen[text]
 
       @seen[text] = true

data/lib/mutaruby/ignore_file.rb

@@ -38,7 +38,7 @@ module Mutaruby
     attr_reader :entries, :path
 
     def self.load(path)
-      new(YAML.safe_load(File.read(path)), path: path)
+      new(YAML.safe_load(File.read(path, encoding: 'UTF-8')), path: path)
     rescue Psych::SyntaxError => e
       raise Invalid, "#{path}: not valid YAML (#{e})"
     end

data/lib/mutaruby/platform.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+module Mutaruby
+  # Everything that differs between POSIX systems and Windows: how a test command is started, how its whole process
+  # tree is stopped, and how sandboxes are named.
+  module Platform
+    # Linux, macOS and the BSDs: the command runs under /bin/sh as the leader of its own process group, and the group
+    # is signalled as a whole.
+    class Posix
+      def name = 'posix'
+
+      def spawn_args(command) = ['/bin/sh', '-c', command]
+
+      def spawn_options = { pgroup: true }
+
+      def temp_prefix = 'mutaruby-'
+
+      # After a run ends, whatever is left of its process group is stopped too.
+      def stop_leftovers? = true
+
+      # graceful: SIGTERM, otherwise SIGKILL, to the process group led by pid.
+      def stop_tree(pid, graceful:)
+        Process.kill(graceful ? 'TERM' : 'KILL', -pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # the group is already gone
+      end
+
+      # waiter: the thread reaping the run's leader (Process.detach); unused here, the group decides.
+      def alive?(pid, _waiter)
+        Process.kill(0, -pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      end
+    end
+
+    # Windows: the command string runs under cmd.exe (Process.spawn with a single string does that) in a new process
+    # group, and the tree below the command's process is stopped with taskkill /T (without /F first, then with /F).
+    class Windows
+      # system: how taskkill is run (replaceable in tests).
+      def initialize(system: ->(*argv) { Kernel.system(*argv, out: File::NULL, err: File::NULL) })
+        @system = system
+      end
+
+      def name = 'windows'
+
+      def spawn_args(command) = [command]
+
+      def spawn_options = { new_pgroup: true }
+
+      # Short: Windows paths are limited to 260 characters unless long paths are enabled.
+      def temp_prefix = 'mr'
+
+      # Not after a normal exit: taskkill /T finds the tree through the (now exited) parent process, and Windows may
+      # already have reused its id for an unrelated process.
+      def stop_leftovers? = false
+
+      def stop_tree(pid, graceful:)
+        @system.call('taskkill', '/T', *(graceful ? [] : ['/F']), '/PID', pid.to_s)
+      end
+
+      # While the thread reaping the command's process (Process.detach) runs, that process has not exited. (Signal 0
+      # is not a reliable liveness test on Windows: it can succeed for a process that has already exited.)
+      def alive?(_pid, waiter)
+        waiter.alive?
+      end
+    end
+
+    def self.windows?(host_os = RbConfig::CONFIG['host_os'])
+      host_os.match?(/mswin|mingw|cygwin/)
+    end
+
+    def self.for(host_os)
+      windows?(host_os) ? Windows.new : Posix.new
+    end
+
+    def self.current
+      @current ||= self.for(RbConfig::CONFIG['host_os'])
+    end
+  end
+end

data/lib/mutaruby/runner.rb

@@ -48,7 +48,8 @@ module Mutaruby
     def plan
       sel = selection
       files = sel.files
-      sources = files.to_h { |f| [f, File.read(File.join(@root, f), encoding: 'UTF-8')] }
+      # Bytes as they are (no newline conversion on Windows), read as UTF-8 whatever the default encoding.
+      sources = files.to_h { |f| [f, File.binread(File.join(@root, f)).force_encoding(Encoding::UTF_8)] }
       warnings = []
       all = files.flat_map do |f|
         g = Generator.new(sources[f], path: File.join(@root, f), rel: f, operators: @o.operators)

data/lib/mutaruby/sandbox.rb

@@ -3,6 +3,7 @@
 require 'fileutils'
 require 'find'
 require 'tmpdir'
+require_relative 'platform'
 
 module Mutaruby
   # A private copy of the project. Every test-command run happens inside one, so the user's files are never written:
@@ -12,16 +13,35 @@ module Mutaruby
   # is written back before the next mutant.
   class Sandbox
     DEFAULT_EXCLUDES = %w[.git coverage].freeze
-    PREFIX = 'mutaruby-'
+    # Writes and deletes are retried this many times, RETRY_DELAY seconds apart, while the file is locked (on Windows a
+    # process that is still exiting, or a virus scanner, can hold it for a moment).
+    RETRIES = 10
+    RETRY_DELAY = 0.1
+    LOCKED = [Errno::EACCES, Errno::EBUSY, Errno::EPERM].freeze
+
+    # Runs the block, retrying while it raises one of the LOCKED errors.
+    def self.retrying(tries: RETRIES, delay: RETRY_DELAY)
+      attempt = 1
+      begin
+        yield
+      rescue *LOCKED
+        raise if attempt >= tries
+
+        attempt += 1
+        sleep delay
+        retry
+      end
+    end
 
     attr_reader :dir
 
-    def initialize(root, excludes: [])
+    def initialize(root, excludes: [], platform: Platform.current)
       # The real path: Find does not descend into a symlink, so a root reached through one (/tmp on macOS) would
       # otherwise be copied as an empty directory.
       @root = File.realpath(root)
       @excludes = DEFAULT_EXCLUDES + excludes
-      @base = Dir.mktmpdir(PREFIX)
+      @prefix = platform.temp_prefix
+      @base = Dir.mktmpdir(@prefix)
       @tmp_parent = File.realpath(File.dirname(@base))
       @dir = File.join(@base, File.basename(@root))
       copy_tree
@@ -35,15 +55,16 @@ module Mutaruby
     def with_file(rel, text, original)
       target = path(rel)
       begin
-        File.binwrite(target, text)
+        Sandbox.retrying { File.binwrite(target, text) }
         yield
       ensure
-        File.binwrite(target, original)
+        Sandbox.retrying { File.binwrite(target, original) }
       end
     end
 
+    # Removes the sandbox. Unlike rm_rf, this does not silently leave a locked file behind: it retries, then raises.
     def cleanup
-      FileUtils.rm_rf(@base)
+      Sandbox.retrying { FileUtils.rm_r(@base) if File.exist?(@base) }
     end
 
     private
@@ -58,10 +79,18 @@ module Mutaruby
     # A sandbox directory (this one or another worker's). When the temporary directory lies inside the project (for
     # example TMPDIR=./tmp), copying it would copy the sandbox into itself. Paths found under the real root are real.
     def sandbox?(path)
-      File.directory?(path) && File.basename(path).start_with?(PREFIX) &&
+      File.directory?(path) && File.basename(path).start_with?(@prefix) &&
         File.dirname(path) == @tmp_parent
     end
 
+    # A symlink is copied as a symlink. Where that is not allowed (Windows without the symlink privilege), what it
+    # points to is copied instead; a dangling link is skipped.
+    def link(src, dest)
+      File.symlink(File.readlink(src), dest)
+    rescue NotImplementedError, Errno::EPERM, Errno::EACCES
+      FileUtils.cp_r(src, dest) if File.exist?(src) # cp_r follows a symlink given as its source
+    end
+
     def copy_tree
       FileUtils.mkdir_p(@dir)
       Find.find(@root) do |src|
@@ -72,7 +101,7 @@ module Mutaruby
         dest = File.join(@dir, rel)
         st = File.lstat(src)
         if st.symlink?
-          File.symlink(File.readlink(src), dest)
+          link(src, dest)
         elsif st.directory?
           FileUtils.mkdir_p(dest)
         elsif st.file? # not sockets, FIFOs or devices: copying a FIFO would block

data/lib/mutaruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mutaruby
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mutaruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Atlas Authorization
@@ -51,6 +51,7 @@ files:
 - lib/mutaruby/ignore_file.rb
 - lib/mutaruby/mutation.rb
 - lib/mutaruby/parsing.rb
+- lib/mutaruby/platform.rb
 - lib/mutaruby/reporters.rb
 - lib/mutaruby/runner.rb
 - lib/mutaruby/sandbox.rb