yard-sorbet 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50408c1c7ce4b8fe04219273c326e3ac432fe8eaee9c02fe7ba243c204202ff3
-  data.tar.gz: e01aabf41806def071f4807d5b4bd45e49c82cdb24360b9e3b9920361505b690
+  metadata.gz: 6269732c6f6c20a5757281dea8e97537116082e9f6fcc01af8e37b375585c573
+  data.tar.gz: 3ba3e2a3e9caf49054d30a3e6030540804d7515eecda12eda07140402406879b
 SHA512:
-  metadata.gz: fa3a9a39d00923dd39824b553900dc12d30cebb3f3770580bbf6400272f52c1bd55905211de9372d7e1bd80ff26d3d2ddaa0c56c437c9a65bb41c24d53e60b08
-  data.tar.gz: e322305cd757bb65135a90e9f9bf166161a98756449110714a4ce6dc7f47657cc539d72175c303114e67de7ac5c750c8216c31d8a1d8c818dacdeb5b404cbe1f
+  metadata.gz: aa63a4e71daaffb9e18d5613bed37d366b47f80ca040570e2195716b1ae2f275d2e1cad568df123064b0678ee9862d757e05b026efcaa164d80eaae26f2eb65a
+  data.tar.gz: 3d7de3147fe46b1ca6339ef32d66ae98c0f48851205a3baee320a88bbafec44921f64672c335c291a2b117895fa858e49fb254cd7ec3f2b20eb339f06e324f39

data/lib/yard-sorbet/handlers/include_handler.rb

@@ -16,10 +16,8 @@ module YARDSorbet
       def process
         statement.parameters(false).each do |mixin|
           obj = YARD::CodeObjects::Proxy.new(namespace, mixin.source)
-          class_methods_namespace = MixesInClassMethodsHandler.mixed_in_class_methods(obj.to_s)
-          next unless class_methods_namespace
-
-          included_in.mixins(:class) << YARD::CodeObjects::Proxy.new(obj, class_methods_namespace)
+          class_methods_namespaces = MixesInClassMethodsHandler.mixed_in_class_methods(obj.to_s)
+          class_methods_namespaces&.each { included_in.mixins(:class) << YARD::CodeObjects::Proxy.new(obj, _1) }
         end
       end
 

data/lib/yard-sorbet/handlers/mixes_in_class_methods_handler.rb

@@ -12,16 +12,17 @@ module YARDSorbet
       handles method_call(:mixes_in_class_methods)
       namespace_only
 
-      @@mix_in_class_methods = T.let({}, T::Hash[String, String]) # rubocop:disable Style/ClassVars
+      @@mix_in_class_methods = T.let({}, T::Hash[String, T::Array[String]]) # rubocop:disable Style/ClassVars
 
-      sig { params(code_obj: String).returns(T.nilable(String)) }
+      sig { params(code_obj: String).returns(T.nilable(T::Array[String])) }
       def self.mixed_in_class_methods(code_obj)
         @@mix_in_class_methods[code_obj]
       end
 
       sig { void }
       def process
-        @@mix_in_class_methods[namespace.to_s] = statement.parameters(false)[0].source
+        @@mix_in_class_methods[namespace.to_s] ||= []
+        @@mix_in_class_methods.fetch(namespace.to_s) << statement.parameters(false)[0].source
       end
     end
   end

data/lib/yard-sorbet/handlers/sig_handler.rb

@@ -10,59 +10,104 @@ module YARDSorbet
       handles method_call(:sig)
       namespace_only
 
-      # These node types attached to sigs represent attr_* declarations
-      ATTR_NODE_TYPES = T.let(%i[command fcall].freeze, T::Array[Symbol])
-      private_constant :ATTR_NODE_TYPES
+      # YARD types that can have docstrings attached to them
+      Documentable = T.type_alias do
+        T.any(
+          YARD::CodeObjects::MethodObject, YARD::Parser::Ruby::MethodCallNode, YARD::Parser::Ruby::MethodDefinitionNode
+        )
+      end
+      private_constant :Documentable
 
       # Swap the method definition docstring and the sig docstring.
       # Parse relevant parts of the `sig` and include them as well.
       sig { void }
       def process
         method_node = NodeUtils.get_method_node(NodeUtils.sibling_node(statement))
-        docstring, directives = Directives.extract_directives(statement.docstring)
-        parse_sig(method_node, docstring)
-        method_node.docstring = docstring.to_raw
-        Directives.add_directives(method_node.docstring, directives)
+        case method_node
+        when YARD::Parser::Ruby::MethodDefinitionNode then process_def(method_node)
+        when YARD::Parser::Ruby::MethodCallNode then process_attr(method_node)
+        end
         statement.docstring = nil
       end
 
       private
 
