mutineer 0.7.0 → 0.8.0

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

@@ -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

data/lib/mutineer/project.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "prism"
+require "set"
 require_relative "parser"
 require_relative "subject"
 
@@ -8,12 +9,17 @@ module Mutineer
   # Subject discovery: parse each path and walk its AST for method definitions,
   # tracking the enclosing class/module namespace.
   class Project
-    # Returns Array<Subject>. `only` filters by qualified name (string equality).
+    # Discovers subjects from source paths.
+    #
+    # @param paths [Array<String>] source file paths.
+    # @param only [String, nil] optional qualified-name filter.
+    # @return [Array<Mutineer::Subject>] discovered subjects.
     def self.discover(paths, only: nil)
       subjects = Array(paths).flat_map do |path|
         result = Parser.parse_file(path)
         visitor = SubjectVisitor.new(path)
         visitor.visit(result.value)
+        visitor.promote_module_functions!
         visitor.subjects
       end
       only ? subjects.select { |s| s.qualified_name == only } : subjects
@@ -24,31 +30,87 @@ module Mutineer
     class SubjectVisitor < Prism::Visitor
       attr_reader :subjects
 
+      # Builds a subject visitor.
+      #
+      # @param file [String] source file path being visited.
       def initialize(file)
         @file = file
         @namespace_stack = []
         @subjects = []
         @singleton_depth = 0
+        @module_function_active = false # bareword `module_function` seen in this module body
+        @module_function_names = []     # names from `module_function :a, :b` / `module_function def`
         super()
       end
 
+      # Promote `module_function :name` / `module_function def name` subjects to
+      # singleton after the full walk — the naming call may appear before or after
+      # the def, so it can't be decided at visit_def_node time (#20).
+      #
+      # @return [void]
+      def promote_module_functions!
+        return if @module_function_names.empty?
+
+        names = @module_function_names.to_set
+        @subjects.each { |s| s.singleton = true if names.include?(s.name) }
+      end
+
+      # Visits class nodes and tracks namespace nesting.
+      #
+      # @param node [Prism::ClassNode] class node.
+      # @return [void]
       def visit_class_node(node)
         @namespace_stack.push(extract_constant_name(node.constant_path))
+        saved = @module_function_active
+        @module_function_active = false # module_function state does not cross a class boundary
         super
+        @module_function_active = saved
         @namespace_stack.pop
       end
 
+      # Visits module nodes and tracks namespace nesting.
+      #
+      # @param node [Prism::ModuleNode] module node.
+      # @return [void]
       def visit_module_node(node)
         @namespace_stack.push(extract_constant_name(node.constant_path))
+        saved = @module_function_active
+        @module_function_active = false # each module body starts without module_function active
         super
+        @module_function_active = saved
         @namespace_stack.pop
       end
 
+      # Track `module_function` so its methods are recorded as singletons (#20) —
+      # the called form is the singleton method on the module object. Bareword
+      # `module_function` flips all SUBSEQUENT defs in this body; the argument
+      # forms (`:sym`, `def`) name methods promoted after the walk.
+      #
+      # @param node [Prism::CallNode] call node.
+      # @return [void]
+      def visit_call_node(node)
+        if node.name == :module_function && node.receiver.nil?
+          args = node.arguments&.arguments || []
+          if args.empty?
+            @module_function_active = true
+          else
+            args.each do |arg|
+              @module_function_names << arg.value.to_sym if arg.is_a?(Prism::SymbolNode)
+              @module_function_names << arg.name if arg.is_a?(Prism::DefNode)
+            end
+          end
+        end
+        super
+      end
+
       # Methods inside `class << self` are class methods of the enclosing
       # namespace, but their def nodes have no receiver — track the singleton
       # context so they're recorded as singleton (so redefine targets the
       # singleton_class, not instances). `class << some_other_obj` can't be
       # represented against the namespace, so its defs are skipped (not recursed).
+      #
+      # @param node [Prism::SingletonClassNode] singleton-class node.
+      # @return [void]
       def visit_singleton_class_node(node)
         return unless node.expression.is_a?(Prism::SelfNode)
 
@@ -57,12 +119,16 @@ module Mutineer
         @singleton_depth -= 1
       end
 
+      # Records a discovered method definition.
+      #
+      # @param node [Prism::DefNode] method definition node.
+      # @return [void]
       def visit_def_node(node)
         @subjects << Subject.new(
           file: @file,
           namespace: @namespace_stack.dup,
           name: node.name,
-          singleton: !node.receiver.nil? || @singleton_depth.positive?,
+          singleton: !node.receiver.nil? || @singleton_depth.positive? || @module_function_active,
           def_node: node
         )
         super
