branchout 0.1.0

data/lib/branchout/input.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Branchout
+  # Ruby source that an input passes in place of a JSON value: a record, an
+  # exception, or a block, which JSON cannot write. An inputs file spells it
+  # {"ruby": "Factories.loan(3)"}. Each call evaluates it again, so every
+  # call gets a new object, and an emitted test writes it as it was given.
+  Code = Data.define(:source) do
+    def self.parse(source)
+      raise Error, "Ruby #{source.inspect} does not parse" unless Prism.parse(source).errors.empty?
+
+      new(-source)
+    end
+
+    # A block as a call takes it, written with braces so it binds to the
+    # call in an emitted assertion as it did in explore.
+    def self.block(source)
+      body = Prism.parse("m #{source}").value.statements.body
+      unless source.start_with?("{") && body.length == 1 && body.first.respond_to?(:block) && body.first.block
+        raise Error, "block #{source.inspect} is not a block such as \"{ |item| item.price > 2 }\""
+      end
+
+      new(-source)
+    end
+
+    def to_s = source
+  end
+
+  # A String input that names a path under the emitted test's project. The
+  # test writes it from its own directory (+from_test+), so it passes in a
+  # copy of the project on another machine. Its text is the path from the
+  # project root, which the test's names and descriptions say.
+  class ProjectPath < String
+    attr_reader :from_test
+
+    def initialize(from_root, from_test)
+      super(from_root)
+      @from_test = -from_test
+      freeze
+    end
+  end
+
+  # A returned String or an error message that holds paths under the
+  # emitted test's project. The test writes the project root from its own
+  # directory (+root_from_test+) between the +pieces+, so it passes in a
+  # copy of the project on another machine. Its text says each path from
+  # the project root, as a ProjectPath does.
+  class ProjectText < String
+    attr_reader :pieces, :root_from_test
+
+    def initialize(pieces, root_from_test)
+      super(pieces.join)
+      @pieces = pieces.map { |piece| -piece }.freeze
+      @root_from_test = -root_from_test
+      freeze
+    end
+  end
+
+  class Input
+    # One call made on the receiver after new and before the entry.
+    # +arguments+ is an Input with no receiver and no setup of its own.
+    SetupCall = Struct.new(:method_name, :arguments) do
+      def to_h
+        arguments.to_h.merge("method" => method_name)
+      end
+    end
+
+    # +receiver+ is the Input whose arguments go to new for a Const#method
+    # entry, the Code that builds the receiver itself (a factory call that
+    # returns a saved record), or nil to call new with none. +setup+ lists
+    # the SetupCalls that build the receiver's state. +pin_keys+, when not nil, replaces
+    # --pin-keys for this input's test. It is not part of the call, so it is
+    # not in to_h. +block+ is the Code of the block the entry gets, or nil.
+    # +before+ is the Code that makes what the call reads, such as the rows
+    # a class method looks up, run first in the input's savepoint, or nil.
+    attr_reader :args, :kwargs, :receiver, :setup, :pin_keys, :block, :before
+
+    def initialize(args:, kwargs: {}, receiver: nil, setup: [], pin_keys: nil, block: nil, before: nil)
+      @args = deep_freeze(normalize(args))
+      unless @args.is_a?(Array)
+        raise Error, "input args must be an array"
+      end
+
+      raw_kwargs = kwargs || {}
+      unless raw_kwargs.is_a?(Hash)
+        raise Error, "input kwargs must be an object"
+      end
+
+      @kwargs = deep_freeze(raw_kwargs.each_with_object({}) { |(key, value), out|
+        out[key.to_s] = normalize(value)
+      })
+      @receiver = receiver
+      @setup = setup.map { |call| SetupCall.new(-call.method_name.to_s, call.arguments).freeze }.freeze
+      @pin_keys = pin_keys&.map { |key| -key }.freeze
+      @block = block
+      @before = before
+      freeze
+    end
+
+    def to_h
+      hash = {"args" => args, "kwargs" => kwargs}
+      if receiver.is_a?(Code)
+        hash["receiver"] = receiver
+      elsif receiver
+        hash["new"] = receiver.to_h
+      end
+      hash["setup"] = setup.map(&:to_h) unless setup.empty?
+      hash["block"] = block.source if block
+      hash["before"] = before if before
+      hash
+    end
+
+    def canonical
+      Canon.json(to_h)
+    end
+
+    # Short form used in the text report. An input with only args prints as
+    # the args array so an agent can paste it back into inputs.json. The
+    # entry form leaves out empty kwargs, which an inputs file may omit.
+    def text
+      return Canon.json(args) if kwargs.empty? && receiver.nil? && setup.empty? && block.nil? && before.nil?
+
+      Canon.json(short_h)
+    end
+
+    def short_h
+      hash = to_h
+      hash.delete("kwargs") if kwargs.empty?
+      hash["new"] = receiver.short_h if hash.key?("new")
+      hash["setup"] = setup.map { |call| call.arguments.short_h.merge("method" => call.method_name) } unless setup.empty?
+      hash
+    end
+
+    # Smaller is a simpler witness: absolute numeric size, then string
+    # length, and each setup call counts one.
+    def weight
+      args.sum { |value| self.class.weight_of(value) } +
+        kwargs.values.sum { |value| self.class.weight_of(value) } +
+        self.class.weight_of(receiver) +
+        setup.sum { |call| 1 + call.arguments.weight } +
+        (block ? block.source.length : 0) +
+        (before ? before.source.length : 0)
+    end
+
+    def self.weight_of(value)
+      case value
+      when Integer then value.abs
+      when Float then value.abs
+      when String then value.length
+      when Code then value.source.length
+      when Input then value.weight
+      when Array then value.length + value.sum { |item| weight_of(item) }
+      when Hash then value.length + value.values.sum { |item| weight_of(item) }
+      else 0
+      end
+    end
+
+    def self.zero(type)
+      case type
+      when "int" then 0
+      when "float" then 0.0
+      when "string" then ""
+      when "array" then []
+      when "hash" then {}
+      when "bool" then false
+      else
+        raise Error, "unknown type #{type}"
+      end
+    end
+
+    def normalize(value)
+      case value
+      when nil, true, false, Integer, ProjectPath
+        value
+      when String, Symbol
+        -value.to_s
+      when Float
+        raise Error, "non-finite float" unless value.finite?
+
+        value.zero? ? 0.0 : value
+      when Code
+        value
+      when Array
+        value.map { |item| normalize(item) }
+      when Hash
+        return Code.parse(value.values.first) if code?(value)
+
+        value.each_with_object({}) do |(key, item), out|
+          out[key.to_s] = normalize(item)
+        end
+      else
+        raise Error, "unsupported input value #{value.class}"
+      end
+    end
+
+    # {"ruby": "..."} is Ruby source. A Hash argument with one key "ruby"
+    # is written as Ruby too: {"ruby": "{\"ruby\" => \"3.4\"}"}.
+    def code?(value)
+      value.length == 1 && value.keys.first.to_s == "ruby" && value.values.first.is_a?(String)
+    end
+
+    def deep_freeze(value)
+      case value
+      when Array
+        value.each { |item| deep_freeze(item) }
+        value.freeze
+      when Hash
+        value.each { |key, item| deep_freeze(item) }
+        value.freeze
+      else
+        value
+      end
+    end
+  end
+end

