branchout 0.1.0

data/examples/arithmetic.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Arithmetic
+  # (3x + 7) % 1000 == 421 is true for x = 138.
+  # y == x + 5 then forces y = 143, and z == 7 is a third nested decision.
+  # x == 114514 && x == 0 is unsatisfiable; that arm stays uncovered.
+  def self.classify(x, y, z)
+    if (x * 3 + 7) % 1000 == 421
+      if y == x + 5
+        if z == 7
+          :hit
+        else
+          :need_z
+        end
+      else
+        :x_only
+      end
+    elsif x == 114514 && x == 0
+      :impossible
+    else
+      :miss
+    end
+  end
+end

data/examples/hidden_bug.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module HiddenBug
+  # ZeroDivisionError only when a > 10, b > 10, and a - b * 2 == 0.
+  def self.scale(a, b)
+    if a > 10 && b > 10
+      denom = a - (b * 2)
+      if denom < 50
+        1000 / denom
+      else
+        :large_gap
+      end
+    else
+      :out_of_range
+    end
+  end
+end

data/examples/inputs/arithmetic.json

@@ -0,0 +1,10 @@
+{
+  "meta": {"rounds": 3},
+  "inputs": [
+    {"args": [0, 0, 0]},
+    {"args": [138, 0, 0]},
+    {"args": [114514, 0, 0]},
+    {"args": [138, 143, 0]},
+    {"args": [138, 143, 7]}
+  ]
+}

data/examples/inputs/arithmetic.seed.json

@@ -0,0 +1,5 @@
+{
+  "inputs": [
+    {"args": [0, 0, 0]}
+  ]
+}

data/examples/inputs/hidden_bug.json

@@ -0,0 +1,9 @@
+{
+  "meta": {"rounds": 2},
+  "inputs": [
+    {"args": [0, 0]},
+    {"args": [11, 11]},
+    {"args": [100, 11]},
+    {"args": [24, 12]}
+  ]
+}

data/examples/inputs/hidden_bug.seed.json

@@ -0,0 +1,5 @@
+{
+  "inputs": [
+    {"args": [0, 0]}
+  ]
+}

data/examples/inputs/magic_value.json

@@ -0,0 +1,7 @@
+{
+  "meta": {"rounds": 1},
+  "inputs": [
+    {"args": [0]},
+    {"args": [114514]}
+  ]
+}

data/examples/inputs/magic_value.seed.json

@@ -0,0 +1,5 @@
+{
+  "inputs": [
+    {"args": [0]}
+  ]
+}

data/examples/inputs/version_parser.json

@@ -0,0 +1,11 @@
+{
+  "meta": {"rounds": 3},
+  "inputs": [
+    {"args": [""]},
+    {"args": ["0"]},
+    {"args": ["-"]},
+    {"args": ["0.0.0"]},
+    {"args": ["0-rc1"]},
+    {"args": ["0-beta1"]}
+  ]
+}

data/examples/inputs/version_parser.seed.json

@@ -0,0 +1,5 @@
+{
+  "inputs": [
+    {"args": [""]}
+  ]
+}

data/examples/magic_value.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module MagicValue
+  def self.classify(x)
+    if x == 114514
+      :magic
+    else
+      :ordinary
+    end
+  end
+end

data/examples/version_parser.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module VersionParser
+  def self.parse(text)
+    if text.empty?
+      :blank
+    elsif text.include?("-")
+      _version, tag = text.split("-", 2)
+      if tag.start_with?("rc")
+        :rc
+      elsif tag.start_with?("beta")
+        :beta
+      else
+        :pre
+      end
+    elsif release?(text)
+      :release
+    else
+      :other
+    end
+  end
+
+  def self.release?(text)
+    parts = text.split(".")
+    return false unless parts.length == 3
+
+    parts.all? { |part| part.match?(/\A[0-9]+\z/) }
+  end
+end

