sorbet-runtime 0.0.1.pre.prealpha → 0.4.4253

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+# typed: true
+
+module T::Private::Methods::SignatureValidation
+  Methods = T::Private::Methods
+  Modes = Methods::Modes
+
+  def self.validate(signature)
+    if signature.method_name == :initialize && signature.method.owner.is_a?(Class)
+      # Constructors are special. They look like overrides in terms of a super_method existing,
+      # but in practice, you never call them polymorphically. Conceptually, they're standard
+      # methods (this is consistent with how they're treated in other languages, e.g. Java)
+      if signature.mode != Modes.standard
+        raise "Constructor methods should always be declared using `sig`."
+      end
+      return
+    end
+
+    super_method = signature.method.super_method
+
+    if super_method && super_method.owner != signature.method.owner
+      Methods.maybe_run_sig_block_for_method(super_method)
+      super_signature = Methods.signature_for_method(super_method)
+
+      # If the super_method has any kwargs we can't build a
+      # Signature for it, so we'll just skip validation in that case.
+      if !super_signature && !super_method.parameters.select {|kind, _| kind == :rest || kind == :kwrest}.empty?
+        nil
+      else
+        # super_signature can be nil when we're overriding a method (perhaps a builtin) that didn't use
+        # one of the method signature helpers. Use an untyped signature so we can still validate
+        # everything but types.
+        #
+        # We treat these signatures as overridable, that way people can use `.override` with
+        # overrides of builtins. In the future we could try to distinguish when the method is a
+        # builtin and treat non-builtins as non-overridable (so you'd be forced to declare them with
+        # `.overridable`).
+        #
+        super_signature ||= Methods::Signature.new_untyped(method: super_method)
+
+        validate_override_mode(signature, super_signature)
+        validate_override_shape(signature, super_signature)
+        validate_override_types(signature, super_signature)
+      end
+    else
+      validate_non_override_mode(signature)
+    end
+  end
+
+  private_class_method def self.pretty_mode(signature)
+    if signature.mode == Modes.overridable_implementation
+      '.overridable.implementation'
+    else
+      ".#{signature.mode}"
+    end
+  end
+
+  def self.validate_override_mode(signature, super_signature)
+    case signature.mode
+    when *Modes::OVERRIDE_MODES
+      if !Modes::OVERRIDABLE_MODES.include?(super_signature.mode)
+        raise "You declared `#{signature.method_name}` as #{pretty_mode(signature)}, but the method it overrides is not declared as `overridable`.\n" \
+              "  Parent definition: #{method_loc_str(super_signature.method)}\n" \
+              "  Child definition:  #{method_loc_str(signature.method)}\n"
+      end
+    when *Modes::IMPLEMENT_MODES
+      if super_signature.mode != Modes.abstract
+        raise "You declared `#{signature.method_name}` as #{pretty_mode(signature)}, but the method it overrides is not declared as abstract.\n" \
+              "  Either mark #{super_signature.method_name} as `abstract.` in the parent: #{method_loc_str(super_signature.method)}\n" \
+              "  ... or mark #{signature.method_name} as `override.` in the child: #{method_loc_str(signature.method)}\n"
+      end
+    when *Modes::NON_OVERRIDE_MODES
+      if super_signature.mode == Modes.standard
+        # Peaceful
+      elsif super_signature.mode == Modes.abstract
+        raise "You must use `.implementation` when overriding the abstract method `#{signature.method_name}`.\n" \
+              "  Abstract definition: #{method_loc_str(super_signature.method)}\n" \
+              "  Implementation definition: #{method_loc_str(signature.method)}\n"
+      elsif super_signature.mode != Modes.untyped
+        raise "You must use `.override` when overriding the existing method `#{signature.method_name}`.\n" \
+              "  Parent definition: #{method_loc_str(super_signature.method)}\n" \
+              "  Child definition:  #{method_loc_str(signature.method)}\n"
+      end
+    else
+      raise "Unexpected mode: #{signature.mode}. Please report to #dev-productivity."
+    end
+  end
+
+  def self.validate_non_override_mode(signature)
+    case signature.mode
+    when Modes.override
+      raise "You marked `#{signature.method_name}` as #{pretty_mode(signature)}, but that method doesn't already exist in this class/module to be overriden.\n" \
+        "  Either check for typos and for missing includes or super classes to make the parent method shows up\n" \
+        "  ... or remove #{pretty_mode(signature)} here: #{method_loc_str(signature.method)}\n"
+    when Modes.standard, *Modes::NON_OVERRIDE_MODES
+      # Peaceful
+      nil
+    when *Modes::IMPLEMENT_MODES
+      raise "You marked `#{signature.method_name}` as #{pretty_mode(signature)}, but it doesn't match up with a corresponding abstract method.\n" \
+        "  Either check for typos and for missing includes or super classes to make the parent method shows up\n" \
+        "  ... or remove #{pretty_mode(signature)} here: #{method_loc_str(signature.method)}\n"
+    else
+      raise "Unexpected mode: #{signature.mode}. Please report to #dev-productivity."
+    end
+
+    owner = signature.method.owner
+    if (signature.mode == Modes.abstract || Modes::OVERRIDABLE_MODES.include?(signature.mode)) &&
+        owner.singleton_class?
+      # Given a singleton class, we can check if it belongs to a
+      # module by looking at its superclass; given `module M`,
+      # `M.singleton_class.superclass == Module`, which is not true
+      # for any class.
+      if owner.superclass == Module
+        raise "Defining an overridable class method (via #{pretty_mode(signature)}) " \
+              "on a module is not allowed. Class methods on " \
+              "modules do not get inherited and thus cannot be overridden. For help, ask in " \
+              "#dev-productivity."
+      end
+    end
+  end
+
+  def self.validate_override_shape(signature, super_signature)
+    return if signature.override_allow_incompatible
+    return if super_signature.mode == Modes.untyped
+
+    method_name = signature.method_name
+    mode_verb = super_signature.mode == Modes.abstract ? 'implements' : 'overrides'
+
+    if !signature.has_rest && signature.arg_count < super_signature.arg_count
+      raise "Your definition of `#{method_name}` must accept at least #{super_signature.arg_count} " \
+            "positional arguments to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if !signature.has_rest && super_signature.has_rest
+      raise "Your definition of `#{method_name}` must have `*#{super_signature.rest_name}` " \
+            "to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if signature.req_arg_count > super_signature.req_arg_count
+      raise "Your definition of `#{method_name}` must have no more than #{super_signature.req_arg_count} " \
+            "required argument(s) to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if !signature.has_keyrest
+      # O(nm), but n and m are tiny here
+      missing_kwargs = super_signature.kwarg_names - signature.kwarg_names
+      if !missing_kwargs.empty?
+        raise "Your definition of `#{method_name}` is missing these keyword arg(s): #{missing_kwargs} " \
+              "which are defined in the method it #{mode_verb}: " \
+              "#{base_override_loc_str(signature, super_signature)}"
+      end
+    end
+
+    if !signature.has_keyrest && super_signature.has_keyrest
+      raise "Your definition of `#{method_name}` must have `**#{super_signature.keyrest_name}` " \
+            "to be compatible with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+
+    # O(nm), but n and m are tiny here
+    extra_req_kwargs = signature.req_kwarg_names - super_signature.req_kwarg_names
+    if !extra_req_kwargs.empty?
+      raise "Your definition of `#{method_name}` has extra required keyword arg(s) " \
+            "#{extra_req_kwargs} relative to the method it #{mode_verb}, making it incompatible: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+
+    if super_signature.block_name && !signature.block_name
+      raise "Your definition of `#{method_name}` must accept a block parameter to be compatible " \
+            "with the method it #{mode_verb}: " \
+            "#{base_override_loc_str(signature, super_signature)}"
+    end
+  end
+
+  def self.validate_override_types(signature, super_signature)
+    return if signature.override_allow_incompatible
+    return if super_signature.mode == Modes.untyped
+    return unless [signature, super_signature].all? do |sig|
+      sig.check_level == :always || (sig.check_level == :tests && T::Private::RuntimeLevels.check_tests?)
+    end
+    mode_noun = super_signature.mode == Modes.abstract ? 'implementation' : 'override'
+
+    # arg types must be contravariant
+    super_signature.arg_types.zip(signature.arg_types).each_with_index do |((_super_name, super_type), (name, type)), index|
+      if !super_type.subtype_of?(type)
+        raise "Incompatible type for arg ##{index + 1} (`#{name}`) in #{mode_noun} of method " \
+              "`#{signature.method_name}`:\n" \
+              "* Base: `#{super_type}` (in #{method_loc_str(super_signature.method)})\n" \
+              "* #{mode_noun.capitalize}: `#{type}` (in #{method_loc_str(signature.method)})\n" \
+              "(The types must be contravariant.)"
+      end
+    end
+
+    # kwarg types must be contravariant
+    super_signature.kwarg_types.each do |name, super_type|
+      type = signature.kwarg_types[name]
+      if !super_type.subtype_of?(type)
+        raise "Incompatible type for arg `#{name}` in #{mode_noun} of method `#{signature.method_name}`:\n" \
+              "* Base: `#{super_type}` (in #{method_loc_str(super_signature.method)})\n" \
+              "* #{mode_noun.capitalize}: `#{type}` (in #{method_loc_str(signature.method)})\n" \
+              "(The types must be contravariant.)"
+      end
+    end
+
+    # return types must be covariant
+    if !signature.return_type.subtype_of?(super_signature.return_type)
+      raise "Incompatible return type in #{mode_noun} of method `#{signature.method_name}`:\n" \
+            "* Base: `#{super_signature.return_type}` (in #{method_loc_str(super_signature.method)})\n" \
+            "* #{mode_noun.capitalize}: `#{signature.return_type}` (in #{method_loc_str(signature.method)})\n" \
+            "(The types must be covariant.)"
+    end
+  end
+
+  private_class_method def self.base_override_loc_str(signature, super_signature)
+    mode_noun = super_signature.mode == Modes.abstract ? 'Implementation' : 'Override'
+    "\n * Base definition: in #{method_loc_str(super_signature.method)}" \
+    "\n * #{mode_noun}: in #{method_loc_str(signature.method)}"
+  end
+
+  private_class_method def self.method_loc_str(method)
+    if method.source_location
+      loc = method.source_location.join(':')
+    else
+      loc = "<unknown location>"
+    end
+    "#{method.owner} at #{loc}"
+  end
+end

