sorbet-runtime 0.0.1.pre.prealpha → 0.4.4253

data/lib/types/private/methods/decl_builder.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+# typed: true
+
+module T::Private::Methods
+  Declaration = Struct.new(:mod, :params, :returns, :bind, :mode, :checked, :finalized, :soft_notify, :override_allow_incompatible, :type_parameters, :generated)
+
+  class DeclBuilder
+    attr_reader :decl
+
+    class BuilderError < StandardError; end
+
+    private def check_live!
+      if decl.finalized
+        raise BuilderError.new("You can't modify a signature declaration after it has been used.")
+      end
+    end
+
+    def initialize(mod)
+      # TODO RUBYPLAT-1278 - with ruby 2.5, use kwargs here
+      @decl = Declaration.new(
+        mod,
+        ARG_NOT_PROVIDED, # params
+        ARG_NOT_PROVIDED, # returns
+        ARG_NOT_PROVIDED, # bind
+        Modes.standard, # mode
+        ARG_NOT_PROVIDED, # checked
+        false, # finalized
+        ARG_NOT_PROVIDED, # soft_notify
+        nil, # override_allow_incompatible
+        ARG_NOT_PROVIDED, # type_parameters
+        ARG_NOT_PROVIDED, # generated
+      )
+    end
+
+    def params(params)
+      check_live!
+      if !decl.params.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .params twice")
+      end
+
+      decl.params = params
+
+      self
+    end
+
+    def returns(type)
+      check_live!
+      if decl.returns.is_a?(T::Private::Types::Void)
+        raise BuilderError.new("You can't call .returns after calling .void.")
+      end
+      if !decl.returns.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .returns multiple times in a signature.")
+      end
+
+      decl.returns = type
+
+      self
+    end
+
+    def void
+      check_live!
+      if !decl.returns.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .void after calling .returns.")
+      end
+
+      decl.returns = T::Private::Types::Void.new
+
+      self
+    end
+
+    def bind(type)
+      check_live!
+      if !decl.bind.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .bind multiple times in a signature.")
+      end
+
+      decl.bind = type
+
+      self
+    end
+
+    def checked(level)
+      if T.unsafe(true)
+        raise "The .checked API is unstable, so we don't want it used until we redesign it. To change Sorbet's runtime behavior, see https://sorbet.org/docs/tconfiguration"
+      end
+      check_live!
+
+      if !decl.checked.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .checked multiple times in a signature.")
+      end
+      if !decl.soft_notify.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't use .checked with .soft.")
+      end
+      if !decl.generated.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't use .checked with .generated.")
+      end
+      if !T::Private::RuntimeLevels::LEVELS.include?(level)
+        raise BuilderError.new("Invalid `checked` level '#{level}'. Use one of: #{T::Private::RuntimeLevels::LEVELS}.")
+      end
+
+      decl.checked = level
+
+      self
+    end
+
+    def soft(notify:)
+      if T.unsafe(true)
+        raise "The .soft API is unstable, so we don't want it used until we redesign it. To change Sorbet's runtime behavior, see https://sorbet.org/docs/tconfiguration"
+      end
+      check_live!
+
+      if !decl.soft_notify.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .soft multiple times in a signature.")
+      end
+      if !decl.checked.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't use .soft with .checked.")
+      end
+      if !decl.generated.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't use .soft with .generated.")
+      end
+
+      # TODO consider validating that :notify is a project that sentry knows about,
+      # as per https://git.corp.stripe.com/stripe-internal/pay-server/blob/master/lib/event/job/sentry_job.rb#L125
+      if !notify || notify == ''
+        raise BuilderError.new("You can't provide an empty notify to .soft().")
+      end
+
+      decl.soft_notify = notify
+
+      self
+    end
+
+    def generated
+      if T.unsafe(true)
+        raise "The .generated API is unstable, so we don't want it used until we redesign it. To change Sorbet's runtime behavior, see https://sorbet.org/docs/tconfiguration"
+      end
+      check_live!
+
+      if !decl.generated.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .generated multiple times in a signature.")
+      end
+      if !decl.checked.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't use .generated with .checked.")
+      end
+      if !decl.soft_notify.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't use .generated with .soft.")
+      end
+
+      decl.generated = true
+
+      self
+    end
+
+    def abstract
+      check_live!
+
+      case decl.mode
+      when Modes.standard
+        decl.mode = Modes.abstract
+      when Modes.abstract
+        raise BuilderError.new(".abstract cannot be repeated in a single signature")
+      else
+        raise BuilderError.new("`.abstract` cannot be combined with any of `.override`, `.implementation`, or "\
+              "`.overridable`.")
+      end
+
+      self
+    end
+
+    def override(allow_incompatible: false)
+      check_live!
+
+      case decl.mode
+      when Modes.standard
+        decl.mode = Modes.override
+        decl.override_allow_incompatible = allow_incompatible
+      when Modes.override
+        raise BuilderError.new(".override cannot be repeated in a single signature")
+      else
+        raise BuilderError.new("`.override` cannot be combined with any of `.abstract`, `.implementation`, or "\
+              "`.overridable`.")
+      end
+
+      self
+    end
+
+    def overridable
+      check_live!
+
+      case decl.mode
+      when Modes.abstract, Modes.override
+        raise BuilderError.new("`.overridable` cannot be combined with `.#{decl.mode}`")
+      when Modes.standard
+        decl.mode = Modes.overridable
+      when Modes.implementation
+        decl.mode = Modes.overridable_implementation
+      when Modes.overridable, Modes.overridable_implementation
+        raise BuilderError.new(".overridable cannot be repeated in a single signature")
+      end
+
+      self
+    end
+
+    def implementation
+      check_live!
+
+      case decl.mode
+      when Modes.abstract, Modes.override
+        raise BuilderError.new("`.implementation` cannot be combined with `.#{decl.mode}`")
+      when Modes.standard
+        decl.mode = Modes.implementation
+      when Modes.overridable
+        decl.mode = Modes.overridable_implementation
+      when Modes.implementation, Modes.overridable_implementation
+        raise BuilderError.new(".implementation cannot be repeated in a single signature")
+      end
+
+      self
+    end
+
+    # Declares valid type paramaters which can be used with `T.type_parameter` in
+    # this `sig`.
+    #
+    # This is used for generic methods. Example usage:
+    #
+    #  sig do
+    #    type_parameters(:U)
+    #    .params(blk: T.proc.params(arg0: Elem).returns(T.type_parameter(:U)))
+    #    .returns(T::Array[T.type_parameter(:U)])
+    #  end
+    #  def map(&blk); end
+    def type_parameters(*names)
+      check_live!
+
+      names.each do |name|
+        raise BuilderError.new("not a symbol: #{name}") unless name.is_a?(Symbol)
+      end
+
+      if !decl.type_parameters.equal?(ARG_NOT_PROVIDED)
+        raise BuilderError.new("You can't call .type_parameters multiple times in a signature.")
+      end
+
+      decl.type_parameters = names
+
+      self
+    end
+
+    def finalize!
+      check_live!
+
+      if decl.bind.equal?(ARG_NOT_PROVIDED)
+        decl.bind = nil
+      end
+      if decl.checked.equal?(ARG_NOT_PROVIDED)
+        decl.checked = :always
+      end
+      if decl.soft_notify.equal?(ARG_NOT_PROVIDED)
+        decl.soft_notify = nil
+      end
+      if decl.generated.equal?(ARG_NOT_PROVIDED)
+        decl.generated = false
+      end
+      if decl.params.equal?(ARG_NOT_PROVIDED)
+        decl.params = {}
+      end
+      if decl.type_parameters.equal?(ARG_NOT_PROVIDED)
+        decl.type_parameters = {}
+      end
+
+      decl.finalized = true
+
+      self
+    end
+  end
+end

