houndstooth 0.1.0

data/lib/houndstooth/environment/builder.rb

@@ -0,0 +1,260 @@
+class Houndstooth::Environment
+    # Analyses a `SemanticNode` tree and builds a set of types and definitions for an `Environment`.
+    #
+    # It's likely this entire class will be unnecessary when CTFE is implemented, but it's a nice
+    # starting point for a basic typing checker.
+    class Builder
+        def initialize(root, environment)
+            @root = root
+            @environment = environment
+        end
+
+        # @return [SemanticNode]
+        attr_reader :root
+
+        # @return [Environment]
+        attr_reader :environment
+
+        def analyze(node: root, type_context: :root)
+            # Note for type_context:
+            #   - An instance of `DefinedType` means that new methods, subtypes etc encountered in
+            #     the node tree will be defined there
+            #   - The symbol `:root` means they're defined at the top-level of the environment
+            #   - `nil` means types and methods cannot be defined here
+
+            # TODO: consider if there's things which will "invalidate" a type context, turning it 
+            # to nil - do we actually bother traversing into such things?
+            # Even if we don't, the CTFE component presumably will
+
+            case node
+            when Houndstooth::SemanticNode::Body
+                node.nodes.each do |child_node|
+                    analyze(node: child_node, type_context: type_context)
+                end
+
+            when Houndstooth::SemanticNode::ClassDefinition
+                is_magic_basic_object = node.comments.find { |c| c.text.strip == "#!magic basicobject" }
+
+                name = constant_to_string(node.name)
+                if name.nil?
+                    Houndstooth::Errors::Error.new(
+                        "Class name is not a constant",
+                        [[node.name.ast_node.loc.expression, "not a constant"]]
+                    ).push
+                    return 
+                end
+
+                if node.superclass
+                    superclass = constant_to_string(node.superclass)
+                    if superclass.nil?
+                        Houndstooth::Errors::Error.new(
+                            "Superclass is not a constant",
+                            [[node.superclass.ast_node.loc.expression, "not a constant"]]
+                        ).push
+                        return 
+                    end
+                else
+                    # Special case used only for BasicObject
+                    if is_magic_basic_object
+                        superclass = nil 
+                    else
+                        superclass = "Object"
+                    end
+                end
+
+                new_type = DefinedType.new(
+                    node: node,
+                    path: append_type_and_rel_path(type_context, name),
+                    type_parameters: type_parameter_definitions(node),
+                    superclass: superclass ? PendingDefinedType.new(superclass) : nil
+                )
+                
+                if is_magic_basic_object
+                    new_type.eigen = DefinedType.new(
+                        path: "<Eigen:BasicObject>",
+                        superclass: PendingDefinedType.new("Class"),
+                        instance_methods: [
+                            SpecialConstructorMethod.new(:new),
+                        ],
+                    )
+                end
+
+                # Find instance variable definitions
+                node.comments
+                    .select { |c| c.text.start_with?('#!var ') }
+                    .each do |c|
+                        unless /^#!var\s+(@[a-zA-Z_][a-zA-Z0-9_]*)\s+(.+)\s*$/ === c.text
+                            Houndstooth::Errors::Error.new(
+                                "Malformed #!var definition",
+                                [[c.loc.expression, "invalid"]]
+                            ).push
+                            next 
+                        end
+
+                        var_name = $1
+                        type = $2
+                        
+                        new_type.type_instance_variables[var_name] = TypeParser.parse_type(type)
+                    end
+
+                environment.add_type(new_type)
+
+                analyze(node: node.body, type_context: new_type)
+
+            when Houndstooth::SemanticNode::ModuleDefinition
+                name = constant_to_string(node.name)
+                if name.nil?
+                    Houndstooth::Errors::Error.new(
+                        "Class name is not a constant",
+                        [[node.name.ast_node.loc.expression, "not a constant"]]
+                    ).push
+                    return 
+                end
+
+                new_type = DefinedType.new(
+                    node: node,
+                    type_parameters: type_parameter_definitions(node),
+                    path: append_type_and_rel_path(type_context, name),
+                )
+                new_type.eigen.superclass = PendingDefinedType.new("Module")
+                environment.add_type(new_type)
+
+                analyze(node: node.body, type_context: new_type)
+            
+            when Houndstooth::SemanticNode::MethodDefinition
+                if node.target.nil?
+                    target = type_context
+                elsif node.target.is_a?(Houndstooth::SemanticNode::SelfKeyword)
+                    target = type_context.eigen
+                else
+                    # TODO
+                    Houndstooth::Errors::Error.new(
+                        "`self` is the only supported explicit target",
+                        [[node.target.ast_node.loc.expression, "unsupported"]]
+                    ).push
+                    return 
+                end
+
+                name = node.name
+                
+                # Look for signature comments attached to this definition - those beginning with:
+                #   #:
+                # The rest of the comment is an RBS signature attached to that method
+                signatures = node.comments
+                    .filter { |comment| comment.text.start_with?('#: ') }
+                    .map do |comment|
+                        TypeParser.parse_method_type(
+                            comment.text[3...].strip,
+                            type_parameters:
+                                type_context.is_a?(DefinedType) \
+                                    ? type_context.type_parameters
+                                    : nil,
+                            method_definition_parameters: node.parameters
+                        ) 
+                    end
+
+                # Look for a declaration that this method is const
+                const = nil
+                const_decls = node.comments
+                    .filter { |c| c.text.start_with?('#!const') }
+                    .map { |c| c.text }
+                if const_decls.length == 1
+                    parts = const_decls.first.strip.split
+                    if parts.length != 1 && parts.length != 2
+                        Houndstooth::Errors::Error.new(
+                            "Malformed #!const definition",
+                            [[node.ast_node.loc.expression, "too many parts"]],
+                        ).push
+                    elsif parts[1] && !['required', 'internal', 'required_internal'].include?(parts[1])
+                        Houndstooth::Errors::Error.new(
+                            "Malformed #!const definition",
+                            [[node.ast_node.loc.expression, "don't understand '#{parts[1]}'"]],
+                        ).push
+                    else
+                        if parts[1]
+                            const = parts[1].to_sym
+                        else
+                            const = :normal
+                        end
+                    end
+                elsif const_decls.length == 0
+                    # That's fine, just leave `const` as nil
+                else
+                    Houndstooth::Errors::Error.new(
+                        "Only one #!const comment is allowed",
+                        [[node.ast_node.loc.expression, "multiple #!const comments given"]],
+                    ).push
+                end
+
+                if type_context.nil? || type_context == :root
+                    # TODO method definitions should definitely be allowed at the root!
+                    Houndstooth::Errors::Error.new(
+                        "Method definition not allowed here",
+                        [[node.ast_node.loc.keyword, "not allowed"]]
+                    ).push
+                    return
+                end
+
+                # TODO: Don't allow methods with duplicate names
+                target.instance_methods << Method.new(name, signatures, const: const)
+            end
+        end
+
+        # Tries to convert a series of nested `Constant`s into a String path.
+        # 
+        # If one of the items in the constant tree is not a `Constant` (or `ConstantRoot`), returns
+        # nil. 
+        #
+        # @param [SemanticNode::Base] node
+        # @return [String, nil]
+        def constant_to_string(node)
+            case node
+            when Houndstooth::SemanticNode::Constant
+                if node.target.nil?
+                    node.name.to_s
+                else
+                    target_as_str = constant_to_string(node.target) or return nil
+                    "#{target_as_str}::#{node.name}"
+                end
+            when Houndstooth::SemanticNode::ConstantBase
+                ''
+            else
+                nil
+            end
+        end
+
+        # Given a `DefinedType`, appends a relative path to its path.
+        #
+        # @param [DefinedType] type
+        # @param [String] rel
+        # @return [String]
+        def append_type_and_rel_path(type, rel)
+            if rel.start_with?('::')
+                rel[2..]
+            else
+                if type == :root
+                    rel
+                else
+                    "#{type.path}::#{rel}"
+                end
+            end
+        end
+
+        # Given a node, gets any type parameters defined on it.
+        def type_parameter_definitions(node)
+            node.comments
+                .select { |c| c.text.start_with?('#!param ') }
+                .map do |c|
+                    unless /^#!param\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*$/ === c.text
+                        Houndstooth::Errors::Error.new(
+                            "Malformed #!param definition",
+                            [[c.loc.expression, "invalid"]]
+                        ).push
+                        return 
+                    end
+
+                    $1
+                end
+        end
+    end
+end

