sorbet-runtime 0.0.1.pre.prealpha → 0.4.4253

data/lib/types/configuration.rb

@@ -0,0 +1,368 @@
+# typed: true
+# frozen_string_literal: true
+
+module T::Configuration
+  # Set a handler to handle `TypeError`s raised by any in-line type assertions,
+  # including `T.must`, `T.let`, `T.cast`, and `T.assert_type!`.
+  #
+  # By default, any `TypeError`s detected by this gem will be raised. Setting
+  # inline_type_error_handler to an object that implements :call (e.g. proc or
+  # lambda) allows users to customize the behavior when a `TypeError` is
+  # raised on any inline type assertion.
+  #
+  # @param [Lambda, Proc, Object, nil] value Proc that handles the error (pass
+  #   nil to reset to default behavior)
+  #
+  # Parameters passed to value.call:
+  #
+  # @param [TypeError] error TypeError that was raised
+  #
+  # @example
+  #   T::Configuration.inline_type_error_handler = lambda do |error|
+  #     puts error.message
+  #   end
+  def self.inline_type_error_handler=(value)
+    validate_lambda_given!(value)
+    @inline_type_error_handler = value
+  end
+
+  private_class_method def self.inline_type_error_handler_default(error)
+    raise error
+  end
+
+  def self.inline_type_error_handler(error)
+    if @inline_type_error_handler
+      @inline_type_error_handler.call(error)
+    else
+      inline_type_error_handler_default(error)
+    end
+  end
+
+  # Set a handler to handle errors that occur when the builder methods in the
+  # body of a sig are executed. The sig builder methods are inside a proc so
+  # that they can be lazily evaluated the first time the method being sig'd is
+  # called.
+  #
+  # By default, improper use of the builder methods within the body of a sig
+  # cause an ArgumentError to be raised. Setting sig_builder_error_handler to an
+  # object that implements :call (e.g. proc or lambda) allows users to
+  # customize the behavior when a sig can't be built for some reason.
+  #
+  # @param [Lambda, Proc, Object, nil] value Proc that handles the error (pass
+  #   nil to reset to default behavior)
+  #
+  # Parameters passed to value.call:
+  #
+  # @param [StandardError] error The error that was raised
+  # @param [Thread::Backtrace::Location] location Location of the error
+  #
+  # @example
+  #   T::Configuration.sig_builder_error_handler = lambda do |error, location|
+  #     puts error.message
+  #   end
+  def self.sig_builder_error_handler=(value)
+    validate_lambda_given!(value)
+    @sig_builder_error_handler = value
+  end
+
+  private_class_method def self.sig_builder_error_handler_default(error, location)
+    T::Private::Methods.sig_error(location, error.message)
+  end
+
+  def self.sig_builder_error_handler(error, location)
+    if @sig_builder_error_handler
+      @sig_builder_error_handler.call(error, location)
+    else
+      sig_builder_error_handler_default(error, location)
+    end
+  end
+
+  # Set a handler to handle sig validation errors.
+  #
+  # Sig validation errors include things like abstract checks, override checks,
+  # and type compatibility of arguments. They happen after a sig has been
+  # successfully built, but the built sig is incompatible with other sigs in
+  # some way.
+  #
+  # By default, sig validation errors cause an exception to be raised. One
+  # exception is for `generated` sigs, for which a message will be logged
+  # instead of raising. Setting sig_validation_error_handler to an object that
+  # implements :call (e.g. proc or lambda) allows users to customize the
+  # behavior when a method signature's build fails.
+  #
+  # @param [Lambda, Proc, Object, nil] value Proc that handles the error (pass
+  #   nil to reset to default behavior)
+  #
+  # Parameters passed to value.call:
+  #
+  # @param [StandardError] error The error that was raised
+  # @param [Hash] opts A hash containing contextual information on the error:
+  # @option opts [Method, UnboundMethod] :method Method on which the signature build failed
+  # @option opts [T::Private::Methods::Declaration] :declaration Method
+  #   signature declaration struct
+  # @option opts [T::Private::Methods::Signature, nil] :signature Signature
+  #   that failed (nil if sig build failed before Signature initialization)
+  # @option opts [T::Private::Methods::Signature, nil] :super_signature Super
+  #   method's signature (nil if method is not an override or super method
+  #   does not have a method signature)
+  #
+  # @example
+  #   T::Configuration.sig_validation_error_handler = lambda do |error, opts|
+  #     puts error.message
+  #   end
+  def self.sig_validation_error_handler=(value)
+    validate_lambda_given!(value)
+    @sig_validation_error_handler = value
+  end
+
+  private_class_method def self.sig_validation_error_handler_default(error, opts)
+    # if this method overrides a generated signature, report that one instead
+    bad_method = opts[:method]
+    if !opts[:declaration].generated
+      super_signature = opts[:super_signature]
+      raise error if !super_signature&.generated
+      bad_method = super_signature.method
+    end
+
+    method_file, method_line = bad_method.source_location
+    T::Configuration.log_info_handler(
+      "SIG-DECLARE-FAILED",
+      {
+        definition_file: method_file,
+        definition_line: method_line,
+        kind: "Delete",
+        message: error.message,
+      },
+    )
+  end
+
+  def self.sig_validation_error_handler(error, opts)
+    if @sig_validation_error_handler
+      @sig_validation_error_handler.call(error, opts)
+    else
+      sig_validation_error_handler_default(error, opts)
+    end
+  end
+
+  # Set a handler for type errors that result from calling a method.
+  #
+  # By default, errors from calling a method cause an exception to be raised.
+  # One exception is for `generated` sigs, for which a message will be logged
+  # instead of raising. Setting call_validation_error_handler to an object that
+  # implements :call (e.g. proc or lambda) allows users to customize the
+  # behavior when a method is called with invalid parameters, or returns an
+  # invalid value.
+  #
+  # @param [Lambda, Proc, Object, nil] value Proc that handles the error
+  #   report (pass nil to reset to default behavior)
+  #
+  # Parameters passed to value.call:
+  #
+  # @param [T::Private::Methods::Signature] signature Signature that failed
+  # @param [Hash] opts A hash containing contextual information on the error:
+  # @option opts [String] :message Error message
+  # @option opts [String] :kind One of:
+  #   ['Parameter', 'Block parameter', 'Return value']
+  # @option opts [Symbol] :name Param or block param name (nil for return
+  #   value)
+  # @option opts [Object] :type Expected param/return value type
+  # @option opts [Object] :value Actual param/return value
+  # @option opts [Thread::Backtrace::Location] :location Location of the
+  #   caller
+  #
+  # @example
+  #   T::Configuration.call_validation_error_handler = lambda do |signature, opts|
+  #     puts opts[:message]
+  #   end
+  def self.call_validation_error_handler=(value)
+    validate_lambda_given!(value)
+    @call_validation_error_handler = value
+  end
+
+  private_class_method def self.call_validation_error_handler_default(signature, opts)
+    method_file, method_line = signature.method.source_location
+    location = opts[:location]
+    suffix = "Caller: #{location.path}:#{location.lineno}\n" \
+      "Definition: #{method_file}:#{method_line}"
+
+    error_message = "#{opts[:kind]}#{opts[:name] ? " '#{opts[:name]}'" : ''}: #{opts[:message]}\n#{suffix}"
+
+    if signature.generated
+      got = opts[:value].class
+      got = T.unsafe(T::Enumerable[T.untyped]).describe_obj(opts[:value]) if got < Enumerable
+      T::Configuration.log_info_handler(
+        "SIG-CHECK-FAILED",
+        {
+          caller_file: location.path,
+          caller_line: location.lineno,
+          definition_file: method_file,
+          definition_line: method_line,
+          kind: opts[:kind],
+          name: opts[:name],
+          expected: opts[:type].name,
+          got: got,
+        },
+      )
+    elsif signature.soft_notify
+      T::Configuration.soft_assert_handler(
+        "TypeError: #{error_message}",
+        {notify: signature.soft_notify}
+      )
+    else
+      begin
+        raise TypeError.new(error_message)
+      rescue TypeError => e # raise into rescue to ensure e.backtrace is populated
+        T::Private::ErrorHandler.handle_inline_type_error(e)
+      end
+    end
+  end
+
+  def self.call_validation_error_handler(signature, opts)
+    if @call_validation_error_handler
+      @call_validation_error_handler.call(signature, opts)
+    else
+      call_validation_error_handler_default(signature, opts)
+    end
+  end
+
+  # Set a handler for logging
+  #
+  # @param [Lambda, Proc, Object, nil] value Proc that handles the error
+  #   report (pass nil to reset to default behavior)
+  #
+  # Parameters passed to value.call:
+  #
+  # @param [String] str Message to be logged
+  # @param [Hash] extra A hash containing additional parameters to be passed along to the logger.
+  #
+  # @example
+  #   T::Configuration.log_info_handler = lambda do |str, extra|
+  #     puts "#{str}, context: #{extra}"
+  #   end
+  def self.log_info_handler=(value)
+    validate_lambda_given!(value)
+    @log_info_handler = value
+  end
+
+  private_class_method def self.log_info_handler_default(str, extra)
+    puts "#{str}, extra: #{extra}" # rubocop:disable PrisonGuard/NoBarePuts
+  end
+
+  def self.log_info_handler(str, extra)
+    if @log_info_handler
+      @log_info_handler.call(str, extra)
+    else
+      log_info_handler_default(str, extra)
+    end
+  end
+
+  # Set a handler for soft assertions
+  #
+  # These generally shouldn't stop execution of the program, but rather inform
+  # some party of the assertion to action on later.
+  #
+  # @param [Lambda, Proc, Object, nil] value Proc that handles the error
+  #   report (pass nil to reset to default behavior)
+  #
+  # Parameters passed to value.call:
+  #
+  # @param [String] str Assertion message
+  # @param [Hash] extra A hash containing additional parameters to be passed along to the handler.
+  #
+  # @example
+  #   T::Configuration.soft_assert_handler = lambda do |str, extra|
+  #     puts "#{str}, context: #{extra}"
+  #   end
+  def self.soft_assert_handler=(value)
+    validate_lambda_given!(value)
+    @soft_assert_handler = value
+  end
+
+  private_class_method def self.soft_assert_handler_default(str, extra)
+    puts "#{str}, extra: #{extra}" # rubocop:disable PrisonGuard/NoBarePuts
+  end
+
+  def self.soft_assert_handler(str, extra)
+    if @soft_assert_handler
+      @soft_assert_handler.call(str, extra)
+    else
+      soft_assert_handler_default(str, extra)
+    end
+  end
+
+  # Set a handler for hard assertions
+  #
+  # These generally should stop execution of the program, and optionally inform
+  # some party of the assertion.
+  #
+  # @param [Lambda, Proc, Object, nil] value Proc that handles the error
+  #   report (pass nil to reset to default behavior)
+  #
+  # Parameters passed to value.call:
+  #
+  # @param [String] str Assertion message
+  # @param [Hash] extra A hash containing additional parameters to be passed along to the handler.
+  #
+  # @example
+  #   T::Configuration.hard_assert_handler = lambda do |str, extra|
+  #     raise "#{str}, context: #{extra}"
+  #   end
+  def self.hard_assert_handler=(value)
+    validate_lambda_given!(value)
+    @hard_assert_handler = value
+  end
+
+  private_class_method def self.hard_assert_handler_default(str, _)
+    raise str
+  end
+
+  def self.hard_assert_handler(str, extra)
+    if @hard_assert_handler
+      @hard_assert_handler.call(str, extra)
+    else
+      hard_assert_handler_default(str, extra)
+    end
+  end
+
+  # Set a list of class strings that are to be considered scalar.
+  #   (pass nil to reset to default behavior)
+  #
+  # @param [String] value Class name.
+  #
+  # @example
+  #   T::Configuration.scalar_types = ["NilClass", "TrueClass", "FalseClass", ...]
+  def self.scalar_types=(values)
+    if values.nil?
+      @scalar_tyeps = values
+    else
+      bad_values = values.select {|v| v.class != String}
+      unless bad_values.empty?
+        raise ArgumentError.new("Provided values must all be class name strings.")
+      end
+
+      @scalar_types = Set.new(values).freeze
+    end
+  end
+
+  @default_scalar_types = Set.new(%w{
+    NilClass
+    TrueClass
+    FalseClass
+    Integer
+    Float
+    String
+    Symbol
+    Time
+  }).freeze
+
+  def self.scalar_types
+    @scalar_types || @default_scalar_types
+  end
+
+
+  private_class_method def self.validate_lambda_given!(value)
+    if !value.nil? && !value.respond_to?(:call)
+      raise ArgumentError.new("Provided value must respond to :call")
+    end
+  end
+end

