yard-lint 1.6.1 → 1.8.0

data/lib/yard/lint/validators/documentation/markdown_syntax/validator.rb

@@ -18,26 +18,30 @@ module Yard
             def in_process_query(object, collector)
               docstring_text = object.docstring.to_s
               return if docstring_text.empty?
+              return if duplicate_docstring?(object)
 
               errors = []
 
-              # Check for unclosed backticks
-              backtick_count = docstring_text.scan(/`/).count
-              errors << 'unclosed_backtick' if backtick_count.odd?
+              # Check for unclosed inline backticks, ignoring fenced code blocks
+              # (``` ... ```): their fence characters and contents are not
+              # inline-code markers and otherwise inflate the count.
+              errors << 'unclosed_backtick' if inline_backtick_count(docstring_text).odd?
 
               # Check for unclosed code blocks
               code_block_count = docstring_text.scan(/^```/).count
               errors << 'unclosed_code_block' if code_block_count.odd?
 
-              # Check for unclosed bold markers (excluding code sections)
-              non_code_text = docstring_text.gsub(/`[^`]*`/, '')
-              bold_count = non_code_text.scan(/\*\*/).count
-              errors << 'unclosed_bold' if bold_count.odd?
+              # Check for unclosed bold markers, ignoring fenced code blocks and
+              # inline code spans (their contents are code, not markdown) as well
+              # as `**` runs surrounded by whitespace, which cannot delimit
+              # CommonMark emphasis (e.g. the exponent operator in `x ** y`).
+              errors << 'unclosed_bold' if bold_marker_count(docstring_text).odd?
 
-              # Check for invalid list markers
+              # Check for invalid list markers, reported with their absolute
+              # source line rather than a docstring-relative index
               docstring_text.lines.each_with_index do |line, line_idx|
                 stripped = line.strip
-                errors << "invalid_list_marker:#{line_idx + 1}" if stripped.match?(/^[•·]/)
+                errors << "invalid_list_marker:#{docstring_line(object, line_idx)}" if stripped.match?(/^[•·]/)
               end
 
               return if errors.empty?
@@ -45,6 +49,59 @@ module Yard
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
               collector.puts errors.join('|')
             end
+
+            private
+
+            # Counts inline backticks, skipping fenced code blocks (``` ... ```)
+            # entirely - their fence characters and contents are not inline-code
+            # markers.
+            # @param text [String] the docstring text
+            # @return [Integer] number of inline backticks outside fenced blocks
+            def inline_backtick_count(text)
+              in_fence = false
+              count = 0
+              text.each_line do |line|
+                if line.strip.start_with?('```')
+                  in_fence = !in_fence
+                  next
+                end
+                next if in_fence
+
+                count += line.count('`')
+              end
+              count
+            end
+
+            # Counts `**` emphasis markers, skipping fenced code blocks and
+            # inline code spans entirely. A `**` run is only counted when it
+            # abuts a non-whitespace character on at least one side, since a run
+            # padded by whitespace on both sides can neither open nor close
+            # CommonMark emphasis - this excludes the exponent operator (`x ** y`)
+            # without dropping genuine `**bold**` markers.
+            # @param text [String] the docstring text
+            # @return [Integer] number of bold markers that can delimit emphasis
+            def bold_marker_count(text)
+              in_fence = false
+              count = 0
+              text.each_line do |line|
+                if line.strip.start_with?('```')
+                  in_fence = !in_fence
+                  next
+                end
+                next if in_fence
+
+                non_code = line.gsub(/`[^`]*`/, '')
+                non_code.scan(/\*\*/) do
+                  match = Regexp.last_match
+                  # Peek at the surrounding characters without consuming them, so
+                  # adjacent runs like `**a**` (single-character bold) still pair up.
+                  before = match.pre_match[-1]
+                  after = match.post_match[0]
+                  count += 1 if before&.match?(/\S/) || after&.match?(/\S/)
+                end
+              end
+              count
+            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/missing_return/validator.rb

@@ -23,9 +23,9 @@ module Yard
               return unless object.is_explicit?
               return if parent_class_allowed?(object)
 
-              # Check if @return tag is missing
-              return_tag = object.tag(:return)
-              return unless return_tag.nil?
+              # Check if @return tag is missing; tags nested inside @overload
+              # blocks live on the overload's own docstring, so check those too
+              return unless all_typed_tags(object.docstring, %w[return]).empty?
 
               # Calculate arity (exclude splat and block parameters)
               arity = object.parameters.reject { |p| p[0].to_s.start_with?('*', '&') }.size

data/lib/yard/lint/validators/documentation/orphaned_doc_comment/validator.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'ripper'
+require 'set'
+
 module Yard
   module Lint
     module Validators
@@ -31,6 +34,8 @@ module Yard
               (def |class |module |attr_reader|attr_writer|attr_accessor|attr_internal|attr\b|alias_method\b|alias\b|define_method\b)
               |
               \A\s*[A-Z][A-Za-z0-9_:]*\s*=
+              |
+              \A\s*\w+\s+def\b
             /x.freeze
 
             # Matches a DSL-style method call whose first argument is a symbol or string literal
@@ -38,7 +43,13 @@ module Yard
             # YARD's DSL handler turns such a call into a documentable method object when the
             # preceding comment carries an implicit-docstring tag, so a doc comment in front of
             # one of these is NOT orphaned.
-            DSL_CALL_PATTERN = /\A\s*(?<method>[a-z_]\w*[!?]?)(?:\s+|\s*\(\s*)(?::\w|:["']|["'])/.freeze
+            DSL_CALL_PATTERN = %r{\A\s*(?:[A-Za-z_][\w:]*\.)?(?<method>[a-z_]\w*[!?]?)(?:\s+|\s*\(\s*)(?::\w|:["']|["'])}.freeze
+            # Matches a plain method call (optionally with a receiver), used when
+            # the comment carries a @method/@attribute tag that names the object
+            # YARD creates - then the call's argument shape does not matter.
+            METHOD_CALL_PATTERN = /\A\s*(?:[A-Za-z_][\w:]*\.)?[a-z_]\w*[!?]?(?:[\s(]|\z)/.freeze
+            # Matches a @method/@attribute tag that names a created object.
+            NAMED_OBJECT_TAG_PATTERN = /\A\s*#\s*@(?:method|attribute)\s+\S/.freeze
             # Mirror of YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS - calls to these
             # are skipped by YARD's DSL handler, so a preceding doc comment really is dropped.
             # (The `attr*`/`alias*` entries are already covered by DEFINITION_PATTERN.)
@@ -74,19 +85,26 @@ module Yard
             # @param collector [Executor::ResultCollector] collector for output lines
             # @return [void]
             def scan_file(file, collector)
-              lines = File.readlines(file, chomp: true)
+              source = File.read(file)
+              lines = source.lines.map(&:chomp)
+              # Line indices (0-based) that hold a real, full-line Ruby comment.
+              # Derived from the lexer so that '#'-leading lines inside heredocs
+              # and string literals are not mistaken for documentation comments.
+              comment_lines = full_line_comment_indices(source, lines)
               i = 0
 
               while i < lines.length
-                if comment_line?(lines[i])
+                if comment_line?(lines[i], i, comment_lines)
                   block_start = i
                   tags = []
 
                   has_directive = false
                   has_implicit_tag = false
-                  while i < lines.length && comment_line?(lines[i])
+                  has_named_object_tag = false
+                  while i < lines.length && comment_line?(lines[i], i, comment_lines)
                     has_directive = true if directive_line?(lines[i])
                     has_implicit_tag = true if implicit_docstring_tag?(lines[i])
+                    has_named_object_tag = true if lines[i].match?(NAMED_OBJECT_TAG_PATTERN)
                     tag = extract_yard_tag(lines[i])
                     tags << tag if tag
                     i += 1
@@ -99,7 +117,7 @@ module Yard
                   # Skip trailing blank lines after the comment block
                   i += 1 while i < lines.length && lines[i].strip.empty?
 
-                  unless documentable?(lines[i], has_implicit_tag)
+                  unless documentable?(lines[i], has_implicit_tag, has_named_object_tag)
                     collector.puts "#{file}:#{block_start + 1}: #{tags.uniq.join(',')}"
                   end
                 else
@@ -108,17 +126,60 @@ module Yard
               end
             end
 
+            # Lex the source and collect the 0-based indices of lines whose first
+            # non-whitespace content is a Ruby comment. Heredoc bodies and string
+            # literals lex as content tokens (not `:on_comment`), so their
+            # `#`-leading lines are excluded - fixing the false positives where
+            # tag-looking text inside a heredoc was treated as a doc comment.
+            # @param source [String] the full file source
+            # @param lines [Array<String>] the source split into chomped lines
+            # @return [Set<Integer>] 0-based indices of full-line comments
+            def full_line_comment_indices(source, lines)
+              indices = Set.new
+              ::Ripper.lex(source).each do |(position, type, _token, _state)|
+                next unless type == :on_comment
+
+                line_no, column = position
+                index = line_no - 1
+                current = lines[index]
+                next unless current
+
+                # Only a full-line comment (nothing but whitespace before the '#').
+                indices << index if current[0...column].to_s.strip.empty?
+              end
+              indices
+            rescue StandardError
+              # If the source cannot be lexed, fall back to the previous regex
+              # behaviour so a single unparseable file does not lose detection.
+              fallback = Set.new
+              lines.each_with_index do |line, index|
+                fallback << index if line.strip.start_with?('#')
+              end
+              fallback
+            end
+
             # @param line [String] a raw source line
