mutineer 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4020e2cd0e53ac4f406998d2c251d26abee9f75c4e6ceef365f2ffe565be50ab
+  data.tar.gz: f42dbc71077fc802b56f878e27885568f3d128f244875fb678dede5f6940f385
+SHA512:
+  metadata.gz: dc24bb60419b7d701a85a09c70495c9d9d7ce2cd2d5b5a10621cb03a940276c3526dc650ee4deb7f93529e09b67b872777c2483419979d5740a83aa9ac9bfd26
+  data.tar.gz: ff59317a64ab0e3478c7dde381ac9752b56c83920d1a63bcf6528ac826f286d787b2d560c1946e897790bd47325ac2209d22b537e3baa146b90f2bedcd2f0c72

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-06-28
+
+### Added
+- **Boot mode for Rails (and any app needing its environment booted)** —
+  `--rails` boots `config/environment` once in the parent and forks per mutant
+  (children inherit the booted app), defaults the strategy to `redefine`, and
+  reconnects ActiveRecord in each fork for DB fork-safety. `--boot FILE` boots a
+  custom entry point. Boot mode requires `--test` files and runs them for every
+  mutant (coverage-guided selection in boot mode is future work). `.mutineer.yml`
+  accepts `boot:` and `rails:`.
+- GitHub Actions CI (test suite + gem build on Ruby 3.4, ubuntu + macos).
+
+### Changed
+- `--strategy` values are now `reload` / `redefine` (canonical); `7a` / `7b`
+  remain accepted as deprecated aliases.
+
+## [0.1.0] - 2026-06-28
+
+### Added
+- Initial release of Mutineer — a clean-room, Prism-based mutation-testing tool
+  for Ruby with zero runtime dependencies (Ruby ≥ 3.4).
+- Mutation operators: arithmetic, comparison, boolean-connector, boolean-literal,
+  statement-removal (Tier 1, default); return-nil, literal-mutation,
+  condition-negation (Tier 2, opt-in via `--operators`).
+- Coverage-guided test selection with a digest-keyed, auto-invalidating cache.
+- Fork-isolated, parallel execution (`--jobs`) with per-mutant timeouts.
+- Two application strategies: `reload` (whole-file, default) and `redefine`
+  (surgical), verified to agree on namespaced multi-statement methods. (`7a`/`7b`
+  accepted as deprecated aliases.)
+- `run`, `--dry-run`, `--threshold`, `--only`, `--operators`, `--strategy`,
+  `--format human|json`, `--output`, `--list-operators`.
+- `.mutineer.yml` configuration (CLI > config > default precedence).
+- Byte-correct source handling for multibyte (UTF-8) sources.
+
+[0.2.0]: https://github.com/davidteren/mutineer/releases/tag/v0.2.0
+[0.1.0]: https://github.com/davidteren/mutineer/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Teren
+
+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,118 @@
+# Mutineer
+
+A clean-room mutation-testing tool for Ruby. Mutineer mutates your source one
+change at a time, runs your Minitest suite against each mutant, and reports the
+ones your tests failed to catch — the gaps where your suite isn't actually
+testing anything.
+
+- **Prism + stdlib only** — zero runtime dependencies (Ruby ≥ 3.4).
+- **One mutation per mutant**, validity-checked by re-parsing.
+- **Fork-isolated**, parallel execution (Linux + macOS).
+- **Coverage-guided** — each mutant runs only the test files that cover its line.
+
+📖 **[mutineer.github.io →](https://davidteren.github.io/mutineer/)** — overview, operators, and usage.
+
+## Install
+
+```sh
+gem install mutineer
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "mutineer", group: :test
+```
+
+## Usage
+
+```sh
+mutineer run <source...> --test <test...> [options]
+```
+
+Mutate `lib/calculator.rb`, checking it against its test, and fail CI if the
+mutation score drops below 90%:
+
+```sh
+mutineer run lib/calculator.rb --test test/calculator_test.rb --threshold 90
+```
+
+### Options
+
+| Flag | Meaning |
+|------|---------|
+| `--test FILE` | Test file covering the sources (repeatable) |
+| `--operators LIST` | Comma-separated operator names (default: the Tier-1 set) |
+| `--threshold FLOAT` | Exit 1 when the score is below FLOAT (default: 0 = off) |
+| `--only NAME` | Restrict to one fully-qualified subject, e.g. `Calculator#add` |
+| `--jobs N` | Parallel worker count (default: processor count) |
+| `--strategy NAME` | Mutation application: `reload` whole-file (default) or `redefine` surgical (`7a`/`7b` accepted as deprecated aliases) |
+| `--format human\|json` | Report format (default: human) |
+| `--output FILE` | Write the report to FILE instead of stdout |
+| `--dry-run` | List candidate mutations without executing |
+| `--list-operators` | List available operators (default vs optional) and exit |
+| `--version`, `--help` | Print version / usage and exit |
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Score ≥ threshold (or no threshold set) |
+| `1` | Survivors below threshold, or a runtime error |
+| `2` | Usage / invalid-flag error |
+
+### Operators
+
+Run `mutineer --list-operators` to see them. Default (Tier 1): `arithmetic`,
+`comparison`, `boolean_connector`, `boolean_literal`, `statement_removal`.
+Available but off by default (Tier 2, enable via `--operators`): `return_nil`,
+`literal_mutation`, `condition_negation`.
+
+## Rails apps
+
+Rails code needs its environment booted before the suite runs, so point Mutineer
+at your app with `--rails` and run it inside the project's bundle:
+
+```sh
+RAILS_ENV=test bundle exec mutineer run \
+  app/models/order.rb --test test/models/order_test.rb --rails
+```
+
+`--rails` boots `config/environment` once in the parent process (every mutant
+then forks and inherits it), defaults `--strategy` to `redefine` (surgical — it
+avoids reloading files into the app tree), and reconnects ActiveRecord in each
+fork so the database connection is fork-safe. Use `--boot FILE` to boot a
+different entry point. Boot mode requires at least one `--test` file and runs
+those tests for every mutant (coverage-guided selection is not yet available in
+boot mode).
+
+Add Mutineer to your Gemfile's test group:
+
+```ruby
+gem "mutineer", group: :test, require: false
+```
+
+## Configuration
+
+Mutineer reads an optional `.mutineer.yml` from the project root (nearest one,
+walking up). CLI flags override config; config overrides defaults.
+
+Sources are positional CLI arguments and test files come from `--test`; the
+config file accepts these keys: `operators`, `threshold`, `jobs`, `only`,
+`require` (extra files to load before mutating), and `boot`/`rails`.
+
+```yaml
+# .mutineer.yml
+operators: [arithmetic, comparison, boolean_connector, boolean_literal, statement_removal]
+threshold: 90
+jobs: 4
+require:
+  - config/environment
+```
+
+Coverage results are cached in `.mutineer/coverage.json` (digest-keyed; rebuilt
+automatically when sources change). Add `.mutineer/` to your `.gitignore`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/bin/mutineer

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/mutineer"
+
+Mutineer::CLI.start(ARGV)

data/lib/mutineer/cli.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "set"
+require_relative "version"
+require_relative "config"
+require_relative "parser"
+require_relative "project"
+require_relative "runner"
+require_relative "reporter"
+require_relative "mutator_registry"
+
+module Mutineer
+  # Command-line entry point. `start` is the single public method called by
+  # bin/mutineer; it parses argv, acts, and exits with a pinned code.
+  #
+  # Exit codes (taxonomy consistent across M1–M5):
+  #   0  success / requested output (--version, --help, score >= threshold)
+  #   1  survivors below threshold, or a runtime error
+  #   2  usage / flag error (unknown subcommand, invalid flag, unknown operator,
+  #      out-of-range threshold)
+  class CLI
+    BANNER = <<~USAGE
+      Usage: mutineer [options] <command> [args]
+
+      Commands:
+        run [options] <source...> --test <test...>   Mutate, run, and report
+        run --dry-run [options] <source...>          Print candidate mutations only
+
+      Run options:
+        --test FILE          Test file covering the sources (repeatable)
+        --operators LIST     Comma-separated operator names (default: Tier 1 set)
+        --threshold FLOAT    Fail (exit 1) when score < FLOAT (default: 0 = off)
+        --only NAME          Restrict to one fully-qualified subject
+        --jobs N             Parallel worker count (default: processor count)
+        --strategy NAME      reload (whole-file) or redefine (surgical); default: reload
+        --boot FILE          Require FILE once in the parent to boot the app env, then
+                             fork per mutant (Rails apps; requires --test, no coverage)
+        --rails              Sugar for --boot config/environment --strategy redefine
+        --format human|json  Report format (default: human)
+        --output FILE        Write the report to FILE instead of stdout
+        --dry-run            List mutations without executing
+
+      Options:
+        --list-operators  List available operators (default vs optional) and exit
+        --version         Print version and exit
+        --help            Print this help and exit
+    USAGE
+
+    # Field symbols whose config-file value is suppressed when the flag is typed.
+    PRECEDENCE_FLAGS = %i[operators jobs threshold only].freeze
+
+    # Deprecated internal strategy names, mapped to their canonical equivalents.
+    STRATEGY_ALIASES = { "7a" => "reload", "7b" => "redefine" }.freeze
+
+    def self.start(argv)
+      opts = {}            # symbol => value, the CLI-provided Config fields
+      explicit = Set.new   # precedence keys the user typed (KTD3)
+      show_operators = false
+
+      parser = OptionParser.new do |o|
+        o.banner = BANNER
+        o.on("--version") do
+          puts Mutineer::VERSION
+          exit 0
+        end
+        o.on("--help") do
+          puts BANNER
+          exit 0
+        end
+        o.on("--list-operators") { show_operators = true }
+        o.on("--dry-run") { opts[:dry_run] = true }
+        o.on("--only NAME") { |v| opts[:only] = v; explicit << :only }
+        o.on("--test FILE") { |v| (opts[:tests] ||= []) << v }
+        o.on("--operators LIST") { |v| opts[:operators] = v.split(",").map(&:strip); explicit << :operators }
+        o.on("--threshold FLOAT") { |v| opts[:threshold] = v.to_f; explicit << :threshold }
+        o.on("--jobs N") { |v| opts[:jobs] = v; explicit << :jobs }
+        o.on("--strategy STRAT") { |v| opts[:strategy] = v; explicit << :strategy }
+        o.on("--boot FILE") { |v| opts[:boot] = v; explicit << :boot }
+        o.on("--rails") { opts[:rails] = true }
+        o.on("--format FORMAT") { |v| opts[:format] = v }
+        o.on("--output FILE") { |v| opts[:output] = v }
+      end
+
+      begin
+        parser.parse!(argv)
+      rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+        warn "mutineer: #{e.message}"
+        exit 2
+      end
+
+      if show_operators
+        list_operators
+        exit 0
+      end
+
+      if argv.empty?
+        puts BANNER
+        exit 0
+      end
+
+      begin
+        file_path = Config.find_file
+        file_hash = file_path ? Config.from_file(file_path) : {}
+        config = Config.resolve(opts, file_hash, explicit)
+      rescue Mutineer::ConfigError => e
+        # R8: the lib layer raises instead of killing the host; the CLI maps a
+        # config (usage) error to exit 2.
+        warn "mutineer: #{e.message}"
+        exit 2
+      end
+
+      case argv.first
+      when "run"
+        config.sources = argv[1..]
+        run(config)
+      else
+        warn "mutineer: unknown command '#{argv.first}'"
+        exit 2
+      end
+    end
+
+    def self.list_operators
+      MutatorRegistry::ALL.each_key do |name|
+        state = MutatorRegistry.default?(name) ? "default" : "disabled"
+        puts format("%-20s tier %d  %-9s %s",
+                    name, MutatorRegistry.tier(name), state, MutatorRegistry::DESCRIPTIONS[name])
+      end
+    end
+
+    def self.run(config)
+      if config.sources.empty?
+        warn "mutineer: run requires at least one source file"
+        exit 2
+      end
+      validate!(config)
+
+      config.dry_run ? dry_run(config) : execute(config)
+    rescue ArgumentError => e
+      # Unknown --operators value surfaces here; no backtrace reaches the user.
+      warn "mutineer: #{e.message}"
+      exit 2
+    rescue SystemCallError => e
+      # R5: a missing/unreadable path reaches here as Errno::ENOENT etc. — a plain
+      # message and usage exit, never a raw backtrace.
+      warn "mutineer: #{e.message}"
+      exit 2
+    rescue SyntaxError => e
+      # A syntactically invalid source file surfaces when `require`d; report it
+      # cleanly rather than dumping a backtrace.
+      warn "mutineer: cannot load source: #{e.message}"
+      exit 1
+    rescue Mutineer::ParseError => e
+      warn "mutineer: error reading: #{e.message}"
+      exit 1
+    end
+
+    # Flag validation: every flag/usage failure exits 2 (C7), consistent with the
+    # taxonomy above — CI can tell "mistyped flag" from "tests too weak."
+    def self.validate!(config)
+      unless (0.0..100.0).cover?(config.threshold)
+        warn "mutineer: --threshold must be between 0 and 100"
+        exit 2
+      end
+
+      jobs = Integer(config.jobs.to_s, exception: false)
+      if jobs.nil? || jobs < 1
+        warn "mutineer: --jobs requires a positive integer (got: #{config.jobs})"
+        exit 2
+      end
+      config.jobs = jobs
+
+      unless %w[human json].include?(config.format)
+        warn %(mutineer: unknown format "#{config.format}". Expected: human, json)
+        exit 2
+      end
+
+      # Canonical strategies are reload|redefine; 7a/7b are accepted as deprecated
+      # aliases. Normalize to canonical so the rest of the pipeline sees one name.
+      config.strategy = STRATEGY_ALIASES.fetch(config.strategy, config.strategy)
+      unless %w[reload redefine].include?(config.strategy)
+        warn %(mutineer: unknown strategy "#{config.strategy}". Expected: reload, redefine)
+        exit 2
+      end
+
+      # Boot mode does no coverage selection — every mutant runs the given tests —
+      # so at least one --test file is mandatory (there is nothing to select from).
+      if config.boot && config.tests.empty?
+        warn "mutineer: --boot/--rails requires at least one --test file"
+        exit 2
+      end
+
+      preflight_output!(config.output) if config.output
+      validate_paths!(config)
+    end
+
+    # R5: validate path existence up front so a typo is a clean usage error (exit
+    # 2), not an Errno::ENOENT backtrace from deep in the run. Flag checks run
+    # first so a bad flag still reports the flag, not the missing file.
+    def self.validate_paths!(config)
+      missing = (config.sources + config.tests)
+                .reject { |p| File.exist?(File.expand_path(p, config.project_root)) }
+      return if missing.empty?
+
+      warn "mutineer: no such file: #{missing.join(', ')}"
+      exit 2
+    end
+
+    def self.preflight_output!(path)
+      dir = File.dirname(File.expand_path(path))
+      return if File.directory?(dir) && File.writable?(dir)
+
+      reason = File.directory?(dir) ? "directory is not writable" : "no such directory"
+      warn "mutineer: cannot write to #{path}: #{reason}"
+      exit 2
+    end
+
+    def self.execute(config)
+      if config.tests.empty?
+        warn "mutineer: run requires at least one --test file (or use --dry-run)"
+        exit 2
+      end
+
+      aggregate, source_map = Runner.execute(config)
+      reporter = Reporter.new(aggregate, source_map)
+      reporter.report(out: $stdout, err: $stderr, threshold: config.threshold,
+                      format: config.format, output: config.output)
+      exit reporter.exit_code(threshold: config.threshold)
+    end
+
+    def self.dry_run(config)
+      operator_classes = MutatorRegistry.resolve(config.operators || MutatorRegistry::DEFAULT_NAMES)
+      sources = {}
+      per_operator = Hash.new(0)
+      skipped = 0
+
+      Project.discover(config.sources, only: config.only).each do |subject|
+        source = (sources[subject.file] ||= Parser.parse_file(subject.file).source.source)
+        operator_classes.each do |klass|
+          klass.new.mutations_for(subject, source).each do |mutation|
+            unless mutation.valid?(source)
+              skipped += 1
+              next
+            end
+            per_operator[mutation.operator] += 1
+            original = source.byteslice(mutation.start_offset...mutation.end_offset)
+            line = source.byteslice(0, mutation.start_offset).count("\n") + 1
+            puts "[#{mutation.operator}] #{subject.qualified_name}  " \
+                 "#{subject.file}:#{line}  `#{original}` -> `#{mutation.replacement}`"
+          end
+        end
+      end
+
+      total = per_operator.values.sum
+      breakdown = per_operator.map { |op, n| "#{op}: #{n}" }.join(", ")
+      summary = breakdown.empty? ? "" : "#{breakdown} — "
+      puts "#{summary}#{total} mutations (dry run, not executed); #{skipped} skipped (invalid)"
+      exit 0
+    end
+  end
+end

data/lib/mutineer/config.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "etc"
+require "yaml"
+
+module Mutineer
+  # Raised by the config layer instead of calling exit/abort — a data class must
+  # never kill the host process (R8). The CLI rescues this and maps it to exit 2.
+  class ConfigError < StandardError; end
+
+  # Plain run configuration, populated by the CLI (or directly by the
+  # integration test). `operators` nil means "all default operators";
+  # `threshold` 0.0 means the CI gate is off (spec §10).
+  #
+  # M5 adds: jobs (parallel workers), format (human|json), output (report file),
+  # strategy (reload|redefine), require_paths (extra files to load). Config loading and
+  # the CLI > file > default precedence merge live here (KTD3/KTD4).
+  #
+  # Boot mode adds: boot (a file to require ONCE in the parent so the app env —
+  # e.g. Rails — is booted before forking; sources are then NOT manually required)
+  # and rails (sugar: defaults boot to config/environment and strategy to redefine,
+  # and reconnects ActiveRecord per fork).
+  Config = Struct.new(
+    :sources, :tests, :operators, :threshold, :only, :dry_run,
+    :cache_dir, :project_root, :load_paths,
+    :jobs, :format, :output, :strategy, :require_paths,
+    :boot, :rails,
+    keyword_init: true
+  ) do
+    CONFIG_FILE = ".mutineer.yml"
+    # Keys accepted in .mutineer.yml (R7). `require` maps to the :require_paths field.
+    KNOWN_KEYS = %w[operators jobs threshold only require boot rails].freeze
+
+    def initialize(**kwargs)
+      super
+      self.sources       ||= []
+      self.tests         ||= []
+      self.threshold     ||= 0.0
+      self.dry_run       ||= false
+      self.cache_dir     ||= ".mutineer"
+      self.project_root  ||= Dir.pwd
+      self.load_paths    ||= ["lib"]
+      self.jobs          ||= Etc.nprocessors
+      self.format        ||= "human"
+      self.strategy      ||= "reload"
+      self.require_paths ||= []
+      self.rails         = false if rails.nil?
+    end
+
+    # Walk from `start` toward `home`, returning the first .mutineer.yml path found
+    # or nil. Checks `home` itself, then stops; if `start` is above `home`
+    # (e.g. /tmp), the walk continues to the filesystem root (KTD4). Pure
+    # discovery — reads no file content.
+    def self.find_file(start = Dir.pwd, home = File.expand_path("~"))
+      dir = File.expand_path(start)
+      loop do
+        candidate = File.join(dir, CONFIG_FILE)
+        return candidate if File.file?(candidate)
+        break if dir == home
+
+        parent = File.dirname(dir)
+        break if parent == dir # filesystem root
+
+        dir = parent
+      end
+      nil
+    end
+
+    # Parse a .mutineer.yml into a symbol-keyed hash of recognized keys. Unknown
+    # keys / unknown operator names emit a one-line stderr warning and are ignored
+    # (R7). A YAML syntax error raises ConfigError (R7a/R8) — never a silent
+    # fallback to defaults, and never an exit from the lib layer.
+    def self.from_file(path)
+      raw = YAML.safe_load(File.read(path)) || {}
+      name = File.basename(path)
+      unless raw.is_a?(Hash)
+        warn "mutineer: #{name} ignored: expected a YAML mapping of keys to values"
+        return {}
+      end
+
+      out = {}
+      raw.each do |key, value|
+        ks = key.to_s
+        unless KNOWN_KEYS.include?(ks)
+          warn "mutineer: unknown config key #{ks.inspect} in #{name} " \
+               "(known: #{KNOWN_KEYS.join(', ')}); ignored"
+          next
+        end
+        out[field_for(ks)] = coerce(ks, value, name)
+      end
+      out
+    rescue Psych::SyntaxError => e
+      raise ConfigError, "#{File.basename(path)} parse error: #{e.message}"
+    end
+
+    # Apply precedence (KTD3): start from the CLI-provided values, then fill in a
+    # config-file value only for keys the user did NOT type on the command line.
+    # `explicit` is a Set of field symbols the CLI saw with a value; a Set (not
+    # nil-sentinels) is used because some valid values are zero/false.
+    def self.resolve(cli_opts, file_hash, explicit)
+      merged = cli_opts.dup
+      file_hash.each { |k, v| merged[k] = v unless explicit.include?(k) }
+      config = new(**merged)
+
+      # --rails sugar: boot config/environment and prefer the surgical (redefine)
+      # strategy, which avoids writing tempfiles into the app tree and Zeitwerk
+      # reload hazards. An explicit --strategy always wins.
+      if config.rails
+        config.boot ||= "config/environment"
+        config.strategy = "redefine" unless explicit.include?(:strategy)
+      end
+      config
+    end
+
+    def self.field_for(known_key)
+      known_key == "require" ? :require_paths : known_key.to_sym
+    end
+
+    def self.coerce(known_key, value, file_name)
+      case known_key
+      when "operators" then filter_operators(Array(value).map(&:to_s), file_name)
+      when "jobs"      then value.to_i
+      when "threshold" then value.to_f
+      when "require"   then Array(value).map(&:to_s)
+      when "boot"      then value.to_s
+      when "rails"     then value == true || value.to_s == "true"
+      else value
+      end
+    end
+
+    # Drop (with a warning) operator names the registry doesn't know (R7).
+    # Referenced lazily so config.rb carries no load-order dependency on the
+    # registry; by the time a config is parsed at runtime, it is loaded.
+    def self.filter_operators(names, file_name)
+      known = MutatorRegistry::ALL.keys
+      names.select do |n|
+        next true if known.include?(n)
+
+        warn "mutineer: unknown operator #{n.inspect} in #{file_name} " \
+             "(known: #{known.join(', ')}); ignored"
+        false
+      end
+    end
+  end
+end