houndstooth 0.1.0

data/lib/houndstooth/semantic_node/parameters.rb

@@ -0,0 +1,108 @@
+module Houndstooth::SemanticNode
+    # A set of parameters accepted by a method definition or block.
+    class Parameters < Base
+        register_ast_converter :args do |ast_node|
+            parameters = Parameters.new(
+                ast_node: ast_node,
+                positional_parameters: [],
+                optional_parameters: [],
+                keyword_parameters: [],
+                optional_keyword_parameters: [],
+                rest_parameter: nil,
+                rest_keyword_parameter: nil,
+                block_parameter: nil,
+                only_proc_parameter: false,
+                has_forward_parameter: false,
+            )
+
+            ast_node.to_a.each do |arg|
+                case arg.type
+                when :arg
+                    parameters.positional_parameters << arg.to_a.first
+                when :kwarg
+                    parameters.keyword_parameters << arg.to_a.first
+                when :optarg
+                    name, value = *arg
+                    parameters.optional_parameters << [name, from_ast(value)]
+                when :kwoptarg
+                    name, value = *arg
+                    parameters.optional_keyword_parameters << [name, from_ast(value)]
+                when :restarg
+                    parameters.rest_parameter = arg.to_a.first
+                when :kwrestarg
+                    parameters.rest_keyword_parameter = arg.to_a.first 
+                when :procarg0
+                    parameters.only_proc_parameter = true
+                when :blockarg
+                    parameters.block_parameter = arg.to_a.first
+                when :forward_arg
+                    parameters.has_forward_parameter = true
+                else
+                    Houndstooth::Errors::Error.new(
+                        "Unsupported argument type",
+                        [[arg.loc.expression, "unsupported"]]
+                    ).push
+                    next nil
+                end
+            end
+
+            parameters
+        end
+
+        # True if this block of parameters takes the magic "progarc0", which in blocks can represent
+        # all parameters given in an array.
+        # @return [Boolean]
+        attr_accessor :only_proc_parameter
+
+        # @return [<Symbol>]
+        attr_accessor :positional_parameters
+        
+        # @return [<(Symbol, SemanticNode)>]
+        attr_accessor :optional_parameters
+        
+        # @return [<Symbol>]
+        attr_accessor :keyword_parameters
+        
+        # @return [<(Symbol, SemanticNode)>]
+        attr_accessor :optional_keyword_parameters
+
+        # @return [Symbol, nil]
+        attr_accessor :rest_parameter
+
+        # @return [Symbol, nil]
+        attr_accessor :rest_keyword_parameter
+
+        # @return [Symbol, nil]
+        attr_accessor :block_parameter
+
+        # True if this method has a `...` parameter.
+        # @return [Boolean]
+        attr_accessor :has_forward_parameter
+
+        def add_to_instruction_block(block)
+            if optional_parameters.any? ||
+                keyword_parameters.any? ||
+                optional_keyword_parameters.any? ||
+                rest_parameter ||
+                rest_keyword_parameter ||
+                has_forward_parameter ||
+                block_parameter ||
+                only_proc_parameter
+
+                # Replace call with a nil
+                Houndstooth::Errors::Error.new(
+                    "Only required positional parameters are supported",
+                    [[ast_node.loc.expression, "unsupported parameters in block"]]
+                ).push 
+                return false
+            end
+
+            # Create parameters on this block
+            positional_parameters.each do |name|
+                block.parameters << I::Variable.new(name.to_s)
+            end
+
+            return true
+        end
+    end
+end

data/lib/houndstooth/semantic_node/send.rb