data/lib/branchout/canon.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Branchout
+  # Byte-stable JSON. Key order is sorted, floats have a fixed spelling,
+  # and non-ASCII is escaped so the bytes do not depend on a JSON mode flag.
+  module Canon
+    module_function
+
+    def json(obj)
+      case obj
+      when nil then "null"
+      when true then "true"
+      when false then "false"
+      when Integer then obj.to_s
+      when Float then format_float(obj)
+      when String then JSON.generate(obj, ascii_only: true)
+      when Symbol then JSON.generate(obj.to_s, ascii_only: true)
+      when Code then json({"ruby" => obj.source})
+      when Array
+        "[#{obj.map { |item| json(item) }.join(",")}]"
+      when Hash
+        pairs = obj.map { |key, value| [key.to_s, value] }.sort_by { |key, _| key }
+        "{#{pairs.map { |key, value| "#{json(key)}:#{json(value)}" }.join(",")}}"
+      else
+        raise Error, "cannot encode #{obj.class} as canonical JSON"
+      end
+    end
+
+    # Float#to_s is the shortest text that reads back as the same float in
+    # Ruby and in JSON. A fixed precision is not: %.16g printed 0.1 + 0.2 as
+    # 0.3, and the largest float as a number that parses to Infinity.
+    def format_float(value)
+      raise Error, "non-finite float" unless value.finite?
+      return "0.0" if value.zero?
+
+      value.to_s
+    end
+
+    def pretty(obj, indent = 0)
+      pad = "  " * indent
+      case obj
+      when Hash
+        return "{}" if obj.empty?
+
+        inner = obj.map do |key, value|
+          "#{"  " * (indent + 1)}#{json(key.to_s)}: #{pretty(value, indent + 1)}"
+        end
+        "{\n#{inner.join(",\n")}\n#{pad}}"
+      when Array
+        return "[]" if obj.empty?
+
+        inner = obj.map { |value| "#{"  " * (indent + 1)}#{pretty(value, indent + 1)}" }
+        "[\n#{inner.join(",\n")}\n#{pad}]"
+      else
+        json(obj)
+      end
+    end
+  end
+end

