moots 0.1.0

data/lib/moots/cli.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../moots"
+require_relative "reporter"
+
+module Moots
+  # Command-line entry point. Survivors and empty runs have a failing exit status.
+  class CLI
+    def self.run(argv = ARGV, out: $stdout, err: $stderr)
+      new(argv, out: out, err: err).run
+    end
+
+    def initialize(argv, out:, err:)
+      @argv = argv
+      @out = out
+      @err = err
+      @path = ".moots.yml"
+      @explicit_path = false
+      @format = "text"
+      @overrides = {}
+    end
+
+    def run
+      return 0 unless run_requested?
+
+      @config_path = @path if @explicit_path || File.exist?(@path)
+      config = @config_path ? Configuration.load(@config_path) : {}
+      results = Moots.run(config.merge(@overrides)) { |event| reporter.call(event) }
+      reporter.finish(results)
+      return 1 if results.empty?
+
+      results.all?(&:killed) ? 0 : 1
+    rescue Error, OptionParser::ParseError, SystemCallError => e
+      reporter.error(e.message)
+      2
+    rescue Interrupt
+      reporter.error("Interrupted")
+      130
+    end
+
+    private
+
+    def reporter
+      @reporter ||= Reporter.new(format: @format, out: @out, err: @err, config_path: @config_path)
+    end
+
+    def run_requested?
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: moots [--config PATH] [--format text|json] [--mutation ID] [--jobs N]"
+        options.on("-c", "--config PATH", "Configuration file (default: .moots.yml)") do |value|
+          @path = value
+          @explicit_path = true
+        end
+        options.on("--format FORMAT", %w[text json], "Output format (default: text)") { |value| @format = value }
+        options.on("--mutation ID", "Run one mutation by its reported ID") { |value| @overrides[:mutation] = value }
+        options.on("-j", "--jobs N", Integer, "Concurrent isolated workers (default: 1)") do |value|
+          @overrides[:jobs] = value
+        end
+        options.on("-v", "--version", "Print version") do
+          @out.puts(VERSION)
+          return false
+        end
+        options.on("-h", "--help", "Show help") do
+          @out.puts(options)
+          return false
+        end
+      end
+      remaining = parser.parse(@argv)
+      raise Error, "Unexpected arguments: #{remaining.join(" ")}" unless remaining.empty?
+
+      true
+    end
+  end
+end

data/lib/moots/configuration.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "error"
+
+module Moots
+  # Load safe YAML and validate the options shared by the CLI and Ruby API.
+  class Configuration
+    DEFAULTS = {
+      include: ["app/**/*.rb", "lib/**/*.rb"].freeze,
+      exclude: [].freeze,
+      test_command: "bundle exec rspec",
+      timeout: 60,
+      mutation: nil,
+      isolation: true,
+      jobs: 1,
+      workspace_exclude: ["tmp", "coverage", "pkg", ".rspec_status"].freeze
+    }.freeze
+
+    def self.load(path)
+      new(YAML.safe_load_file(path)).to_h
+    rescue Psych::Exception, SystemCallError => e
+      raise Error, "Cannot load configuration #{path}: #{e.message}"
+    end
+
+    def initialize(options = {})
+      raise Error, "Configuration must be a mapping" unless options.is_a?(Hash)
+
+      normalized = options.transform_keys(&:to_s)
+      unknown = normalized.keys - DEFAULTS.keys.map(&:to_s)
+      raise Error, "Unknown configuration keys: #{unknown.join(", ")}" unless unknown.empty?
+
+      @options = DEFAULTS.merge(normalized.transform_keys(&:to_sym))
+      validate_patterns(:include)
+      validate_patterns(:exclude)
+      validate_patterns(:workspace_exclude)
+      raise Error, "isolation must be true or false" unless [true, false].include?(@options[:isolation])
+
+      validate_jobs
+      validate_command
+      validate_mutation
+      timeout = @options[:timeout]
+      return if timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout.positive?
+
+      raise Error, "timeout must be a positive finite number of seconds"
+    end
+
+    def to_h
+      @options.dup
+    end
+
+    private
+
+    def validate_jobs
+      jobs = @options[:jobs]
+      raise Error, "jobs must be a positive integer" unless jobs.is_a?(Integer) && jobs.positive?
+      raise Error, "jobs greater than 1 require isolation: true" if jobs > 1 && !@options[:isolation]
+    end
+
+    def validate_patterns(key)
+      patterns = @options[key]
+      return if patterns.is_a?(Array) && patterns.all? { |pattern| valid_string?(pattern) }
+
+      raise Error, "#{key} must be an array of non-empty glob strings"
+    end
+
+    def validate_command
+      command = @options[:test_command]
+      return if valid_string?(command)
+      return if command.is_a?(Array) && !command.empty? && command.all? { |part| valid_string?(part) }
+
+      raise Error, "test_command must be a non-empty string or argument array"
+    end
+
+    def valid_string?(value)
+      value.is_a?(String) && !value.strip.empty? && !value.include?("\0")
+    end
+
+    def validate_mutation
+      id = @options[:mutation]
+      return if id.nil? || (id.is_a?(String) && /\A[0-9a-f]{16}\z/.match?(id))
+
+      raise Error, "mutation must be a 16-character lowercase hexadecimal ID or null"
+    end
+  end
+end

