solargraph 0.56.0 → 0.58.2

data/lib/solargraph/convention/struct_definition/struct_definition_node.rb

@@ -1,100 +1,102 @@
-# frozen_string_literal: true
-
-module Solargraph
-  module Convention
-    module StructDefinition
-      # A node wrapper for a Struct definition via inheritance.
-      # @example
-      #   class MyStruct < Struct.new(:bar, :baz)
-      #     def foo
-      #     end
-      #   end
-      class StructDefintionNode
-        class << self
-          # @example
-          #   s(:class,
-          #     s(:const, nil, :Foo),
-          #     s(:send,
-          #       s(:const, nil, :Struct), :new,
-          #       s(:sym, :bar),
-          #       s(:sym, :baz)),
-          #       s(:hash,
-          #         s(:pair,
-          #           s(:sym, :keyword_init),
-          #           s(:true)))),
-          #     s(:def, :foo,
-          #       s(:args),
-          #       s(:send, nil, :bar)))
-          def valid?(node)
-            return false unless node&.type == :class
-
-            struct_definition_node?(node.children[1])
-          end
-
-          private
-
-          # @param struct_node [Parser::AST::Node]
-          # @return [Boolean]
-          def struct_definition_node?(struct_node)
-            return false unless struct_node.is_a?(::Parser::AST::Node)
-            return false unless struct_node&.type == :send
-            return false unless struct_node.children[0]&.type == :const
-            return false unless struct_node.children[0].children[1] == :Struct
-            return false unless struct_node.children[1] == :new
-
-            true
-          end
-        end
-
-        # @return [Parser::AST::Node]
-        def initialize(node)
-          @node = node
-        end
-
-        # @return [String]
-        def class_name
-          Parser::NodeMethods.unpack_name(node)
-        end
-
-        # @return [Array<Array(Parser::AST::Node, String)>]
-        def attributes
-          struct_attribute_nodes.map do |struct_def_param|
-            next unless struct_def_param.type == :sym
-            [struct_def_param, struct_def_param.children[0].to_s]
-          end.compact
-        end
-
-        def keyword_init?
-          keyword_init_param = struct_attribute_nodes.find do |struct_def_param|
-            struct_def_param.type == :hash && struct_def_param.children[0].type == :pair &&
-              struct_def_param.children[0].children[0].children[0] == :keyword_init
-          end
-
-          return false if keyword_init_param.nil?
-
-          keyword_init_param.children[0].children[1].type == :true
-        end
-
-        # @return [Parser::AST::Node]
-        def body_node
-          node.children[2]
-        end
-
-        private
-
-        # @return [Parser::AST::Node]
-        attr_reader :node
-
-        # @return [Parser::AST::Node]
-        def struct_node
-          node.children[1]
-        end
-
-        # @return [Array<Parser::AST::Node>]
-        def struct_attribute_nodes
-          struct_node.children[2..-1]
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Solargraph
+  module Convention
+    module StructDefinition
+      # A node wrapper for a Struct definition via inheritance.
+      # @example
+      #   class MyStruct < Struct.new(:bar, :baz)
+      #     def foo
+      #     end
+      #   end
+      class StructDefintionNode
+        class << self
+          # @example
+          #   s(:class,
+          #     s(:const, nil, :Foo),
+          #     s(:send,
+          #       s(:const, nil, :Struct), :new,
+          #       s(:sym, :bar),
+          #       s(:sym, :baz)),
+          #       s(:hash,
+          #         s(:pair,
+          #           s(:sym, :keyword_init),
+          #           s(:true)))),
+          #     s(:def, :foo,
+          #       s(:args),
+          #       s(:send, nil, :bar)))
+          #
+          # @param node [Parser::AST::Node]
+          def match?(node)
+            return false unless node&.type == :class
+
+            struct_definition_node?(node.children[1])
+          end
+
+          private
+
+          # @param struct_node [Parser::AST::Node]
+          # @return [Boolean]
+          def struct_definition_node?(struct_node)
+            return false unless struct_node.is_a?(::Parser::AST::Node)
+            return false unless struct_node&.type == :send
+            return false unless struct_node.children[0]&.type == :const
+            return false unless struct_node.children[0].children[1] == :Struct
+            return false unless struct_node.children[1] == :new
+
+            true
+          end
+        end
+
+        # @param node [Parser::AST::Node]
+        def initialize(node)
+          @node = node
+        end
+
+        # @return [String]
+        def class_name
+          Parser::NodeMethods.unpack_name(node)
+        end
+
+        # @return [Array<Array(Parser::AST::Node, String)>]
+        def attributes
+          struct_attribute_nodes.map do |struct_def_param|
+            next unless struct_def_param.type == :sym
+            [struct_def_param, struct_def_param.children[0].to_s]
+          end.compact
+        end
+
+        def keyword_init?
+          keyword_init_param = struct_attribute_nodes.find do |struct_def_param|
+            struct_def_param.type == :hash && struct_def_param.children[0].type == :pair &&
+              struct_def_param.children[0].children[0].children[0] == :keyword_init
+          end
+
+          return false if keyword_init_param.nil?
+
+          keyword_init_param.children[0].children[1].type == :true
+        end
+
+        # @return [Parser::AST::Node]
+        def body_node
+          node.children[2]
+        end
+
+        private
+
+        # @return [Parser::AST::Node]
+        attr_reader :node
+
+        # @return [Parser::AST::Node]
+        def struct_node
+          node.children[1]
+        end
+
+        # @return [Array<Parser::AST::Node>]
+        def struct_attribute_nodes
+          struct_node.children[2..-1]
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/convention/struct_definition.rb