-      sig { params(method_node: YARD::Parser::Ruby::AstNode, docstring: YARD::Docstring).void }
-      def parse_sig(method_node, docstring)
-        NodeUtils.bfs_traverse(statement) do |n|
-          case n.source
-          when 'abstract'
-            YARDSorbet::TagUtils.upsert_tag(docstring, 'abstract')
-          when 'params'
-            parse_params(method_node, n, docstring)
-          when 'returns', 'void'
-            parse_return(n, docstring)
-          end
+      sig { params(def_node: YARD::Parser::Ruby::MethodDefinitionNode).void }
+      def process_def(def_node)
+        separator = scope == :instance && def_node.type == :def ? '#' : '.'
+        registered = YARD::Registry.at("#{namespace}#{separator}#{def_node.method_name(true)}")
+        if registered
+          parse_node(registered, registered.docstring)
+          # Since we're probably in an RBI file, delete the def node, which could otherwise erroneously override the
+          # visibility setting
+          NodeUtils.delete_node(def_node)
+        else
+          parse_node(def_node, statement.docstring)
         end
       end
 
-      sig do
-        params(
-          method_node: YARD::Parser::Ruby::AstNode,
-          node: YARD::Parser::Ruby::AstNode,
-          docstring: YARD::Docstring
-        ).void
+      sig { params(attr_node: YARD::Parser::Ruby::MethodCallNode).void }
+      def process_attr(attr_node)
+        return if merged_into_attr?(attr_node)
+
+        parse_node(attr_node, statement.docstring, include_params: false)
       end
-      def parse_params(method_node, node, docstring)
-        return if ATTR_NODE_TYPES.include?(method_node.type)
 
+      # An attr* sig can be merged into a previous attr* docstring if it is the only parameter passed to the attr*
+      # declaration. This is to avoid needing to rewrite the source code to separate merged and unmerged attr*
+      # declarations.
+      sig { params(attr_node: YARD::Parser::Ruby::MethodCallNode).returns(T::Boolean) }
+      def merged_into_attr?(attr_node)
+        names = NodeUtils.validated_attribute_names(attr_node)
+        return false if names.size != 1
+
+        attrs = namespace.attributes[scope][names[0]]
+        return false if attrs.nil? || attrs.empty?
+
+        document_attr_methods(attrs.values.compact)
+        attr_node.docstring = nil
+        true
+      end
+
+      sig { params(method_objects: T::Array[YARD::CodeObjects::MethodObject]).void }
+      def document_attr_methods(method_objects)
+        method_objects.each { parse_node(_1, _1.docstring, include_params: false) }
+      end
+
+      sig { params(attach_to: Documentable, docstring: T.nilable(String), include_params: T::Boolean).void }
+      def parse_node(attach_to, docstring, include_params: true)
+        existing_docstring = docstring.is_a?(YARD::Docstring)
+        docstring, directives = Directives.extract_directives(docstring) unless existing_docstring
+        parse_sig(docstring, include_params: include_params)
+        attach_to.docstring = docstring.to_raw
+        Directives.add_directives(attach_to.docstring, directives) unless existing_docstring
+      end
+
+      sig { params(docstring: YARD::Docstring, include_params: T::Boolean).void }
+      def parse_sig(docstring, include_params: true)
+        NodeUtils.bfs_traverse(statement) do |node|
+          case node.source
+          when 'returns' then parse_return(node, docstring)
+          when 'params' then parse_params(node, docstring) if include_params
+          when 'void' then TagUtils.upsert_tag(docstring, 'return', TagUtils::VOID_RETURN_TYPE)
+          when 'abstract' then TagUtils.upsert_tag(docstring, 'abstract')
+          end
+        end
+      end
+
+      sig { params(node: YARD::Parser::Ruby::AstNode, docstring: YARD::Docstring).void }
+      def parse_params(node, docstring)
         sibling = NodeUtils.sibling_node(node)
-        sibling[0][0].each do |p|
-          param_name = p[0][0]
-          types = SigToYARD.convert(p.last)
+        sibling[0][0].each do |param|
+          param_name = param[0][0]
+          types = SigToYARD.convert(param.last)
           TagUtils.upsert_tag(docstring, 'param', types, param_name)
         end
       end
 
       sig { params(node: YARD::Parser::Ruby::AstNode, docstring: YARD::Docstring).void }
       def parse_return(node, docstring)
-        type = node.source == 'void' ? ['void'] : SigToYARD.convert(NodeUtils.sibling_node(node))
+        type = SigToYARD.convert(NodeUtils.sibling_node(node))
         TagUtils.upsert_tag(docstring, 'return', type)
       end
     end

data/lib/yard-sorbet/handlers/struct_class_handler.rb

@@ -35,7 +35,7 @@ module YARDSorbet
         docstring, directives = Directives.extract_directives(object.docstring)
         object.tags.each { docstring.add_tag(_1) }
         props.each { TagUtils.upsert_tag(docstring, 'param', _1.types, _1.prop_name, _1.doc) }