@@ -70,6 +136,11 @@ module Mutineer
 
       private
 
+      # Extracts a constant name from a Prism constant node.
+      #
+      # @api private
+      # @param node [Prism::Node] constant node.
+      # @return [String, nil] constant name.
       def extract_constant_name(node)
         case node
         when Prism::ConstantReadNode

data/lib/mutineer/reporter.rb

@@ -41,6 +41,12 @@ module Mutineer
       end
     end
 
+    # Renders the human report.
+    #
+    # @param out [IO] output stream.
+    # @param err [IO] error stream.
+    # @param threshold [Float] score threshold.
+    # @return [void]
     def human_report(out, err, threshold)
       if @agg.total.zero?
         err.puts "No mutations generated — verify target files contain in-scope " \
@@ -75,6 +81,11 @@ module Mutineer
     # Canonical machine-readable schema (KTD7). survivors/no_coverage are sorted
     # by (file, line, operator) so output is byte-stable regardless of --jobs
     # worker finish order (R22).
+    # Renders the JSON report.
+    #
+    # @api private
+    # @param baseline [Mutineer::Baseline::Delta, nil] baseline delta.
+    # @return [String] JSON text.
     def json_report(baseline = nil)
       killed = @agg.killed_count
       survived = @agg.survived_count
@@ -135,6 +146,12 @@ module Mutineer
       }
     end
 
+    # Builds per-source JSON.
+    #
+    # @api private
+    # @param file [String] source file path.
+    # @param agg [Mutineer::AggregateResult] source aggregate.
+    # @return [Hash] per-source JSON object.
     def per_source_json(file, agg)
       {
         file: file, total: agg.total,
@@ -143,6 +160,11 @@ module Mutineer
       }
     end
 
+    # Builds survivor JSON.
+    #
+    # @api private
+    # @param result [Mutineer::Result] survivor result.
+    # @return [Hash] survivor JSON object.
     def survivor_json(result)
       m = result.mutation
       file = result.subject.file
@@ -198,6 +220,11 @@ module Mutineer
       [start_line, original_block, mutated_block, token]
     end
 
+    # Builds no-coverage JSON.
+    #
+    # @api private
+    # @param result [Mutineer::Result] result object.
+    # @return [Hash] no-coverage JSON object.
     def no_coverage_json(result)
       m = result.mutation
       file = result.subject.file
@@ -209,6 +236,10 @@ module Mutineer
       }
     end
 
+    # Writes the summary block.
+    #
+    # @param out [IO] output stream.
+    # @return [void]
     def summary(out)
       out.puts "Summary"
       out.puts "-------"
@@ -222,6 +253,11 @@ module Mutineer
       out.puts format("Ignored:      %-6d  (equivalent, suppressed)", @agg.ignored_count)
     end
 
+    # Writes the score line.
+    #
+    # @param out [IO] output stream.
+    # @param err [IO] error stream.
+    # @return [void]
     def score_line(out, err)
       score = @agg.mutation_score
       excluded = "#{@agg.no_coverage_count} no-coverage, #{@agg.uncapturable_count} uncapturable, " \
@@ -239,6 +275,10 @@ module Mutineer
     # #11: one line per source after the global summary, so a multi-source run
     # shows which file is weak. Omitted for a single-source run — the global
     # summary already says everything (ponytail: no redundant one-line block).
+    # Writes the per-source breakdown.
+    #
+    # @param out [IO] output stream.
+    # @return [void]
     def per_source(out)
       sources = @agg.by_source
       return if sources.size <= 1
@@ -274,6 +314,10 @@ module Mutineer
       out.puts(delta.regressed ? "REGRESSION vs baseline" : "OK: no regression vs baseline")
     end
 
+    # Writes the survivors block.
+    #
+    # @param out [IO] output stream.
+    # @return [void]
     def survivors(out)
       mutants = @agg.surviving_mutants
       return if mutants.empty?
@@ -288,6 +332,12 @@ module Mutineer
       end
     end
 
+    # Writes one survivor entry.
+    #
+    # @param out [IO] output stream.
+    # @param file [String] source file path.
+    # @param result [Mutineer::Result] survivor result.
+    # @return [void]
     def survivor(out, file, result)
       m = result.mutation
       source = @source_map[file] || File.read(file)
@@ -299,6 +349,11 @@ module Mutineer
       mutated_block.each_line  { |l| out.puts "  + #{l.chomp}" }
     end
 
+    # Writes the final verdict line.
+    #
+    # @param out [IO] output stream.
+    # @param threshold [Float] score threshold.
+    # @return [void]
     def verdict(out, threshold)
       score = @agg.mutation_score
       return if score.nil?