@@ -1,101 +1,164 @@
-# frozen_string_literal: true
-
-module Solargraph
-  module Convention
-    module StructDefinition
-      autoload :StructDefintionNode, 'solargraph/convention/struct_definition/struct_definition_node'
-      autoload :StructAssignmentNode, 'solargraph/convention/struct_definition/struct_assignment_node'
-
-      module NodeProcessors
-        class StructNode < Parser::NodeProcessor::Base
-          def process
-            return if struct_definition_node.nil?
-
-            loc = get_node_location(node)
-            nspin = Solargraph::Pin::Namespace.new(
-              type: :class,
-              location: loc,
-              closure: region.closure,
-              name: struct_definition_node.class_name,
-              comments: comments_for(node),
-              visibility: :public,
-              gates: region.closure.gates.freeze
-            )
-            pins.push nspin
-
-            # define initialize method
-            initialize_method_pin = Pin::Method.new(
-              name: 'initialize',
-              parameters: [],
-              scope: :instance,
-              location: get_node_location(node),
-              closure: nspin,
-              visibility: :private,
-              comments: comments_for(node)
-            )
-
-            pins.push initialize_method_pin
-
-            struct_definition_node.attributes.map do |attribute_node, attribute_name|
-              initialize_method_pin.parameters.push(
-                Pin::Parameter.new(
-                  name: attribute_name,
-                  decl: struct_definition_node.keyword_init? ? :kwarg : :arg,
-                  location: get_node_location(attribute_node),
-                  closure: initialize_method_pin
-                )
-              )
-            end
-
-            # define attribute accessors and instance variables
-            struct_definition_node.attributes.each do |attribute_node, attribute_name|
-              [attribute_name, "#{attribute_name}="].each do |name|
-                method_pin = Pin::Method.new(
-                  name: name,
-                  parameters: [],
-                  scope: :instance,
-                  location: get_node_location(attribute_node),
-                  closure: nspin,
-                  comments: attribute_comments(attribute_node, attribute_name),
-                  visibility: :public
-                )
-
-                pins.push method_pin
-
-                next unless name.include?('=') # setter
-                pins.push Pin::InstanceVariable.new(name: "@#{attribute_name}",
-                                                    closure: method_pin,
-                                                    location: get_node_location(attribute_node),
-                                                    comments: attribute_comments(attribute_node, attribute_name))
-              end
-            end
-
-            process_children region.update(closure: nspin, visibility: :public)
-          end
-
-          private
-
-          # @return [StructDefintionNode, nil]
-          def struct_definition_node
-            @struct_definition_node ||= if StructDefintionNode.valid?(node)
-                                          StructDefintionNode.new(node)
-                                        elsif StructAssignmentNode.valid?(node)
-                                          StructAssignmentNode.new(node)
-                                        end
-          end
-
-          # @param attribute_node [Parser::AST::Node]
-          # @return [String, nil]
-          def attribute_comments(attribute_node, attribute_name)
-            struct_comments = comments_for(attribute_node)
-            return if struct_comments.nil? || struct_comments.empty?
-
-            struct_comments.split("\n").find do |row|
-              row.include?(attribute_name)
-            end&.gsub('@param', '@return')&.gsub(attribute_name, '')
-          end
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Solargraph
+  module Convention
+    module StructDefinition
+      autoload :StructDefintionNode, 'solargraph/convention/struct_definition/struct_definition_node'
+      autoload :StructAssignmentNode, 'solargraph/convention/struct_definition/struct_assignment_node'
+
+      module NodeProcessors
+        class StructNode < Parser::NodeProcessor::Base
+          # @return [Boolean] continue processing the next processor of the same node.
+          def process
+            return true if struct_definition_node.nil?
+
+            loc = get_node_location(node)
+            nspin = Solargraph::Pin::Namespace.new(
+              type: :class,
+              location: loc,
+              closure: region.closure,
+              name: struct_definition_node.class_name,
+              docstring: docstring,
+              visibility: :public,
+              gates: region.closure.gates.freeze,
+              source: :struct_definition
+            )
+            pins.push nspin
+
+            # define initialize method
+            initialize_method_pin = Pin::Method.new(
+              name: 'initialize',
+              parameters: [],
+              scope: :instance,
+              location: get_node_location(node),
+              closure: nspin,
+              visibility: :private,
+              docstring: docstring,
+              source: :struct_definition
+            )
+
+            pins.push initialize_method_pin
+
+            struct_definition_node.attributes.map do |attribute_node, attribute_name|
+              initialize_method_pin.parameters.push(
+                Pin::Parameter.new(
+                  name: attribute_name,
+                  decl: struct_definition_node.keyword_init? ? :kwarg : :arg,
+                  location: get_node_location(attribute_node),
+                  closure: initialize_method_pin,
+                  source: :struct_definition
+                )
+              )
+            end
+
+            # define attribute accessors and instance variables
+            struct_definition_node.attributes.each do |attribute_node, attribute_name|
+              [attribute_name, "#{attribute_name}="].each do |name|
+                docs = docstring.tags.find { |t| t.tag_name == 'param' && t.name == attribute_name }
+
+                attribute_type = ComplexType.parse(tag_string(docs))
+                return_type_comment = attribute_comment(docs, false)
+                param_comment = attribute_comment(docs, true)
+
+                method_pin = Pin::Method.new(
+                  name: name,
+                  parameters: [],
+                  scope: :instance,
+                  location: get_node_location(attribute_node),
+                  closure: nspin,
+                  docstring: YARD::Docstring.new(return_type_comment),
+                  # even assignments return the value
+                  comments: return_type_comment,
+                  return_type: attribute_type,
+                  visibility: :public,
+                  source: :struct_definition
+                )
+
+                if name.end_with?('=')
+                  method_pin.parameters << Pin::Parameter.new(
+                    name: attribute_name,
+                    location: get_node_location(attribute_node),
+                    closure: method_pin,
+                    return_type: attribute_type,
+                    comments: param_comment,
+                    source: :struct_definition
+                  )
+
+                  pins.push Pin::InstanceVariable.new(name: "@#{attribute_name}",
+                                                      closure: method_pin,
+                                                      location: get_node_location(attribute_node),
+                                                      return_type: attribute_type,
+                                                      comments: "@type [#{attribute_type.rooted_tags}]",
+                                                      source: :struct_definition)
+                end
+
+                pins.push method_pin
+              end
+            end
+
+            process_children region.update(closure: nspin, visibility: :public)
+            false
+          end
+
+          private
+
+          # @return [StructDefintionNode, StructAssignmentNode, nil]
+          def struct_definition_node
+            @struct_definition_node ||= if StructDefintionNode.match?(node)
+                                          StructDefintionNode.new(node)
+                                        elsif StructAssignmentNode.match?(node)
+                                          StructAssignmentNode.new(node)
+                                        end
+          end
+
+          # Gets/generates the relevant docstring for this struct & it's attributes
+          # @return [YARD::Docstring]
+          def docstring
+            @docstring ||= parse_comments
+          end
+
+          # Parses any relevant comments for a struct int a yard docstring
+          # @return [YARD::Docstring]
+          def parse_comments
+            struct_comments = comments_for(node) || ''
+            struct_definition_node.attributes.each do |attr_node, attr_name|
+              comment = comments_for(attr_node)
+              next if comment.nil?
+
+              # We should support specific comments for an attribute, and that can be either a @return on an @param
+              # But since we merge into the struct_comments, then we should interpret either as a param
+              comment = "@param #{attr_name}#{comment[7..]}" if comment.start_with?('@return')
+
+              struct_comments += "\n#{comment}"
+            end
+
+            Solargraph::Source.parse_docstring(struct_comments).to_docstring
+          end
+
+          # @param tag [YARD::Tags::Tag, nil] The param tag for this attribute.xtract_
+          #
+          # @return [String]
+          def tag_string(tag)
+            tag&.types&.join(',') || 'undefined'
+          end
+
+          # @param tag [YARD::Tags::Tag, nil] The param tag for this attribute. If nil, this method is a no-op
+          # @param for_setter [Boolean] If true, will return a @param tag instead of a @return tag
+          #
+          # @return [String] The formatted comment for the attribute
+          def attribute_comment(tag, for_setter)
+            return "" if tag.nil?
+
+            suffix = "[#{tag_string(tag)}] #{tag.text}"
+
+            if for_setter
+              "@param #{tag.name} #{suffix}"
+            else
+              "@return #{suffix}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solargraph/convention.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-
 module Solargraph
   # Conventions provide a way to modify an ApiMap based on expectations about
   # one of its sources.