-        TagUtils.upsert_tag(docstring, 'return', ['void'])
+        TagUtils.upsert_tag(docstring, 'return', TagUtils::VOID_RETURN_TYPE)
         decorate_t_struct_init(object, props, docstring, directives)
       end
 

data/lib/yard-sorbet/handlers/struct_prop_handler.rb

@@ -13,7 +13,7 @@ module YARDSorbet
 
       sig { void }
       def process
-        name = statement.parameters.first.last.last.source
+        name = params[0][-1][-1].source
         prop = make_prop(name)
         update_state(prop)
         object = YARD::CodeObjects::MethodObject.new(namespace, name, scope)
@@ -27,36 +27,45 @@ module YARDSorbet
       sig { params(object: YARD::CodeObjects::MethodObject, prop: TStructProp).void }
       def decorate_object(object, prop)
         object.source = prop.source
-        # TODO: this should use `+` to delimit the attribute name when markdown is disabled
-        reader_docstring = prop.doc.empty? ? "Returns the value of attribute `#{prop.prop_name}`." : prop.doc
+        # TODO: this should use `+` to delimit the prop name when markdown is disabled
+        reader_docstring = prop.doc.empty? ? "Returns the value of prop `#{prop.prop_name}`." : prop.doc
         docstring = YARD::DocstringParser.new.parse(reader_docstring).to_docstring
         docstring.add_tag(YARD::Tags::Tag.new(:return, '', prop.types))
         object.docstring = docstring.to_raw
       end
 
-      # Get the default prop value
-      sig { returns(T.nilable(String)) }
-      def default_value
-        statement.traverse { break _1 if _1.type == :label && _1.source == 'default:' }&.parent&.[](1)&.source
+      sig { returns(T::Boolean) }
+      def immutable?
+        statement.method_name(true) == :const || kw_arg('immutable:') == 'true'
+      end
+
+      # @return the value passed to the keyword argument, or nil
+      sig { params(kwd: String).returns(T.nilable(String)) }
+      def kw_arg(kwd)
+        params[2]&.find { _1[0].source == kwd }&.[](1)&.source
       end
 
       sig { params(name: String).returns(TStructProp) }
       def make_prop(name)
         TStructProp.new(
-          default: default_value,
+          default: kw_arg('default:'),
           doc: statement.docstring.to_s,
           prop_name: name,
           source: statement.source,
-          types: SigToYARD.convert(statement.parameters[1])
+          types: SigToYARD.convert(params[1])
         )
       end
 
+      sig { returns(T::Array[T.untyped]) }
+      def params
+        @params ||= T.let(statement.parameters(false), T.nilable(T::Array[T.untyped]))
+      end
+
       # Register the field explicitly as an attribute.
-      # While `const` attributes are immutable, `prop` attributes may be reassigned.
       sig { params(object: YARD::CodeObjects::MethodObject, name: String).void }
       def register_attrs(object, name)
-        # Create the virtual method in our current scope
-        write = statement.method_name(true) == :prop ? object : nil
+        write = immutable? ? nil : object
+        # Create the virtual attribute in our current scope
         namespace.attributes[scope][name] ||= SymbolHash[read: object, write: write]
       end
 

data/lib/yard-sorbet/node_utils.rb

@@ -12,7 +12,6 @@ module YARDSorbet
     SKIP_METHOD_CONTENTS = T.let(%i[params returns].freeze, T::Array[Symbol])
     # Node types that can have type signatures
     SigableNode = T.type_alias { T.any(YARD::Parser::Ruby::MethodDefinitionNode, YARD::Parser::Ruby::MethodCallNode) }
-
     private_constant :ATTRIBUTE_METHODS, :SKIP_METHOD_CONTENTS, :SigableNode
 
     # Traverse AST nodes in breadth-first order
@@ -29,17 +28,15 @@ module YARDSorbet
       end
     end
 
+    sig { params(node: YARD::Parser::Ruby::AstNode).void }
+    def self.delete_node(node)
+      node.parent.children.delete(node)
+    end
+
     # Gets the node that a sorbet `sig` can be attached do, bypassing visisbility modifiers and the like
     sig { params(node: YARD::Parser::Ruby::AstNode).returns(SigableNode) }
     def self.get_method_node(node)
-      case node
-      when YARD::Parser::Ruby::MethodDefinitionNode
-        return node
-      when YARD::Parser::Ruby::MethodCallNode
-        return node if ATTRIBUTE_METHODS.include?(node.method_name(true))
-      end
-
-      node.jump(:def, :defs)
+      sigable_node?(node) ? node : node.jump(:def, :defs)
     end
 
     # Find and return the adjacent node (ascending)
