moots 0.1.0

data/lib/moots/workspace.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "pathname"
+require_relative "error"
+require_relative "environment"
+
+module Moots
+  # A disposable snapshot of the current project, with paths mapped back for reports.
+  class Workspace
+    METADATA = %w[.git .hg .svn].freeze
+
+    attr_reader :directory
+
+    def initialize(isolation:, workspace_exclude:, root: Dir.pwd)
+      @root = File.realpath(root)
+      @directory = @root
+      @isolation = isolation
+      @exclude = workspace_exclude
+    end
+
+    def open
+      return yield self unless @isolation
+
+      if inside?(File.realpath(Dir.tmpdir))
+        raise Error, "Temporary directory must be outside the project for isolated runs"
+      end
+
+      Dir.mktmpdir("moots-workspace-") do |temporary|
+        @directory = File.realpath(temporary)
+        copy_directory(@root, @directory)
+        yield self
+      end
+    end
+
+    def files(patterns)
+      patterns.flat_map do |pattern|
+        absolute = File.expand_path(pattern, @root)
+        raise Error, "Source pattern escapes the project: #{pattern}" if @isolation && !inside?(absolute)
+
+        Dir.glob(rebase(absolute)).map { |path| selected_path(path) }
+      end.uniq.sort
+    end
+
+    def with_workers(count)
+      Dir.mktmpdir("moots-workers-") do |temporary|
+        directory = File.realpath(temporary)
+        workers = Array.new(count) do |index|
+          self.class.new(isolation: true, workspace_exclude: [], root: @directory)
+              .copy_to(File.join(directory, index.to_s))
+        end
+        yield workers
+      end
+    end
+
+    def original_path(path)
+      File.expand_path(Pathname.new(path).relative_path_from(Pathname.new(@directory)).to_s, @root)
+    end
+
+    def command(value)
+      return value unless value.is_a?(Array)
+
+      value.map { |argument| rebase(argument) }
+    end
+
+    def environment(source = ENV)
+      Environment.rebase(source) { |path| rebase(path) }
+    end
+
+    protected
+
+    def copy_to(destination)
+      @directory = destination
+      Dir.mkdir(destination)
+      copy_directory(@root, destination)
+      self
+    end
+
+    private
+
+    def inside?(path, root = @root)
+      path == root || path.start_with?("#{root}/")
+    end
+
+    def selected_path(path)
+      absolute = File.expand_path(path)
+      if @isolation && (!inside?(absolute, @directory) || File.realpath(absolute) != absolute)
+        raise Error, "Selected source escapes or links outside the working copy: #{path}"
+      end
+
+      absolute
+    end
+
+    def rebase(path)
+      return path unless Pathname.new(path).absolute?
+
+      absolute = File.exist?(path) ? File.realpath(path) : File.expand_path(path)
+      return path unless inside?(absolute)
+
+      File.expand_path(Pathname.new(absolute).relative_path_from(Pathname.new(@root)).to_s, @directory)
+    end
+
+    def excluded?(relative, name)
+      METADATA.include?(name) || @exclude.any? do |pattern|
+        File.fnmatch?(pattern, relative, File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB)
+      end
+    end
+
+    def copy_directory(source, destination)
+      Dir.children(source).each do |name|
+        path = File.join(source, name)
+        relative = Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s
+        next if excluded?(relative, name)
+
+        stat = File.lstat(path)
+        if stat.symlink? || File.realpath(path) != path
+          raise Error,
+                "Cannot isolate linked path #{relative}; exclude it with workspace_exclude or use isolation: false"
+        end
+
+        copy_entry(path, File.join(destination, name), stat)
+      end
+    end
+
+    def copy_entry(source, destination, stat)
+      if stat.directory?
+        Dir.mkdir(destination)
+        copy_directory(source, destination)
+      elsif stat.file?
+        FileUtils.copy_file(source, destination, true)
+      else
+        raise Error, "Cannot isolate special file #{source}; exclude it with workspace_exclude"
+      end
+    end
+  end
+end