data/lib/houndstooth/environment/type_parser.rb

@@ -0,0 +1,149 @@
+require 'rbs'
+
+class Houndstooth::Environment
+    module TypeParser
+        # Parses an RBS type signature, e.g. "(String) -> Integer", and returns it as a `Type` in 
+        # this project's type model.
+        #
+        # The types used do not necessarily need to be defined - all type references in the
+        # returned signature will be instances of `PendingDefinedType`, which can be converted to
+        # `DefinedType` using `Type#resolve_all_pending_types`.
+        #
+        # @param [String] input
+        # @return [Type]
+        def self.parse_method_type(input, type_parameters: nil, method_definition_parameters: nil)
+            types_from_rbs(
+                RBS::Parser.parse_method_type(input),
+                type_parameters: type_parameters,
+                method_definition_parameters: method_definition_parameters
+            )
+        end
+
+        # Same as `parse_method_type`, but parses a singular type, such as `String`.
+        #
+        # @param [String] input
+        # @return [Type]
+        def self.parse_type(input, type_parameters: nil, method_definition_parameters: nil)
+            types_from_rbs(
+                RBS::Parser.parse_type(input),
+                type_parameters: type_parameters,
+                method_definition_parameters: method_definition_parameters
+            )
+        end
+
+        # Converts an RBS type to this project's type model.
+        def self.types_from_rbs(rbs_type, type_parameters: nil, method_definition_parameters: nil)
+            type_parameters ||= []
+
+            case rbs_type
+
+            when RBS::MethodType, RBS::Types::Function, RBS::Types::Proc                
+                conv = ->(klass, name, rbs, opt) do
+                    klass.new(name, types_from_rbs(rbs.type, type_parameters: type_parameters), optional: opt)
+                end
+
+                # `MethodType` has a `Function` instance in its #type field
+                # It also has a block and type parameters, whereas `Function` does not
+                if rbs_type.is_a?(RBS::MethodType) || rbs_type.is_a?(RBS::Types::Proc)
+                    # Get block parameter
+                    block_parameter = rbs_type.block&.then { |bp| conv.(BlockParameter, nil, bp, !bp.required) }
+
+                    # Get method type parameters
+                    method_type_parameters = rbs_type.type_params.map(&:name).map(&:to_s)
+
+                    # Replace `rbs_type` used throughout this method with the inner `Function`
+                    rbs_type = rbs_type.type
+                else
+                    block_parameter = nil
+                end
+                
+                # Build up lists of positional and keyword parameters
+                positional_parameters =
+                    rbs_type.required_positionals.map { |rp| conv.(PositionalParameter, rp.name, rp, false) } \
+                    + rbs_type.optional_positionals.map { |op| conv.(PositionalParameter, op.name, op, true) }
+
+                keyword_parameters =
+                    rbs_type.required_keywords.map { |n, rk| conv.(KeywordParameter, n, rk, false) } \
+                    + rbs_type.optional_keywords.map { |n, ok| conv.(KeywordParameter, n, ok, true) }
+
+                # Get rest parameters
+                rest_positional_parameter = rbs_type.rest_positionals&.then { |rsp| conv.(PositionalParameter, rsp.name, rsp, false) }
+                rest_keyword_parameter = rbs_type.rest_keywords&.then { |rsk| conv.(KeywordParameter, rsk.name, rsk, false) }
+
+                # Get return type
+                return_type = types_from_rbs(rbs_type.return_type, type_parameters: type_parameters)
+
+                # TODO: If method definition parameter list given, check that the counts and names
+                # line up (or fill in the names if the definition doesn't have them)
+
+                MethodType.new(
+                    positional: positional_parameters,
+                    keyword: keyword_parameters,
+                    rest_positional: rest_positional_parameter,
+                    rest_keyword: rest_keyword_parameter,
+                    block: block_parameter,
+                    return_type: return_type,
+                    type_parameters: method_type_parameters,
+                )
+
+            when RBS::Types::ClassInstance
+                # rbs_type.name is not a String, it's a RBS::TypeName which also has a #namespace
+                # property
+                # Just converting to a String with #to_s simplifies things, since it includes the
+                # namespace for us
+                if type_parameters.include?(rbs_type.name.to_s)
+                    TypeParameterPlaceholder.new(rbs_type.name.to_s)
+                else
+                    TypeInstance.new(
+                        PendingDefinedType.new(rbs_type.name.to_s),
+                        type_arguments: rbs_type.args.map { |t| types_from_rbs(t, type_parameters: type_parameters) }
+                    )
+                end
+
+            when RBS::Types::Variable
+                TypeParameterPlaceholder.new(rbs_type.name.to_s)
+
+            when RBS::Types::Bases::Void
+                VoidType.new
+
+            when RBS::Types::Bases::Self
+                SelfType.new
+
+            when RBS::Types::Bases::Instance
+                InstanceType.new
+
+            when RBS::Types::Bases::Any # written as `untyped`
+                UntypedType.new
+
+            else
+                # TODO: handle errors like this better
+                raise "RBS type construct #{rbs_type.class} is not supported (usage: #{rbs_type.location.source})"
+            end
+        end
+
+        # Given a list of types as strings, conventionally a list of type arguments (but it doesn't
+        # actually matter), parses them into types and returns the new array. The original array is
+        # not modified. If any of the items in the array are not strings, they are left unchanged in
+        # the new array.
+        # @param [<String, Type>] type_args
+        # @return [<Type>]
+        def self.parse_type_arguments(env, type_args, type_parameters)
+            type_args.map do |arg|
+                if arg.is_a?(String)
+                    # TODO: as specified in comment at instruction-generation-time, not ideal
+                    # We don't know about other type arguments, nor the correct context
+                    t = parse_type(arg, type_parameters: type_parameters)
+                    t.resolve_all_pending_types(env, context: nil)
+
+                    if t.is_a?(TypeInstance)
+                        t
+                    else
+                        t.instantiate
+                    end
+                else
+                    arg
+                end
+            end
+        end
+    end
+end

