mutineer 0.7.0 → 0.9.0

data/lib/mutineer/coverage_map.rb

@@ -117,6 +117,9 @@ module Mutineer
       self
     end
 
+    # Runs standalone Phase A coverage capture.
+    #
+    # @api private
     def run_phase_a
       @phase_a_ran = true
       @map = {}
@@ -160,6 +163,11 @@ module Mutineer
     # fork + Marshal-over-pipe + hard-exit! discipline as WorkerPool/Isolation.
     def fork_capture(abs_test, abs_sources, rails)
       rd, wr = IO.pipe
+      # #19: Marshal output is binary — an un-binmoded pipe can raise
+      # Encoding::UndefinedConversionError on write, which the child's rescue then
+      # swallows, losing the real error and yielding a bare "no result".
+      rd.binmode
+      wr.binmode
       pid = fork do
         rd.close
         payload =
@@ -189,12 +197,30 @@ module Mutineer
       wr.close
       data = rd.read
       rd.close
-      Process.waitpid(pid)
-      return nil if data.empty?
+      _, status = Process.waitpid2(pid)
+      # #19: an empty pipe means the child died before writing (e.g. a hard crash,
+      # OOM, or a signal from the test's own subprocess handling). Report HOW it
+      # died (exit status / signal) as a diagnostic string so --verbose has
+      # something actionable instead of a silent "no result".
+      return "child wrote no result (#{describe_status(status)})" if data.empty?
 
       Marshal.load(data)
