branchout 0.1.0

data/lib/branchout/emitters/support.rb

@@ -0,0 +1,1248 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "pathname"
+require "tmpdir"
+
+module Branchout
+  module Emitters
+    # Shared, deterministic rendering used by every characterization emitter.
+    module Support
+      module_function
+
+      def header(target, kind, destination)
+        [
+          "# frozen_string_literal: true",
+          "",
+          "# Generated by branchout #{VERSION}. Characterization #{kind} for discovered inputs.",
+          "# target: #{header_path(target, destination)}",
+          "# entry: #{target.entry}"
+        ]
+      end
+
+      # The target as the report names it when it is under the working
+      # directory. Otherwise it is relative to the root of its project (the
+      # nearest directory with a Gemfile, a gemspec, or .git), so a committed
+      # file does not carry one machine's path.
+      def header_path(target, destination)
+        absolute = File.expand_path(target.path)
+        return target.display_path unless target.display_path == absolute
+
+        root = project_root(File.dirname(absolute))
+        root ? absolute.delete_prefix("#{root}/") : relative_require(destination, absolute)
+      end
+
+      def project_root(dir)
+        loop do
+          marked = %w[Gemfile .git].any? { |name| File.exist?(File.join(dir, name)) } ||
+                   !Dir.glob("*.gemspec", base: dir).empty?
+          return dir if marked
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      # The requires of an emitted test: the --require files, then the
+      # target. +by_name+ requires each through the load path, named from
+      # the first of the -I directories (+load_paths+) and the --require
+      # files' directories that holds it, so the test loads whichever
+      # checkout the runner's -I names. With neither, the nearest lib
+      # directory above the target names it, or the target's own directory,
+      # as for a library's entry file. A file under none of them keeps its
+      # path, behind a comment that says why. A comment above the requires
+      # names, as -I, each directory a require by name needs and the
+      # runner does not put on the load path itself (+runner_load_paths+,
+      # from +from+, where the runner starts).
+      def require_lines(requires, target_path, destination, by_name: false, load_paths: [], runner_load_paths: [], from: Dir.pwd)
+        roots = name_roots(requires, target_path, load_paths)
+        used = []
+        lines = [*requires, *target_path].flat_map do |path|
+          absolute = File.expand_path(path)
+          root = roots.find { |dir| absolute.start_with?(dir) }
+          if by_name && root
+            used |= [root]
+            next ["require #{absolute.delete_prefix(root).delete_suffix(".rb").inspect}"]
+          end
+
+          relative = relative_require(destination, path)
+          note = "# Required by path: no -I or --require directory holds #{relative}." if by_name
+          [*note, "require_relative #{relative.inspect}"]
+        end
+        used -= runner_load_paths.map { |dir| "#{File.expand_path(dir, from)}/" }
+        used.empty? ? lines : ["# Load path: #{used.map { |dir| "-I #{shown_directory(dir.chomp("/"), from: from)}" }.join(" ")}", *lines]
+      end
+
+      # A directory as a person passes it to -I: from the working directory
+      # when it is under it, else from its project's root, named after it,
+      # so a committed test carries no machine's path where it can avoid one.
+      def shown_directory(dir, from: Dir.pwd)
+        cwd = "#{File.expand_path(from)}/"
+        return dir.delete_prefix(cwd) if dir.start_with?(cwd)
+
+        root = project_root(dir)
+        return dir unless root
+
+        "#{root == dir ? "." : dir.delete_prefix("#{root}/")} (in #{File.basename(root)})"
+      end
+
+      # The files of +requires+ and +target_path+ that --require-by-name
+      # cannot name, because no directory in +load_paths+ or of +requires+
+      # holds them.
+      def unnamed_requires(requires, target_path, load_paths: [])
+        roots = require_roots(requires, load_paths)
+        return [] if roots.empty?
+
+        [*requires, *target_path].reject { |path| roots.any? { |dir| File.expand_path(path).start_with?(dir) } }
+      end
+
+      # The files require_lines requires by path that sit in another project
+      # than +destination+, or under no project when it has one: their
+      # require_relative names this machine's directories, absolute or
+      # climbing out of the test's project.
+      def required_outside_project(requires, target_path, destination, by_name: false, load_paths: [])
+        roots = by_name ? name_roots(requires, target_path, load_paths) : []
+        home = project_root(File.dirname(File.expand_path(destination)))
+        [*requires, *target_path].map { |path| File.expand_path(path) }.select do |absolute|
+          roots.none? { |dir| absolute.start_with?(dir) } &&
+            (project_root(File.dirname(absolute)) != home || File.absolute_path?(relative_require(destination, absolute)))
+        end
+      end
+
+      def name_roots(requires, target_path, load_paths)
+        roots = require_roots(requires, load_paths)
+        roots.empty? && target_path ? [load_root(target_path)] : roots
+      end
+
+      def require_roots(requires, load_paths)
+        [*load_paths, *requires.map { |path| File.dirname(path) }].map { |dir| "#{File.expand_path(dir)}/" }
+      end
+
+      def load_root(path)
+        dir = File.dirname(File.expand_path(path))
+        lib = dir.split("/").rindex("lib")
+        "#{lib ? dir.split("/")[0..lib].join("/") : dir}/"
+      end
+
+      # Paths that share only / give the absolute path: a climb to / breaks
+      # as soon as either file moves, and require_relative accepts it.
+      def relative_require(destination, target_path)
+        from = Pathname.new(File.expand_path(File.dirname(destination)))
+        to = Pathname.new(File.expand_path(target_path))
+        return to.to_s if from.each_filename.first != to.each_filename.first
+
+        relative = to.relative_path_from(from).to_s.tr("\\", "/")
+        relative.start_with?(".") ? relative : "./#{relative}"
+      end
+
+      # +input+ with each String that names a path under the project of
+      # +destination+ as a ProjectPath. A String that File.expand_path
+      # would not give back as written, such as one with a trailing /, stays.
+      def project_paths(input, destination)
+        root = project_root(File.dirname(File.expand_path(destination)))
+        return input unless root
+
+        rewrite = lambda do |value|
+          case value
+          when ProjectPath then value
+          when String then project_path(value, destination, root) || value
+          when Array then value.map(&rewrite)
+          when Hash then value.transform_values(&rewrite)
+          else value
+          end
+        end
+        receiver = input.receiver.is_a?(Input) ? project_paths(input.receiver, destination) : input.receiver
+        setup = input.setup.map { |call| Input::SetupCall.new(call.method_name, project_paths(call.arguments, destination)) }
+        Input.new(args: rewrite.(input.args), kwargs: rewrite.(input.kwargs), receiver: receiver, setup: setup,
+                  pin_keys: input.pin_keys, block: input.block, before: input.before)
+      end
+
+      # +value+, a returned value or an error message, with each String
+      # that holds a path under the project of +destination+ written from
+      # the test's directory: a String that is one such path as a
+      # ProjectPath, and one that holds such paths among other text as a
+      # ProjectText.
+      def project_value(value, destination)
+        root = project_root(File.dirname(File.expand_path(destination)))
+        return value unless root
+
+        rewrite = lambda do |item|
+          case item
+          when ProjectPath, ProjectText then item
+          when String
+            next item unless item.include?("#{root}/")
+
+            project_path(item, destination, root) ||
+              ProjectText.new(item.split("#{root}/", -1), from_test(destination, root))
+          when Array then item.map(&rewrite)
+          when Hash then item.transform_values(&rewrite)
+          else item
+          end
+        end
+        rewrite.(value)
+      end
+
+      # +value+ as a ProjectPath when it is one path under +root+ that
+      # File.expand_path gives back as written (a trailing / it would not).
+      def project_path(value, destination, root)
+        return nil unless value.start_with?("#{root}/")
+
+        relative = from_test(destination, value)
+        File.expand_path(relative, File.dirname(File.expand_path(destination))) == value ? ProjectPath.new(value.delete_prefix("#{root}/"), relative) : nil
+      end
+
+      # File.expand_path reads a leading ~ as a home directory.
+      def from_test(destination, path)
+        relative_require(destination, path).sub(%r{\A\./(?!~)}, "")
+      end
+
+      # The paths of this machine, under the home or the temporary
+      # directory, that the Strings of +value+ hold anywhere in their text.
+      def machine_paths_in(value)
+        homes = machine_homes.map { |home| Regexp.escape(home) }.join("|")
+        strings(value).flat_map { |text| text.scan(%r{(?:#{homes})[^\s"'`(),;]+}) }
+      end
+
+      def machine_homes
+        [Dir.tmpdir, Dir.home].flat_map { |dir| ["#{dir}/", "#{File.realpath(dir)}/"] }.uniq
+      end
+
+      # The Strings of +input+ that are a path of this machine: one under
+      # the home or the temporary directory, whether it exists or not.
+      # /dev/null, or /tmp itself, is the same on every machine.
+      def machine_paths(input)
+        strings(input).select do |value|
+          File.absolute_path?(value) && machine_homes.any? { |home| value.start_with?(home) }
+        end
+      end
+
+      def strings(value)
+        case value
+        when ProjectPath, ProjectText then []
+        when String then [value]
+        when Array then value.flat_map { |item| strings(item) }
+        when Hash then strings(value.values)
+        when Input
+          [value.args, value.kwargs, value.receiver, *value.setup.map(&:arguments)].flat_map { |item| strings(item) }
+        else []
+        end
+      end
+
+      # The statements that build the receiver, and the entry call. With no
+      # setup calls the receiver is built inline and there is no statement.
+      # A name in +private_calls+ (the entry, or new) is called through send,
+      # as explore called it. +const+ is the class as the test writes it.
+      def arrange(target, input, private_calls: [], const: target.const_name, thawed: false)
+        receiver = if target.singleton
+          const
+        else
+          receiver_text(input, const, private_calls, thawed: thawed)
+        end
+        call = ->(on) { with_block(call_text(on, target.method_name, argument_list(input, thawed: thawed), private_calls), input.block) }
+        before = input.before ? input.before.source.lines(chomp: true) : []
+        return [before, call.(receiver)] if input.setup.empty? && !input.receiver.is_a?(Code)
+
+        name = input.receiver.is_a?(Code) ? built_receiver_name(target) : receiver_name(target)
+        statements = [*before, "#{name} = #{receiver}"]
+        input.setup.each do |setup_call|
+          statements << call_text(name, setup_call.method_name, argument_list(setup_call.arguments, thawed: thawed), [])
+        end
+        [statements, call.(name)]
+      end
+
+      # How the receiver of an instance method's input is built: the Code
+      # the input gives, or new with the input's arguments for it.
+      def receiver_text(input, const, private_calls, thawed: false)
+        return input.receiver.source if input.receiver.is_a?(Code)
+
+        call_text(const, :new, input.receiver ? argument_list(input.receiver, thawed: thawed) : "", private_calls)
+      end
+
+      def call_text(on, method_name, arguments, private_calls)
+        # A setter or an operator goes through send: "cart.limit=" and
+        # "cart.limit=(a: 1)" do not parse, and "cart.limit=()" passes nil.
+        plain = method_name.to_s.match?(/\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/)
+        if plain && !private_calls.include?(method_name)
+          return arguments.empty? ? "#{on}.#{method_name}" : "#{on}.#{method_name}(#{arguments})"
+        end
+
+        "#{on}.send(#{[method_name.to_sym.inspect, *(arguments unless arguments.empty?)].join(", ")})"
+      end
+
+      def with_block(call, block)
+        block ? "#{call} #{block.source}" : call
+      end
+
+      # The name a receiver built by the input's Ruby takes in every format,
+      # which RSpec's own method names cannot take, so that the input's
+      # arguments can name it while explore runs and in the emitted test.
+      def built_receiver_name(target)
+        name = receiver_name(target)
+        Emitters::RSpec::TAKEN_NAMES.include?(name) ? "object" : name
+      end
+
+      # The class name in snake case, as a reader would name the object.
+      def receiver_name(target)
+        name = target.const_name.split("::").last
+                     .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                     .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                     .downcase
+        RESERVED_NAMES.include?(name) ? "subject" : name
+      end
+
+      RESERVED_NAMES = %w[
+        alias and begin break case class def defined do else elsif end ensure false for if in
+        module next nil not or redo rescue retry return self super then true undef unless until
+        when while yield error
+      ].freeze
+
+      def argument_list(input, thawed: false)
+        args = input.args.map { |value| ruby_literal(value, thawed: thawed) }
+        kwargs = input.kwargs.keys.map { |key|
+          "#{keyword_literal(key)}: #{ruby_literal(input.kwargs[key], thawed: thawed)}"
+        }
+        (args + kwargs).join(", ")
+      end
+
+      # An emitted test has frozen_string_literal, so a +thawed+ string is
+      # written with a leading + to match the copy the explore run passed.
+      def ruby_literal(value, thawed: false)
+        case value
+        when nil then "nil"
+        when true then "true"
+        when false then "false"
+        when Integer then value.to_s
+        when Float then Canon.format_float(value)
+        when ProjectPath then "File.expand_path(#{value.from_test.inspect}, __dir__)"
+        when ProjectText
+          root = "\#{File.expand_path(#{value.root_from_test.inspect}, __dir__)}/"
+          %("#{value.pieces.map { |piece| piece.inspect[1...-1] }.join(root)}")
+        when String then thawed ? "+#{value.inspect}" : value.inspect
+        when Symbol then value.inspect
+        when Code then value.source
+        when Struct, Data
+          members = value.to_h.map { |key, item| positional?(value) ? ruby_literal(item, thawed: thawed) : "#{keyword_literal(key)}: #{ruby_literal(item, thawed: thawed)}" }
+          "#{value.class.name}.new(#{members.join(", ")})"
+        when Set then "Set[#{value.map { |item| ruby_literal(item, thawed: thawed) }.join(", ")}]"
+        when Array
+          "[#{value.map { |item| ruby_literal(item, thawed: thawed) }.join(", ")}]"
+        when Hash
+          # Insertion order, as the value prints: a failure diff then lines
+          # up key by key, and Hash equality ignores order anyway.
+          value.empty? ? "{}" : "{ #{value.map { |key, item| "#{hash_key_literal(key)} #{ruby_literal(item, thawed: thawed)}" }.join(", ")} }"
+        else
+          return "Date.new(#{value.year}, #{value.mon}, #{value.mday})" if plain_date?(value)
+
+          raise Error, "cannot emit a literal for #{value.class}"
+        end
+      end
+
+      # A Regexp literal for a String that quotes a backtrace frame, whose
+      # label Ruby 3.4 writes in another form than 3.3, or nil.
+      def frame_pattern(value)
+        source = value.is_a?(String) && Runner::ExceptionInfo.frame_pattern(value)
+        Regexp.new(source).inspect if source
+      end
+
+      def literal?(value)
+        case value
+        when nil, true, false, Integer, String, Symbol then true
+        when Float then value.finite?
+        when Array, Set then value.all? { |item| literal?(item) }
+        when Hash then value.all? { |key, item| literal?(key) && literal?(item) }
+        when Code then false
+        when Struct, Data then value_object?(value)
+        else plain_date?(value)
+        end
+      end
+
+      # A Date of the default calendar reads back from Date.new(year, month,
+      # day). A DateTime, or a Date of another calendar reform, does not.
+      def plain_date?(value)
+        defined?(::Date) && value.instance_of?(::Date) && value.start == ::Date::ITALY
+      end
+
+      # A Data or a Struct reads back from its class's new when its class's
+      # name leads to it, each member has a literal, and new with those
+      # members makes an equal value: an initialize of its own may change
+      # what it is given.
+      def value_object?(value)
+        name = value.class.name
+        return false unless name && Object.const_get(name).equal?(value.class)
+        return false unless value.to_h.each_value.all? { |item| literal?(item) }
+
+        positional?(value) ? value.class.new(*value.to_a) == value : value.class.new(**value.to_h) == value
+      rescue StandardError
+        false
+      end
+
+      # A Struct made with keyword_init: false takes its members by position.
+      def positional?(value)
+        value.is_a?(Struct) && value.class.keyword_init? == false
+      end
+
+      # A value with no Ruby literal, such as a Set or a Struct, is pinned by
+      # its class. An anonymous class has no stable name, so its nearest
+      # named superclass stands in.
+      def class_literal(value)
+        value.class.ancestors.find { |mod| mod.is_a?(Class) && mod.name }.name
+      end
+
+      # A Symbol key takes the key: form, as the keyword of a call does.
+      def hash_key_literal(key)
+        key.is_a?(Symbol) ? "#{keyword_literal(key)}:" : "#{ruby_literal(key)} =>"
+      end
+
+      def keyword_literal(key)
+        text = key.to_s
+        return text if text.match?(/\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/)
+
+        text.inspect
+      end
+
+      def class_name_for(target)
+        const_part = target.const_name.gsub("::", "")
+        method_part = target.method_name.to_s.sub(/[?!=]\z/, "?" => "_predicate", "!" => "_bang", "=" => "_writer")
+        method_part = method_part.split("_").map { |word| word.sub(/\A[a-z]/, &:upcase) }.join
+        "#{const_part}#{method_part}CharacterizationTest"
+      end
+
+      # Minitest method names: the input's values, then what the test pins.
+      # Siblings, inputs whose names would be the same, are named by the
+      # leaves that differ between them instead, so a name tells them apart
+      # and adding an input can rename its siblings. A name that still
+      # collides gets six hex digits of its input's digest, and a digest
+      # collision a counter.
+      def test_names(pins, pin_keys = [])
+        pinned = pins.map { |pin| pinned_pin(pin, pin_keys) }
+        differences = hash_differences(pinned.map { |pin| pin.value unless pin.error }, pins.map(&:input))
+        # A Hash outcome may take more room, so the leaves RSpec names fit, and
+        # so may an Array of scalars and collections, so its keys fit after
+        # "array".
+        outcomes = pinned.zip(differences).map do |pin, differing|
+          roomy = !differing.empty? || (!pin.error && mixed_array?(pin.value))
+          clip(outcome_words(pin, differing), roomy ? OUTCOME_LIMIT : 30)
+        end
+        names = pins.each_with_index.map { |pin, index| name_of(input_words(pin.input), outcomes[index]) }
+        names.each_index.group_by { |index| names[index] }.each_value do |siblings|
+          next if siblings.one?
+
+          words = differing_words(siblings.map { |index| pins[index].input })
+          siblings.zip(words) { |index, differing| names[index] = name_of(differing, outcomes[index]) }
+        end
+        repeated = names.tally
+        names = names.each_with_index.map do |name, index|
+          repeated[name] > 1 ? "#{name}_#{Digest::SHA256.hexdigest(pins[index].input.canonical)[0, 6]}" : name
+        end
+        seen = Hash.new(0)
+        names.map { |name| (seen[name] += 1) == 1 ? name : "#{name}_#{seen[name]}" }
+      end
+
+      def name_of(input_words, outcome)
+        ["test", clip(input_words, 40), outcome].reject(&:empty?).join("_")
+      end
+
+      # For each input, the words of every leaf whose value is not the same
+      # in all +inputs+: the deepest key above it, then its value, or "none"
+      # where the input has no such leaf. Strings at one leaf drop the words
+      # they all start with, so a shared start does not fill the name.
+      # Leaves keep their order in the first input by canonical form, so the
+      # words do not depend on the order of +inputs+.
+      def differing_words(inputs)
+        leaves = inputs.map { |input| input_leaves(input).to_h }
+        paths = inputs.zip(leaves).sort_by { |input, _| input.canonical }.flat_map { |_, map| map.keys }.uniq
+        differing = paths.reject do |path|
+          leaves.all? { |map| map.key?(path) && map[path].eql?(leaves.first[path]) }
+        end
+        shared = differing.to_h { |path| [path, shared_start(leaves.select { |map| map.key?(path) }.map { |map| map[path] })] }
+        leaves.map do |map|
+          differing.flat_map do |path|
+            # An input that has an empty collection above this leaf, or
+            # items below it, does have the key; its own leaf names it.
+            next [] if !map.key?(path) && map.keys.any? { |other| other.first(path.length) == path || path.first(other.length) == other }
+            # So does one that holds another shape under the leaf's last key.
+            # A Symbol key and a String key of one name are the one key a
+            # name can say.
+            held = path.rindex { |step| key_step?(step) }
+            above = held && path.first(held + 1).map { |step| plain_step(step) }
+            next [] if !map.key?(path) && held && map.keys.any? { |other| other.first(held + 1).map { |step| plain_step(step) } == above }
+            # An item of an Array has no key to say "none" after, so a Hash
+            # that the input holds in that Array's place names it.
+            parent = path[0...-1]
+            next [] if !map.key?(path) && path.last.is_a?(Integer) &&
+                       map.keys.any? { |other| other.first(parent.length) == parent && key_step?(other[parent.length]) }
+
+            key = telling_key(path, paths)
+            # Ruby source keeps the word before the part, as the name it
+            # compares (limit_100), where a String drops its whole shared start.
+            kept = map[path].is_a?(Code) ? [shared[path] - 1, 0].max : shared[path]
+            rest = worded?(map[path]) ? tokens(map[path]).drop(kept) : []
+            value = if !map.key?(path) then ["none"]
+            elsif map[path] == {} || map[path] == [] then ["empty"]
+            elsif !rest.empty? then rest
+            else value_words(map[path])
+            end
+            key ? [key, *value] : value
+          end.then { |words| without_repeated_none(words) }
+        end
+      end
+
+      # A key that several leaves of an absent collection end in says
+      # "none" once, and so do the missing items at the end of a shorter
+      # Array, which have no key.
+      def without_repeated_none(words)
+        out = []
+        index = 0
+        while index < words.length
+          if words[index].is_a?(Key) && words[index + 1] == "none"
+            pair = words[index, 2]
+            out.concat(pair) unless out.each_cons(2).include?(pair)
+            index += 2
+          elsif words[index] == "none" && out.last == "none" && !out[-2].is_a?(Key)
+            index += 1
+          else
+            out << words[index]
+            index += 1
+          end
+        end
+        out
+      end
+
+      # A String, or the Ruby source of a receiver or argument, reads as words.
+      def worded?(value) = value.is_a?(String) || value.is_a?(Code)
+
+      # How many leading words all of +values+ share, when they read as words.
+      def shared_start(values)
+        return 0 unless values.all? { |value| worded?(value) }
+
+        words = values.map { |value| tokens(value) }
+        words.first.each_index.take_while { |index| words.all? { |list| list[index] == words.first[index] } }.length
+      end
+
+      # [path, value] for every scalar or empty collection of an input. A
+      # Symbol step names a part of the input, a String a String Hash key, a
+      # SymbolKey a Symbol Hash key, and an Integer a position.
+      def input_leaves(input)
+        out = []
+        input.args.each_with_index { |arg, index| collect_leaves(arg, [:args, index], out) }
+        input.kwargs.each { |key, value| collect_leaves(value, [:kwargs, key], out) }
+        if input.receiver.is_a?(Code)
+          out << [[:receiver], input.receiver]
+        elsif input.receiver
+          input_leaves(input.receiver).each { |path, value| out << [[:new, *path], value] }
+        end
+        input.setup.each_with_index do |call, index|
+          out << [[:setup, index, :method], call.method_name]
+          input_leaves(call.arguments).each { |path, value| out << [[:setup, index, *path], value] }
+        end
+        out << [[:block], input.block] if input.block
+        out << [[:before], input.before] if input.before
+        out
+      end
+
+      # +whole_arrays+ keeps an Array of scalars as one leaf, so a reader
+      # sees items is [1, 2] and not each item by its position.
+      def collect_leaves(value, path, out, whole_arrays: false)
+        return out << [path, value] if path.last.is_a?(TapBlock)
+
+        value = written_value(value)
+        children = case value
+          when Code then call_parts(value)
+          when Hash then value.map { |key, item| [key.is_a?(Symbol) ? SymbolKey.new(key.to_s) : key.to_s, item] }
+          when Array
+            whole_arrays && value.none? { |item| collection?(item) } ? [] : value.each_with_index.map { |item, index| [index, item] }
+          else []
+        end
+        return out << [path, value] if children.empty?
+
+        children.each { |step, item| collect_leaves(item, path + [step], out, whole_arrays: whole_arrays) }
+      end
+
+      # What each pin's test pins, as RSpec says it: "raises KeyError",
+      # "returns :miss". A Hash says the scalar entries that differ between
+      # the Hashes of +pins+, so siblings say how their results differ.
+      # +short+ names a leaf by its deepest key (discarded: 1).
+      def outcomes(pins, pin_keys = [], short: false)
+        pinned = pins.map { |pin| pinned_pin(pin, pin_keys) }
+        differences = hash_differences(pinned.map { |pin| pin.value unless pin.error }, pins.map(&:input))
+        pins.each_index.to_h { |index| [pins[index], outcome_text(pinned[index], differences[index], short: short)] }
+      end
+
+      # The entries of a returned Hash whose keys +pin_keys+ names, by
+      # name, so a key added later fails no test. A value that is not a
+      # Hash, or a Hash with none of the keys, is pinned whole.
+      def pinned_value(value, pin_keys)
+        return value if pin_keys.empty? || !value.is_a?(Hash)
+
+        chosen = value.select { |key, _| pin_keys.include?(key.to_s) }
+        chosen.empty? ? value : chosen
+      end
+
+      def pinned_pin(pin, pin_keys)
+        pin.error ? pin : pin.dup.tap { |copy| copy.value = pinned_value(pin.value, keys_for(pin, pin_keys)) }
+      end
+
+      # The keys that pin +pin+'s Hash: its input's own, or else +pin_keys+,
+      # without the keys whose values differed between two runs.
+      def keys_for(pin, pin_keys)
+        keys = pin.input.pin_keys || pin_keys
+        return keys unless pin.varying.is_a?(Array)
+
+        stable = pin.value.keys.map(&:to_s) - pin.varying
+        chosen = keys & stable
+        chosen.empty? ? stable : chosen
+      end
+
+      def outcome_text(pin, differing, short: false)
+        return "raises #{pin.error.class_name}" if pin.error
+
+        value = pin.value
+        unless differing.empty?
+          entries = differing.map do |path, item|
+            [short ? telling_path(path, differing.map(&:first)) : path, ruby_literal(described(item))]
+          end
+          return "returns #{entries_text(entries, merge: !short)}"
+        end
+        unless literal?(value)
+          return "returns an Array of #{value.length}" if value.is_a?(Array)
+          return "returns a Hash of #{value.keys.map(&:to_s).join(", ")}" if keyed?(value)
+
+          return "returns #{article(class_literal(value))}"
+        end
+
+        text = ruby_literal(described(value))
+        return "returns #{text}" if text.length <= 40
+
+        # A String or an Array of scalars says its start, as the minitest
+        # name says its first words.
+        case value
+        when Hash then "returns a Hash of #{value.keys.map(&:to_s).join(", ")}"
+        when Array
+          if value.all? { |item| composite?(item) } then "returns an Array of #{value.length}"
+          elsif value.any? { |item| composite?(item) } then "returns [#{value.map { |item| item_text(item) }.join(", ")}]"
+          else "returns #{text[0, 37]}..."
+          end
+        when String then "returns #{text[0...word_end(text, 0, 37)]}..."
+        when Struct, Data then "returns #{article(value.class.name)}"
+        else "returns #{text}"
+        end
+      end
+
+      # Where a cut of +text+ from +start+ to +finish+ ends: at +finish+,
+      # or, when that falls inside a word, before the word, unless that
+      # leaves fewer than 12 characters.
+      def word_end(text, start, finish)
+        return finish unless finish < text.length && text[finish - 1].match?(/\w/) && text[finish].match?(/\w/)
+
+        boundary = text.rindex(/\W/, finish - 1)
+        boundary && boundary - start >= 12 ? boundary : finish
+      end
+
+      # An item of an Array that holds both scalars and collections: a
+      # scalar as written, and a collection by its keys or its size.
+      def item_text(item)
+        case item
+        when Hash then item.empty? ? "{}" : "a Hash of #{item.keys.map(&:to_s).join(", ")}"
+        when Array then item.empty? ? "[]" : "an Array of #{item.length}"
+        when Struct, Data then article(item.class.name)
+        else ruby_literal(item)
+        end
+      end
+
+      # An RSpec matcher argument for a value with no literal: a Struct or
+      # Data by its class and members, an Array or Hash by its items, and
+      # anything else by its class.
+      def shape_matcher(value)
+        case value
+        when Struct, Data
+          members = value.to_h.map { |key, item| "#{key}: #{literal?(item) ? ruby_literal(item) : shape_matcher(item)}" }
+          "a_kind_of(#{class_literal(value)}).and(have_attributes(#{members.join(", ")}))"
+        when Array then "[#{value.map { |item| literal?(item) ? ruby_literal(item) : shape_matcher(item) }.join(", ")}]"
+        # RSpec finds each expected key in the Hash, so a key with no
+        # literal leaves the Hash pinned by its class, as class_pins says.
+        when Hash
+          return "a_kind_of(Hash)" unless value.each_key.all? { |key| literal?(key) }
+
+          entries = value.map { |key, item| "#{hash_key_literal(key)} #{literal?(item) ? ruby_literal(item) : shape_matcher(item)}" }
+          entries.empty? ? "{}" : "{ #{entries.join(", ")} }"
+        else "a_kind_of(#{class_literal(value)})"
+        end
+      end
+
+      # Minitest assertions on the returned +value+, held in a local named
+      # value, that check what shape_matcher checks: each part with a
+      # literal by its value, and each part class_pins names by its class.
+      # A Hash or an Array is compared whole, each part with no literal
+      # standing in as itself, so a missing key or item fails too.
+      def shape_assertions(value, path = "")
+        return [literal_assertion(value, "value#{path}")] if literal?(value)
+
+        case value
+        when Hash, Array
+          return ["assert_kind_of Hash, value#{path}"] if value.is_a?(Hash) && !value.each_key.all? { |key| literal?(key) }
+
+          parts = []
+          whole = shape_template(value, path, parts)
+          [*parts, "assert_equal(#{whole}, value#{path})"]
+        when Struct, Data
+          members = value.to_h
+          literal, other = members.partition { |_, item| literal?(item) }.map(&:to_h)
+          lines = ["assert_kind_of #{class_literal(value)}, value#{path}"]
+          unless literal.empty?
+            keys = literal.keys.map { |key| ruby_literal(key) }.join(", ")
+            lines << "assert_equal(#{ruby_literal(literal)}, value#{path}.to_h.slice(#{keys}))"
+          end
+          lines + other.flat_map { |key, item| shape_assertions(item, "#{path}.#{key}") }
+        else ["assert_kind_of #{class_literal(value)}, value#{path}"]
+        end
+      end
+
+      # Minitest 6 fails assert_equal with an expected nil.
+      def literal_assertion(value, actual)
+        return "assert_nil #{actual}" if value.nil?
+
+        "assert_equal(#{ruby_literal(value)}, #{actual})"
+      end
+
+      # The literal of a Hash or an Array whose parts with no literal are
+      # read from the returned value, so comparing it with the value checks
+      # the rest; +parts+ gets the assertions on those parts.
+      def shape_template(value, path, parts)
+        return ruby_literal(value) if literal?(value)
+
+        case value
+        when Array then "[#{value.each_with_index.map { |item, index| shape_template(item, "#{path}[#{index}]", parts) }.join(", ")}]"
+        when Hash
+          if value.each_key.all? { |key| literal?(key) }
+            entries = value.map { |key, item| "#{hash_key_literal(key)} #{shape_template(item, "#{path}[#{ruby_literal(key)}]", parts)}" }
+            return entries.empty? ? "{}" : "{ #{entries.join(", ")} }"
+          end
+          parts.concat(shape_assertions(value, path))
+          "value#{path}"
+        else
+          parts.concat(shape_assertions(value, path))
+          "value#{path}"
+        end
+      end
+
+      # [path, class name] for each part of +value+ that has no literal, as
+      # the RSpec matcher reaches it: into a Hash, an Array, and the members
+      # of a Struct or Data, and no further.
+      def class_pins(value, path = "")
+        return [] if literal?(value)
+
+        case value
+        when Hash
+          value.flat_map { |key, item| literal?(key) ? class_pins(item, "#{path}[#{ruby_literal(key)}]") : [[path, class_literal(value)]] }.uniq
+        when Array then value.each_with_index.flat_map { |item, index| class_pins(item, "#{path}[#{index}]") }
+        when Struct, Data then value.to_h.flat_map { |key, item| class_pins(item, "#{path}.#{key}") }
+        else [[path, class_literal(value)]]
+        end
+      end
+
+      def article(name)
+        name.match?(/\A[AEIOU]/) ? "an #{name}" : "a #{name}"
+      end
+
+      # For each of +values+, the [path, leaf] entries of a Hash at the
+      # paths chosen to tell its siblings apart: the fewest leaves, nested
+      # ones too, that tell every two different Hashes of +values+ apart, at
+      # most three. Each pick is a leaf that does not repeat its input,
+      # then a leaf every Hash has, when one tells a pair apart, then tells
+      # the most pairs apart, then has the most distinct values. A pick that would make a minitest outcome longer
+      # than OUTCOME_LIMIT is left out, so both formats name the same
+      # leaves. A value that is not a Hash has none.
+      def hash_differences(values, inputs = [])
+        # A part with no literal is checked by its class, so it tells no
+        # sibling apart.
+        leaves = values.map { |value| named_leaves(value).select { |_, (_, leaf)| literal?(leaf) } if keyed?(value) }
+        echoes = leaves.each_index.map { |index| inputs[index] ? inputs[index].args.map { |arg| written_value(arg) }.grep(Hash).map { |arg| named_leaves(arg) }.reduce({}, :merge) : {} }
+        distinct = leaves.compact.uniq.sort_by(&:inspect)
+        paths = distinct.flat_map(&:keys).uniq
+        pairs = distinct.combination(2).to_a
+        # A leaf every Hash has says something about each of them, so it
+        # comes before one that only some have.
+        shared = paths.to_h { |path| [path, distinct.all? { |map| map.key?(path) }] }
+        # A leaf that holds what the input passed at the same path, such as
+        # a document the method merges into, says nothing the input did not.
+        echoed = paths.to_h do |path|
+          [path, leaves.each_index.all? { |index| !leaves[index]&.key?(path) || (echoes[index].key?(path) && echoes[index][path].eql?(leaves[index][path])) }]
+        end
+        chosen = []
+        entries = ->(map, picks) { picks.filter_map { |path| map[path] if map.key?(path) } }
+        until pairs.empty? || chosen.length == 3
+          told = paths.to_h { |path| [path, pairs.count { |a, b| leaves_differ?(a, b, path) }] }
+          spread = paths.to_h { |path| [path, distinct.map { |map| map.fetch(path, MISSING) }.uniq.length] }
+          best = paths.each_with_index.max_by { |path, index| [told[path].positive? && !echoed[path] ? 1 : 0, told[path].positive? && shared[path] ? 1 : 0, told[path], spread[path], -index] }.first
+          break if chosen.any? && distinct.any? { |map| outcome_length(entries.(map, chosen + [best])) > OUTCOME_LIMIT }
+
+          chosen << best
+          pairs.reject! { |a, b| leaves_differ?(a, b, best) }
+        end
+        leaves.map { |map| map ? entries.(map, chosen) : [] }
+      end
+
+      MISSING = Object.new.freeze
+      # The longest minitest outcome part of a name, in characters: room for
+      # the "and" before each of the second and third leaves too.
+      OUTCOME_LIMIT = 51
+
+      def outcome_length(entries)
+        clip(outcome_entry_words(entries), Float::INFINITY).length
+      end
+
+      # path => leaf for every scalar or empty collection under a Hash.
+      def hash_leaves(value)
+        [].tap { |out| collect_leaves(value, [], out) }.reject { |path, _| path.empty? }.to_h
+      end
+
+      # hash_leaves by the names of their keys, each to its own [path, leaf],
+      # so a key that one Hash holds as a Symbol and another as a String is
+      # one leaf to compare, and each still reads as its Hash holds it.
+      def named_leaves(value)
+        hash_leaves(value).to_h { |path, leaf| [path.map { |step| plain_step(step) }, [path, leaf]] }
+      end
+
+      def leaves_differ?(a, b, path)
+        !(a.key?(path) && b.key?(path) && a[path].eql?(b[path]))
+      end
+
+      # "returns", then each entry's key, as telling_key names it, and its
+      # value.
+      def outcome_entry_words(entries)
+        words = entries.flat_map do |path, item|
+          [telling_key(path, entries.map(&:first)), *(item == [] || item == {} ? ["empty"] : value_words(item))].compact
+        end
+        ["returns", *words]
+      end
+
+      # A path into a value as a reader writes it. A Symbol key that is a
+      # plain name reads bare, lines[0].sku, and any other Symbol key as a
+      # Symbol, [:"a b"]. A String key keeps its quotes, params["sku"], so a
+      # String-keyed Hash does not read as if a Symbol lookup would find it.
+      # +root+, when given, is the name the path starts from.
+      def path_text(path, root = nil)
+        path.each_with_object(+"#{root}") do |step, text|
+          text << if step.is_a?(CallHead) then ""
+                  elsif step.is_a?(TapBlock) then ".#{step.name}"
+                  elsif step.is_a?(Integer) then "[#{step}]"
+                  elsif !step.is_a?(SymbolKey) then "[#{step.inspect}]"
+                  elsif !step.name.match?(/\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/) then "[#{step.name.to_sym.inspect}]"
+                  elsif text.empty? then step.name
+                  else ".#{step.name}"
+                  end
+        end
+      end
+
+      # Leaves of a returned Hash, each a [path, value text], as a reader
+      # writes them: due: 0 and lines[0].sku: "A" by their path, and a leaf
+      # whose path would start at a bracket as the literal that holds it,
+      # "counts" => {"discarded" => 0}. With +merge+, leaves under one key
+      # share its literal, "tests" => [{"file" => "a.rb", "state" => "ok"}];
+      # a short path does not, since its first key may sit at two depths.
+      def entries_text(entries, merge: true)
+        groups = []
+        entries.each do |path, text|
+          name = path_text(path)
+          next groups << "#{name}#{path.last.is_a?(String) ? " =>" : ":"} #{text}" unless name.start_with?("[")
+
+          group = groups.find { |other| other.is_a?(Array) && other.first.first.first == path.first } if merge
+          group ? group << [path, text] : groups << [[path, text]]
+        end
+        groups.map { |group| group.is_a?(Array) ? held_entries(group, braces: false) : group }.join(", ")
+      end
+
+      # Leaves that share a value, each a [path into it, value text], as
+      # the literal of that value, with _ for an Array element no leaf is in.
+      def held_entries(entries, braces: true)
+        return entries.first[1] if entries.first[0].empty?
+
+        steps = entries.group_by { |path, _| path.first }.transform_values { |group| group.map { |path, text| [path.drop(1), text] } }
+        return "[#{(0..steps.keys.max).map { |index| steps.key?(index) ? held_entries(steps[index]) : "_" }.join(", ")}]" if steps.keys.first.is_a?(Integer)
+
+        pairs = steps.map { |key, group| "#{key_literal(key)} #{held_entries(group)}" }.join(", ")
+        braces ? "{#{pairs}}" : pairs
+      end
+
+      def key_literal(key)
+        return "#{key.inspect} =>" unless key.is_a?(SymbolKey)
+
+        key.name.match?(/\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/) ? "#{key.name}:" : "#{key.name.to_sym.inspect} =>"
+      end
+
+      # A Symbol Hash key in a path. It is a step of its own, so a String key
+      # of the same name makes another path and the two inputs read apart.
+      SymbolKey = Data.define(:name) do
+        def to_s = name
+      end
+
+      def key_step?(step) = step.is_a?(String) || step.is_a?(SymbolKey)
+
+      def plain_step(step) = step.is_a?(SymbolKey) ? step.name : step
+
+      def key_texts(path) = path.select { |step| key_step?(step) }.map(&:to_s)
+
+      # A Code that is a plain literal, such as [{sku: "B"}], names as the
+      # value it builds, so it reads in the style of a JSON value and its
+      # Symbol keys read apart from String keys. Any other Code stays whole.
+      def written_value(value)
+        return value unless value.is_a?(Code)
+
+        body = Prism.parse(value.source).value.statements&.body || []
+        return value unless body.one?
+
+        catch(:not_plain) { return plain_literal(body.first) }
+        value
+      end
+
+      # +lines+ of Ruby, each indented by +indent+, except an empty line and
+      # a line of the body or the terminator of a << or <<- heredoc: an
+      # indented terminator of << does not end it, and <<- keeps the
+      # indentation of its body in its text. A <<~ heredoc removes the
+      # indentation its lines share, so its body is indented with the rest.
+      def indent(lines, indent)
+        kept = heredoc_lines(lines.join("\n"))
+        lines.each_with_index.map { |line, index| line.empty? || kept.include?(index + 1) ? line : "#{indent}#{line}" }
+      end
+
+      # Node types, not classes: naming a class would load prism when branchout loads, before the suite chose its version.
+      HEREDOCS = %i[string_node interpolated_string_node x_string_node interpolated_x_string_node].freeze
+
+      def heredoc_lines(source, node = Prism.parse(source).value, out = Set.new)
+        if HEREDOCS.include?(node.type) && node.opening_loc&.slice&.match?(/\A<<[-A-Za-z_"'`]/)
+          first = node.respond_to?(:content_loc) ? node.content_loc : node.parts.first&.location
+          out.merge((first || node.closing_loc).start_line..node.closing_loc.start_line)
+        end
+        node.compact_child_nodes.each { |child| heredoc_lines(source, child, out) }
+        out
+      end
+
+      # The statements of Ruby source, each as its own Code, so sources
+      # that share some lines read apart by the lines that differ.
+      def statements(code)
+        body = Prism.parse(code.source).value.statements&.body || []
+        body.length < 2 ? [code] : body.map { |node| Code.new(node.slice) }
+      end
+
+      # The call before its keyword arguments, in a path into a Ruby call.
+      # It has no name of its own, so the leaf reads as the argument.
+      CallHead = Data.define
+
+      # A Ruby call with keyword arguments, such as a factory call, as its
+      # head and each keyword, so inputs that share a long call read apart
+      # by the keywords that differ (b is "Y") and not by a cut source.
+      # Empty for any other Ruby, which stays one leaf.
+      def call_parts(code)
+        body = Prism.parse(code.source).value.statements&.body || []
+        call = body.first if body.one?
+        return tap_parts(call) if tapped?(call)
+        return [] unless call.is_a?(Prism::CallNode) && call.block.nil? && call.arguments
+
+        *positional, keywords = call.arguments.arguments
+        return [] unless keywords.is_a?(Prism::KeywordHashNode) &&
+                         keywords.elements.all? { |pair| pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode) }
+
+        head = code.source[0...keywords.location.start_offset - call.location.start_offset].sub(/[(,\s]+\z/, "")
+        head = "#{head})" if call.opening_loc && !positional.empty?
+        [[CallHead.new, Code.new(head)]] + keywords.elements.map do |pair|
+          plain = catch(:not_plain) { [plain_literal(pair.value)] }
+          [SymbolKey.new(pair.key.unescaped), plain ? plain.first : Code.new(pair.value.slice)]
+        end
+      end
+
+      # The block of a tap or then, as a step of a path. A Ruby argument
+      # that runs one, such as FactoryBot.build(:fact).tap { create(:part) },
+      # reads apart from its siblings by the block, which the call's source
+      # cut at its start would not show.
+      TapBlock = Data.define(:name)
+
+      def tapped?(call)
+        call.is_a?(Prism::CallNode) && %i[tap then].include?(call.name) && call.receiver && call.arguments.nil? &&
+          call.block.is_a?(Prism::BlockNode)
+      end
+
+      # The parts of the receiver, as call_parts gives them or as one head,
+      # then the block on one line.
+      def tap_parts(call)
+        receiver = Code.new(call.receiver.slice)
+        parts = call_parts(receiver)
+        parts = [[CallHead.new, receiver]] if parts.empty?
+        parts + [[TapBlock.new(call.name.to_s), Code.new(block_text(call.block))]]
+      end
+
+      def block_text(block)
+        body = block.body
+        statements = body.is_a?(Prism::StatementsNode) ? body.body.map(&:slice) : [body&.slice].compact
+        words = [block.opening_loc.slice, block.parameters&.slice, statements.join("; "), block.closing_loc.slice]
+        words.compact.reject(&:empty?).join(" ").gsub(/\s*\n\s*/, " ")
+      end
+
+      def plain_literal(node)
+        case node
+        when Prism::ArrayNode then node.elements.map { |item| plain_literal(item) }
+        when Prism::HashNode, Prism::KeywordHashNode
+          node.elements.to_h do |pair|
+            throw :not_plain unless pair.is_a?(Prism::AssocNode)
+
+            [plain_literal(pair.key), plain_literal(pair.value)]
+          end
+        when Prism::StringNode then node.unescaped
+        when Prism::SymbolNode then node.unescaped.to_sym
+        when Prism::IntegerNode, Prism::FloatNode then node.value
+        when Prism::NilNode then nil
+        when Prism::TrueNode then true
+        when Prism::FalseNode then false
+        else throw :not_plain
+        end
+      end
+
+      def input_words(input)
+        words = input.args.flat_map { |arg| argument_words(arg) }
+        words += input.kwargs.flat_map { |key, value| [key.to_s, *argument_words(value)] }
+        if input.receiver.is_a?(Code)
+          words += ["receiver", *value_words(input.receiver)]
+        elsif input.receiver
+          words += ["new", *input_words(input.receiver)]
+        end
+        input.setup.each { |call| words += [call.method_name, *input_words(call.arguments)] }
+        words += %w[with block] if input.block
+        words += ["after", *value_words(input.before)] if input.before
+        words
+      end
+
+      # +differing+ is the pin's entry of hash_differences: a Hash whose
+      # siblings differ in a leaf is named by those leaves.
+      def outcome_words(pin, differing = [])
+        return ["raises", *snake_words(pin.error.class_name)] if pin.error
+        return outcome_entry_words(differing) unless differing.empty?
+        return ["returns", *shape_words(pin.value)] if literal?(pin.value) || keyed?(pin.value)
+        return ["returns", "array", "of", pin.value.length.to_s] if pin.value.is_a?(Array)
+
+        ["returns", *snake_words(class_literal(pin.value))]
+      end
+
+      # A Hash whose keys all have a literal, so RSpec matches it key by key
+      # and a name can say its keys.
+      def keyed?(value) = value.is_a?(Hash) && value.each_key.all? { |key| literal?(key) }
+
+      # A Hash is named by its keys and an Array of collections by its size,
+      # so the start of a long value does not fill the name.
+      def shape_words(value)
+        case value
+        when {}, [] then ["empty", value.is_a?(Hash) ? "hash" : "array"]
+        when Hash then ["hash", *value.keys.each_with_index.map { |key, index| Key.new(key.to_s, index.positive?) }]
+        when Array
+          if value.all? { |item| composite?(item) } then ["array", "of", value.length.to_s]
+          # Any other Array says so, so [nil] is not named as nil, [3] not
+          # as 3, and ["Done", []] not as the String "Done".
+          elsif mixed_array?(value) then ["array", *value.flat_map { |item| collection?(item) ? shape_words(item) : value_words(item) }]
+          else ["array", *value_words(value)]
+          end
+        when Struct, Data then snake_words(value.class.name)
+        else value_words(value)
+        end
+      end
+
+      # A Hash argument is named by its values, a collection in it by its
+      # key and size (groups_3, tags_empty), and an Array of collections by
+      # its size, so a tree of arguments does not fill the name and two
+      # trees of different sizes read apart. An empty argument still says
+      # so (empty_array), so the name keeps every input.
+      def argument_words(value)
+        value = written_value(value)
+        case value
+        when {}, [] then shape_words(value)
+        when Hash
+          value.flat_map { |key, item| collection?(item) ? [key.to_s, item.empty? ? "empty" : item.length.to_s] : value_words(item) }
+        when Array
+          value.any? { |item| collection?(item) } ? ["array", "of", value.length.to_s] : value_words(value)
+        else value_words(value)
+        end
+      end
+
+      def collection?(value)
+        value.is_a?(Hash) || value.is_a?(Array)
+      end
+
+      # A value object reads as one thing, as a collection does, and not as
+      # the scalars it holds.
+      def composite?(value)
+        collection?(value) || value.is_a?(Struct) || value.is_a?(Data)
+      end
+
+      def mixed_array?(value)
+        value.is_a?(Array) && value.any? { |item| collection?(item) } && !value.all? { |item| collection?(item) }
+      end
+
+      # The shortest end of +path+ that starts at a Hash key and ends no
+      # other path in +paths+, so id at the top and items[0].id read apart.
+      # With no key in +path+, the whole path.
+      def telling_path(path, paths)
+        starts = path.each_index.select { |index| key_step?(path[index]) }
+        return path if starts.empty?
+
+        others = paths.reject { |other| other == path }
+        found = starts.reverse.find do |start|
+          tail = path.drop(start)
+          others.none? { |other| other.last(tail.length) == tail }
+        end
+        path.drop(found || starts.first)
+      end
+
+      # The fewest last Hash keys of +path+ that end the keys of no other
+      # path in +paths+, as one Key: items_id. Paths with the same keys,
+      # such as args[0].value and args[1].value, cannot be told apart by
+      # keys, so they do not lengthen each other's.
+      def telling_key(path, paths)
+        keys = key_texts(path)
+        return nil if keys.empty?
+
+        others = paths.map { |other| key_texts(other) }.reject { |other| other == keys }
+        length = (1..keys.length).find { |count| others.none? { |other| other.last(count) == keys.last(count) } }
+        Key.new(keys.last(length || keys.length).join(" "))
+      end
+
+      def value_words(value)
+        case value
+        when Array then value.flat_map { |item| value_words(item) }
+        when Set then value.empty? ? %w[empty set] : ["set", *value.flat_map { |item| value_words(item) }]
+        when Integer then [number_word(value)]
+        when nil then ["nil"]
+        when "" then ["empty"]
+        when /\A\s+\z/ then ["blank"]
+        when /\A[^A-Za-z0-9]+\z/ then ["text"]
+        when Numeric then [value.to_s.sub(/\A-/, "neg")]
+        when String then literal_safe([without_machine_directories(value)])
+        when Symbol then literal_safe([value.to_s])
+        else [value.to_s]
+        end
+      end
+
+      # A String or a Symbol that reads as nil, true, or false says it is
+      # text, so a name does not claim the literal for it.
+      def literal_safe(words)
+        %w[nil true false].include?(tokens(words.first).join("_")) ? ["text", *words] : words
+      end
+
+      # +value+ as a name or a description says it: a path under the
+      # project from the project root, and a path of this machine by its
+      # file alone.
+      def described(value)
+        case value
+        when ProjectPath, ProjectText then String.new(value)
+        when String then without_machine_directories(value)
+        when Array then value.map { |item| described(item) }
+        when Hash then value.transform_values { |item| described(item) }
+        else value
+        end
+      end
+
+      # The directories of a path under the home or the temporary directory
+      # differ per machine, so a name keeps only the file of such a path.
+      # A whole path may hold spaces, so it keeps all of its file name.
+      def without_machine_directories(text)
+        return File.basename(text) if machine_homes.any? { |home| text.start_with?(home) } && !text.end_with?("/")
+
+        homes = machine_homes.map { |home| Regexp.escape(home) }.join("|")
+        text.gsub(%r{(?:#{homes})(?:[^\s"\x27`(),;/]+/)*}, "")
+      end
+
+      # A number longer than LONG_NUMBER digits fills a name, so it keeps
+      # its first three digits and its power of ten: 123e46.
+      def number_word(value)
+        digits = value.abs.to_s
+        word = digits.length > LONG_NUMBER ? "#{digits[0, 3]}e#{digits.length - 3}" : digits
+        value.negative? ? "neg#{word}" : word
+      end
+
+      LONG_NUMBER = 15
+
+      def snake_words(class_name)
+        [class_name.gsub("::", "_").gsub(/([a-z\d])([A-Z])/, '\1_\2')]
+      end
+
+      # A Hash key in a name. It is one unit that a cut never splits, and a
+      # key that +follows+ another key of the same list comes after "and",
+      # so line_items reads as one key and not as the keys line and items.
+      # A key that starts a list, such as the first key of each Hash in an
+      # Array, does not follow the keys before it.
+      Key = Data.define(:text, :follows) do
+        def initialize(text:, follows: true) = super
+      end
+
+      # Joins words into identifier characters, at most +limit+ long, cut
+      # between words. Only a first word longer than +limit+ is cut inside.
+      # A key whose value the cut drops goes too, so a name never ends in a
+      # key that says nothing.
+      def clip(words, limit)
+        listed = false
+        units = words.flat_map do |word|
+          next tokens(word).map { |token| ["_", token, false] } unless word.is_a?(Key)
+
+          # A key with no letter or digit, such as "", still says it is a key,
+          # so its value is not read as the whole outcome, and so does a key
+          # that reads as nil, true, or false: {"NIL" => 0} is never
+          # returns_nil_0.
+          key = tokens(word.text).join("_")
+          key = "key" if key.empty?
+          key = "key_#{key}" if %w[nil true false].include?(key)
+
+          joiner = listed && word.follows ? "_and_" : "_"
+          listed = true
+          [[joiner, key, true]]
+        end
+        return "" if units.empty?
+
+        text = units.first[1]
+        return text[0, limit] if text.length > limit
+
+        taken = 1
+        units.drop(1).each do |joiner, unit|
+          break if text.length + joiner.length + unit.length > limit
+
+          text += joiner + unit
+          taken += 1
+        end
+        last, cut = units[taken - 1], units[taken]
+        return text.delete_suffix("#{last[0]}#{last[1]}") if last[2] && cut && !cut[2]
+
+        text
+      end
+
+      def tokens(word)
+        word.to_s.downcase.split(/[^a-z0-9]+/).reject(&:empty?)
+      end
+
+      # Why a file holds no test, in the words of the report's NOT PINNED.
+      def no_pin_reason(all_varied)
+        return "branchout did not discover an input" unless all_varied
+
+        "each input returned a value that differed between two runs, so no emitted test checks it"
+      end
+
+      def cover_comment(pin, indent)
+        return [] if pin.covers.empty?
+
+        ["#{indent}# covers:", *pin.covers.map { |cover| "#{indent}#   line #{cover.line}: #{cover.text}" }]
+      end
+
+      # Says why the Strings of a thawed input carry a +, which a reader of
+      # a frozen_string_literal file would otherwise take for noise.
+      def thawed_comment(pin, indent)
+        return [] unless pin.thawed
+
+        ["#{indent}# With frozen Strings this input raised FrozenError, so its Strings are unfrozen (+\"...\").",
+         "#{indent}# This value is from a second run, which saw what the first run changed before it raised and no " \
+         "savepoint undid, such as a global, a class variable, or a file."]
+      end
+
+      def write_file(destination, content)
+        FileUtils.mkdir_p(File.dirname(destination))
+        File.write(destination, content)
+      end
+    end
+  end
+end