+            # @param index [Integer] 0-based line index
+            # @param comment_lines [Set<Integer>] indices of real full-line comments
             # @return [Boolean] true if the line is a Ruby comment (excluding magic comments)
-            def comment_line?(line)
-              stripped = line.strip
-              stripped.start_with?('#') && !magic_comment?(stripped)
+            def comment_line?(line, index, comment_lines)
+              return false unless comment_lines.include?(index)
+
+              !magic_comment?(line.strip)
             end
 
             # @param stripped_line [String] a comment line with leading/trailing whitespace removed
             # @return [Boolean] true if the line is a Ruby magic comment (frozen_string_literal, encoding, etc.)
             def magic_comment?(stripped_line)
-              stripped_line.match?(/\A#\s*(frozen[_-]string[_-]literal|encoding|warn[_-]indent|shareable[_-]constant[_-]value)\s*:/i)
+              # A real magic comment has a single-token value (e.g. `true`,
+              # `utf-8`), optionally followed by `;` (combined directives) or an
+              # emacs `-*-` wrapper. Requiring that avoids treating prose that
+              # merely starts with a magic-comment word - like
+              # `# encoding: UTF-8 is assumed for all inputs` - as a magic
+              # comment, which would split a documentation block.
+              stripped_line.match?(
+                /\A#\s*(?:-\*-\s*)?(frozen[_-]string[_-]literal|encoding|warn[_-]indent|shareable[_-]constant[_-]value)\s*:\s*\S+\s*(?:;|-\*-|\z)/i
+              )
             end
 
             # @param line [String] a raw source line
@@ -137,11 +198,18 @@ module Yard
             # @param line [String, nil] the source line following the comment block, or nil at EOF
             # @param has_implicit_tag [Boolean] whether the comment block carries a tag that makes
             #   YARD's DSL handler emit a method object (see IMPLICIT_DOCSTRING_TAG_PATTERN)
+            # @param has_named_object_tag [Boolean] whether the comment block carries a
+            #   @method/@attribute tag naming the object YARD creates, so any following
+            #   method call attaches the docstring regardless of its arguments
             # @return [Boolean] true if YARD will attach the comment to a documentable construct
-            def documentable?(line, has_implicit_tag)
+            def documentable?(line, has_implicit_tag, has_named_object_tag = false)
               return false if line.nil?
 
-              definition_line?(line) || (has_implicit_tag && dsl_method_line?(line))
+              definition_line?(line) ||
+                (has_implicit_tag && dsl_method_line?(line)) ||
+                # A @method/@attribute tag names the object YARD creates, so any
+                # following method call (regardless of its arguments) attaches it.
+                (has_named_object_tag && line.match?(METHOD_CALL_PATTERN))
             end
 
             # @param line [String] a raw source line

data/lib/yard/lint/validators/documentation/orphaned_doc_comment.rb

@@ -15,10 +15,6 @@ module Yard
         # non-documentable statement (variable assignment, `require`, `include`, etc.)
         # or sits at the end of a file.
         #
-        # @note This validator is complementary to `Documentation/BlankLineBeforeDefinition`,
-        #   which catches doc blocks separated from a `def` by blank lines.
-        #   `OrphanedDocComment` catches doc blocks that lead to non-definition code entirely.
-        #
         # @example Bad - comment before variable assignment
         #   # @param name [String] the name
         #   # @return [void]
@@ -39,6 +35,10 @@ module Yard
         #   def process(name)
         #   end
         #
+        # @note This validator is complementary to `Documentation/BlankLineBeforeDefinition`,
+        #   which catches doc blocks separated from a `def` by blank lines.
+        #   `OrphanedDocComment` catches doc blocks that lead to non-definition code entirely.
+        #
         # ## Configuration
         #
         # To disable this validator:

data/lib/yard/lint/validators/documentation/text_substitution/validator.rb

@@ -16,6 +16,7 @@ module Yard
             def in_process_query(object, collector)
               docstring_text = object.docstring.to_s
               return if docstring_text.empty?
+              return if duplicate_docstring?(object)
 
               substitutions = config_or_default('Substitutions')
               return if substitutions.nil? || substitutions.empty?
@@ -24,7 +25,8 @@ module Yard
               return if violations.empty?
 
               violations.each do |violation|
-                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                line = docstring_line(object, violation[:line_offset])
+                collector.puts "#{object.file}:#{line}: #{object.title}"
                 collector.puts violation[:forbidden]
                 collector.puts violation[:replacement]
                 collector.puts "#{violation[:line_offset]}|#{violation[:line_text]}"
@@ -48,10 +50,16 @@ module Yard
                 end
                 next if in_code_block
 
+                # Match against the line with inline code spans (`...`) removed,
+                # so a forbidden string that only appears inside code is not
+                # flagged - it is literal code, not prose to be substituted. The
+                # reported line_text remains the original line.
+                scannable = line.gsub(/`[^`]*`/, '')
+
                 substitutions.each do |forbidden, replacement|
                   next if forbidden.nil? || forbidden.empty?
                   next if replacement.nil? || replacement.empty?
-                  next unless line.include?(forbidden)
+                  next unless scannable.include?(forbidden)
 
                   violations << {
                     forbidden: forbidden,

data/lib/yard/lint/validators/documentation/underfilled_lines/config.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Configuration for UnderfilledLines validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :underfilled_lines
+            self.defaults = {
+              'Enabled' => false,
+              'Severity' => 'convention',
+              # Target width. Re-wrapping prose at this width must save a line for an
+              # offense to be reported. Mirror your Documentation/LineLength MaxLength.
+              'MaxLength' => 120,
+              # Only flag when the widest non-final line of the paragraph leaves at
+              # least this many unused columns - avoids nitpicking near-full prose.
+              'MinTrailingSpace' => 20,
+              # Paragraphs shorter than this are never flagged (a single line cannot
+              # be "under-filled" - there is nothing to pull up onto it).
+              'MinParagraphLines' => 2,
+              # A non-final prose line ending in one of these characters is treated as
+              # a deliberate sentence/clause break, and its paragraph is left alone.
+              # Add ',' to also respect comma breaks (suppresses more, catches less).
+              'SentenceEndChars' => ['.', '?', '!', ':', ';'],
+              # Skip paragraphs containing non-ASCII text: String#length is not a
+              # reliable display width for CJK/full-width/emoji content.
+              'SkipNonAscii' => true
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines/messages_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Builds human-readable messages for UnderfilledLines violations.
+          class MessagesBuilder
+            class << self
+              # @param offense [Hash] offense details with :actual_lines, :reflowed_lines,
+              #   :widest_fill, :max_length and :object_name
+              # @return [String] formatted message
+              def call(offense)
+                actual = offense[:actual_lines]
+                reflowed = offense[:reflowed_lines]
+                widest = offense[:widest_fill]
+                max_length = offense[:max_length]
+                object_name = offense[:object_name]
+
+                "Documentation paragraph uses #{actual} lines but fits in #{reflowed} " \
+                  "at <=#{max_length} cols [widest line filled to #{widest}/#{max_length}] " \
+                  "for '#{object_name}'"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines/parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Parses UnderfilledLines validator output into structured violation hashes.
+          #
+          # Expected format (two lines per object with violations):
+          #   file.rb:OBJECT_LINE: ObjectName
+          #   MAX_LENGTH|START:ACTUAL:REFLOW:WIDEST|START:ACTUAL:REFLOW:WIDEST|...
+          class Parser < Parsers::Base
+            # @param output [String] raw validator output
+            # @return [Array<Hash>] array of violation hashes
+            def call(output, **)
+              return [] if output.nil? || output.empty?
+
+              violations = []
+              lines = output.lines.map(&:chomp)
+
+              i = 0
+              while i < lines.size
+                location_match = lines[i].match(/^(.+):(\d+): (.+)$/)
+
+                if location_match
+                  file_path = location_match[1]
+                  object_line = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  i += 1
+                  if i < lines.size
+                    parts = lines[i].split('|')
+                    max_length = parts.shift.to_i
+
+                    parts.each do |part|
+                      start, actual, reflow, widest = part.split(':', 4)
+                      next unless start && actual && reflow && widest
+
+                      violations << {
+                        location: file_path,
+                        line: start.to_i,
+                        object_line: object_line,
+                        object_name: object_name,
+                        actual_lines: actual.to_i,
+                        reflowed_lines: reflow.to_i,
+                        widest_fill: widest.to_i,
+                        max_length: max_length
+                      }
+                    end
+                  end
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/underfilled_lines/result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UnderfilledLines
+          # Result wrapper for UnderfilledLines validator.
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'line'
+            self.offense_name = 'UnderfilledLines'
+
+            private
+
+            # @param offense [Hash] offense details from the parser
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end