yard-lint 1.6.1 → 1.7.0

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

@@ -29,12 +29,18 @@ module Yard
 
               object.docstring.tags.each do |tag|
                 next unless tags_to_check.include?(tag.tag_name)
-                next unless tag.name && tag.text && !tag.text.strip.empty?
 
-                param_name = tag.name
-                description = tag.text.strip.gsub(/\.$/, '')
+                # Option tags carry their description on the nested pair tag;
+                # the documented name is the option key (e.g. ":mode"), not the
+                # hash parameter name
+                data = tag_data(tag)
+                param_name = data.equal?(tag) ? tag.name : data.name.to_s.sub(/\A:/, '')
+                next if param_name.nil? || param_name.empty?
+                next unless data.text && !data.text.strip.empty?
+
+                description = data.text.strip.gsub(/\.$/, '')
                 word_count = description.split.length
-                type_name = tag.types&.first&.gsub(/[<>{}\[\],]/, '')&.strip
+                type_name = data.types&.first&.gsub(/[<>{}\[\],]/, '')&.strip
 
                 next if word_count > max_words
 
@@ -46,7 +52,7 @@ module Yard
                 next unless pattern_type
 
                 collector.puts "#{object.file}:#{object.line}: #{object.title}"
-                collector.puts "#{tag.tag_name}|#{param_name}|#{tag.text.strip}|#{type_name || ''}|#{pattern_type}|#{word_count}"
+                collector.puts "#{tag.tag_name}|#{param_name}|#{data.text.strip}|#{type_name || ''}|#{pattern_type}|#{word_count}"
               end
             end
             # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
@@ -68,7 +74,9 @@ module Yard
             # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
             def detect_pattern(param_name, description, type_name, word_count, articles, generic_terms, connectors, low_value_verbs, patterns)
               desc_parts = description.split
