yard 0.9.36 → 0.9.40

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/ast_node.rb

@@ -271,7 +271,7 @@ module YARD
 
         # @return [Fixnum] the starting line number of the node
         def line
-          line_range && line_range.first
+          line_range && (line_range.begin || line_range.end)
         end
 
         # @return [String] the first line of source represented by the node.
@@ -345,8 +345,8 @@ module YARD
           elsif !children.empty?
             f = children.first
             l = children.last
-            self.line_range = Range.new(f.line_range.first, l.line_range.last)
-            self.source_range = Range.new(f.source_range.first, l.source_range.last)
+            self.line_range = Range.new(f.line_range.begin, l.line_range.end)
+            self.source_range = Range.new(f.source_range.begin, l.source_range.end)
           elsif @fallback_line || @fallback_source
             self.line_range = @fallback_line
             self.source_range = @fallback_source
@@ -431,7 +431,8 @@ module YARD
           # shape is (required, optional, rest, more, keyword, keyword_rest, block)
           # Ruby 3.1 moves :args_forward from rest to keyword_rest
           args_index = YARD.ruby31? ? -2 : 2
-          self[args_index].type == :args_forward if self[args_index]
+          node = self[args_index]
+          node.is_a?(AstNode) && node.type == :args_forward
         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/legacy/ruby_lex.rb

@@ -656,7 +656,7 @@ module YARD
           if @lex_state != EXPR_END && @lex_state != EXPR_CLASS &&
              (@lex_state != EXPR_ARG || @space_seen)
             c = peek(0)
