typeguard 1.0.0

data/lib/typeguard/type_model/builder/yard_builder.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'yard'
+
+module Typeguard
+  module TypeModel
+    module Builder
+      # Takes YARD documentation and returns a generic type model
+      class YardBuilder
+        include Typeguard::TypeModel::Definitions
+
+        # @see https://rubydoc.info/gems/typeguard/YARD/Registry
+        # @param reparse_files [Boolean] has no effect if target is a string.
+        #   If false and target is an array, the files are only reparsed if no .yardoc is present.
+        #   If true and target is an array, the files are always reparsed.
+        def initialize(target, reparse_files)
+          @object_vars = {}
+          return unless YARD::Registry.load(target, reparse_files).root.children.empty?
+
+          if target.is_a?(String)
+            puts "WARNING: could not find YARD objects for target directory '#{target}'. " \
+            "Confirm that the directory exists and/or execute 'yardoc [...]' again."
+          else
+            puts "WARNING: could not find YARD objects for target files after reparsing array #{target}. " \
+            "Confirm that the files exist and/or execute 'yardoc #{target.join(' ')}' again in the correct directory."
+          end
+        end
+
+        def build
+          # Deduplicated tree-like structure where the root is an array of
+          # objects whose parent is undefined or YARD root/proxy
+          YARD::Registry.all(:class, :module, :method).filter_map do |object|
+            build_object(object) if object.parent.nil? || %i[root proxy].include?(object.parent.type)
+          end
+        end
+
+        def build_object(object)
+          case object.type
+          when :class
+            children = object.children.map { |child| build_object(child) }.compact
+            ClassDefinition.new(
+              name: object.path.gsub('.self', ''),
+              source: "#{object.file}:#{object.line}",
+              vars: build_inherit_vars(object),
+              parent: object.superclass&.path,
+              type_parameters: nil,
+              children: children
+            )
+          when :module
+            children = object.children.map { |child| build_object(child) }.compact
+            ModuleDefinition.new(
+              name: object.path.gsub('.self', ''),
+              source: "#{object.file}:#{object.line}",
+              vars: build_inherit_vars(object),
+              type_parameters: nil,
+              children: children
+            )
+          when :method
+            return_tag = object.tag(:return)
+            returns = ReturnDefinition.new(
+              source: "#{object.file}:#{object.line}",
+              types: build_types(return_tag),
+              types_string: build_types_string(return_tag)
+            )
+            MethodDefinition.new(
+              name: object.name,
+              source: "#{object.file}:#{object.line}",
+              scope: object.scope,
+              visibility: object.visibility,
+              parameters: build_parameters(object),
+              returns: returns
+            )
+          when :constant, :classvariable, :proxy
+            # Covered by build_vars and build
+          else
+            raise "Unsupported YARD object: #{object.class}"
+          end
+        end
+
+        def build_parameters(object)
+          unbound_children = object.tags(:option).each_with_object({}) do |tag, hash|
+            index = tag.name.gsub(/:/, '')
+            hash[index] ||= [[], []]
+            key = build_symbol
+            key.metadata[:key] = tag.pair.name.gsub(/:/, '')
+            value = build_types(tag.pair)
+            value.each { |node| node.metadata[:defaults] = tag.pair.defaults }
+            hash[index].first << key
+            hash[index].last << value
+          end
+
+          ps = object.parameters.dup
+          parameters = object.tags(:param).map do |tag|
+            param = ps.find { |name, _| name.gsub(/[*:]/, '') == tag.name }
+            next unless param
+
+            ps.delete(param)
+            bound_children = unbound_children.delete(tag.name)
+            ParameterDefinition.new(
+              name: tag.name.to_sym,
+              source: "#{object.file}:#{object.line}",
+              default: param.last,
+              types: bound_children ? [build_fixed_hash(bound_children)] : build_types(tag),
+              types_string: build_types_string(tag)
+            )
+          end
+
+          untyped_defaults = ps.reject { |_, default| default.nil? }
+          untyped_defaults.each do |name, default|
+            parameter = ParameterDefinition.new(
+              name: name.to_sym,
+              source: "#{object.file}:#{object.line}",
+              default: default,
+              types: build_types(nil),
+              types_string: build_types_string(nil)
+            )
+            parameters << parameter
+          end
+
+          unbound_children.each do |k, v|
+            parameter = ParameterDefinition.new(
+              name: k,
+              source: "#{object.file}:#{object.line}",
+              default: nil,
+              types: [build_fixed_hash(v)],
+              types_string: 'Hash'
+            )
+            parameters << parameter
+          end
+
+          parameters
+        end
+
+        def build_inherit_vars(object)
+          # Looks at mixins and superclasses to build a full set
+          # of (inherited) vars, order-preserved such that the
+          # narrowest namespace takes precedence: if class A and
+          # B < A define attribute c, the definition of A::B holds
+          # pp "build_inherit_vars for #{object}"
+          # object.inheritance_tree(true).flat_map do |inherited|
+          object.inheritance_tree(true).flat_map do |inherited|
+            @object_vars[inherited] ||= build_vars(inherited)
+          end.uniq(&:name)
+        end
+
+        def build_vars(object)
+          return [] unless %i[class module].include?(object.type)
+
+          # NOTE: When a module is defined with .self syntax
+          # and also referenced with :: syntax, the reference
+          # is interpreted as a proxy. You could eventually
+          # find the actual code object, but iteratively
+          # replacing every :: with .self or vice versa and
+          # performing the lookup is not very nice. So, we
+          # simply don't propagate in this case.
+          return [] if object.is_a? YARD::CodeObjects::Proxy
+
+          vars = []
+          object.cvars.each do |cvar|
+            return_tag = cvar.tag(:return)
+            vars << VarDefinition.new(
+              name: cvar.name,
+              source: "#{cvar.file}:#{cvar.line}",
+              scope: :class,
+              types: build_types(return_tag),
+              types_string: build_types_string(return_tag)
+            )
+          end
+          object.constants.each do |const|
+            return_tag = const.tag(:return)
+            vars << VarDefinition.new(
+              name: const.name,
+              source: "#{const.file}:#{const.line}",
+              scope: :constant,
+              types: build_types(return_tag),
+              types_string: build_types_string(return_tag)
+            )
+          end
+          object.attributes[:instance].each do |key, value|
+            method = value[:read]
+            return_tag = method.tag(:return)
+            vars << VarDefinition.new(
+              name: "@#{key}".to_sym,
+              source: "#{method.file}:#{method.line}",
+              scope: :instance,
+              types: build_types(return_tag),
+              types_string: build_types_string(return_tag)
+            )
+          end
+          object.attributes[:class].each do |key, value|
+            method = value[:read]
+            return_tag = method.tag(:return)
+            vars << VarDefinition.new(
+              name: key,
+              source: "#{method.file}:#{method.line}",
+              scope: :self,
+              types: build_types(return_tag),
+              types_string: build_types_string(return_tag)
+            )
+          end
+
+          vars
+        end
+
+        def build_types(tag)
+          if tag.respond_to?(:types) && tag.types && !tag.types.empty?
+            tag.types.map { |t| Typeguard::TypeModel::Mapper::YardMapper.parse_map(t) }
+          else
+            result = TypeNode.new(
+              kind: :untyped,
+              shape: :untyped,
+              children: [],
+              metadata: { note: 'Types specifier list is empty: untyped' }
+            )
+            [result]
+          end
+        end
+
+        def build_types_string(tag)
+          tag.respond_to?(:types) && !tag.types.nil? ? tag.types.join(' or ') : []
+        end
+
+        def build_symbol
+          Typeguard::TypeModel::Mapper::YardMapper.parse_map('Symbol')
+        end
+
+        def build_fixed_hash(children)
+          node = Typeguard::TypeModel::Mapper::YardMapper.parse_map('Hash')
+          node.shape = :fixed_hash
+          node.children = children
+          node.metadata[:note] = 'Hash specified via @options'
+          node
+        end
+      end
+    end
+  end
+end

