type_toolkit 0.0.4 → 0.0.6

data/lib/rubocop/cop/type_toolkit/plugin.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "lint_roller"
+require "type_toolkit/version"
 
 module RuboCop
   module Cop
@@ -12,7 +13,7 @@ module RuboCop
             name: "rubocop-type_toolkit",
             version: ::TypeToolkit::VERSION,
             homepage: "https://github.com/Shopify/type_toolkit",
-            description: "Detects misuse of UnexpectedNilError.",
+            description: "RuboCop rules for Type Toolkit.",
           )
         end
 

data/lib/rubocop/cop/type_toolkit/prefer_not_nil.rb

@@ -0,0 +1,96 @@
+# typed: true
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module TypeToolkit
+      # Replaces Sorbet's `T.must(value)` assertion with Type Toolkit's `value.not_nil!` assertion.
+      class PreferNotNil < Base
+        extend AutoCorrector
+
+        MSG = "Use `.not_nil!` instead of `T.must()`."
+        RESTRICT_ON_SEND = [:must].freeze
+
+        COMMA_BYTE = ",".ord
+        private_constant :COMMA_BYTE
+
+        KEYWORD_EXPRESSION_TYPES = [:defined?, :super, :yield, :zsuper].freeze
+        private_constant :KEYWORD_EXPRESSION_TYPES
+
+        #: (RuboCop::AST::SendNode) -> void
+        def on_send(node)
+          return unless (argument = extract_t_must_argument(node))
+
+          if nested_t_must?(node)
+            add_offense(node, message: MSG)
+          else
+            replacement = replacement_for(argument)
+            correction = correction_for(node, argument, replacement)
+
+            add_offense(node, message: MSG) do |corrector|
+              corrector.replace(node, correction)
+            end
+          end
+        end
+
+        private
+
+        #: (RuboCop::AST::SendNode) -> RuboCop::AST::Node?
+        def extract_t_must_argument(node)
+          receiver = node.receiver
+          return unless receiver.is_a?(RuboCop::AST::ConstNode)
+          return unless receiver.short_name == :T && node.method?(:must) && node.arguments.one?
+
+          namespace = receiver.namespace
+          return unless namespace.nil? || namespace.cbase_type?
+
+          argument = node.first_argument
+          return unless argument
+          return if argument.splat_type? || argument.kwsplat_type?
+
+          argument
+        end
+
+        #: (RuboCop::AST::Node) -> String
+        def replacement_for(argument)
+          source = argument.source
+          source = "(#{source})" if requires_parentheses?(argument)
+          "#{source}.not_nil!"
+        end
+
+        #: (RuboCop::AST::SendNode, RuboCop::AST::Node, String) -> String
+        def correction_for(node, argument, replacement)
+          return replacement unless node.multiline?
+
+          grouped_range = node.source_range.with(begin_pos: node.loc.begin.begin_pos, end_pos: node.loc.end.end_pos)
+          grouped_source = grouped_range.source
+          comma_offset = argument.source_range.end_pos - grouped_range.begin_pos
+          grouped_source.slice!(comma_offset) if grouped_source.getbyte(comma_offset) == COMMA_BYTE
+          "#{grouped_source}.not_nil!"
+        end
+
+        #: (RuboCop::AST::SendNode) -> bool
+        def nested_t_must?(node)
+          node.each_ancestor(:send).any? do |ancestor|
+            ancestor.is_a?(RuboCop::AST::SendNode) && extract_t_must_argument(ancestor)
+          end
+        end
+
+        #: (RuboCop::AST::Node) -> bool
+        def requires_parentheses?(argument)
+          return false if argument.begin_type?
+
+          if argument.is_a?(RuboCop::AST::SendNode)
+            return true if argument.operator_method?
+            return true if argument.arguments? && !argument.parenthesized_call?
+          end
+          return true if argument.range_type? || argument.operator_keyword?
+          return true if argument.if_type? || argument.assignment?
+          return true if argument.any_block_type?
+
+          KEYWORD_EXPRESSION_TYPES.include?(argument.type)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop-type_toolkit.rb

@@ -3,3 +3,4 @@
 require "rubocop"
 require_relative "rubocop/cop/type_toolkit/plugin"
 require_relative "rubocop/cop/type_toolkit/dont_expect_unexpected_nil"
+require_relative "rubocop/cop/type_toolkit/prefer_not_nil"