data/lib/branchout/cli.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Branchout
+  module CLI
+    HELP = <<~TEXT
+      branchout #{VERSION}
+
+      Usage:
+        branchout explore TARGET ENTRY [options]
+        branchout baselines TARGET ENTRY [options]
+
+      ENTRY is Const.method or Const#method. --entry ENTRY is accepted too.
+
+      The tool does not call an LLM. It executes the inputs you pass, plus
+      optional literal mutation and seeded random samples, and prints the
+      branch arms that are still uncovered.
+
+      Options:
+        --inputs PATH       JSON file of candidate inputs
+        --require PATH      load PATH, or a feature on -I or the load path, before TARGET (repeatable)
+        -I DIR              put DIR on the load path (repeatable)
+        --seed N            RNG seed (default 0)
+        --random N          random samples (default 16)
+        --mutate-cap N      literal-mutation budget (default 256)
+        --strategy LIST     comma list: inputs,mutate,random (default all)
+        --timeout SEC       per-input timeout (default 1)
+        --verbose           print the run settings and every arm in the text report
+        --json              print JSON on stdout instead of text
+        --json-out PATH     write JSON to a file
+        --md-out PATH       write the text report as Markdown
+        --emit-tests PATH   write characterization tests (explore only)
+        --format NAME       minitest or rspec (default minitest; _spec.rb infers rspec)
+        --pin-keys LIST     comma list of keys: a returned Hash pins only these keys
+        --require-by-name   emitted tests require the --require files and the target
+                            through the load path, named from the first -I directory or
+                            --require file's directory that holds each (with neither, the
+                            nearest lib directory above the target); a file none holds is
+                            required by path, and the test and stderr say so; on by
+                            default for a test under a .jitcatch directory
+        --help
+        --version
+    TEXT
+
+    module_function
+
+    def start(argv)
+      run(argv)
+    rescue Error => e
+      $stderr.puts "branchout: #{e.message}"
+      1
+    end
+
+    def run(argv)
+      args = argv.map(&:dup)
+      if args.empty? || args == ["--help"] || args == ["-h"]
+        puts HELP
+        return 0
+      end
+      if args == ["--version"] || args == ["-v"]
+        puts "branchout #{VERSION}"
+        return 0
+      end
+
+      command = args.shift
+      raise Error, "unknown command #{command.inspect}" unless %w[explore baselines].include?(command)
+
+      opts = {
+        seed: 0,
+        random: 16,
+        mutate_cap: 256,
+        timeout: 1,
+        strategies: Engine::STRATEGY_ORDER.dup,
+        json: false,
+        verbose: false,
+        inputs: nil,
+        entry: nil,
+        json_out: nil,
+        md_out: nil,
+        emit_tests: nil,
+        format: nil,
+        require_by_name: false,
+        pin_keys: [],
+        requires: [],
+        load_paths: []
+      }
+      positionals = []
+      until args.empty?
+        arg = args.shift
+        case arg
+        when "--inputs" then opts[:inputs] = take(args, arg)
+        when "--require" then opts[:requires] << take(args, arg)
+        when "-I" then opts[:load_paths] << take(args, arg)
+        when /\A-I(.+)/ then opts[:load_paths] << Regexp.last_match(1)
+        when "--seed" then opts[:seed] = parse_int(take(args, arg), "seed")
+        when "--random" then opts[:random] = parse_int(take(args, arg), "random")
+        when "--mutate-cap" then opts[:mutate_cap] = parse_int(take(args, arg), "mutate-cap")
+        when "--timeout" then opts[:timeout] = parse_timeout(take(args, arg))
+        when "--strategy" then opts[:strategies] = parse_strategies(take(args, arg))
+        when "--entry" then opts[:entry] = take(args, arg)
+        when "--json" then opts[:json] = true
+        when "--verbose" then opts[:verbose] = true
+        when "--json-out" then opts[:json_out] = take(args, arg)
+        when "--md-out" then opts[:md_out] = take(args, arg)
+        when "--emit-tests" then opts[:emit_tests] = take(args, arg)
+        when "--format" then opts[:format] = take(args, arg)
+        when "--require-by-name" then opts[:require_by_name] = true
+        when "--pin-keys" then opts[:pin_keys] = parse_keys(take(args, arg))
+        when "--help", "-h"
+          puts HELP
+          return 0
+        else
+          raise Error, "unknown option #{arg}" if arg.start_with?("-")
+
+          positionals << arg
+        end
+      end
+
+      target = positionals.shift
+      entry = opts[:entry] || positionals.shift
+      raise Error, "missing TARGET" unless target
+      raise Error, "missing ENTRY" unless entry
+      raise Error, "unexpected arguments: #{positionals.join(" ")}" unless positionals.empty?
+      raise Error, "seed must be >= 0" if opts[:seed].negative?
+      raise Error, "random count must be >= 0" if opts[:random].negative?
+      raise Error, "mutate-cap must be >= 0" if opts[:mutate_cap].negative?
+      if opts[:emit_tests] && command != "explore"
+        raise Error, "--emit-tests is only valid with explore"
+      end
+      raise Error, "--verbose is only valid with explore" if opts[:verbose] && command != "explore"
+      if opts[:verbose] && opts[:json]
+        raise Error, "--verbose is only valid with the text report; --json holds every arm and the run settings"
+      end
+      if opts[:require_by_name]
+        raise Error, "--require-by-name requires --emit-tests" unless opts[:emit_tests]
+      end
+      raise Error, "--pin-keys requires --emit-tests" if !opts[:pin_keys].empty? && !opts[:emit_tests]
+      if opts[:format] && !opts[:emit_tests]
+        raise Error, "--format requires --emit-tests"
+      end
+      if opts[:emit_tests]
+        opts[:format] = Emitters.resolve(opts[:format], opts[:emit_tests])
+        # jitcatch copies a test under .jitcatch/ to the root of each
+        # checkout, and its rerun line loads the test where it was written.
+        # A require_relative names a different file from each place.
+        opts[:require_by_name] ||= File.expand_path(opts[:emit_tests]).split("/").include?(".jitcatch")
+      end
+
+      user_inputs = []
+      type_overrides = nil
+      if opts[:inputs]
+        user_inputs, type_overrides = InputFile.load(opts[:inputs])
+        InputFile.quoted_strings(user_inputs).each { |line| $stderr.puts "branchout: #{line}" }
+      end
+
+      case command
+      when "explore"
+        result = Engine.explore(
+          target: target,
+          entry: entry,
+          user_inputs: user_inputs,
+          type_overrides: type_overrides,
+          seed: opts[:seed],
+          strategies: opts[:strategies],
+          random: opts[:random],
+          mutate_cap: opts[:mutate_cap],
+          timeout: opts[:timeout],
+          requires: opts[:requires],
+          load_paths: opts[:load_paths]
+        )
+        if result.repeated_inputs.positive?
+          $stderr.puts "branchout: #{result.repeated_inputs} of #{user_inputs.length} inputs repeat an earlier input, " \
+                       "so they did not run again."
+        end
+        if result.covered.empty? && result.frontier.empty? && !result.operators.empty?
+          $stderr.puts "branchout: #{entry} and the methods it calls in #{result.target} have no arm that branch coverage counts, " \
+                       "but it branches at the operators OPERATORS lists, and coverage does not see which side of " \
+                       "||, &&, ||=, or &&= ran. Give inputs that make each left side truthy and falsy. " \
+                       "--emit-tests still pins the return value or error of each input."
+        elsif result.covered.empty? && result.frontier.empty? && !Array(result.memos).empty?
+          memos = result.memos.map { |found| "`#{found.text}` at #{found.loc}" }
+          $stderr.puts "branchout: #{entry} and the methods it calls in #{result.target} have no arm that branch coverage counts, " \
+                       "and their only #{memos.one? ? "branch is the memo" : "branches are the memos"} #{memos.join(", ")}. " \
+                       "#{memos.one? ? "Its cached side runs" : "The cached side of each runs"} only on a second call on the same object, " \
+                       "which no input makes. Explore the methods #{memos.one? ? "its right side calls" : "their right sides call"} " \
+                       "(NOT COUNTED lists those in other files), and test #{memos.one? ? "the memo" : "each memo"} by hand: call the method twice on one object and check that the second call returns " \
+                       "the first value without running the right side again. " \
+                       "--emit-tests still pins the return value or error of each input."
+        elsif result.covered.empty? && result.frontier.empty?
+          $stderr.puts "branchout: #{entry} and the methods it calls in #{result.target} have no branches. " \
+                       "Only a bare call, a self. call, and a call on new are followed; target the method that branches. " \
+                       "--emit-tests still pins the return value or error of each input."
+        end
+        write_optional(opts[:json_out], Report.json(result, pin_keys: opts[:pin_keys]))
+        write_optional(opts[:md_out], Report.markdown(result))
+        if opts[:emit_tests]
+          parsed = Target.parse(target, entry, type_overrides: type_overrides)
+          format = Emitters.resolve(opts[:format], opts[:emit_tests])
+          warnings = Emitters.write(format, result, parsed, opts[:emit_tests], require_by_name: opts[:require_by_name],
+                                                                                pin_keys: opts[:pin_keys])
+          warnings.each { |line| $stderr.puts line }
+          warn_unnamed(result, target, opts[:emit_tests]) if opts[:require_by_name]
+        end
+        $stdout.write(opts[:json] ? Report.json(result, pin_keys: opts[:pin_keys]) : Report.text(result, tests: opts[:emit_tests], verbose: opts[:verbose], pin_keys: opts[:pin_keys]))
+      when "baselines"
+        info = {
+          target: Target.display_path(File.expand_path(target)),
+          entry: entry,
+          seed: opts[:seed],
+          random: opts[:random],
+          mutate_cap: opts[:mutate_cap],
+          timeout: opts[:timeout]
+        }
+        rows = [
+          ["random", run_strategy(target, entry, user_inputs, type_overrides, opts, ["random"])],
+          ["mutate", run_strategy(target, entry, user_inputs, type_overrides, opts, ["mutate"])],
+          ["agent", run_strategy(target, entry, user_inputs, type_overrides, opts, ["inputs"])]
+        ]
+        stdout = opts[:json] ? Report.baselines_json(info, rows) : Report.baselines_text(info, rows)
+        $stdout.write(stdout)
+        write_optional(opts[:json_out], Report.baselines_json(info, rows))
+        write_optional(opts[:md_out], Report.baselines_markdown(info, rows))
+      end
+      0
+    end
+
+    def run_strategy(target, entry, user_inputs, type_overrides, opts, strategies)
+      Engine.explore(
+        target: target,
+        entry: entry,
+        user_inputs: user_inputs,
+        type_overrides: type_overrides,
+        seed: opts[:seed],
+        strategies: strategies,
+        random: opts[:random],
+        mutate_cap: opts[:mutate_cap],
+        timeout: opts[:timeout],
+        command: "baselines",
+        requires: opts[:requires],
+        load_paths: opts[:load_paths]
+      )
+    end
+
+    # A file outside the test's project has had its warning from
+    # Emitters.write already.
+    def warn_unnamed(result, target, destination)
+      required = (target unless result.target_required)
+      unnamed = Emitters::Support.unnamed_requires(result.requires, required, load_paths: result.load_paths).map { |path| File.expand_path(path) } -
+                Emitters::Support.required_outside_project(result.requires, required, destination)
+      unnamed.each do |path|
+        $stderr.puts "branchout: #{Target.display_path(path)} is under no -I or --require directory, so the emitted test requires it by path. " \
+                     "Pass -I with a directory that holds it to require it by name."
+      end
+    end
+
+    def write_optional(path, content)
+      return unless path
+
+      FileUtils.mkdir_p(File.dirname(File.expand_path(path)))
+      File.write(path, content)
+    end
+
+    def take(args, flag)
+      value = args.shift
+      raise Error, "#{flag} needs a value" unless value
+
+      value
+    end
+
+    def parse_int(text, label)
+      Integer(text)
+    rescue ArgumentError
+      raise Error, "#{label} must be an integer"
+    end
+
+    def parse_timeout(text)
+      value = Float(text)
+      raise Error, "timeout must be > 0" unless value.positive?
+
+      value == value.to_i ? value.to_i : value
+    rescue ArgumentError
+      raise Error, "timeout must be a number"
+    end
+
+    def parse_keys(text)
+      keys = text.split(",").map(&:strip).reject(&:empty?)
+      raise Error, "--pin-keys list is empty" if keys.empty?
+
+      keys
+    end
+
+    def parse_strategies(text)
+      names = text.split(",").map(&:strip).reject(&:empty?)
+      unknown = names - Engine::STRATEGY_ORDER
+      raise Error, "unknown strategy #{unknown.join(", ")}" unless unknown.empty?
+      raise Error, "strategy list is empty" if names.empty?
+
+      Engine::STRATEGY_ORDER.select { |name| names.include?(name) }
+    end
+  end
+end