data/lib/typeguard/type_model/builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Typeguard
+  module TypeModel
+    module Builder
+      IMPL_SYM = :IMPLEMENTATION
+      def self.yard
+        require_relative 'builder/yard_builder'
+        require_relative 'mapper/yard_mapper'
+        const_set(IMPL_SYM, YardBuilder)
+      end
+
+      def self.rbs
+        require_relative 'builder/rbs_builder'
+        require_relative 'mapper/rbs_mapper'
+        const_set(IMPL_SYM, RBSBuilder)
+      end
+    end
+  end
+end

data/lib/typeguard/type_model/definitions.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Typeguard
+  module TypeModel
+    module Definitions
+      TypeNode = Struct.new(:kind, :shape, :children, :metadata, keyword_init: true)
+      ModuleDefinition = Struct.new(:name, :source, :vars, :type_parameters, :children, keyword_init: true)
+      ClassDefinition = Struct.new(:name, :source, :vars, :parent, :type_parameters, :children, keyword_init: true)
+      MethodDefinition = Struct.new(:name, :source, :scope, :visibility, :parameters, :returns, keyword_init: true)
+      ParameterDefinition = Struct.new(:name, :source, :default, :types, :types_string, keyword_init: true)
+      ReturnDefinition = Struct.new(:source, :types, :types_string, keyword_init: true)
+      VarDefinition = Struct.new(:name, :source, :scope, :types, :types_string, keyword_init: true)
+    end
+  end
+end

