Implement user-defined type guard method

This implements the minimal version of user-defined type guard method.
A user-defined type guard methos is a method defined by user that is
able to guarantee the type of the objects (receiver or arguments).

At present, Steep supports type guard methods provided by ruby-core (ex.
`#is_a?`, `#nil?`, and so on).  But we also have many kinds of
user-defined methods that are able to check the type of the objects.

Therefore user-defined type guard will help checking the type of these
applications by narrowing types.

This implementation uses an annotation to declare user-defined type
guard method.

```
class Example < Integer
  %a{guard:self is Integer}
  def integer?: () -> bool
end
```

For example, the above method `Example#integer?` is a user-defined
type guard method that narrows the Example object itself to an Integer
if the conditional branch passed.

```
example = Example.new
if example.integer?
  example  #=> Integer
end
```

In this PR, the predicate of type guards only supports "self is TYPE"
statement.  I have a plan to extend it:

* `%a{guard:self is arg}`
* `%a{guard:self is_a arg}`
* `%a{guard:self is TYPE_PARAM}`
* `%a{guard:arg is TYPE}`

Note: The compatibility of RBS syntax is the large reason of using
annotations.  I'm afraid that adding a new syntax to define it will
bring breaking change to the RBS, and difficult to use it on common
repository or generators (ex. gem_rbs_collection and rbs_rails).

lib/steep/ast/types/logic.rb

@@ -4,7 +4,7 @@ module Types
       module Logic
         class Base
           extend SharedInstance
-          
+
           def subst(s)
             self
           end
@@ -53,6 +53,28 @@ class ArgEqualsReceiver < Base
         class ArgIsAncestor < Base
         end
 
+        class Guard < Base
+          PATTERN = /\Aguard:\s*(self)\s+(is)\s+(.*?)\s*\Z/
+
+          attr_reader :subject
+          attr_reader :operator
+          attr_reader :type
+
+          def initialize(subject:, operator:, type:)
+            @subject = subject
+            @operator = operator
+            @type = type
+          end
+
+          def ==(other)
+            super && subject == other.subject && operator == other.operator && type == other.type
+          end
+
+          def hash
+            self.class.hash ^ subject.hash ^ operator.hash ^ type.hash
+          end
+        end
+
         class Env < Base
           attr_reader :truthy, :falsy, :type
 

lib/steep/diagnostic/ruby.rb

@@ -1013,6 +1013,22 @@ def header_line
         end
       end
 
+      class InsufficientTypeGuard < Base
+        attr_reader :super_type
+        attr_reader :sub_type
+
+        def initialize(node:, super_type:, sub_type:)
+          @super_type = super_type
+          @sub_type = sub_type
+
+          super(node: node)
+        end
+
+        def header_line
+          "Cannot narrow the type: #{super_type} is not a subtype of #{sub_type}"
+        end
+      end
+
       ALL = ObjectSpace.each_object(Class).with_object([]) do |klass, array|
         if klass < Base
           array << klass

lib/steep/diagnostic/signature.rb

@@ -460,6 +460,32 @@ def header_line
         end
       end
 
+      class TypeGuardSyntaxError < Base
+        attr_reader :predicate
+
+        def initialize(predicate, location:)
+          super(location: location)
+          @predicate = predicate
+        end
+
+        def header_line
+          "Type guard `#{predicate}` is invalid"
+        end
+      end
+
+      class InvalidTypeGuardType < Base
+        attr_reader :type
+
+        def initialize(type, location:)
+          super(location: location)
+          @type = type
+        end
+
+        def header_line
+          "Type guard `#{type}` is invalid"
+        end
+      end
+
 
       def self.from_rbs_error(error, factory:)
         case error

lib/steep/interface/builder.rb

@@ -281,6 +281,7 @@ def singleton_shape(type_name)
               overloads = method.defs.map do |type_def|
                 method_name = method_name_for(type_def, name)
                 method_type = factory.method_type(type_def.type)
+                method_type = replace_guard_method(definition, type_def, method_type)
                 method_type = replace_primitive_method(method_name, type_def, method_type)
                 method_type = replace_kernel_class(method_name, type_def, method_type) { AST::Builtin::Class.instance_type }
                 method_type = add_implicitly_returns_nil(type_def.annotations, method_type)
@@ -313,6 +314,7 @@ def object_shape(type_name)
               overloads = method.defs.map do |type_def|
                 method_name = method_name_for(type_def, name)
                 method_type = factory.method_type(type_def.type)
+                method_type = replace_guard_method(definition, type_def, method_type)
                 method_type = replace_primitive_method(method_name, type_def, method_type)
                 if type_name.class?
                   method_type = replace_kernel_class(method_name, type_def, method_type) { AST::Types::Name::Singleton.new(name: type_name) }
@@ -725,6 +727,35 @@ def proc_shape(proc, proc_shape)
         shape
       end
 
