yard-lint 1.2.3 → 1.3.0

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

@@ -7,112 +7,136 @@ module Yard
         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('|')
+            # Enable in-process execution
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Checks for redundant/meaningless parameter descriptions.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+            def in_process_query(object, collector)
+              return unless object.is_a?(YARD::CodeObjects::MethodObject)
+
+              articles = config_articles
+              generic_terms = config_generic_terms.map(&:downcase)
+              connectors = config_low_value_connectors.map(&:downcase)
+              low_value_verbs = config_low_value_verbs.map(&:downcase)
               max_words = config_max_redundant_words
-              checked_tags = config_checked_tags
+              tags_to_check = 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}'"
+              object.docstring.tags.each do |tag|
+                next unless tags_to_check.include?(tag.tag_name)
+                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 = detect_pattern(
+                  param_name, description, type_name, word_count,
+                  articles, generic_terms, connectors, low_value_verbs, patterns
+                )
+
+                next unless pattern_type
+
+                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                collector.puts "#{tag.tag_name}|#{param_name}|#{tag.text.strip}|#{type_name || ''}|#{pattern_type}|#{word_count}"
+              end
             end
+            # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+
+            private
+
+            # Detect the type of redundant pattern
+            # @param param_name [String] parameter name
+            # @param description [String] description text
+            # @param type_name [String, nil] type annotation
+            # @param word_count [Integer] number of words in description
+            # @param articles [Array<String>] article words
+            # @param generic_terms [Array<String>] generic terms
+            # @param connectors [Array<String>] low-value connectors
+            # @param low_value_verbs [Array<String>] low-value verbs
+            # @param patterns [Hash] enabled pattern flags
+            # @return [String, nil] pattern type or nil
+            # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/ParameterLists
+            def detect_pattern(param_name, description, type_name, word_count, articles, generic_terms, connectors, low_value_verbs, patterns)
+              desc_parts = description.split
+              articles_re = /^(#{articles.join('|')})/i
+
+              # ArticleParam pattern
+              if patterns['ArticleParam'] && word_count <= 3 && desc_parts.length == 2
+                if desc_parts[0].match?(articles_re) && desc_parts[1].downcase == param_name.downcase
+                  return 'article_param'
+                end
+              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
+              # PossessiveParam pattern
+              if patterns['PossessiveParam'] && word_count <= 4 && desc_parts.length >= 3
+                if desc_parts[0].match?(articles_re) && desc_parts[1].end_with?('s') &&
+                   desc_parts[1].include?("'") && desc_parts[2].downcase == param_name.downcase
+                  return 'possessive_param'
+                end
+              end
+
+              # TypeRestatement pattern
+              if patterns['TypeRestatement'] && type_name && word_count <= 2
+                if description.downcase == type_name.downcase
+                  return 'type_restatement'
+                elsif word_count == 2
+                  parts = description.split
+                  if parts[0].downcase == type_name.downcase && generic_terms.include?(parts[1].downcase)
+                    return 'type_restatement'
+                  end
+                end
+              end
+
+              # ParamToVerb pattern
+              if patterns['ParamToVerb'] && word_count <= 4 && desc_parts.length == 3
+                if desc_parts[0].downcase == param_name.downcase && desc_parts[1].downcase == 'to'
+                  return 'param_to_verb'
+                end
+              end
+
+              # IdPattern
+              if patterns['IdPattern'] && word_count <= 6 && param_name =~ /_id$|_uuid$|_identifier$/
+                if description =~ /^(ID|Unique identifier|Identifier)\s+(of|for)\s+/i
+                  return 'id_pattern'
+                end
+              end
+
+              # DirectionalDate pattern
+              if patterns['DirectionalDate'] && word_count <= 4 && param_name =~ /^(from|to|till|until)$/
+                if desc_parts.length == 3 && desc_parts[0].downcase == param_name.downcase && desc_parts[1].downcase == 'this'
+                  return 'directional_date'
+                end
+              end
+
+              # TypeGeneric pattern
+              if patterns['TypeGeneric'] && type_name && word_count <= 5 && desc_parts.length >= 2
+                if desc_parts[0].downcase == type_name.downcase && generic_terms.include?(desc_parts[1].downcase)
+                  return 'type_generic'
+                end
+              end
+
+              # ArticleParamPhrase pattern: "The action being performed"
+              if patterns['ArticleParamPhrase'] && word_count >= 3 && desc_parts.length >= 3 &&
+                 desc_parts[0].match?(articles_re) &&
+                 desc_parts[1].downcase == param_name.downcase &&
+                 connectors.include?(desc_parts[2].downcase) &&
+                 (desc_parts.length == 3 ||
+                  (desc_parts.length == 4 && low_value_verbs.include?(desc_parts[3].downcase)))
+                return 'article_param_phrase'
+              end
+
+              nil
             end
+            # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/ParameterLists
 
             private
 
@@ -126,6 +150,16 @@ module Yard
               config_or_default('GenericTerms')
             end
 
+            # @return [Array<String>] configured low-value connectors
+            def config_low_value_connectors
+              config_or_default('LowValueConnectors')
+            end
+
+            # @return [Array<String>] configured low-value verbs
+            def config_low_value_verbs
+              config_or_default('LowValueVerbs')
+            end
+
             # @return [Integer] maximum word count for redundant descriptions
             def config_max_redundant_words
               config_or_default('MaxRedundantWords')

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

@@ -159,7 +159,6 @@ module Yard
         #
         #     Tags/RedundantParamDescription:
         #       Enabled: false
-        #
         module RedundantParamDescription
         end
       end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagGroupSeparator
+          # Configuration for TagGroupSeparator validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :tag_group_separator
+            self.defaults = {
+              'Enabled' => false,
+              'Severity' => 'convention',
+              'TagGroups' => {
+                'param' => %w[param option],
+                'return' => %w[return],
+                'error' => %w[raise throws],
+                'example' => %w[example],
+                'meta' => %w[see note todo deprecated since version api],
+                'yield' => %w[yield yieldparam yieldreturn]
+              },
+              'RequireAfterDescription' => false
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagGroupSeparator
+          # Builds messages for missing tag group separator offenses.
+          class MessagesBuilder
+            class << self
+              # Build message for missing tag group separator.
+              #
+              # @param offense [Hash] offense data with :method_name and :separators keys
+              #
+              # @return [String] formatted message
+              def call(offense)
+                transitions = parse_transitions(offense[:separators])
+
+                if transitions.size == 1
+                  from, to = transitions.first
+                  "The `#{offense[:method_name]}` is missing a blank line between " \
+                    "`#{from}` and `#{to}` tag groups."
+                else
+                  formatted = transitions.map { |from, to| "`#{from}` -> `#{to}`" }.join(', ')
+                  "The `#{offense[:method_name]}` is missing blank lines between tag groups: " \
+                    "#{formatted}."
+                end
+              end
+
+              private
+
+              # Parses transition string into array of [from, to] pairs.
+              #
+              # @param separators [String] string in format "from->to,from->to"
+              #
+              # @return [Array<Array<String>>] array of [from, to] pairs
+              def parse_transitions(separators)
+                separators
+                  .to_s
+                  .split(',')
+                  .map { |transition| transition.split('->') }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagGroupSeparator
+          # Parser for extracting tag group separator violations from raw validator output.
+          #
+          # @example Output format
+          #   /path/to/file.rb:10: ClassName#method_name
+          #   param->return,return->error
+          class Parser < Parsers::Base
+            # Regexp to extract only word and numeric parts of the location line
+            NORMALIZATION_REGEXP = /\w+/
+
+            private_constant :NORMALIZATION_REGEXP
+
+            # Parses raw validator output into structured offense data.
+            #
+            # @param yard_list [String] raw validator output string
+            #
+            # @return [Array<Hash>] array of hashes with offense details
+            def call(yard_list)
+              return [] if yard_list.nil? || yard_list.empty?
+
+              base_hash = {}
+
+              yard_list.split("\n").each_slice(2).each do |location, separators|
+                next if location.nil? || separators.nil?
+
+                key = normalize(location)
+
+                if separators == 'valid'
+                  base_hash[key] = 'valid'
+                else
+                  base_hash[key] ||= [location, separators]
+                end
+              end
+
+              base_hash.delete_if { |_key, value| value == 'valid' }
+              separator_data = base_hash.values.map(&:last)
+
+              Validators::Documentation::UndocumentedMethodArguments::Parser
+                .new
+                .call(base_hash.values.map(&:first).join("\n"))
+                .each.with_index { |element, index| element[:separators] = separator_data[index] }
+            end
+
+            private
+
+            # Normalizes a location line by extracting only word and numeric characters.
+            #
+            # @param location_line [String] full line with the location
+            #
+            # @return [String] normalized line without special characters
+            def normalize(location_line)
+              location_line
+                .scan(NORMALIZATION_REGEXP)
+                .join
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagGroupSeparator
+          # Result object for tag group separator validation.
+          # Transforms parsed separator violations into offense objects.
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'method'
+            self.offense_name = 'MissingTagGroupSeparator'
+
+            # Build human-readable message for tag group separator offense.
+            #
+            # @param offense [Hash] offense data with :method_name and :separators keys
+            #
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagGroupSeparator
+          # Validates that blank lines separate different groups of YARD documentation tags.
+          #
+          # This validator enforces visual separation between semantically different tag
+          # groups (e.g., @param tags should be separated from @return tags by a blank line).
+          class Validator < Base
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
+
+            # Execute query for a single object during in-process execution.
+            # Checks if different tag groups are separated by blank lines.
+            #
+            # @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?
+
+              docstring = object.docstring.all
+              return if docstring.nil? || docstring.empty?
+
+              missing_separators = find_missing_separators(docstring)
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+
+              if missing_separators.empty?
+                collector.puts 'valid'
+              else
+                collector.puts missing_separators.map { |s| "#{s[:from]}->#{s[:to]}" }.join(',')
+              end
+            end
+
+            private
+
+            # Find all locations where a blank line separator is missing between tag groups.
+            #
+            # @param docstring [String] the raw docstring content
+            #
+            # @return [Array<Hash>] array of hashes with :from and :to group names
+            def find_missing_separators(docstring)
+              lines = docstring.split("\n")
+              missing = []
+
+              previous_group = require_after_description? ? 'description' : nil
+              had_blank_line = true
+
+              lines.each do |line|
+                stripped = line.strip
+
+                if stripped.empty?
+                  had_blank_line = true
+                  next
+                end
+
+                if stripped.start_with?('@')
+                  tag_name = stripped.match(/^@(\S+)/)&.captures&.first
+                  next unless tag_name
+
+                  current_group = group_for_tag(tag_name)
+
+                  if previous_group && current_group != previous_group && !had_blank_line
+                    missing << { from: previous_group, to: current_group }
+                  end
+
+                  previous_group = current_group
+                elsif previous_group.nil? && require_after_description?
+                  # Non-tag, non-blank line (continuation or description)
+                  # Only set description group if we haven't seen tags yet
+                  previous_group = 'description'
+                end
+
+                had_blank_line = false
+              end
+
+              missing
+            end
+
+            # Determine which group a tag belongs to.
+            #
+            # @param tag_name [String] the tag name without the @ prefix
+            #
+            # @return [String] the group name, or the tag name itself if not in any group
+            def group_for_tag(tag_name)
+              tag_groups.each do |group_name, tags|
+                return group_name if tags.include?(tag_name)
+              end
+
+              # Tags not in any configured group are their own group
+              tag_name
+            end
+
+            # @return [Hash] configured tag groups
+            def tag_groups
+              @tag_groups ||= config.validator_config('Tags/TagGroupSeparator', 'TagGroups') ||
+                              Config.defaults['TagGroups']
+            end
+
+            # @return [Boolean] whether to require separator after description
+            def require_after_description?
+              @require_after_description ||= config.validator_config(
+                'Tags/TagGroupSeparator',
+                'RequireAfterDescription'
+              ) || false
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # TagGroupSeparator validator
+        #
+        # Enforces blank line separators between different groups of YARD documentation
+        # tags. This improves readability by visually grouping semantically related tags.
+        # This validator is disabled by default.
+        #
+        # @example Bad - No separator between @param and @return
+        #   # @param organization_id [String] the organization ID
+        #   # @param id [String] the pet ID
+        #   # @return [Pet] the pet object
+        #   def call(organization_id, id)
+        #   end
+        #
+        # @example Good - Blank line separates tag groups
+        #   # @param organization_id [String] the organization ID
+        #   # @param id [String] the pet ID
+        #   #
+        #   # @return [Pet] the pet object
+        #   def call(organization_id, id)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To enable this validator:
+        #
+        #     Tags/TagGroupSeparator:
+        #       Enabled: true
+        #
+        # To customize tag groups:
+        #
+        #     Tags/TagGroupSeparator:
+        #       Enabled: true
+        #       TagGroups:
+        #         param: [param, option]
+        #         return: [return]
+        #         error: [raise]
+        #         yield: [yield, yieldparam, yieldreturn]
+        module TagGroupSeparator
+        end
+      end
+    end
+  end
+end