jitcatch 0.1.0

data/lib/jitcatch/cli.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module JitCatch
+  class CLI
+    def self.start(argv, finished_in_time: nil)
+      new(argv, finished_in_time: finished_in_time).run
+    rescue UsageError => err
+      warn "jitcatch: #{err.message}"
+      1
+    rescue GitError => err
+      warn "jitcatch: #{err.message}"
+      2
+    end
+
+    def initialize(argv, finished_in_time: nil)
+      @argv = argv
+      @finished_in_time = finished_in_time
+    end
+
+    def run
+      if @argv.empty? || %w[-h --help help].include?(@argv.first)
+        $stdout.write(help_text)
+        return 0
+      end
+      if %w[-v --version].include?(@argv.first)
+        $stdout.write(version_line)
+        return 0
+      end
+
+      case @argv.first
+      when "context" then command_context(@argv.drop(1))
+      when "run" then command_run(@argv.drop(1))
+      when "assess" then command_assess(@argv.drop(1))
+      else
+        raise UsageError, "unknown command: #{@argv.first}\n\n#{help_text}"
+      end
+    end
+
+    private
+
+    # A copy run from its own git checkout, as a gem installed from git
+    # is, names its commit, so a quoted output can say which code wrote it.
+    # A copy inside another project's checkout names none.
+    def version_line
+      root = File.expand_path("../..", __dir__)
+      sha = File.exist?(File.join(root, ".git")) ? IO.popen(["git", "-C", root, "rev-parse", "--short", "HEAD"], err: File::NULL, &:read).strip : ""
+      sha.empty? ? "jitcatch #{VERSION}\n" : "jitcatch #{VERSION} (#{sha})\n"
+    rescue SystemCallError
+      "jitcatch #{VERSION}\n"
+    end
+
+    def command_context(argv)
+      opts, positional = parse_options(argv, %i[repo coverage all_readers])
+      return write_help if opts[:help]
+      raise UsageError, "usage: jitcatch context BASE HEAD" unless positional.size == 2
+
+      doc = Changes.between(repo_at(opts), positional[0], positional[1], coverage: opts[:coverage], readers: true)
+      limit = opts[:all_readers] ? nil : Render::READERS_SHOWN
+      $stdout.write(opts[:json] ? Render.dump(Render.context_json(doc, readers_limit: limit)) : Render.context_text(doc, readers_limit: limit))
+      0
+    end
+
+    def command_run(argv)
+      opts, positional = parse_options(argv, %i[repo reruns timeout env workers serial number_database_url setup])
+      return write_help if opts[:help]
+      raise UsageError, "usage: jitcatch run BASE HEAD TESTS_DIR" unless positional.size == 3
+
+      raw = Runner.run(
+        repo_at(opts),
+        positional[0],
+        positional[1],
+        positional[2],
+        reruns: opts.fetch(:reruns, 2),
+        timeout: opts[:timeout],
+        env: opts.fetch(:env, []),
+        workers: opts.fetch(:workers, 1),
+        serial: opts.fetch(:serial, false),
+        number_database_url: opts.fetch(:number_database_url, false),
+        setup: opts[:setup],
+        finished_in_time: @finished_in_time
+      )
+      doc = Assessor.apply(raw)
+      $stdout.write(opts[:json] ? Render.dump(Render.run_json(doc)) : Render.run_text(doc))
+      Assessor.untested_run?(doc) ? 3 : 0
+    rescue EnvironmentError => err
+      # Every exit 3 is a report on stdout, so a caller reads one stream for it.
+      $stdout.write(opts[:json] ? Render.dump(err.doc) : Render.setup_failed_text(err.doc))
+      3
+    end
+
+    def command_assess(argv)
+      opts, positional = parse_options(argv, [])
+      return write_help if opts[:help]
+      raise UsageError, "usage: jitcatch assess RUN.json" unless positional.size == 1
+
+      path = positional[0]
+      raise UsageError, "run json not found: #{path}" unless File.file?(path)
+
+      raw = JSON.parse(File.read(path))
+      raise UsageError, "run json must be an object" unless raw.is_a?(Hash)
+      raise UsageError, "run json is a run that stopped on a setup failure, so it has no tests to assess" if raw["error"] == "setup_failed"
+
+      doc = Assessor.apply(raw)
+      $stdout.write(opts[:json] ? Render.dump(Render.assess_json(doc)) : Render.assess_text(doc))
+      0
+    rescue JSON::ParserError => err
+      raise UsageError, "run json is not JSON: #{err.message}"
+    end
+
+    def parse_options(argv, allowed)
+      opts = {}
+      positional = []
+      rest = argv.dup
+      while (arg = rest.shift)
+        if arg == "--help" || arg == "-h"
+          opts[:help] = true
+        elsif arg == "--json"
+          opts[:json] = true
+        elsif arg == "--all-readers" && allowed.include?(:all_readers)
+          opts[:all_readers] = true
+        elsif arg == "--serial" && allowed.include?(:serial)
+          opts[:serial] = true
+        elsif arg == "--number-database-url" && allowed.include?(:number_database_url)
+          opts[:number_database_url] = true
+        elsif arg.start_with?("--")
+          name = arg.delete_prefix("--").tr("-", "_").to_sym
+          raise UsageError, "unknown option: #{arg}" unless allowed.include?(name)
+
+          value = rest.shift
+          raise UsageError, "#{arg} requires a value" if value.nil? || value.start_with?("-")
+          next (opts[:env] ||= []) << env_option(arg, value) if name == :env
+
+          opts[name] = case name
+          when :reruns then integer_option(arg, value)
+          when :timeout, :workers then positive_option(arg, value)
+          else value
+          end
+        else
+          positional << arg
+        end
+      end
+      [opts, positional]
+    end
+
+    def integer_option(flag, value)
+      raise UsageError, "#{flag} requires an integer" unless value.match?(/\A\d+\z/)
+
+      value.to_i
+    end
+
+    def positive_option(flag, value)
+      number = integer_option(flag, value)
+      raise UsageError, "#{flag} must be >= 1" if number < 1
+
+      number
+    end
+
+    # A value on the command line would reach the run and no rerun line,
+    # which reads each name from the reader's shell, so --env takes a name.
+    def env_option(flag, value)
+      name = value[/\A([A-Za-z_][A-Za-z0-9_]*)=/, 1]
+      raise UsageError, "#{flag} takes a name and reads its value from your shell, as each rerun line does: run export #{name}=<value>, then pass #{flag} #{name}" if name
+      raise UsageError, "#{flag} needs a variable name, not #{value}" unless value.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+      raise UsageError, "#{flag} cannot pass #{value}: jitcatch sets it" if Runner::RESERVED_ENV.include?(value)
+
+      value
+    end
+
+    def repo_at(opts)
+      opts[:repo] || Dir.pwd
+    end
+
+    def write_help
+      $stdout.write(help_text)
+      0
+    end
+
+    def help_text
+      <<~HELP
+        jitcatch #{VERSION}
+
+        Deterministic Just-in-Time catching-test helper for Ruby.
+        This tool never calls an LLM. An agent writes the tests and judges intent.
+
+        Usage:
+          jitcatch context [--json] [--repo DIR] [--coverage FILE] [--all-readers] BASE HEAD
+          jitcatch run [--json] [--repo DIR] [--reruns N] [--timeout SEC] [--workers N | --serial] [--env NAME]... [--number-database-url] [--setup CMD] BASE HEAD TESTS_DIR
+          jitcatch assess [--json] RUN.json
+          jitcatch --version
+
+        context   Short brief of changed methods, old/new source, call sites, tests, and the code that reads
+                  each changed value without calling it by name.
+        run       Run each candidate file on base and head. Keep pass/fail, drop flakes.
+        assess    Re-apply the rule assessor to a run JSON file.
+
+        Exit status: 0 success, 1 usage error, 2 git error, 3 run tested nothing (setup or --setup failed, or
+        no row compared base with head and a row timed out or found no database or table).
+      HELP
+    end
+  end
+end

