yard-lint 1.2.3 → 1.3.0

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

@@ -9,100 +9,69 @@ module Yard
           # YARD standard (type_after_name): @param name [String] description
           # Alternative (type_first): @param name [String] description
           #
-          # Note: @return tags are not checked as they don't have parameter names
+          # @note @return tags are not checked as they don't have parameter names
           class Validator < Base
-            private
-
-            # Runs YARD query to check type position in tags
-            # @param dir [String] directory where YARD database is stored
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution results
-            def yard_cmd(dir, file_list_path)
-              # Write query to a temporary file to avoid shell escaping issues
-              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{query} "
-
-              Tempfile.create(['yard_query', '.sh']) do |f|
-                f.write("#!/bin/bash\n")
-                f.write(cmd)
-                f.write("#{shell_arguments} -b #{Shellwords.escape(dir)}\n")
-                f.flush
-                f.chmod(0o755)
-
-                shell("bash #{Shellwords.escape(f.path)}")
-              end
-            end
-
-            # YARD query that checks source code directly instead of docstring.all
-            # Detects patterns based on configured style
-            # @return [String] YARD query string
-            def query
-              <<~QUERY.strip
-                '
-                require "ripper"
-
-                checked_tags = #{checked_tags_array}
-                enforced_style = "#{enforced_style}"
-
-                # Read the source file and find comment lines for this object
-                return false unless object.file && File.exist?(object.file)
-
-                source_lines = File.readlines(object.file)
-                start_line = [object.line - 50, 0].max
-                end_line = [object.line, source_lines.length - 1].min
-
-                # Look for comments before the object definition
-                # Start just before the object line and scan backward
-                (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?
-
-                  # Stop if we hit code (non-comment line)
-                  break unless line.start_with?("#")
-
-                  # Skip comment-only lines without tags
-                  next unless line.include?("@")
-
-                  checked_tags.each do |tag_name|
-                    if enforced_style == "type_first"
-                      # Detect: @tag_name word [Type] (violation when type_first is enforced)
-                      pattern = /@\#{tag_name}\\s+(\\w+)\\s+\\[([^\\]]+)\\]/
-                      if line =~ pattern
-                        param_name = $1
-                        type_info = $2
-                        puts object.file + ":" + (line_num + 1).to_s + ": " + object.title
-                        puts tag_name + "|" + param_name + "|" + type_info + "|type_after_name"
-                      end
-                    else
-                      # Detect: @tag_name [Type] word (violation when type_after_name is enforced)
-                      pattern = /@\#{tag_name}\\s+\\[([^\\]]+)\\]\\s+(\\w+)/
-                      if line =~ pattern
-                        type_info = $1
-                        param_name = $2
-                        puts object.file + ":" + (line_num + 1).to_s + ": " + object.title
-                        puts tag_name + "|" + param_name + "|" + type_info + "|type_first"
-                      end
+            # Enable in-process execution
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Checks type annotation position in @param and @option tags.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              return unless object.file && File.exist?(object.file)
+
+              checked_tags = config_or_default('CheckedTags')
+              style = enforced_style
+
+              source_lines = File.readlines(object.file)
+              start_line = [object.line - 50, 0].max
+              end_line = [object.line, source_lines.length - 1].min
+
+              # Look for comments before the object definition
+              (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?
+
+                # Stop if we hit code (non-comment line)
+                break unless line.start_with?('#')
+
+                # Skip comment-only lines without tags
+                next unless line.include?('@')
+
+                checked_tags.each do |tag_name|
+                  if style == 'type_first'
+                    # Detect: @tag_name word [Type] (violation when type_first is enforced)
+                    pattern = /@#{tag_name}\s+(\w+)\s+\[([^\]]+)\]/
+                    if line =~ pattern
+                      param_name = ::Regexp.last_match(1)
+                      type_info = ::Regexp.last_match(2)
+                      collector.puts "#{object.file}:#{line_num + 1}: #{object.title}"
+                      collector.puts "#{tag_name}|#{param_name}|#{type_info}|type_after_name"
+                    end
+                  else
+                    # Detect: @tag_name [Type] word (violation when type_after_name is enforced)
+                    pattern = /@#{tag_name}\s+\[([^\]]+)\]\s+(\w+)/
+                    if line =~ pattern
+                      type_info = ::Regexp.last_match(1)
+                      param_name = ::Regexp.last_match(2)
+                      collector.puts "#{object.file}:#{line_num + 1}: #{object.title}"
+                      collector.puts "#{tag_name}|#{param_name}|#{type_info}|type_first"
                     end
                   end
                 end
-
-                false
-                '
-              QUERY
+              end
             end
 
+            private
+
             # @return [String] the enforced style ('type_after_name' (standard) or 'type_first')
             def enforced_style
               config_or_default('EnforcedStyle')
             end
-
-            # Array of tag names to check, formatted for YARD query
-            # @return [String] Ruby array literal string
-            def checked_tags_array
-              tags = config_or_default('CheckedTags')
-              "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
-            end
           end
         end
       end

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

@@ -42,7 +42,6 @@ module Yard
         #
         #     Tags/TagTypePosition:
         #       Enabled: false
-        #
         module TagTypePosition
         end
       end

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

@@ -16,9 +16,14 @@ module Yard
             # @option _kwargs [Object] :unused this parameter accepts no options (reserved for future use)
             # @return [Array<Hash>] array with violation details
             def call(yard_output, **_kwargs)
-              return [] if yard_output.nil? || yard_output.strip.empty?
+              return [] if yard_output.nil?
 
-              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+              # Handle encoding issues from YARD output that may contain invalid UTF-8 sequences
+              # This can happen when YARD processes files with non-ASCII characters in type specs
+              sanitized = yard_output.encode('UTF-8', invalid: :replace, undef: :replace, replace: '')
+              return [] if sanitized.strip.empty?
+
+              lines = sanitized.split("\n").map(&:strip).reject(&:empty?)
               violations = []
 
               lines.each_slice(2) do |location_line, details_line|

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

@@ -7,66 +7,36 @@ module Yard
         module TypeSyntax
           # Runs YARD to validate type syntax using TypesExplainer::Parser
           class Validator < Base
-            private
-
-            # Runs YARD query to validate type syntax on given files
-            # @param dir [String] directory where YARD database is stored
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution results
-            def yard_cmd(dir, file_list_path)
-              # Write query to a temporary file to avoid shell escaping issues
-              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{query} "
-
-              Tempfile.create(['yard_query', '.sh']) do |f|
-                f.write("#!/bin/bash\n")
-                f.write(cmd)
-                f.write("#{shell_arguments} -b #{Shellwords.escape(dir)}\n")
-                f.flush
-                f.chmod(0o755)
-
-                shell("bash #{Shellwords.escape(f.path)}")
-              end
-            end
-
-            # YARD query that validates type syntax for each tag
-            # Format output as two lines per violation:
-            #   Line 1: file.rb:LINE: ClassName#method_name
-            #   Line 2: tag_name|type_string|error_message
-            # @return [String] YARD query string
-            def query
-              <<~QUERY.strip
-                '
-                require "yard"
-
-                docstring
-                  .tags
-                  .select { |tag| #{validated_tags_array}.include?(tag.tag_name) }
-                  .each do |tag|
-                    next unless tag.types
-
-                    tag.types.each do |type_str|
-                      begin
-                        YARD::Tags::TypesExplainer::Parser.parse(type_str)
-                      rescue SyntaxError => e
-                        puts object.file + ":" + object.line.to_s + ": " + object.title
-                        puts tag.tag_name + "|" + type_str + "|" + e.message
-                        break
-                      end
-                    end
+            # Enable in-process execution
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Validates type syntax in tags using YARD's TypesExplainer::Parser.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              validated_tags = config.validator_config('Tags/TypeSyntax', 'ValidatedTags') ||
+                               %w[param option return yieldreturn]
+
+              object.docstring.tags
+                    .select { |tag| validated_tags.include?(tag.tag_name) }
+                    .each do |tag|
+                next unless tag.types
+
+                tag.types.each do |type_str|
+                  begin
+                    YARD::Tags::TypesExplainer::Parser.parse(type_str)
+                  rescue SyntaxError => e
+                    # Sanitize error message to handle invalid UTF-8 sequences
+                    # YARD's parser may generate malformed error messages for non-ASCII input
+                    error_msg = e.message.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?')
+                    collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                    collector.puts "#{tag.tag_name}|#{type_str}|#{error_msg}"
+                    break
                   end
-
-                false
-                '
-              QUERY
-            end
-
-            # Array of tag names to validate, formatted for YARD query
-            # @return [String] Ruby array literal string
-            def validated_tags_array
-              tags = config.validator_config('Tags/TypeSyntax', 'ValidatedTags') || %w[
-                param option return yieldreturn
-              ]
-              "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
+                end
+              end
             end
           end
         end

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

@@ -29,7 +29,6 @@ module Yard
         #
         #     Tags/TypeSyntax:
         #       Enabled: false
-        #
         module TypeSyntax
         end
       end

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

@@ -5,25 +5,8 @@ module Yard
     module Validators
       module Warnings
         module DuplicatedParameterName
-          # Runs YARD stats command to check for duplicatedparametername
+          # Validator for detecting duplicated parameter name warnings from YARD
           class Validator < Base
-            private
-
-            # Runs YARD stats command with proper settings on a given dir and files
-            # @param dir [String] dir where we should generate the temp docs
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, file_list_path)
-              cmd = <<~CMD
-                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
-                  #{shell_arguments} \
-                --compact \
-                -b #{Shellwords.escape(dir)}
-              CMD
-              cmd = cmd.tr("\n", ' ')
-
-              shell(cmd)
-            end
           end
         end
       end

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

@@ -5,25 +5,8 @@ module Yard
     module Validators
       module Warnings
         module InvalidDirectiveFormat
-          # Runs YARD stats command to check for invaliddirectiveformat
+          # Validator for detecting invalid directive format warnings from YARD
           class Validator < Base
-            private
-
-            # Runs YARD stats command with proper settings on a given dir and files
-            # @param dir [String] dir where we should generate the temp docs
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, file_list_path)
-              cmd = <<~CMD
-                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
-                  #{shell_arguments} \
-                --compact \
-                -b #{Shellwords.escape(dir)}
-              CMD
-              cmd = cmd.tr("\n", ' ')
-
-              shell(cmd)
-            end
           end
         end
       end

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

@@ -5,25 +5,8 @@ module Yard
     module Validators
       module Warnings
         module InvalidTagFormat
-          # Runs YARD stats command to check for invalidtagformat
+          # Validator for detecting invalid tag format warnings from YARD
           class Validator < Base
-            private
-
-            # Runs YARD stats command with proper settings on a given dir and files
-            # @param dir [String] dir where we should generate the temp docs
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, file_list_path)
-              cmd = <<~CMD
-                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
-                  #{shell_arguments} \
-                --compact \
-                -b #{Shellwords.escape(dir)}
-              CMD
-              cmd = cmd.tr("\n", ' ')
-
-              shell(cmd)
-            end
           end
         end
       end

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

