yard-lint 1.0.0 → 1.2.0

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module ExampleSyntax
+          # Validator to check syntax of code in @example tags
+          class Validator < Base
+            private
+
+            # Runs yard list query to find objects with invalid syntax in @example 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}")
+
+              shell(cmd)
+            end
+
+            # @return [String] yard query to find @example tags with syntax errors
+            def query
+              <<~QUERY
+                '
+                  if object.has_tag?(:example)
+                    example_tags = object.tags(:example)
+
+                    example_tags.each_with_index do |example, index|
+                      code = example.text
+                      next if code.nil? || code.empty?
+
+                      # Clean the code: strip output indicators (#=>) and everything after it
+                      code_lines = code.split("\\n").map do |line|
+                        line.sub(/\\s*#\\s*=>.*$/, "")
+                      end
+
+                      cleaned_code = code_lines.join("\\n").strip
+                      next if cleaned_code.empty?
+
+                      # Check if code looks incomplete (single expression without context)
+                      # Skip validation for these cases
+                      lines = cleaned_code.split("\\n").reject { |l| l.strip.empty? || l.strip.start_with?("#") }
+
+                      # Skip if it is a single line that looks like an incomplete expression
+                      if lines.size == 1
+                        line = lines.first.strip
+                        # Skip method calls, variable references, or simple expressions
+                        # These are likely incomplete snippets showing usage
+                        if line.match?(/^[a-z_][a-z0-9_]*(\\.| |$)/) || line.match?(/^[A-Z]/) && !line.match?(/^(class|module|def)\\s/)
+                          next
+                        end
+                      end
+
+                      # Try to parse the code
+                      begin
+                        RubyVM::InstructionSequence.compile(cleaned_code)
+                      rescue SyntaxError => e
+                        # Report syntax errors
+                        example_name = example.name || "Example " + (index + 1).to_s
+                        puts object.file + ":" + object.line.to_s + ": " + object.title
+                        puts "syntax_error"
+                        puts example_name
+                        puts e.message
+                      rescue => e
+                        # Other errors (like NameError, ArgumentError) are fine
+                        # We only check syntax, not semantics
+                        next
+                      end
+                    end
+                  end
+                  false
+                '
+              QUERY
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      # Tags validators - validate YARD tag quality and consistency
+      module Tags
+        # ExampleSyntax validator
+        #
+        # Validates Ruby syntax in `@example` tags using RubyVM::InstructionSequence.compile().
+        # This validator ensures that code examples in documentation are syntactically valid.
+        # It automatically strips output indicators (`#=>`) and skips incomplete single-line
+        # snippets. This validator is enabled by default.
+        #
+        # @example Bad - Invalid Ruby syntax in example
+        #   # @example
+        #   #   def broken(
+        #   #     # missing closing
+        #   def my_method
+        #   end
+        #
+        # @example Good - Valid Ruby syntax in example
+        #   # @example
+        #   #   def my_method(name)
+        #   #     puts name
+        #   #   end
+        #   def my_method(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/ExampleSyntax:
+        #       Enabled: false
+        #
+        module ExampleSyntax
+        end
+      end
+    end
+  end
+end

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

@@ -77,14 +77,14 @@ module Yard
             # @return [String] tags names for which we want to check the invalid tags
             #   types definitions
             def checked_tags_names
-              validated_tags = config.validator_config('Tags/InvalidTypes', 'ValidatedTags')
+              validated_tags = config_or_default('ValidatedTags')
               query_array(validated_tags)
             end
 
             # @return [String] extra names that we allow for types definitions in a yard
             #   query acceptable form
             def allowed_types_code
-              extra_types = config.validator_config('Tags/InvalidTypes', 'ExtraTypes') || []
+              extra_types = config_or_default('ExtraTypes')
               query_array(ALLOWED_DEFAULTS + extra_types)
             end
 

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

@@ -4,7 +4,31 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # InvalidTypes validator module
+        # InvalidTypes validator
+        #
+        # Detects invalid or malformed type annotations in YARD tags. This validator
+        # checks that type specifications follow YARD's type syntax rules and that
+        # type names are valid. This validator is enabled by default.
+        #
+        # @example Bad - Invalid type syntax
+        #   # @param name [String | Integer] the name (wrong pipe syntax)
+        #   # @return [Array[String]] invalid nested syntax
+        #   def process(name)
+        #   end
+        #
+        # @example Good - Valid type syntax
+        #   # @param name [String, Integer] the name (comma-separated union)
+        #   # @return [Array<String>] valid nested syntax
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/InvalidTypes:
+        #       Enabled: false
+        #
         module InvalidTypes
         end
       end

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

@@ -67,14 +67,12 @@ module Yard
 
             # @return [Array<String>] tags that should only appear on methods
             def checked_tags
-              config.validator_config('Tags/MeaninglessTag', 'CheckedTags') || %w[param option]
+              config_or_default('CheckedTags')
             end
 
             # @return [Array<String>] object types that shouldn't have method-only tags
             def invalid_object_types
-              config.validator_config('Tags/MeaninglessTag', 'InvalidObjectTypes') || %w[
-                class module constant
-              ]
+              config_or_default('InvalidObjectTypes')
             end
           end
         end

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