data/lib/moots/environment.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Moots
+  # Relocate known Bundler and Ruby path variables without editing the parent environment.
+  module Environment
+    PATH_VARIABLES = %w[BUNDLE_GEMFILE BUNDLE_APP_CONFIG BUNDLE_BIN_PATH BUNDLE_PATH GEM_HOME].freeze
+    PATH_LISTS = %w[GEM_PATH RUBYLIB PATH].freeze
+
+    def self.rebase(source, &mapper)
+      (PATH_VARIABLES + PATH_LISTS).each_with_object({}) do |name, overrides|
+        [name, "BUNDLER_ORIG_#{name}"].each do |key|
+          next unless source.key?(key)
+
+          overrides[key] = if PATH_LISTS.include?(name)
+                             source.fetch(key).split(File::PATH_SEPARATOR, -1).map(&mapper).join(File::PATH_SEPARATOR)
+                           else
+                             mapper.call(source.fetch(key))
+                           end
+        end
+      end
+    end
+  end
+end

data/lib/moots/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Moots
+  # An invalid configuration, source file, or test execution.
+  class Error < StandardError; end
+end

data/lib/moots/mutation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require "digest"
+require "json"
+require "pathname"
+
+module Moots
+  # A single expression replacement, located by byte offset in the original source.
+  class Mutation
+    attr_reader :original_code, :mutated_code, :line_number, :file_path, :start_offset
+
+    def initialize(original_code:, mutated_code:, line_number:, file_path:, start_offset:)
+      @original_code = original_code
+      @mutated_code = mutated_code
+      @line_number = line_number
+      @file_path = file_path
+      @start_offset = start_offset
+    end
+
+    def relative_path(root: Dir.pwd)
+      Pathname.new(File.expand_path(file_path)).relative_path_from(Pathname.new(File.expand_path(root))).to_s
+    end
+
+    # Stable across equivalent checkouts; source bytes distinguish each replacement.
+    def id(root: Dir.pwd)
+      identity = [relative_path(root: root), start_offset, original_code.b.unpack1("H*"), mutated_code.b.unpack1("H*")]
+      Digest::SHA256.hexdigest(JSON.generate(identity))[0, 16]
+    end
+
+    # Return a changed copy without touching the input or replacing other occurrences.
+    def apply(code)
+      bytes = code.b
+      unless bytes.byteslice(start_offset, original_code.bytesize) == original_code.b
+        raise Error, "Source no longer matches mutation at #{file_path}:#{line_number}"
+      end
+
+      bytes[start_offset, original_code.bytesize] = mutated_code.b
+      bytes.force_encoding(code.encoding)
+    end
+  end
+end

