mutineer 0.2.0

data/lib/mutineer/mutators/condition_negation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+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).
+    #
+    # Clean-room: from the spec's operator description, not the mutant gem.
+    class ConditionNegation < Base
+      def visit_if_node(node)
+        wrap(node.predicate)
+        super
+      end
+
+      def visit_unless_node(node)
+        wrap(node.predicate)
+        super
+      end
+
+      private
+
+      def wrap(predicate)
+        return unless predicate
+
+        loc = predicate.location
+        original = @source.byteslice(loc.start_offset...loc.end_offset)
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: "!( #{original} )",
+          operator: :condition_negation
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/literal_mutation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+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).
+    #
+    # Clean-room: from the spec's operator description, not the mutant gem.
+    class LiteralMutation < Base
+      def visit_integer_node(node)
+        n = node.value
+        emit(node.location, "0") unless n.zero?
+        emit(node.location, "1") unless n == 1
+        emit(node.location, (n + 1).to_s)
+        super
+      end
+
+      def visit_string_node(node)
+        loc = node.location
+        token = @source.byteslice(loc.start_offset...loc.end_offset)
+        emit(loc, '""') unless token == '""' || token == "''" || node.unescaped.empty?
+        super
+      end
+
+      private
+
+      def emit(loc, replacement)
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: replacement,
+          operator: :literal_mutation
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/return_nil.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+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).
+    #
+    # Clean-room: from the spec's operator description, not the mutant gem.
+    class ReturnNil < Base
+      def mutations_for(subject, source)
+        @source = source
+        @mutations = []
+        body = subject.def_node.body
+        if body
+          body.accept(self)       # rule 1 (explicit return nodes in this body)
+          final_expression_nil(body) # rule 2 (method's final expression)
+        end
+        @mutations
+      end
+
+      def visit_return_node(node)
+        args = node.arguments
+        if args
+          values = args.arguments
+          unless values.size == 1 && values.first.is_a?(Prism::NilNode)
+            emit(args.location)
+          end
+        end
+        super
+      end
+
+      # Nested method definitions are discovered as their own subjects; do not
+      # recurse into them (prevents double-counting their statements).
+      def visit_def_node(node); end
+
+      private
+
+      def final_expression_nil(body)
+        return unless body.is_a?(Prism::StatementsNode)
+
+        last = body.body.last
+        return if last.nil? || last.is_a?(Prism::ReturnNode) || last.is_a?(Prism::NilNode)
+
+        emit(last.location)
+      end
+
+      def emit(loc)
+        @mutations << Mutation.new(
+          start_offset: loc.start_offset,
+          end_offset: loc.end_offset,
+          replacement: "nil",
+          operator: :return_nil
+        )
+      end
+    end
+  end
+end

data/lib/mutineer/mutators/statement_removal.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # Clean-room: from the spec's operator description, not the mutant gem.
+    class StatementRemoval < Base
+      def visit_statements_node(node)
+        stmts = node.body
+        return if stmts.length < 2
+
+        stmts[0...-1].each do |stmt|
+          loc = stmt.location
+          @mutations << Mutation.new(
+            start_offset: loc.start_offset,
+            end_offset: loc.end_offset,
+            replacement: "nil",
+            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
+end

data/lib/mutineer/parser.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+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.
+  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.
+  class Parser
+    # Returns Prism::ParseResult. Re-raises I/O failures as Mutineer::ParseError.
+    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?.
+    def self.parse_string(source)
+      Prism.parse(source)
+    end
+  end
+end

data/lib/mutineer/project.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "parser"
+require_relative "subject"
+
+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).
+    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.subjects
+      end
+      only ? subjects.select { |s| s.qualified_name == only } : subjects
+    end
+
+    # Walks an AST, maintaining a namespace stack, emitting Subjects.
+    # Nested inside Project to signal its private role.
+    class SubjectVisitor < Prism::Visitor
+      attr_reader :subjects
+
+      def initialize(file)
+        @file = file
+        @namespace_stack = []
+        @subjects = []
+        super()
+      end
+
+      def visit_class_node(node)
+        @namespace_stack.push(extract_constant_name(node.constant_path))
+        super
+        @namespace_stack.pop
+      end
+
+      def visit_module_node(node)
+        @namespace_stack.push(extract_constant_name(node.constant_path))
+        super
+        @namespace_stack.pop
+      end
+
+      def visit_def_node(node)
+        @subjects << Subject.new(
+          file: @file,
+          namespace: @namespace_stack.dup,
+          name: node.name,
+          singleton: !node.receiver.nil?,
+          def_node: node
+        )
+        super
+      end
+
+      private
+
+      def extract_constant_name(node)
+        case node
+        when Prism::ConstantReadNode
+          node.name.to_s
+        when Prism::ConstantPathNode
+          [extract_constant_name(node.parent), node.name.to_s].compact.join("::")
+        end
+      end
+    end
+  end
+end