data/lib/jitcatch/diff_parser.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module JitCatch
+  # Parses `git diff --unified=0` text. Line numbers are 1-based, matching Prism.
+  module DiffParser
+    module_function
+
+    def parse(text)
+      files = []
+      current = nil
+      text.to_s.each_line do |raw|
+        line = raw.delete_suffix("\n")
+        if line.start_with?("diff --git ")
+          current = { "old_path" => nil, "new_path" => nil, "hunks" => [] }
+          files << current
+        elsif current && line.start_with?("--- ")
+          current["old_path"] = clean_path(line[4..])
+        elsif current && line.start_with?("+++ ")
+          current["new_path"] = clean_path(line[4..])
+        elsif current && (match = line.match(/\A@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/))
+          current["hunks"] << {
+            "old_start" => match[1].to_i,
+            "old_count" => (match[2] || "1").to_i,
+            "new_start" => match[3].to_i,
+            "new_count" => (match[4] || "1").to_i
+          }
+        end
+      end
+      files
+    end
+
+    def name_status(text)
+      text.to_s.lines.filter_map do |line|
+        status, path = line.strip.split("\t", 2)
+        next if path.nil? || path.empty?
+
+        { "status" => status[0], "file" => path }
+      end.sort_by { |entry| [entry["file"], entry["status"]] }
+    end
+
+    def clean_path(raw)
+      path = raw.to_s.strip
+      return nil if path == "/dev/null"
+
+      path.sub(%r{\A[ab]/}, "")
+    end
+
+    def overlaps?(start_line, end_line, hunks, side)
+      hunks.any? do |hunk|
+        count = hunk["#{side}_count"]
+        next false if count.zero?
+
+        hunk_start = hunk["#{side}_start"]
+        hunk_end = hunk_start + count - 1
+        start_line <= hunk_end && end_line >= hunk_start
+      end
+    end
+  end
+end