data/lib/types/private/methods/modes.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# typed: true
+
+module T::Private::Methods::Modes
+  def self.standard; 'standard'; end
+  def self.abstract; 'abstract'; end
+  def self.overridable; 'overridable'; end
+  def self.implementation; 'implementation'; end
+  def self.override; 'override'; end
+  def self.overridable_implementation; 'overridable_implementation'; end
+  def self.untyped; 'untyped'; end
+  MODES = [self.standard, self.abstract, self.overridable, self.implementation, self.override, self.overridable_implementation, self.untyped]
+
+  IMPLEMENT_MODES = [self.implementation, self.overridable_implementation]
+  OVERRIDABLE_MODES = [self.override, self.overridable, self.overridable_implementation, self.untyped]
+  OVERRIDE_MODES = [self.override]
+  NON_OVERRIDE_MODES = MODES - OVERRIDE_MODES - IMPLEMENT_MODES
+end

data/lib/types/private/methods/signature.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+# typed: true
+
+class T::Private::Methods::Signature
+  attr_reader :method, :method_name, :arg_types, :kwarg_types, :block_type, :block_name,
+              :rest_type, :rest_name, :keyrest_type, :keyrest_name, :bind,
+              :return_type, :mode, :req_arg_count, :req_kwarg_names, :has_rest, :has_keyrest,
+              :check_level, :generated, :parameters, :soft_notify, :override_allow_incompatible, :ever_failed
+
+  def self.new_untyped(method:, mode: T::Private::Methods::Modes.untyped, parameters: method.parameters)
+    # Using `Untyped` ensures we'll get an error if we ever try validation on these.
+    not_typed = T::Private::Types::NotTyped.new
+    raw_return_type = not_typed
+    raw_arg_types = parameters.map do |_param_kind, param_name|
+      [param_name, not_typed]
+    end.to_h
+
+    self.new(
+      method: method,
+      method_name: method.name,
+      raw_arg_types: raw_arg_types,
+      raw_return_type: raw_return_type,
+      bind: nil,
+      mode: mode,
+      check_level: :never,
+      parameters: parameters,
+      soft_notify: nil,
+    )
+  end
+
+  def mark_failed
+    @ever_failed = true
+  end
+
+  def initialize(method:, method_name:, raw_arg_types:, raw_return_type:, bind:, mode:, check_level:, parameters: method.parameters, soft_notify:, generated: false, override_allow_incompatible: false)
+    @method = method
+    @method_name = method_name
+    @arg_types = []
+    @kwarg_types = {}
+    @block_type = nil
+    @block_name = nil
+    @rest_type = nil
+    @rest_name = nil
+    @keyrest_type = nil
+    @keyrest_name = nil
+    @return_type = T::Utils.coerce(raw_return_type)
+    @bind = bind ? T::Utils.coerce(bind) : bind
+    @mode = mode
+    @check_level = check_level
+    @req_arg_count = 0
+    @req_kwarg_names = []
+    @has_rest = false
+    @has_keyrest = false
+    @parameters = parameters
+    @soft_notify = soft_notify
+    @override_allow_incompatible = override_allow_incompatible
+    @generated = generated
+    @ever_failed = false
+
+    param_names = parameters.map {|_, name| name}
+    declared_param_names = raw_arg_types.keys
+    missing_names = param_names - declared_param_names
+    extra_names = declared_param_names - param_names
+    if !missing_names.empty?
+      raise "The declaration for `#{method.name}` is missing parameter(s): #{missing_names.join(', ')}"
+    end
+    if !extra_names.empty?
+      raise "The declaration for `#{method.name}` has extra parameter(s): #{extra_names.join(', ')}"
+    end
+
+    parameters.zip(raw_arg_types) do |(param_kind, param_name), (type_name, raw_type)|
+      if type_name != param_name
+        hint = ""
+        # Ruby reorders params so that required keyword arguments
+        # always precede optional keyword arguments. We can't tell
+        # whether the culprit is the Ruby reordering or user error, so
+        # we error but include a note
+        if param_kind == :keyreq && parameters.any? {|k, _| k == :key}
+          hint = "\n\nNote: Any required keyword arguments must precede any optional keyword " \
+                 "arguments. If your method declaration matches your `def`, try reordering any " \
+                 "optional keyword parameters to the end of the method list."
+        end
+
+        raise "Parameter `#{type_name}` is declared out of order (declared as arg number " \
+              "#{declared_param_names.index(type_name) + 1}, defined in the method as arg number " \
+              "#{param_names.index(type_name) + 1}).#{hint}\nMethod: #{method_desc}"
+      end
+
+      type = T::Utils.coerce(raw_type)
+
+      case param_kind
+      when :req
+        if @arg_types.length > @req_arg_count
+          # Note that this is actually is supported by Ruby, but it would add complexity to
+          # support it here, and I'm happy to discourage its use anyway.
+          raise "Required params after optional params are not supported in method declarations. Method: #{method_desc}"
+        end
+        @arg_types << [param_name, type]
+        @req_arg_count += 1
+      when :opt
+        @arg_types << [param_name, type]
+      when :key, :keyreq
+        @kwarg_types[param_name] = type
+        if param_kind == :keyreq
+          @req_kwarg_names << param_name
+        end
+      when :block
+        @block_name = param_name
+        @block_type = type
+      when :rest
+        @has_rest = true
+        @rest_name = param_name
+        @rest_type = type
+      when :keyrest
+        @has_keyrest = true
+        @keyrest_name = param_name
+        @keyrest_type = type
+      else
+        raise "Unexpected param_kind: `#{param_kind}`. Method: #{method_desc}"
+      end
+    end
+  end
+
+  def arg_count
+    @arg_types.length
+  end
+
+  def kwarg_names
+    @kwarg_types.keys
+  end
+
+  def owner
+    @method.owner
+  end
+
+  def dsl_method
+    "#{@mode}_method"
+  end
+
+  # @return [Hash] a mapping like {arg_name: [val, type], ...}, for only those args actually present.
+  def each_args_value_type(args)
+    # Manually split out args and kwargs based on ruby's behavior. Do not try to implement this by
+    # getting ruby to determine the kwargs for you (e.g., by defining this method to take *args and
+    # **kwargs). That won't work, because ruby's behavior for determining kwargs is dependent on the
+    # the other parameters in the method definition, and our method definition here doesn't (and
+    # can't) match the definition of the method we're validating. In addition, Ruby has a bug that
+    # causes forwarding **kwargs to do the wrong thing: see https://bugs.ruby-lang.org/issues/10708
+    # and https://bugs.ruby-lang.org/issues/11860.
+    if (args.length > @req_arg_count) && (!@kwarg_types.empty? || @has_keyrest) && args[-1].is_a?(Hash)
+      kwargs = args[-1]
+      args = args[0...-1]
+    else
+      kwargs = EMPTY_HASH
+    end
+
+    arg_types = @arg_types
+
+    if @has_rest
+      arg_types += [[@rest_name, @rest_type]] * (args.length - @arg_types.length)
+
+    elsif (args.length < @req_arg_count) || (args.length > @arg_types.length)
+      expected_str = @req_arg_count.to_s
+      if @arg_types.length != @req_arg_count
+        expected_str += "..#{@arg_types.length}"
+      end
+      raise ArgumentError.new("wrong number of arguments (given #{args.length}, expected #{expected_str})")
+    end
+
+    begin
+      it = 0
+      while it < args.length
+        yield arg_types[it][0], args[it], arg_types[it][1]
+        it += 1
+      end
+    end
+
+    kwargs.each do |name, val|
+      type = @kwarg_types[name]
+      if !type && @has_keyrest
+        type = @keyrest_type
+      end
+      yield name, val, type if type
+    end
+  end
+
+  def method_desc
+    if @method.source_location
+      loc = @method.source_location.join(':')
+    else
+      loc = "<unknown location>"
+    end
+    "#{@method} at #{loc}"
+  end
+
+  EMPTY_HASH = {}.freeze
+end