+      def replace_guard_method(definition, method_def, method_type)
+        match = method_def.annotations.filter_map { AST::Types::Logic::Guard::PATTERN.match(_1.string) }.first
+        if match
+          subject = match[1] or raise
+          operator = match[2] or raise
+          type_name = match[3] or raise
+
+          context = context_from(definition.type_name)
+          type = RBS::Parser.parse_type(type_name) or raise
+          type = type.map_type_name { factory.absolute_type_name(_1, context: context) or raise }
+          guard = AST::Types::Logic::Guard.new(subject: subject, operator: operator, type: type)
+
+          method_type.with(type: method_type.type.with(return_type: guard))
+        else
+          method_type
+        end
+      rescue
+        method_type
+      end
+
+      def context_from(type_name)
+        if type_name.namespace == RBS::Namespace.root
+          [nil, type_name]
+        else
+          parent = context_from(type_name.namespace.to_type_name)
+          [parent, type_name]
+        end
+      end
+
       def replace_primitive_method(method_name, method_def, method_type)
         defined_in = method_def.defined_in
         member = method_def.member

lib/steep/signature/validator.rb

@@ -213,7 +213,7 @@ def each_method_type(definition)
         definition.methods.each_value do |method|
           if method.defined_in == type_name
             method.method_types.each do |method_type|
-              yield method_type
+              yield method, method_type
             end
           end
         end
@@ -236,7 +236,7 @@ def each_variable_type(definition)
       end
 
       def validate_definition_type(definition)
-        each_method_type(definition) do |method_type|
+        each_method_type(definition) do |method, method_type|
           upper_bounds = method_type.type_params.each.with_object({}) do |param, hash| #$ Hash[Symbol, AST::Types::t?]
             hash[param.name] = factory.type_opt(param.upper_bound_type)
           end
@@ -245,6 +245,8 @@ def validate_definition_type(definition)
             method_type.each_type do |type|
               validate_type(type)
             end
+
+            validate_method_type(definition, method, method_type)
           end
         end
 
@@ -253,6 +255,44 @@ def validate_definition_type(definition)
         end
       end
 
+      def validate_method_type(definition, method, method_type)
+        annotations = method.defs.find { _1.type == method_type }&.annotations.to_a
+        annotations.each do |annotation|
+          validate_type_guard_annotation(definition, method_type, annotation) if annotation.string.start_with?("guard:")
+        end
+      end
+
+      def validate_type_guard_annotation(definition, method_type, annotation)
+        match = AST::Types::Logic::Guard::PATTERN.match(annotation.string)
+        unless match
+          @errors << Diagnostic::Signature::TypeGuardSyntaxError.new(annotation.string, location: annotation.location)
+          return
+        end
+
+        type_name = match[3] or raise
+        type = RBS::Parser.parse_type(type_name) rescue nil
+        if type.nil?
+          @errors << Diagnostic::Signature::InvalidTypeGuardType.new(type_name, location: annotation.location)
+          return
+        end
+
+        begin
+          context = context_from(definition.type_name)
+          type = type.map_type_name { factory.absolute_type_name(_1, context: context) or raise }
+        rescue
+          @errors << Diagnostic::Signature::InvalidTypeGuardType.new(type_name, location: annotation.location)
+        end
+      end
+
+      def context_from(type_name)
+        if type_name.namespace == RBS::Namespace.root
+          [nil, type_name]
+        else
+          parent = context_from(type_name.namespace.to_type_name)
+          [parent, type_name]
+        end
+      end
+
       def validate_type_params(type_name, type_params)
         if error_type_params = RBS::AST::TypeParam.validate(type_params)
           error_type_params.each do |type_param|

lib/steep/type_inference/logic_type_interpreter.rb

@@ -405,6 +405,38 @@ def evaluate_method_call(env:, type:, receiver:, arguments:)
               truthy_result.update_type { FALSE }
             ]
           end
+
+        when AST::Types::Logic::Guard
+          if receiver
+            receiver_type = factory.deep_expand_alias(typing.type_of(node: receiver)) || raise
+
+            # TODO: Support argument types (ex. `self is arg1`)
+            # TODO: Support class' type param types (ex. `self is T`)
+            # TODO: Support method's type param types (ex. `self is T`)
+            # TODO: Support is_a operator
+
+            sub_type = factory.type(type.type)
+            if no_subtyping?(sub_type: sub_type, super_type: receiver_type)
+              typing.add_error(Diagnostic::Ruby::InsufficientTypeGuard.new(node: receiver, super_type: receiver_type, sub_type: sub_type))
+              return
+            end
+
+            truthy_type, falsy_type = type_guard_type_case_select(receiver_type, sub_type)
+            truthy_env, falsy_env = refine_node_type(
+              env: env,
+              node: receiver,
+              truthy_type: truthy_type || receiver_type,
+              falsy_type: falsy_type || UNTYPED
+            )
+
+            truthy_result = Result.new(type: TRUE, env: truthy_env, unreachable: false)
+            truthy_result.unreachable! unless truthy_type
+
+            falsy_result = Result.new(type: FALSE, env: falsy_env, unreachable: false)
+            falsy_result.unreachable! unless falsy_type
+
+            [truthy_result, falsy_result]
+          end
         end
       end
 
