docrb-parser 0.1.0

data/lib/docrb/parser/container.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class Container
+      visible_attr_accessor :classes, :modules, :defined_by, :instance_methods,
+        :class_methods, :extends, :includes, :name, :path_segments,
+        :instance_attributes, :class_attributes, :current_visibility_modifier,
+        :constants, :location
+      attr_accessor :parent, :parser, :doc
+
+      SINGLETON_CLASS_TYPES = %i[
+        singleton_class_node
+        deferred_singleton_class_node
+      ].freeze
+
+      def initialize(parser, parent, node)
+        @object_id = parser.make_id(self)
+        @node = node
+        @parser = parser
+        @explicit_instance_visibility = {}
+        @explicit_class_visibility = {}
+        @constants = NodeArray.new
+        @classes = NodeArray.new
+        @modules = NodeArray.new
+        @includes = NodeArray.new
+        @extends = NodeArray.new
+        @defined_by = []
+        @instance_methods = NodeArray.new
+        @class_methods = NodeArray.new
+        @class_attributes = NodeArray.new
+        @instance_attributes = NodeArray.new
+        @inside_module_function = false
+        @location = parser.location(node.location)
+        @parent = parent
+
+        @name = if SINGLETON_CLASS_TYPES.include? node&.type
+          nil
+        elsif node
+          name = parser.unfurl_constant_path(node.constant_path)
+          @path_segments = name
+          name.pop
+        end
+
+        node&.body&.body&.each { handle_node(_1) }
+      end
+
+      def full_path(relative_to: nil)
+        path = [self] + (parent&.full_path || [])
+        return path unless relative_to
+
+        rel_path = relative_to.full_path
+        while rel_path.last == path.last
+          rel_path.pop
+          path.pop
+        end
+
+        path
+      end
+
+      def extract_references(from, attr)
+        NodeArray.new(from
+          .filter(&:fulfilled?)
+          .map { _1.resolved.id }
+          .map { parser.object_by_id(_1) }
+          .map { _1.send(attr) }
+          .flatten)
+      end
+
+      def unowned_classes = extract_references(@includes, :all_classes)
+
+      def all_classes = NodeArray.new(@classes).tap { _1.merge_unowned(*unowned_classes) }
+
+      def unowned_modules = extract_references(@includes, :all_modules)
+
+      def all_modules = NodeArray.new(@modules).tap { _1.merge_unowned(*unowned_modules) }
+
+      def unowned_instance_methods = extract_references(@includes, :all_instance_methods)
+
+      def all_instance_methods = NodeArray.new(@instance_methods).tap { _1.merge_unowned(*unowned_instance_methods) }
+
+      def unowned_class_methods = extract_references(@extends, :all_instance_methods)
+
+      def all_class_methods = NodeArray.new(@class_methods).tap { _1.merge_unowned(*unowned_class_methods) }
+
+      def unowned_class_attributes = extract_references(@extends, :all_instance_attributes)
+
+      def all_class_attributes = NodeArray.new(@class_attributes).tap { _1.merge_unowned(*unowned_class_attributes) }
+
+      def unowned_instance_attributes = extract_references(@includes, :all_instance_attributes)
+
+      def all_instance_attributes
+        NodeArray.new(@instance_attributes)
+          .tap { _1.merge_unowned(*unowned_instance_attributes) }
+      end
+
+      def all_objects
+        NodeArray.new(
+          all_classes + all_modules + all_instance_methods + all_classes +
+            all_class_attributes + all_instance_attributes
+        )
+      end
+
+      def id = @object_id
+
+      def source_of(obj)
+        parent = obj.parent.id
+        case
+        when parent == id
+          :self
+        when @includes.filter(&:fulfilled?).any? { _1.resolved.id == id }
+          :included
+        when @extends.filter(&:fulfilled?).any? { _1.resolved.id == id }
+          :extended
+        else
+          :unknown
+        end
+      end
+
+      def handle_parsed_node(_parser, _node) = nil
+
+      def instance_method_added(_parser, _node, _method) = nil
+
+      def class_method_added(_parser, _node, _method) = nil
+
+      def class_added(_parser, _node, _method) = nil
+
+      def module_added(_parser, _node, _method) = nil
+
+      def handle_call(call)
+        case call.name
+        when :extend
+          extends.append(*call.arguments.map { reference(_1) })
+          true
+        when :include
+          includes.append(*call.arguments.map { reference(_1) })
+          true
+        when :attr, :attr_reader
+          add_attribute(parser, call, :reader)
+          true
+        when :attr_accessor
+          add_attribute(parser, call, :accessor)
+          true
+        when :attr_writer
+          add_attribute(parser, call, :writer)
+          true
+        when :private, :public, :protected
+          handle_visibility_modifier(parser, call)
+          true
+        when :private_class_method, :public_class_method
+          handle_singleton_visibility_modifier(parser, call)
+          true
+        else
+          false
+        end
+      end
+
+      def handle_node(node)
+        case v = parse_node(node)
+        when nil
+          # Pass
+        when Method
+          if v.instance?
+            @instance_methods << v
+            instance_method_added(parser, node, v)
+          else
+            @class_methods << v
+            class_method_added(parser, node, v)
+          end
+        when Class
+          if v.singleton? && kind == :class
+            merge_singleton_class(v)
+          else
+            @classes << v
+            class_added(parser, node, v)
+          end
+        when Module
+          @modules << v
+          module_added(parser, node, v)
+        when Call
+          handle_parsed_node(parser, v) unless handle_call(v)
+        when Constant
+          @constants << v
+        else
+          handle_parsed_node(parser, v)
+        end
+      end
+
+      def parse_node(node) = parser.handle_node(node, self)
+
+      def reference(path) = parser.reference(self, path)
+
+      def add_attribute(parser, node, type)
+        node.arguments.each do |arg|
+          next unless arg.try(:type) == :symbol_node # TODO: Support extra types?
+
+          @instance_attributes << Attribute.new(parser, self, node, arg.value.to_sym, type)
+        end
+      end
+
+      def adjust_split_attributes!(scope)
+        attrs = instance_variable_get("@#{scope}_attributes")
+        methods = instance_variable_get("@#{scope}_methods")
+        exp = instance_variable_get("@explicit_#{scope}_visibility")
+
+        loop do
+          changed = false
+          attrs.each do |attr|
+            setter = "#{attr.name}=".to_sym
+
+            # Do we have a writer defined explicitly?
+            if (method = methods.named(setter).first)
+              changed = true
+              methods.delete(method)
+              attr.writer_visibility = exp.fetch(setter, method.visibility)
+
+              # Promote attribute to accessor in case it was only a reader.
+              attr.type = :accessor if attr.type == :reader
+            end
+
+            next unless (method = methods.named(attr.name).first)
+
+            changed = true
+            methods.delete(method)
+            attr.reader_visibility = exp.fetch(setter, method.visibility)
+
+            # Promote attribute to accessor in case it was only a writer.
+            attr.type = :accessor if attr.type == :writer
+          end
+
+          # Finally, move all methods ending in `=` that are left to write-only
+          # attributes, and re-run this loop if required.
+          methods.each do |met|
+            name = met.name.to_s
+            next unless name.end_with? "="
+
+            changed = true
+            attr_name = name.gsub("=", "").to_sym
+            attrs << Attribute.new(@parser, self, met.node, attr_name, :writer).tap do |attr|
+              attr.writer_visibility = met.visibility
+            end
+            methods.delete(met)
+          end
+
+          break unless changed
+        end
+      end
+
+      def handle_visibility_modifier(_parser, node)
+        @inside_module_function = false
+        old_visibility = @current_visibility_modifier
+        @current_visibility_modifier = node.name
+        node.arguments&.each do |arg|
+          case arg.type
+          when :symbol_node
+            @explicit_instance_visibility[arg.value.to_sym] = @current_visibility_modifier
+            if (method = @instance_methods.named(arg.value.to_sym).first)
+              method.visibility = @current_visibility_modifier
+              next
+            end
+
+            if (attr = @instance_attributes.named(arg.value.gsub("=", "").to_sym).first)
+              if arg.value.end_with? "="
+                attr.writer_visibility = @current_visibility_modifier
+              else
+                attr.reader_visibility = @current_visibility_modifier
+              end
+            end
+
+          when :def_node, :call_node
+            @explicit_instance_visibility[arg.name.to_sym] = @current_visibility_modifier
+            known_methods = @instance_methods.map(&:name)
+            handle_node(arg)
+            (@instance_methods.map(&:name) - known_methods).each do |n|
+              @explicit_instance_visibility[n] = @current_visibility_modifier
+            end
+          else
+            parser.unhandled_node! node
+          end
+        end
+      ensure
+        @current_visibility_modifier = old_visibility unless node.arguments && node.arguments.empty?
+      end
+
+      def handle_singleton_visibility_modifier(_parser, node)
+        visibility = node.name.to_s.split("_", 2).first.to_sym
+        node.arguments.each do |arg|
+          if arg.value == "new"
+            @default_constructor_visibility = visibility
+            next
+          end
+          @class_methods.named(arg.value.to_sym).first&.visibility = visibility
+        end
+      end
+
+      def update_constructor_visibility!
+        return if @default_constructor_visibility == :public
+
+        # Create a new "new" singleton
+        handle_node(VirtualMethod.new(:new, :self_node))
+        @class_methods.named(:new).first!.visibility = @default_constructor_visibility
+      end
+    end
+  end
+end