data/lib/jitcatch/factories.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module JitCatch
+  # Reads FactoryBot definitions as source, without loading them, so a test
+  # that calls `create(:loan)` can be traced to the class the factory
+  # builds. It does not know the app's inflections or any class a run
+  # computes: a factory whose class the source does not settle comes back
+  # with a reason and no class.
+  module Factories
+    # `builds` holds the classes its associations build, through their own
+    # associations too. `trait_builds` holds, by trait name, what a trait
+    # builds when a test names it.
+    Factory = Data.define(:name, :class_name, :file, :line, :reason, :builds, :trait_builds)
+    # One `factory` call as written. `outer` is the factory it nests in.
+    # `associations` names the factories it may build with: a bare name
+    # counts only when a factory of that name exists. `traits` holds the
+    # names of each trait's associations.
+    Written = Data.define(:names, :file, :line, :own_class, :parent, :outer, :reason, :associations, :traits)
+
+    # Calls in a factory block that define something other than an attribute.
+    DEFINITIONS = %i[factory trait transient sequence after before callback traits_for_enum initialize_with to_create skip_create].freeze
+
+    module_function
+
+    def file?(path)
+      path.match?(%r{(?:\A|/)(?:spec|test)/factories(?:\.rb\z|/.*\.rb\z)})
+    end
+
+    # A parent can be defined in another file, so every file is read before
+    # any class is settled.
+    def read(sources)
+      written = sources.sort.flat_map { |file, source| collect(Prism.parse(source).value, file, nil) }
+      by_name = written.flat_map { |item| item.names.map { |name| [name, item] } }.to_h
+      written.flat_map do |item|
+        class_name, reason = settle(item, by_name, [])
+        builds = classes_built(built_with(item, by_name, [item]), by_name)
+        trait_builds = traits_of(item, by_name, [item]).transform_values { |names|
+          classes_built(names.filter_map { |name| by_name[name] }.flat_map { |other| [other, *built_with(other, by_name, [other])] }, by_name)
+        }
+        names = item.names.empty? ? [nil] : item.names
+        names.map { |name| Factory.new(name: name, class_name: class_name, file: item.file, line: item.line, reason: reason, builds: builds, trait_builds: trait_builds) }
+      end
+    end
+
+    def classes_built(items, by_name)
+      items.filter_map { |other| settle(other, by_name, [])[0] }.uniq.sort
+    end
+
+    # A factory can use the traits of its parent and of the factory it
+    # nests in, and its own trait of the same name wins.
+    def traits_of(item, by_name, seen)
+      inherited = [item.outer, item.parent && by_name[item.parent]].compact.reject { |other| seen.include?(other) }
+      inherited.reverse.map { |other| traits_of(other, by_name, [*seen, other]) }.reduce({}, :merge).merge(item.traits).sort.to_h
+    end
+
+    def collect(node, file, outer)
+      if node.is_a?(Prism::CallNode) && node.name == :factory && node.receiver.nil?
+        item = written(node, file, outer)
+        return [item, *collect(node.block, file, item)]
+      end
+      return [] if node.nil?
+
+      node.compact_child_nodes.flat_map { |child| collect(child, file, outer) }
+    end
+
+    def written(node, file, outer)
+      first, *rest = Array(node.arguments&.arguments)
+      options = rest.grep(Prism::KeywordHashNode).flat_map(&:elements).grep(Prism::AssocNode)
+        .select { |pair| pair.key.is_a?(Prism::SymbolNode) }.to_h { |pair| [pair.key.unescaped, pair.value] }
+      name = literal(first)
+      reason = "its name is not a symbol or a string" unless name
+      own_class = class_named(options["class"]) if options.key?("class")
+      reason ||= "class: is not a constant, a string, or a symbol" if options.key?("class") && own_class.nil?
+      parent = options.key?("parent") ? literal(options["parent"]) : nil
+      reason ||= "parent: is not a symbol or a string" if options.key?("parent") && parent.nil?
+      aliases = options["aliases"].is_a?(Prism::ArrayNode) ? options["aliases"].elements.filter_map { |element| literal(element) } : []
+      Written.new(names: [name, *aliases].compact, file: file, line: node.location.start_line, own_class: own_class, parent: parent, outer: outer, reason: reason,
+        associations: associations_in(node.block), traits: traits_in(node.block))
+    end
+
+    def traits_in(block)
+      statements = block.is_a?(Prism::BlockNode) && block.body.is_a?(Prism::StatementsNode) ? block.body.body : []
+      statements.grep(Prism::CallNode).select { |call| call.receiver.nil? && call.name == :trait }.filter_map { |call|
+        name = literal(call.arguments&.arguments&.first)
+        [name, associations_in(call.block)] if name
+      }.to_h
+    end
+
+    # The statements of the factory's own block. A trait runs only when a
+    # test names it, and a nested factory is a factory of its own.
+    def associations_in(block)
+      statements = block.is_a?(Prism::BlockNode) && block.body.is_a?(Prism::StatementsNode) ? block.body.body : []
+      statements.grep(Prism::CallNode).flat_map do |call|
+        next [] unless call.receiver.nil? && !DEFINITIONS.include?(call.name)
+        next [association_name(call)].compact if call.name == :association
+        next [call.name.to_s] if call.arguments.nil? && call.block.nil?
+        next [] unless call.block.is_a?(Prism::BlockNode) && call.block.body.is_a?(Prism::StatementsNode)
+
+        call.block.body.body.grep(Prism::CallNode).select { |inner| inner.receiver.nil? && inner.name == :association }.filter_map { |inner| association_name(inner) }
+      end
+    end
+
+    # `association :author, factory: :user` builds from :user, and
+    # `factory: [:user, :admin]` from :user with a trait.
+    def association_name(call)
+      first, *rest = Array(call.arguments&.arguments)
+      factory = rest.grep(Prism::KeywordHashNode).flat_map(&:elements).grep(Prism::AssocNode)
+        .find { |pair| pair.key.is_a?(Prism::SymbolNode) && pair.key.unescaped == "factory" }&.value
+      factory = factory.elements.first if factory.is_a?(Prism::ArrayNode)
+      literal(factory) || literal(first)
+    end
+
+    # The factories an item builds with, its parent's and the one it nests
+    # in included, since a child factory inherits their attributes.
+    def built_with(item, by_name, seen)
+      inherited = [item.parent && by_name[item.parent], item.outer].compact
+      direct = item.associations.filter_map { |name| by_name[name] }
+      (direct + inherited).reject { |other| seen.include?(other) }.uniq.flat_map do |other|
+        reached = built_with(other, by_name, [*seen, other])
+        inherited.include?(other) ? reached : [other, *reached]
+      end
+    end
+
+    # FactoryBot takes a factory's class from its own `class:`, then from
+    # its parent (named by `parent:`, or the factory it nests in), then
+    # from its name.
+    def settle(item, by_name, seen)
+      return [nil, item.reason] if item.reason
+      return [item.own_class, nil] if item.own_class
+
+      if item.parent
+        parent = by_name[item.parent]
+        return [nil, "its parent :#{item.parent} is not a factory read here"] if parent.nil? || seen.include?(parent)
+
+        return settle(parent, by_name, [*seen, item])
+      end
+      return settle(item.outer, by_name, [*seen, item]) if item.outer
+
+      [camelize(item.names.first), nil]
+    end
+
+    # A string or a symbol that starts in upper case is a constant's name,
+    # and FactoryBot camelizes any other.
+    def class_named(node)
+      case node
+      when Prism::ConstantReadNode, Prism::ConstantPathNode
+        node.location.slice.delete(" ").delete_prefix("::")
+      when Prism::StringNode, Prism::SymbolNode
+        text = node.unescaped.delete_prefix("::")
+        text.match?(/\A[A-Z]/) ? text : camelize(text)
+      end
+    end
+
+    def literal(node)
+      node.unescaped if node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+    end
+
+    def camelize(name)
+      name.split("/").map { |part| part.split("_").map { |word| word.sub(/\A./) { |letter| letter.upcase } }.join }.join("::")
+    end
+  end
+end

