mutineer 0.7.0 → 0.9.0

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/collection_method.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Collection / enumerable method-name mutator (Tier-2).
+    #
+    # Swaps the method-name token of a call to its semantic opposite, one
+    # mutation per occurrence, exactly like the arithmetic/comparison operators.
+    class CollectionMethod < Base
+      # Method-name swaps. All targets are core-Ruby Enumerable/Array methods so
+      # the mutant exercises real behaviour rather than always raising.
+      #
+      # ponytail: include? -> exclude? was specced but skipped — exclude? is not
+      # core Ruby, so that mutant would always NoMethodError (a weak mutant).
+      REPLACEMENTS = {
+        map: "each", each: "map",
+        all?: "any?", any?: "all?",
+        first: "last", last: "first",
+        min: "max", max: "min",
+        select: "reject", reject: "select"
+      }.freeze
+
+      # Visits call nodes and emits collection-method mutations.
+      #
+      # @param node [Prism::CallNode] call node to inspect.
+      # @return [void]
+      def visit_call_node(node)
+        replacement = REPLACEMENTS[node.name]
+        loc = node.message_loc
+        if replacement && loc
+          @mutations << Mutation.new(
+            start_offset: loc.start_offset,
+            end_offset: loc.end_offset,
+            replacement: replacement,
+            operator: :collection_method
+          )
+        end
+        super
+      end
+    end
+  end
+end

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,