data/lib/houndstooth/environment/types/basic/type.rb

@@ -0,0 +1,85 @@
+class Houndstooth::Environment
+    class Type
+        # Looks for methods on an instance of this type.
+        # For example, you would resolve :+ on Integer, and :new on <Class:Integer>.
+        #
+        # @param [Symbol] method_name
+        # @return [Method, nil]
+        def resolve_instance_method(method_name, env, **_)
+            nil
+        end
+
+        # Resolves the type of an instance variable by checking this type and its superclasses.
+        # Returns nil if no type could be resolved.
+        # @param [String] name
+        # @return [Type, nil]
+        def resolve_instance_variable(name)
+            nil
+        end
+
+        def resolve_all_pending_types(environment, context: nil); end
+
+        # If the given type is an instance of `PendingDefinedType`, uses the given environment to
+        # resolve the type. If the type couldn't be resolved, throws an exception.
+        #
+        # @param [Type] type
+        # @param [Environment] environment
+        # @return [DefinedType]
+        def resolve_type_if_pending(type, context, environment)
+            if type.is_a?(PendingDefinedType)
+                new_type = environment.resolve_type(type.path, type_context: context)
+                raise "could not resolve type '#{type.path}'" if new_type.nil? # TODO better error
+                new_type
+            else
+                # Do not recurse into DefinedTypes, this could cause infinite loops if classes are
+                # superclasses of each other
+                if !type.is_a?(DefinedType)
+                    type&.resolve_all_pending_types(environment, context: context)
+                end
+                type
+            end
+        end
+
+        # Determine whether the type `other` can be passed into a "slot" (e.g. function parameter)
+        # which takes this type.
+        #
+        # The return value is either:
+        #   - A positive (or zero) integer, indicating the "distance" between the two types. Zero
+        #     indicates an exact type match (e.g. Integer and Integer), while every increment 
+        #     indicates a level of cast (e.g. Integer -> Numeric = 1, Integer -> Object = 2).
+        #     This can be used to select an overload which is closest to the given set of arguments
+        #     if multiple overloads match.
+        #   - False, if the types do not match.
+        def accepts?(other)
+            raise "unimplemented for #{self.class.name}"
+        end
+
+        # Returns a copy of this type with any type parameters substituted for their actual values
+        # based on the given instance, and if provided, the call-specific type arguments.
+        #
+        # The instance is required, but the call-specific type arguments are not, and should be
+        # passed as `nil` for everything except methods.
+        #
+        # Because this has no link back the method type on which arguments are being substituted,
+        # the caller must construct a hash of call-specific type arguments which includes their
+        # name.
+        #
+        # The returned type could be a partial clone, deep clone, or even not a copy at all (just
+        # `self`) - the implementor makes no guarantees. As such, do NOT modify the returned type.
+        #
+        # @param [TypeInstance] instance
+        # @param [{String => Type}] call_type_args
+        # @return [Type]
+        def substitute_type_parameters(instance, call_type_args) = self
+
+        # Returns an RBS representation of this type. Subclasses should override this.
+        # This will not have the same formatting as the input string this is parsed from.
+        def rbs
+            "???"
+        end 
+
+        def instantiate(type_arguments = nil)
+            TypeInstance.new(self, type_arguments: type_arguments || [])
+        end
+    end
+end