data/lib/types/private/mixins/mixins.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# typed: true
+
+module T::Private
+  module MixesInClassMethods
+    def included(other)
+      mod = Abstract::Data.get(self, :class_methods_mixin)
+      other.extend(mod)
+      super
+    end
+  end
+
+  module Mixins
+    def self.declare_mixes_in_class_methods(mixin, class_methods)
+      if mixin.is_a?(Class)
+        raise "Classes cannot be used as mixins, and so mixes_in_class_methods cannot be used on a Class."
+      end
+
+      if Abstract::Data.key?(mixin, :class_methods_mixin)
+        raise "mixes_in_class_methods can only be used once per module."
+      end
+
+      mixin.singleton_class.include(MixesInClassMethods)
+      Abstract::Data.set(mixin, :class_methods_mixin, class_methods)
+    end
+  end
+end

data/lib/types/private/runtime_levels.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# typed: true
+
+# Used in `sig.checked(level)` to determine when runtime type checking
+# is enabled on a method.
+module T::Private::RuntimeLevels
+  LEVELS = [
+    # Validate every call in every environment
+    :always,
+    # Validate in tests, but not in production
+    :tests,
+    # Don't even validate in tests, b/c too expensive,
+    # or b/c we fully trust the static typing
+    :never,
+  ].freeze
+
+  @check_tests = false
+  @wrapped_tests_with_validation = false
+
+  def self.check_tests?
+    # Assume that this code path means that some `sig.checked(:tests)`
+    # has been wrapped (or not wrapped) already, which is a trapdoor
+    # for toggling `@check_tests`.
+    @wrapped_tests_with_validation = true
+
+    @check_tests
+  end
+
+  def self.enable_checking_in_tests
+    if !@check_tests && @wrapped_tests_with_validation
+      raise "Toggle `:tests`-level runtime type checking earlier. " \
+        "There are already some methods wrapped with `sig.checked(:tests)`." \
+    end
+
+    _toggle_checking_tests(true)
+  end
+
+  def self._toggle_checking_tests(checked)
+    @check_tests = checked
+  end
+end