data/lib/types/generic.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# typed: true
+
+# Use as a mixin with extend (`extend T::Generic`).
+# Docs at https://hackpad.corp.stripe.com/Type-Validation-in-pay-server-1JaoTHir5Mo.
+module T::Generic
+  include T::Helpers
+  include Kernel
+
+  ### Class/Module Helpers ###
+
+  def [](*types)
+    self
+  end
+
+  def type_member(variance=:invariant, fixed: nil)
+    T::Types::TypeMember.new(variance) # rubocop:disable PrisonGuard/UseOpusTypesShortcut
+  end
+
+  def type_template(variance=:invariant, fixed: nil)
+    T::Types::TypeTemplate.new(variance) # rubocop:disable PrisonGuard/UseOpusTypesShortcut
+  end
+end

data/lib/types/helpers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# typed: true
+
+# Use as a mixin with extend (`extend T::Helpers`).
+# Docs at https://confluence.corp.stripe.com/display/PRODINFRA/Ruby+Types
+module T::Helpers
+  Private = T::Private
+
+  ### Class/Module Helpers ###
+
+  def abstract!
+    Private::Abstract::Declare.declare_abstract(self, type: :abstract)
+  end
+
+  def interface!
+    Private::Abstract::Declare.declare_abstract(self, type: :interface)
+  end
+
+  # Causes a mixin to also mix in class methods from the named module.
+  #
+  # Nearly equivalent to
+  #
+  #  def self.included(other)
+  #    other.extend(mod)
+  #  end
+  #
+  # Except that it is statically analyzed by sorbet.
+  def mixes_in_class_methods(mod)
+    Private::Mixins.declare_mixes_in_class_methods(self, mod)
+  end
+end