data/lib/moots.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative "moots/version"
+require_relative "moots/configuration"
+require_relative "moots/mutation_generator"
+require_relative "moots/test_runner"
+require_relative "moots/workspace"
+require_relative "moots/worker_pool"
+
+# Mutation testing for Ruby projects with isolated test processes.
+module Moots
+  Result = Struct.new(:mutation, :killed, :test_result, keyword_init: true)
+
+  class << self
+    # Verify the baseline, then run each mutation in a disposable project snapshot.
+    def run(options = {}, &progress)
+      config = Configuration.new(options).to_h
+      emit(progress, :workspace_started) if config[:isolation]
+      Workspace.new(isolation: config[:isolation], workspace_exclude: config[:workspace_exclude]).open do |workspace|
+        execute(config.merge(test_command: workspace.command(config[:test_command])), workspace, progress)
+      end
+    end
+
+    private
+
+    def execute(config, workspace, progress)
+      runner = TestRunner.new(chdir: workspace.directory, env: workspace.environment)
+      verify_baseline(runner, config, progress)
+      targets = mutation_targets(config, workspace)
+      return run_parallel(targets, config, workspace, progress) if config[:jobs] > 1 && targets.size > 1
+
+      targets.each_with_index.map do |(file, code, mutation), index|
+        position = { index: index + 1, total: targets.size }
+        emit(progress, :mutation_started, **position, mutation: mutation)
+        test_result = test_mutation(file, code, mutation, runner, config)
+        result = Result.new(mutation: mutation, killed: !test_result.success?, test_result: test_result)
+        emit(progress, :mutation_finished, **position, result: result)
+        result
+      end
+    end
+
+    def run_parallel(targets, config, workspace, progress)
+      workspace.with_workers([config[:jobs], targets.size].min) do |copies|
+        workers = copies.map do |copy|
+          runner = TestRunner.new(chdir: copy.directory, env: copy.environment(workspace.environment))
+          [copy, runner, config.merge(test_command: copy.command(config[:test_command]))]
+        end
+        before = lambda do |target, index|
+          emit(progress, :mutation_started, index: index + 1, total: targets.size, mutation: target.last)
+        end
+        after = lambda do |result, index|
+          emit(progress, :mutation_finished, index: index + 1, total: targets.size, result: result)
+        end
+        WorkerPool.new(workers, before: before, after: after).map(targets) do |(copy, runner, options), target|
+          file, code, mutation = target
+          test_result = test_mutation(copy.command([file]).first, code, mutation, runner, options)
+          Result.new(mutation: mutation, killed: !test_result.success?, test_result: test_result)
+        end
+      end
+    end
+
+    def emit(progress, type, **payload)
+      progress&.call(type: type, **payload)
+    end
+
+    def verify_baseline(runner, config, progress)
+      emit(progress, :baseline_started)
+      baseline = runner.run_tests(config[:test_command], timeout: config[:timeout])
+      raise Error, "Baseline tests failed; no mutations applied.\n#{baseline.output}" unless baseline.success?
+
+      emit(progress, :baseline_passed)
+    end
+
+    def mutation_targets(config, workspace)
+      generator = MutationGenerator.new
+      targets = find_files(config, workspace).flat_map do |file|
+        code = File.binread(file)
+        generator.generate_mutations(code, file_path: workspace.original_path(file)).map do |mutation|
+          [file, code, mutation]
+        end
+      end
+      return targets unless config[:mutation]
+
+      selected = targets.select { |_file, _code, mutation| mutation.id == config[:mutation] }
+      if selected.empty?
+        raise Error,
+              "No mutation matches #{config[:mutation]}; source or configuration may have changed."
+      end
+
+      selected
+    end
+
+    def find_files(config, workspace)
+      included = workspace.files(config[:include])
+      excluded = workspace.files(config[:exclude])
+      included.reject do |path|
+        excluded.include?(path) || !File.file?(path)
+      end
+    end
+
+    def test_mutation(file, code, mutation, runner, config)
+      mutated_code = mutation.apply(code)
+      begin
+        File.binwrite(file, mutated_code)
+        runner.run_tests(config[:test_command], timeout: config[:timeout])
+      ensure
+        File.binwrite(file, code)
+      end
+    end
+  end
+end

data/sig/moots.rbs

@@ -0,0 +1,4 @@
+module Moots
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: moots
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dave Russell
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+email:
+- dave.kerr@gmail.com
+executables:
+- moots
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- docs/isolation.md
+- docs/reporting.md
+- exe/moots
+- lib/moots.rb
+- lib/moots/cli.rb
+- lib/moots/configuration.rb
+- lib/moots/environment.rb
+- lib/moots/error.rb
+- lib/moots/mutation.rb
+- lib/moots/mutation_generator.rb
+- lib/moots/reporter.rb
+- lib/moots/test_result.rb
+- lib/moots/test_runner.rb
+- lib/moots/version.rb
+- lib/moots/worker_pool.rb
+- lib/moots/workspace.rb
+- sig/moots.rbs
+homepage: https://github.com/OkayDave/moots
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/OkayDave/moots
+  source_code_uri: https://github.com/OkayDave/moots
+  changelog_uri: https://github.com/OkayDave/moots/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Moots is a simple tool to provide mutation testing for Ruby
+test_files: []