yard-lint 1.0.0 → 1.1.0

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

@@ -4,9 +4,37 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # MeaninglessTag validator module
-        # Detects @param and @option tags on classes, modules, or constants
-        # (these tags only make sense on methods)
+        # 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

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

@@ -29,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
@@ -52,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.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

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Tags validators - validate YARD tag quality and consistency
+      module Tags
+        # RedundantParamDescription validator
+        #
+        # Detects parameter descriptions that add no meaningful information beyond
+        # what's already obvious from the parameter name and type. This validator
+        # helps maintain high-quality documentation by flagging descriptions that
+        # should either be expanded with meaningful details or removed entirely.
+        #
+        # ## Why This Matters
+        #
+        # Documentation is most valuable when AI assistants and human developers
+        # can trust it. Redundant descriptions like `@param user [User] The user`
+        # create noise without adding value, training both humans and AI to ignore
+        # parameter documentation. Better to have no description (letting the type
+        # speak for itself) than a redundant one.
+        #
+        # @example Redundant - Article + param name (will be flagged)
+        #   # @param appointment [Appointment] The appointment
+        #   # @param user [User] the user
+        #   def process(appointment, user)
+        #   end
+        #
+        # @example Redundant - Possessive form (will be flagged)
+        #   # @param appointment [Appointment] The event's appointment
+        #   def schedule(appointment)
+        #   end
+        #
+        # @example Redundant - Type restatement (will be flagged)
+        #   # @param user [User] User object
+        #   # @param value [Integer] Integer value
+        #   def update(user, value)
+        #   end
+        #
+        # @example Redundant - Parameter to verb pattern (will be flagged)
+        #   # @param payments [Array] Payments to count
+        #   # @param user [User] User to notify
+        #   def process(payments, user)
+        #   end
+        #
+        # @example Redundant - ID pattern (will be flagged)
+        #   # @param treatment_id [String] ID of the treatment
+        #   # @param uuid [String] Unique identifier for the list
+        #   def find(treatment_id, uuid)
+        #   end
+        #
+        # @example Redundant - Directional date (will be flagged)
+        #   # @param from [Date] from this date
+        #   # @param till [Date] till this date
+        #   def filter(from, till)
+        #   end
+        #
+        # @example Redundant - Type + generic term (will be flagged)
+        #   # @param payment [Payment] Payment object
+        #   # @param data [Hash] Hash data
+        #   def process(payment, data)
+        #   end
+        #
+        # @example Good - No description (type is self-explanatory)
+        #   # @param appointment [Appointment]
+        #   # @param user [User]
+        #   def process(appointment, user)
+        #   end
+        #
+        # @example Good - Long, meaningful descriptions with context
+        #   # @param date [Date, nil] the date that can describe the event starting information or nil if event did not yet start
+        #   # @param user [User] the user who initiated the request and will receive notifications
+        #   # @param data [Hash] configuration options for the API endpoint including timeout and retry settings
+        #   def configure(date, user, data)
+        #   end
+        #
+        # @example Good - Short but adds value beyond param name
+        #   # @param count [Integer] maximum number of retries before giving up
+        #   # @param timeout [Integer] seconds to wait before timing out the connection
+        #   # @param enabled [Boolean] whether the feature is enabled for this account
+        #   def setup(count, timeout, enabled)
+        #   end
+        #
+        # @example Good - Starts similar but continues with valuable info
+        #   # @param user [User] the current user, or guest if not authenticated
+        #   # @param data [Hash] the request payload containing user preferences
+        #   # @param id [String] unique identifier used for tracking across systems
+        #   def track(user, data, id)
+        #   end
+        #
+        # ## Configuration
+        #
+        # The validator is highly configurable to match your project's needs:
+        #
+        #     Tags/RedundantParamDescription:
+        #       Description: 'Detects meaningless parameter descriptions.'
+        #       Enabled: true
+        #       Severity: convention
+        #       CheckedTags:
+        #         - param
+        #         - option
+        #       # Articles that trigger the article_param pattern
+        #       Articles:
+        #         - The
+        #         - the
+        #         - A
+        #         - a
+        #         - An
+        #         - an
+        #       # Maximum word count for redundant descriptions (longer descriptions are never flagged)
+        #       MaxRedundantWords: 6
+        #       # Generic terms that trigger the type_generic pattern
+        #       GenericTerms:
+        #         - object
+        #         - instance
+        #         - value
+        #         - data
+        #         - item
+        #         - element
+        #       # Pattern toggles (enable/disable specific detection patterns)
+        #       EnabledPatterns:
+        #         ArticleParam: true        # "The user", "the appointment"
+        #         PossessiveParam: true     # "The event's appointment"
+        #         TypeRestatement: true     # "User object", "Appointment"
+        #         ParamToVerb: true         # "Payments to count"
+        #         IdPattern: true           # "ID of the treatment" for *_id params
+        #         DirectionalDate: true     # "from this date" for from/to/till
+        #         TypeGeneric: true         # "Payment object", "Hash data"
+        #
+        # ## Pattern Types
+        #
+        # The validator detects 7 different redundancy patterns:
+        #
+        # 1. **ArticleParam**: `"The user"`, `"the appointment"` - Article + parameter name
+        # 2. **PossessiveParam**: `"The event's appointment"` - Possessive form + parameter name
+        # 3. **TypeRestatement**: `"User object"`, `"Appointment"` - Just repeats the type
+        # 4. **ParamToVerb**: `"Payments to count"` - Parameter name + "to" + verb
+        # 5. **IdPattern**: `"ID of the treatment"` - For `_id` or `_uuid` suffixed parameters
+        # 6. **DirectionalDate**: `"from this date"` - For `from`, `to`, `till` parameters
+        # 7. **TypeGeneric**: `"Payment object"` - Type + generic term like "object", "instance"
+        #
+        # You can disable individual patterns while keeping others enabled.
+        #
+        # ## False Positive Prevention
+        #
+        # The validator uses multiple strategies to prevent false positives:
+        #
+        # 1. **Word count threshold**: Descriptions longer than `MaxRedundantWords` (default: 6)
+        #    are never flagged, even if they start with a redundant pattern
+        # 2. **EXACT pattern matching**: Only flags complete matches, not partial/prefix matches
+        # 3. **Configurable patterns**: Disable patterns that don't work for your codebase
+        #
+        # This means `"the date that can describe the event starting information"` (9 words)
+        # will never be flagged, even though it starts with "the date".
+        #
+        # ## Disabling
+        #
+        # To disable this validator:
+        #
+        #     Tags/RedundantParamDescription:
+        #       Enabled: false
+        #
+        module RedundantParamDescription
+        end
+      end
+    end
+  end
+end

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

@@ -94,15 +94,13 @@ module Yard
 
             # @return [String] the enforced style ('type_after_name' (standard) or 'type_first')
             def enforced_style
-              config.validator_config('Tags/TagTypePosition', 'EnforcedStyle') || 'type_after_name'
+              config_or_default('EnforcedStyle')
             end
 
             # Array of tag names to check, formatted for YARD query
             # @return [String] Ruby array literal string
             def checked_tags_array
-              tags = config.validator_config(
-                'Tags/TagTypePosition', 'CheckedTags'
-              ) || %w[param option]
+              tags = config_or_default('CheckedTags')
               "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
             end
           end