-            tk = identify_here_document if /[-\w\"\'\`]/ =~ c
+            tk = identify_here_document if /[-~\w\"\'\`]/ =~ c
           end
           if !tk
             @lex_state = EXPR_BEG
@@ -978,7 +978,7 @@ module YARD
       end
 
       def identify_identifier
-        token = ""
+        token = String.new
         token.concat getc if peek(0) =~ /[$@]/
         token.concat getc if peek(0) == "@"
 
@@ -1063,6 +1063,8 @@ module YARD
         ch = getc
         if ch == "-"
           ch = getc
+        elsif ch == "~"
+          ch = getc
           indent = true
         end
         if /['"`]/ =~ ch # '
@@ -1096,9 +1098,12 @@ module YARD
         str = String.new
         while (l = gets)
           l.chomp!
-          l.strip! if indent
-          break if l == quoted
-          str << l.chomp << "\n"
+          if l == quoted
+            str = dedent(str) if indent
+            break
+          else
+            str << l.chomp << "\n"
+          end
         end
 
         @reader.divert_read_from(reserve)
@@ -1108,6 +1113,16 @@ module YARD
         Token(Ltype2Token[lt], str).set_text(str.dump)
       end
 
+      def dedent(str)
+        lines = str.split("\n", -1)
+        dedent_amt = lines.map do |line|
+          line =~ /\S/ ? line.match(/^ */).offset(0)[1] : nil
+        end.compact.min || 0
+        return str if dedent_amt.zero?
+
+        lines.map { |line| line =~ /\S/ ? line.gsub(/^ {#{dedent_amt}}/, "") : line }.join("\n")
+      end
+
       def identify_quotation(initial_char)
         ch = getc
         if lt = PERCENT_LTYPE[ch]

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

@@ -236,14 +236,26 @@ module YARD
 
         def visit_event(node)
           map = @map[MAPPINGS[node.type]]
-          lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
+
+          # Pattern matching and `in` syntax creates :case nodes without 'case' tokens,
+          # fall back to the first child node.
+          if node.type == :case && (!map || map.empty?) && (child_node = node[0])
+            lstart = child_node.line_range.first
+            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?
+
           node.source_range = Range.new(sstart, @ns_charno - 1)
           node.line_range = Range.new(lstart, lineno)
           if node.respond_to?(:block)
             sr = node.block.source_range
             lr = node.block.line_range
-            node.block.source_range = Range.new(sr.first, @tokens.last[2][1] - 1)
-            node.block.line_range = Range.new(lr.first, @tokens.last[2][0])
+            node.block.source_range = Range.new(sr.begin, @tokens.last[2][1] - 1)
+            node.block.line_range = Range.new(lr.begin, @tokens.last[2][0])
           end
           node
         end
@@ -259,7 +271,10 @@ module YARD
         def visit_ns_token(token, data, ast_token = false)
           add_token(token, data)
           ch = charno
-          @last_ns_token = [token, data]
+
+          # For purposes of tracking parsing state, don't treat keywords as such
+          # where used as a symbol identifier.
+          @last_ns_token = [@last_ns_token && @last_ns_token.first == :symbeg ? :symbol : token, data]
           @charno += data.length
           @ns_charno = charno
           @newline = [:semicolon, :comment, :kw, :op, :lparen, :lbrace].include?(token)
@@ -272,14 +287,14 @@ module YARD
           if @percent_ary
             if token == :words_sep && data !~ /\s\z/
               rng = @percent_ary.source_range
-              rng = Range.new(rng.first, rng.last + data.length)
+              rng = Range.new(rng.begin, rng.end.to_i + data.length)
               @percent_ary.source_range = rng
               @tokens << [token, data, [lineno, charno]]
               @percent_ary = nil
               return
             elsif token == :tstring_end && data =~ /\A\s/
               rng = @percent_ary.source_range
-              rng = Range.new(rng.first, rng.last + data.length)
+              rng = Range.new(rng.begin, rng.end.to_i + data.length)
               @percent_ary.source_range = rng
               @tokens << [token, data, [lineno, charno]]
               @percent_ary = nil
@@ -294,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
@@ -322,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
@@ -357,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
@@ -377,20 +407,22 @@ module YARD
         def on_aref(*args)
           @map[:lbracket].pop
           ll, lc = *@map[:aref].shift
-          sr = args.first.source_range.first..lc
-          lr = args.first.line_range.first..ll
+          sr = args.first.source_range.begin..lc
+          lr = args.first.line_range.begin..ll
           AstNode.new(:aref, args, :char => sr, :line => lr)
         end
 
         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)
           node = AstNode.node_class_for(:array).new(:array, [other])
-          map = @map[MAPPINGS[node.type]]
+          map = @map[MAPPINGS[node.type]] if other.nil? || other.type == :list
           if map && !map.empty?
             lstart, sstart = *map.pop
             node.source_range = Range.new(sstart, @ns_charno - 1)
@@ -406,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)
@@ -416,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
@@ -449,8 +509,8 @@ module YARD
             def on_#{kw}(*args)
               mapping = @map[#{kw.to_s.sub(/_mod$/, '').inspect}]
               mapping.pop if mapping
-              sr = args.last.source_range.first..args.first.source_range.last
-              lr = args.last.line_range.first..args.first.line_range.last
+              sr = args.last.source_range.begin..args.first.source_range.end
+              lr = args.last.line_range.begin..args.first.line_range.end
               #{node_class}.new(:#{kw}, args, :line => lr, :char => sr)
             end
           eof
@@ -473,8 +533,8 @@ module YARD
             begin; undef on_#{kw}_add; rescue NameError; end
             def on_#{kw}_add(list, item)
               last = @source[@ns_charno,1] == "\n" ? @ns_charno - 1 : @ns_charno
-              list.source_range = (list.source_range.first..last)
-              list.line_range = (list.line_range.first..lineno)
+              list.source_range = (list.source_range.begin..last)
+              list.line_range = (list.line_range.begin..lineno)
               list.push(item)
               list
             end
@@ -485,9 +545,9 @@ module YARD
           node = visit_event_arr(LiteralNode.new(:string_literal, args))
           if args.size == 1
             r = args[0].source_range
-            if node.source_range != Range.new(r.first - 1, r.last + 1)
+            if node.source_range != Range.new(r.begin - 1, r.end + 1)
               klass = AstNode.node_class_for(node[0].type)
-              r = Range.new(node.source_range.first + 1, node.source_range.last - 1)
+              r = Range.new(node.source_range.begin + 1, node.source_range.end - 1)
               node[0] = klass.new(node[0].type, [@source[r]], :line => node.line_range, :char => r)
             end
           end
@@ -573,7 +633,7 @@ module YARD
             @comments_flags[lineno] = @comments_flags[lineno - 1]
             @comments_flags.delete(lineno - 1)
             range = @comments_range.delete(lineno - 1)
-            source_range = range.first..source_range.last
+            source_range = range.begin..source_range.end
             comment = append_comment + "\n" + comment
           end
 
@@ -609,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"
@@ -627,11 +688,13 @@ module YARD
             end
 
             # check upwards from line before node; check node's line at the end
-            ((node.line - 1).downto(node.line - 2).to_a + [node.line]).each do |line|
-              comment = @comments[line]
-              if comment && !comment.empty?
-                add_comment(line, node)
-                break
+            if (n_l = node.line)
+              ((n_l - 1).downto(n_l - 2).to_a + [n_l]).each do |line|
+                comment = @comments[line]
+                if comment && !comment.empty?
+                  add_comment(line, node)
+                  break
+                end
               end
             end
 
@@ -656,6 +719,23 @@ module YARD
             end
           end unless @comments.empty?
 
+          # Attach comments that fall within an otherwise empty
+          # class or module body. Without this step, a comment used
+          # solely for directives (like @!method) would be treated as
+          # a top-level comment and its directives would not be scoped
+          # to the namespace.
+          unless @comments.empty?
+            root.traverse do |node|
+              next unless [:class, :module, :sclass].include?(node.type)
+              body = node.children.last
+              next unless body && body.type == :list && body.empty?
+              @comments.keys.each do |line|
+                next unless node.line_range.include?(line)
+                add_comment(line, nil, body, true)
+              end
+            end
+          end
+
           # insert all remaining comments
           @comments.each do |line, _comment|
             add_comment(line, nil, root, true)
@@ -667,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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 require 'stringio'
-require 'ostruct'
 
 module YARD
   module Parser
@@ -68,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
@@ -106,9 +105,10 @@ 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 } }
+            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) }
 
           log.enter_level(level) do
             parse_in_order(*files.uniq)
@@ -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
     #