yard-lint 1.2.3 → 1.3.0

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.3'
+    VERSION = '1.3.0'
   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/lib/yard-lint.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Load IRB notifier shim before YARD to avoid IRB dependency in Ruby 3.5+
+# Load IRB notifier shim before YARD to avoid IRB dependency in Ruby 3.5+/4.0+
 # This must be loaded before any YARD code is required
 require_relative 'yard/lint/ext/irb_notifier_shim'
 

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"
-    }
   ]
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.3.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -54,11 +54,15 @@ files:
 - bin/yard-lint
 - lib/yard-lint.rb
 - lib/yard/lint.rb
-- lib/yard/lint/command_cache.rb
 - lib/yard/lint/config.rb
 - lib/yard/lint/config_generator.rb
 - lib/yard/lint/config_loader.rb
+- lib/yard/lint/config_updater.rb
 - lib/yard/lint/errors.rb
+- lib/yard/lint/executor/in_process_registry.rb
+- lib/yard/lint/executor/query_executor.rb
+- lib/yard/lint/executor/result_collector.rb
+- lib/yard/lint/executor/warning_dispatcher.rb
 - lib/yard/lint/ext/irb_notifier_shim.rb
 - lib/yard/lint/formatters/progress.rb
 - lib/yard/lint/git.rb
@@ -74,6 +78,18 @@ files:
 - lib/yard/lint/templates/strict_config.yml
 - lib/yard/lint/validators/base.rb
 - lib/yard/lint/validators/config.rb
+- lib/yard/lint/validators/documentation/blank_line_before_definition.rb
+- lib/yard/lint/validators/documentation/blank_line_before_definition/config.rb
+- lib/yard/lint/validators/documentation/blank_line_before_definition/messages_builder.rb
+- lib/yard/lint/validators/documentation/blank_line_before_definition/parser.rb
+- lib/yard/lint/validators/documentation/blank_line_before_definition/result.rb
+- lib/yard/lint/validators/documentation/blank_line_before_definition/validator.rb
+- lib/yard/lint/validators/documentation/empty_comment_line.rb
+- lib/yard/lint/validators/documentation/empty_comment_line/config.rb
+- lib/yard/lint/validators/documentation/empty_comment_line/messages_builder.rb
+- lib/yard/lint/validators/documentation/empty_comment_line/parser.rb
+- lib/yard/lint/validators/documentation/empty_comment_line/result.rb
+- lib/yard/lint/validators/documentation/empty_comment_line/validator.rb
 - lib/yard/lint/validators/documentation/markdown_syntax.rb
 - lib/yard/lint/validators/documentation/markdown_syntax/config.rb
 - lib/yard/lint/validators/documentation/markdown_syntax/messages_builder.rb
@@ -126,6 +142,12 @@ files:
 - lib/yard/lint/validators/tags/example_syntax/parser.rb
 - lib/yard/lint/validators/tags/example_syntax/result.rb
 - lib/yard/lint/validators/tags/example_syntax/validator.rb
+- lib/yard/lint/validators/tags/informal_notation.rb
+- lib/yard/lint/validators/tags/informal_notation/config.rb
+- lib/yard/lint/validators/tags/informal_notation/messages_builder.rb
+- lib/yard/lint/validators/tags/informal_notation/parser.rb
+- lib/yard/lint/validators/tags/informal_notation/result.rb
+- lib/yard/lint/validators/tags/informal_notation/validator.rb
 - lib/yard/lint/validators/tags/invalid_types.rb
 - lib/yard/lint/validators/tags/invalid_types/config.rb
 - lib/yard/lint/validators/tags/invalid_types/messages_builder.rb
@@ -138,6 +160,12 @@ files:
 - lib/yard/lint/validators/tags/meaningless_tag/parser.rb
 - lib/yard/lint/validators/tags/meaningless_tag/result.rb
 - lib/yard/lint/validators/tags/meaningless_tag/validator.rb
+- lib/yard/lint/validators/tags/non_ascii_type.rb
+- lib/yard/lint/validators/tags/non_ascii_type/config.rb
+- lib/yard/lint/validators/tags/non_ascii_type/messages_builder.rb
+- lib/yard/lint/validators/tags/non_ascii_type/parser.rb
+- lib/yard/lint/validators/tags/non_ascii_type/result.rb
+- lib/yard/lint/validators/tags/non_ascii_type/validator.rb
 - lib/yard/lint/validators/tags/option_tags.rb
 - lib/yard/lint/validators/tags/option_tags/config.rb
 - lib/yard/lint/validators/tags/option_tags/messages_builder.rb
@@ -156,6 +184,12 @@ files:
 - lib/yard/lint/validators/tags/redundant_param_description/parser.rb
 - lib/yard/lint/validators/tags/redundant_param_description/result.rb
 - lib/yard/lint/validators/tags/redundant_param_description/validator.rb
