kimera 0.1.0

data/lib/kimera/cli/survivors/panel.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../../support/duration"
+
+class Kimera::CLI::Survivors::Panel
+  def initialize(io: $stdout)
+    @io = io
+  end
+
+  def announce(matching, options)
+    @io.puts("#{matching.size} #{options[:status]} mutant(s):")
+    sorted(matching).each { |row| entry(row) }
+    @io.puts
+    @io.puts("detail: kimera mutant <N> --report #{options[:report]}")
+  end
+
+  def describe(row)
+    header(row)
+    diff(row, "  ")
+    extra(row)
+    tests("covering tests", row["covering_tests"])
+    tests("failing tests", row["failing_tests"])
+  end
+
+  private
+
+  def entry(row)
+    @io.puts
+    brief(row)
+  end
+
+  def sorted(matching)
+    matching.sort_by { |file, line,| [file, line] }.map { |_, _, row| row }
+  end
+
+  def header(row)
+    @io.puts("##{row["mutant_id"]}  #{row["status"]}  #{location(row)}")
+    field("operator: ", row["operator"])
+    field("label:    ", row["label"])
+  end
+
+  def extra(row)
+    seconds = row["duration"]
+    @io.puts("  duration: #{Kimera::Duration.new(seconds).brief}") if seconds&.positive?
+    field("detail:   ", row["detail"])
+  end
+
+  def field(prefix, value)
+    @io.puts("  #{prefix}#{value}") if value
+  end
+
+  def brief(row)
+    @io.puts("  ##{row["mutant_id"]}  #{location(row)}  [#{row["label"]}]")
+    diff(row, "    ")
+    covering = Array(row["covering_tests"])
+    @io.puts("    covered by #{covering.size} test(s)") unless covering.empty?
+  end
+
+  def diff(row, indent)
+    source(row["original"], "-", indent)
+    mutated = row["mutated"]
+    source(mutated, "+", indent) if mutated
+  end
+
+  def source(code, sign, indent)
+    first, *rest = code.to_s.split("\n")
+    @io.puts("#{indent}#{sign} #{first}")
+    rest.each { |line| @io.puts("#{indent}  #{line}") }
+  end
+
+  def tests(title, items)
+    items = Array(items)
+    return if items.empty?
+    @io.puts("  #{title} (#{items.size}):")
+    items.each { |test| @io.puts("    #{test}") }
+  end
+
+  def location(row)
+    [row["file"], row["line"]].compact.join(":")
+  end
+end