data/lib/houndstooth/environment/types/basic/type_instance.rb

@@ -0,0 +1,54 @@
+class Houndstooth::Environment
+    # Represents type arguments passed with a usage of a type. This doesn't necessarily need to be
+    # an "instance" of a class - "instance" refers to a usage of a type.
+    class TypeInstance < Type
+        def initialize(type, type_arguments: nil)
+            @type = type
+            @type_arguments = type_arguments || []
+        end
+
+        # @return [DefinedType]
+        attr_accessor :type
+
+        # @return [<Type>]
+        attr_accessor :type_arguments
+
+        def ==(other)
+            other.is_a?(TypeInstance) \
+                && type == other.type \
+                && type_arguments == other.type_arguments
+        end
+
+        def hash = [type, type_arguments].hash
+
+        def accepts?(other)
+            return false unless other.is_a?(TypeInstance)
+
+            type.accepts?(other.type)
+        end
+
+        def resolve_instance_method(method_name, env, top_level: true)
+            type.resolve_instance_method(method_name, env, instance: self, top_level: top_level)
+        end
+
+        def resolve_all_pending_types(environment, context: nil)
+            @type = resolve_type_if_pending(type, context, environment)
+            type_arguments.map! { |type| resolve_type_if_pending(type, context, environment) }
+        end
+
+        def substitute_type_parameters(instance, call_type_args)
+            clone.tap do |t|
+                t.type = t.type.substitute_type_parameters(instance, call_type_args)
+                t.type_arguments = t.type_arguments.map { |arg| arg.substitute_type_parameters(instance, call_type_args) }
+            end
+        end
+
+        def rbs
+            if type_arguments.any?
+                "#{type.rbs}[#{type_arguments.map(&:rbs).join(', ')}]"
+            else
+                type.rbs
+            end 
+        end
+    end
+end

