yard-lint 1.2.3 → 1.3.0.rc1

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

@@ -7,63 +7,31 @@ module Yard
         module MeaninglessTag
           # Validates that @param/@option tags only appear on methods
           class Validator < Base
-            private
-
-            # Runs YARD query to find @param/@option tags on non-methods
-            # @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("--private --protected #{shell_arguments} -b #{Shellwords.escape(dir)}\n")
-                f.flush
-                f.chmod(0o755)
-
-                shell("bash #{Shellwords.escape(f.path)}")
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
+
+            # Execute query for a single object during in-process execution.
+            # Checks for @param/@option tags on non-method objects.
+            # @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)
+              object_type = object.type.to_s
+              invalid_types = invalid_object_types
+              tags_to_check = checked_tags
+
+              return unless invalid_types.include?(object_type)
+
+              object.docstring.tags.each do |tag|
+                next unless tags_to_check.include?(tag.tag_name)
+
+                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                collector.puts "#{object_type}|#{tag.tag_name}"
+                break
               end
             end
 
-            # YARD query that finds method-only tags on non-method objects
-            # Format output as two lines per violation:
-            #   Line 1: file.rb:LINE: ClassName
-            #   Line 2: object_type|tag_name
-            # @return [String] YARD query string
-            def query
-              <<~QUERY.strip
-                '
-                object_type = object.type.to_s
-
-                if #{invalid_object_types_array}.include?(object_type)
-                  docstring.tags.each do |tag|
-                    if #{checked_tags_array}.include?(tag.tag_name)
-                      puts object.file + ":" + object.line.to_s + ": " + object.title
-                      puts object_type + "|" + tag.tag_name
-                      break
-                    end
-                  end
-                end
-
-                false
-                '
-              QUERY
-            end
-
-            # Array of tag names to check, formatted for YARD query
-            # @return [String] Ruby array literal string
-            def checked_tags_array
-              "[#{checked_tags.map { |t| "\"#{t}\"" }.join(',')}]"
-            end
-
-            # Array of invalid object types, formatted for YARD query
-            # @return [String] Ruby array literal string
-            def invalid_object_types_array
-              "[#{invalid_object_types.map { |t| "\"#{t}\"" }.join(',')}]"
-            end
+            private
 
             # @return [Array<String>] tags that should only appear on methods
             def checked_tags

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

@@ -34,7 +34,6 @@ module Yard
         #       @name = name
         #     end
         #   end
-        #
         module MeaninglessTag
         end
       end

data/lib/yard/lint/validators/tags/non_ascii_type/config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module NonAsciiType
+          # Configuration for NonAsciiType validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :non_ascii_type
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning',
+              'ValidatedTags' => %w[param option return yieldreturn yieldparam]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module NonAsciiType
+          # Builds human-readable messages for non-ASCII type violations
+          class MessagesBuilder
+            class << self
+              # Formats a non-ASCII type violation message
+              # @param offense [Hash] offense details with tag_name, type_string, character, codepoint
+              # @return [String] formatted message
+              def call(offense)
+                tag = offense[:tag_name]
+                type = offense[:type_string]
+                char = offense[:character]
+                codepoint = offense[:codepoint]
+
+                "Type specification in @#{tag} tag contains non-ASCII character " \
+                  "'#{char}' (#{codepoint}) in '#{type}'. Ruby type names must use ASCII characters only."
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module NonAsciiType
+          # Parser for NonAsciiType validator output
+          # Parses output that reports non-ASCII characters in type specifications
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses validator output and extracts non-ASCII type violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ClassName#method_name
+            #   tag_name|type_string|character|codepoint
+            # @param yard_output [String] raw validator query results
+            # @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?
+
+              # Handle potential encoding issues
+              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|
+                next unless location_line && details_line
+
+                # Parse location: "file.rb:10: ClassName#method_name"
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # Parse details: "tag_name|type_string|character|codepoint"
+                details = details_line.split('|', 4)
+                next unless details.size == 4
+
+                tag_name, type_string, character, codepoint = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  method_name: location_match[3],
+                  tag_name: tag_name,
+                  type_string: type_string,
+                  character: character,
+                  codepoint: codepoint
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/non_ascii_type/result.rb

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

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module NonAsciiType
+          # Validates that type specifications contain only ASCII characters
+          # Ruby type names must be valid Ruby identifiers (ASCII only)
+          class Validator < Base
+            # Enable in-process execution
+            in_process visibility: :public
+
+            # Pattern to match non-ASCII characters
+            NON_ASCII_PATTERN = /[^\x00-\x7F]/
+
+            # Execute query for a single object during in-process execution.
+            # Checks type specifications for non-ASCII characters.
+            # @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/NonAsciiType', 'ValidatedTags') ||
+                               %w[param option return yieldreturn yieldparam]
+
+              object.docstring.tags
+                    .select { |tag| validated_tags.include?(tag.tag_name) }
+                    .each do |tag|
+                next unless tag.types
+
+                tag.types.each do |type_str|
+                  non_ascii_chars = type_str.scan(NON_ASCII_PATTERN).uniq
+                  next if non_ascii_chars.empty?
+
+                  # Format: file:line: object_title
+                  # Then: tag_name|type_string|char|codepoint
+                  non_ascii_chars.each do |char|
+                    codepoint = format('U+%04X', char.ord)
+                    collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                    collector.puts "#{tag.tag_name}|#{type_str}|#{char}|#{codepoint}"
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # NonAsciiType validator
+        #
+        # Detects non-ASCII characters in YARD type specifications. Ruby type names
+        # must be valid Ruby identifiers which only support ASCII characters. Non-ASCII
+        # characters in type specifications are usually the result of copy-paste errors
+        # from word processors that use smart typography (e.g., `…` instead of `...`).
+        #
+        # This validator is enabled by default.
+        #
+        # @example Bad - Non-ASCII characters in type specification
+        #   # @param flags [Symbol, …] variadic flags
+        #   # @return [String→Integer] transformation result
+        #   def process(flags)
+        #   end
+        #
+        # @example Good - Valid ASCII type syntax
+        #   # @param flags [Symbol] variadic flags
+        #   # @return [Hash{String => Integer}] transformation result
+        #   def process(flags)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/NonAsciiType:
+        #       Enabled: false
+        module NonAsciiType
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/option_tags/result.rb