data/lib/types/private/types/not_typed.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# typed: true
+
+# A placeholder for when an untyped thing must provide a type.
+# Raises an exception if it is ever used for validation.
+class T::Private::Types::NotTyped < T::Types::Base
+  ERROR_MESSAGE = "Validation is being done on a `NotTyped`. Please report to #dev-productivity."
+
+  # @override Base
+  def name
+    "<NOT-TYPED>"
+  end
+
+  # @override Base
+  def valid?(obj)
+    raise ERROR_MESSAGE
+  end
+
+  # @override Base
+  private def subtype_of_single?(other)
+    raise ERROR_MESSAGE
+  end
+end

data/lib/types/private/types/string_holder.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# typed: true
+
+# Holds a string. Useful for showing type aliases in error messages
+class T::Private::Types::StringHolder < T::Types::Base
+  attr_reader :string
+
+  def initialize(string)
+    @string = string
+  end
+
+  # @override Base
+  def name
+    string
+  end
+
+  # @override Base
+  def valid?(obj)
+    false
+  end
+
+  # @override Base
+  private def subtype_of_single?(other)
+    false
+  end
+end

data/lib/types/private/types/void.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# typed: true
+
+# A marking class for when methods return void.
+# Should never appear in types directly.
+class T::Private::Types::Void < T::Types::Base
+  ERROR_MESSAGE = "Validation is being done on an `Void`. Please report to #dev-productivity."
+
+  # The actual return value of `.void` methods.
+  #
+  # Uses `Module.new` because in Ruby an anonymous module will inherit the name
+  # of the constant it's assigned to. This gives it a readable name someone
+  # examines it in Pry or with `#inspect` like:
+  #
+  #     T::Private::Types::Void::VOID
+  #
+  VOID = Module.new.freeze
+
+  # @override Base
+  def name
+    "<VOID>"
+  end
+
+  # @override Base
+  def valid?(obj)
+    raise ERROR_MESSAGE
+  end
+
+  # @override Base
+  private def subtype_of_single?(other)
+    raise ERROR_MESSAGE
+  end
+end