data/lib/houndstooth/environment/types/compound/union_type.rb

@@ -0,0 +1,72 @@
+class Houndstooth::Environment
+    class UnionType < Type
+        # The types which this union is made up of.
+        # @return [<Type>]
+        attr_accessor :types
+
+        def initialize(types)
+            @types = types
+        end
+
+        # Simplifies this union using a couple of different strategies:
+        #   - If any of the child types is also a `UnionType`, flattens it into one longer union.
+        #   - If some children are the same, combines them.
+        #   - If there is only one child, returns the child.
+        # Returns a new type with the same references, since the latter step could return something
+        # other than `UnionType`.
+        def simplify
+            new_types = types.flat_map do |type|
+                if type.is_a?(UnionType)
+                    type.types
+                else
+                    [type]
+                end
+            end
+
+            new_types.uniq! { |x| x.hash }
+
+            if new_types.length == 1
+                new_types.first
+            else
+                UnionType.new(new_types)
+            end
+        end
+
+        def resolve_instance_method(method_name, env, **_)
+            env.resolve_type('::BasicObject').resolve_instance_method(method_name, env)
+        end
+
+        def resolve_all_pending_types(environment, context: nil)
+            types.map! { |type| resolve_type_if_pending(type, self, environment) }
+        end
+
+        def substitute_type_parameters(instance, call_type_args)
+            clone.tap do |t|
+                t.types = t.types.map { |type| type.substitute_type_parameters(instance, call_type_args) }
+            end
+        end
+
+        def accepts?(other)
+            # Normalise into an array
+            if other.is_a?(UnionType)
+                other_types = other.types
+            else
+                other_types = [other]
+            end
+
+            # Each of the other types should fit into one of this type's options
+            # Find minimum distances from each candidate and sum them, plus one since this union is
+            # itself a "hop"
+            other_types.map do |ot|
+                candidates = types.map { |mt| mt.accepts?(ot) }.reject { |r| r == false }
+                return false if candidates.empty?
+
+                candidates.min
+            end.sum + 1
+        end
+
+        def rbs
+            types.map(&:rbs).join(" | ")
+        end 
+    end
+end

data/lib/houndstooth/environment/types/defined/base_defined_type.rb

@@ -0,0 +1,23 @@
+class Houndstooth::Environment
+    # A slightly hacky type which represents the base namespace, such as when a constant is accessed
+    # using ::A syntax. 
+    # This only appears in one place; the type change of a `ConstantBaseAccessInstruction`. This is
+    # invalid if it appears in any context where an actual type is expected.
+    # Unlike other constant accesses, this does NOT represent an *instance* of the base namespace,
+    # because that cannot exist.
+    class BaseDefinedType < Type
+        def accepts?(other)
+            false
+        end
+
+        def name
+            ""
+        end
+        alias path name
+        alias uneigen name
+
+        def rbs
+            "(base)"
+        end 
+    end
+end