data/lib/mutineer/reporter.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+require "stringio"
+require_relative "mutation"
+
+module Mutineer
+  # Renders an AggregateResult: the summary block, mutation score, and per-file
+  # survivor diffs. Stream discipline (R14): the report goes to `out` (stdout),
+  # diagnostics/warnings go to `err` (stderr), so `mutineer ... > report.txt`
+  # captures only the report.
+  #
+  # `source_map` is { file_path => raw source string }, used to extract the
+  # containing source line for each survivor diff.
+  class Reporter
+    def initialize(aggregate, source_map)
+      @agg = aggregate
+      @source_map = source_map
+    end
+
+    # Single entry point (R20/R21). Branches on `format` ("human" | "json") and
+    # routes the rendered report to `output` (a file, with a stderr confirmation)
+    # or to `out`. Diagnostics always go to `err`.
+    def report(out: $stdout, err: $stderr, threshold: 0.0, format: "human", output: nil)
+      rendered =
+        if format == "json"
+          json_report
+        else
+          sio = StringIO.new
+          human_report(sio, err, threshold)
+          sio.string
+        end
+
+      if output
+        abs = File.expand_path(output)
+        File.write(abs, rendered)
+        err.puts "Report written to #{abs}"
+      else
+        out.print rendered
+      end
+    end
+
+    def human_report(out, err, threshold)
+      if @agg.total.zero?
+        err.puts "No mutations generated — verify target files contain in-scope " \
+                 "operators and are reached by the suite."
+        return
+      end
+
+      out.puts "Mutineer — Mutation Results"
+      out.puts "========================="
+      out.puts
+      summary(out)
+      out.puts
+      score_line(out, err)
+
+      survivors(out)
+      verdict(out, threshold) if threshold && threshold.positive?
+    end
+
+    # 0 pass / 1 below threshold. Usage errors (exit 2) are the CLI's job.
+    def exit_code(threshold:)
+      return 0 if threshold.nil? || threshold <= 0
+
+      score = @agg.mutation_score
+      return 0 if score.nil? # no testable mutants — gate skipped (warning already emitted)
+
+      score >= threshold ? 0 : 1
+    end
+
+    private
+
+    # 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).
+    def json_report
+      killed = @agg.killed_count
+      survived = @agg.survived_count
+      # C8: null (not 0.0) on an empty denominator, matching the nil-vs-0.0
+      # discipline in AggregateResult; and the SAME rounding as the human report
+      # (one run must not yield two scores by --format).
+      score = @agg.mutation_score
+
+      doc = {
+        schema_version: "1.0",
+        summary: {
+          total: @agg.total, killed: killed, survived: survived,
+          no_coverage: @agg.no_coverage_count,
+          skipped_invalid: @agg.skipped_invalid_count,
+          errored: @agg.errored_count, timeout: @agg.timeout_count,
+          score: score
+        },
+        survivors: @agg.surviving_mutants.map { |r| survivor_json(r) }
+                       .sort_by { |h| [h[:file], h[:line], h[:operator]] },
+        no_coverage: @agg.results.select(&:no_coverage?).map { |r| no_coverage_json(r) }
+                         .sort_by { |h| [h[:file], h[:line]] }
+      }
+      "#{JSON.generate(doc)}\n"
+    end
+
+    def survivor_json(result)
+      m = result.mutation
+      file = result.subject.file
+      source = @source_map[file] || File.read(file)
+      start_line, original_block, mutated_block, = diff_for(m, source)
+      minus = original_block.each_line.map { |l| "-#{l.chomp}" }.join("\n")
+      plus  = mutated_block.each_line.map { |l| "+#{l.chomp}" }.join("\n")
+      {
+        subject: result.subject.qualified_name,
+        file: file,
+        line: start_line,
+        operator: m.operator.to_s,
+        diff: "--- a/#{file}\n+++ b/#{file}\n@@ -#{start_line} +#{start_line} @@\n#{minus}\n#{plus}\n"
+      }
+    end
+
+    # Builds a line-aligned diff for a mutation whose byte range may span several
+    # lines (e.g. statement-removal of a multi-line statement). Returns the
+    # mutation's 1-based start line, the full original line-block it touches, the
+    # spliced mutated block, and a single-line token label for the header.
+    def diff_for(m, source)
+      # Byte math (C1): Prism offsets are byte offsets; byteindex/byterindex/
+      # byteslice keep line splicing correct for multibyte sources.
+      line_begin = m.start_offset.zero? ? 0 : (source.byterindex("\n", m.start_offset - 1) || -1) + 1
+      line_end   = source.byteindex("\n", m.end_offset) || source.bytesize
+      before = source.byteslice(line_begin...m.start_offset)
+      after  = source.byteslice(m.end_offset...line_end)
+      original_block = source.byteslice(line_begin...line_end)
+      mutated_block  = "#{before}#{m.replacement}#{after}"
+      start_line  = source.byteslice(0, m.start_offset).count("\n") + 1
+      token       = source.byteslice(m.start_offset...m.end_offset).gsub(/\s+/, " ").strip
+      token       = "#{token[0, 47]}..." if token.length > 50
+      [start_line, original_block, mutated_block, token]
+    end
+
+    def no_coverage_json(result)
+      m = result.mutation
+      file = result.subject.file
+      source = @source_map[file] || File.read(file)
+      {
+        subject: result.subject.qualified_name,
+        file: file,
+        line: source.byteslice(0, m.start_offset).count("\n") + 1
+      }
+    end
+
+    def summary(out)
+      out.puts "Summary"
+      out.puts "-------"
+      out.puts format("Total:        %-6d  Killed:        %d", @agg.total, @agg.killed_count)
+      out.puts format("Survived:     %-6d  No coverage:   %d", @agg.survived_count, @agg.no_coverage_count)
+      out.puts format("Skipped:      %-6d  Errored:       %d", @agg.skipped_invalid_count,
+                      @agg.errored_count + @agg.timeout_count)
+    end
+
+    def score_line(out, err)
+      score = @agg.mutation_score
+      excluded = "#{@agg.no_coverage_count} no-coverage, #{@agg.skipped_invalid_count} skipped, " \
+                 "#{@agg.errored_count + @agg.timeout_count} errored excluded"
+      if score.nil?
+        out.puts "Mutation score: N/A  (no covered mutants)"
+        err.puts "[mutineer] no covered mutations; mutation score is N/A and the threshold check is skipped."
+      else
+        out.puts "Mutation score: #{score}%  (killed / (killed + survived); #{excluded})"
+      end
+    end
+
+    def survivors(out)
+      mutants = @agg.surviving_mutants
+      return if mutants.empty?
+
+      out.puts
+      out.puts "Surviving Mutants"
+      out.puts "-----------------"
+      mutants.group_by { |r| r.subject.file }.sort.each do |file, group|
+        out.puts
+        out.puts file
+        group.sort_by { |r| r.mutation.start_offset }.each { |r| survivor(out, file, r) }
+      end
+    end
+
+    def survivor(out, file, result)
+      m = result.mutation
+      source = @source_map[file] || File.read(file)
+      start_line, original_block, mutated_block, token = diff_for(m, source)
+
+      out.puts "  #{result.subject.qualified_name} (#{File.basename(file)}:#{start_line})"
+      out.puts "  Operator: #{m.operator}  (#{token} -> #{m.replacement})"
+      original_block.each_line { |l| out.puts "  - #{l.chomp}" }
+      mutated_block.each_line  { |l| out.puts "  + #{l.chomp}" }
+    end
+
+    def verdict(out, threshold)
+      score = @agg.mutation_score
+      return if score.nil?
+
+      if score >= threshold
+        out.puts "PASSED: #{score}% >= threshold #{threshold}%"
+      else
+        out.puts "FAILED: #{score}% < threshold #{threshold}%"
+      end
+    end
+  end
+end

