mutaterb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e60dd9f48be985c4852b318ee38410f6ce76cb924604c9d37f1f64004e2c27f6
+  data.tar.gz: 6ef1b8387ed290681db0ab7480021fe2536782cf57478834d56f1331b3676ecc
+SHA512:
+  metadata.gz: 1f168ec32386423f8c2beb49856791fed45ce11c80f42d3d7284d1782577b9c55e7f3344b13360ecbcc2b1bbf22932e919d1b79d5af05529fc40d353445581ea
+  data.tar.gz: bf83a88519717178e2863c9ec85ef30acaeddb0dac5433ee0b467c4d2d7aa2f14d38ed657173903f74045a84446cb8e465002d7895d0ca69344cd780f72784ca

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MarceloM47
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,50 @@
+# MutateRB
+
+A mutation testing tool for Ruby and Ruby on Rails projects: it modifies code covered
+by your RSpec tests and checks whether the test suite catches the change. If a mutated
+test does not fail, that test is identified as weak.
+
+## Installation
+
+```bash
+gem install mutaterb
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "mutaterb", group: :development
+```
+
+## Usage
+
+Run the command from your project root (where your `Gemfile` is):
+
+```bash
+mutaterb
+```
+
+Without flags, it automatically detects whether the project is pure Ruby or Rails,
+locates specs in `spec/`, applies mutations to covered code, and displays a summary:
+how many mutations were "killed" (caught by a test) and how many "survived" (no test
+caught them — weak tests), with file, line, and related test(s) for each survivor.
+
+### Main flags
+
+| Flag | Description |
+|---|---|
+| `--dir PATH` | Target folder to analyze |
+| `--include PATHS` | Restrict analysis to these paths (comma-separated) |
+| `--exclude PATHS` | Exclude these paths (comma-separated) |
+| `--strictness LEVEL` | `low`, `default`, or `high` |
+| `--mutation-types TYPES` | Mutation types to apply, comma-separated |
+| `--exit-zero` | Do not fail (exit 0) even if "survived" mutations exist |
+| `--json-output PATH` | Export the results summary to a JSON file |
+| `--config PATH` | Use a config file other than `.mutaterb.yml` |
+
+You can also set these options in a `.mutaterb.yml` file at the project root; CLI
+flags take precedence over the file when both define the same option.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/exe/mutaterb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mutaterb"
+
+exit MutateRB::CLI.run(ARGV)