data/lib/type_toolkit/abstract_method_receiver.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+
+module TypeToolkit
+  # Raised when a call is made to an abstract method that never had a real implementation.
+  class AbstractMethodNotImplementedError < Exception # rubocop:disable Lint/InheritException
+    def initialize(method_name:)
+      # Do not rely on this message content! Its content is subject to change.
+      super("Abstract method `##{method_name}` was never implemented.")
+    end
+  end
+
+  # This module is included on a class whose instances can be receivers of calls to abstract methods.
+  #
+  # Since abstract methods are removed at runtime (see `TypeToolkit::DSL#abstract`), attempting to call
+  # an unimplemented abstract method would usually raise a `NoMethodError`.
+  # This module uses `method_missing` to raise `AbstractMethodNotImplementedError` instead.
+  # @requires_ancestor: Kernel
+  module AbstractInstanceMethodReceiver
+    # This `#method_missing` is hit when calling a potentially abstract method on an instance
+    # E.g. TheClass.new.maybe_abstract_method
+    #
+    # (Symbol, ...) -> untyped
+    def method_missing(method_name, ...)
+      c = self.class #: as Class[top] & HasAbstractMethods
+
+      if c.abstract_method_declared?(method_name)
+        raise AbstractMethodNotImplementedError.new(method_name:)
+      end
+
+      super
+    end
+
+    #: (Symbol, ?bool) -> bool
+    def respond_to_missing?(method_name, include_private = false)
+      self.class.abstract_method_declared?(method_name) || super
+    end
+  end
+end

data/lib/type_toolkit/dsl.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+module TypeToolkit
+  # @requires_ancestor: MethodDefRecorder
+  module DSL
+    # Mark `method_name` as abstract.
+    #
+    # A real implementation of the method must be provided somewhere in the ancestor chain.
+    # Calls to an unimplemented abstract method will raise `AbstractMethodNotImplementedError`.
+    #
+    #: (Symbol) -> Symbol
+    def abstract(method_name)
+      #: self as (Module[top] & HasAbstractMethods & MethodDefRecorder)
+
+      recorded_method_name, is_singleton_method = __last_method_def
+
+      if recorded_method_name != method_name
+        prefix = is_singleton_method ? "." : "#"
+
+        # Do not rely on this message content! Its content is subject to change.
+        raise <<~MSG.chomp
+          `abstract` expected to see `#{prefix}#{method_name}`, but the last recorded method was called `#{recorded_method_name}`.
+          This can happen when `abstract` is combined with other metaprogramming.
+          If you think this is a bug, please open an issue: https://github.com/Shopify/type_toolkit/issues
+        MSG
+      end
+
+      # The `method_owner` is the class whose method table stores the abstract method.
+      #
+      # Example:
+      #
+      #   class Foo
+      #     # is_singleton_method = false, owner is the `Foo` class
+      #     abstract def foo; end
+      #
+      #     # is_singleton_method = true, owner is `Foo.singleton_class`
+      #     abstract def self.foo; end
+      #   end
+      method_owner = is_singleton_method ? singleton_class : self #: as Module[top] & HasAbstractMethods
+
+      # Register the fact that this method is meant to be abstract,
+      # used by APIs like `abstract_method_declared?` and `Method#abstract?`
+      method_owner.__register_abstract_method(method_name)
+
+      # We never want the empty "stub" method to be called, so we remove it. This has one of 3 effects:
+      #
+      # 1. If the abstract method is implemented by a subclass, then there's no effect.
+      #    The subclass' implementation will always be invoked, so this removal does nothing.
+      #
+      # 2. If the abstract method was already implemented by a superclass,
+      #    Then this removal ensures that calls to the method will resolve to
+      #    the superclass' implementation, and never the empty stub.
+      #
+      # 3. If the abstract method was not implemented anywhere in the ancestor chain,
+      #    then this removal ensures we hit `method_missing`, which will then raise
+      #    the `AbstractMethodNotImplementedError`.
+      method_owner.remove_method(method_name)
+
+      # Return the method name, so `abstract` can be chained, e.g. `private abstract def foo; end`
+      method_name
+    end
+  end
+end

data/lib/type_toolkit/ext/method.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "type_toolkit/method_patch"
+
+class Method
+  prepend TypeToolkit::MethodPatch
+end
+
+class UnboundMethod
+  prepend TypeToolkit::MethodPatch
+end

data/lib/type_toolkit/ext/module.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Module
+  def interface!
+    TypeToolkit.make_interface!(self)
+  end
+end

data/lib/type_toolkit/ext/nil_assertions.rb

@@ -27,7 +27,9 @@ module TypeToolkit
   #
   # `UnexpectedNilError` should never occur in well-formed code, so it should never be rescued.
   # This is why it inherits from `Exception` instead of `StandardError`,
