yard 0.9.38 → 0.9.40

data/lib/yard/parser/rbs/rbs_parser.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+module YARD
+  module Parser
+    module RBS
+      # Parses RBS (Ruby type signature) files and produces a list of
+      # {Statement} objects for post-processing by handlers.
+      #
+      # RBS is Ruby's official type signature format (introduced in Ruby 3.0).
+      # This parser handles: class/module/interface declarations, method
+      # signatures, attribute accessors, mixins, and constants.
+      #
+      # No external gem dependencies are used; the parser is hand-written.
+      class RbsParser < YARD::Parser::Base
+        # @param source [String] source code to parse
+        # @param filename [String] path to the source file
+        def initialize(source, filename)
+          @source   = source
+          @filename = filename
+          @statements = nil
+        end
+
+        # Parses the source and returns self.
+        # @return [RbsParser] self
+        def parse
+          lines = @source.lines.map { |l| l.chomp }
+          @statements, = parse_body(lines, 0, false)
+          self
+        end
+
+        # Tokenization is not implemented for RBS.
+        def tokenize
+          raise NotImplementedError, "RBS parser does not support tokenization"
+        end
+
+        # @return [Array<Statement>] top-level statements for the post-processor
+        def enumerator
+          @statements
+        end
+
+        private
+
+        # Parse a sequence of lines, returning statements and the index after the last consumed line.
+        #
+        # @param lines [Array<String>] source lines
+        # @param start [Integer] index to start from (0-based)
+        # @param stop_at_end [Boolean] when true, stop parsing when we see a bare `end`
+        # @return [Array(Array<Statement>, Integer)] [statements, new_index]
+        def parse_body(lines, start, stop_at_end)
+          statements        = []
+          i                 = start
+          pending_comments  = []
+          pending_start_1   = nil  # 1-indexed line number of first pending comment
+
+          while i < lines.length
+            raw      = lines[i]
+            stripped = raw.strip
+
+            if stripped =~ /\A#(.*)/
+              # Comment line – accumulate into pending docstring.
+              # Strip at most one leading space (conventional RBS doc style).
+              pending_comments << $1.sub(/\A /, '')
+              pending_start_1 ||= i + 1
+              i += 1
+
+            elsif stripped.empty?
+              # Blank line resets pending comments.
+              pending_comments  = []
+              pending_start_1   = nil
+              i += 1
+
+            elsif stop_at_end && stripped == 'end'
+              # End of enclosing block.
+              return [statements, i + 1]
+
+            else
+              stmt, i = parse_statement(lines, i, pending_comments, pending_start_1)
+              statements << stmt if stmt
+              pending_comments  = []
+              pending_start_1   = nil
+            end
+          end
+
+          [statements, i]
+        end
+
+        def strip_inline_comment(line)
+          in_single = false
+          in_double = false
+          escaped   = false
+
+          line.each_char.with_index do |char, index|
+            if escaped
+              escaped = false
+              next
+            end
+
+            case char
+            when "\\"
+              escaped = true if in_single || in_double
+            when "'"
+              in_single = !in_single unless in_double
+            when '"'
+              in_double = !in_double unless in_single
+            when '#'
+              return line[0...index].rstrip unless in_single || in_double
+            end
+          end
+
+          line.rstrip
+        end
+
+        def sanitized_statement_lines(lines, start_index)
+          overrides = { start_index => strip_inline_comment(lines[start_index]) }
+
+          j = start_index + 1
+          while j < lines.length && lines[j].lstrip.start_with?('|')
+            overrides[j] = strip_inline_comment(lines[j])
+            j += 1
+          end
+
+          overrides
+        end
+
+        # Dispatch a single declaration line.
+        def parse_statement(lines, i, comments, comment_start_1)
+          sanitized     = sanitized_statement_lines(lines, i)
+          stripped      = sanitized.fetch(i, lines[i]).strip
+          line_num        = i + 1  # 1-indexed
+
+          docs   = comments.empty? ? nil : comments.join("\n")
+          crange = comment_start_1 ? (comment_start_1)..(line_num - 1) : nil
+
+          case stripped
+          when /\Aclass\s/
+            parse_namespace(:class, lines, i, docs, crange)
+          when /\Amodule\s/
+            parse_namespace(:module, lines, i, docs, crange)
+          when /\Ainterface\s/
+            parse_namespace(:interface, lines, i, docs, crange)
+          when /\Adef\s/
+            parse_method_def(sanitized, lines, i, docs, crange)
+          when /\Aattr_reader\s/
+            parse_attr(:attr_reader, lines, i, docs, crange)
+          when /\Aattr_writer\s/
+            parse_attr(:attr_writer, lines, i, docs, crange)
+          when /\Aattr_accessor\s/
+            parse_attr(:attr_accessor, lines, i, docs, crange)
+          when /\A(include|extend|prepend)\s+(\S+)/
+            kind = $1.to_sym
+            name = $2.delete(';')
+            stmt = Statement.new(
+              :type           => kind,
+              :name           => name,
+              :mixin_name     => name,
+              :line           => line_num,
+              :source         => stripped,
+              :comments       => docs,
+              :comments_range => crange
+            )
+            [stmt, i + 1]
+          when /\Aalias\s+(\S+)\s+(\S+)/
+            stmt = Statement.new(
+              :type           => :alias,
+              :name           => $1,
+              :line           => line_num,
+              :source         => stripped,
+              :comments       => docs,
+              :comments_range => crange
+            )
+            [stmt, i + 1]
+          when /\A(public|private|protected)\s*(\z|#)/
+            # Visibility modifier – skip silently.
+            [nil, i + 1]
+          when /\Aend\s*(\z|#)/
+            # Stray `end` – skip.
+            [nil, i + 1]
+          when /\Atype\s/
+            # Type alias declaration – nothing to document.
+            [nil, i + 1]
+          else
+            # Constant declaration: `NAME: Type`
+            if stripped =~ /\A([A-Z][a-zA-Z0-9_]*(?:::[A-Z][a-zA-Z0-9_]*)*)\s*:\s*(.+)\z/
+              stmt = Statement.new(
+                :type           => :constant,
+                :name           => $1,
+                :attr_rbs_type  => $2.strip,
+                :line           => line_num,
+                :source         => stripped,
+                :comments       => docs,
+                :comments_range => crange
+              )
+              [stmt, i + 1]
+            else
+              [nil, i + 1]
+            end
+          end
+        end
+
+        def parse_namespace(type, lines, i, docs, crange)
+          # Strip trailing inline comment from the declaration line.
+          decl     = lines[i].strip.sub(/\s*#.*\z/, '')
+          line_num = i + 1
+
+          name       = nil
+          superclass = nil
+
+          case type
+          when :class
+            # class Foo[T] < Bar[String]
+            if decl =~ /\Aclass\s+([^\s<\[]+)(\[[^\]]*\])?(?:\s*<\s*(.+))?\z/
+              name       = $1.strip
+              superclass = $3 ? $3.strip : nil
+              # Strip generic params from superclass, e.g. "Array[String]" -> "Array"
+              superclass.sub!(/\[.*\]\z/, '') if superclass
+            else
+              return [nil, i + 1]
+            end
+
+          when :module
+            # module Foo[T] : SelfType
+            if decl =~ /\Amodule\s+([^\s\[(:]+)/
+              name = $1.strip
+            else
+              return [nil, i + 1]
+            end
+
+          when :interface
+            # interface _Foo[T]
+            if decl =~ /\Ainterface\s+([^\s\[]+)/
+              name = $1.strip
+            else
+              return [nil, i + 1]
+            end
+          end
+
+          children, new_i = parse_body(lines, i + 1, true)
+          source = lines[i...new_i].join("\n")
+
+          stmt = Statement.new(
+            :type           => type,
+            :name           => name,
+            :superclass     => superclass,
+            :line           => line_num,
+            :source         => source,
+            :comments       => docs,
+            :comments_range => crange,
+            :block          => children
+          )
+
+          [stmt, new_i]
+        end
+
+        def parse_method_def(sanitized, lines, i, docs, crange)
+          stripped = sanitized.fetch(i, lines[i]).strip
+          line_num = i + 1
+
+          # def method_name: overload1
+          #                | overload2
+          # Also handles: def self.method_name: ...
+          unless stripped =~ /\Adef\s+(self\.)?(\S+?)\s*:\s*(.*)\z/
+            return [nil, i + 1]
+          end
+
+          is_class_side = !$1.nil?
+          meth_name     = $2
+          first_sig     = $3.strip
+
+          sigs = [first_sig]
+          j    = i + 1
+
+          # Collect `| overload` continuation lines.
+          while j < lines.length
+            cont = sanitized.fetch(j, lines[j]).strip
+            if cont =~ /\A\|\s*(.*)\z/
+              sigs << $1.strip
+              j += 1
+            else
+              break
+            end
+          end
+
+          stmt = Statement.new(
+            :type           => :method_def,
+            :name           => meth_name,
+            :line           => line_num,
+            :source         => lines[i...j].join("\n"),
+            :comments       => docs,
+            :comments_range => crange,
+            :signatures     => sigs,
+            :visibility     => is_class_side ? :class : :instance
+          )
+
+          [stmt, j]
+        end
+
+        def parse_attr(type, lines, i, docs, crange)
+          stripped = strip_inline_comment(lines[i]).strip
+          line_num = i + 1
+          keyword  = type.to_s
+
+          # attr_reader [self.] name : Type
+          if stripped =~ /\A#{Regexp.escape(keyword)}\s+(self\.)?(\w+)\s*:\s*(.*)\z/
+            is_class  = !$1.nil?
+            attr_name = $2
+            attr_type = $3.strip
+
+            stmt = Statement.new(
+              :type           => type,
+              :name           => attr_name,
+              :attr_rbs_type  => attr_type,
+              :line           => line_num,
+              :source         => stripped,
+              :comments       => docs,
+              :comments_range => crange,
+              :visibility     => is_class ? :class : :instance
+            )
+            [stmt, i + 1]
+          else
+            [nil, i + 1]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/parser/rbs/statement.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+module YARD
+  module Parser
+    module RBS
+      # Represents a single parsed declaration from an RBS file.
+      # Each Statement may have a block of child statements for
+      # namespace declarations (class, module, interface).
+      class Statement
+        # @return [Symbol] declaration type:
+        #   :class, :module, :interface, :method_def,
+        #   :attr_reader, :attr_writer, :attr_accessor,
+        #   :include, :extend, :prepend, :constant, :alias
+        attr_reader :type
+
+        # @return [String] the declaration name
+        attr_reader :name
+
+        # @return [String, nil] the superclass name (for :class)
+        attr_reader :superclass
+
+        # @return [Integer] 1-indexed line number of this statement
+        attr_reader :line
+
+        # @return [String] raw source text of the statement
+        attr_reader :source
+
+        # @return [String, nil] adjacent comment text (the docstring)
+        attr_reader :comments
+
+        # @return [Range, nil] line range of the preceding comments
+        attr_reader :comments_range
+
+        # @return [false] RBS files don't use ## hash-flag comments
+        attr_reader :comments_hash_flag
+
+        # @return [Array<Statement>] child statements for namespace blocks
+        attr_reader :block
+
+        # @return [Array<String>] RBS type signature strings for :method_def
+        #   Each element is one overload (e.g. "(String name) -> Integer")
+        attr_reader :signatures
+
+        # @return [String, nil] mixin name for :include/:extend/:prepend
+        attr_reader :mixin_name
+
+        # @return [String, nil] RBS type annotation for attrs and constants
+        attr_reader :attr_rbs_type
+
+        # @return [Symbol, nil] :class or :instance scope hint from parser
+        attr_reader :visibility
+
+        def initialize(attrs = {})
+          @type              = attrs[:type]
+          @name              = attrs[:name]
+          @superclass        = attrs[:superclass]
+          @line              = attrs[:line] || 1
+          @source            = attrs[:source] || ''
+          @comments          = attrs[:comments]
+          @comments_range    = attrs[:comments_range]
+          @comments_hash_flag = false
+          @block             = attrs[:block] || []
+          @signatures        = attrs[:signatures] || []
+          @mixin_name        = attrs[:mixin_name]
+          @attr_rbs_type     = attrs[:attr_rbs_type]
+          @visibility        = attrs[:visibility]
+        end
+
+        # @return [String] a textual snippet used in error messages
+        def show
+          source
+        end
+      end
+    end
+  end
+end

data/lib/yard/parser/ruby/legacy/irb/slex.rb

@@ -10,7 +10,25 @@
 #
 #
 
-require "irb/notifier"
+begin
+  require "irb/notifier"
+rescue LoadError
+  module IRB
+    module DebugLogger
+      def self.pp(*args) end
+    end
+
+    module Notifier
+      D_NOMSG = 0x00
+      def self.def_notifier(*args) self end
+      def self.pp(*args) end
+      def self.exec_if(*args, &block) end
+      def self.printf(*args) end
+      def self.puts(*args) end
+      def self.level=(value) end
+    end
+  end
+end
 
 # @private
 module IRB

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -244,6 +244,7 @@ module YARD
             sstart = child_node.source_range.first
           else
             lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
+            (@map[:rbrace] ||= []).shift if map && MAPPINGS[node.type] == :lbrace
           end
 
           raise "Cannot determine start of node #{node} around #{file}:#{lineno}" if lstart.nil? || sstart.nil?
@@ -308,7 +309,7 @@ module YARD
             @heredoc_tokens << [token, data, [lineno, charno]]
 
             # fix ripper encoding of heredoc bug
-            # (see http://bugs.ruby-lang.org/issues/6200)
+            # (see https://bugs.ruby-lang.org/issues/6200)
             data.force_encoding(file_encoding) if file_encoding
 
             @heredoc_state = :ended if token == :heredoc_end
@@ -336,6 +337,7 @@ module YARD
         undef on_aref_field
         undef on_lbracket
         undef on_rbracket
+        undef on_rbrace
         undef on_string_literal
         undef on_lambda
         undef on_unary
@@ -371,6 +373,20 @@ module YARD
           visit_event AstNode.new(:hash, args.first || [])
         end
 
+        # Ruby 3.0+ pattern matching: braced hash patterns ({key: val} syntax) fire
+        # on_lbrace and on_rbrace scanner events. The corresponding parser event is
+        # on_hshptn (not on_hash), so we must clean up the brace maps to prevent stale
+        # entries from corrupting source ranges of later hash literals and brace blocks.
+        # Bare hash patterns (key: val without braces) fire no brace scanner events, so
+        # we only clean up when @map[:rbrace] confirms a closing brace was scanned.
+        def on_hshptn(*args)
+          if (@map[:rbrace] ||= []).any?
+            (@map[:lbrace] ||= []).pop
+            @map[:rbrace].shift
+          end
+          AstNode.new(:hshptn, args)
+        end
+
         def on_bare_assoc_hash(*args)
           AstNode.new(:list, args.first)
         end
@@ -398,8 +414,10 @@ module YARD
 
         def on_aref_field(*args)
           @map[:lbracket].pop
-          AstNode.new(:aref_field, args,
-                      :listline => lineno..lineno, :listchar => charno...charno)
+          ll, lc = *@map[:aref].shift
+          sr = args.first.source_range.begin..lc
+          lr = args.first.line_range.begin..ll
+          AstNode.new(:aref_field, args, :char => sr, :line => lr)
         end
 
         def on_array(other)
@@ -420,6 +438,27 @@ module YARD
           node
         end
 
+        # Ruby 3.0+ pattern matching: array patterns (SomeClass[a, b]) and find patterns
+        # (SomeClass[*pre, val, *post]) use [...] brackets, which fire on_lbracket and
+        # on_rbracket scanner events. The corresponding parser events are on_aryptn/on_fndptn
+        # (not on_aref), so we must clean up the bracket maps to prevent stale entries from
+        # corrupting source ranges of later array indexing expressions.
+        def on_aryptn(*args)
+          (@map[:lbracket] ||= []).pop
+          (@map[:aref] ||= []).shift
+          # Source range is intentionally not set; no handler is registered for
+          # pattern-match nodes, so they produce no documentation output.
+          AstNode.new(:aryptn, args)
+        end
+
+        def on_fndptn(*args)
+          (@map[:lbracket] ||= []).pop
+          (@map[:aref] ||= []).shift
+          # Source range is intentionally not set; no handler is registered for
+          # pattern-match nodes, so they produce no documentation output.
+          AstNode.new(:fndptn, args)
+        end
+
         def on_lbracket(tok)
           (@map[:lbracket] ||= []) << [lineno, charno]
           visit_ns_token(:lbracket, tok, false)
@@ -430,6 +469,13 @@ module YARD
           visit_ns_token(:rbracket, tok, false)
         end
 
+        # Maintained explicitly (unlike on_lbracket/on_rbracket) so on_hshptn can
+        # distinguish braced from bare hash patterns in Ruby 3.0+ pattern matching.
+        def on_rbrace(tok)
+          (@map[:rbrace] ||= []) << [lineno, charno]
+          visit_ns_token(:rbrace, tok, false)
+        end
+
         def on_dyna_symbol(sym)
           rng = if sym.source_range.to_a.size == 0 # rubocop:disable Style/ZeroLengthPredicate
                   (sym.source_range.begin - 3)...sym.source_range.end
@@ -623,6 +669,7 @@ module YARD
         alias compile_error on_parse_error
 
         def comment_starts_line?(charno)
+          return true if @source[charno] == "\n"
           (charno - 1).downto(0) do |i|
             ch = @source[i]
             break if ch == "\n"
@@ -700,6 +747,11 @@ module YARD
         def add_comment(line, node = nil, before_node = nil, into = false)
           comment = @comments[line]
           source_range = @comments_range[line]
+          if comment && source_range
+            source = @source[source_range]
+            last_line = source.lines.to_a.last
+            return if last_line && last_line =~ /^\s*\#-\s*$/
+          end
           line_range = ((line - comment.count("\n"))..line)
           if node.nil?
             node = CommentNode.new(:comment, [comment], :line => line_range, :char => source_range)

data/lib/yard/parser/source_parser.rb

@@ -67,7 +67,7 @@ module YARD
 
       # The default glob of files to be parsed.
       # @since 0.9.0
-      DEFAULT_PATH_GLOB = ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp,rb}"]
+      DEFAULT_PATH_GLOB = ["{lib,app}/**/*.{rb,rbs}", "sig/**/*.rbs", "ext/**/*.{c,cc,cxx,cpp,rb}"]
 
       # Byte order marks for various encodings
       # @since 0.7.0
@@ -105,7 +105,7 @@ module YARD
             end
           end
           files = [paths].flatten.
-            map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c,cc,cxx,cpp}" : p }.
+            map {|p| File.directory?(p) ? "#{p}/**/*.{rb,rbs,c,cc,cxx,cpp}" : p }.
             map {|p| p.include?("*") ? Dir[p].sort_by {|d| [d.length, d] } : p }.flatten.
             reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }.
             map {|p| p.encoding == Encoding.default_external ? p : p.dup.force_encoding(Encoding.default_external) }
@@ -379,6 +379,7 @@ module YARD
       register_parser_type :ruby,   Ruby::RubyParser
       register_parser_type :ruby18, Ruby::Legacy::RubyParser
       register_parser_type :c,      C::CParser, ['c', 'cc', 'cxx', 'cpp']
+      register_parser_type :rbs,    RBS::RbsParser, ['rbs']
 
       self.parser_type = :ruby
 

data/lib/yard/registry_resolver.rb

@@ -75,6 +75,13 @@ module YARD
       lexical_lookup = 0
       while namespace && !resolved
         resolved = lookup_path_direct(namespace, path, type)
+        # Prevent a bare name from resolving back to the namespace we started
+        # from when searching through a parent namespace. For example,
+        # `include Enumerable` inside `A::Enumerable` would walk up to namespace
+        # `A` and match `A::Enumerable`, creating a false self-referential mixin.
+        # Only skip when we have already moved to a parent (namespace != orignamespace).
+        # See https://github.com/lsegal/yard/issues/1116
+        resolved = nil if resolved.equal?(orignamespace) && !namespace.equal?(orignamespace)
         resolved ||= lookup_path_inherited(namespace, path, type) if inheritance
         break if resolved
         namespace = namespace.parent

data/lib/yard/rubygems/specification.rb

@@ -11,7 +11,7 @@ class Gem::Specification
     @has_rdoc == 'yard'
   end
 
-  undef has_rdoc?
+  undef has_rdoc? if method_defined?(:has_rdoc?)
   def has_rdoc?
     (@has_rdoc ||= true) && @has_rdoc != 'yard'
   end

data/lib/yard/server/library_version.rb

@@ -71,7 +71,7 @@ module YARD
     #     def load_yardoc_from_http
     #       Thread.new do
     #         # zip/unzip method implementations are not shown
-    #         download_zip_file("http://mysite.com/yardocs/#{self}.zip")
+    #         download_zip_file("https://mysite.com/yardocs/#{self}.zip")
     #         unzip_file_to("/path/to/yardocs/#{self}")
     #       end
     #