data/lib/branchout/coverage.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The test file that explores requires this file first, before its helper
+# loads the app, so that explore can count the arms of the app's files.
+# Requiring branchout itself does not start coverage: an app whose Gemfile
+# lists branchout without require: false loads it in every process.
+require_relative "coverage_session"
+
+Branchout::CoverageSession.install

data/lib/branchout/coverage_session.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "coverage"
+
+module Branchout
+  # Coverage counts a file's arms only when the file loads after Coverage
+  # was set up. Setup leaves measurement suspended: explore resumes it
+  # around each call.
+  module CoverageSession
+    LIB = File.join(File.expand_path("..", __dir__), "")
+
+    # Many suites start SimpleCov unconditionally at the top of a helper.
+    # From a helper that loads after the session, its Coverage.start would
+    # raise "coverage measurement is already setup", so the session keeps
+    # measuring, and the tool reads the session's result when it reports.
+    module LaterStart
+      def setup(...) = (super unless CoverageSession.installed?)
+
+      def start(...) = (super unless CoverageSession.installed?)
+    end
+
+    module_function
+
+    # Coverage that another tool started earlier measures lines only, so
+    # the session stops it and sets Coverage up again with branches.
+    def install
+      return if installed?
+
+      Coverage.result unless Coverage.state == :idle
+      Coverage.setup(lines: true, branches: true)
+      Coverage.singleton_class.prepend(LaterStart)
+      @installed = true
+    end
+
+    def installed? = @installed == true
+
+    # A file of branchout's own lib loads with the tool, so it has arms only
+    # when coverage was set up before the tool loaded. Only a run that names
+    # one sets it up that early: each call reads the coverage of every file
+    # loaded after setup, and the tool's own files made that 1.3 ms a call
+    # instead of 0.04 ms.
+    def names_own_file?(argv, from: Dir.pwd)
+      argv.any? do |arg|
+        path = File.expand_path(arg, from)
+        File.file?(path) && path.start_with?(LIB)
+      end
+    end
+  end
+end

