mutineer 0.7.0 → 0.8.0

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

@@ -10,13 +10,16 @@ require_relative "mutators/literal_mutation"
 require_relative "mutators/condition_negation"
 
 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,
@@ -28,9 +31,12 @@ module Mutineer
       "condition_negation" => Mutators::ConditionNegation
     }.freeze
 
+    # The default Tier-1 operator set.
     DEFAULT_NAMES = %w[arithmetic comparison boolean_connector boolean_literal statement_removal].freeze
+    # Tier-2 operators that remain opt-in.
     TIER2_NAMES   = %w[return_nil literal_mutation condition_negation].freeze
 
+    # Short human-readable descriptions for each operator.
     DESCRIPTIONS = {
       "arithmetic"         => "+ <-> -, * <-> /, % -> *, ** -> *",
       "comparison"         => "< <-> <=, > <-> >=, == <-> !=",
@@ -42,13 +48,25 @@ module Mutineer
       "condition_negation" => "wrap if/unless/ternary condition in !( ... )"
     }.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 = []

data/lib/mutineer/mutators/boolean_connector.rb

@@ -4,20 +4,26 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Boolean connector operator: && <-> ||, and <-> or. Replacement is derived
-    # from the actual source token (operator_loc.slice) so symbolic and keyword
-    # forms each map to their own form — never crossing && to `or`, which would
-    # change precedence and surprise the reader (KTD-2).
+    # Boolean connector mutator.
     #
-    # Clean-room: from the spec's operator table, not the mutant gem.
+    # Replaces symbolic and keyword connectors with their opposite form.
     class BooleanConnector < Base
+      # Token replacements for boolean connectors.
       REPLACEMENTS = { "&&" => "||", "||" => "&&", "and" => "or", "or" => "and" }.freeze
 
+      # Visits `and` nodes.
+      #
+      # @param node [Prism::AndNode] node to inspect.
+      # @return [void]
       def visit_and_node(node)
         emit(node)
         super
       end
 
+      # Visits `or` nodes.
+      #
+      # @param node [Prism::OrNode] node to inspect.
+      # @return [void]
       def visit_or_node(node)
         emit(node)
         super
@@ -25,6 +31,10 @@ module Mutineer
 
       private
 
+      # Emits a connector mutation when the token is replaceable.
+      #
+      # @param node [Prism::Node] connector node.
+      # @return [void]
       def emit(node)
         loc = node.operator_loc
         replacement = REPLACEMENTS[loc.slice]

data/lib/mutineer/mutators/boolean_literal.rb

@@ -4,24 +4,32 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Mutates true/false AND nil literals — "boolean_literal" is the spec's name
-    # for the family (§4), so nil is in-scope by design even though it is not
-    # strictly a boolean. true<->false, and nil->true (nil->true catches more
-    # return-value gaps than nil->false). Rewrites the whole node location;
-    # these nodes have no sub-token location.
+    # Boolean literal mutator.
     #
-    # Clean-room: from the spec's operator table, not the mutant gem.
+    # Mutates true/false and nil literals in the boolean_literal family.
     class BooleanLiteral < Base
+      # Visits true literals.
+      #
+      # @param node [Prism::TrueNode] node to inspect.
+      # @return [void]
       def visit_true_node(node)
         emit(node, "false")
         super
       end
 
+      # Visits false literals.
+      #
+      # @param node [Prism::FalseNode] node to inspect.
+      # @return [void]
       def visit_false_node(node)
         emit(node, "true")
         super
       end
 
+      # Visits nil literals.
+      #
+      # @param node [Prism::NilNode] node to inspect.
+      # @return [void]
       def visit_nil_node(node)
         emit(node, "true")
         super
@@ -29,6 +37,11 @@ module Mutineer
 
       private
 