-              articles_re = /^(#{articles.join('|')})/i
+              # Anchored on both ends: only a whole-word article counts, not
+              # any word that merely starts with one (authenticated, theme)
+              articles_re = /\A(#{articles.map { |a| Regexp.escape(a) }.join('|')})\z/i
 
               # ArticleParam pattern
               if patterns['ArticleParam'] && word_count <= 3 && desc_parts.length == 2
@@ -97,9 +105,14 @@ module Yard
                 end
               end
 
-              # ParamToVerb pattern
+              # ParamToVerb pattern: "<param> to <low-value verb>" (e.g.
+              # "user to update"). The third word must actually be a low-value
+              # verb, otherwise meaningful noun phrases like "path to file" are
+              # wrongly flagged.
               if patterns['ParamToVerb'] && word_count <= 4 && desc_parts.length == 3
-                if desc_parts[0].downcase == param_name.downcase && desc_parts[1].downcase == 'to'
+                if desc_parts[0].downcase == param_name.downcase &&
+                   desc_parts[1].downcase == 'to' &&
+                   low_value_verbs.include?(desc_parts[2].downcase)
                   return 'param_to_verb'
                 end
               end

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

@@ -39,12 +39,19 @@ module Yard
               end
 
               base_hash.delete_if { |_key, value| value == 'valid' }
-              separator_data = base_hash.values.map(&:last)
 
-              Validators::Documentation::UndocumentedMethodArguments::Parser
-                .new
-                .call(base_hash.values.map(&:first).join("\n"))
-                .each.with_index { |element, index| element[:separators] = separator_data[index] }
+              location_parser = Validators::Documentation::UndocumentedMethodArguments::Parser.new
+
+              # Parse each location together with its own separators so that an
+              # unparseable location line drops only its own offense instead of
+              # shifting the separators of all offenses that follow it
+              base_hash.values.filter_map do |location, separators|
+                element = location_parser.call(location).first
+                next unless element
+
+                element[:separators] = separators
+                element
+              end
             end
 
             private

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

@@ -21,7 +21,9 @@ module Yard
             #
             # @return [void]
             def in_process_query(object, collector)
-              return if object.is_alias?
+              # is_alias? exists only on method objects; on namespace objects
+              # YARD's method_missing raises NameError, so guard by type first
+              return if object.type == :method && object.is_alias?
 
               docstring = object.docstring.all
               return if docstring.nil? || docstring.empty?
@@ -52,17 +54,17 @@ module Yard
               had_blank_line = true
 
               lines.each do |line|
-                stripped = line.strip
-
-                if stripped.empty?
+                if line.strip.empty?
                   had_blank_line = true
                   next
                 end
 
-                if stripped.start_with?('@')
-                  tag_name = stripped.match(/^@(\S+)/)&.captures&.first
-                  next unless tag_name
+                # A real YARD tag begins at column 0 of the docstring. Indented
+                # @-leading lines are tag continuation or @example/code content
+                # (e.g. an instance variable like `@result`), not new tag groups.
+                tag_name = line[/\A@(\S+)/, 1]
 
+                if tag_name
                   current_group = group_for_tag(tag_name)
 
                   if previous_group && current_group != previous_group && !had_blank_line

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

@@ -33,8 +33,10 @@ module Yard
               (start_line...(end_line - 1)).reverse_each do |line_num|
                 line = source_lines[line_num].to_s.strip
 
-                # Skip empty lines
-                next if line.empty?
+                # A blank line means the comment above is detached from the
+                # definition - YARD does not attach it as the docstring, so stop
+                # scanning rather than reaching up to an unrelated comment block.
+                break if line.empty?
 
                 # Stop if we hit code (non-comment line)
                 break unless line.start_with?('#')
@@ -43,6 +45,10 @@ module Yard
                 next unless line.include?('@')
 
                 checked_tags.each do |tag_name|
+                  # The @option grammar is always "name [Type] :key", so the name
+                  # must precede the type - it is not subject to type_first.
+                  next if style == 'type_first' && tag_name == 'option'
+
                   if style == 'type_first'
                     # Detect: @tag_name word [Type] (violation when type_first is enforced)
                     pattern = /@#{tag_name}\s+(\w+)\s+\[([^\]]+)\]/

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

@@ -29,7 +29,7 @@ module Yard
             # @return [void]
             def in_process_query(object, collector)
               validated_tags = config.validator_config('Tags/TypeSyntax', 'ValidatedTags') ||
-                               %w[param option return yieldreturn]
+                               Config.defaults['ValidatedTags']
 
               all_typed_tags(object.docstring, validated_tags).each do |tag|
                 next unless tag.types

data/lib/yard/lint/validators/warnings/invalid_directive_format/parser.rb

@@ -10,9 +10,9 @@ module Yard
             # Set of regexps for detecting warnings reported by YARD stats
             self.regexps = {
               general: /^\[warn\]: Invalid directive format/,
-              message: /\[warn\]: (.*) in file/,
+              message: %r{\[warn\]: (.*?) in file},
               location: /in file `(.*)`/,
-              line: /line (\d*)/
+              line: %r{near line (\d+)}
             }.freeze
           end
         end

data/lib/yard/lint/validators/warnings/invalid_tag_format/parser.rb

@@ -10,9 +10,9 @@ module Yard
             # Set of regexps for detecting warnings reported by YARD stats
             self.regexps = {
               general: /^\[warn\]: Invalid tag format/,
-              message: /\[warn\]: (.*) in file/,
+              message: %r{\[warn\]: (.*?) in file},
               location: /in file `(.*)`/,
-              line: /line (\d*)/
+              line: %r{near line (\d+)}
             }.freeze
           end
         end

data/lib/yard/lint/validators/warnings/syntax_error/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # Validator for detecting files YARD could not parse
+        module SyntaxError
+          # Configuration for SyntaxError validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :syntax_error
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'error'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/syntax_error/parser.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module SyntaxError
+          # Parser for SyntaxError warnings.
+          #
+          # YARD reports a parse failure as a single warning line of the form:
+          #   Syntax error in `path/to/file.rb`:(LINE,COL): <description>
+          # (a sibling `ParserSyntaxError:` line and a stack trace are also
+          # emitted, but the `general` pattern matches only the first so each
+          # failure yields exactly one offense).
+          class Parser < ::Yard::Lint::Parsers::OneLineBase
+            # Set of regexps for detecting syntax-error warnings reported by YARD
+            self.regexps = {
+              general: /^\[warn\]: Syntax error in /,
+              message: /:\(\d+,\d+\):\s*(.+)$/,
+              location: /Syntax error in `(.+?)`/,
+              line: /:\((\d+),\d+\):/
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/syntax_error/result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module SyntaxError
+          # Result object for SyntaxError validation
+          class Result < Results::Base
+            self.default_severity = 'error'
+            self.offense_type = 'line'
+            self.offense_name = 'SyntaxError'
+
+            # Build human-readable message for a SyntaxError offense
+            # @param offense [Hash] offense data with :message key
+            # @return [String] formatted message
+            def build_message(offense)
+              base = 'File could not be parsed by YARD and was skipped'
+              detail = offense[:message]
+              detail && !detail.empty? ? "#{base}: #{detail}" : base
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/syntax_error/validator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module SyntaxError
+          # Validator for detecting files YARD could not parse (syntax errors)
+          class Validator < Base
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/syntax_error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Validators for checking YARD warnings
+      module Warnings
+        # SyntaxError validator
+        #
+        # Flags Ruby files that YARD could not parse because of a syntax error.
+        # Such files are silently skipped by YARD - they contribute no objects and
+        # therefore no documentation offenses - so without this validator a run
+        # could pass (exit 0) over code that does not even parse. This validator
+        # surfaces the parser error as an offense (severity `error` by default),
+        # making the run exit non-zero. Enabled by default.
+        #
+        # For example, a file whose method signature is missing its closing
+        # parenthesis (`def foo(x` followed by a body and `end`) fails to parse;
+        # YARD reports `Syntax error in <file>:(LINE,COL): ...` and this validator
+        # turns that into an offense. A file that parses cleanly produces nothing.
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Warnings/SyntaxError:
+        #       Enabled: false
+        #
+        module SyntaxError
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/warnings/unknown_directive/parser.rb

@@ -10,9 +10,9 @@ module Yard
             # Set of regexps for detecting warnings reported by YARD stats
             self.regexps = {
               general: /^\[warn\]: Unknown directive.*@!.*near line/,
-              message: /\[warn\]: (.*) in file/,
+              message: %r{\[warn\]: (.*?) in file},
               location: /in file `(.*)`/,
-              line: /line (\d*)/
+              line: %r{near line (\d+)}
             }.freeze
           end
         end

data/lib/yard/lint/validators/warnings/unknown_parameter_name/messages_builder.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'did_you_mean'
-require 'shellwords'
 
 module Yard
   module Lint
@@ -52,14 +51,8 @@ module Yard
 
                 line_num = line.to_i
 
-                # First, try to parse directly from the Ruby source file
-                # This is faster and doesn't require YARD to be fully loaded
-                params = parse_parameters_from_source(file, line_num)
-                return params unless params.empty?
-
-                # Fallback: Query YARD list for the method
-                # This requires YARD to parse the file first
-                fetch_parameters_via_yard(file, line_num)
+                # Parse directly from the Ruby source file.
+                parse_parameters_from_source(file, line_num)
               rescue StandardError => e
                 # If anything goes wrong, just return empty array (no suggestion)
                 warn "Failed to fetch parameters: #{e.message}" if ENV['DEBUG']
@@ -73,8 +66,10 @@ module Yard
               def parse_parameters_from_source(file, line)
                 return [] unless File.exist?(file)
 
-                # Calculate the search range (line numbers are 1-indexed)
-                start_line = [(line - 15), 1].max
+                # The warning is reported at the method's def line, so start
+                # there - scanning earlier would pick up an unrelated method
+                # defined in the preceding lines.
+                start_line = [line, 1].max
                 end_line = line + 5
 
                 # Only read the lines in the relevant range to avoid loading the whole file
@@ -92,12 +87,15 @@ module Yard
                 param_lines = []
 
                 lines.each do |source_line|
+                  # The method name may include a receiver (def self.foo, def
+                  # obj.foo) or be an operator, so match anything up to the
+                  # opening parenthesis rather than a bare \w+.
                   # Match single-line method definitions: def method_name(param1, param2)
-                  if source_line =~ /^\s*def\s+\w+\s*\((.*?)\)/
+                  if source_line =~ /^\s*def\s+[^(]+\((.*?)\)/
                     params_str = ::Regexp.last_match(1)
                     return extract_parameter_names(params_str)
                   # Match start of multi-line method definition: def method_name(
-                  elsif source_line =~ /^\s*def\s+\w+\s*\((.*)$/
+                  elsif source_line =~ /^\s*def\s+[^(]+\((.*)$/
                     in_multiline_def = true
                     param_lines << ::Regexp.last_match(1)
                     next
@@ -111,7 +109,7 @@ module Yard
                       params_str = params_str[/\A(.*?)\)/, 1] || params_str
                       return extract_parameter_names(params_str)
                     end
-                  elsif source_line.match?(/^\s*def\s+\w+\s*$/)
+                  elsif source_line.match?(/^\s*def\s+[^(]+$/)
                     # Method with no parameters
                     return []
                   end
@@ -130,38 +128,42 @@ module Yard
               def extract_parameter_names(params_str)
                 return [] if params_str.nil? || params_str.strip.empty?
 
-                params_str.split(',').map do |param|
-                  # Remove default values: "name = 'default'" => "name"
-                  param = param.split('=').first
-                  # Remove type annotations: "name:" => "name"
-                  param = param.delete(':')
-                  # Remove splat and block symbols: "*args", "**kwargs", "&block"
-                  param = param.delete('*&')
-                  # Strip whitespace
-                  param.strip
-                end.reject(&:empty?)
+                split_top_level_params(params_str).filter_map do |param|
+                  # Strip leading splat/block markers (*args, **kwargs, &block).
+                  name = param.strip.sub(/\A[*&]+/, '')
+                  # The name is everything up to the first ':' (keyword) or '='
+                  # (default), so a symbol default like `mode: :fast` or a default
+                  # containing commas like `list = [1, 2]` is not mangled.
+                  name = name[/\A[^:=]+/].to_s.strip
+                  name.empty? ? nil : name
+                end
               end
 
-              # Fetch parameters via YARD list command (fallback method)
-              # @param file [String] file path
-              # @param line [Integer] line number
-              # @return [Array<String>] array of parameter names
-              def fetch_parameters_via_yard(file, line)
-                # Query YARD for the method at this location
-                # Use Shellwords.escape to prevent command injection
-                escaped_file = Shellwords.escape(file)
-                query = "'type == :method && file == \"#{escaped_file}\" && line >= #{line - 15} && line <= #{line + 5}'"
-                cmd = "yard list --query #{query} 2>/dev/null"
-
-                output = `#{cmd}`.strip
-                return [] if output.empty?
-
-                # YARD list doesn't show parameters, we'd need to parse the source
-                # So this fallback is just for validation - use source parsing instead
-                []
-              rescue StandardError => e
-                warn "Failed to query YARD: #{e.message}" if ENV['DEBUG']
-                []
+              # Splits a parameter string on top-level commas, respecting
+              # brackets so defaults like `[1, 2]` or `{a: 1}` stay intact.
+              # @param params_str [String] the raw parameter list
+              # @return [Array<String>] individual parameter substrings
+              def split_top_level_params(params_str)
+                parts = []
+                current = +''
+                depth = 0
+                params_str.each_char do |char|
+                  case char
+                  when '(', '[', '{' then depth += 1; current << char
+                  when ')', ']', '}' then depth -= 1; current << char
+                  when ','
+                    if depth.zero?
+                      parts << current
+                      current = +''
+                    else
+                      current << char
+                    end
+                  else
+                    current << char
+                  end
+                end
+                parts << current
+                parts
               end
 
               # Find the best suggestion using DidYouMean spell checker
@@ -203,9 +205,12 @@ module Yard
                 return nil unless best_match
 
                 param, distance = best_match
-                max_distance = [unknown_param.length, param.length].max / 2
+                # Require the edit distance to be strictly less than half the
+                # longer length, so short, very different names are not
+                # "corrected" to an unrelated parameter.
+                max_length = [unknown_param.length, param.length].max
 
-                distance <= max_distance ? param : nil
+                distance < max_length / 2.0 ? param : nil
               end
 
               # Calculate Levenshtein distance between two strings

data/lib/yard/lint/validators/warnings/unknown_tag/messages_builder.rb

@@ -58,8 +58,13 @@ module Yard
                 suggestion = find_suggestion(unknown_tag)
 
                 if suggestion
+                  # A directive (e.g. parse, method, attribute) must be written
+                  # with the @! prefix; only real tags use a plain @. Rendering
+                  # a directive suggestion as @parse would itself be an unknown
+                  # tag.
+                  prefix = directive_only?(suggestion) ? '@!' : '@'
                   # Replace just the descriptive part before "in file"
-                  message.sub(/Unknown tag @\w+/, "Unknown tag @#{unknown_tag} (did you mean '@#{suggestion}'?)")
+                  message.sub(/Unknown tag @\w+/, "Unknown tag @#{unknown_tag} (did you mean '#{prefix}#{suggestion}'?)")
                 else
                   message
                 end
@@ -67,6 +72,14 @@ module Yard
 
               private
 
+              # Whether the given name is a YARD directive and not also a tag,
+              # so it must be referenced with the @! prefix.
+              # @param name [String] candidate tag/directive name
+              # @return [Boolean]
+              def directive_only?(name)
+                known_directives.include?(name) && !known_tags.include?(name)
+              end
+
               # Find the best suggestion using DidYouMean spell checker
               # @param unknown_tag [String] the unknown tag name (without @ prefix)
               # @return [String, nil] suggested tag name or nil
@@ -104,9 +117,13 @@ module Yard
                 return nil unless best_match
 
                 tag, distance = best_match
-                max_distance = [unknown_tag.length, tag.length].max / 2
+                # Require the edit distance to be strictly less than half the
+                # longer length, so short, very different names like @foo/@spec
+                # are not "corrected" to @todo/@see (which differ by half their
+                # characters).
+                max_length = [unknown_tag.length, tag.length].max
 
-                distance <= max_distance ? tag : nil
+                distance < max_length / 2.0 ? tag : nil
               end
 
               # Calculate Levenshtein distance between two strings

data/lib/yard/lint/validators/warnings/unknown_tag/parser.rb

@@ -12,9 +12,9 @@ module Yard
             # Set of regexps for detecting warnings reported by YARD stats
             self.regexps = {
               general: /^\[warn\]: Unknown tag.*@.*near line/,
-              message: /\[warn\]: (.*) in file/,
+              message: %r{\[warn\]: (.*?) in file},
               location: /in file `(.*)`/,
-              line: /line (\d*)/
+              line: %r{near line (\d+)}
             }.freeze
           end
         end

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.6.1'
+    VERSION = '1.7.0'
   end
 end

data/lib/yard/lint.rb

@@ -78,7 +78,10 @@ module Yard
         # Get changed files from git based on mode
         git_files = case diff[:mode]
                     when :ref
-                      Git.changed_files(diff[:base_ref], path)
+                      # When no explicit REF was given, honor the configured
+                      # DefaultBaseRef before falling back to main/master.
+                      base_ref = diff[:base_ref] || config&.diff_mode_default_base_ref
+                      Git.changed_files(base_ref, path)
                     when :staged
                       Git.staged_files(path)
                     when :changed

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -262,6 +262,11 @@ files:
 - lib/yard/lint/validators/warnings/invalid_tag_format/parser.rb
 - lib/yard/lint/validators/warnings/invalid_tag_format/result.rb
 - lib/yard/lint/validators/warnings/invalid_tag_format/validator.rb
+- lib/yard/lint/validators/warnings/syntax_error.rb
+- lib/yard/lint/validators/warnings/syntax_error/config.rb
+- lib/yard/lint/validators/warnings/syntax_error/parser.rb
+- lib/yard/lint/validators/warnings/syntax_error/result.rb
+- lib/yard/lint/validators/warnings/syntax_error/validator.rb
 - lib/yard/lint/validators/warnings/unknown_directive.rb
 - lib/yard/lint/validators/warnings/unknown_directive/config.rb
 - lib/yard/lint/validators/warnings/unknown_directive/parser.rb