data/lib/typeguard/type_model/mapper/rbs_mapper.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'rbs'
+
+module Typeguard
+  module TypeModel
+    module Mapper
+      # Maps RBS types to the generic type model
+      class RBSMapper
+        include Typeguard::TypeModel::Definitions
+
+        # @param type [RBS::Types::Base] an RBS type object
+        # @return [TypeNode] a mapped type node in the generic model.
+        def self.parse_map(type)
+          map_rbs(type)
+        end
+
+        def self.map_rbs(node)
+          name = (node.respond_to?(:name) ? node.name.relative!.to_s : node.to_s).to_sym
+          mapped_node = TypeNode.new(kind: name, shape: :basic, children: [], metadata: {})
+
+          case node
+          when RBS::Types::ClassInstance
+            if node.args.empty?
+              mapped_node.shape = :basic
+            elsif node.name.name == :Hash && node.args.length == 2
+              key_node = map_rbs(node.args.first)
+              value_node = map_rbs(node.args.last)
+              mapped_node.shape = :hash
+              mapped_node.children = [[key_node], [value_node]]
+              mapped_node.metadata[:note] = 'Hash specified via parametrized types: one key and one value type'
+            else
+              children = node.args.map { |arg| map_rbs(arg) }
+              mapped_node.children = children
+              mapped_node.shape = :generic
+            end
+          when RBS::Types::Tuple
+            children = node.types.map { |child| map_rbs(child) }
+            mapped_node.kind = :Array
+            mapped_node.shape = :fixed
+            mapped_node.children = children
+            mapped_node.metadata[:note] = 'Tuples are a fixed-length array with known types for each element'
+          when RBS::Types::Union
+            children = node.types.map { |child| map_rbs(child) }
+            mapped_node.shape = :union
+            mapped_node.children = children
+            mapped_node.metadata[:note] = 'Union types denote a type of one of the given types'
+          when RBS::Types::Optional
+            child = map_rbs(node.type)
+            nil_node = TypeNode.new(kind: :nil, shape: :literal, children: [], metadata: { note: 'Optional nil' })
+            mapped_node.shape = :union
+            mapped_node.children = [child, nil_node]
+            mapped_node.metadata[:note] = 'Optional type'
+          when RBS::Types::Bases::Bool
+            true_node  = TypeNode.new(kind: :TrueClass, shape: :basic, children: [], metadata: {})
+            false_node = TypeNode.new(kind: :FalseClass, shape: :basic, children: [], metadata: {})
+            mapped_node.kind = :boolean
+            mapped_node.shape = :union
+            mapped_node.children = [true_node, false_node]
+            mapped_node.metadata = { note: 'Boolean represents both TrueClass and FalseClass' }
+          when RBS::Types::Bases::Any
+            mapped_node.kind = :untyped
+            mapped_node.shape = :untyped
+            mapped_node.metadata[:note] = 'Type not specified: any'
+          when RBS::Types::Bases::Self
+            mapped_node.shape = :literal
+            mapped_node.metadata[:note] = 'self indicates that calling this method on will return the same type as the type of the receiver'
+          when RBS::Types::Bases::Void
+            mapped_node.shape = :literal
+            mapped_node.metadata[:note] = 'void is only allowed as a return type or a generic parameter'
+          when RBS::Types::Bases::Nil
+            mapped_node.shape = :literal
+            mapped_node.metadata[:note] = 'nil is for nil. nil is recommended over NilClass'
+          when RBS::Types::Literal
+            mapped_node.shape = :literal
+            mapped_node.metadata[:note] = 'Literal types denote a type with only one value of the literal'
+          else raise "Unknown node type: #{node.class} #{node}"
+          end
+          mapped_node
+        end
+      end
+    end
+  end
+end