data/lib/types/interface_wrapper.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+# typed: false
+
+# Wraps an object, exposing only the methods defined on a given class/module. The idea is that, in
+# the absence of a static type checker that would prevent you from calling non-Bar methods on a
+# variable of type Bar, we can use these wrappers as a way of enforcing it at runtime.
+#
+# Once we ship static type checking, we should get rid of this entirely.
+class T::InterfaceWrapper
+  extend T::Sig
+
+  module Helpers
+    def wrap_instance(obj)
+      T::InterfaceWrapper.wrap_instance(obj, self)
+    end
+
+    def wrap_instances(arr)
+      T::InterfaceWrapper.wrap_instances(arr, self)
+    end
+  end
+
+  private_class_method :new # use `wrap_instance`
+
+  def self.wrap_instance(obj, interface_mod)
+    wrapper = wrapped_dynamic_cast(obj, interface_mod)
+    if wrapper.nil?
+      raise "#{obj.class} cannot be cast to #{interface_mod}"
+    end
+    wrapper
+  end
+
+  sig do
+    params(
+      arr: Array,
+      interface_mod: T.untyped
+    )
+    .returns(Array)
+  end
+  def self.wrap_instances(arr, interface_mod)
+    arr.map {|instance| self.wrap_instance(instance, interface_mod)}
+  end
+
+  def initialize(target_obj, interface_mod)
+    if target_obj.is_a?(T::InterfaceWrapper)
+      # wrapped_dynamic_cast should guarantee this never happens.
+      raise "Unexpected: wrapping a wrapper. Please report to #dev-productivity."
+    end
+
+    if !target_obj.is_a?(interface_mod)
+      # wrapped_dynamic_cast should guarantee this never happens.
+      raise "Unexpected: `is_a?` failed. Please report to #dev-productivity."
+    end
+
+    if target_obj.class == interface_mod
+      # wrapped_dynamic_cast should guarantee this never happens.
+      raise "Unexpected: exact class match. Please report to #dev-productivity."
+    end
+
+    @target_obj = target_obj
+    @interface_mod = interface_mod
+    self_methods = self.class.self_methods
+
+    # If perf becomes an issue, we can define these on an anonymous subclass, and keep a cache
+    # so we only need to do it once per unique `interface_mod`
+    T::Utils.methods_excluding_object(interface_mod).each do |method_name|
+      if self_methods.include?(method_name)
+        raise "interface_mod has a method that conflicts with #{self.class}: #{method_name}"
+      end
+
+      define_singleton_method(method_name) do |*args, &blk|
+        target_obj.send(method_name, *args, &blk)
+      end
+
+      if target_obj.singleton_class.public_method_defined?(method_name)
+        # no-op, it's already public
+      elsif target_obj.singleton_class.protected_method_defined?(method_name)
+        singleton_class.send(:protected, method_name)
+      elsif target_obj.singleton_class.private_method_defined?(method_name)
+        singleton_class.send(:private, method_name)
+      else
+        raise "This should never happen. Report to #dev-productivity"
+      end
+    end
+  end
+
+  def kind_of?(other) # rubocop:disable PrisonGuard/BanBuiltinMethodOverride
+    is_a?(other)
+  end
+
+  def is_a?(other) # rubocop:disable PrisonGuard/BanBuiltinMethodOverride
+    if !other.is_a?(Module)
+      raise TypeError.new("class or module required")
+    end
+
+    # This makes is_a? return true for T::InterfaceWrapper (and its ancestors),
+    # as well as for @interface_mod and its ancestors.
+    self.class <= other || @interface_mod <= other
+  end
+
+  # Prefixed because we're polluting the namespace of the interface we're wrapping, and we don't
+  # want anyone else (besides dynamic_cast) calling it.
+  def __target_obj_DO_NOT_USE
+    @target_obj
+  end
+
+  # Prefixed because we're polluting the namespace of the interface we're wrapping, and we don't
+  # want anyone else (besides wrapped_dynamic_cast) calling it.
+  def __interface_mod_DO_NOT_USE
+    @interface_mod
+  end
+
+  # "Cast" an object to another type. If `obj` is an InterfaceWrapper, returns the the wrapped
+  # object if that matches `type`. Otherwise, returns `obj` if it matches `type`. Otherwise,
+  # returns nil.
+  #
+  # @param obj [Object] object to cast
+  # @param mod [Module] type to cast `obj` to
+  #
+  # @example
+  #   if (impl = T::InterfaceWrapper.dynamic_cast(iface, MyImplementation))
+  #     impl.do_things
+  #   end
+  def self.dynamic_cast(obj, mod)
+    if obj.is_a?(T::InterfaceWrapper)
+      target_obj = obj.__target_obj_DO_NOT_USE
+      target_obj.is_a?(mod) ? target_obj : nil
+    elsif obj.is_a?(mod)
+      obj
+    else
+      nil
+    end
+  end
+
+  # Like dynamic_cast, but puts the result in its own wrapper if necessary.
+  #
+  # @param obj [Object] object to cast
+  # @param mod [Module] type to cast `obj` to
+  def self.wrapped_dynamic_cast(obj, mod)
+    # Avoid unwrapping and creating an equivalent wrapper.
+    if obj.is_a?(T::InterfaceWrapper) && obj.__interface_mod_DO_NOT_USE == mod
+      return obj
+    end
+
+    cast_obj = dynamic_cast(obj, mod)
+    if cast_obj.nil?
+      nil
+    elsif cast_obj.class == mod
+      # Nothing to wrap, they want the full class
+      cast_obj
+    else
+      new(cast_obj, mod)
+    end
+  end
+
+  def self.self_methods
+    @self_methods ||= self.instance_methods(false).to_set
+  end
+end