@@ -0,0 +1,349 @@
+module Houndstooth::SemanticNode
+    # A method call, called a 'send' internally by Ruby and its parser, hence its name here.
+    class Send < Base
+        # @return [SemanticNode, nil]
+        attr_accessor :target
+        
+        # @return [Symbol]
+        attr_accessor :method
+
+        # @return [<SemanticNode>]
+        attr_accessor :arguments
+
+        # @return [Boolean]
+        attr_accessor :safe_navigation
+
+        # If true, this isn't really a send, but instead a super call. The `target` and `method` 
+        # of this instance should be ignored.
+        # @return [Boolean]
+        attr_accessor :super_call
+
+        # @return [Block, nil]
+        attr_accessor :block
+
+        register_ast_converter :send do |ast_node, multiple_assignment_lhs: false|
+            target, method, *arguments_nodes = *ast_node
+            
+            # Let the target shift comments first!
+            # This is because you can break onto newlines on the dots if you need to apply a comment
+            # to another node.
+            #
+            # Say you need to apply a magic comment to all of the three sends in a chain:
+            #
+            #    a.b.c
+            #
+            # Appying to the first send in the chain (the "deepest target") allows you to do this:
+            #
+            #    # Comment A
+            #    a
+            #      # Comment B
+            #      .b
+            #      # Comment C
+            #      .c
+            #
+            # Rather than what you've have to do if they apply to the end of the chain:
+            #
+            #    # Comment A
+            #    _a = a
+            #    # Comment B
+            #    _b = a.b
+            #    # Comment C
+            #    _c = b.c
+            #
+            target = from_ast(target) if target
+            comments = shift_comments(ast_node)
+
+            if multiple_assignment_lhs
+                next Send.new(
+                    ast_node: ast_node,
+                    comments: comments,
+
+                    target: target,
+                    method: method,
+                    arguments: [PositionalArgument.new(MagicPlaceholder.new)],
+                    safe_navigation: false,
+                )
+            end 
+
+            if arguments_nodes.last&.type == :kwargs
+                arguments = arguments_nodes[0...-1].map { PositionalArgument.new(from_ast(_1)) }
+                arguments.concat(arguments_nodes.last.to_a.map do |kwarg|
+                    next [:_, nil] if kwarg.type == :kwsplat
+
+                    unless kwarg.type == :pair
+                        Houndstooth::Errors::Error.new(
+                            "Expected keyword argument list to contain only pairs",
+                            [[kwarg.loc.expression, "did not parse as a pair"]]
+                        ).push
+                        next nil
+                    end
+
+                    name, value = *kwarg.to_a.map { from_ast(_1) }
+                    KeywordArgument.new(value, name: name)
+                end)
+            else
+                arguments = arguments_nodes.map { PositionalArgument.new(from_ast(_1)) }
+            end
+
+            Send.new(
+                ast_node: ast_node,
+                comments: comments,
+
+                target: target,
+                method: method,
+                arguments: arguments,
+                safe_navigation: false,
+            )
+        end
+
+        register_ast_converter :csend do |ast_node, multiple_assignment_lhs: false|
+            # Convert this csend into a send
+            equivalent_send_node = Parser::AST::Node.new(:send, ast_node, location: ast_node.location)
+
+            # Convert that into a semantic node and set the safe flag
+            send = from_ast(equivalent_send_node, multiple_assignment_lhs: multiple_assignment_lhs)
+            send.safe_navigation = true
+
+            send
+        end
+
+        register_ast_converter :block do |ast_node|
+            send_ast_node, args_ast_node, block_body = *ast_node
+
+            # Parse the `send`, we'll set block properties afterwards
+            send = from_ast(send_ast_node)
+            send.ast_node = ast_node
+
+            send.block = Block.new(
+                ast_node: ast_node,
+                parameters: from_ast(args_ast_node),
+                body: block_body.nil? ? Body.new(ast_node: ast_node) : from_ast(block_body)
+            )
+
+            send
+        end
+
+        # Numblocks are just converted into regular blocks with the same parameter names, e.g.:
+        #
+        #   array.map { _1 + 1 }
+        #
+        # Becomes:
+        #
+        #   array.map { |_1| _1 + 1 }
+        #
+        register_ast_converter :numblock do |ast_node|
+            send_ast_node, args_count, block_body = *ast_node
+
+            # Parse the `send`, we'll set block properties afterwards
+            send = from_ast(send_ast_node)
+            send.ast_node = ast_node
+
+            # Build a fake set of parameters for the block
+            # We need to respect the "procarg0" semantics by checking if there's only 1 parameter
+            if args_count == 1
+                parameters = Parameters.new(
+                    ast_node: block_body,
+                    positional_parameters: [],
+                    optional_parameters: [],
+                    keyword_parameters: [],
+                    optional_keyword_parameters: [],
+                    rest_parameter: nil,
+                    rest_keyword_parameter: nil,
+                    only_proc_parameter: true,
+                )
+            else
+                parameters = Parameters.new(
+                    ast_node: block_body,
+                    positional_parameters: args_count.times.map { |i| :"_#{i + 1}" },
+                    optional_parameters: [],
+                    keyword_parameters: [],
+                    optional_keyword_parameters: [],
+                    rest_parameter: nil,
+                    rest_keyword_parameter: nil,
+                    only_proc_parameter: false,
+                )
+            end
+
+            send.block = Block.new(
+                ast_node: ast_node,
+                parameters: parameters,
+                body: from_ast(block_body)
+            )
+
+            send
+        end
+
+        # Supers are virtually identical to method calls in terms of the arguments they can take.
+        register_ast_converter :super do |ast_node|
+            # Convert this super into a fake send node
+            equivalent_send_node = Parser::AST::Node.new(
+                :send,
+                [
+                    # Target
+                    nil,
+
+                    # Method
+                    :super__NOT_A_REAL_METHOD,
+
+                    # Arguments
+                    *ast_node
+                ],
+                location: ast_node.location
+            )
+
+            # Convert that into a semantic node and set the super flag
+            send = from_ast(equivalent_send_node)
+            send.super_call = true
+
+            send
+        end 
+
+        def to_instructions(block)
+            # Generate instructions for the method's target
+            # If it doesn't have one, then it's implicitly `self`
+            if target
+                target.to_instructions(block)
+            else
+                block.instructions << I::SelfInstruction.new(block: block, node: self)
+            end
+            target_variable = block.instructions.last.result
+            
+            type_arguments = get_type_arguments
+
+            # If this call uses save navigation, we want to wrap everything else in a conditional
+            # which checks the target isn't nil
+            # (If safe navigation bails from a call because the target is nil, the arguments don't
+            #  get evaluated either)
+            if safe_navigation
+                # Generates:
+                #   $1 = ...target...
+                #   if $2.nil?
+                #     nil
+                #   else
+                #     $1.method
+                #   end
+                block.instructions << I::SendInstruction.new(
+                    block: block,
+                    node: self,
+                    target: target_variable,
+                    method_name: :nil?,
+                )
+
+                true_blk = I::InstructionBlock.new(has_scope: false, parent: block)
+                true_blk.instructions << I::LiteralInstruction.new(block: true_blk, node: self, value: nil)
+                block.instructions << I::ConditionalInstruction.new(
+                    block: block,
+                    node: self,
+                    condition: block.instructions.last.result,
+                    true_branch: true_blk,
+                    false_branch: I::InstructionBlock.new(has_scope: false, parent: block),
+                )
+
+                # Replace the working instruction block with the false branch, so we insert the
+                # actual send in there
+                block = block.instructions.last.false_branch
+            end
+
+            # Evaluate arguments
+            ins_args = arguments.map do |arg|
+                case arg
+                when PositionalArgument
+                    arg.node.to_instructions(block)
+                    I::PositionalArgument.new(block.instructions.last.result)
+                when KeywordArgument
+                    if arg.name.is_a?(SymbolLiteral) && arg.name.components.length == 1 && arg.name.components.first.is_a?(String)
+                        arg.node.to_instructions(block)
+                        I::KeywordArgument.new(
+                            block.instructions.last.result,
+                            name: arg.name.components.first,
+                        )
+                    else
+                        Houndstooth::Errors::Error.new(
+                            "Keyword argument keys must be non-interpolated symbol literals",
+                            [[arg.name.ast_node.loc.expression, "invalid key"]]
+                        ).push
+    
+                        block.instructions << I::LiteralInstruction.new(block: block, node: arg.name, value: nil)
+                        I::KeywordArgument.new(
+                            block.instructions.last.result,
+                            name: "__non_symbol_key_error_#{(rand * 10000).to_i}",
+                        )
+                    end
+                else
+                    raise "unknown node argument type: #{arg}"
+                end
+            end
+            
+            # Insert send instruction
+            si = I::SendInstruction.new(
+                block: block,
+                node: self,
+                target: target_variable,
+                method_name: method,
+                arguments: ins_args,
+                super_call: super_call,
+                type_arguments: type_arguments,
+            )
+
+            # Build up method block
+            if self.block
+                si.method_block =
+                    I::InstructionBlock.new(has_scope: true, parent: si).tap do |blk|
+                        if !self.block.parameters.add_to_instruction_block(blk)
+                            block.instructions << I::LiteralInstruction.new(node: self, block: block, value: nil)
+                            return
+                        end
+
+                        # Create body
+                        self.block.body.to_instructions(blk)
+                    end
+            end
+
+            block.instructions << si
+        end
+    end
+
+    # A block passed to a `Send`.
+    class Block < Base
+        # @return [Parameters]
+        attr_accessor :parameters
+
+        # @return [SemanticNode]
+        attr_accessor :body
+    end
+
+    # An argument to a `Send`.
+    # @abstract
+    class Argument
+        # The node for the argument's value.
+        # @return [SemanticNode]
+        attr_accessor :node
+
+        def initialize(node)
+            @node = node
+        end
+    end
+
+    # A standard, singular, positional argument.
+    class PositionalArgument < Argument; end
+
+    # A singular keyword argument.
+    class KeywordArgument < Argument
+        # The keyword.
+        # @return [SemanticNode]
+        attr_accessor :name
+
+        def initialize(node, name:)
+            super(node)
+            @name = name
+        end
+    end 
+
+    # A special argument which may appear in the arguments to a `Send`, when arguments have been
+    # forwarded from the enclosing method into it.
+    class ForwardedArguments < Base
+        register_ast_converter :forwarded_args do |ast_node|
+            ForwardedArguments.new(ast_node: ast_node)
+        end
+    end
+end