data/lib/jitcatch/failure.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module JitCatch
+  # The result a parser gives each test, and the one it gives a file that
+  # fails before any test reports.
+  module Failure
+    module_function
+
+    FRAME = /^\s*(?:# )?(.+):(\d+):in [`']([^`']*)[`']/.freeze
+    # The runner writes this where a worktree root was, so a message still
+    # shows that a path stood there. Frames drop it to match the diff's paths.
+    WORKTREE = "{worktree}/"
+    # Where the runner copies the tests directory in each worktree.
+    TESTS_COPY = /#{Regexp.escape(WORKTREE)}\.jitcatch(?![\w.-])/.freeze
+    COPY_FRAME = %r{\A\.jitcatch/}.freeze
+    # Ruby names the file it was started on by the path it was given, so the
+    # error report of a file that fails to load starts a line with the copy's
+    # relative path. Elsewhere a relative path may be what a test compared.
+    COPY_PATH = %r{^(\s*(?:from )?)\.jitcatch/(?=\S+?:\d+:in )}.freeze
+    MESSAGE_LINES = 20
+    FRAMES = 15
+
+    # +cause+ is the error the failing one was raised from, when the
+    # framework printed it: {"error_class", "message"}.
+    def result(status, error_class, message, frames, cause: nil)
+      message = message.to_s.strip.lines.first(MESSAGE_LINES).join.rstrip
+      {
+        "status" => status,
+        "error_class" => error_class,
+        "message" => message,
+        "message_first_line" => first_line(message),
+        "backtrace" => frames.first(FRAMES),
+        "cause" => cause
+      }
+    end
+
+    # A test reads its own files from the copy, and the rerun line names
+    # +tests+, the tests directory from the repository root, so a message
+    # names it after the root, and a frame names it, where either named the
+    # copy. An absolute +tests+ is outside every worktree, so it stands alone.
+    def naming_tests(result, tests)
+      return nil if result.nil?
+
+      rooted = tests.start_with?("/") ? tests : "#{WORKTREE}#{tests}"
+      named = ->(text) { text.to_s.gsub(TESTS_COPY) { rooted }.gsub(COPY_PATH) { "#{$1}#{tests}/" } }
+      message = named.call(result["message"])
+      cause = result["cause"] && result["cause"].merge("message" => named.call(result["cause"]["message"]))
+      backtrace = Array(result["backtrace"]).map { |frame| frame.merge("file" => frame["file"].sub(COPY_FRAME) { "#{tests}/" }) }
+      result.merge("message" => message, "message_first_line" => first_line(message), "cause" => cause, "backtrace" => backtrace)
+    end
+
+    def passed(status)
+      result(status, nil, "", [])
+    end
+
+    def frame(file, line)
+      { "file" => file.delete_prefix(WORKTREE).delete_prefix("./"), "line" => line.to_i }
+    end
+
+    def frames_in(lines)
+      lines.filter_map { |line| (match = line.match(FRAME)) && frame(match[1], match[2]) }
+    end
+
+    # What a process printed when it stopped before its framework reported.
+    def from_streams(stdout, stderr)
+      text = stderr.strip
+      text = stdout.strip if text.empty?
+      return nil if text.empty?
+
+      error_class = if text.include?("LoadError") || text.include?("cannot load such file")
+        "LoadError"
+      elsif text.include?("SyntaxError") || text.include?("syntax error")
+        "SyntaxError"
+      elsif (match = text.match(/\(([A-Za-z0-9_:]+)\)\s*\z/))
+        match[1]
+      else
+        "RuntimeError"
+      end
+      result("error", error_class, text.lines.map(&:strip).reject(&:empty?).first, frames_in(text.lines))
+    end
+
+    def first_line(message)
+      message.to_s.lines.map(&:strip).reject(&:empty?).first.to_s[0, 180]
+    end
+  end
+end

data/lib/jitcatch/framework.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module JitCatch
+  # How a candidate file runs and how its output reads. A `*_spec.rb` file
+  # is RSpec unless it requires minitest (minitest/spec names files that way
+  # too); every other file is Minitest.
+  module Framework
+    MINITEST_REQUIRE = /^\s*require\s*\(?\s*["']minitest/.freeze
+    REPORT = ".jitcatch-report.json"
+
+    def self.for(relative, source)
+      RSpec.names?(File.basename(relative)) && !source.match?(MINITEST_REQUIRE) ? RSpec : Minitest
+    end
+
+    def self.named?(relative)
+      [Minitest, RSpec].any? { |framework| framework.names?(File.basename(relative)) }
+    end
+
+    module Minitest
+      module_function
+
+      BARE = /\A[\w.,:\/@\#{}=+-]+\z/
+
+      def names?(basename)
+        basename.match?(/\Atest_.+\.rb\z/) || basename.end_with?("_test.rb")
+      end
+
+      REPORTER = File.expand_path("minitest_report.rb", __dir__)
+
+      def arguments(path)
+        ["-r#{REPORTER}", path, "--seed", "1"]
+      end
+
+      def parse(report, stdout, stderr, normalizer)
+        MinitestParser.parse(report, stdout, stderr, normalizer: normalizer)
+      end
+
+      LIBRARY = "minitest"
+
+      # Minitest is a bundled gem, so under Bundler only a Gemfile that lists
+      # it can load it.
+      def missing(bundled)
+        bundled ? 'minitest is not in the bundle: add gem "minitest" to the Gemfile' : "minitest is not installed for this Ruby: gem install minitest"
+      end
+
+      def rerun(path, name, _line, pin_root: true, launcher: false)
+        ["ruby", "-Ilib", "-I.", path, *(["-n", name] if name)].map { |part| quote(part) }.join(" ")
+      end
+
+      # A word a shell reads as written stays bare, so a path and a
+      # `Class#test` name stay readable; any other word is single-quoted.
+      def quote(part)
+        return part if part.match?(BARE)
+
+        "'#{part.gsub("'", %q('\\\\''))}'"
+      end
+    end
+
+    module RSpec
+      module_function
+
+      # RSpec puts lib/ of the nearest directory that holds spec/ first on
+      # the load path, which under a Rails app's tmp/ is the app's lib/, not
+      # the checkout's. Pinning that directory to the working directory
+      # loads the checkout's lib/ in the run and in its rerun line alike.
+      # RSpec cuts an object it prints to 200 characters, which can cut
+      # the class and message a raise_error got out of the row.
+      PIN_ROOT = "RSpec::Core::RubyProject.instance_variable_set(:@project_root, Dir.pwd); "
+      LAUNCH = 'require "rspec/core"; require "rspec/support/object_formatter"; ' \
+               "#{PIN_ROOT}" \
+               "RSpec::Support::ObjectFormatter.default_instance.max_formatted_output_length = nil; exit(RSpec::Core::Runner.run(ARGV))"
+
+      def names?(basename)
+        basename.end_with?("_spec.rb")
+      end
+
+      # `--backtrace` keeps the gem frames that tell a gem's error apart.
+      # Formatters given here replace the ones a `.rspec` file names.
+      def arguments(path)
+        ["-e", LAUNCH, "--", "--format", "json", "--out", REPORT, "--seed", "1", "--backtrace", "--no-color", path]
+      end
+
+      def parse(report, stdout, stderr, normalizer)
+        RSpecParser.parse(report, stdout, stderr, normalizer: normalizer)
+      end
+
+      LIBRARY = "rspec/core"
+
+      def missing(bundled)
+        bundled ? 'rspec-core is not in the bundle: add gem "rspec" to the Gemfile' : "rspec-core is not installed for this Ruby: gem install rspec-core"
+      end
+
+      # What `rspec -r` loads to lift the cut, when head's Ruby can load it.
+      LAUNCHER = "jitcatch/rspec"
+
+      # The same load path and launch as the run, so the rerun loads what
+      # the row loaded. In a checkout that holds spec/ RSpec already takes
+      # the working directory as its root and adds its lib/, so the line
+      # needs no pin, the one part that sets rspec-core's private state, and
+      # is plain `rspec` when head's Ruby loads the launcher.
+      def rerun(path, _name, line, pin_root: true, launcher: false)
+        target = "#{path}#{":#{line}" if line}"
+        return ["rspec", "-I.", "-r", LAUNCHER, target].map { |part| Minitest.quote(part) }.join(" ") if launcher && !pin_root
+
+        launch = pin_root ? LAUNCH : LAUNCH.sub(PIN_ROOT, "")
+        ["ruby", "-Ilib", "-I.", "-e", launch, target].map { |part| Minitest.quote(part) }.join(" ")
+      end
+    end
+  end
+end