@@ -11,6 +10,8 @@ module Solargraph
     autoload :Gemspec, 'solargraph/convention/gemspec'
     autoload :Rakefile, 'solargraph/convention/rakefile'
     autoload :StructDefinition, 'solargraph/convention/struct_definition'
+    autoload :DataDefinition,   'solargraph/convention/data_definition'
+    autoload :ActiveSupportConcern, 'solargraph/convention/active_support_concern'
 
     # @type [Set<Convention::Base>]
     @@conventions = Set.new
@@ -21,6 +22,12 @@ module Solargraph
       @@conventions.add convention.new
     end
 
+    # @param convention [Class<Convention::Base>]
+    # @return [void]
+    def self.unregister convention
+      @@conventions.delete_if { |c| c.is_a?(convention) }
+    end
+
     # @param source_map [SourceMap]
     # @return [Environ]
     def self.for_local(source_map)
@@ -31,7 +38,7 @@ module Solargraph
       result
     end
 
-    # @param yard_map [DocMap]
+    # @param doc_map [DocMap]
     # @return [Environ]
     def self.for_global(doc_map)
       result = Environ.new
@@ -41,8 +48,31 @@ module Solargraph
       result
     end
 
+    # Provides any additional method pins based on the described object.
+    #
+    # @param api_map [ApiMap]
+    # @param rooted_tag [String] A fully qualified namespace, with
+    #   generic parameter values if applicable
+    # @param scope [Symbol] :class or :instance
+    # @param visibility [Array<Symbol>] :public, :protected, and/or :private
+    # @param deep [Boolean]
+    # @param skip [Set<String>]
+    # @param no_core [Boolean] Skip core classes if true
+    #
+    # @return [Environ]
+    def self.for_object api_map, rooted_tag, scope, visibility,
+                        deep, skip, no_core
+      result = Environ.new
+      @@conventions.each do |conv|
+        result.merge conv.object(api_map, rooted_tag, scope, visibility,
+                                 deep, skip, no_core)
+      end
+      result
+    end
+
     register Gemfile
     register Gemspec
     register Rakefile