data/lib/types/profile.rb

@@ -0,0 +1,27 @@
+# typed: true
+# frozen_string_literal: true
+
+module T::Profile
+  SAMPLE_RATE = 101 # 1 out of that many typechecks will be measured
+  class <<self
+    attr_accessor :typecheck_duration
+    attr_accessor :typecheck_samples
+    attr_accessor :typecheck_sample_attempts
+    def typecheck_duration_estimate
+      total_typechecks = typecheck_samples * SAMPLE_RATE + (SAMPLE_RATE - typecheck_sample_attempts)
+      typechecks_measured = typecheck_samples * SAMPLE_RATE
+      typecheck_duration * SAMPLE_RATE * 1.0 * total_typechecks / typechecks_measured
+    end
+
+    def typecheck_count_estimate
+      typecheck_samples * SAMPLE_RATE
+    end
+
+    def reset
+      @typecheck_duration = 0
+      @typecheck_samples = 0
+      @typecheck_sample_attempts = SAMPLE_RATE
+    end
+  end
+  self.reset
+end

data/lib/types/props/_props.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+# typed: false
+
+# A mixin for defining typed properties (attributes).
+# To get serialization methods (to/from JSON-style hashes), add T::Props::Serializable.
+# To get a constructor based on these properties, inherit from T::Struct.
+module T::Props
+  extend T::Helpers
+
+  #####
+  # CAUTION: This mixin is used in hundreds of classes; we want to keep its surface area as narrow
+  # as possible and avoid polluting (and possibly conflicting with) the classes that use it.
+  #
+  # It currently has *zero* instance methods; let's try to keep it that way.
+  # For ClassMethods (below), try to add things to T::Props::Decorator instead unless you are sure
+  # it needs to be exposed here.
+  #####
+
+  module ClassMethods
+    extend T::Sig
+    extend T::Helpers
+
+    def props; decorator.props; end
+    def plugins; @plugins ||= []; end
+
+    def decorator_class; Decorator; end
+
+    def decorator; @decorator ||= decorator_class.new(self); end
+    def reload_decorator!; @decorator = decorator_class.new(self); end
+
+    # @!method self.prop(name, type, opts={})
+    #
+    # Define a new property. See {file:README.md} for some concrete
+    #  examples.
+    #
+    # Defining a property defines a method with the same name as the
+    # property, that returns the current value, and a `prop=` method
+    # to set its value. Properties will be inherited by subclasses of
+    # a document class.
+    #
+    # @param name [Symbol] The name of this property
+    # @param cls [Class,T::Props::CustomType] (String) The type of this
+    #   property. If the type is itself a {Document} subclass, this
+    #   property will be recursively serialized/deserialized.
+    # @param rules [Hash] Options to control this property's behavior.
+    # @option rules [T::Boolean,Symbol] :optional If `true`, this property
+    #   is never required to be set before an instance is serialized.
+    #   If `:on_load` (default), when this property is missing or nil, a
+    #   new model cannot be saved, and an existing model can only be
+    #   saved if the property was already missing when it was loaded.
+    #   If `false`, when the property is missing/nil after deserialization, it
+    #   will be set to the default value (as defined by the `default` or
+    #   `factory` option) or will raise if they are not present.
+    #   Deprecated: For {Model}s, if `:optional` is set to the special value
+    #   `:existing`, the property can be saved as nil even if it was
+    #   deserialized with a non-nil value. (Deprecated because there should
+    #   never be a need for this behavior; the new behavior of non-optional
+    #   properties should be sufficient.)
+    # @option rules [Array] :enum An array of legal values; The
+    #  property is required to take on one of those values.
+    # @option rules [T::Boolean] :dont_store If true, this property will
+    #   not be saved on the hash resulting from {#serialize}
+    # @option rules [Object] :ifunset A value to be returned if this
+    #   property is requested but has never been set (is set to
+    #   `nil`). It is applied at property-access time, and never saved
+    #   back onto the object or into the database.
+    #
+    #   ``:ifunset`` is considered **DEPRECATED** and should not be used
+    #    in new code, in favor of just setting a default value.
+    # @option rules [Model, Symbol, Proc] :foreign A model class that this
+    #  property is a reference to. Passing `:foreign` will define a
+    #  `:"#{name}_"` method, that will load and return the
+    #  corresponding foreign model.
+    #
+    #  A symbol can be passed to avoid load-order dependencies; It
+    #  will be lazily resolved relative to the enclosing module of the
+    #  defining class.
+    #
+    #  A callable (proc or method) can be passed to dynamically specify the
+    #  foreign model. This will be passed the object instance so that other
+    #  properties of the object can be used to determine the relevant model
+    #  class. It should return a string/symbol class name or the foreign model
+    #  class directly.
+    #
+    # @option rules [Object] :default A default value that will be set
+    #   by {#initialize} if none is provided in the initialization
+    #   hash. This will not affect objects loaded by {.from_hash}.
+    # @option rules [Proc] :factory A `Proc` that will be called to
+    #   generate an initial value for this prop on {#initialize}, if
+    #   none is providede.
+    # @option rules [T::Boolean] :immutable If true, this prop cannot be
+    #   modified after an instance is created or loaded from a hash.
+    # @option rules [Class,T::Props::CustomType] :array If set, specifies the
+    #   type of individual members of a prop with `type` `Array`. This
+    #   allows for typechecking of arrays, and also for recursive
+    #   serialization of arrays of sub-{Document}s.
+    # @option rules [T::Boolean] :override It is an error to redeclare a
+    #   `prop` that has already been declared (including on a
+    #   superclass), unless `:override` is set to `true`.
+    # @option rules [Symbol, Array] :redaction A redaction directive that may
+    #   be passed to Chalk::Tools::RedactionUtils.redact_with_directive to
+    #   sanitize this parameter for display. Will define a
+    #   `:"#{name}_redacted"` method, which will return the value in sanitized
+    #   form.
+    #
+    # @return [void]
+    def prop(name, cls, rules={})
+      cls = T::Utils.coerce(cls) if !cls.is_a?(Module)
+      decorator.prop_defined(name, cls, rules)
+    end
+
+    # @!method validate_prop_value(propname, value)
+    #
+    # Validates the value of the specified prop. This method allows the caller to
+    #  validate a value for a prop without having to set the data on the instance.
+    #  Throws if invalid.
+    #
+    # @param prop [Symbol]
+    # @param val [Object]
+    # @return [void]
+    def validate_prop_value(prop, val)
+      decorator.validate_prop_value(prop, val)
+    end
+
+    # Needs to be documented
+    def plugin(mod)
+      decorator.plugin(mod)
+    end
+
+    # Shorthand helper to define a `prop` with `immutable => true`
+    sig {params(name: T.any(Symbol, String), cls_or_args: T.untyped, args: T::Hash[Symbol, T.untyped]).void}
+    def const(name, cls_or_args, args={})
+      if (cls_or_args.is_a?(Hash) && cls_or_args.key?(:immutable)) || args.key?(:immutable)
+        raise ArgumentError.new("Cannot pass 'immutable' argument when using 'const' keyword to define a prop")
+      end
+
+      if cls_or_args.is_a?(Hash)
+        self.prop(name, cls_or_args.merge(immutable: true))
+      else
+        self.prop(name, cls_or_args, args.merge(immutable: true))
+      end
+    end
+
+    def included(child)
+      decorator.model_inherited(child)
+      super
+    end
+
+    def prepended(child)
+      decorator.model_inherited(child)
+      super
+    end
+
+    def extended(child)
+      decorator.model_inherited(child.singleton_class)
+      super
+    end
+
+    def inherited(child)
+      decorator.model_inherited(child)
+      super
+    end
+  end
+  mixes_in_class_methods(ClassMethods)
+end