yard-lint 1.12.0 → 1.13.1

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module ReferenceTypo
+          # Parser for ReferenceTypo validator output
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses validator output and extracts reference typo violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ObjectName
+            #   reference|suggestion
+            # @param yard_output [String] raw validator output
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+
+              lines.each_slice(2).filter_map do |location_line, details_line|
+                next unless location_line && details_line
+
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                reference, suggestion = details_line.split('|', 2)
+                next if reference.to_s.empty? || suggestion.to_s.empty?
+
+                {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  reference: reference,
+                  suggestion: suggestion
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'did_you_mean'
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module ReferenceTypo
+          # Validates that references in documentation are not probable typos
+          class Validator < Base
+            # Same matching rules YARD uses for `{name}` / `{name title}` links
+            LINK_PATTERN = /(?<![\\!])\{(?!\})(\S+?)(?:\s[^}]*)?\}/
+
+            # Code spans, fenced and indented code blocks hold code, not links
+            CODE_PATTERN = /```.*?```|`[^`\n]*`|^(?: {4}|\t)[^\n]*/m
+
+            # `Foo::Bar#baz`, `Foo.baz` or a namespace-relative `#baz`
+            METHOD_REFERENCE = /\A(?<namespace>(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*)?(?<separator>[#.])(?<name>[A-Za-z_]\w*[?!=]?)\z/
+
+            # `Foo`, `Foo::Bar` or `::Foo::BAR`
+            CONSTANT_REFERENCE = /\A(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*\z/
+
+            in_process visibility: :all
+
+            # Execute query for a single object during in-process execution.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            def in_process_query(object, collector)
+              return if object.type == :method && object.is_alias?
+              return if module_function_copy?(object)
+              return if duplicate_docstring?(object)
+
+              references(object).uniq.each do |reference|
+                suggestion = suggest(object, reference)
+                next unless suggestion
+
+                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                collector.puts "#{reference}|#{suggestion}"
+              end
+            end
+
+            private
+
+            # @param object [YARD::CodeObjects::Base] documented object
+            # @return [Array<String>] link targets and `@see` names in its docs
+            def references(object)
+              overloads = object.tags(:overload)
+              tags = object.tags + overloads.flat_map { |overload| overload.docstring.tags }
+
+              texts = [object.docstring.to_s] + overloads.map { |overload| overload.docstring.to_s }
+              tags.each do |tag|
+                texts << tag.text.to_s unless tag.tag_name == 'example'
+              end
+
+              links = texts.flat_map do |text|
+                text.gsub(CODE_PATTERN, '').scan(LINK_PATTERN).map(&:first)
+              end
+
+              links + tags.select { |tag| tag.tag_name == 'see' }.map { |tag| tag.name.to_s }
+            end
+
+            # @param object [YARD::CodeObjects::Base] documented object
+            # @param reference [String] referenced name
+            # @return [String, nil] corrected reference for a probable typo
+            def suggest(object, reference)
+              if (match = METHOD_REFERENCE.match(reference))
+                return if resolve(object, reference)
+
+                suggest_method(object, match)
+              elsif CONSTANT_REFERENCE.match?(reference)
+                suggest_constant(object, reference)
+              end
+            end
+
+            # @param object [YARD::CodeObjects::Base] documented object
+            # @param match [MatchData] parts of a method reference
+            # @return [String, nil] corrected method reference
+            def suggest_method(object, match)
+              namespace_name = match[:namespace]
+              namespace = namespace_name ? resolve(object, namespace_name) : lexical_namespace(object)
+
+              unless namespace
+                suggestion = namespace_name && suggest_constant(object, namespace_name)
+
+                return suggestion && "#{suggestion}#{match[:separator]}#{match[:name]}"
+              end
+
+              return unless namespace.is_a?(YARD::CodeObjects::NamespaceObject)
+
+              scope = match[:separator] == '#' ? :instance : :class
+              return if external_method?(namespace, match[:name], scope)
+
+              candidates = namespace.meths(scope: scope).map { |meth| meth.name.to_s }
+              # YARD does not resolve a method found more than one namespace up
+              return if candidates.include?(match[:name])
+
+              suggestion = spell_check(match[:name], candidates)
+
+              suggestion && "#{namespace_name}#{match[:separator]}#{suggestion}"
+            end
+
+            # @param object [YARD::CodeObjects::Base] documented object
+            # @param reference [String] constant reference
+            # @return [String, nil] corrected constant reference
+            def suggest_constant(object, reference)
+              return if resolve(object, reference)
+              return if runtime_constant?(reference)
+
+              parent_name, _, name = reference.rpartition('::')
+
+              if parent_name.empty?
+                return if reference.start_with?('::')
+
+                candidates = visible_constants(lexical_namespace(object))
+              else
+                parent = resolve(object, parent_name)
+                return unless parent.is_a?(YARD::CodeObjects::NamespaceObject)
+
+                candidates = constant_names(parent)
+              end
+
+              suggestion = spell_check(name, candidates)
+              return unless suggestion
+
+              parent_name.empty? ? suggestion : "#{parent_name}::#{suggestion}"
+            end
+
+            # @param object [YARD::CodeObjects::Base] lookup context
+            # @param name [String] name to resolve
+            # @return [YARD::CodeObjects::Base, nil] resolved registry object
+            def resolve(object, name)
+              YARD::Registry.resolve(object, name, true)
+            end
+
+            # @param object [YARD::CodeObjects::Base] documented object
+            # @return [YARD::CodeObjects::Base, YARD::CodeObjects::Proxy] namespace links resolve against
+            def lexical_namespace(object)
+              object.is_a?(YARD::CodeObjects::NamespaceObject) ? object : object.namespace
+            end
+
+            # Root-level names are left out: a bare name near one of them is as
+            # likely a constant of a gem YARD did not parse as it is a typo
+            # @param namespace [YARD::CodeObjects::Base, YARD::CodeObjects::Proxy] innermost namespace
+            # @return [Array<String>] constant names visible from it
+            def visible_constants(namespace)
+              names = []
+
+              # `def CONST.name` and `class Unknown::Name` leave unresolved
+              # namespaces, which have no children to list
+              while namespace.is_a?(YARD::CodeObjects::NamespaceObject) && !namespace.root?
+                names.concat(constant_names(namespace))
+                namespace = namespace.namespace
+              end
+
+              names.uniq
+            end
+
+            # @param namespace [YARD::CodeObjects::NamespaceObject] namespace to list
+            # @return [Array<String>] names of its constants, classes and modules
+            def constant_names(namespace)
+              namespace.children.filter_map do |child|
+                child.name.to_s if %i[constant class module].include?(child.type)
+              end
+            end
+
+            # A method may come from an ancestor YARD does not know about, so it
+            # is checked against the loaded Ruby ancestors as well
+            # @param namespace [YARD::CodeObjects::NamespaceObject] referenced namespace
+            # @param name [String] referenced method name
+            # @param scope [Symbol] :instance or :class
+            # @return [Boolean] true when the method may exist outside the registry
+            def external_method?(namespace, name, scope)
+              ancestors = namespace.inheritance_tree(true).grep(YARD::CodeObjects::Proxy)
+              ancestors << YARD::CodeObjects::Proxy.new(:root, 'Object')
+              ancestors << YARD::CodeObjects::Proxy.new(:root, 'Class') if scope == :class
+
+              ancestors.any? do |proxy|
+                constant = runtime_constant(proxy.path)
+                # An ancestor that is not loaded here may define anything
+                next true unless constant.is_a?(Module)
+
+                constant.method_defined?(name) || constant.private_method_defined?(name)
+              end
+            end
+
+            # @param path [String] constant path
+            # @return [Boolean] true when the constant is defined in this Ruby process
+            def runtime_constant?(path)
+              !runtime_constant(path).nil?
+            end
+
+            # @param path [String] constant path
+            # @return [Object, nil] the constant's value, if it is loaded
+            def runtime_constant(path)
+              Object.const_get(path.delete_prefix('::'))
+            rescue NameError
+              nil
+            end
+
+            # @param name [String] misspelled name
+            # @param candidates [Array<String>] known names
+            # @return [String, nil] closest known name
+            def spell_check(name, candidates)
+              return if candidates.empty?
+
+              DidYouMean::SpellChecker.new(dictionary: candidates).correct(name).first
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # ReferenceTypo validator
+        #
+        # Detects probable typos in method and constant names referenced from
+        # documentation: `{Foo#bar}` links in docstring and tag text, and `@see`
+        # targets. A reference is reported only when it does not resolve in the
+        # YARD registry, its namespace does, and a close match exists there.
+        # References into namespaces YARD does not know (stdlib, other gems) are
+        # skipped, as are methods a loaded Ruby ancestor may define. A bare
+        # constant is compared only with constants of its enclosing namespaces,
+        # not with top-level ones. This validator is enabled by default.
+        #
+        # @example Bad - link to a misspelled method
+        #   # Delegates to {Parser#prase}
+        #   def call
+        #   end
+        #
+        # @example Good - link to an existing method
+        #   # Delegates to {Parser#parse}
+        #   def call
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/ReferenceTypo:
+        #       Enabled: false
+        module ReferenceTypo
+        end
+      end
+    end
+  end
+end

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

@@ -8,10 +8,15 @@ module Yard
         module UndocumentedBooleanMethods
           # Class used to extract details about undocumented boolean methods
           # @example Output format (skip-lint)
-          #   Platform::Analysis::Authors#valid?
+          #   lib/platform/analysis/authors.rb:12: Platform::Analysis::Authors#valid?
           class Parser < Parsers::Base
-            # Regex to extract location and method name from yard list output
-            LOCATION_REGEX = /^(.+)#(.+)$|^(.+)\.(.+)$/
+            # Regex to extract file, line and method title from the validator output
+            # Format: file.rb:LINE: Namespace#method?, Namespace.method?, or #method? and
+            # ::method? at the root
+            LINE_REGEX = /^(.+):(\d+): (.+)$/
+
+            # Method name: the last segment of the title
+            METHOD_NAME_REGEX = /[^#.:]+\z/
 
             # @param yard_list [String] raw yard list results string
             # @return [Array<Hash>] Array with undocumented boolean methods details
@@ -20,18 +25,14 @@ module Yard
                 .split("\n")
                 .reject(&:empty?)
                 .filter_map do |line|
-                  match_data = line.match(LOCATION_REGEX)
+                  match_data = line.match(LINE_REGEX)
                   next unless match_data
 
-                  # Handle both instance (#) and class (.) methods
-                  location = match_data[1] || match_data[3]
-                  method_name = match_data[2] || match_data[4]
-
                   {
-                    location: location,
-                    element: "#{location}##{method_name}",
-                    method_name: method_name,
-                    line: 0 # YARD list doesn't provide line numbers
+                    location: match_data[1],
+                    line: match_data[2].to_i,
+                    element: match_data[3],
+                    method_name: match_data[3][METHOD_NAME_REGEX]
                   }
                 end
             end

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

@@ -6,13 +6,22 @@ module Yard
       module Documentation
         module UndocumentedBooleanMethods
           # Runs a query that will pick all the boolean methods (ending with ?) that
-          # do not have a return type or return description documented
+          # do not have a return documented
           class Validator < Base
+            # A top-level tag line; indented lines belong to the tag above them
+            TAG_REGEX = /\A@(!?[\w.]+)/
+            # A macro use or definition, capturing the macro name
+            MACRO_REGEX = /\A@!?macro(?:\s+\[[^\]]*\])?\s+(\S+)/
+            # Macros may reference other macros; stop at this depth
+            MAX_MACRO_DEPTH = 5
+
+            private_constant :TAG_REGEX, :MACRO_REGEX, :MAX_MACRO_DEPTH
+
             # Enable in-process execution for this validator
             in_process visibility: :public
 
             # Execute query for a single object during in-process execution.
-            # Finds boolean methods (ending with ?) without @return tag or return types.
+            # Finds boolean methods (ending with ?) without a user-written @return tag.
             # @param object [YARD::CodeObjects::Base] the code object to query
             # @param collector [Executor::ResultCollector] collector for output
             # @return [void]
@@ -26,12 +35,82 @@ module Yard
               # Only check boolean methods (ending with ?)
               return unless object.name.to_s.end_with?('?')
 
-              # Check if @return tag is missing or has no types
-              return_tag = object.tag(:return)
-              return unless return_tag.nil? || return_tag.types.to_a.empty?
+              # A module_function pair is reported once, on its public class method
+              twin = module_function_twin(object)
+              return if twin && object.scope == :instance
+
+              # The copied half's raw text includes YARD's inferred `@return`
+              docstring = module_function_copy?(object) ? twin.docstring : object.docstring
+
+              # Undocumented methods are reported by UndocumentedObjects
+              return if docstring.all.empty?
+              # YARD adds `@return [Boolean]` to every `?` method without one, so the
+              # tags cannot tell; read the raw docstring instead
+              return if user_return?(docstring.all)
 
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
             end
+
+            private
+
+            # Tells if the raw docstring text has a `@return` written by the user: at the
+            # top level, inside an `@overload`, or carried by a macro. Text inside other
+            # tags (e.g. an `@example` body) never counts.
+            # @param text [String] raw docstring text
+            # @param depth [Integer] macro nesting depth
+            # @return [Boolean] true when a user-written `@return` is present
+            def user_return?(text, depth = 0)
+              tag_blocks(text).any? do |line, body|
+                case line[TAG_REGEX, 1]
+                when 'return'
+                  true
+                when 'overload'
+                  user_return?(dedent(body), depth)
+                when 'macro', '!macro'
+                  macro_return?(line, depth)
+                else
+                  false
+                end
+              end
+            end
+
+            # Tells if the macro named in the line carries a `@return`
+            # @param line [String] the `@macro` or `@!macro` line
+            # @param depth [Integer] macro nesting depth
+            # @return [Boolean] true when the macro text has a `@return` or the macro
+            #   is not in the registry
+            def macro_return?(line, depth)
+              return false if depth >= MAX_MACRO_DEPTH
+
+              name = line[MACRO_REGEX, 1]
+              macro = name && YARD::CodeObjects::MacroObject.find(name)
+              # Only the selected files are parsed, so a macro from another file is
+              # unknown here; count it as written to report the same in every run
+              return true unless macro
+
+              user_return?(macro.macro_data.to_s, depth + 1)
+            end
+
+            # Splits the text into top-level tag lines and the indented lines below them
+            # @param text [String] raw docstring text
+            # @return [Array<Array(String, Array<String>)>] tag line and body lines
+            def tag_blocks(text)
+              text.lines.map(&:chomp).each_with_object([]) do |line, blocks|
+                if line.match?(TAG_REGEX)
+                  blocks << [line, []]
+                elsif blocks.any? && (line.start_with?(/\s/) || line.empty?)
+                  blocks.last.last << line
+                end
+              end
+            end
+
+            # Removes the common leading whitespace from the lines
+            # @param lines [Array<String>] lines to dedent
+            # @return [String] dedented text
+            def dedent(lines)
+              indent = lines.reject { |l| l.strip.empty? }.map { |l| l[/\A\s*/].size }.min || 0
+              lines.map { |l| l[indent..] || '' }.join("\n")
+            end
           end
         end
       end

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

@@ -6,9 +6,13 @@ module Yard
       module Documentation
         # UndocumentedBooleanMethods validator
         #
-        # Ensures that boolean methods (methods ending with `?`) have an explicit
-        # `@return [Boolean]` tag. Boolean methods should clearly document that they
-        # return true or false values. This validator is enabled by default.
+        # Ensures that documented boolean methods (methods ending with `?`) have an
+        # explicit `@return` tag, at the top level or inside an `@overload`. Boolean
+        # methods should clearly document that they return true or false values.
+        # YARD adds `@return [Boolean]` to such methods on its own, so this validator
+        # reads the tags written in the comment. Methods without any documentation
+        # are reported by `Documentation/UndocumentedObjects`. This validator is
+        # enabled by default.
         #
         # @example Bad - Missing @return tag on boolean method
         #   # Checks if the user is active
@@ -23,6 +27,15 @@ module Yard
         #     @active
         #   end
         #
+        # @example Good - Boolean return documented inside @overload
+        #   # Checks if the user is active
+        #   # @overload active?(strict)
+        #   #   @param strict [Boolean] whether to require a confirmed account
+        #   #   @return [Boolean] true if the user is active
+        #   def active?(strict)
+        #     @active
+        #   end
+        #
         # ## Configuration
         #
         # To disable this validator:

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

@@ -37,8 +37,9 @@ module Yard
               # does not need option tags.
               return if options_param_documented_as_non_hash?(object)
 
-              # Check if @option tags are missing
-              option_tags = object.tags(:option)
+              # Check if @option tags are missing; tags nested inside overload
+              # blocks live on the overload's own docstring, so check those too
+              option_tags = all_typed_tags(object.docstring, %w[option])
               return unless option_tags.empty?
 
               # Output method location and parameter info

data/lib/yard/lint/validators/tags/example_style/validator.rb

@@ -16,14 +16,14 @@ module Yard
             # @param collector [Executor::ResultCollector] collector for output
             # @return [void]
             def in_process_query(object, collector)
-              return unless object.has_tag?(:example)
+              # Tags nested inside overload blocks live on the overload's own
+              # docstring, so check those too
+              example_tags = all_typed_tags(object.docstring, %w[example])
+              return if example_tags.empty?
 
               # Get or initialize runner (memoized for performance)
               return unless runner
 
-              # Process each example
-              example_tags = object.tags(:example)
-
               example_tags.each_with_index do |example, index|
                 code = example.text
                 next if code.nil? || code.empty?

data/lib/yard/lint/validators/tags/example_syntax/validator.rb

@@ -16,10 +16,12 @@ module Yard
             # @param collector [Executor::ResultCollector] collector for output
             # @return [void]
             def in_process_query(object, collector)
-              return unless object.has_tag?(:example)
+              # Tags nested inside overload blocks live on the overload's own
+              # docstring, so check those too
+              example_tags = all_typed_tags(object.docstring, %w[example])
+              return if example_tags.empty?
 
               skip_non_ruby = config_or_default('SkipNonRuby')
-              example_tags = object.tags(:example)
 
               example_tags.each_with_index do |example, index|
                 code = example.text

data/lib/yard/lint/validators/tags/invalid_types/messages_builder.rb

@@ -15,10 +15,9 @@ module Yard
                 violations = offense[:tag_violations]
 
                 if violations&.any?
-                  details = violations.map do |v|
-                    label = v[:param] ? "#{v[:tag]} #{v[:param]}" : v[:tag]
-                    types = v[:types].map { |t| "`#{t}`" }.join(', ')
-                    "#{label}: #{types}"
+                  details = violations.group_by { |v| v[:param] ? "#{v[:tag]} #{v[:param]}" : v[:tag] }
+                                      .map do |label, entries|
+                    "#{label}: #{entries.map { |v| describe_types(v) }.join(', ')}"
                   end.join('; ')
 
                   "The `#{offense[:method_name]}` has invalid type(s): #{details}"
@@ -26,6 +25,18 @@ module Yard
                   "The `#{offense[:method_name]}` has at least one tag with an invalid type definition."
                 end
               end
+
+              private
+
+              # @param violation [Hash] entry with :types (invalid names) and :type_string (full type, may be nil)
+              # @return [String] the invalid names, plus the full type when it differs from them
+              def describe_types(violation)
+                names = violation[:types].map { |t| "`#{t}`" }.join(', ')
+                type_string = violation[:type_string]
+                return names if type_string.nil? || violation[:types] == [type_string]
+
+                "#{names} in `#{type_string}`"
+              end
             end
           end
         end

data/lib/yard/lint/validators/tags/invalid_types/parser.rb

@@ -8,7 +8,9 @@ module Yard
           # Parser for invalid tag types output.
           # The validator emits two lines per offense:
           #   /path/to/file.rb:10: ClassName#method_name
-          #   @tagname param_name:BadType1,BadType2|@tagname2:BadType3
+          #   @tagname param_name:BadType1,BadType2:Type|@tagname2:BadType3:Type2
+          # One entry per type with invalid names. '%', '|', ',', ':' and newlines
+          # inside tags, params, names and types are escaped as %25, %7C, %2C, %3A and %0A
           class Parser < Parsers::Base
             # @return [Regexp] matches "file:line: ObjectTitle"
             LOCATION_REGEX = /^(.+):(\d+):\s+(.+)$/
@@ -71,20 +73,29 @@ module Yard
               match ? [match[1], match[2]] : [title, title]
             end
 
-            # Parse "tagname param:Type1,Type2|tagname2:Type3" into structured data
+            # Parse "tagname param:Bad1,Bad2:Type|tagname2:Bad3:Type2" into structured data
             # @param line [String] the violations line
             # @return [Array<Hash>] each entry has :tag, :param (may be nil), :types
+            #   (the invalid names) and :type_string (the full type, may be nil)
             def parse_tag_violations(line)
               line.split('|').map do |entry|
-                label, types_str = entry.split(':', 2)
-                parts = label.split(' ', 2)
+                label, types_str, type_string = entry.split(':', 3)
+                tag, param = label.split(' ', 2)
                 {
-                  tag: parts[0],
-                  param: parts[1],
-                  types: (types_str || '').split(',').reject(&:empty?)
+                  tag: unescape_field(tag),
+                  param: param && unescape_field(param),
+                  types: (types_str || '').split(',').reject(&:empty?).map { |name| unescape_field(name) },
+                  type_string: type_string && unescape_field(type_string)
                 }
               end
             end
+
+            # Reverts the validator's escaping
+            # @param text [String] escaped field text
+            # @return [String] raw field text
+            def unescape_field(text)
+              text.gsub(/%(?:25|7C|2C|3A|0A)/, '%25' => '%', '%7C' => '|', '%2C' => ',', '%3A' => ':', '%0A' => "\n")
+            end
           end
         end
       end