data/lib/branchout/emitters/minitest.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Branchout
+  module Emitters
+    module Minitest
+      module_function
+
+      def render(result, target, destination, require_by_name: false, pin_keys: [], from: Dir.pwd, all_varied: false)
+        lines = Support.header(target, "tests", destination)
+        lines << ""
+        lines << 'require "minitest/autorun"'
+        lines.concat(Support.require_lines(result.requires, (target.path unless result.target_required), destination,
+                                          by_name: require_by_name, load_paths: result.load_paths, from: from))
+        lines << ""
+        lines << "class #{Support.class_name_for(target)} < #{result.test_class || "Minitest::Test"}"
+        if result.pins.empty?
+          lines << "  def #{all_varied ? "test_no_input_pinned" : "test_no_inputs_discovered"}"
+          lines << "    skip #{Support.no_pin_reason(all_varied).inspect}"
+          lines << "  end"
+        else
+          names = Support.test_names(result.pins, pin_keys)
+          result.pins.each_with_index do |pin, index|
+            lines << "" unless index.zero?
+            lines.concat(example_lines(target, pin, names[index], result.private_calls, pin_keys, result.const_expression || target.const_name))
+          end
+        end
+        lines << "end"
+        "#{lines.join("\n")}\n"
+      end
+
+      def example_lines(target, pin, name, private_calls, pin_keys, const = target.const_name)
+        lines = ["  def #{name}"]
+        lines.concat(Support.cover_comment(pin, "    "))
+        lines.concat(Support.thawed_comment(pin, "    "))
+        arrange, call = Support.arrange(target, pin.input, private_calls: private_calls, const: const, thawed: pin.thawed)
+        if pin.error
+          lines << "    error = assert_raises(#{pin.error.class_name}) do"
+          lines.concat(Support.indent(arrange + [call], "      "))
+          lines << "    end"
+          if pin.error.name
+            lines << "    assert_equal #{pin.error.name.inspect}, error.name"
+          elsif pin.error.stable_message
+            lines << "    assert_equal #{Support.ruby_literal(pin.error.exact_message || pin.error.message)}, error.message"
+          elsif pin.error.message_pattern
+            lines << "    assert_match(#{Regexp.new(pin.error.message_pattern).inspect}, error.message)"
+          end
+          return lines << "  end"
+        end
+
+        lines.concat(Support.indent(arrange, "    "))
+        pinned = Support.pinned_value(pin.value, Support.keys_for(pin, pin_keys))
+        if !pinned.equal?(pin.value) && Support.literal?(pinned)
+          keys = pinned.keys.map { |key| Support.ruby_literal(key) }.join(", ")
+          lines << "    assert_equal(#{Support.ruby_literal(pinned)}, #{call}.slice(#{keys}))"
+        elsif !pinned.equal?(pin.value)
+          lines.concat(part_lines(pinned, call))
+        elsif pin.value.nil?
+          # Minitest 6 fails assert_equal with an expected nil.
+          lines << "    assert_nil #{call}"
+        elsif (pattern = Support.frame_pattern(pin.value))
+          lines << "    assert_match(#{pattern}, #{call})"
+        elsif pin.value.is_a?(Hash) && Support.literal?(pin.value)
+          # Without parentheses Ruby reads a leading { as a block.
+          lines << "    assert_equal(#{Support.ruby_literal(pin.value)}, #{call})"
+        elsif Support.literal?(pin.value)
+          lines << "    assert_equal #{Support.ruby_literal(pin.value)}, #{call}"
+        elsif Support.class_pins(pin.value) == [["", Support.class_literal(pin.value)]]
+          lines << "    assert_kind_of #{Support.class_literal(pin.value)}, #{call}"
+        else
+          lines << "    value = #{call}"
+          lines.concat(Support.shape_assertions(pin.value).map { |line| "    #{line}" })
+        end
+        lines << "  end"
+        lines
+      end
+
+      # The stable keys of a Hash with no literal: its literal entries by
+      # value, and each other one by its shape, as RSpec's include pins it.
+      # The call runs once, since a second call could make another record.
+      def part_lines(pinned, call)
+        literal, other = pinned.partition { |_, item| Support.literal?(item) }.map(&:to_h)
+        lines = ["    value = #{call}"]
+        unless literal.empty?
+          keys = literal.keys.map { |key| Support.ruby_literal(key) }.join(", ")
+          lines << "    assert_equal(#{Support.ruby_literal(literal)}, value.slice(#{keys}))"
+        end
+        other.each { |key, item| lines.concat(Support.shape_assertions(item, "[#{Support.ruby_literal(key)}]").map { |line| "    #{line}" }) }
+        lines
+      end
+    end
+  end
+end