-  # so that bare rescues clauses (like `rescue => e`) don't rescue it.
+  # so that bare rescue clauses (like `rescue => e`) don't accidentally swallow it.
+  #
+  # Note: `rescue Exception` can still catch it, but that's intentionally harder to write accidentally.
   class UnexpectedNilError < Exception # rubocop:disable Lint/InheritException
     def initialize(message = "Called `not_nil!` on nil.")
       super

data/lib/type_toolkit/has_abstract_methods.rb

@@ -0,0 +1,108 @@
+# typed: strict
+# frozen_string_literal: true
+
+module TypeToolkit
+  # Given a class Foo, abstract methods can be defined at two levels:
+  # 1. Instance methods available on the instance of Foo
+  # 2. "Class methods" available on the Foo class itself
+  #
+  # In case 1, the storage belongs one level up, in the class Foo.
+  # In case 2, the storage belongs two levels up, in the singleton class of Foo (`Foo::<Foo>`)
+  module HasAbstractMethods
+    # Private API, do not use directly. Only meant to be called from the `abstract` macro.
+    #: (Symbol) -> void
+    def __register_abstract_method(method_name) # :nodoc:
+      (
+        @__abstract_methods ||= Set.new #: Set[Symbol]?
+      ) << method_name
+    end
+
+    # Returns all methods that were marked abstract (even those which are implemented).
+    #: (?bool) -> Array[Symbol]
+    def declared_abstract_instance_methods(include_super = true)
+      #: self as HasAbstractMethods & Module[top]
+
+      result = @__abstract_methods
+
+      return result.to_a unless include_super
+
+      if defined?(super) && (super_abstract_methods = super)
+        if result
+          result.merge(super_abstract_methods)
+        else
+          result = super_abstract_methods
+        end
+      end
+
+      abstract_methods_in_interfaces = included_modules.flat_map do |m|
+        m.is_a?(HasAbstractMethods) ? m.declared_abstract_instance_methods : []
+      end
+
+      if abstract_methods_in_interfaces.any?
+        if result&.any?
+          result.merge(abstract_methods_in_interfaces)
+        else
+          result = abstract_methods_in_interfaces
+        end
+      end
+
+      result.to_a
+    end
+
+    # Returns all methods that are abstract and have not been implemented.
+    #: (?bool) -> Array[Symbol]
+    def abstract_instance_methods(include_super = true)
+      #: self as HasAbstractMethods & Module[top]
+
+      declared_abstract_instance_methods(include_super).reject do |m|
+        method_defined?(m) || private_method_defined?(m)
+      end
+    end
+
+    # Returns true if the given method name was ever marked abstract, even if it has a concrete implementation.
+    #
+    # Similar to `public_method_defined?` and friends, this method is called on a class to check if the method
+    # is defined for _instances_ of that class. For example:
+    #
+    #     if Foo.abstract_method_declared?(:instance_method)
+    #       Foo.new.instance_method # Might raise AbstractMethodNotImplementedError
+    #     end
+    #
+    #     if Foo.singleton_class.abstract_method_declared?(:class_method)
+    #       Foo.class_method # Might raise AbstractMethodNotImplementedError
+    #     end
+    #
+    #: (Symbol) -> bool
+    def abstract_method_declared?(method_name)
+      #: self as Module[top]
+
+      @__abstract_methods&.include?(method_name) ||
+        included_modules.any? { |m| m.is_a?(HasAbstractMethods) && m.abstract_method_declared?(method_name) } ||
+        (defined?(super) && super)
+    end
+
+    # Returns true if the given method is abstract, and has not been implemented.
+    # Calling it *will* raise an `AbstractMethodNotImplementedError`.
+    #
+    # Similar to `public_method_defined?` and friends, this method is called on a class to check if the method
+    # is defined for _instances_ of that class. For example:
+    #
+    #     if Foo.abstract_method?(:instance_method)
+    #       Foo.new.instance_method # Will raise AbstractMethodNotImplementedError
+    #     end
+    #
+    #     if Foo.singleton_class.abstract_method?(:class_method)
+    #       Foo.class_method # Will raise AbstractMethodNotImplementedError
+    #     end
+    #
+    #: (Symbol) -> bool
+    def abstract_method?(method_name)
+      #: self as (HasAbstractMethods & Module[top])
+
+      # If the method is defined, it has a concrete implementation, so it's not abstract.
+      return false if method_defined?(method_name) || private_method_defined?(method_name)
+
+      abstract_method_declared?(method_name)
+    end
+  end
+end