@@ -5,25 +5,8 @@ module Yard
     module Validators
       module Warnings
         module UnknownDirective
-          # Runs YARD stats command to check for unknowndirective
+          # Validator for detecting unknown directive warnings from YARD
           class Validator < Base
-            private
-
-            # Runs YARD stats command with proper settings on a given dir and files
-            # @param dir [String] dir where we should generate the temp docs
-            # @param file_list_path [String] path to temp file containing file paths (one per line)
-            # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, file_list_path)
-              cmd = <<~CMD
-                cat #{Shellwords.escape(file_list_path)} | xargs yard stats \
-                  #{shell_arguments} \
-                --compact \
-                -b #{Shellwords.escape(dir)}
-              CMD
-              cmd = cmd.tr("\n", ' ')
-
-              shell(cmd)
-            end
           end
         end
       end

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

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'did_you_mean'
+require 'shellwords'
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownParameterName
+          # Builds enhanced messages with "did you mean" suggestions
+          class MessagesBuilder
+            class << self
+              # Build message with suggestion for unknown parameter
+              # @param offense [Hash] offense data with :message, :location (file), :line keys
+              # @return [String] formatted message with suggestion if available
+              def call(offense)
+                message = offense[:message] || 'UnknownParameterName detected'
+
+                # Extract the unknown parameter name from the message
+                # Format: "@param tag has unknown parameter name: param_name"
+                match = message.match(/@param tag has unknown parameter name: (\w+)/)
+                return message unless match
+
+                unknown_param = match[1]
+
+                # Get actual parameters for the method at this location
+                # Note: offense[:location] contains the file path
+                file = offense[:location]
+                line = offense[:line]
+                actual_params = fetch_actual_parameters(file, line)
+                return message if actual_params.empty?
+
+                # Find best suggestion using did_you_mean
+                suggestion = find_suggestion(unknown_param, actual_params)
+
+                if suggestion
+                  "#{message} (did you mean '#{suggestion}'?)"
+                else
+                  message
+                end
+              end
+
+              private
+
+              # Fetch actual method parameters from YARD at the given location
+              # @param file [String] file path
+              # @param line [Integer, String] line number
+              # @return [Array<String>] array of actual parameter names
+              def fetch_actual_parameters(file, line)
+                return [] unless file && line
+
+                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)
+              rescue StandardError => e
+                # If anything goes wrong, just return empty array (no suggestion)
+                warn "Failed to fetch parameters: #{e.message}" if ENV['DEBUG']
+                []
+              end
+
+              # Parse method parameters directly from Ruby source file
+              # @param file [String] file path
+              # @param line [Integer] line number (approximate location of method)
+              # @return [Array<String>] array of parameter names
+              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
+                end_line = line + 5
+
+                # Only read the lines in the relevant range to avoid loading the whole file
+                lines = []
+                current_line_num = 1
+                File.foreach(file) do |source_line|
+                  lines << source_line if current_line_num.between?(start_line, end_line)
+                  break if current_line_num > end_line
+
+                  current_line_num += 1
+                end
+
+                # Search for method definition in the collected lines
+                in_multiline_def = false
+                param_lines = []
+
+                lines.each do |source_line|
+                  # Match single-line method definitions: def method_name(param1, param2)
+                  if source_line =~ /^\s*def\s+\w+\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*\((.*)$/
+                    in_multiline_def = true
+                    param_lines << ::Regexp.last_match(1)
+                    next
+                  elsif in_multiline_def
+                    param_lines << source_line.strip
+                    # Check if this line closes the parameter list
+                    if source_line.include?(')')
+                      # Join all lines and extract params
+                      params_str = param_lines.join(' ')
+                      # Remove trailing ')' and anything after it
+                      params_str = params_str[/\A(.*?)\)/, 1] || params_str
+                      return extract_parameter_names(params_str)
+                    end
+                  elsif source_line.match?(/^\s*def\s+\w+\s*$/)
+                    # Method with no parameters
+                    return []
+                  end
+                end
+
+                []
+              rescue StandardError => e
+                warn "Failed to parse source: #{e.message}" if ENV['DEBUG']
+                []
+              end
+
+              # Extract parameter names from a parameter string
+              # Handles various parameter formats: regular, default values, splat, keyword, block
+              # @param params_str [String] parameter string from method signature
+              # @return [Array<String>] array of parameter names
+              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?)
+              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']
+                []
+              end
+
+              # Find the best suggestion using DidYouMean spell checker
+              # @param unknown_param [String] the unknown parameter name
+              # @param actual_params [Array<String>] array of actual parameter names
+              # @return [String, nil] suggested parameter name or nil
+              def find_suggestion(unknown_param, actual_params)
+                return nil if actual_params.empty?
+
+                # Use DidYouMean::SpellChecker for smart suggestions
+                spell_checker = DidYouMean::SpellChecker.new(dictionary: actual_params)
+                suggestions = spell_checker.correct(unknown_param)
+
+                # If DidYouMean found suggestions, return the best one
+                return suggestions.first unless suggestions.empty?
+
+                # Otherwise, fallback to Levenshtein distance
+                find_suggestion_fallback(unknown_param, actual_params)
+              rescue StandardError => e
+                # Fallback to simple Levenshtein distance if DidYouMean fails
+                warn "DidYouMean failed: #{e.message}, using fallback" if ENV['DEBUG']
+                find_suggestion_fallback(unknown_param, actual_params)
+              end
+
+              # Fallback suggestion finder using simple Levenshtein distance
+              # @param unknown_param [String] the unknown parameter name
+              # @param actual_params [Array<String>] array of actual parameter names
+              # @return [String, nil] suggested parameter name or nil
+              def find_suggestion_fallback(unknown_param, actual_params)
+                # Calculate Levenshtein distance for each parameter
+                distances = actual_params.map do |param|
+                  [param, levenshtein_distance(unknown_param, param)]
+                end
+
+                # Sort by distance and get the closest match
+                best_match = distances.min_by { |_param, distance| distance }
+
+                # Only suggest if the distance is reasonable (less than half the length)
+                return nil unless best_match
+
+                param, distance = best_match
+                max_distance = [unknown_param.length, param.length].max / 2
+
+                distance <= max_distance ? param : nil
+              end
+
+              # Calculate Levenshtein distance between two strings
+              # @param str1 [String] first string
+              # @param str2 [String] second string
+              # @return [Integer] Levenshtein distance
+              def levenshtein_distance(str1, str2)
+                return str2.length if str1.empty?
+                return str1.length if str2.empty?
+
+                matrix = Array.new(str1.length + 1) { Array.new(str2.length + 1) }
+
+                (0..str1.length).each { |i| matrix[i][0] = i }
+                (0..str2.length).each { |j| matrix[0][j] = j }
+
+                (1..str1.length).each do |i|
+                  (1..str2.length).each do |j|
+                    cost = str1[i - 1] == str2[j - 1] ? 0 : 1
+                    matrix[i][j] = [
+                      matrix[i - 1][j] + 1,      # deletion
+                      matrix[i][j - 1] + 1,      # insertion
+                      matrix[i - 1][j - 1] + cost # substitution
+                    ].min
+                  end
+                end
+
+                matrix[str1.length][str2.length]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -12,10 +12,11 @@ module Yard
             self.offense_name = 'UnknownParameterName'
 
             # Build human-readable message for UnknownParameterName offense
-            # @param offense [Hash] offense data with :message key
-            # @return [String] formatted message
+            # Uses MessagesBuilder to add "did you mean" suggestions
+            # @param offense [Hash] offense data with :message, :location, :line keys
+            # @return [String] formatted message with suggestion if available
             def build_message(offense)
-              offense[:message] || 'UnknownParameterName detected'
+              MessagesBuilder.call(offense)
             end
           end
         end