@@ -494,25 +526,33 @@ def literal_var_type_case_select(value_node, arg_type)
         end
       end
 
-      def type_case_select(type, klass)
-        truth_types, false_types = type_case_select0(type, klass)
+      def type_guard_type_case_select(type, guard_type)
+        truth_types, false_types = type_case_select0(type, guard_type)
 
         [
           truth_types.empty? ? nil : AST::Types::Union.build(types: truth_types),
           false_types.empty? ? nil : AST::Types::Union.build(types: false_types)
         ]
       end
 
-      def type_case_select0(type, klass)
+      def type_case_select(type, klass)
         instance_type = factory.instance_type(klass)
+        truth_types, false_types = type_case_select0(type, instance_type)
+
+        [
+          truth_types.empty? ? nil : AST::Types::Union.build(types: truth_types),
+          false_types.empty? ? nil : AST::Types::Union.build(types: false_types)
+        ]
+      end
 
+      def type_case_select0(type, instance_type)
         case type
         when AST::Types::Union
           truthy_types = [] # :Array[AST::Types::t]
           falsy_types = [] #: Array[AST::Types::t]
 
           type.types.each do |ty|
-            truths, falses = type_case_select0(ty, klass)
+            truths, falses = type_case_select0(ty, instance_type)
 
             if truths.empty?
               falsy_types.push(ty)
@@ -529,7 +569,7 @@ def type_case_select0(type, klass)
           if ty == type
             [[type], [type]]
           else
-            type_case_select0(ty, klass)
+            type_case_select0(ty, instance_type)
           end
 
         when AST::Types::Any, AST::Types::Top, AST::Types::Var

sig/steep/ast/types.rbs

@@ -6,7 +6,7 @@ module Steep
            | Intersection  | Record | Tuple | Union
            | Name::Alias | Name::Instance | Name::Interface | Name::Singleton
            | Proc | Var
-           | Logic::Not | Logic::ReceiverIsNil | Logic::ReceiverIsNotNil | Logic::ReceiverIsArg | Logic::ArgIsReceiver | Logic::ArgEqualsReceiver | Logic::ArgIsAncestor | Logic::Env
+           | Logic::Not | Logic::ReceiverIsNil | Logic::ReceiverIsNotNil | Logic::ReceiverIsArg | Logic::ArgIsReceiver | Logic::ArgEqualsReceiver | Logic::ArgIsAncestor | Logic::Guard | Logic::Env
 
       # Variables and special types that is subject for substitution
       #

sig/steep/ast/types/logic.rbs

@@ -50,6 +50,19 @@ module Steep
         class ArgIsAncestor < Base
         end
 
+        # A type for type guard.
+        class Guard < Base
+          PATTERN: Regexp
+
+          attr_reader subject: String
+          attr_reader operator: String
+          attr_reader type: RBS::Types::t
+
+          def self.new: (subject: String, operator: String, type: RBS::Types::t) -> Guard
+
+          def initialize: (subject: String, operator: String, type: RBS::Types::t) -> void
+        end
+
         # A type with truthy/falsy type environment.
         class Env < Base
           attr_reader truthy: TypeInference::TypeEnv

sig/steep/diagnostic/ruby.rbs

@@ -1911,6 +1911,46 @@ module Steep
         def header_line: () -> String
       end
 
+      # A type guard method doesn't narrow the type because the determined type is not a subtype of the actual type.
+      #
+      # ### RBS
+      #
+      # ```rbs
+      # class Object
+      #   %a{guard:self is String}
+      #   def string?: () -> bool
+      # end
+      # ```
+      #
+      # ### Ruby code
+      #
+      # ```ruby
+      # a = 123
+      # if a.string?
+      #   puts "Hello"
+      # end
+      # ```
+      #
+      # ### Diagnostic
+      #
+      # ```
+      # test.rb:2:4: [error] Cannot narrow the type: ::Integer is not a subtype of ::String
+      # │ Diagnostic ID: Ruby::InsufficientTypeGuard
+      # │
+      # └   if a.string?
+      #        ~
+      # ```
+      #
+      class InsufficientTypeGuard < Base
+        attr_reader node (): Node
+        attr_reader super_type: AST::Types::t
+        attr_reader sub_type: AST::Types::t
+
+        def initialize: (node: Node, super_type: AST::Types::t, sub_type: AST::Types::t) -> void
+
+        def header_line: () -> String
+      end
+
       ALL: Array[singleton(Base)]
 
       type template = Hash[singleton(Base), LSPFormatter::severity?]