data/lib/moots/mutation_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "mutation"
+
+module Moots
+  # Generate one mutation per supported operator using Prism's byte locations.
+  class MutationGenerator
+    ARITHMETIC_OPERATORS = { "+" => "-", "-" => "+", "*" => "/", "/" => "*" }.freeze
+    COMPARISON_OPERATORS = { "==" => "!=", "!=" => "==", ">" => ">=", ">=" => ">", "<" => "<=", "<=" => "<" }.freeze
+    CALL_OPERATORS = ARITHMETIC_OPERATORS.merge(COMPARISON_OPERATORS).freeze
+    BOOLEAN_OPERATORS = { "&&" => "||", "||" => "&&", "and" => "or", "or" => "and" }.freeze
+
+    def generate_mutations(code, file_path: "(string)")
+      parsed = Prism.parse(code)
+      unless parsed.success?
+        error = parsed.errors.first
+        raise Error, "#{file_path}:#{error.location.start_line}: #{error.message}"
+      end
+
+      mutations = []
+      nodes = [parsed.value]
+      until nodes.empty?
+        node = nodes.pop
+        mutation = mutation_for(node, file_path)
+        mutations << mutation if mutation
+        nodes.concat(node.compact_child_nodes.reverse)
+      end
+      mutations
+    end
+
+    private
+
+    def mutation_for(node, file_path)
+      case node
+      when Prism::CallNode
+        replacement = CALL_OPERATORS[node.name.to_s]
+        return unless replacement
+
+        location = node.message_loc
+      when Prism::AndNode, Prism::OrNode
+        location = node.operator_loc
+        replacement = BOOLEAN_OPERATORS.fetch(location.slice)
+      else
+        return
+      end
+
+      expression = node.location
+      mutated = expression.slice.b
+      mutated[location.start_offset - expression.start_offset, location.length] = replacement
+      Mutation.new(
+        original_code: expression.slice,
+        mutated_code: mutated.force_encoding(expression.slice.encoding),
+        line_number: location.start_line,
+        file_path: file_path,
+        start_offset: expression.start_offset
+      )
+    end
+  end
+end

data/lib/moots/reporter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moots
+  # Stream progress independently of the final, versioned machine-readable report.
+  class Reporter
+    def initialize(format:, out:, err:, config_path: nil, root: Dir.pwd)
+      @format = format
+      @out = out
+      @err = err
+      @progress = format == "json" ? err : out
+      @config_path = config_path
+      @root = root
+      @results = []
+    end
+
+    def call(event)
+      case event.fetch(:type)
+      when :workspace_started
+        @progress.puts("Preparing isolated working copy...")
+      when :baseline_started
+        @progress.puts("Running baseline tests...")
+      when :baseline_passed
+        @progress.puts("Baseline passed.")
+      when :mutation_started
+        @progress.puts("[#{event.fetch(:index)}/#{event.fetch(:total)}] Testing #{location(event.fetch(:mutation))}")
+      when :mutation_finished
+        result = event.fetch(:result)
+        @results[event.fetch(:index, @results.size)] = result
+        @progress.puts("#{result.killed ? "KILLED" : "SURVIVED"} #{location(result.mutation)}")
+        survivor(result.mutation) unless result.killed
+      else
+        raise ArgumentError, "Unknown progress event: #{event[:type]}"
+      end
+      @progress.flush
+    end
+
+    def finish(results)
+      @results = results
+      if @format == "json"
+        @out.puts(JSON.generate(document("completed")))
+      else
+        counts = summary
+        @out.puts("#{counts[:mutations]} mutations, #{counts[:killed]} killed, #{counts[:survived]} survived")
+      end
+      @out.flush
+    end
+
+    def error(message)
+      @err.puts("moots: #{text(message)}")
+      @err.flush
+      return unless @format == "json"
+
+      @out.puts(JSON.generate(document("error").merge(error: text(message))))
+      @out.flush
+    end
+
+    private
+
+    def text(value)
+      value.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    def location(mutation)
+      "#{mutation.id(root: @root)} #{text(mutation.relative_path(root: @root))}:#{mutation.line_number}"
+    end
+
+    def rerun(mutation)
+      command = %w[bundle exec moots]
+      command.push("--config", @config_path) if @config_path
+      command + ["--mutation", mutation.id(root: @root)]
+    end
+
+    def survivor(mutation)
+      @progress.puts("  Expression diff:")
+      text(mutation.original_code).each_line { |line| @progress.puts("  - #{line.chomp}") }
+      text(mutation.mutated_code).each_line { |line| @progress.puts("  + #{line.chomp}") }
+      @progress.puts("  Rerun argv: #{JSON.generate(rerun(mutation))}")
+    end
+
+    def summary
+      completed = @results.compact
+      killed = completed.count(&:killed)
+      { mutations: completed.size, killed: killed, survived: completed.size - killed }
+    end
+
+    def document(status)
+      serialized = @results.compact.map { |result| serialize(result) }
+      { schema_version: 1, status: status, summary: summary, results: serialized }
+    end
+
+    def serialize(result)
+      mutation = result.mutation
+      {
+        id: mutation.id(root: @root), file: text(mutation.relative_path(root: @root)),
+        line: mutation.line_number, start_offset: mutation.start_offset,
+        original: text(mutation.original_code), mutated: text(mutation.mutated_code),
+        status: result.killed ? "killed" : "survived", test_output: text(result.test_result.output),
+        rerun: rerun(mutation)
+      }
+    end
+  end
+end