data/lib/mutineer/result.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Mutineer
+  # Immutable outcome of running one mutant. Six distinct states:
+  #   killed      — a test failed/errored, so the mutation was caught.
+  #   survived    — every test passed, so the mutation went undetected.
+  #   error       — the child crashed (unhandled exception): exit status 2.
+  #   timeout     — the parent SIGKILLed a child that overran its wall clock.
+  #   skipped     — the mutated source failed to re-parse (invalid); no fork.
+  #   no_coverage — no test exercises the mutated line; not run, not scored.
+  #
+  # `error` and `skipped` are deliberately distinct: skipped is a pre-fork
+  # validity failure (counted separately by the reporter), error is a runtime
+  # crash. Never conflate them via `details` string parsing. `no_coverage` is a
+  # pre-fork selection result (M3): excluded from the score denominator.
+  #
+  # `subject` and `mutation` are nil when the Result is built by Isolation/Runner
+  # (which only know the outcome); the orchestrator attaches them afterwards via
+  # `result.with(subject:, mutation:)` so the Reporter can render survivor diffs.
+  Result = Data.define(:status, :details, :subject, :mutation) do
+    def self.killed               = new(status: :killed, details: nil, subject: nil, mutation: nil)
+    def self.survived             = new(status: :survived, details: nil, subject: nil, mutation: nil)
+    def self.error(details = nil) = new(status: :error, details: details, subject: nil, mutation: nil)
+    def self.timeout              = new(status: :timeout, details: nil, subject: nil, mutation: nil)
+    def self.skipped(details = nil) = new(status: :skipped, details: details, subject: nil, mutation: nil)
+    def self.no_coverage          = new(status: :no_coverage, details: nil, subject: nil, mutation: nil)
+
+    def killed?      = status == :killed
+    def survived?    = status == :survived
+    def error?       = status == :error
+    def timeout?     = status == :timeout
+    def skipped?     = status == :skipped
+    def no_coverage? = status == :no_coverage
+  end
+
+  # Aggregates a flat list of Results into counts, the mutation score, and the
+  # surviving-mutant list. The score denominator is killed + survived ONLY
+  # (KTD-4): no-coverage, skipped (invalid), errored, and timeout are each
+  # excluded and surfaced separately. An empty denominator yields a nil score
+  # (rendered "N/A"), never 0.0 — distinguishing "no testable mutants" from
+  # "0% killed".
+  class AggregateResult
+    attr_reader :results
+
+    def initialize(results)
+      @results = results
+      @by_status = results.group_by(&:status)
+    end
+
+    def killed_count          = count(:killed)
+    def survived_count        = count(:survived)
+    def no_coverage_count     = count(:no_coverage)
+    def skipped_invalid_count = count(:skipped)
+    def errored_count         = count(:error)
+    def timeout_count         = count(:timeout)
+
+    # Every generated, classified mutation. NOT the score denominator.
+    def total = @results.size
+
+    # The score denominator (also shown to the reader).
+    def covered_count = killed_count + survived_count
+
+    # killed / (killed + survived) as a rounded percentage, or nil when nothing
+    # was testable.
+    def mutation_score
+      return nil if covered_count.zero?
+
+      (killed_count.to_f / covered_count * 100).round(1)
+    end
+
+    def surviving_mutants = @results.select(&:survived?)
+
+    private
+
+    def count(status) = (@by_status[status] || []).size
+  end
+end