yard-lint 1.2.2 → 1.3.0.rc1

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

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

@@ -5,25 +5,8 @@ module Yard
     module Validators
       module Warnings
         module UnknownParameterName
-          # Runs YARD stats command to check for unknownparametername
+          # Validator for detecting unknown 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/unknown_tag/messages_builder.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Warnings
+        module UnknownTag
+          # Builds enhanced messages with "did you mean" suggestions for unknown tags
+          class MessagesBuilder
+            class << self
+              # Dynamically fetch list of valid YARD meta-data tags from YARD::Tags::Library
+              # This ensures we're always in sync with the installed YARD version
+              # @return [Array<String>] array of tag names (without @ prefix)
+              def known_tags
+                @known_tags ||= begin
+                  lib = ::YARD::Tags::Library.instance
+                  lib.methods
+                     .grep(/_tag$/)
+                     .map { |m| m.to_s.sub(/_tag$/, '') }
+                     .sort
+                     .freeze
+                end
+              end
+
+              # Dynamically fetch list of valid YARD directives from YARD::Tags::Library
+              # This ensures we're always in sync with the installed YARD version
+              # @return [Array<String>] array of directive names (without @! prefix)
+              def known_directives
+                @known_directives ||= begin
+                  lib = ::YARD::Tags::Library.instance
+                  lib.methods
+                     .grep(/_directive$/)
+                     .map { |m| m.to_s.sub(/_directive$/, '') }
+                     .sort
+                     .freeze
+                end
+              end
+
+              # Combined list of all known tags and directives
+              # @return [Array<String>] array of all valid tag and directive names
+              def all_known_tags
+                @all_known_tags ||= (known_tags + known_directives).freeze
+              end
+              # Build message with suggestion for unknown tag
+              # @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] || 'Unknown tag detected'
+
+                # Extract the unknown tag name from the message
+                # Format: "Unknown tag @tagname in file..."
+                match = message.match(/Unknown tag @(\w+)/)
+                return message unless match
+
+                unknown_tag = match[1]
+
+                # Find best suggestion using did_you_mean
+                suggestion = find_suggestion(unknown_tag)
+
+                if suggestion
+                  # Replace just the descriptive part before "in file"
+                  message.sub(/Unknown tag @\w+/, "Unknown tag @#{unknown_tag} (did you mean '@#{suggestion}'?)")
+                else
+                  message
+                end
+              end
+
+              private
+
+              # 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
+              def find_suggestion(unknown_tag)
+                return nil if unknown_tag.nil? || unknown_tag.empty?
+
+                # Use DidYouMean::SpellChecker for smart suggestions
+                spell_checker = DidYouMean::SpellChecker.new(dictionary: all_known_tags)
+                suggestions = spell_checker.correct(unknown_tag)
+
+                # If DidYouMean found suggestions, return the best one
+                return suggestions.first unless suggestions.empty?
+
+                # Otherwise, fallback to Levenshtein distance
+                find_suggestion_fallback(unknown_tag)
+              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_tag)
+              end
+
+              # Fallback suggestion finder using simple Levenshtein distance
+              # @param unknown_tag [String] the unknown tag name
+              # @return [String, nil] suggested tag name or nil
+              def find_suggestion_fallback(unknown_tag)
+                # Calculate Levenshtein distance for each tag
+                distances = all_known_tags.map do |tag|
+                  [tag, levenshtein_distance(unknown_tag, tag)]
+                end
+
+                # Sort by distance and get the closest match
+                best_match = distances.min_by { |_tag, distance| distance }
+
+                # Only suggest if the distance is reasonable (less than half the length)
+                return nil unless best_match
+
+                tag, distance = best_match
+                max_distance = [unknown_tag.length, tag.length].max / 2
+
+                distance <= max_distance ? tag : 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_tag/result.rb

@@ -12,10 +12,11 @@ module Yard
             self.offense_name = 'UnknownTag'
 
             # Build human-readable message for unknown tag 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] || 'Unknown tag detected'
+              MessagesBuilder.call(offense)
             end
           end
         end

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

@@ -5,25 +5,8 @@ module Yard
     module Validators
       module Warnings
         module UnknownTag
-          # Runs YARD stats command to check for unknown YARD tags
+          # Validator for detecting unknown YARD tag warnings
           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_tag.rb

@@ -12,18 +12,28 @@ module Yard
         # doesn't recognize, which could indicate typos or unsupported tags.
         # This validator is enabled by default.
         #
+        # Provides intelligent "did you mean" suggestions for common typos using
+        # Ruby's did_you_mean gem with Levenshtein distance fallback.
+        #
         # @example Bad - Misspelled or non-existent tags
         #   # @param name [String] typo in param tag
         #   # @returns [String] should be @return not @returns
+        #   # @raises [Error] should be @raise not @raises
         #   def process(name)
         #   end
         #
         # @example Good - Standard YARD tags
         #   # @param name [String] the name
         #   # @return [String] the result
+        #   # @raise [Error] the error
         #   def process(name)
         #   end
         #
+        # **Output with suggestions:**
+        #
+        #     lib/foo.rb:10: [error] Unknown tag @returns (did you mean '@return'?)
+        #     lib/foo.rb:11: [error] Unknown tag @raises (did you mean '@raise'?)
+        #
         # ## Configuration
         #
         # To disable this validator:

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.2.2'
+    VERSION = '1.3.0.rc1'
   end
 end