data/lib/branchout/input_file.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Branchout
+  module InputFile
+    module_function
+
+    def load(path)
+      raise Error, "inputs file not found: #{path}" unless File.file?(path)
+
+      begin
+        data = JSON.parse(File.read(path))
+      rescue JSON::ParserError => e
+        raise Error, "invalid JSON in #{path}: #{e.message}"
+      end
+
+      types = nil
+      entries = data
+      if data.is_a?(Hash)
+        types = data["types"]
+        entries = data["inputs"]
+        raise Error, "#{path} is missing \"inputs\"" if entries.nil?
+      end
+      raise Error, "#{path} inputs must be an array" unless entries.is_a?(Array)
+      if types && !types.is_a?(Array)
+        raise Error, "#{path} types must be an array"
+      end
+      if types&.any? { |type| !Mutator::TYPES.include?(type) }
+        raise Error, "#{path} has an unknown type (#{Mutator::TYPES.join(", ")})"
+      end
+
+      inputs = entries.each_with_index.map { |entry, index| parse_entry(entry, "#{path} inputs[#{index}]") }
+      [inputs, types]
+    end
+
+    # Keys that say how the entry is called, so args may be left out for none.
+    CALL_KEYS = %w[new receiver setup kwargs block before].freeze
+
+    METHOD_NAME = /\A(?:[A-Za-z_][A-Za-z0-9_]*[?!=]?|<<|>>|\[\]=?|[-+*\/%&|^<>]|\*\*|<=>|==|!=|<=|>=|=~)\z/
+
+    def parse_entry(entry, label, keys = %w[args kwargs new receiver setup note pin_keys block before])
+      case entry
+      when Array
+        Input.new(args: entry)
+      when Hash
+        unknown = entry.keys - keys
+        raise Error, "#{label} has unknown keys: #{unknown.join(", ")}" unless unknown.empty?
+        unless entry.key?("args") || label.end_with?(" new") || CALL_KEYS.any? { |key| entry.key?(key) }
+          raise Error, "#{label} is missing args; write \"args\": [] for a call with no arguments"
+        end
+
+        receiver = parse_entry(entry["new"], "#{label} new", %w[args kwargs new]) if entry.key?("new")
+        raise Error, "#{label} new cannot have its own new" if receiver&.receiver
+        if entry.key?("receiver")
+          raise Error, "#{label} gives both new and receiver; receiver builds the object itself" if receiver
+
+          built = entry["receiver"]
+          raise Error, "#{label} receiver must be Ruby such as {\"ruby\": \"create(:loan)\"}" unless built.is_a?(Hash) && code?(built)
+
+          receiver = Code.parse(built["ruby"])
+        end
+
+        setup = parse_setup(entry.fetch("setup", []), "#{label} setup")
+        pin_keys = entry["pin_keys"]
+        unless pin_keys.nil? || (pin_keys.is_a?(Array) && pin_keys.all? { |key| key.is_a?(String) && !key.empty? })
+          raise Error, "#{label} pin_keys must be an array of key names"
+        end
+
+        block = Code.block(entry["block"]) if entry.key?("block")
+        if entry.key?("before")
+          raise Error, "#{label} before must be Ruby such as {\"ruby\": \"create(:part)\"}" unless entry["before"].is_a?(Hash) && code?(entry["before"])
+
+          before = Code.parse(entry["before"]["ruby"])
+        end
+        Input.new(args: entry.fetch("args", []), kwargs: entry["kwargs"] || {}, receiver: receiver, setup: setup, pin_keys: pin_keys, block: block,
+                  before: before)
+      else
+        raise Error, "#{label} is #{JSON.generate(entry)}, not a call; write each call as an array of its arguments, such as #{JSON.generate([entry])}"
+      end
+    rescue Error => e
+      raise if e.message.start_with?(label)
+
+      raise Error, "#{label} #{e.message}"
+    end
+
+    # A String argument wrapped in its own quotes, as "\"0306406150\"", is
+    # most often Ruby or JSON source written where a JSON value goes, and
+    # the method then gets the quotes too.
+    def quoted_strings(inputs)
+      inputs.each_with_index.flat_map do |input, index|
+        named = input.args.each_with_index.map { |value, at| ["args[#{at}]", value] } +
+                input.kwargs.map { |key, value| ["kwargs.#{key}", value] }
+        named.filter_map do |place, value|
+          next unless value.is_a?(String) && value.length >= 2 && value.match?(/\A(["']).*\z/m)
+
+          unquoted = value[1...-1]
+          "inputs[#{index}] #{place} is the String #{value.inspect}, quotes included. " \
+            "An inputs file is JSON, so write #{unquoted.inspect} for the #{unquoted.empty? ? "empty String" : "String #{unquoted}"}, " \
+            "or {\"ruby\": \"...\"} for Ruby source. Keep the quotes only if the method should get them."
+        end
+      end
+    end
+
+    def code?(value)
+      value.keys == ["ruby"] && value["ruby"].is_a?(String)
+    end
+
+    def parse_setup(steps, label)
+      raise Error, "#{label} must be an array" unless steps.is_a?(Array)
+
+      steps.each_with_index.map do |step, index|
+        step_label = "#{label}[#{index}]"
+        raise Error, "#{step_label} must be an object" unless step.is_a?(Hash)
+
+        unknown = step.keys - %w[method args kwargs]
+        raise Error, "#{step_label} has unknown keys: #{unknown.join(", ")}" unless unknown.empty?
+        raise Error, "#{step_label} is missing method" unless step.key?("method")
+
+        name = step["method"]
+        raise Error, "#{step_label} method #{name.inspect} is not a method name" unless name.is_a?(String) && METHOD_NAME.match?(name)
+
+        Input::SetupCall.new(name, Input.new(args: step.fetch("args", []), kwargs: step["kwargs"] || {}))
+      end
+    end
+  end
+end

data/lib/branchout/mutator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Branchout
+  # Literal mutation in the style of a cheap comparison-guided fuzzer.
+  # Every source literal is tried in each argument slot. A capped cartesian
+  # product of the first two numeric slots comes after that, so a magic
+  # constant is not dropped just because it sorts late.
+  class Mutator
+    TYPES = %w[int float string array hash bool].freeze
+
+    def initialize(target, cap:)
+      @target = target
+      @cap = cap
+      raise Error, "mutate-cap must be >= 0" if cap.negative?
+    end
+
+    # A slot is one value an input passes: a positional or required keyword
+    # parameter of the entry, or of initialize when the entry is an instance
+    # method. Optional keywords keep their defaults.
+    Slot = Struct.new(:owner, :param)
+
+    def inputs
+      return [] if @cap.zero?
+
+      slots = slots_of(:entry, @target.parameters) + slots_of(:new, @target.constructor)
+      base = slots.to_h { |slot| [slot, base_value(slot.param)] }
+      pools = slots.to_h { |slot| [slot, pool_for(slot.param)] }
+
+      tier_one = [build(base)]
+      slots.each do |slot|
+        pools[slot].each { |value| tier_one << build(base.merge(slot => value)) }
+      end
+
+      tier_two = []
+      first, second = slots.select { |slot| slot.owner == :entry && slot.param.kind != :keyreq }
+      if second && numeric?(first.param) && numeric?(second.param)
+        pools[first].each do |left|
+          pools[second].each { |right| tier_two << build(base.merge(first => left, second => right)) }
+        end
+      end
+
+      deduped = []
+      seen = {}
+      (sort_inputs(tier_one) + sort_inputs(tier_two)).each do |input|
+        key = input.canonical
+        next if seen[key]
+
+        seen[key] = true
+        deduped << input
+        break if deduped.length >= @cap
+      end
+      deduped
+    end
+
+    # Every input passes each required keyword, or the call stops at
+    # ArgumentError before the method body runs.
+    def slots_of(owner, parameters)
+      parameters.select { |param| %i[req opt keyreq].include?(param.kind) }.map { |param| Slot.new(owner, param) }
+    end
+
+    def build(values)
+      entry = values.select { |slot, _| slot.owner == :entry }
+      made = values.reject { |slot, _| slot.owner == :entry }
+      receiver = arguments(made) unless @target.constructor.empty?
+      arguments(entry, receiver)
+    end
+
+    def arguments(values, receiver = nil)
+      args = values.reject { |slot, _| slot.param.kind == :keyreq }.values
+      kwargs = values.select { |slot, _| slot.param.kind == :keyreq }.to_h { |slot, value| [slot.param.name.to_s, value] }
+      Input.new(args: args, kwargs: kwargs, receiver: receiver)
+    end
+
+    def pool_for(param)
+      literals = @target.literals
+      case param.inferred_type
+      when "int"
+        values = [0, 1, -1]
+        values.concat(literals.ints)
+        values.concat(literals.ints.flat_map { |number| [number - 1, number + 1] })
+        values << param.default if param.default.is_a?(Integer)
+        values.grep(Integer).uniq.sort
+      when "float"
+        values = [0.0, 1.0, -1.0]
+        values.concat(literals.floats)
+        values.concat(literals.ints.map(&:to_f))
+        values.concat(values.flat_map { |number| [number - 1.0, number + 1.0] })
+        values << param.default if param.default.is_a?(Float)
+        values.grep(Float).select(&:finite?).map { |number| number.zero? ? 0.0 : number }.uniq.sort
+      when "string"
+        values = ["", "a"]
+        values.concat(literals.strings)
+        values << param.default if param.default.is_a?(String)
+        literals.strings.each do |text|
+          values << text[0..-2].to_s
+          values << "#{text}1"
+        end
+        values.uniq.sort
+      when "array"
+        [[], [0], [1], [0, 1]]
+      when "hash"
+        [{}, {"a" => 0}, {"a" => 1}]
+      when "bool"
+        [false, true]
+      else
+        [Input.zero(param.inferred_type || "int")]
+      end
+    end
+
+    def base_value(param)
+      return param.default unless param.default.nil?
+
+      Input.zero(param.inferred_type)
+    end
+
+    def numeric?(param)
+      param.inferred_type == "int" || param.inferred_type == "float"
+    end
+
+    def sort_inputs(list)
+      list.sort_by(&:canonical)
+    end
+  end
+end

data/lib/branchout/prism_choice.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Branchout
+  # Outside a bundle the first require of prism activates the newest one,
+  # and a target that then requires a gem pinned to an older prism, as
+  # minitest 6 is to prism ~> 1.5, fails to activate that gem. The CLI
+  # parses the target before it loads it, so it activates the newest prism
+  # that the newest installed version of every gem accepts.
+  module PrismChoice
+    module_function
+
+    def activate
+      return if defined?(::Bundler) || Gem.loaded_specs.key?("prism")
+
+      version = accepted(Gem::Specification.find_all_by_name("prism").map(&:version), Gem::Specification.to_a)
+      gem "prism", "= #{version}" if version
+    end
+
+    def accepted(versions, specs)
+      newest = specs.group_by(&:name).map { |_, same| same.max_by(&:version) }
+      wanted = newest.flat_map { |spec| spec.runtime_dependencies.select { |dep| dep.name == "prism" }.map(&:requirement) }
+      versions.select { |version| wanted.all? { |requirement| requirement.satisfied_by?(version) } }.max
+    end
+  end
+end