yard-lint 0.2.1 → 1.1.0

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        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)}")
+              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
+
+            # @return [Array<String>] tags that should only appear on methods
+            def checked_tags
+              config_or_default('CheckedTags')
+            end
+
+            # @return [Array<String>] object types that shouldn't have method-only tags
+            def invalid_object_types
+              config_or_default('InvalidObjectTypes')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # MeaninglessTag validator
+        #
+        # Prevents `@param` and `@option` tags from being used on classes, modules,
+        # or constants, where they make no sense. These tags are only valid on methods.
+        # This validator is enabled by default.
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/MeaninglessTag:
+        #       Enabled: false
+        #
+        # @example Bad - @param on a class
+        #   # @param name [String] this makes no sense on a class
+        #   class User
+        #   end
+        #
+        # @example Bad - @option on a module
+        #   # @option config [Boolean] :enabled modules don't have parameters
+        #   module Authentication
+        #   end
+        #
+        # @example Good - @param on a method
+        #   class User
+        #     # @param name [String] the user's name
+        #     def initialize(name)
+        #       @name = name
+        #     end
+        #   end
+        #
+        module MeaninglessTag
+        end
+      end
+    end
+  end
+end

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

@@ -11,15 +11,14 @@ module Yard
 
             # 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 escaped_file_names [String] files for which we want to get the stats
+            # @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, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard list \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
                 --private \
                 --protected \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
               cmd = cmd.gsub('yard list', "yard list --query #{query}")
@@ -30,13 +29,14 @@ module Yard
             # @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(/[*:]/, '')
-                      ['options', 'opts', 'kwargs'].include?(param_name)
+                      #{parameter_names.inspect}.include?(param_name)
                       end
 
                     if has_options_param
@@ -53,6 +53,11 @@ module Yard
                 '
               QUERY
             end
+
+            # @return [Array<String>] parameter names that should have @option tags
+            def config_parameter_names
+              config.validator_config('Tags/OptionTags', 'ParameterNames') || Config.defaults['ParameterNames']
+            end
           end
         end
       end

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

@@ -4,7 +4,32 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # OptionTags validator module
+        # OptionTags validator
+        #
+        # Ensures that methods with options parameters document them using `@option`
+        # tags. This validator is enabled by default.
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/OptionTags:
+        #       Enabled: false
+        #
+        # @example Good - Options hash is documented
+        #   # @param name [String] the name
+        #   # @param options [Hash] configuration options
+        #   # @option options [Boolean] :enabled Whether to enable the feature
+        #   # @option options [Integer] :timeout Timeout in seconds
+        #   def configure(name, options = {})
+        #   end
+        #
+        # @example Bad - Missing @option tags
+        #   # @param name [String] the name
+        #   # @param options [Hash] configuration options
+        #   def configure(name, options = {})
+        #   end
+        #
         module OptionTags
         end
       end

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

@@ -12,16 +12,15 @@ module Yard
 
             # 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 escaped_file_names [String] files for which we want to get the stats
+            # @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, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard list \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
                 --private \
                 --protected \
                 --query #{query} \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
 
               result = shell(cmd)

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

@@ -4,7 +4,31 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # Order validator module
+        # Order validator
+        #
+        # Enforces a consistent order for YARD documentation tags. This validator
+        # checks that tags appear in a logical sequence (e.g., `@param` before
+        # `@return`, `@option` after `@param`). This validator is enabled by default.
+        #
+        # @example Bad - Tags in wrong order
+        #   # @return [String] the result
+        #   # @param name [String] the name
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Tags in correct order
+        #   # @param name [String] the name
+        #   # @return [String] the result
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/Order:
+        #       Enabled: false
+        #
         module Order
         end
       end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module RedundantParamDescription