@@ -24,14 +24,14 @@ module Yard
             # @return [Array<Hash>] array of offense hashes
             def build_offenses
               @parsed_data.map do |offense_data|
-                {
+                offense_data.merge(
                   severity: configured_severity,
                   type: self.class.offense_type,
                   name: offense_data[:name] || self.class.offense_name,
                   message: build_message(offense_data),
                   location: offense_data[:location] || offense_data[:file],
                   location_line: offense_data[:line] || offense_data[:location_line] || 0
-                }
+                )
               end
             end
           end

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

@@ -7,53 +7,38 @@ module Yard
         module OptionTags
           # Validator to check methods with options hash have @option tags
           class Validator < Base
-            private
-
-            # Runs yard list query to find methods with options parameter but missing @option tags
-            # @param dir [String] dir where the yard db is (or where it should be generated)
-            # @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 list \
-                --private \
-                --protected \
-                -b #{Shellwords.escape(dir)}
-              CMD
-              cmd = cmd.tr("\n", ' ')
-              cmd = cmd.gsub('yard list', "yard list --query #{query}")
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
 
-              shell(cmd)
-            end
+            # Execute query for a single object during in-process execution.
+            # Checks if methods with options parameter have @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.is_a?(YARD::CodeObjects::MethodObject)
 
-            # @return [String] yard query to find methods with options parameter
-            #   but no @option tags
-            def query
               parameter_names = config_parameter_names
-              <<~QUERY
-                '
-                  if object.is_a?(YARD::CodeObjects::MethodObject)
-                      # Check if method has a parameter named "options" or "opts"
-                    has_options_param = object.parameters.any? do |param|
-                      param_name = param[0].to_s.gsub(/[*:]/, '')
-                      #{parameter_names.inspect}.include?(param_name)
-                      end
 
-                    if has_options_param
-                        # Check if method has any @option tags
-                      option_tags = object.tags(:option)
+              # Check if method has a parameter named "options" or "opts" etc.
+              has_options_param = object.parameters.any? do |param|
+                param_name = param[0].to_s.gsub(/[*:]/, '')
+                parameter_names.include?(param_name)
+              end
+
+              return unless has_options_param
 
-                      if option_tags.empty?
-                        puts object.file + ':' + object.line.to_s + ': ' + object.title
-                        puts 'missing_option_tags'
-                        end
-                      end
-                    end
-                  false
-                '
-              QUERY
+              # Check if method has any @option tags
+              option_tags = object.tags(:option)
+
+              return unless option_tags.empty?
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts 'missing_option_tags'
             end
 
+            private
+
             # @return [Array<String>] parameter names that should have @option tags
             def config_parameter_names
               config.validator_config('Tags/OptionTags', 'ParameterNames') || Config.defaults['ParameterNames']

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

@@ -29,7 +29,6 @@ module Yard
         #   # @param options [Hash] configuration options
         #   def configure(name, options = {})
         #   end
-        #
         module OptionTags
         end
       end

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

@@ -8,78 +8,51 @@ module Yard
           # Runs a query that will pick all the objects that have docs with tags in an invalid
           #   order. By invalid we mean, that they are not as defined in the settings.
           class Validator < Base