-    rescue StandardError
-      nil
+    rescue StandardError => e
+      "parent could not read capture result: #{e.class}: #{e.message}"
+    end
+
+    # Human description of a child Process::Status for capture diagnostics.
+    #
+    # @api private
+    # @param status [Process::Status] the reaped child status.
+    # @return [String] e.g. "killed by signal 9 (SIGKILL)" or "exit status 1".
+    def describe_status(status)
+      if status.signaled?
+        sig = status.termsig
+        "killed by signal #{sig}#{Signal.signame(sig) ? " (SIG#{Signal.signame(sig)})" : ''}"
+      else
+        "exit status #{status.exitstatus.inspect}"
+      end
     end
 
     # Spawns a fresh `ruby` reading an inline script from stdin. A fork would
@@ -225,6 +251,12 @@ module Mutineer
       fail_test(test_path, "invalid coverage output: #{e.message}")
     end
 
+    # Records a failed coverage capture.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @param reason [String] failure reason.
+    # @return [void]
     def fail_test(test_path, reason)
       rel = relativize(test_path)
       @failed_test_files << rel
@@ -232,10 +264,20 @@ module Mutineer
       nil
     end
 
+    # Builds the framework-specific subprocess script.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @return [String] Ruby script text.
     def subprocess_script(test_path)
       @framework == "rspec" ? rspec_subprocess_script(test_path) : minitest_subprocess_script(test_path)
     end
 
+    # Builds the minitest subprocess script.
+    #
+    # @api private
+    # @param test_path [String] test file path.
+    # @return [String] Ruby script text.
     def minitest_subprocess_script(test_path)
       <<~RUBY
         require "coverage"
@@ -322,6 +364,13 @@ module Mutineer
       File.exist?(absolute(@boot_path)) ? @boot_path : "#{@boot_path}.rb"
     end
 
+    # Groups a digest with its role and paths.
+    #
+    # @api private
+    # @param digest [String] digest string.
+    # @param role [String] digest role.
+    # @param paths [Array<String>] paths in the digest group.
+    # @return [Array(String, String, Array<String>)] grouped digest data.
     def digest_group(digest, role, paths)
       paths.sort.each do |p|
         content = File.read(absolute(p))
@@ -347,8 +396,16 @@ module Mutineer
       end
     end
 
+    # Returns the cache path.
+    #
+    # @api private
+    # @return [String] cache file path.
     def cache_path = File.join(@cache_dir, "coverage.json")
 
+    # Reads the coverage cache.
+    #
+    # @api private
+    # @return [Hash, nil] cached payload.
     def read_cache
       return nil unless File.exist?(cache_path)
 
@@ -357,6 +414,10 @@ module Mutineer
       nil # corrupt cache — rebuild from scratch
     end
 
+    # Saves the coverage cache.
+    #
+    # @api private
+    # @return [void]
     def save
       FileUtils.mkdir_p(@cache_dir)
       data = { "digest" => @digest, "failed_test_files" => @failed_test_files, "map" => @map }
@@ -365,20 +426,41 @@ module Mutineer
       File.rename(tmp, cache_path) # atomic swap
     end
 
+    # Warns when coverage capture was incomplete.
+    #
+    # @api private
+    # @return [void]
     def warn_incomplete
       warn "[mutineer] cached coverage map may be incomplete; these test files " \
            "failed to contribute: #{@failed_test_files.join(', ')}"
     end
 
+    # Returns absolute source paths.
+    #
+    # @return [Array<String>] absolute source paths.
     def abs_source_paths = @source_paths.map { |p| absolute(p) }
+
+    # Returns absolute load paths.
+    #
+    # @return [Array<String>] absolute load paths.
     def abs_load_paths   = @load_paths.map { |p| absolute(p) }
 
+    # Relativizes a path against the project root.
+    #
+    # @api private
+    # @param path [String] path to relativize.
+    # @return [String] relative path.
     def relativize(path)
       return path unless path.start_with?("/")
 
       path.delete_prefix("#{@project_root}/")
     end
 
+    # Expands a path relative to the project root.
+    #
+    # @api private
+    # @param path [String] path to expand.
+    # @return [String] absolute path.
     def absolute(path)
       File.absolute_path?(path) ? path : File.expand_path(path, @project_root)
     end

data/lib/mutineer/isolation.rb

@@ -10,20 +10,25 @@ module Mutineer
   # exit status into a Result.
   #
   # Exit-status contract (the block's return value, or an explicit exit, is the
-  # child's status): 0 => survived, 1 => killed, 2 => error. Timeout is detected
-  # by the parent's monitor flag, not by status.signaled? (which is true for ANY
-  # signal death, e.g. SIGSEGV — it cannot tell our SIGKILL apart from the OS's).
+  # child's status): 0 => survived, 1 => killed, 2 => error. Timeout is
+  # detected by the parent's monitor flag, not by status.signaled? (which is
+  # true for ANY signal death, e.g. SIGSEGV — it cannot tell our SIGKILL apart
+  # from the OS's).
   #
-  # mutineer: the reload strategy this enables (whole-file `load`) re-executes the
-  # entire file — any top-level code runs again. Acceptable for POROs; document
-  # if users hit issues with initializers/callbacks. Alternative: the redefine
-  # strategy (surgical single-method redefinition).
+  # mutineer: the reload strategy this enables (whole-file `load`) re-executes
+  # the entire file — any top-level code runs again. Acceptable for POROs;
+  # document if users hit issues with initializers/callbacks. Alternative: the
+  # redefine strategy (surgical single-method redefinition).
   class Isolation
     DEFAULT_TIMEOUT = 10 # seconds
 
     # Runs the block in a forked child. The block's return value (an Integer
     # exit code) or any explicit `exit` is honoured; an unhandled exception
     # becomes exit 2 with the cause written to STDERR.
+    #
+    # @param timeout [Integer] timeout in seconds.
+    # @yieldreturn [Integer] child exit status.
+    # @return [Mutineer::Result] result from the child process.
     def self.run(timeout: DEFAULT_TIMEOUT)
       pid = fork do
         code = 0
@@ -43,11 +48,12 @@ module Mutineer
         exit!(code)
       end
 
-      # Single-threaded deadline poll (R2): we are the ONLY caller of waitpid on
-      # this pid, so we never reap-then-kill. We SIGKILL only after WNOHANG shows
-      # the child is still alive past the deadline — so the kill can never hit a
-      # reaped/recycled pid. Timeout is a parent-side fact (deadline reached), not
-      # status.signaled? (which is true for ANY signal death, e.g. SIGSEGV).
+      # Single-threaded deadline poll (R2): we are the ONLY caller of waitpid
+      # on this pid, so we never reap-then-kill. We SIGKILL only after WNOHANG
+      # shows the child is still alive past the deadline — so the kill can
+      # never hit a reaped/recycled pid. Timeout is a parent-side fact
+      # (deadline reached), not status.signaled? (which is true for ANY signal
+      # death, e.g. SIGSEGV).
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       loop do
         reaped, status = Process.waitpid2(pid, Process::WNOHANG)
@@ -63,13 +69,19 @@ module Mutineer
     end
 
     # Strategy 7a (default): write the whole mutated file and `load` it, which
-    # reopens its classes and redefines every method in place. Re-runs file-level
-    # side effects. Child-only — mutates the loaded program.
+    # reopens its classes and redefines every method in place. Re-runs file-
+    # level side effects. Child-only — mutates the loaded program.
     #
     # The tempfile is created in the ORIGINAL file's directory, not the system
-    # temp dir, so any `require_relative` in the mutated source resolves against
-    # its real neighbours (e.g. a mutator's `require_relative "base"`). Writing it
-    # elsewhere makes those requires resolve to the temp dir and raise LoadError.
+    # temp dir, so any `require_relative` in the mutated source resolves
+    # against its real neighbours (e.g. a mutator's `require_relative
+    # "base"`). Writing it elsewhere makes those requires resolve to the temp
+    # dir and raise LoadError.
+    #
+    # @api private
+    # @param mutated [String] mutated source text.
+    # @param source_file [String] original source file path.
+    # @return [Object] whatever `load` returns.
     def self.apply_whole_file(mutated, source_file)
       Tempfile.create(["mutineer_mutant", ".rb"], File.dirname(source_file)) do |f|
         f.write(mutated)
@@ -78,47 +90,69 @@ module Mutineer
       end
     end
 
-    # Redefine strategy: extract just the enclosing DefNode, apply the mutation to
-    # that snippet, wrap it in its real namespace, and `load` only that one method
-    # back into the running process. No file-level side effects re-run. Child-only.
+    # Redefine strategy: extract just the enclosing DefNode, apply the mutation
+    # to that snippet, wrap it in its real namespace, and `load` only that one
+    # method back into the running process. No file-level side effects re-run.
+    # Child-only.
     #
     # The snippet keeps its own `def self.x` for singletons, so the namespace
     # wrapper redefines instance and singleton methods correctly without any
     # special-casing.
+    #
+    # @api private
+    # @param mutation [Mutineer::Mutation] mutation to apply.
+    # @param subject [Mutineer::Subject] subject being mutated.
+    # @param source [String] full source text.
+    # @return [Object] whatever `load` returns.
     def self.apply_surgical(mutation, subject, source)
       loc = subject.def_node.location
       def_start = loc.start_offset
-      # Byte slicing (C1): Prism offsets are byte offsets.
       snippet = source.byteslice(def_start...loc.end_offset)
       rel_s = mutation.start_offset - def_start
       rel_e = mutation.end_offset - def_start
       mutated_def = snippet.byteslice(0...rel_s) + mutation.replacement + snippet.byteslice(rel_e..)
 
       # Rebuild the FULL namespace nesting textually so unqualified enclosing-
-      # namespace constants resolve exactly as the reload strategy would. A bare
-      # redefinition on the owner would collapse Module.nesting to [owner] and
-      # raise NameError on such constants (C2 scope-collapse).
+      # namespace constants resolve exactly as the reload strategy would. A
+      # bare redefinition on the owner would collapse Module.nesting to [owner]
+      # and raise NameError on such constants (C2 scope-collapse).
       keywords = nesting_keywords(subject.namespace)
       prefix   = keywords.map { |kw, name| "#{kw} #{name}" }.join("\n")
       prefix  += "\n" unless prefix.empty?
-      wrapped  = "#{prefix}#{mutated_def}#{"\nend" * keywords.size}"
 
-      # A snippet that fails to reparse must NOT silently fall through to running
-      # the ORIGINAL method (C2 false-survived). Raise -> the fork block aborts
-      # before any test runs -> Result.error, never a bogus `survived`.
+      # #20: a singleton method whose def has NO `self.` receiver (the
+      # `class << self` and `module_function` forms) would, as a bare `def foo`
+      # inside `module Owner`, redefine the INSTANCE method — but the call
+      # (`Owner.foo`) dispatches to the singleton, so the mutant never runs and
+      # falsely survives. Re-open the singleton class so the redefinition lands on
+      # the same method the test calls. `def self.foo` already carries its
+      # receiver, so it is left as-is (wrapping it would mis-target).
+      inner =
+        if subject.singleton && subject.def_node.receiver.nil?
+          "class << self\n#{mutated_def}\nend"
+        else
+          mutated_def
+        end
+      wrapped = "#{prefix}#{inner}#{"\nend" * keywords.size}"
+
+      # A snippet that fails to reparse must NOT silently fall through to
+      # running the ORIGINAL method (C2 false-survived). Raise -> the fork
+      # block aborts before any test runs -> Result.error, never a bogus
+      # `survived`.
       raise "surgical snippet failed to reparse" if Parser.parse_string(wrapped).errors.any?
 
-      # Preserve original visibility — class/module bodies define methods public,
-      # but 7a's `load` would re-apply the file's private/protected (C2).
+      # Preserve original visibility — class/module bodies define methods
+      # public, but 7a's `load` would re-apply the file's private/protected
+      # (C2).
       owner  = subject.namespace.empty? ? Object : Object.const_get(subject.namespace.join("::"))
       target = subject.singleton ? owner.singleton_class : owner
       vis    = method_visibility(target, subject.name)
 
-      # Write the wrapped snippet to a tempfile and `load` it: `load` runs it at
-      # top level, so the textual class/module wrappers rebuild Module.nesting
-      # identically, with no dynamic string execution for scanners to flag. The
-      # input is the project's OWN source (the enclosing method, textually
-      # mutated), loaded only in this forked child.
+      # Write the wrapped snippet to a tempfile and `load` it: `load` runs it
+      # at top level, so the textual class/module wrappers rebuild
+      # Module.nesting identically, with no dynamic string execution for
+      # scanners to flag. The input is the project's OWN source (the enclosing
+      # method, textually mutated), loaded only in this forked child.
       Tempfile.create(["mutineer_surgical", ".rb"]) do |f|
         f.write(wrapped)
         f.flush
@@ -132,11 +166,15 @@ module Mutineer
     # keyword (reopening a class with `module` — or vice versa — raises
     # TypeError), so the textual wrapper matches the real definitions.
     #
-    # #5: a compact element like "Foo::Bar" stays a SINGLE wrapper `class Foo::Bar`
-    # (nesting [Foo::Bar]), matching how a whole-file load (reload) sees it.
-    # Splitting it into `module Foo; class Bar` gave nesting [Foo::Bar, Foo], so an
-    # unqualified constant defined only in Foo would resolve under redefine but not
-    # reload — a strategy disagreement.
+    # #5: a compact element like "Foo::Bar" stays a SINGLE wrapper `class Foo::
+    # Bar` (nesting [Foo::Bar]), matching how a whole-file load (reload) sees
+    # it. Splitting it into `module Foo; class Bar` gave nesting [Foo::Bar,
+    # Foo], so an unqualified constant defined only in Foo would resolve under
+    # redefine but not reload — a strategy disagreement.
+    #
+    # @api private
+    # @param namespace [Array<String>] namespace components.
+    # @return [Array<[String, String]>] wrapper keywords and names.
     def self.nesting_keywords(namespace)
       mod = Object
       namespace.map do |name|
@@ -145,6 +183,12 @@ module Mutineer
       end
     end
 
+    # Returns the visibility for a method name.
+    #
+    # @api private
+    # @param mod [Module] module or class being inspected.
+    # @param name [Symbol] method name.
+    # @return [Symbol, nil] `:public`, `:protected`, `:private`, or nil.
     def self.method_visibility(mod, name)
       return :private   if mod.private_method_defined?(name)
       return :protected if mod.protected_method_defined?(name)
@@ -153,6 +197,11 @@ module Mutineer
       nil
     end
 
+    # Decodes a child status into a Result.
+    #
+    # @api private
+    # @param status [Process::Status] child exit status.
+    # @return [Mutineer::Result] decoded result.
     def self.decode(status)
       case status.exitstatus
       when 0 then Result.survived

data/lib/mutineer/minitest_integration.rb

@@ -11,18 +11,19 @@ module Mutineer
   # (autorun, runnables) that only makes sense in a throwaway forked child.
   #
   # No `rescue` here: Isolation.run's fork block is the single exception
-  # boundary (any exception there becomes exit 2). Adding a rescue would create
-  # a second exit-2 path and break this method's 0/1 return contract.
+  # boundary (any exception there becomes exit 2). Adding a rescue would
+  # create a second exit-2 path and break this method's 0/1 return contract.
   class MinitestIntegration
     # ponytail: tested via runner_test.rb (U6), not in isolation — a direct
     # unit test would require forking and duplicate isolation_test's coverage.
     #
-    # `test_files` is one path or an Array of paths (M3 coverage selection passes
-    # the covering subset); each is loaded before the single Minitest.run.
+    # `test_files` is one path or an Array of paths (M3 coverage selection
+    # passes the covering subset); each is loaded before the single
+    # Minitest.run.
+    #
+    # @param test_files [String, Array<String>] one file or many files.
+    # @return [Integer] 0 on success, 1 on failure.
     def self.run(test_files)
-      # minitest is required LAZILY (never at load time) so Mutineer keeps zero
-      # runtime gem deps and loads fine in an rspec-only project; a missing
-      # minitest raises a clear Mutineer error rather than a LoadError backtrace.
       begin
         require "minitest"
       rescue LoadError
@@ -31,6 +32,10 @@ module Mutineer
               "or use --framework rspec"
       end
 
+      # minitest is required LAZILY (never at load time) so Mutineer keeps
+      # zero runtime gem deps and loads fine in an rspec-only project; a missing
+      # minitest raises a clear Mutineer error rather than a LoadError backtrace.
+
       # Neutralise autorun so a test file's `require "minitest/autorun"`
       # registers no at_exit hook.
       def Minitest.autorun; end # rubocop:disable Lint/NestedMethodDefinition
@@ -38,11 +43,10 @@ module Mutineer
       # Drop runnables inherited from the parent suite (this is the child's
       # private copy — the parent is unaffected) so only the target test runs.
       Minitest::Runnable.reset
-
       Array(test_files).each { |f| load f }
 
-      # Silence the child's test output; the parent only cares about pass/fail.
       orig = $stdout
+      # Silence the child's test output; the parent only cares about pass/fail.
       $stdout = StringIO.new
       passed = Minitest.run([])
       $stdout = orig

data/lib/mutineer/mutant_id.rb

@@ -16,8 +16,18 @@ module Mutineer
   module MutantId
     module_function
 
+    # Computes the stable id for a single mutant.
+    #
     # NUL-joined so token delimiters (`||=`, spaces, `::`, `#`) can never collide
     # with the separator; SHA256[0,12] gives a fixed-length, copy-pasteable key.
+    #
+    # @param subject [Mutineer::Subject] the subject (method) the mutant lives in;
+    #   its `qualified_name` anchors the id to a method rather than a byte position.
+    # @param mutation [Mutineer::Mutation] the atomic edit whose operator is hashed.
+    # @param source [String] the full, unmutated source the mutation indexes into.
+    # @param occurrence [Integer] 0-based ordinal among twins sharing the same
+    #   (operator, token) within the subject, disambiguating otherwise-identical mutants.
+    # @return [String] a 12-character hex id, stable across edits outside the subject.
     def for(subject, mutation, source, occurrence = 0)
       Digest::SHA256.hexdigest(
         [subject.qualified_name, mutation.operator,
@@ -25,9 +35,14 @@ module Mutineer
       )[0, 12]
     end
 
-    # Ids for a subject's full mutation list, in input order, assigning each its
-    # 0-based occurrence among twins sharing the same (operator, token). This is
-    # what disambiguates `a + b + c`'s two `+` mutants without an offset.
+    # Computes ids for a subject's full mutation list, in input order, assigning
+    # each its 0-based occurrence among twins sharing the same (operator, token).
+    # This is what disambiguates `a + b + c`'s two `+` mutants without an offset.
+    #
+    # @param subject [Mutineer::Subject] the subject the mutations belong to.
+    # @param source [String] the full, unmutated source for token normalization.
+    # @param mutations [Array<Mutineer::Mutation>] the subject's mutations, in order.
+    # @return [Array<String>] one 12-character id per mutation, positionally aligned.
     def for_subject(subject, source, mutations)
       seen = Hash.new(0)
       mutations.map do |m|
@@ -38,8 +53,12 @@ module Mutineer
       end
     end
 
-    # The exact code being mutated, whitespace-collapsed — same normalization the
-    # Reporter's diff_for uses for its token label.
+    # Extracts the exact code being mutated, whitespace-collapsed — the same
+    # normalization the Reporter's `diff_for` uses for its token label.
+    #
+    # @param mutation [Mutineer::Mutation] supplies the byte range to slice.
+    # @param source [String] the source to byteslice (byte offsets, never char).
+    # @return [String] the mutated token with runs of whitespace collapsed to one space.
     def normalized_token(mutation, source)
       source.byteslice(mutation.start_offset...mutation.end_offset).gsub(/\s+/, " ").strip
     end

data/lib/mutineer/mutation.rb

@@ -3,17 +3,23 @@
 require_relative "parser"
 
 module Mutineer
-  # One atomic byte-range edit. Immutable. One mutation per mutant — never
-  # combine. Source is mutated textually, never regenerated from the AST.
+  # One atomic byte-range edit.
+  #
+  # Immutable. One mutation per mutant — never combine. Source is mutated
+  # textually, never regenerated from the AST.
   Mutation = Data.define(:start_offset, :end_offset, :replacement, :operator) do
-    # Pure: returns a new string, does not mutate `source`. Prism offsets are
-    # BYTE offsets, so all slicing is byte-based (byteslice) — char slicing would
-    # corrupt any source containing a multibyte char before the mutation point.
+    # Applies the mutation to source text.
+    #
+    # @param source [String] original source text.
+    # @return [String] mutated source text.
     def apply(source)
       source.byteslice(0, start_offset) + replacement + source.byteslice(end_offset..)
     end
 
-    # Validity rule: a mutation is valid iff the mutated source re-parses clean.
+    # Checks whether the mutated source still parses cleanly.
+    #
+    # @param source [String] original source text.
+    # @return [Boolean] true when the mutated source re-parses without errors.
     def valid?(source)
       Parser.parse_string(apply(source)).errors.empty?
     end

data/lib/mutineer/mutator_registry.rb

@@ -8,15 +8,21 @@ require_relative "mutators/statement_removal"
 require_relative "mutators/return_nil"
 require_relative "mutators/literal_mutation"
 require_relative "mutators/condition_negation"
+require_relative "mutators/string_literal"
+require_relative "mutators/regex_literal"
+require_relative "mutators/collection_method"
 
 module Mutineer
-  # Maps operator name -> operator class. DEFAULT_NAMES is the v1 default set
+  # Maps operator names to operator classes.
+  #
+  # DEFAULT_NAMES is the v1 default set
   # (the M4 Tier-1 + statement-removal operators per locked decision #2). The
   # three Tier-2 operators live in ALL but are OFF by default — they only run
   # when named via --operators or `operators:` in .mutineer.yml (KTD8). Keeping
   # DEFAULT_NAMES an explicit subset (not ALL.keys) is what keeps the M4 default
   # survivor set unchanged.
   class MutatorRegistry
+    # All available mutator classes keyed by operator name.
     ALL = {
       "arithmetic"         => Mutators::Arithmetic,
       "comparison"         => Mutators::Comparison,
@@ -25,12 +31,18 @@ module Mutineer
       "statement_removal"  => Mutators::StatementRemoval,
       "return_nil"         => Mutators::ReturnNil,
       "literal_mutation"   => Mutators::LiteralMutation,
-      "condition_negation" => Mutators::ConditionNegation
+      "condition_negation" => Mutators::ConditionNegation,
+      "string_literal"     => Mutators::StringLiteral,
+      "regex"              => Mutators::RegexLiteral,
+      "collection_method"  => Mutators::CollectionMethod
     }.freeze
 
+    # The default Tier-1 operator set.
     DEFAULT_NAMES = %w[arithmetic comparison boolean_connector boolean_literal statement_removal].freeze
-    TIER2_NAMES   = %w[return_nil literal_mutation condition_negation].freeze
+    # Tier-2 operators that remain opt-in.
+    TIER2_NAMES   = %w[return_nil literal_mutation condition_negation string_literal regex collection_method].freeze
 
+    # Short human-readable descriptions for each operator.
     DESCRIPTIONS = {
       "arithmetic"         => "+ <-> -, * <-> /, % -> *, ** -> *",
       "comparison"         => "< <-> <=, > <-> >=, == <-> !=",
@@ -39,16 +51,31 @@ module Mutineer
       "statement_removal"  => "replace a non-final statement with nil",
       "return_nil"         => "replace a return / final expression with nil",
       "literal_mutation"   => "integer -> 0, 1, n+1; string -> empty",
-      "condition_negation" => "wrap if/unless/ternary condition in !( ... )"
+      "condition_negation" => "wrap if/unless/ternary condition in !( ... )",
+      "string_literal"     => "non-empty string -> \"\", empty string -> \"mutineer\"",
+      "regex"              => "drop leading ^ / trailing $, swap + <-> *",
+      "collection_method"  => "map<->each, all?<->any?, first<->last, min<->max, select<->reject"
     }.freeze
 
-    # Returns the operator classes for the given names. Unknown names raise
-    # ArgumentError immediately (caught at the CLI boundary -> exit 2).
+    # Resolves operator names to classes.
+    #
+    # @param names [Array<String>] operator names to resolve.
+    # @return [Array<Class>] mutator classes in the requested order.
+    # @raise [ArgumentError] when a name is unknown.
     def self.resolve(names = DEFAULT_NAMES)
       names.map { |n| ALL.fetch(n) { raise ArgumentError, "Unknown operator: #{n.inspect}" } }
     end
 
+    # Returns whether the operator is part of the default Tier-1 set.
+    #
+    # @param name [String] operator name.
+    # @return [Boolean] true when the operator is default.
     def self.default?(name) = DEFAULT_NAMES.include?(name)
+
+    # Returns the tier number for an operator name.
+    #
+    # @param name [String] operator name.
+    # @return [Integer] 2 for Tier-2 operators, otherwise 1.
     def self.tier(name)     = TIER2_NAMES.include?(name) ? 2 : 1
   end
 end

data/lib/mutineer/mutators/arithmetic.rb

@@ -4,13 +4,19 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Arithmetic operator: +<->-, *<->/, %->*, **->*. One mutation per
-    # occurrence, rewriting the operator token (CallNode#message_loc).
+    # Arithmetic operator mutator.
+    #
+    # One mutation per occurrence, rewriting the operator token.
     class Arithmetic < Base
+      # Token replacements for arithmetic operators.
       REPLACEMENTS = {
         :+ => "-", :- => "+", :* => "/", :/ => "*", :% => "*", :** => "*"
       }.freeze
 
+      # Visits call nodes and emits arithmetic mutations.
+      #
+      # @param node [Prism::CallNode] call node to inspect.
+      # @return [void]
       def visit_call_node(node)
         replacement = REPLACEMENTS[node.name]
         loc = node.message_loc

data/lib/mutineer/mutators/base.rb

@@ -4,14 +4,22 @@ require "prism"
 require_relative "../mutation"
 
 module Mutineer
+  # Namespace for all built-in mutator implementations.
   module Mutators
-    # Base Prism visitor for operators. Subclasses override visit_* methods to
-    # push Mutation objects onto @mutations. Visiting only def_node.body is the
-    # body-only enforcement — the def signature line is never touched.
+    # Base Prism visitor for operators.
+    #
+    # Subclasses override `visit_*` methods to push `Mutation` objects onto
+    # `@mutations`. Visiting only `def_node.body` is the body-only enforcement:
+    # the def signature line is never touched.
     #
     # ponytail: one implementor in M1; Base earns its keep at M4 when
     # comparison/boolean operators land and share this contract.
     class Base < Prism::Visitor
+      # Walks the subject body and collects mutations.
+      #
+      # @param subject [Mutineer::Subject] subject whose body is visited.
+      # @param source [String] full source text for byte-based slicing.
+      # @return [Array<Mutineer::Mutation>] collected mutations.
       def mutations_for(subject, source)
         @source = source
         @mutations = []