@@ -50,5 +47,26 @@ module YARDSorbet
       node_index = siblings.find_index { _1.equal?(node) }
       siblings.fetch(node_index + 1)
     end
+
+    sig { params(node: YARD::Parser::Ruby::AstNode).returns(T::Boolean) }
+    def self.sigable_node?(node)
+      case node
+      when YARD::Parser::Ruby::MethodDefinitionNode then true
+      when YARD::Parser::Ruby::MethodCallNode then ATTRIBUTE_METHODS.include?(node.method_name(true))
+      else false
+      end
+    end
+
+    # @see https://github.com/lsegal/yard/blob/main/lib/yard/handlers/ruby/attribute_handler.rb
+    #   YARD::Handlers::Ruby::AttributeHandler.validated_attribute_names
+    sig { params(attr_node: YARD::Parser::Ruby::MethodCallNode).returns(T::Array[String]) }
+    def self.validated_attribute_names(attr_node)
+      attr_node.parameters(false).map do |obj|
+        case obj
+        when YARD::Parser::Ruby::LiteralNode then obj[0][0].source
+        else raise YARD::Parser::UndocumentableError, obj.source
+        end
+      end
+    end
   end
 end

data/lib/yard-sorbet/sig_to_yard.rb

@@ -6,6 +6,7 @@ module YARDSorbet
   module SigToYARD
     extend T::Sig
 
+    # Map of common types to YARD conventions (in order to reduce allocations)
     REF_TYPES = T.let({
       'T::Boolean' => ['Boolean'].freeze, # YARD convention for booleans
       # YARD convention is use singleton objects when applicable:
@@ -87,7 +88,7 @@ module YARDSorbet
     sig { params(node: YARD::Parser::Ruby::AstNode).returns([String]) }
     private_class_method def self.convert_collection(node)
       collection_type = node.first.source.split('::').last
-      member_type = convert_node(node.last.first).join(', ')
+      member_type = convert_node(node[-1][0]).join(', ')
       ["#{collection_type}<#{member_type}>"]
     end
 
@@ -106,17 +107,16 @@ module YARDSorbet
 
     sig { params(node_source: String).returns([String]) }
     private_class_method def self.convert_ref(node_source)
-      REF_TYPES.fetch(node_source, [node_source])
+      REF_TYPES[node_source] || [node_source]
     end
 
     sig { params(node: YARD::Parser::Ruby::MethodCallNode).returns(T::Array[String]) }
     private_class_method def self.convert_t_method(node)
       case node.method_name(true)
-      when :any then node.last.first.children.flat_map { convert_node(_1) }
-      # Order matters here, putting `nil` last results in a more concise
-      # return syntax in the UI (superscripted `?`)
+      # Order matters here, putting `nil` last results in a more concise return syntax in the UI (superscripted `?`):
       # https://github.com/lsegal/yard/blob/cfa62ae/lib/yard/templates/helpers/html_helper.rb#L499-L500
-      when :nilable then convert_node(node.last) + ['nil']
+      when :nilable then convert_node(node.last) + REF_TYPES.fetch('NilClass')
+      when :any then node[-1][0].children.flat_map { convert_node(_1) }
       else [node.source]
       end
     end

data/lib/yard-sorbet/tag_utils.rb

@@ -6,6 +6,9 @@ module YARDSorbet
   module TagUtils
     extend T::Sig
 
+    # The `void` return type, as a constant to reduce array allocations
+    VOID_RETURN_TYPE = T.let(['void'].freeze, [String])
+
     # @return the tag with the matching `tag_name` and `name`, or `nil`
     sig do
       params(docstring: YARD::Docstring, tag_name: String, name: T.nilable(String)).returns(T.nilable(YARD::Tags::Tag))

data/lib/yard-sorbet/version.rb

@@ -4,5 +4,5 @@
 # Types are documentation
 module YARDSorbet
   # {https://rubygems.org/gems/yard-sorbet Version history}
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-sorbet
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Douglas Eichelberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-24 00:00:00.000000000 Z
+date: 2023-01-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -86,28 +86,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.35.0
+        version: 1.42.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.35.0
+        version: 1.42.0
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.14.0
+        version: 1.15.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.14.0
+        version: 1.15.0
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
@@ -128,14 +128,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.12.1
+        version: 2.16.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.12.1
+        version: 2.16.0
 - !ruby/object:Gem::Dependency
   name: rubocop-sorbet
   requirement: !ruby/object:Gem::Requirement
@@ -170,14 +170,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.4
+        version: 0.10.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.4
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
   requirement: !ruby/object:Gem::Requirement
@@ -206,9 +206,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.9'
-description: 'A YARD plugin that incorporates Sorbet type information
-
-  '
+description: A YARD plugin that incorporates Sorbet type information
 email: dduugg@gmail.com
 executables: []
 extensions: []