+      # Emits a boolean-literal mutation.
+      #
+      # @param node [Prism::Node] literal node.
+      # @param replacement [String] replacement token.
+      # @return [void]
       def emit(node, replacement)
         loc = node.location
         @mutations << Mutation.new(

data/lib/mutineer/mutators/comparison.rb

@@ -4,23 +4,22 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Comparison / boundary operator: <->-<=, >->-=>, ==->!=, etc. The single
-    # highest-value Tier-1 family (spec §4) — exposes off-by-one and boundary
-    # gaps line coverage never catches. Rewrites the operator token
-    # (CallNode#message_loc), one mutation per occurrence.
+    # Comparison and boundary mutator.
     #
-    # Clean-room: implemented from the spec's operator table and public
-    # mutation-testing literature, not the mutant gem.
+    # Rewrites comparison operators one occurrence at a time.
     class Comparison < Base
+      # Token replacements for comparison operators.
       REPLACEMENTS = {
         :< => "<=", :<= => "<", :> => ">=", :>= => ">", :== => "!=", :!= => "=="
       }.freeze
 
+      # Visits call nodes and emits comparison mutations.
+      #
+      # @param node [Prism::CallNode] call node to inspect.
+      # @return [void]
       def visit_call_node(node)
         replacement = REPLACEMENTS[node.name]
         loc = node.message_loc
-        # receiver guard: reject any unary call accidentally named like an
-        # operator; binary comparisons always have a receiver.
         if replacement && loc && node.receiver
           @mutations << Mutation.new(
             start_offset: loc.start_offset,

data/lib/mutineer/mutators/condition_negation.rb

@@ -4,18 +4,23 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Condition-negation operator (Tier 2, OFF by default). Wraps an if/unless/
-    # ternary condition in `!( ... )` textually. Ruby ternaries parse as IfNode in
-    # Prism, so visit_if_node covers them too (R12). The standard validity re-parse
-    # downstream discards any wrap that fails to round-trip (R14).
+    # Condition-negation mutator.
     #
-    # Clean-room: from the spec's operator description, not the mutant gem.
+    # Wraps if/unless predicates in `!( ... )` textually.
     class ConditionNegation < Base
+      # Visits if nodes.
+      #
+      # @param node [Prism::IfNode] node to inspect.
+      # @return [void]
       def visit_if_node(node)
         wrap(node.predicate)
         super
       end
 
+      # Visits unless nodes.
+      #
+      # @param node [Prism::UnlessNode] node to inspect.
+      # @return [void]
       def visit_unless_node(node)
         wrap(node.predicate)
         super
@@ -23,6 +28,10 @@ module Mutineer
 
       private
 
+      # Wraps a predicate in negation.
+      #
+      # @param predicate [Prism::Node, nil] predicate node.
+      # @return [void]
       def wrap(predicate)
         return unless predicate
 

data/lib/mutineer/mutators/literal_mutation.rb

@@ -4,12 +4,14 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Literal-fuzzing operator (Tier 2, OFF by default). Integers emit up to
-    # three mutations (0, 1, n+1) with no-op guards for 0 and 1; strings collapse
-    # to "" unless already empty. One mutation per emitted candidate (R11).
+    # Literal mutation mutator.
     #
-    # Clean-room: from the spec's operator description, not the mutant gem.
+    # Mutates integers and strings with the Tier-2 literal rules.
     class LiteralMutation < Base
+      # Visits integer literals.
+      #
+      # @param node [Prism::IntegerNode] node to inspect.
+      # @return [void]
       def visit_integer_node(node)
         n = node.value
         emit(node.location, "0") unless n.zero?
@@ -18,6 +20,10 @@ module Mutineer
         super
       end
 
+      # Visits string literals.
+      #
+      # @param node [Prism::StringNode] node to inspect.
+      # @return [void]
       def visit_string_node(node)
         loc = node.location
         token = @source.byteslice(loc.start_offset...loc.end_offset)
@@ -27,6 +33,11 @@ module Mutineer
 
       private
 
+      # Emits a literal mutation.
+      #
+      # @param loc [Prism::Location] source location.
+      # @param replacement [String] replacement literal.
+      # @return [void]
       def emit(loc, replacement)
         @mutations << Mutation.new(
           start_offset: loc.start_offset,