data/lib/mutaterb/cli.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # Entry point: parses flags, resolves Config, runs the mutation analysis
+  # and returns the process exit code (contracts/cli.md).
+  class CLI
+    EXIT_OPERATIONAL_ERROR = 2
+    EXIT_INTERRUPTED = 130
+
+    def self.run(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      config = resolve_config(argv)
+      execute(config)
+    rescue ConfigError => e
+      warn "mutaterb: #{e.message}"
+      EXIT_OPERATIONAL_ERROR
+    rescue StandardError => e
+      # Constitution Principle V: no error may go uncaught.
+      # Any unforeseen failure (project detection, baseline run, etc.) is
+      # reported in a controlled manner instead of propagating a raw backtrace
+      # (contracts/cli.md: exit 2 = operational error, SC-005).
+      warn "mutaterb: unexpected error: #{e.message}"
+      EXIT_OPERATIONAL_ERROR
+    end
+
+    private
+
+    def resolve_config(argv)
+      flags = FlagParser.parse(argv)
+      base = Config.load_file(flags.fetch(:config_path, Config::DEFAULT_FILE_NAME))
+      base.merge_flags(flags.except(:config_path))
+    end
+
+    def execute(config)
+      interrupted = false
+      Signal.trap("INT") { interrupted = true }
+
+      detection = ProjectDetector.new(config).detect
+      if detection.spec_files.empty?
+        warn "mutaterb: no tests found in #{config.target_dir}"
+        return EXIT_OPERATIONAL_ERROR
+      end
+
+      test_suite = build_test_suite(config, detection)
+      run = MutationRun.new(config: config, test_suite: test_suite)
+      run_mutations(run, test_suite, config) { interrupted }
+
+      run.finished_at = Time.now
+      run.interrupted = interrupted
+      Reporter.new(run).report
+
+      return EXIT_INTERRUPTED if interrupted
+
+      run.exit_code
+    end
+
+    def build_test_suite(config, detection)
+      test_runner = TestRunner.new(config: config, project_type: detection.project_type)
+      baseline_examples = test_runner.run_baseline(detection.spec_files)
+      TestSuite.from_baseline(project_type: detection.project_type, baseline_examples: baseline_examples)
+    end
+
+    def run_mutations(run, test_suite, config)
+      mutator = Mutator.new(config: config, test_suite: test_suite)
+      mutator.each_mutant do |mutant|
+        run.add_mutant(mutant)
+        break if yield
+      end
+    end
+  end
+end

data/lib/mutaterb/config.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MutateRB
+  # Resolved options for a run, merging .mutaterb.yml and CLI flags
+  # (flags win, FR-009). See contracts/config-schema.md for the file format.
+  class Config
+    ALL_MUTATION_TYPES = %i[conditional_boundary boolean_literal nil_literal arithmetic_comparison].freeze
+    VALID_STRICTNESS = %i[low default high].freeze
+    DEFAULT_FILE_NAME = ".mutaterb.yml"
+
+    attr_accessor :target_dir, :include_paths, :exclude_paths, :strictness,
+                  :mutation_types, :exit_on_survivors, :json_output_path
+
+    def initialize(target_dir: ".", include_paths: [], exclude_paths: [],
+                   strictness: :default, mutation_types: ALL_MUTATION_TYPES.dup,
+                   exit_on_survivors: true, json_output_path: nil)
+      @target_dir = target_dir
+      @include_paths = include_paths
+      @exclude_paths = exclude_paths
+      @strictness = strictness
+      @mutation_types = mutation_types
+      @exit_on_survivors = exit_on_survivors
+      @json_output_path = json_output_path
+      validate!
+    end
+
+    def self.default
+      new
+    end
+
+    # Loads .mutaterb.yml (or the path given by --config) if present, validates
+    # it, and returns a Config with the file's values applied on top of the
+    # defaults (FR-007). Returns Config.default if no file is present.
+    def self.load_file(path = DEFAULT_FILE_NAME)
+      return default unless File.exist?(path)
+
+      raw = YAML.safe_load_file(path, permitted_classes: [Symbol], symbolize_names: false)
+      raise ConfigError, "#{path} must contain a YAML mapping" unless raw.is_a?(Hash)
+
+      new(**attributes_from_yaml(raw))
+    rescue Psych::SyntaxError => e
+      raise ConfigError, "#{path} is not valid YAML: #{e.message}"
+    end
+
+    def self.attributes_from_yaml(raw)
+      known_keys = %w[target_dir include_paths exclude_paths strictness mutation_types
+                      exit_on_survivors json_output_path]
+      raw.each_key do |key|
+        warn "mutaterb: ignoring unknown config key #{key.inspect}" unless known_keys.include?(key)
+      end
+
+      {
+        target_dir: raw.fetch("target_dir", "."),
+        include_paths: Array(raw["include_paths"]),
+        exclude_paths: Array(raw["exclude_paths"]),
+        strictness: raw.key?("strictness") ? symbolize(raw["strictness"], "strictness") : :default,
+        mutation_types: if raw.key?("mutation_types")
+                          Array(raw["mutation_types"]).map do |t|
+                            symbolize(t, "mutation_types")
+                          end
+                        else
+                          ALL_MUTATION_TYPES.dup
+                        end,
+        exit_on_survivors: raw.fetch("exit_on_survivors", true),
+        json_output_path: raw["json_output_path"]
+      }
+    end
+    private_class_method :attributes_from_yaml
+
+    def self.symbolize(value, field)
+      raise ConfigError, "#{field} must be a string" unless value.is_a?(String)
+
+      value.to_sym
+    end
+    private_class_method :symbolize
+
+    # Applies CLI flag overrides on top of this config, field by field
+    # (FR-009: a flag always wins over the config file).
+    def merge_flags(flags)
+      merged = dup
+      flags.each do |key, value|
+        next if value.nil?
+
+        merged.public_send("#{key}=", value)
+      end
+      merged.validate!
+      merged
+    end
+
+    def validate!
+      raise ConfigError, "target_dir must be a String" unless target_dir.is_a?(String)
+      raise ConfigError, "target_dir #{target_dir.inspect} does not exist" unless Dir.exist?(target_dir)
+      raise ConfigError, "include_paths must be an Array" unless include_paths.is_a?(Array)
+      raise ConfigError, "exclude_paths must be an Array" unless exclude_paths.is_a?(Array)
+      unless VALID_STRICTNESS.include?(strictness)
+        raise ConfigError, "strictness must be one of #{VALID_STRICTNESS.join(', ')}, got #{strictness.inspect}"
+      end
+      raise ConfigError, "mutation_types must be an Array" unless mutation_types.is_a?(Array)
+
+      unknown = mutation_types - ALL_MUTATION_TYPES
+      raise ConfigError, "unknown mutation_types: #{unknown.join(', ')}" unless unknown.empty?
+      raise ConfigError, "exit_on_survivors must be true or false" unless [true, false].include?(exit_on_survivors)
+
+      return unless json_output_path
+
+      parent = File.dirname(File.expand_path(json_output_path))
+      raise ConfigError, "directory for json_output_path does not exist: #{parent}" unless Dir.exist?(parent)
+    end
+  end
+end

data/lib/mutaterb/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # Raised when the config file or CLI flags fail validation (FR-011).
+  class ConfigError < StandardError; end
+
+  # Raised when a mutation cannot be applied or reverted safely.
+  class MutationError < StandardError; end
+end

data/lib/mutaterb/flag_parser.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module MutateRB
+  # Parses CLI flags into the hash consumed by Config#merge_flags (FR-008,
+  # contracts/cli.md). Only flags actually passed appear in the result, so
+  # CLI flags win over the config file field by field (FR-009).
+  class FlagParser
+    def self.parse(argv)
+      new.parse(argv)
+    end
+
+    def parse(argv)
+      flags = { config_path: Config::DEFAULT_FILE_NAME }
+
+      parser = build_parser(flags)
+      parser.parse!(argv.dup)
+      flags
+    rescue OptionParser::ParseError => e
+      raise ConfigError, e.message
+    end
+
+    private
+
+    def build_parser(flags)
+      OptionParser.new do |opts|
+        opts.banner = "Usage: mutaterb [flags]"
+
+        opts.on("--dir PATH", "Target folder to analyze") { |v| flags[:target_dir] = v }
+        opts.on("--include PATHS", "Subdirectories/files to include, comma-separated") do |v|
+          flags[:include_paths] = v.split(",")
+        end
+        opts.on("--exclude PATHS", "Subdirectories/files to exclude, comma-separated") do |v|
+          flags[:exclude_paths] = v.split(",")
+        end
+        opts.on("--strictness LEVEL", "low|default|high") { |v| flags[:strictness] = v.to_sym }
+        opts.on("--mutation-types TYPES", "Mutation types to apply, comma-separated") do |v|
+          flags[:mutation_types] = v.split(",").map(&:to_sym)
+        end
+        opts.on("--exit-zero", "Do not fail even if survived mutations exist") do
+          flags[:exit_on_survivors] = false
+        end
+        opts.on("--json-output PATH", "Export summary to a JSON file") do |v|
+          flags[:json_output_path] = v
+        end
+        opts.on("--config PATH", "Use a config file other than .mutaterb.yml") do |v|
+          flags[:config_path] = v
+        end
+        opts.on("-h", "--help", "Show this help") do
+          puts opts
+          exit 0
+        end
+      end
+    end
+  end
+end

data/lib/mutaterb/mutant.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # A single mutation applied to one location of a source file.
+  #
+  # Status starts at :pending and transitions exactly once to :killed,
+  # :survived or :error (data-model.md).
+  class Mutant
+    VALID_STATUSES = %i[pending killed survived error].freeze
+    VALID_KILL_REASONS = %i[assertion_failure timeout].freeze
+
+    attr_reader :id, :operator_type, :file_path, :line, :column_range,
+                :original_fragment, :mutated_fragment, :status, :kill_reason,
+                :related_tests, :failing_tests, :error_message
+
+    def initialize(id:, operator_type:, file_path:, line:, column_range:,
+                   original_fragment:, mutated_fragment:)
+      raise ArgumentError, "id must be a String" unless id.is_a?(String)
+      raise ArgumentError, "operator_type must be a Symbol" unless operator_type.is_a?(Symbol)
+      raise ArgumentError, "file_path must be a String" unless file_path.is_a?(String)
+      raise ArgumentError, "line must be an Integer" unless line.is_a?(Integer)
+      raise ArgumentError, "column_range must be a Range" unless column_range.is_a?(Range)
+
+      @id = id
+      @operator_type = operator_type
+      @file_path = file_path
+      @line = line
+      @column_range = column_range
+      @original_fragment = original_fragment
+      @mutated_fragment = mutated_fragment
+      @status = :pending
+      @kill_reason = nil
+      @related_tests = []
+      @failing_tests = []
+      @error_message = nil
+    end
+
+    def related_tests=(test_cases)
+      @related_tests = Array(test_cases)
+    end
+
+    # Records the single, final outcome of running this mutant (FR-004).
+    def finish!(status:, kill_reason: nil, failing_tests: [], error_message: nil)
+      raise MutationError, "Mutant #{id} already finished as #{@status}" unless @status == :pending
+      raise ArgumentError, "invalid status #{status.inspect}" unless VALID_STATUSES.include?(status)
+      raise ArgumentError, "status must not be :pending" if status == :pending
+      if kill_reason && !VALID_KILL_REASONS.include?(kill_reason)
+        raise ArgumentError, "invalid kill_reason #{kill_reason.inspect}"
+      end
+
+      @status = status
+      @kill_reason = kill_reason
+      @failing_tests = Array(failing_tests)
+      @error_message = error_message
+      self
+    end
+
+    def killed? = status == :killed
+    def survived? = status == :survived
+    def error? = status == :error
+  end
+end

data/lib/mutaterb/mutation_operators/arithmetic_comparison_operator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MutateRB
+  module MutationOperators
+    # Swaps an arithmetic or equality operator for its common typo/off-by-logic
+    # counterpart: + <-> -, * <-> /, == <-> !=.
+    class ArithmeticComparisonOperator < BaseOperator
+      SWAPS = { "+" => "-", "-" => "+", "*" => "/", "/" => "*", "==" => "!=", "!=" => "==" }.freeze
+
+      def self.operator_type = :arithmetic_comparison
+
+      def self.applicable?(node)
+        node.type == :OPCALL && SWAPS.key?(node.children[1].to_s)
+      end
+
+      def self.replacement_for(node, fragment)
+        op = node.children[1].to_s
+        fragment.sub(op, SWAPS.fetch(op))
+      end
+    end
+  end
+end

data/lib/mutaterb/mutation_operators/base_operator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module MutateRB
+  module MutationOperators
+    # Walks a file's AST via RubyVM::AbstractSyntaxTree (research.md #1) and
+    # turns each matching node into a Mutant, without reserializing the file:
+    # only the exact node span gets patched as a text substitution.
+    #
+    # ponytail: multi-line expressions are skipped (first_lineno != last_lineno)
+    # to keep the text-patch approach simple; revisit with the `parser` gem if
+    # the operator catalog needs to mutate across line breaks.
+    class BaseOperator
+      class << self
+        def operator_type
+          raise NotImplementedError
+        end
+
+        def applicable?(_node)
+          raise NotImplementedError
+        end
+
+        def replacement_for(_node, _fragment)
+          raise NotImplementedError
+        end
+
+        def candidates(file_path)
+          source = File.read(file_path)
+          root = RubyVM::AbstractSyntaxTree.parse(source)
+          lines = source.lines
+          mutants = []
+          walk(root) { |node| mutants << build_mutant(file_path, lines, node) if applicable?(node) }
+          mutants.compact
+        rescue SyntaxError
+          []
+        end
+
+        private
+
+        def walk(node, &block)
+          return unless node.is_a?(RubyVM::AbstractSyntaxTree::Node)
+
+          block.call(node) if node.first_lineno == node.last_lineno
+          node.children.each { |child| walk(child, &block) }
+        end
+
+        def build_mutant(file_path, lines, node)
+          range = node.first_column...node.last_column
+          original = lines[node.first_lineno - 1][range]
+          return nil if original.nil?
+
+          mutated = replacement_for(node, original)
+          return nil if mutated.nil? || mutated == original
+
+          Mutant.new(
+            id: "#{file_path}:#{node.first_lineno}:#{range.begin}:#{operator_type}",
+            operator_type: operator_type,
+            file_path: file_path,
+            line: node.first_lineno,
+            column_range: range,
+            original_fragment: original,
+            mutated_fragment: mutated
+          )
+        end
+      end
+    end
+  end
+end

data/lib/mutaterb/mutation_operators/boolean_literal_operator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module MutateRB
+  module MutationOperators
+    # Flips a literal `true`/`false`.
+    class BooleanLiteralOperator < BaseOperator
+      def self.operator_type = :boolean_literal
+
+      def self.applicable?(node)
+        %i[TRUE FALSE].include?(node.type)
+      end
+
+      def self.replacement_for(_node, fragment)
+        fragment == "true" ? "false" : "true"
+      end
+    end
+  end
+end

data/lib/mutaterb/mutation_operators/conditional_boundary_operator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module MutateRB
+  module MutationOperators
+    # Swaps a comparison operator for its off-by-one boundary: < <-> <=, > <-> >=.
+    class ConditionalBoundaryOperator < BaseOperator
+      SWAPS = { "<" => "<=", "<=" => "<", ">" => ">=", ">=" => ">" }.freeze
+
+      def self.operator_type = :conditional_boundary
+
+      def self.applicable?(node)
+        node.type == :OPCALL && SWAPS.key?(node.children[1].to_s)
+      end
+
+      def self.replacement_for(node, fragment)
+        op = node.children[1].to_s
+        fragment.sub(op, SWAPS.fetch(op))
+      end
+    end
+  end
+end

data/lib/mutaterb/mutation_operators/nil_literal_operator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module MutateRB
+  module MutationOperators
+    # Replaces a literal `nil` with `false` — distinguishes code/tests that
+    # depend on `nil` specifically (`.nil?`, `== nil`) from merely-falsy checks.
+    #
+    # ponytail: a bare `nil` as the sole/last expression of a method body is
+    # optimized away by Ruby (implicit nil return, no NIL node at all), so it
+    # is never mutated. Upgrade path: only relevant if that trailing-position
+    # case turns out to matter in practice.
+    class NilLiteralOperator < BaseOperator
+      def self.operator_type = :nil_literal
+
+      def self.applicable?(node)
+        node.type == :NIL
+      end
+
+      def self.replacement_for(_node, _fragment)
+        "false"
+      end
+    end
+  end
+end

data/lib/mutaterb/mutation_run.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # Aggregates a complete run: the config used, the detected test suite, and
+  # every mutant generated with its outcome (data-model.md).
+  class MutationRun
+    attr_reader :config, :test_suite, :mutants, :started_at
+    attr_accessor :finished_at, :interrupted
+
+    def initialize(config:, test_suite:)
+      @config = config
+      @test_suite = test_suite
+      @mutants = []
+      @started_at = Time.now
+      @finished_at = nil
+      @interrupted = false
+    end
+
+    def add_mutant(mutant)
+      raise ArgumentError, "expected a Mutant" unless mutant.is_a?(Mutant)
+
+      @mutants << mutant
+      mutant
+    end
+
+    def baseline_broken_tests
+      test_suite.baseline_broken_tests
+    end
+
+    def survived?
+      mutants.any?(&:survived?)
+    end
+
+    def survived_mutants
+      mutants.select(&:survived?)
+    end
+
+    def summary
+      {
+        total_mutants: mutants.size,
+        killed: mutants.count(&:killed?),
+        survived: mutants.count(&:survived?),
+        errors: mutants.count(&:error?),
+        baseline_broken_tests: baseline_broken_tests.size
+      }
+    end
+
+    # Exit code for a normal (non-interrupted) completion. SIGINT is handled
+    # separately by the CLI's signal trap (contracts/cli.md: exit 130).
+    def exit_code
+      return 0 unless survived?
+      return 0 unless config.exit_on_survivors
+
+      1
+    end
+  end
+end

data/lib/mutaterb/mutator.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # Orchestrates one mutation at a time: patches the file, runs the related
+  # tests, classifies the outcome, and always restores the original file
+  # (FR-003, FR-005, FR-010).
+  class Mutator
+    OPERATORS = {
+      conditional_boundary: MutationOperators::ConditionalBoundaryOperator,
+      boolean_literal: MutationOperators::BooleanLiteralOperator,
+      nil_literal: MutationOperators::NilLiteralOperator,
+      arithmetic_comparison: MutationOperators::ArithmeticComparisonOperator
+    }.freeze
+
+    def initialize(config:, test_suite:, test_runner: nil)
+      @config = config
+      @test_suite = test_suite
+      @test_runner = test_runner || TestRunner.new(config: config, project_type: test_suite.project_type)
+    end
+
+    # Yields each finished Mutant, one at a time.
+    def each_mutant
+      source_files.each do |file|
+        candidates_for(file).each { |mutant| yield run_one(mutant) }
+      end
+    end
+
+    private
+
+    attr_reader :config, :test_suite, :test_runner
+
+    def source_files
+      Dir.glob(File.join(config.target_dir, "**", "*.rb"))
+         .reject { |f| f.include?("/spec/") || f.start_with?(File.join(config.target_dir, "spec")) }
+         .select { |f| in_scope?(f) }
+    end
+
+    def in_scope?(file)
+      included = config.include_paths.empty? || config.include_paths.any? { |p| file.start_with?(p) }
+      excluded = config.exclude_paths.any? { |p| file.start_with?(p) }
+      included && !excluded
+    end
+
+    def candidates_for(file)
+      config.mutation_types.flat_map { |type| OPERATORS.fetch(type).candidates(file) }
+    end
+
+    def run_one(mutant)
+      related = related_tests_for(mutant.file_path)
+      mutant.related_tests = related
+
+      begin
+        original_content = File.read(mutant.file_path)
+      rescue StandardError => e
+        mutant.finish!(status: :error, error_message: "could not read #{mutant.file_path}: #{e.message}")
+        return mutant
+      end
+
+      begin
+        apply_patch(mutant, original_content)
+        classify(mutant, related)
+      rescue StandardError => e
+        mutant.finish!(status: :error, error_message: e.message) if mutant.status == :pending
+      ensure
+        File.write(mutant.file_path, original_content)
+      end
+
+      mutant
+    end
+
+    def apply_patch(mutant, original_content)
+      lines = original_content.lines
+      line = lines[mutant.line - 1]
+      range = mutant.column_range
+      lines[mutant.line - 1] = line[0...range.begin] + mutant.mutated_fragment + line[range.end..]
+      patched = lines.join
+
+      begin
+        RubyVM::AbstractSyntaxTree.parse(patched)
+      rescue SyntaxError => e
+        mutant.finish!(status: :error, error_message: "mutation produced invalid code: #{e.message}")
+        return
+      end
+
+      File.write(mutant.file_path, patched)
+    end
+
+    def classify(mutant, related_tests)
+      return unless mutant.status == :pending # apply_patch already marked :error
+
+      if related_tests.empty?
+        finish_inconclusive(mutant, "no related tests")
+        return
+      end
+
+      result = test_runner.run_for_mutant(related_tests)
+      case result[:status]
+      when :timeout
+        mutant.finish!(status: :killed, kill_reason: :timeout)
+      when :error
+        finish_inconclusive(mutant, "failed to run tests")
+      else
+        classify_from_examples(mutant, related_tests, result[:examples])
+      end
+    end
+
+    # An inconclusive result (no tests exercised the mutation, or test
+    # execution failed) does not prove the mutation is detected. With
+    # strictness "high" this counts as evidence of weakness ("survived");
+    # at other levels it is reported separately as "error" without
+    # affecting the killed/survived count (US3/AC2, FR-008).
+    def finish_inconclusive(mutant, message)
+      if config.strictness == :high
+        mutant.finish!(status: :survived)
+      else
+        mutant.finish!(status: :error, error_message: message)
+      end
+    end
+
+    def classify_from_examples(mutant, related_tests, examples)
+      failing_ids = examples.select { |e| e[:status] == :failed }.map { |e| e[:id] }
+      failing_tests = related_tests.select { |t| failing_ids.include?(t.id) }
+      if failing_tests.any?
+        mutant.finish!(status: :killed, kill_reason: :assertion_failure, failing_tests: failing_tests)
+      else
+        mutant.finish!(status: :survived)
+      end
+    end
+
+    # Convention-based coverage mapping: lib/foo/bar.rb -> spec/foo/bar_spec.rb.
+    # ponytail: no real coverage tracking yet; falls back to the whole suite
+    # when no matching spec file exists. Upgrade path: integrate SimpleCov
+    # coverage data if this heuristic proves too coarse for real projects.
+    def related_tests_for(source_file)
+      mapped = mapped_spec_file(source_file)
+      matches = test_suite.test_cases.select { |t| t.file_path == mapped }
+      matches = test_suite.test_cases.dup if matches.empty?
+      matches.reject(&:baseline_broken?)
+    end
+
+    def mapped_spec_file(source_file)
+      relative = source_file.sub(%r{\A#{Regexp.escape(config.target_dir)}/?}, "")
+      relative = relative.sub(%r{\A(lib|app)/}, "")
+      spec_relative = relative.sub(/\.rb\z/, "_spec.rb")
+      File.join(config.target_dir, "spec", spec_relative)
+    end
+  end
+end

data/lib/mutaterb/project_detector.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # Detects whether the target project is Ruby or Rails and locates its RSpec
+  # files (FR-001, FR-002).
+  class ProjectDetector
+    Detection = Struct.new(:project_type, :spec_files)
+
+    def initialize(config)
+      @config = config
+    end
+
+    def detect
+      Detection.new(project_type, discover_spec_files)
+    end
+
+    private
+
+    attr_reader :config
+
+    def project_type
+      rails_marker = File.join(config.target_dir, "config", "application.rb")
+      rails_bin = File.join(config.target_dir, "bin", "rails")
+      File.exist?(rails_marker) || File.exist?(rails_bin) ? :rails : :ruby
+    end
+
+    def discover_spec_files
+      pattern = File.join(config.target_dir, "spec", "**", "*_spec.rb")
+      apply_scope(Dir.glob(pattern))
+    end
+
+    def apply_scope(files)
+      files = files.select { |f| config.include_paths.any? { |p| f.start_with?(p) } } unless config.include_paths.empty?
+      files.reject { |f| config.exclude_paths.any? { |p| f.start_with?(p) } }
+    end
+  end
+end

data/lib/mutaterb/reporter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module MutateRB
+  # Prints the console summary (FR-006) and, if configured, exports the same
+  # result to JSON (FR-015, contracts/json-report-schema.md).
+  class Reporter
+    def initialize(run)
+      @run = run
+    end
+
+    def report
+      print_console
+      write_json if run.config.json_output_path
+    end
+
+    private
+
+    attr_reader :run
+
+    def print_console
+      summary = run.summary
+      puts "MutateRB — #{summary[:total_mutants]} mutations: " \
+           "#{summary[:killed]} killed, #{summary[:survived]} survived, #{summary[:errors]} errors"
+      print_baseline_broken
+      print_survived
+    end
+
+    def print_baseline_broken
+      broken = run.baseline_broken_tests
+      return if broken.empty?
+
+      puts "Pre-broken tests before mutation (excluded from count): #{broken.size}"
+      broken.each { |t| puts "  - #{t.id} #{t.description}" }
+    end
+
+    def print_survived
+      survived = run.survived_mutants
+      return if survived.empty?
+
+      puts "\nSurvived mutations (weak tests):"
+      survived.each do |mutant|
+        related = mutant.related_tests.map(&:id).join(", ")
+        puts "  - #{mutant.file_path}:#{mutant.line} [#{mutant.operator_type}] " \
+             "'#{mutant.original_fragment}' -> '#{mutant.mutated_fragment}' (tests: #{related})"
+      end
+    end
+
+    def write_json
+      File.write(run.config.json_output_path, JSON.pretty_generate(to_h))
+    end
+
+    def to_h
+      {
+        mutaterb_version: MutateRB::VERSION,
+        started_at: run.started_at.utc.iso8601,
+        finished_at: run.finished_at&.utc&.iso8601,
+        interrupted: run.interrupted,
+        config: config_h,
+        summary: run.summary,
+        baseline_broken_tests: run.baseline_broken_tests.map { |t| test_case_h(t) },
+        survived_mutants: run.survived_mutants.map { |m| mutant_h(m) },
+        exit_code: run.exit_code
+      }
+    end
+
+    def config_h
+      c = run.config
+      {
+        target_dir: c.target_dir,
+        include_paths: c.include_paths,
+        exclude_paths: c.exclude_paths,
+        strictness: c.strictness.to_s,
+        mutation_types: c.mutation_types.map(&:to_s),
+        exit_on_survivors: c.exit_on_survivors
+      }
+    end
+
+    def mutant_h(mutant)
+      {
+        id: mutant.id,
+        operator_type: mutant.operator_type.to_s,
+        file_path: mutant.file_path,
+        line: mutant.line,
+        original_fragment: mutant.original_fragment,
+        mutated_fragment: mutant.mutated_fragment,
+        related_tests: mutant.related_tests.map { |t| test_case_h(t) }
+      }
+    end
+
+    def test_case_h(test_case)
+      { id: test_case.id, description: test_case.description }
+    end
+  end
+end

data/lib/mutaterb/test_case.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # A single test detected in the target project (data-model.md).
+  class TestCase
+    VALID_BASELINE_STATUSES = %i[passed failed].freeze
+
+    attr_reader :id, :description, :file_path
+    attr_accessor :baseline_status, :baseline_duration_seconds
+
+    def initialize(id:, description:, file_path:, baseline_status: nil,
+                   baseline_duration_seconds: nil)
+      raise ArgumentError, "id must be a String" unless id.is_a?(String)
+      raise ArgumentError, "file_path must be a String" unless file_path.is_a?(String)
+      if baseline_status && !VALID_BASELINE_STATUSES.include?(baseline_status)
+        raise ArgumentError, "invalid baseline_status #{baseline_status.inspect}"
+      end
+
+      @id = id
+      @description = description.to_s
+      @file_path = file_path
+      @baseline_status = baseline_status
+      @baseline_duration_seconds = baseline_duration_seconds
+    end
+
+    def baseline_broken? = baseline_status == :failed
+  end
+end

data/lib/mutaterb/test_runner.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+require "bundler"
+
+module MutateRB
+  # Runs the target project's own RSpec suite as a subprocess (research.md #2):
+  # MutateRB never bundles its own RSpec, it shells out to `bundle exec rspec`
+  # inside the target project so the project's own Gemfile.lock decides the
+  # RSpec version.
+  class TestRunner
+    MIN_TIMEOUT_SECONDS = 5
+
+    def initialize(config:, project_type:)
+      @config = config
+      @project_type = project_type
+    end
+
+    # Runs the given spec files once, unmutated, and returns one Hash per
+    # RSpec example: { id:, description:, file_path:, status:, duration: }.
+    # Used to build TestCase instances (FR-012's baseline_status) and as the
+    # basis for the per-mutant timeout (FR-014).
+    def run_baseline(spec_files)
+      spawn_rspec(spec_files, timeout_seconds: nil).fetch(:examples, [])
+    end
+
+    # Runs the given test cases against a mutation. Timeout = 2x the slowest
+    # related test's baseline duration, floor MIN_TIMEOUT_SECONDS (FR-014).
+    # On timeout the child process is killed explicitly (research.md #3) so no
+    # hung process survives the run.
+    def run_for_mutant(test_cases)
+      return { status: :error, examples: [] } if test_cases.empty?
+
+      slowest_baseline = test_cases.filter_map(&:baseline_duration_seconds).max || 0
+      timeout_seconds = [slowest_baseline * 2, MIN_TIMEOUT_SECONDS].max
+      files = test_cases.map(&:file_path).uniq
+      spawn_rspec(files, timeout_seconds: timeout_seconds)
+    end
+
+    private
+
+    attr_reader :config, :project_type
+
+    # Runs inside Bundler.with_unbundled_env (research.md #2): when `mutaterb`
+    # itself is invoked via `bundle exec`, BUNDLE_GEMFILE/RUBYOPT point at
+    # MutateRB's own Gemfile and would otherwise leak into this child process,
+    # making `bundle exec rspec` resolve the target project's suite against
+    # the wrong bundle. with_unbundled_env restores the pre-bundler
+    # environment for the duration of the spawn.
+    def spawn_rspec(files, timeout_seconds:)
+      env = project_type == :rails ? { "RAILS_ENV" => "test" } : {}
+      stdout_read, stdout_write = IO.pipe
+      pid = Bundler.with_unbundled_env do
+        Process.spawn(env, *rspec_command(files), out: stdout_write, err: File::NULL,
+                                                  chdir: File.expand_path(config.target_dir))
+      end
+      stdout_write.close
+
+      output = wait_with_timeout(pid, stdout_read, timeout_seconds)
+      stdout_read.close unless stdout_read.closed?
+      output
+    end
+
+    def wait_with_timeout(pid, stdout_read, timeout_seconds)
+      if timeout_seconds
+        Timeout.timeout(timeout_seconds) { read_and_wait(pid, stdout_read) }
+      else
+        read_and_wait(pid, stdout_read)
+      end
+    rescue Timeout::Error
+      kill(pid)
+      { status: :timeout, examples: [] }
+    end
+
+    def read_and_wait(pid, stdout_read)
+      raw = stdout_read.read
+      Process.wait(pid)
+      parse_output(raw)
+    end
+
+    # Kills a hung child process: TERM first, KILL if it ignores TERM for 1s
+    # (research.md #3 — Timeout alone never touches the child process).
+    def kill(pid)
+      Process.kill("TERM", pid)
+      begin
+        Timeout.timeout(1) { Process.wait(pid) }
+      rescue Timeout::Error
+        Process.kill("KILL", pid)
+        Process.wait(pid)
+      end
+    rescue Errno::ESRCH, Errno::ECHILD
+      nil
+    end
+
+    def rspec_command(files)
+      ["bundle", "exec", "rspec", "--format", "json", *files]
+    end
+
+    def parse_output(raw)
+      data = JSON.parse(raw)
+      examples = data.fetch("examples", []).map do |example|
+        {
+          id: example["id"],
+          description: example["full_description"],
+          file_path: example["file_path"],
+          status: example["status"] == "passed" ? :passed : :failed,
+          duration: example["run_time"].to_f
+        }
+      end
+      { status: :completed, examples: examples }
+    rescue JSON::ParserError
+      { status: :error, examples: [] }
+    end
+  end
+end

data/lib/mutaterb/test_suite.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module MutateRB
+  # The collection of tests detected for the target project (data-model.md).
+  class TestSuite
+    VALID_PROJECT_TYPES = %i[ruby rails].freeze
+
+    attr_reader :framework, :project_type, :test_cases
+
+    def initialize(project_type:, test_cases: [])
+      unless VALID_PROJECT_TYPES.include?(project_type)
+        raise ArgumentError,
+              "invalid project_type #{project_type.inspect}"
+      end
+
+      @framework = :rspec
+      @project_type = project_type
+      @test_cases = Array(test_cases)
+    end
+
+    # Builds a TestSuite from the raw example hashes returned by
+    # TestRunner#run_baseline (FR-012's baseline_status comes from here).
+    def self.from_baseline(project_type:, baseline_examples:)
+      test_cases = baseline_examples.map do |example|
+        TestCase.new(
+          id: example.fetch(:id),
+          description: example.fetch(:description),
+          file_path: example.fetch(:file_path),
+          baseline_status: example.fetch(:status),
+          baseline_duration_seconds: example.fetch(:duration)
+        )
+      end
+      new(project_type: project_type, test_cases: test_cases)
+    end
+
+    def find(id)
+      test_cases.find { |test_case| test_case.id == id }
+    end
+
+    def baseline_broken_tests
+      test_cases.select(&:baseline_broken?)
+    end
+  end
+end

data/lib/mutaterb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MutateRB
+  VERSION = "0.1.0"
+end

data/lib/mutaterb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "mutaterb/version"
+require_relative "mutaterb/errors"
+require_relative "mutaterb/mutant"
+require_relative "mutaterb/test_case"
+require_relative "mutaterb/test_suite"
+require_relative "mutaterb/config"
+require_relative "mutaterb/mutation_run"
+require_relative "mutaterb/flag_parser"
+require_relative "mutaterb/project_detector"
+require_relative "mutaterb/test_runner"
+require_relative "mutaterb/mutation_operators/base_operator"
+require_relative "mutaterb/mutation_operators/conditional_boundary_operator"
+require_relative "mutaterb/mutation_operators/boolean_literal_operator"
+require_relative "mutaterb/mutation_operators/nil_literal_operator"
+require_relative "mutaterb/mutation_operators/arithmetic_comparison_operator"
+require_relative "mutaterb/mutator"
+require_relative "mutaterb/reporter"
+require_relative "mutaterb/cli"
+
+module MutateRB
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: mutaterb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MarceloM47
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+description: Detects weak tests by mutating source code covered by an RSpec suite
+  and checking whether the suite catches the mutation.
+email:
+- marcelo.esteche@proton.me
+executables:
+- mutaterb
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/mutaterb
+- lib/mutaterb.rb
+- lib/mutaterb/cli.rb
+- lib/mutaterb/config.rb
+- lib/mutaterb/errors.rb
+- lib/mutaterb/flag_parser.rb
+- lib/mutaterb/mutant.rb
+- lib/mutaterb/mutation_operators/arithmetic_comparison_operator.rb
+- lib/mutaterb/mutation_operators/base_operator.rb
+- lib/mutaterb/mutation_operators/boolean_literal_operator.rb
+- lib/mutaterb/mutation_operators/conditional_boundary_operator.rb
+- lib/mutaterb/mutation_operators/nil_literal_operator.rb
+- lib/mutaterb/mutation_run.rb
+- lib/mutaterb/mutator.rb
+- lib/mutaterb/project_detector.rb
+- lib/mutaterb/reporter.rb
+- lib/mutaterb/test_case.rb
+- lib/mutaterb/test_runner.rb
+- lib/mutaterb/test_suite.rb
+- lib/mutaterb/version.rb
+homepage: https://github.com/MarceloM47/mutateRB
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MarceloM47/mutateRB
+  source_code_uri: https://github.com/MarceloM47/mutateRB
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Mutation testing CLI for Ruby and Ruby on Rails projects
+test_files: []