data/lib/docrb/parser/deferred_singleton_class.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class DeferredSingletonClass < Class
+      visible_attr_reader :target
+
+      def kind = :deferred_singleton_class
+
+      def initialize(parser, parent, node)
+        super
+        @target = parser.unfurl_constant_path(node.expression)
+        singleton!
+      end
+    end
+  end
+end

data/lib/docrb/parser/location.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class Location
+      visible_attr_reader :line_start, :line_end, :offset_start, :offset_end
+      attr_reader :parser, :file_path, :ast, :source
+
+      def initialize(parser, ast, loc)
+        @parser = parser
+        @ast = ast
+        if loc.try(:virtual?)
+          @virtual = true
+        else
+          @line_start = loc.start_line
+          @line_end = loc.end_line
+          @offset_start = loc.start_offset
+          @offset_end = loc.end_offset
+          @file_path = parser.current_file
+        end
+
+        @source = nil
+      end
+
+      def virtual? = @virtual || false
+
+      def load_source!
+        return if @virtual
+
+        @source = @ast.source.source[@offset_start...@offset_end]
+          .then do |src|
+          lines = src.lines
+          next src unless lines.length > 1
+
+          match = /^(\s+)/.match(lines.last)
+          next src unless match
+
+          src.gsub(/^\s{#{match[1].length}}/, "")
+        end
+      end
+    end
+  end
+end

data/lib/docrb/parser/method.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class Method
+      visible_attr_accessor :name, :parameters, :visibility, :overriding,
+        :overridden_by, :type, :external_receiver, :location
+      attr_accessor :parent, :node, :doc
+
+      def kind = :method
+
+      def initialize(parser, parent, node)
+        @object_id = parser.make_id(self)
+        @parser = parser
+        @parent = parent
+        @node = node
+        @name = node.name
+        @visibility = parent.try(:current_visibility_modifier) || :public
+        @location = parser.location(node.location) unless node.is_a? VirtualMethod
+        @parameters = MethodParameters.new(parser, self, node.parameters)
+        @overridden_by = []
+        case node.receiver&.type
+        when nil
+          @type = :instance
+        when :self_node
+          @type = :class
+        else
+          @type = :class
+          @external_receiver = parser.reference(self, parser.unfurl_constant_path(node.receiver))
+        end
+      end
+
+      def id = @object_id
+
+      def class? = @type == :class
+
+      def instance? = @type == :instance
+
+      def module_function? = @visibility == :module_function
+
+      def external? = !@external_receiver.nil?
+
+      def override_target = (@parser.object_by_id(@overriding) if @overriding)
+      def overriders = @overridden_by.map { @parser.object_by_id(_1) }.map(&:parent).compact
+
+      def full_path(relative_to: nil)
+        path = (parent&.full_path || []).reverse + [self]
+        return path unless relative_to
+
+        full_rel = relative_to.full_path.reverse
+        while full_rel.first == path.first
+          full_rel.shift
+          path.shift
+        end
+
+        path
+      end
+
+      docrb_inspect { "name=#{name}" }
+    end
+  end
+end

data/lib/docrb/parser/method_parameters.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class MethodParameters < Array
+      def initialize(parser, parent, node)
+        @object_id = parser.make_id(self)
+        super()
+        @parent = parent
+        @node = node
+        node&.compact_child_nodes&.sort_by { _1.location.start_offset }&.each do |n|
+          kind = case n
+          when Prism::RequiredParameterNode then :arg
+          when Prism::OptionalParameterNode then :optarg
+          when Prism::RestParameterNode then :rest
+          when Prism::KeywordParameterNode then n.value ? :optkw : :kw
+          when Prism::KeywordRestParameterNode then :kwrest
+          when Prism::BlockParameterNode then :block
+          else raise NotImplementedError, "Unsupported parameter kind #{n.class}"
+          end
+          append Parameter.new(parser, kind, n.name, n.try(:value))
+        end
+      end
+
+      def id = @object_id
+
+      docrb_inspect { to_a }
+
+      class Parameter
+        visible_attr_reader :kind, :name, :value, :value_type
+        attr_reader :parser
+
+        def initialize(parser, kind, name, value = nil)
+          @object_id = parser.make_id(self)
+          @kind = kind
+          @name = name || name_by_type
+          @value_type = type_for_value(value)
+          @value = value.then! { parser.location(_1.location) }
+        end
+
+        def id = @object_id
+
+        def has_value? = !value.nil?
+
+        def optional? = kind == :optarg || kind == :optkw
+
+        def positional? = kind == :optarg || kind == :arg || kind == :rest
+
+        def keyword? = kind == :kw || kind == :optkw || kind == :kwrest
+
+        def block? = kind == :block
+
+        def rest? = kind == :kwrest || kind == :rest
+
+        private
+
+        def name_by_type
+          case kind
+          when :rest then :*
+          when :kwrest then :**
+          when :block then :&
+          else
+            raise "Invalid call to name_by_type for a non-anonymous parameter"
+          end
+        end
+
+        def type_for_value(value)
+          return unless value
+
+          case value
+          when Prism::SymbolNode then :symbol
+          when Prism::NilNode then :nil
+          when Prism::FalseNode, Prism::TrueNode then :bool
+          when Prism::CallNode then :call
+          when Prism::StringNode then :string
+          when Prism::IntegerNode, Prism::FloatNode then :number
+          when Prism::ConstantReadNode, Prism::ConstantPathNode then :const
+          else
+            puts "Unhandled parameter value type #{value.class.name}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docrb/parser/module.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class Module < Container
+      def kind = :module
+
+      def initialize(parser, parent, node)
+        super
+        adjust_split_attributes! :class
+        adjust_split_attributes! :instance
+      end
+
+      def instance_method_added(_parser, _node, method)
+        return unless @inside_module_function
+        return unless method.instance?
+
+        method.type = :module_function
+        @class_methods.append(method)
+        @instance_methods.delete(method)
+      end
+
+      def handle_parsed_node(parser, node)
+        return unless node.is_a? Call
+        return unless node.name == :module_function
+
+        old_module_function = @inside_module_function
+        @inside_module_function = true
+
+        node.arguments&.each do |arg|
+          case arg.type
+          when :symbol_node
+            if (method = @instance_methods.named(arg.value.to_sym).first)
+              method.type = :module_function
+              @class_methods.append(method)
+              @instance_methods.delete(method)
+            end
+
+          when :def_node, :call_node
+            handle_node(arg)
+          else
+            parser.unhandled_node! node
+          end
+        ensure
+          @inside_module_function = old_module_function unless node.arguments && node.arguments.empty?
+        end
+      end
+    end
+  end
+end

data/lib/docrb/parser/node_array.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class NodeArray < Array
+      def by_kind(*kind) = filter { _1.respond_to?(:kind) && kind.include?(_1.kind) }
+
+      def named(name)
+        name = name.to_s
+        NodeArray.new(filter { _1.respond_to?(:name) && _1.name.to_s == name })
+      end
+
+      def named!(name) = named(name).first!
+
+      def typed(*classes) = filter { |node| classes.any? { node.is_a? _1 } }
+
+      def merge_unowned(*other)
+        other
+          .reject { |v| find { _1.name == v.name } }
+          .then { append(*_1) unless _1.empty? }
+      end
+    end
+  end
+end

data/lib/docrb/parser/reference.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class Reference
+      visible_attr_accessor :path, :resolved
+      attr_accessor :parent
+
+      def initialize(parser, parent, path)
+        @parent = parent
+        @path = path
+        @parser = parser
+      end
+
+      def resolved? = !resolved.nil?
+      def fulfilled? = resolved? && resolved.valid?
+
+      def dereference!
+        raise "Dereference of unfulfilled reference" unless fulfilled?
+
+        resolved.dereference!
+      end
+    end
+  end
+end

data/lib/docrb/parser/reloader.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class Reloader
+      def self.reload!
+        Object.send(:remove_const, :Docrb) if defined? Docrb
+
+        root_dir = File.expand_path("../..", __dir__)
+        $LOADED_FEATURES
+          .select { _1.start_with? root_dir }
+          .each { $LOADED_FEATURES.delete _1 }
+
+        require "docrb/parser"
+        true
+      end
+    end
+  end
+end

data/lib/docrb/parser/resolved_reference.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class ResolvedReference
+      visible_attr_accessor :status
+
+      def initialize(parser, status, id)
+        @status = status
+        @object_id = id
+        @parser = parser
+      end
+
+      def id = @object_id
+
+      def broken? = status == :broken
+      def valid? = status == :valid
+
+      def dereference!
+        raise "Cannot dereference broken reference" if broken?
+
+        @parser.object_by_id(id)
+      end
+    end
+  end
+end

data/lib/docrb/parser/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    VERSION = "0.1.0"
+  end
+end

data/lib/docrb/parser/virtual_container.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class VirtualContainer
+      Body = Struct.new(:body)
+      ConstantName = Struct.new(:name) do
+        def type = :constant_read_node
+      end
+
+      attr_accessor :location, :body, :constant_path, :type, :superclass
+
+      def initialize(type, name)
+        @type = type
+        @constant_path = ConstantName.new(name:)
+        @location = VirtualLocation.new
+        @body = Body.new(body: [])
+      end
+    end
+  end
+end

data/lib/docrb/parser/virtual_location.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Docrb
+  class Parser
+    class VirtualLocation
+      def virtual? = true
+    end
+  end
+end