data/lib/type_toolkit/interface.rb

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "dsl"
+require_relative "method_def_recorder"
+require_relative "has_abstract_methods"
+require_relative "abstract_method_receiver"
+
+module TypeToolkit
+  class << self
+    #: (Module[top]) -> void
+    def make_interface!(mod)
+      if Class === mod
+        raise TypeError, "Classes can't be interfaces. Did you mean to make it `abstract` instead?"
+      end
+
+      mod.extend(TypeToolkit::Interface)
+      mod.extend(TypeToolkit::DSL)
+      mod.extend(TypeToolkit::MethodDefRecorder)
+      mod.extend(TypeToolkit::HasAbstractMethods)
+    end
+  end
+
+  # This module is extended onto any module that represents an interface.
+  # All of its members should be public and abstract.
+  module Interface
+    #: (Module[top]) -> void
+    def included(target_module)
+      # Including/extending a module is idempotent, so we don't have to worry these were already included/extended.
+
+      # Potentially abstract methods will be called on instances of `self`, so we need the `method_missing` hooks.
+      target_module.include(TypeToolkit::AbstractInstanceMethodReceiver)
+
+      # The `method_missing` hooks need to be able to look up the abstract methods (from the interface).
+      target_module.extend(TypeToolkit::HasAbstractMethods)
+    end
+  end
+end

data/lib/type_toolkit/method_def_recorder.rb

@@ -0,0 +1,53 @@
+# typed: strict
+# frozen_string_literal: true
+
+module TypeToolkit
+  # This module tracks new methods being defined, and whether they were
+  # instance methods (`def foo; end`) or singleton methods (`def self.foo; end`).
+  module MethodDefRecorder
+    #: [Symbol, bool]?
+    attr_reader :__last_method_def
+
+    class << self
+      #: (Module[top]) -> void
+      def extended(target_module)
+        # Also extend the singleton class so methods are available there
+        target_module.singleton_class.extend(ClassMethods)
+      end
+    end
+
+    # These actually go on the YourClass.singleton_class.singleton_class
+    # @requires_ancestor: MethodDefRecorder
+    module ClassMethods
+      #: () -> [Symbol, bool]?
+      def __last_method_def
+        #: self as Class[MethodDefRecorder]
+        cls = attached_object #: as MethodDefRecorder
+        cls.__last_method_def
+      end
+    end
+
+    # Need `@without_runtime` because of https://github.com/Shopify/tapioca/issues/2513
+    # @without_runtime
+    #: (Symbol) -> void
+    def method_added(m)
+      is_singleton_method = false
+      @__last_method_def = [m, is_singleton_method] #: [Symbol, bool]?
+
+      super
+    end
+
+    # Need `@without_runtime` because of https://github.com/Shopify/tapioca/issues/2513
+    # @without_runtime
+    # @override
+    #: (Symbol) -> void
+    def singleton_method_added(m)
+      return super if m == :singleton_method_added
+
+      is_singleton_method = true
+      @__last_method_def = [m, is_singleton_method] #: [Symbol, bool]?
+
+      super
+    end
+  end
+end

data/lib/type_toolkit/method_patch.rb

@@ -0,0 +1,16 @@
+# typed: strict
+# frozen_string_literal: true
+
+module TypeToolkit
+  # @requires_ancestor: MethodOrUnboundMethod
+  module MethodPatch
+    # Returns true if this method is an abstract method that hasn't been implemented.
+    # Calling it will raise an `AbstractMethodNotImplementedError`.
+    #: -> bool
+    def abstract?
+      return false unless TypeToolkit::HasAbstractMethods === (owner = self.owner)
+
+      owner.abstract_method?(name)
+    end
+  end
+end

data/lib/type_toolkit/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module TypeToolkit
-  VERSION = "0.0.4"
+  VERSION = "0.0.6"
 end

data/lib/type_toolkit.rb

@@ -2,6 +2,9 @@
 # frozen_string_literal: true
 
 require_relative "type_toolkit/version"
+require_relative "type_toolkit/interface"
+require_relative "type_toolkit/ext/method"
+require_relative "type_toolkit/ext/module"
 require_relative "type_toolkit/ext/nil_assertions"
 
 module TypeToolkit

data/sorbet/config

@@ -3,5 +3,7 @@
 --ignore=tmp/
 --ignore=vendor/
 --enable-experimental-rbs-comments
+--enable-experimental-requires-ancestor
 --suppress-payload-superclass-redefinition-for=RDoc::Markup::Heading
---disable-watchman
+--suppress-error-code=5022
+--parser=prism