mutineer 0.6.2 → 0.8.0

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,

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # 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.
+    #
+    # @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|
+        abs = File.expand_path(arg, root)
+        if File.directory?(abs)
+          Dir.glob(File.join(abs, "**", "*.rb")).sort.map { |f| f.delete_prefix("#{root}/") }
+        else
+          [arg]
+        end
+      end.uniq
+    end
+
+    # 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.
+    #
+    # @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|
+        File.exist?(File.expand_path(rel, project_root))
+      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.
+    #
+    # @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/")
+        [no_ext.sub(%r{\Aapp/}, ""), false]
+      elsif no_ext.start_with?("lib/")
+        [no_ext.sub(%r{\Alib/}, ""), true]
+      else
+        [no_ext, false]
+      end
+    end
+
+    # 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
+      rspec = ["spec/#{base}_spec.rb"]
+      rspec << "spec/lib/#{base}_spec.rb" if lib
+      prefer == "rspec" ? rspec + minitest : minitest + rspec
+    end
+  end
+end

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