data/lib/mutineer/mutators/regex_literal.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # Regular-expression literal mutator (Tier-2).
+    #
+    # Conservative, clearly-safe textual swaps inside a plain regex literal:
+    # drop a leading +^+ anchor, drop a trailing +$+ anchor, and swap the +
+    # and * quantifiers. Interpolated regexes use a different node type and are
+    # never visited. Escaped tokens (preceded by a backslash) are left alone.
+    class RegexLiteral < Base
+      # Visits regular-expression literals.
+      #
+      # @param node [Prism::RegularExpressionNode] node to inspect.
+      # @return [void]
+      def visit_regular_expression_node(node)
+        loc = node.content_loc
+        content = @source.byteslice(loc.start_offset...loc.end_offset)
+        scan(content, loc.start_offset)
+        super
+      end
+
+      private
+
+      # Scans the pattern bytes and emits anchor/quantifier mutations.
+      #
+      # @param content [String] regex pattern between the slashes.
+      # @param base [Integer] byte offset of the pattern start in source.
+      # @return [void]
+      def scan(content, base)
+        emit(base, base + 1, "") if content.start_with?("^")
+        emit(base + content.bytesize - 1, base + content.bytesize, "") if trailing_anchor?(content)
+
+        escaped = false
+        offset = base
+        content.each_char do |ch|
+          unless escaped
+            emit(offset, offset + 1, "*") if ch == "+"
+            emit(offset, offset + 1, "+") if ch == "*"
+          end
+          escaped = ch == "\\" && !escaped
+          offset += ch.bytesize
+        end
+      end
+
+      # Whether the pattern ends with an unescaped +$+ anchor.
+      #
+      # @param content [String] regex pattern.
+      # @return [Boolean] true when a trailing anchor is droppable.
+      def trailing_anchor?(content)
+        content.end_with?("$") && !content.end_with?("\\$")
+      end
+
+      # Emits a regex mutation.
+      #
+      # @param start_offset [Integer] byte start.
+      # @param end_offset [Integer] byte end.
+      # @param replacement [String] replacement text.
+      # @return [void]
+      def emit(start_offset, end_offset, replacement)
+        @mutations << Mutation.new(
+          start_offset: start_offset,
+          end_offset: end_offset,
+          replacement: replacement,
+          operator: :regex
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/return_nil.rb

@@ -4,15 +4,15 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Return-value-nil operator (Tier 2, OFF by default). Two rules:
-    #   1. an explicit `return <expr>` -> `return nil`, unless the value is
-    #      already nil (no-op guard).
-    #   2. a method body whose final expression is neither a ReturnNode nor a
-    #      NilNode -> that expression becomes `nil`.
-    # Nested defs are their own subjects, so we never descend into them (R10).
+    # Return-nil mutator.
     #
-    # Clean-room: from the spec's operator description, not the mutant gem.
+    # Replaces explicit return values and final expressions with nil.
     class ReturnNil < Base
+      # Collects return-nil mutations for a subject.
+      #
+      # @param subject [Mutineer::Subject] subject to inspect.
+      # @param source [String] full source text.
+      # @return [Array<Mutineer::Mutation>] collected mutations.
       def mutations_for(subject, source)
         @source = source
         @mutations = []
@@ -24,6 +24,10 @@ module Mutineer
         @mutations
       end
 
+      # Visits return nodes.
+      #
+      # @param node [Prism::ReturnNode] node to inspect.
+      # @return [void]
       def visit_return_node(node)
         args = node.arguments
         if args
@@ -37,10 +41,17 @@ module Mutineer
 
       # Nested method definitions are discovered as their own subjects; do not
       # recurse into them (prevents double-counting their statements).
+      #
+      # @param node [Prism::DefNode] nested definition node.
+      # @return [void]
       def visit_def_node(node); end
 
       private
 
+      # Mutates a method's final expression to nil when eligible.
+      #
+      # @param body [Prism::Node] method body node.
+      # @return [void]
       def final_expression_nil(body)
         return unless body.is_a?(Prism::StatementsNode)
 
@@ -50,6 +61,10 @@ module Mutineer
         emit(last.location)
       end
 
+      # Emits a return-nil mutation.
+      #
+      # @param loc [Prism::Location] source location.
+      # @return [void]
       def emit(loc)
         @mutations << Mutation.new(
           start_offset: loc.start_offset,

data/lib/mutineer/mutators/statement_removal.rb

@@ -4,14 +4,14 @@ require_relative "base"
 
 module Mutineer
   module Mutators
-    # Statement-removal operator: replace each non-final method statement with
-    # "nil". Tests whether the suite detects a missing side effect. The final
-    # expression is always skipped — replacing the return value with nil is the
-    # M5 return-nil operator's distinct concern (KTD-1). A body with < 2
-    # statements has no non-final statement, so it generates nothing.
+    # Statement-removal mutator.
     #
-    # Clean-room: from the spec's operator description, not the mutant gem.
+    # Replaces each non-final method statement with `nil`.
     class StatementRemoval < Base
+      # Visits statement nodes and emits removals.
+      #
+      # @param node [Prism::StatementsNode] statement list to inspect.
+      # @return [void]
       def visit_statements_node(node)
         stmts = node.body
         return if stmts.length < 2
@@ -25,9 +25,6 @@ module Mutineer
             operator: :statement_removal
           )
         end
-        # ponytail: no super — recursing into a nested StatementsNode would
-        # re-emit removals already covered at the top level and double-count.
-        # Each subject's body is visited once.
       end
     end
   end

data/lib/mutineer/mutators/string_literal.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Mutineer
+  module Mutators
+    # String literal mutator (Tier-2).
+    #
+    # Empties a non-empty string literal and fills an empty one. Only plain
+    # quoted strings are touched; interpolated strings, heredocs and %-literals
+    # are skipped for safety (they re-parse unpredictably).
+    class StringLiteral < Base
+      # Visits string literals.
+      #
+      # @param node [Prism::StringNode] node to inspect.
+      # @return [void]
+      def visit_string_node(node)
+        # ponytail: only plain "..." / '...' quotes. opening is nil for
+        # interpolation parts and %w[] elements; heredocs/%-literals use a
+        # different opening token. Skipping them keeps mutants re-parseable.
+        if %w[" '].include?(node.opening)
+          loc = node.content_loc
+          @mutations << Mutation.new(
+            start_offset: loc.start_offset,
+            end_offset: loc.end_offset,
+            replacement: node.unescaped.empty? ? "mutineer" : "",
+            operator: :string_literal
+          )
+        end
+        super
+      end
+    end
+  end
+end

data/lib/mutineer/pairing.rb

@@ -4,18 +4,24 @@ module Mutineer
   # Source -> test pairing by path convention (#11). Pure stdlib path logic:
   # no Rails, no class loading, no process. Two jobs:
   #   * expand_sources — a directory argument becomes its sorted **/*.rb files.
-  #   * infer_test     — a source's test file by convention (app/ and lib/ sources
-  #                      map to test/.../_test.rb or spec/.../_spec.rb), preserving
-  #                      namespaced subdirectories. First EXISTING candidate wins.
+  #   * infer_test     — a source's test file by convention (app/ and lib/
+  #                     sources map to test/.../_test.rb or spec/.../_spec.rb),
+  #                     preserving namespaced subdirectories. First EXISTING
+  #                     candidate wins.
   #
-  # Independently unit-testable: every method is pure in/out over the filesystem,
-  # so the pairing contract is exercised with plain fixtures, no Rails, no fork.
+  # Independently unit-testable: every method is pure in/out over the
+  # filesystem, so the pairing contract is exercised with plain fixtures, no
+  # Rails, no fork.
   module Pairing
     module_function
 
     # Expand each positional source: a directory -> its sorted **/*.rb files
-    # (relative to project_root); a file (or glob, or anything non-directory) ->
-    # itself. Flattened, deduped, order-stable.
+    # (relative to project_root); a file (or glob, or anything non-directory)
+    # -> itself. Flattened, deduped, order-stable.
+    #
+    # @param args [Array<String>] source paths or directories.
+    # @param project_root [String] repository root for relative expansion.
+    # @return [Array<String>] flattened, deduped source file list.
     def expand_sources(args, project_root:)
       root = File.expand_path(project_root)
       Array(args).flat_map do |arg|
@@ -30,8 +36,13 @@ module Mutineer
 
     # The first EXISTING candidate test path for a source (relative to
     # project_root), or nil. `prefer` is the resolved framework ("minitest" |
-    # "rspec"): its candidates are tried first, the other framework's as fallback,
-    # so a minitest default still finds a spec and vice-versa.
+    # "rspec"): its candidates are tried first, the other framework's as
+    # fallback, so a minitest default still finds a spec and vice-versa.
+    #
+    # @param source_rel [String] relative source path.
+    # @param project_root [String] repository root for existence checks.
+    # @param prefer [String] preferred framework name.
+    # @return [String, nil] existing test path or nil.
     def infer_test(source_rel, project_root:, prefer: "minitest")
       base, lib = logical_path(source_rel)
       candidates(base, lib, prefer).find do |rel|
@@ -39,10 +50,13 @@ module Mutineer
       end
     end
 
-    # Strip the source root to a logical path (no ".rb") and flag lib/ sources.
-    # app/foo/bar.rb and lib/foo/bar.rb both -> "foo/bar"; anything else -> the
-    # path minus ".rb" (still attempted). Namespaced subdirs are preserved
-    # verbatim — structural, never constant resolution.
+    # Strip the source root to a logical path (no ".rb") and flag lib/
+    # sources. app/foo/bar.rb and lib/foo/bar.rb both -> "foo/bar"; anything
+    # else -> the path minus ".rb" (still attempted). Namespaced subdirs are
+    # preserved verbatim — structural, never constant resolution.
+    #
+    # @param source_rel [String] relative source path.
+    # @return [Array(String, Boolean)] logical base path and whether it came from lib/.
     def logical_path(source_rel)
       no_ext = source_rel.sub(/\.rb\z/, "")
       if no_ext.start_with?("app/")
@@ -56,6 +70,11 @@ module Mutineer
 
     # Ordered candidate test paths. lib/ sources also get test/lib/... and
     # spec/lib/... (Rails apps put lib tests under either layout).
+    #
+    # @param base [String] logical source path without extension.
+    # @param lib [Boolean] whether the source originated from lib/.
+    # @param prefer [String] preferred framework name.
+    # @return [Array<String>] candidate test paths in preferred order.
     def candidates(base, lib, prefer)
       minitest = ["test/#{base}_test.rb"]
       minitest << "test/lib/#{base}_test.rb" if lib

data/lib/mutineer/parser.rb

@@ -3,22 +3,32 @@
 require "prism"
 
 module Mutineer
-  # Raised only for I/O failures while reading a source file. Prism syntax
-  # errors are NOT raised — they are in-band via ParseResult#errors.
+  # Raised only for I/O failures while reading a source file.
+  #
+  # Prism syntax errors are NOT raised — they are in-band via ParseResult#errors.
   class ParseError < StandardError; end
 
-  # Thin boundary around Prism. Both methods return a Prism::ParseResult so all
-  # callers use result.value (AST root), result.source.source (raw bytes), and
-  # result.errors uniformly. No wrapping struct.
+  # Thin boundary around Prism.
+  #
+  # Both methods return a Prism::ParseResult so all callers use result.value,
+  # result.source.source (raw bytes), and result.errors uniformly. No wrapping
+  # struct.
   class Parser
-    # Returns Prism::ParseResult. Re-raises I/O failures as Mutineer::ParseError.
+    # Parses a file with Prism.
+    #
+    # @param path [String] source file path.
+    # @return [Prism::ParseResult] Prism parse result.
+    # @raise [Mutineer::ParseError] when file I/O fails.
     def self.parse_file(path)
       Prism.parse_file(path)
     rescue SystemCallError => e
       raise ParseError, e.message
     end
 
-    # Returns Prism::ParseResult. Never raises; callers check .errors.empty?.
+    # Parses source text with Prism.
+    #
+    # @param source [String] source text.
+    # @return [Prism::ParseResult] Prism parse result.
     def self.parse_string(source)
       Prism.parse(source)
     end