-            private
-
-            # Runs yard list query with proper settings on a given dir and files
-            # @param dir [String] dir where the yard db is (or where it should be generated)
-            # @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 list \
-                --private \
-                --protected \
-                --query #{query} \
-                -b #{Shellwords.escape(dir)}
-              CMD
-
-              result = shell(cmd)
-              result[:stdout] = { result: result[:stdout], tags_order: tags_order }
-              result
-            end
-
-            # @return [String] multiline yard query that we use to find methods with
-            #   tags that are not in the valid order
-            # @note We need to print things for all of the elements as some of them
-            #   are listed in yard twice (for example module functions), and for the
-            #   second time, yard injects things by itself making it impossible to
-            #   figure out whether the order is ok or now. That's why we print all and those
-            #   that are ok, we mark with 'valid' and if it is reported later as invalid again,
-            #   we know, that it is valid
-            def query
-              <<-QUERY
-            '
-              tags_order = #{query_array(tags_order)}
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
+
+            # Execute query for a single object during in-process execution.
+            # Checks if tags appear in the configured order.
+            # @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 if object.is_alias?
+
+              # Extract @tag names from docstring
+              tag_pattern = /^@(\S+)/
+              doc_tags = object.docstring.all.scan(tag_pattern).flatten
+
+              # Remove consecutive duplicates
               accu = []
-              str = "@"
-              slash = 92.chr
-              regexp = "^"+str+"("+slash+"S+)"
-              doc_tags = object.docstring.all.scan(Regexp.new(regexp)).flatten
-
               doc_tags.each do |param|
                 accu << param unless accu.last == param
               end
 
-              tags_order.delete_if { |el| !accu.include?(el) }
-              accu.delete_if { |el| !tags_order.include?(el) }
+              # Filter to only configured tags
+              order = tags_order.dup
+              order.delete_if { |el| !accu.include?(el) }
+              accu.delete_if { |el| !order.include?(el) }
 
-              tags_orders = tags_order.join.to_i(36)
+              # Compare order using base-36 encoding
+              tags_orders = order.join.to_i(36)
               accus = accu.join.to_i(36)
 
-              puts object.file + ":" + object.line.to_s + ": " + object.title
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
 
-              if accus != tags_orders && !is_alias?
-                puts tags_order.join(",")
+              if accus != tags_orders
+                collector.puts order.join(',')
               else
-                puts "valid"
+                collector.puts 'valid'
               end
-
-              false
-            ' \\
-              QUERY
             end
 
+            private
+
             # @return [Array<String>] tags order
             def tags_order
               config.validator_config('Tags/Order', 'EnforcedOrder')
             end
-
-            # @param elements [Array<String>] array of elements that we want to convert into
-            #   a string ruby yard query array form
-            # @return [String] array of elements for yard query converted into a string
-            def query_array(elements)
-              "[#{elements.map { |type| "\"#{type}\"" }.join(',')}]"
-            end
           end
         end
       end

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

@@ -28,7 +28,6 @@ module Yard
         #
         #     Tags/Order:
         #       Enabled: false
-        #
         module Order
         end
       end

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

@@ -15,6 +15,19 @@ module Yard
               'Articles' => %w[The the A a An an],
               'MaxRedundantWords' => 6,
               'GenericTerms' => %w[object instance value data item element],
+              'LowValueConnectors' => %w[being to that which for],
+              'LowValueVerbs' => %w[
+                perform performed performing
+                process processed processing
+                use used using
+                handle handled handling
+                act acted acting
+                pass passed passing
+                invoke invoked invoking
+                call called calling
+                execute executed executing
+                run running
+              ],
               'EnabledPatterns' => {
                 'ArticleParam' => true,
                 'PossessiveParam' => true,
@@ -22,7 +35,8 @@ module Yard
                 'ParamToVerb' => true,
                 'IdPattern' => true,
                 'DirectionalDate' => true,
-                'TypeGeneric' => true
+                'TypeGeneric' => true,
+                'ArticleParamPhrase' => true
               }
             }.freeze
           end

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

@@ -48,6 +48,11 @@ module Yard
                 'The @' + tag_name + ' description \'' + description + '\' just combines type and generic terms. ' \
                 'Consider removing it or providing specific details about this ' + param_name + '.'
 
+              when 'article_param_phrase'
+                'The @' + tag_name + ' description \'' + description + '\' is a filler phrase that adds no value ' \
+                'beyond the parameter name. ' \
+                'Consider removing it or explaining the specific purpose of ' + param_name + '.'
+
               else
                 'The @' + tag_name + ' description \'' + description + '\' appears redundant. ' \
                 'Consider providing a meaningful description or omitting it entirely.'