data/lib/moots/test_result.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Moots
+  # The exit status and combined output of one test command.
+  class TestResult
+    attr_reader :output
+
+    def initialize(success:, output:)
+      @success = success
+      @output = output
+    end
+
+    def success?
+      @success
+    end
+  end
+end

data/lib/moots/test_runner.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+require_relative "error"
+require_relative "test_result"
+
+module Moots
+  # Execute suites with a deadline and concurrently drain both output streams.
+  class TestRunner
+    def initialize(chdir: Dir.pwd, env: {})
+      @directory = chdir
+      @environment = env
+    end
+
+    def run_tests(command, timeout: 60)
+      options = Gem.win_platform? ? { new_pgroup: true } : { pgroup: true }
+      Open3.popen3(@environment, *Array(command), chdir: @directory, **options) do |stdin, stdout, stderr, process|
+        stdin.close
+        readers = [stdout, stderr].map { |stream| Thread.new { stream.read } }
+        completed = false
+        begin
+          result = Timeout.timeout(timeout) do
+            status = process.value
+            output = readers.map(&:value).reject(&:empty?).join("\n").strip
+            raise Error, "Test command terminated by signal #{status.termsig}" if status.signaled?
+            if [126, 127].include?(status.exitstatus)
+              raise Error, "Test command could not execute (exit #{status.exitstatus}): #{output}"
+            end
+
+            TestResult.new(success: status.success?, output: output)
+          end
+          completed = true
+          result
+        ensure
+          terminate(process.pid) unless completed
+          readers.each(&:kill) unless completed
+          readers.each(&:join)
+        end
+      end
+    rescue Timeout::Error
+      raise Error, "Test command timed out after #{timeout} seconds"
+    rescue SystemCallError => e
+      raise Error, "Cannot execute test command: #{e.message}"
+    end
+
+    private
+
+    def terminate(pid)
+      if Gem.win_platform?
+        system("taskkill", "/PID", pid.to_s, "/T", "/F", out: File::NULL, err: File::NULL)
+      else
+        Process.kill("KILL", -pid)
+      end
+    rescue Errno::ESRCH
+      # The process may have exited between the timeout and the kill.
+      nil
+    end
+  end
+end

data/lib/moots/version.rb

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

data/lib/moots/worker_pool.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Moots
+  # Run work concurrently, but deliver callbacks and exceptions on the calling thread.
+  class WorkerPool
+    def initialize(workers, before:, after:)
+      @workers = workers
+      @before = before
+      @after = after
+    end
+
+    def map(items, &operation)
+      pending = Queue.new
+      items.each_with_index { |item, index| pending << [item, index] }
+      events = Queue.new
+      threads = []
+      begin
+        @workers.each { |worker| threads << start_worker(worker, pending, events, operation) }
+        results = collect(items.size, events)
+        threads.each(&:join)
+        results
+      ensure
+        threads.each(&:kill)
+        threads.each(&:join)
+      end
+    end
+
+    private
+
+    def take(queue)
+      queue.pop(true)
+    rescue ThreadError
+      nil
+    end
+
+    def start_worker(worker, pending, events, operation)
+      Thread.new do
+        while (entry = take(pending))
+          item, index = entry
+          ready = Queue.new
+          events << [:started, index, item, ready]
+          ready.pop
+          result = operation.call(worker, item)
+          events << [:finished, index, result]
+        end
+      # Relay every worker exception, including Interrupt, so the caller never waits forever.
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        events << [:failed, e]
+      end
+    end
+
+    def collect(total, events)
+      results = Array.new(total)
+      total.times do
+        index, value = next_result(events)
+        results[index] = value
+        @after.call(value, index)
+      end
+      results
+    end
+
+    def next_result(events)
+      loop do
+        type, index, value, ready = events.pop
+        if type == :started
+          @before.call(value, index)
+          ready << true
+        elsif type == :failed
+          raise index
+        else
+          return [index, value]
+        end
+      end
+    end
+  end
+end