data/lib/kimera/cli/survivors.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../error"
+require_relative "flag"
+require_relative "report_file"
+
+class Kimera::CLI::Survivors
+  OPTIONS = Kimera::FlagTable.new(
+    banner: "Usage: kimera survivors REPORT.json [options] [FILE_SUBSTRING]\n" \
+      "Lists a report's surviving mutants; FILE_SUBSTRING keeps only " \
+      "mutants whose file path contains it (e.g. models/discount).",
+    flags: [
+      Kimera::Flag.build("--id N", :id, "Show one mutant in full detail", type: Integer),
+      Kimera::Flag.build(
+        "--status NAME", :status,
+        "List a different status (survived, no_coverage, " \
+          "timeout, error, killed, isolated_only)"
+      )
+    ]
+  )
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    attempt(argv)
+  rescue Kimera::UsageError => error
+    @errors.puts("kimera: #{error.message}")
+    1
+  end
+
+  private
+
+  def attempt(argv)
+    options = parse(argv)
+    results = load(options[:report]).fetch("results", [])
+    id = options[:id]
+    id ? show(results, id) : list(results, options)
+  end
+
+  def parse(argv)
+    options = { status: "survived", id: nil }
+    report, filter = OPTIONS.parse(argv, options)
+    raise(Kimera::UsageError, "survivors: a report file is required (run with --report FILE first)") unless report
+    options.merge(report: report, filter: filter)
+  end
+
+  def load(path)
+    raise(Kimera::UsageError, "no such report: #{path}") unless File.file?(path)
+    Kimera::CLI::ReportFile.parse(path)
+  end
+
+  def list(results, options)
+    matching = matches(results, options)
+    return none(options) if matching.empty?
+    Panel.new(io: @io).announce(matching, options)
+    0
+  end
+
+  def matches(results, options)
+    status = options[:status]
+    filter = options[:filter]
+    found = results.select { |row| row["status"] == status }.map { |row| [row["file"].to_s, row["line"] || 0, row] }
+    filter ? found.select { |file,| file.include?(filter) } : found
+  end
+
+  def none(options)
+    filter = options[:filter]
+    @io.puts("no #{options[:status]} mutants#{" matching #{filter}" if filter}")
+    0
+  end
+
+  def show(results, id)
+    row = results.find { |candidate| candidate["mutant_id"] == id }
+    return missing(id) unless row
+    Panel.new(io: @io).describe(row)
+    0
+  end
+
+  def missing(id)
+    @errors.puts("kimera: no mutant ##{id} in this report")
+    1
+  end
+end
+
+require_relative "survivors/panel"

data/lib/kimera/cli/synthesize.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../operators"
+require_relative "../registry/builder"
+require_relative "../scope/config"
+require_relative "../scope/file_set"
+require_relative "../synthesis/project"
+require_relative "flag"
+
+module Kimera
+end
+
+class Kimera::CLI
+end
+
+class Kimera::CLI::Synthesize
+  OPTIONS = Kimera::FlagTable.new(
+    banner: "Usage: kimera synthesize [paths...] [options]",
+    flags: [
+      Kimera::Flag.build("--out DIR", :out, "Write synthesized mirror tree to DIR"),
+      Kimera::REGISTRY_FLAG,
+      Kimera::OPERATORS_FLAG,
+      Kimera::CONFIG_FLAG
+    ]
+  )
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    options = Kimera::Config.scope({ out: nil, registry: nil, operators: Kimera::Operators::DEFAULT_KEYS }, argv)
+    paths = OPTIONS.parse(argv, options)
+    out = options[:out]
+    out ? synthesize(paths, options, out) : missing
+  end
+
+  private
+
+  def missing
+    @errors.puts("kimera synthesize: --out DIR is required")
+    1
+  end
+
+  def synthesize(paths, options, out)
+    registry = load(paths, options)
+    report(registry, Kimera::Synthesis::Project.new(registry).write(out), out)
+    0
+  end
+
+  def report(registry, manifest, out)
+    @io.puts("Synthesized #{registry.files.size} files to #{out}.")
+    @io.puts("  #{manifest.mutant_files.size} mutants on the schema path.")
+    unsafe = manifest.unsafe_mutants
+    @io.puts("  #{unsafe.size} mutants routed to reload fallback (memoization).") unless unsafe.empty?
+  end
+
+  def load(paths, options)
+    stored = options[:registry]
+    return Kimera::Registry.load(stored) if stored
+    Kimera::RegistryScan.new(operators: Kimera::Operators.build(keys: options[:operators]))
+      .build(Kimera::FileSet.scoped(paths, options))
+  end
+end

data/lib/kimera/cli/workflows.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "init"
+require_relative "doctor"
+require_relative "changed"
+require_relative "ci"
+require_relative "completion"
+require_relative "skill"

data/lib/kimera/cli.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "cli/flag"
+require_relative "cli/help_text"
+require_relative "cli/suggestion"
+require_relative "operators"
+require_relative "registry/builder"
+require_relative "scope/config"
+require_relative "scope/file_set"
+require_relative "version"
+
+class Kimera::CLI
+  REGISTRY_OPTIONS = Kimera::FlagTable.new(
+    banner: "Usage: kimera registry [paths...] [options]",
+    flags: [
+      Kimera::Flag.build(["-o", "--output FILE"], :output, "Write registry JSON to FILE"),
+      Kimera::OPERATORS_FLAG,
+      Kimera::CONFIG_FLAG,
+      Kimera::Flag.build("--json", :json, "Print registry JSON to stdout"),
+      Kimera::Flag.build(["-q", "--quiet"], :quiet, "Suppress the summary line")
+    ]
+  )
+
+  COMMANDS = { "registry" => :registry, "dump" => :registry, "synthesize" => :synthesize }
+    .merge("run" => :execute, "survivors" => :survivors, "report" => :report, "mutant" => :mutant)
+    .merge("init" => :init, "doctor" => :doctor, "changed" => :changed, "ci" => :ci, "completion" => :completion)
+    .merge("baseline" => :baseline, "skill" => :skill, "version" => :version)
+    .merge("-v" => :version, "--version" => :version, "help" => :help)
+    .merge("-h" => :help, "--help" => :help)
+    .freeze
+  private_constant(:COMMANDS)
+
+  COMMAND_NAMES = COMMANDS.keys.grep_v(/\A-/).freeze
+
+  class << self
+    def start(argv)
+      new.run(argv)
+    end
+  end
+
+  def initialize(io: $stdout, errors: $stderr)
+    @io = io
+    @errors = errors
+  end
+
+  def run(argv)
+    dispatch(argv.dup)
+  rescue Kimera::UsageError => error
+    @errors.puts("kimera: #{error.message}")
+    1
+  end
+
+  private
+
+  def dispatch(argv)
+    command = argv.shift || "help"
+    handler = COMMANDS[command]
+    return unknown(command, argv) unless handler
+    __send__(handler, argv)
+  end
+
+  def unknown(command, argv)
+    hint = Kimera::CLI::Suggestion.new(COMMAND_NAMES).hint(command)
+    @errors.puts("kimera: unknown command #{command.inspect}#{hint}\nTry: kimera help")
+    dispatch(["help", *argv])
+    1
+  end
+
+  def registry(argv)
+    options = Kimera::Config.scope({ output: nil, operators: Kimera::Operators::DEFAULT_KEYS, quiet: false }, argv)
+    paths = REGISTRY_OPTIONS.parse(argv, options)
+    files = Kimera::FileSet.scoped(paths, options)
+    return missing(paths, options) if files.empty?
+    build(files, options)
+  end
+
+  def missing(paths, options)
+    @errors.puts("kimera: no Ruby files matched #{Kimera::FileSet.globs(paths, options).join(", ")}")
+    1
+  end
+
+  def build(files, options)
+    emit(scan(options).build(files), options)
+  end
+
+  def scan(options)
+    Kimera::RegistryScan.new(operators: Kimera::Operators.build(keys: options[:operators]))
+  end
+
+  def emit(built, options)
+    out, json = options.values_at(:output, :json)
+    built.write(out) if out
+    @io.puts(built.to_json) if json
+    announce(built, out) unless options[:quiet] || json
+    0
+  end
+
+  def announce(built, out)
+    @io.puts(built.summary)
+    @io.puts("Wrote registry to #{out}") if out
+  end
+
+  def version(*)
+    @io.puts("kimera #{Kimera::VERSION}")
+    0
+  end
+
+  def help(*)
+    @io.puts(Kimera::HelpText::HELP)
+    0
+  end
+
+  def synthesize(argv) = delegate("synthesize", :Synthesize, argv)
+  def execute(argv) = delegate("run", :Run, argv)
+  def survivors(argv) = delegate("survivors", :Survivors, argv)
+  def report(argv) = delegate("survivors", :Survivors, argv)
+  def mutant(argv) = delegate("mutant", :Mutant, argv)
+  def baseline(argv) = delegate("baseline", :Baseline, argv)
+  def init(argv) = workflow(:Init, argv)
+  def doctor(argv) = workflow(:Doctor, argv)
+  def changed(argv) = workflow(:Changed, argv)
+  def ci(argv) = workflow(:CI, argv)
+  def completion(argv) = workflow(:Completion, argv)
+  def skill(argv) = workflow(:Skill, argv)
+  def workflow(name, argv) = delegate("workflows", name, argv)
+
+  def delegate(file, name, argv)
+    require_relative("cli/#{file}")
+    Kimera::CLI.const_get(name).new(io: @io, errors: @errors).run(argv)
+  end
+end

data/lib/kimera/error.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "support/errors"

data/lib/kimera/execution/baseline_failure.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Kimera
+  module Execution
+  end
+end
+
+class Kimera::Execution::BaselineFailure < Kimera::Error
+  MAX_DETAILS = 3
+  MAX_MESSAGE = 300
+
+  class << self
+    def build(failed, messages)
+      new(summary(failed, messages))
+    end
+
+    def summary(failed, messages)
+      text = "baseline suite is not green: #{failed.join(", ")}"
+      text += appendix(failed, messages)
+      "#{text}\n#{reproduce(failed)}"
+    end
+
+    def appendix(failed, messages)
+      items = details(failed, messages)
+      items.empty? ? "" : "\n#{items.join("\n")}"
+    end
+
+    def details(failed, messages)
+      failed.first(MAX_DETAILS).filter_map { |id| detail(id, messages[id]) }
+    end
+
+    def detail(id, message)
+      return unless message
+      "  #{id}:\n    #{truncate(message).gsub("\n", "\n    ")}"
+    end
+
+    def truncate(text)
+      text.length > MAX_MESSAGE ? "#{text[0, MAX_MESSAGE]}…" : text
+    end
+
+    def reproduce(failed)
+      "  reproduce without kimera: rspec #{failed.first(MAX_DETAILS).join(" ")} --order defined"
+    end
+  end
+end

data/lib/kimera/execution/baseline_pass.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../error"
+require_relative "../runtime"
+require_relative "baseline_failure"
+require_relative "null_progress"
+
+class Kimera::Execution::BaselinePass
+  Measured = Struct.new(:coverage, :irrelevant, keyword_init: true)
+  Tally = Struct.new(:coverage, :failures, :irrelevant)
+
+  def initialize(adapter:, registry:, progress: Kimera::Execution::NullProgress)
+    @adapter = adapter
+    @registry = registry
+    @progress = progress
+    @messages = {}
+  end
+
+  def measure!
+    settle { serial }
+  end
+
+  def parallel!(&)
+    settle { dispatch(&) }
+  end
+
+  def check!
+    Kimera::Runtime.active = nil
+    outcome = quietly { @adapter.run(@adapter.test_ids) }
+    return if outcome.passed?
+    @messages = outcome.failures
+    failure!(outcome.failed_ids)
+  end
+
+  private
+
+  def settle
+    @progress.start(@adapter.test_ids.size, "baseline")
+    yield
+    report
+  ensure
+    @progress.finish
+  end
+
+  def tally = @_tally ||= Tally.new(Hash.new { |h, k| h[k] = [] }, [], [])
+
+  def report
+    failures = tally.failures
+    failure!(failures) unless failures.empty?
+    Measured.new(coverage: tally.coverage, irrelevant: tally.irrelevant)
+  end
+
+  def serial
+    ledger = Kimera::Runtime.start!
+    @adapter.test_ids.each { |test_id| attempt(ledger, test_id) }
+  ensure
+    Kimera::Runtime.stop!(ledger)
+  end
+
+  def attempt(ledger, test_id)
+    Kimera::Runtime.active = nil
+    Kimera::Runtime.clear!(ledger)
+    record(test_id, quietly { @adapter.run([test_id]) }, Kimera::Runtime.drain!(ledger))
+  end
+
+  def record(test_id, outcome, touched)
+    touched.each { |id| tally.coverage[id] << test_id }
+    bank(test_id, touched, message: outcome.failures[test_id]) unless outcome.passed?
+    @progress.tick
+  end
+
+  def dispatch
+    yield(resolve: resolve, lost: loss)
+  end
+
+  def resolve
+    ->(message) { receive(message) }
+  end
+
+  def receive(message)
+    touched = message["touched"]
+    test_id = message["id"]
+    touched.each { |id| tally.coverage[id] << test_id }
+    bank(test_id, touched, message: message["failure"]) unless message["passed"]
+    @progress.tick
+  end
+
+  def loss
+    method(:lost)
+  end
+
+  def lost(test_id, _reason)
+    tally.failures << test_id
+    @progress.tick
+  end
+
+  def bank(test_id, touched, message: nil)
+    @messages[test_id] = message
+    bucket(touched) << test_id
+  end
+
+  def bucket(touched)
+    Array(touched).any? { |id| @registry.index.key?(id) } ? tally.failures : tally.irrelevant
+  end
+
+  def quietly
+    swap = [$stdout, $stderr]
+    silence
+    yield
+  ensure
+    $stdout, $stderr = swap
+  end
+
+  def silence
+    $stdout = StringIO.new
+    $stderr = StringIO.new
+  end
+
+  def failure!(failed)
+    raise(Kimera::Execution::BaselineFailure.build(failed, @messages))
+  end
+end

data/lib/kimera/execution/boot.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "isolation"
+
+class Kimera::Execution::Boot
+  def initialize(adapter:, isolate:, errors: nil)
+    @adapter = adapter
+    @isolate = isolate
+    @errors = errors
+  end
+
+  def suite(test_files)
+    @adapter.source(test_files)
+    @adapter.start
+    load!
+  end
+
+  def load!
+    loader&.call
+  rescue StandardError => error
+    (@errors || $stderr).puts(failure(error))
+  end
+
+  def isolate(isolation)
+    return isolation unless @isolate
+    return isolation unless defined?(ActiveRecord::Base)
+    Kimera::Execution::CompositeIsolation.new(
+      [Kimera::Execution::TransactionIsolation.new(ActiveRecord::Base), isolation]
+    )
+  end
+
+  private
+
+  def application
+    Rails.application
+  rescue NameError
+    nil
+  end
+
+  def loader
+    application&.method(:eager_load!)
+  rescue NameError
+    nil
+  end
+
+  def failure(error)
+    "kimera: eager_load! failed (#{error.class}: #{error.message}); " \
+      "lazily-autoloaded files may escape mutation"
+  end
+end

data/lib/kimera/execution/callback.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Kimera
+  module Execution
+  end
+end
+
+class Kimera::Execution::Callback
+  def initialize(filter)
+    @filter = filter
+  end
+
+  def duplicate?(existing)
+    case @filter
+    when Proc then sourced?(existing)
+    when Symbol, String then existing == @filter
+    else alike?(existing)
+    end
+  end
+
+  private
+
+  def sourced?(existing)
+    existing.is_a?(Proc) && existing.source_location&.first == @filter.source_location&.first
+  end
+
+  def alike?(existing)
+    kind = @filter.class
+    return false unless existing.instance_of?(kind)
+    return true unless kind.method_defined?(:attributes)
+    existing.attributes == @filter.attributes
+  end
+end

data/lib/kimera/execution/child_process.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "english"
+require "json"
+
+module Kimera
+  module Execution
+    module ChildProcess
+      private
+
+      def silence!
+        STDOUT.reopen(File::NULL, "w")
+        STDERR.reopen(File::NULL, "w")
+        $stdout = STDOUT
+        $stderr = STDERR
+      end
+
+      def kill(pid)
+        Process.kill("KILL", pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def reap(pid)
+        Process.wait(pid)
+        $CHILD_STATUS
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def shut(io)
+        io.close
+      rescue IOError
+        nil
+      end
+
+      def parse(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end