data/lib/yard/lint.rb

@@ -6,6 +6,9 @@ require 'open3'
 require 'tempfile'
 require 'tmpdir'
 require 'digest'
+require 'did_you_mean'
+require 'yard'
+require 'set'
 
 module Yard
   # YARD Lint module providing linting functionality for YARD documentation
@@ -59,6 +62,9 @@ module Yard
       # @param config [Yard::Lint::Config] configuration object
       # @return [Array<String>] array of absolute file paths
       def get_diff_files(diff, path, config)
+        # Determine the base directory for relative path calculations
+        base_dir = determine_base_dir(path)
+
         # Get changed files from git based on mode
         git_files = case diff[:mode]
                     when :ref
@@ -72,11 +78,7 @@ module Yard
                     end
 
         # Apply exclusion patterns
-        git_files.reject do |file|
-          config.exclude.any? do |pattern|
-            File.fnmatch(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
-          end
-        end
+        git_files.reject { |file| excluded_file?(file, config.exclude, base_dir) }
       end
 
       # Expand path/glob patterns into an array of files
@@ -84,28 +86,94 @@ module Yard
       # @param config [Yard::Lint::Config] configuration object
       # @return [Array<String>] array of absolute file paths
       def expand_path(path, config)
+        # Determine the base directory for relative path calculations
+        base_dir = determine_base_dir(path)
+
+        files = discover_ruby_files(path)
+
+        # Convert to absolute paths for YARD
+        files = files.map { |file| File.expand_path(file) }
+
+        # Filter out excluded files
+        files.reject { |file| excluded_file?(file, config.exclude, base_dir) }
+      end
+
+      # Discover Ruby files from path/glob patterns
+      # @param path [String, Array<String>] path or array of paths
+      # @return [Array<String>] array of discovered Ruby file paths
+      # @raise [Errors::FileNotFoundError] if a specified path does not exist
+      def discover_ruby_files(path)
         files = Array(path).flat_map do |p|
           if p.include?('*')
             Dir.glob(p)
           elsif File.directory?(p)
             Dir.glob(File.join(p, '**/*.rb'))
           else
+            validate_path_exists!(p)
             p
           end
         end
 
-        files = files.select { |f| File.file?(f) && f.end_with?('.rb') }
+        files.select { |file| File.file?(file) && file.end_with?('.rb') }
+      end
 
-        # Convert to absolute paths for YARD
-        files = files.map { |f| File.expand_path(f) }
+      # Validate that a path exists
+      # @param path [String] file or directory path to check for existence
+      # @raise [Errors::FileNotFoundError] if path does not exist
+      def validate_path_exists!(path)
+        return if File.exist?(path)
 
-        # Filter out excluded files
-        files.reject do |file|
-          config.exclude.any? do |pattern|
-            File.fnmatch(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
-          end
+        raise Errors::FileNotFoundError, "No such file or directory: #{path}"
+      end
+
+      # Determine base directory for relative path calculations
+      # @param path [String, Array<String>] path or array of paths
+      # @return [String] absolute base directory path
+      def determine_base_dir(path)
+        first_path = Array(path).first
+        return Dir.pwd unless first_path
+
+        absolute_path = File.expand_path(first_path)
+        File.directory?(absolute_path) ? absolute_path : File.dirname(absolute_path)
+      end
+
+      # Check if a file matches any exclusion pattern
+      # Patterns are matched against both absolute and relative paths
+      # @param file [String] absolute file path
+      # @param patterns [Array<String>] exclusion patterns
+      # @param base_dir [String] base directory for relative path calculation
+      # @return [Boolean] true if file should be excluded
+      def excluded_file?(file, patterns, base_dir)
+        relative_path = relative_path_from(file, base_dir)
+
+        patterns.any? do |pattern|
+          match_path?(pattern, file, relative_path)
         end
       end
+
+      # Calculate relative path from base directory
+      # @param file [String] absolute file path
+      # @param base_dir [String] base directory
+      # @return [String] relative path
+      def relative_path_from(file, base_dir)
+        if file.start_with?("#{base_dir}/")
+          file.sub("#{base_dir}/", '')
+        else
+          file
+        end
+      end
+
+      # Check if a pattern matches a file path
+      # Tries matching against both relative and absolute paths
+      # @param pattern [String] glob pattern
+      # @param absolute_path [String] absolute file path
+      # @param relative_path [String] relative file path
+      # @return [Boolean] true if pattern matches
+      def match_path?(pattern, absolute_path, relative_path)
+        flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+        File.fnmatch(pattern, relative_path, flags) || File.fnmatch(pattern, absolute_path, flags)
+      end
     end
   end
 end

data/renovate.json

@@ -3,6 +3,7 @@
   "extends": [
     "config:recommended"
   ],
+  "minimumReleaseAge": "7 days",
   "github-actions": {
     "enabled": true,
     "pinDigests": true
@@ -10,13 +11,5 @@
   "includePaths": [
     "Gemfile",
     "yard-lint.gemspec"
-  ],
-  "packageRules": [
-    {
-      "matchManagers": [
-        "github-actions"
-      ],
-      "minimumReleaseAge": "7 days"
-    }
   ]
 }