data/lib/typeguard/type_model/mapper/yard_mapper.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Typeguard
+  module TypeModel
+    module Mapper
+      # Maps YARD types to the type model
+      class YardMapper
+        include Typeguard::TypeModel::Definitions
+
+        SPECIAL_LITERALS = %w[true false nil self void].freeze
+
+        def self.parse_map(type)
+          # NOTE: Using private YARD API here.
+          map_yard(YARD::Tags::TypesExplainer::Parser.parse(type).first)
+        end
+
+        def self.map_yard(node)
+          mapped_node = TypeNode.new(kind: node.name.to_sym, shape: :basic, children: [], metadata: {})
+          case node
+          when YARD::Tags::TypesExplainer::FixedCollectionType
+            children = node.types.map { |child| map_yard(child) }
+            mapped_node.shape = :fixed
+            mapped_node.children = children
+            mapped_node.metadata[:note] = 'Order-dependent lists must appear in the exact order'
+          when YARD::Tags::TypesExplainer::CollectionType
+            if node.name == 'Hash' && node.types.length == 2
+              key_node = map_yard(node.types.first)
+              value_node = map_yard(node.types.last)
+              mapped_node.shape = :hash
+              mapped_node.children = [[key_node], [value_node]]
+              mapped_node.metadata[:note] = 'Hash specified via parametrized types: one key and one value type'
+            else
+              children = node.types.map { |child| map_yard(child) }
+              mapped_node.shape = :generic
+              mapped_node.children = children
+              mapped_node.metadata[:note] = 'Generics specify one or more parametrized types'
+            end
+          when YARD::Tags::TypesExplainer::HashCollectionType
+            key_nodes = node.key_types.map { |k| map_yard(k) }
+            value_nodes = node.value_types.map { |v| map_yard(v) }
+            mapped_node.shape = :hash
+            mapped_node.children = [key_nodes, value_nodes]
+            mapped_node.metadata[:note] = 'Hash specified via rocket syntax: multiple key and value type'
+          when YARD::Tags::TypesExplainer::Type
+            map_base(node, mapped_node)
+          else raise "Unknown node type: #{node.class}"
+          end
+          mapped_node
+        end
+
+        def self.map_base(node, mapped_node)
+          case node.name
+          when *SPECIAL_LITERALS
+            mapped_node.shape = :literal
+            mapped_node.metadata = { note: 'Ruby (and YARD) supported literal' }
+          when 'Boolean'
+            true_node  = TypeNode.new(kind: :TrueClass, shape: :basic, children: [], metadata: {})
+            false_node = TypeNode.new(kind: :FalseClass, shape: :basic, children: [], metadata: {})
+            mapped_node.kind = :boolean
+            mapped_node.shape = :union
+            mapped_node.children = [true_node, false_node]
+            mapped_node.metadata = { note: 'Boolean represents both TrueClass and FalseClass' }
+          when /^#\w+/
+            mapped_node.shape = :duck
+            mapped_node.metadata = { note: "Duck-type: object should respond to :#{node.name[1..]}" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/typeguard/types.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Typeguard
+  module Validation
+    class Base
+      def self.from(node)
+        case node.shape
+        when :basic
+          Basic.new(node)
+        when :generic
+          Generic.new(node)
+        when :fixed
+          Fixed.new(node)
+        when :hash
+          GenericHash.new(node)
+        when :fixed_hash
+          FixedHash.new(node)
+        when :union
+          Union.new(node)
+        when :literal
+          case node.kind
+          when :nil then Nil.new
+          when :void, :self then Untyped.new
+          else Literal.new(node)
+          end
+        when :duck
+          Duck.new(node)
+        when :untyped
+          Untyped.new
+        else
+          raise "Unexpected type node shape: #{node.shape}"
+        end
+      end
+
+      def valid?(_value)
+        raise NotImplementedError, 'Abstract'
+      end
+    end
+
+    class Basic < Base
+      def initialize(node)
+        @klass = node.metadata[:const]
+      end
+
+      def valid?(value)
+        value.is_a?(@klass)
+      end
+    end
+
+    class Generic < Base
+      def initialize(node)
+        @klass = node.metadata[:const]
+        @children = node.children.map { |child| Base.from(child) }
+      end
+
+      def valid?(value)
+        return false unless value.is_a?(@klass)
+
+        value.all? do |element|
+          @children.any? { |child| child.valid?(element) }
+        end
+      end
+    end
+
+    class Fixed < Base
+      def initialize(node)
+        @klass = node.metadata[:const]
+        @children = node.children.map { |child| Base.from(child) }
+      end
+
+      def valid?(value)
+        return false unless value.is_a?(@klass)
+        return false unless value.size == @children.size
+
+        @children.each_with_index.all? do |child, i|
+          child.valid?(value[i])
+        end
+      end
+    end
+
+    class GenericHash < Base
+      def initialize(node)
+        @klass = node.metadata[:const]
+        @keys   = node.children.first.map { |k| Base.from(k) }
+        @values = node.children.last.map { |v| Base.from(v) }
+      end
+
+      def valid?(value)
+        return false unless value.is_a?(@klass)
+
+        value.all? do |k, v|
+          key_valid = @keys.any? { |child| child.valid?(k) }
+          value_valid = @values.any? { |child| child.valid?(v) }
+          key_valid && value_valid
+        end
+      end
+    end
+
+    class FixedHash < Base
+      def initialize(node)
+        @klass = node.metadata[:const]
+        @map = node.children.transpose.each_with_object({}) do |(k, v), h|
+          index = k.metadata[:key]
+          k_validator = Base.from(k)
+          v_validators = v.map { |val| Base.from(val) }
+          h[index] = [k_validator, v_validators]
+        end
+      end
+
+      def valid?(value)
+        return false unless value.is_a?(@klass)
+
+        value.all? do |k, v|
+          index = k.to_s
+          return false unless @map.key?(index)
+
+          k_validator, v_validator = @map[index]
+          key_valid = k_validator.valid?(k)
+          value_valid = v_validator.any? { |child| child.valid?(v) }
+          key_valid && value_valid
+        end
+      end
+    end
+
+    class Union < Base
+      def initialize(node)
+        @children = node.children.map { |child| Base.from(child) }
+      end
+
+      def valid?(value)
+        @children.any? { |child| child.valid?(value) }
+      end
+    end
+
+    class Literal < Base
+      def initialize(node)
+        @expected = node.kind.to_s
+      end
+
+      def valid?(value)
+        value.to_s == @expected
+      end
+    end
+
+    class Nil < Base
+      def valid?(value)
+        value.nil?
+      end
+    end
+
+    class Duck < Base
+      def initialize(node)
+        @name = node.kind[1..]
+      end
+
+      def valid?(value)
+        value.respond_to?(@name)
+      end
+    end
+
+    class Untyped < Base
+      def valid?(_)
+        true
+      end
+    end
+
+    class UnionOf < Base
+      def initialize(children)
+        @children = children
+      end
+
+      def valid?(value)
+        @children.any? { |v| v.valid?(value) }
+      end
+    end
+  end
+end

data/lib/typeguard/validator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Typeguard
+  module Validation
+    class Validator
+      def self.param_validator(types)
+        children = types.map { |node| Base.from(node) }
+        if children.size == 1
+          children.first
+        else
+          UnionOf.new(children)
+        end
+      end
+
+      def self.zip_params(method_params, sig_params)
+        method_params.map do |mp|
+          sig_param = sig_params.find { |sp| sp.name.to_s.gsub(/[*:]/, '').to_sym == mp.last }
+          validator = param_validator(sig_param.types) if sig_param
+          [mp, sig_param, validator]
+        end
+      end
+
+      def self.param_names(zipped_params)
+        # Tuples of [parameter, invocation] names
+        zipped_params.map do |(type, name), sp, _|
+          name = name.to_s
+          case type
+          when :req     then [name, name]                                         # foo
+          when :keyreq  then ["#{name}:", "#{name}: #{name}"]                     # foo:
+          when :keyrest then [name == '**' ? name : "**#{name}"] * 2              # **foo
+          when :rest    then [name == '*' ? name : "*#{name}"] * 2                # *foo
+          when :block   then [name == '&' ? name : "&#{name}"] * 2                # &foo
+          when :opt     then ["#{name} = (#{sp.default})", name]                  # foo = (bar)
+          when :key     then ["#{name}: (#{sp.default})", "#{name}: #{name}"]     # foo: (bar)
+          when :nokey   then ['**nil'] * 2                                        # **nil
+          else raise type.to_s
+          end
+        end
+      end
+
+      def self.exhaustive_path(mod, method, sig)
+        zipped_params = zip_params(method.parameters, sig.parameters)
+        return_validator = (param_validator(sig.returns.types) if sig.returns && !sig.returns.types.empty?)
+        p_names = param_names(zipped_params)
+        block_params = p_names.map(&:first).join(', ')
+        call_args = p_names.map(&:last).reject { |s| ['*', '**', '&'].include?(s) }.join(', ')
+        locals = method.parameters.map do |s|
+          return nil if s.size == 1 # Ruby 3.1.0 compatible
+
+          ['*', '**', '&'].include?(s.last.to_s) ? nil : s.last
+        end.compact.join(', ')
+        redefinition = sig.scope == :class ? 'define_singleton_method' : 'define_method'
+        if return_validator
+          mod.module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            #{redefinition}(sig.name) do |#{block_params}|
+              zipped_params.zip([#{locals}]).each do |(mp, sp, validator), local|
+                next if validator.nil? || validator.valid?(local)
+
+                Metrics.report_unexpected_argument(sig, sp.types_string, local, mod.name, sp)
+              end
+              result = method.bind_call(self, #{call_args})
+              unless return_validator.valid?(result)
+                Metrics.report_unexpected_return(sig, sig.returns.types_string, result, mod.name)
+              end
+              result
+            end
+          RUBY
+        else
+          mod.module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            #{redefinition}(sig.name) do |#{block_params}|
+              zipped_params.zip([#{locals}]).each do |(mp, sp, validator), local|
+                next if validator.nil? || validator.valid?(local)
+
+                Metrics.report_unexpected_argument(sig, sp.types_string, local, mod.name, sp)
+              end
+              method.bind_call(self, #{call_args})
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/typeguard/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Typeguard
+  VERSION = '1.0.0'
+end