+    register ActiveSupportConcern
   end
 end

data/lib/solargraph/diagnostics/require_not_found.rb

@@ -1,53 +1,53 @@
-# frozen_string_literal: true
-
-module Solargraph
-  module Diagnostics
-    # RequireNotFound reports required paths that could not be resolved to
-    # either a file in the workspace or a gem.
-    #
-    class RequireNotFound < Base
-      def diagnose source, api_map
-        return [] unless source.parsed? && source.synchronized?
-        result = []
-        refs = {}
-        map = api_map.source_map(source.filename)
-        map.requires.each { |ref| refs[ref.name] = ref }
-        api_map.missing_docs.each do |r|
-          next unless refs.key?(r)
-          result.push docs_error(r, refs[r].location)
-        end
-        api_map.unresolved_requires.each do |r|
-          next unless refs.key?(r)
-          result.push require_error(r, refs[r].location)
-        end
-        result
-      end
-
-      private
-
-      # @param path [String]
-      # @param location [Location]
-      # @return [Hash]
-      def docs_error path, location
-        {
-          range: location.range.to_hash,
-          severity: Diagnostics::Severities::WARNING,
-          source: 'RequireNotFound',
-          message: "YARD docs not found for #{path}"
-        }
-      end
-
-      # @param path [String]
-      # @param location [Location]
-      # @return [Hash]
-      def require_error path, location
-        {
-          range: location.range.to_hash,
-          severity: Diagnostics::Severities::WARNING,
-          source: 'RequireNotFound',
-          message: "Required path #{path} could not be resolved."
-        }
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Solargraph
+  module Diagnostics
+    # RequireNotFound reports required paths that could not be resolved to
+    # either a file in the workspace or a gem.
+    #
+    class RequireNotFound < Base
+      def diagnose source, api_map
+        return [] unless source.parsed? && source.synchronized?
+        result = []
+        refs = {}
+        map = api_map.source_map(source.filename)
+        map.requires.each { |ref| refs[ref.name] = ref }
+        api_map.missing_docs.each do |r|
+          next unless refs.key?(r)
+          result.push docs_error(r, refs[r].location)
+        end
+        api_map.unresolved_requires.each do |r|
+          next unless refs.key?(r)
+          result.push require_error(r, refs[r].location)
+        end
+        result
+      end
+
+      private
+
+      # @param path [String]
+      # @param location [Location]
+      # @return [Hash]
+      def docs_error path, location
+        {
+          range: location.range.to_hash,
+          severity: Diagnostics::Severities::WARNING,
+          source: 'RequireNotFound',
+          message: "YARD docs not found for #{path}"
+        }
+      end
+
+      # @param path [String]
+      # @param location [Location]
+      # @return [Hash]
+      def require_error path, location
+        {
+          range: location.range.to_hash,
+          severity: Diagnostics::Severities::WARNING,
+          source: 'RequireNotFound',
+          message: "Required path #{path} could not be resolved."
+        }
+      end
+    end
+  end
+end