+          # Configuration for RedundantParamDescription validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :redundant_param_description
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'convention',
+              'CheckedTags' => %w[param option],
+              'Articles' => %w[The the A a An an],
+              'MaxRedundantWords' => 6,
+              'GenericTerms' => %w[object instance value data item element],
+              'EnabledPatterns' => {
+                'ArticleParam' => true,
+                'PossessiveParam' => true,
+                'TypeRestatement' => true,
+                'ParamToVerb' => true,
+                'IdPattern' => true,
+                'DirectionalDate' => true,
+                'TypeGeneric' => true
+              }
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module RedundantParamDescription
+          # Builds human-readable messages for redundant parameter description violations
+          class MessagesBuilder
+            # Build message for a violation
+            # @param offense [Hash] the offense data
+            # @return [String] formatted message
+            def self.call(offense)
+              tag_name = offense[:tag_name]
+              param_name = offense[:param_name]
+              description = offense[:description]
+              pattern_type = offense[:pattern_type]
+
+              case pattern_type
+              when 'article_param'
+                'The @' + tag_name + ' description \'' + description + '\' is redundant - ' \
+                'it just restates the parameter name. ' \
+                'Consider removing the description: @' + tag_name + ' ' + param_name + ' [Type]'
+
+              when 'possessive_param'
+                'The @' + tag_name + ' description \'' + description + '\' adds no meaningful information ' \
+                'beyond the parameter name. ' \
+                'Consider removing it or explaining the parameter\'s specific purpose.'
+
+              when 'type_restatement'
+                'The @' + tag_name + ' description \'' + description + '\' just repeats the type name. ' \
+                'Consider removing the description or explaining what makes this ' + param_name + ' significant.'
+
+              when 'param_to_verb'
+                'The @' + tag_name + ' description \'' + description + '\' is too generic. ' \
+                'Consider removing it or explaining what the ' + param_name + ' is used for in detail.'
+
+              when 'id_pattern'
+                'The @' + tag_name + ' description \'' + description + '\' is self-explanatory from the parameter name. ' \
+                'Consider removing the description: @' + tag_name + ' ' + param_name + ' [Type]'
+
+              when 'directional_date'
+                'The @' + tag_name + ' description \'' + description + '\' is redundant - ' \
+                'the parameter name already indicates this. ' \
+                'Consider removing the description or explaining the date\'s specific meaning.'
+
+              when 'type_generic'
+                'The @' + tag_name + ' description \'' + description + '\' just combines type and generic terms. ' \
+                'Consider removing it or providing specific details about this ' + param_name + '.'
+
+              else
+                'The @' + tag_name + ' description \'' + description + '\' appears redundant. ' \
+                'Consider providing a meaningful description or omitting it entirely.'
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module RedundantParamDescription
+          # Parses YARD output for redundant parameter description violations
+          class Parser < Parsers::Base
+            # Parse YARD output into structured violations
+            # @param yard_output [String] raw YARD output
+            # @return [Array<Hash>] array of violation hashes
+            def call(yard_output)
+              return [] if yard_output.nil? || yard_output.empty?
+
+              violations = []
+              lines = yard_output.lines.map(&:chomp)
+
+              i = 0
+              while i < lines.length
+                line = lines[i]
+
+                # Match location line: "file:line: object_name"
+                location_match = line.match(/^(.+):(\d+): (.+)$/)
+                unless location_match
+                  i += 1
+                  next
+                end
+
+                file_path = location_match[1]
+                line_number = location_match[2].to_i
+                object_name = location_match[3]
+
+                # Next line contains violation data
+                i += 1
+                next unless i < lines.length
+
+                data_line = lines[i]
+                parts = data_line.split('|')
+                next unless parts.length == 6
+
+                tag_name, param_name, description, type_name, pattern_type, word_count = parts
+
+                violations << {
+                  name: 'RedundantParamDescription',
+                  tag_name: tag_name,
+                  param_name: param_name,
+                  description: description,
+                  type_name: type_name.empty? ? nil : type_name,
+                  pattern_type: pattern_type,
+                  word_count: word_count.to_i,
+                  location: file_path,
+                  line: line_number,
+                  object_name: object_name
+                }
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module RedundantParamDescription
+          # Result builder for redundant parameter description violations
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'tag'
+            self.offense_name = 'RedundantParamDescription'
+
+            # Build human-readable message for redundant param offense
+            # @param offense [Hash] offense data with redundancy 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/redundant_param_description/validator.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module RedundantParamDescription
+          # Validates that parameter descriptions are not redundant/meaningless
+          class Validator < Validators::Base
+            # YARD query to detect redundant parameter descriptions
+            # @return [String] YARD Ruby query code
+            def query
+              articles = config_articles.join('|')
+              generic_terms = config_generic_terms.join('|')
+              max_words = config_max_redundant_words
+              checked_tags = config_checked_tags
+              patterns = config_enabled_patterns
+
+              # Build query as single line for shell compatibility
+              query_body = 'if object.is_a?(YARD::CodeObjects::MethodObject); ' \
+                "object.docstring.tags.select { |tag| #{checked_tags.inspect}.include?(tag.tag_name) }.each do |tag|; " \
+                'next unless tag.name && tag.text && !tag.text.strip.empty?; ' \
+                'param_name = tag.name; ' \
+                'description = tag.text.strip.gsub(/\\.$/, ""); ' \
+                'word_count = description.split.length; ' \
+                'type_name = tag.types&.first&.gsub(/[<>{}\\[\\],]/, "")&.strip; ' \
+                "next if word_count > #{max_words}; " \
+                'pattern_type = nil; ' \
+                "if #{patterns['ArticleParam']} && word_count <= 3; " \
+                "articles_re = /^(#{articles})/i; " \
+                'desc_parts = description.split; ' \
+                'if desc_parts.length == 2 && desc_parts[0].match?(articles_re) && desc_parts[1].downcase == param_name.downcase; ' \
+                'pattern_type = "article_param"; ' \
+                'end; ' \
+                'end; ' \
+                "if pattern_type.nil? && #{patterns['PossessiveParam']} && word_count <= 4; " \
+                'desc_parts = description.split; ' \
+                'if desc_parts.length >= 3; ' \
+                "articles_re = /^(#{articles})/i; " \
+                'if desc_parts[0].match?(articles_re) && desc_parts[1].end_with?("s") && desc_parts[1].include?(39.chr) && desc_parts[2].downcase == param_name.downcase; ' \
+                'pattern_type = "possessive_param"; ' \
+                'end; ' \
+                'end; ' \
+                'end; ' \
+                "if pattern_type.nil? && #{patterns['TypeRestatement']} && type_name && word_count <= 2; " \
+                "generic_terms_arr = [\"#{generic_terms.gsub('|', '\", \"')}\"].map(&:downcase); " \
+                'if description.downcase == type_name.downcase; ' \
+                'pattern_type = "type_restatement"; ' \
+                'elsif word_count == 2; ' \
+                'parts = description.split; ' \
+                'if parts[0].downcase == type_name.downcase && generic_terms_arr.include?(parts[1].downcase); ' \
+                'pattern_type = "type_restatement"; ' \
+                'end; ' \
+                'end; ' \
+                'end; ' \
+                "if pattern_type.nil? && #{patterns['ParamToVerb']} && word_count <= 4; " \
+                'parts = description.split; ' \
+                'if parts.length == 3 && parts[0].downcase == param_name.downcase && parts[1].downcase == "to"; ' \
+                'pattern_type = "param_to_verb"; ' \
+                'end; ' \
+                'end; ' \
+                "if pattern_type.nil? && #{patterns['IdPattern']} && word_count <= 6; " \
+                'if param_name =~ /_id$|_uuid$|_identifier$/; ' \
+                'if description =~ /^(ID|Unique identifier|Identifier)\\s+(of|for)\\s+/i; ' \
+                'pattern_type = "id_pattern"; ' \
+                'end; ' \
+                'end; ' \
+                'end; ' \
+                "if pattern_type.nil? && #{patterns['DirectionalDate']} && word_count <= 4; " \
+                'if param_name =~ /^(from|to|till|until)$/; ' \
+                'parts = description.split; ' \
+                'if parts.length == 3 && parts[0].downcase == param_name.downcase && parts[1].downcase == "this"; ' \
+                'pattern_type = "directional_date"; ' \
+                'end; ' \
+                'end; ' \
+                'end; ' \
+                "if pattern_type.nil? && #{patterns['TypeGeneric']} && type_name && word_count <= 5; " \
+                "generic_terms_arr = [\"#{generic_terms.gsub('|', '\", \"')}\"].map(&:downcase); " \
+                'parts = description.split; ' \
+                'if parts.length >= 2 && parts[0].downcase == type_name.downcase && generic_terms_arr.include?(parts[1].downcase); ' \
+                'pattern_type = "type_generic"; ' \
+                'end; ' \
+                'end; ' \
+                'if pattern_type; ' \
+                'puts object.file + ":" + object.line.to_s + ": " + object.title; ' \
+                'puts tag.tag_name + "|" + param_name + "|" + tag.text.strip + "|" + (type_name || "") + "|" + pattern_type + "|" + word_count.to_s; ' \
+                'end; ' \
+                'end; ' \
+                'end; ' \
+                'false'
+
+              # Wrap in single quotes like other validators do
+              "'#{query_body}'"
+            end
+
+            # Builds and executes the YARD command
+            # @param dir [String] the directory containing the .yardoc database
+            # @param file_list_path [String] path to file containing list of files to analyze
+            # @return [Hash] command output with stdout, stderr, exit_code
+            def yard_cmd(dir, file_list_path)
+              # Create a temporary script file to avoid shell escaping issues
+              require 'tempfile'
+
+              script = Tempfile.new(['yard_lint_query', '.sh'])
+              script.write("#!/bin/bash\n")
+              # Write query to a variable - since query already has outer single quotes, just assign it
+              script.write("QUERY=#{query}\n")
+              script.write("cat #{Shellwords.escape(file_list_path)} | xargs yard list #{shell_arguments} --query \"$QUERY\" -q -b #{Shellwords.escape(dir)}\n")
+              script.chmod(0o755)
+              script.close
+
+              result = shell(script.path)
+              script.unlink
+              result
+            end
+
+            private
+
+            # @return [Array<String>] configured articles to check
+            def config_articles
+              config_or_default('Articles')
+            end
+
+            # @return [Array<String>] configured generic terms to check
+            def config_generic_terms
+              config_or_default('GenericTerms')
+            end
+
+            # @return [Integer] maximum word count for redundant descriptions
+            def config_max_redundant_words
+              config_or_default('MaxRedundantWords')
+            end
+
+            # @return [Array<String>] tags to check for redundant descriptions
+            def config_checked_tags
+              config_or_default('CheckedTags')
+            end
+
+            # @return [Hash] enabled pattern detection flags
+            def config_enabled_patterns
+              config_or_default('EnabledPatterns')
+            end
+          end
+        end
+      end
+    end
+  end
+end