+- lib/yard/lint/validators/tags/tag_group_separator.rb
+- lib/yard/lint/validators/tags/tag_group_separator/config.rb
+- lib/yard/lint/validators/tags/tag_group_separator/messages_builder.rb
+- lib/yard/lint/validators/tags/tag_group_separator/parser.rb
+- lib/yard/lint/validators/tags/tag_group_separator/result.rb
+- lib/yard/lint/validators/tags/tag_group_separator/validator.rb
 - lib/yard/lint/validators/tags/tag_type_position.rb
 - lib/yard/lint/validators/tags/tag_type_position/config.rb
 - lib/yard/lint/validators/tags/tag_type_position/messages_builder.rb
@@ -190,11 +224,13 @@ files:
 - lib/yard/lint/validators/warnings/unknown_directive/validator.rb
 - lib/yard/lint/validators/warnings/unknown_parameter_name.rb
 - lib/yard/lint/validators/warnings/unknown_parameter_name/config.rb
+- lib/yard/lint/validators/warnings/unknown_parameter_name/messages_builder.rb
 - lib/yard/lint/validators/warnings/unknown_parameter_name/parser.rb
 - lib/yard/lint/validators/warnings/unknown_parameter_name/result.rb
 - lib/yard/lint/validators/warnings/unknown_parameter_name/validator.rb
 - lib/yard/lint/validators/warnings/unknown_tag.rb
 - lib/yard/lint/validators/warnings/unknown_tag/config.rb
+- lib/yard/lint/validators/warnings/unknown_tag/messages_builder.rb
 - lib/yard/lint/validators/warnings/unknown_tag/parser.rb
 - lib/yard/lint/validators/warnings/unknown_tag/result.rb
 - lib/yard/lint/validators/warnings/unknown_tag/validator.rb

data/lib/yard/lint/command_cache.rb

@@ -1,93 +0,0 @@
-# frozen_string_literal: true
-
-module Yard
-  module Lint
-    # Cache for YARD command executions to avoid running identical commands multiple times
-    # This provides a transparent optimization layer - validators don't need to know about it
-    class CommandCache
-      def initialize
-        @cache = {}
-        @hits = 0
-        @misses = 0
-      end
-
-      # Execute a command through the cache
-      # If the command has been executed before, return cached result
-      # Otherwise execute and cache the result
-      # @param command_string [String] the shell command to execute
-      # @return [Hash] hash with stdout, stderr, exit_code keys
-      # @note Returns a deep clone to prevent validators from modifying cached data
-      def execute(command_string)
-        cache_key = generate_cache_key(command_string)
-
-        if @cache.key?(cache_key)
-          @hits += 1
-          deep_clone(@cache[cache_key])
-        else
-          @misses += 1
-          result = execute_command(command_string)
-          @cache[cache_key] = deep_clone(result)
-          result
-        end
-      end
-
-      # Get cache statistics
-      # @return [Hash] hash with hits, misses, and total executions
-      def stats
-        {
-          hits: @hits,
-          misses: @misses,
-          total: @hits + @misses,
-          saved_executions: @hits
-        }
-      end
-
-      private
-
-      # Generate a cache key for the command
-      # Normalizes the command to handle whitespace differences
-      # @param command_string [String] the command to generate key for
-      # @return [String] SHA256 hash of normalized command
-      def generate_cache_key(command_string)
-        # Normalize whitespace: collapse multiple spaces/newlines into single spaces
-        normalized = command_string.strip.gsub(/\s+/, ' ')
-        Digest::SHA256.hexdigest(normalized)
-      end
-
-      # Actually execute the command
-      # @param command_string [String] the command to execute
-      # @return [Hash] hash with stdout, stderr, exit_code keys
-      def execute_command(command_string)
-        # Set up environment to load IRB shim before YARD (Ruby 3.5+ compatibility)
-        env = build_environment_with_shim
-
-        stdout, stderr, status = Open3.capture3(env, command_string)
-        {
-          stdout: stdout,
-          stderr: stderr,
-          exit_code: status.exitstatus
-        }
-      end
-
-      # Build environment hash with RUBYOPT to load IRB shim
-      # This ensures the shim is loaded in subprocesses (like yard list commands)
-      # @return [Hash] environment variables for command execution
-      def build_environment_with_shim
-        shim_path = File.expand_path('ext/irb_notifier_shim.rb', __dir__)
-        rubyopt = "-r#{shim_path}"
-
-        # Preserve existing RUBYOPT if present
-        rubyopt = "#{ENV['RUBYOPT'].strip} #{rubyopt}" if ENV['RUBYOPT']
-
-        { 'RUBYOPT' => rubyopt }
-      end
-
-      # Deep clone a hash to prevent modifications to cached data
-      # @param hash [Hash] the hash to clone
-      # @return [Hash] deep cloned hash
-      def deep_clone(hash)
-        Marshal.load(Marshal.dump(hash))
-      end
-    end
-  end
-end