data/lib/houndstooth/semantic_node/super.rb

@@ -0,0 +1,12 @@
+module Houndstooth::SemanticNode
+    # An implicit super call, without parentheses. This will forward arguments to the superclass'
+    # method automatically.
+    class ImplicitSuper < Base
+        register_ast_converter :zsuper do |ast_node|
+            self.new(ast_node: ast_node)
+        end
+    end
+
+    # ...Where's `ExplicitSuper`?
+    # We use `Send` for that, since the parameters are largely the same!
+end

data/lib/houndstooth/semantic_node.rb

@@ -0,0 +1,119 @@
+require 'parser/ruby30'
+
+# Accuracy to Ruby 3
+LEGACY_MODES = %i[lambda procarg0 encoding arg_inside_procarg0 forward_arg kwargs match_pattern]
+LEGACY_MODES.each do |mode|
+    Parser::Builders::Default.send :"emit_#{mode}=", true
+end
+Parser::Builders::Default.emit_index = false
+Parser::Builders::Default.emit_lambda = false
+
+# Useful resource: https://docs.rs/lib-ruby-parser/3.0.12/lib_ruby_parser/index.html
+# Based on whitequark/parser so gives good idea of what node types to expect
+
+module Houndstooth::SemanticNode
+    # Shorthand for use by #to_instructions implementations
+    I = Houndstooth::Instructions
+
+    class Base
+        # @return [Parser::AST::Node]
+        attr_accessor :ast_node
+
+        # @return [<Parser::Source::Comment>]
+        attr_accessor :comments
+
+        def initialize(ast_node:, **kwargs)
+            @comments = []
+            @ast_node = ast_node
+
+            kwargs.each do |k, v|
+                send :"#{k}=", v
+            end
+        end
+
+        def self.from_ast(ast_node, **options)
+            converter = @@ast_converters[ast_node.type]
+
+            if converter.nil?
+                Houndstooth::Errors::Error.new(
+                    "Unsupported AST node type #{ast_node.type}",
+                    [[ast_node.loc.expression, "unsupported"]]
+                ).push
+                return
+            end
+
+            converter.(ast_node, **options)
+        end
+
+        def self.register_ast_converter(*types, &block)
+            @@ast_converters ||= {}
+            types.each do |type|
+                @@ast_converters[type] = block
+            end
+        end
+
+        # TODO: shouldn't use a global!!
+        def self.shift_comments(ast_node)
+            # TODO: don't pick *any* comment before this one, only ones on their own line
+            # In this case:
+            #   x = 2 # foo
+            #   y
+            # We shouldn't match  the `# foo` comment to the `y` Send
+
+            if ast_node.type == :send && ast_node.location.respond_to?(:selector) && ast_node.location.selector
+                # Use name of the method as position reference, if available
+                reference_location = ast_node.location.selector
+            else
+                # Not sure what this is, just use the very start of the expression
+                reference_location = ast_node.location.expression
+            end
+
+            comments = []
+            comments << $comments.shift \
+                while $comments.first && $comments.first.location.expression < reference_location
+            comments
+        end
+
+        # Converts this semantic node into a sequence of equivalent instructions, and adds them to
+        # the given instruction block.
+        # It is expected that, after this call returns, the variable assigned by the final
+        # instruction in the block has an equivalent result to evaluating this expression. 
+        # @param [InstructionBlock] block
+        def to_instructions(block)
+            raise "#to_instructions not implemented for #{self.class.name}"
+        end
+
+        protected
+
+        # Extracts type arguments from comments as strings.
+        def get_type_arguments
+            comments
+                .select { |c| c.text.start_with?('#!arg ') }
+                .map do |c|
+                    unless /^#!arg\s+(.+)\s*$/ === c.text
+                        Houndstooth::Errors::Error.new(
+                            "Malformed #!arg definition",
+                            [[c.loc.expression, "invalid"]]
+                        ).push
+                        return 
+                    end
+
+                    $1
+                end
+        end
+    end
+
+    def self.from_ast(...)
+        Base.from_ast(...)
+    end
+end
+
+require_relative 'semantic_node/parameters'
+require_relative 'semantic_node/control_flow'
+require_relative 'semantic_node/operators'
+require_relative 'semantic_node/identifiers'
+require_relative 'semantic_node/keywords'
+require_relative 'semantic_node/literals'
+require_relative 'semantic_node/send'
+require_relative 'semantic_node/definitions'
+require_relative 'semantic_node/super'

data/lib/houndstooth/stdlib.rb

@@ -0,0 +1,6 @@
+module Houndstooth::Stdlib
+    def self.add_types(environment)
+        Houndstooth.process_file('stdlib.htt', File.read(File.join(__dir__, '..', '..', 'types', 'stdlib.htt')), environment)
+        environment.resolve_all_pending_types
+    end
+end