yard-lint 0.2.0 → 1.0.0

data/lib/yard/lint/validators/documentation/undocumented_objects/parser.rb

@@ -8,14 +8,28 @@ module Yard
           # Class used to extract details about undocumented objects from raw yard list output
           # @example
           #   /path/to/file.rb:3: UndocumentedClass
-          #   /path/to/file.rb:4: UndocumentedClass#method_one
+          #   /path/to/file.rb:4: UndocumentedClass#method_one|2
           class Parser < ::Yard::Lint::Parsers::Base
-            # Regex used to parse yard list output format: file.rb:LINE: ObjectName
-            LINE_REGEX = /^(.+):(\d+): (.+)$/
+            # Regex used to parse yard list output format
+            # Format: file.rb:LINE: ObjectName or ObjectName|ARITY
+            LINE_REGEX = /^(.+):(\d+): (.+?)(?:\|(\d+))?$/
 
             # @param yard_list_output [String] raw yard list results string
+            # @param config [Yard::Lint::Config, nil] configuration object (optional)
+            # @param _kwargs [Hash] unused keyword arguments (for compatibility)
             # @return [Array<Hash>] Array with undocumented objects details
-            def call(yard_list_output)
+            def call(yard_list_output, config: nil, **_kwargs)
+              excluded_methods = config&.validator_config(
+                'Documentation/UndocumentedObjects',
+                'ExcludedMethods'
+              ) || []
+
+              # Ensure excluded_methods is an Array
+              excluded_methods = Array(excluded_methods)
+
+              # Sanitize patterns: remove nil, empty, whitespace-only, and normalize
+              excluded_methods = sanitize_patterns(excluded_methods)
+
               yard_list_output
                 .split("\n")
                 .map(&:strip)
@@ -24,13 +38,89 @@ module Yard
                   match = line.match(LINE_REGEX)
                   next unless match
 
+                  element = match[3]
+                  arity = match[4]&.to_i
+
+                  # Skip if method is in excluded list
+                  next if method_excluded?(element, arity, excluded_methods)
+
                   {
                     location: match[1],
                     line: match[2].to_i,
-                    element: match[3]
+                    element: element
                   }
                 end
             end
+
+            private
+
+            # Checks if a method should be excluded based on ExcludedMethods config
+            # Supports: simple names, arity notation, and regex patterns
+            # @param element [String] the element name (e.g., "Class#method")
+            # @param arity [Integer, nil] number of parameters (required + optional,
+            #   excluding splat and block)
+            # @param excluded_methods [Array<String>] list of exclusion patterns
+            # @return [Boolean] true if method should be excluded
+            def method_excluded?(element, arity, excluded_methods)
+              # Extract method name from element (e.g., "Foo::Bar#baz" -> "baz")
+              method_name = element.split(/[#.]/).last
+              return false unless method_name
+
+              excluded_methods.any? do |pattern|
+                case pattern
+                when %r{^/(.+)/$}
+                  # Regex pattern: '/^_/' matches methods starting with _
+                  match_regex_pattern(method_name, Regexp.last_match(1))
+                when %r{/\d+$}
+                  # Arity pattern: 'initialize/0' checks method name and parameter count
+                  match_arity_pattern(method_name, arity, pattern)
+                else
+                  # Simple name match: 'initialize'
+                  # Simple names match any arity (use arity notation for specific arity)
+                  method_name == pattern
+                end
+              end
+            end
+
+            # Sanitize exclusion patterns
+            # @param patterns [Array] raw patterns from config
+            # @return [Array<String>] cleaned and validated patterns
+            def sanitize_patterns(patterns)
+              patterns
+                .compact # Remove nil values
+                .map { |p| p.to_s.strip } # Convert to strings and trim whitespace
+                .reject(&:empty?) # Remove empty strings
+                .reject { |p| p == '//' } # Reject empty regex (matches everything)
+            end
+
+            # Match a regex pattern against method name with error handling
+            # @param method_name [String] the method name to match
+            # @param regex_pattern [String] the regex pattern (without delimiters)
+            # @return [Boolean] true if matches, false if invalid regex or no match
+            def match_regex_pattern(method_name, regex_pattern)
+              return false if regex_pattern.empty? # Empty regex would match everything
+
+              Regexp.new(regex_pattern).match?(method_name)
+            rescue RegexpError
+              # Invalid regex - skip this pattern
+              false
+            end
+
+            # Match an arity pattern like "initialize/0"
+            # @param method_name [String] the method name
+            # @param arity [Integer, nil] the method's arity
+            # @param pattern [String] the full pattern like "initialize/0"
+            # @return [Boolean] true if matches
+            def match_arity_pattern(method_name, arity, pattern)
+              pattern_name, pattern_arity_str = pattern.split('/')
+
+              # Validate arity is numeric
+              return false unless pattern_arity_str.match?(/^\d+$/)
+
+              pattern_arity = pattern_arity_str.to_i
+
+              method_name == pattern_name && arity == pattern_arity
+            end
           end
         end
       end

data/lib/yard/lint/validators/documentation/undocumented_objects/validator.rb

@@ -7,30 +7,34 @@ module Yard
         module UndocumentedObjects
           # Runs yard list to check for undocumented objects
           class Validator < Base
-            # Query to find all objects without documentation
-            QUERY = "'docstring.blank?'"
-
-            private_constant :QUERY
-
             private
 
             # Runs yard list query with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @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 \
                   #{shell_arguments} \
-                  --query #{QUERY} \
+                  --query #{query} \
                   -q \
-                  -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                  -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 
               shell(cmd)
             end
+
+            # Custom query that outputs parameter count for methods
+            # Format: file.rb:LINE: ElementName|ARITY
+            # Arity counts all parameters (required + optional) excluding splat and block
+            # @return [String] YARD query string
+            def query
+              <<~QUERY.chomp
+                "if docstring.all.empty? then if object.is_a?(YARD::CodeObjects::MethodObject) then arity = object.parameters.reject { |p| p[0].start_with?('*', '&') }.size; puts object.file + ':' + object.line.to_s + ': ' + object.title + '|' + arity.to_s; else puts object.file + ':' + object.line.to_s + ': ' + object.title; end; false; end"
+              QUERY
+            end
           end
         end
       end

data/lib/yard/lint/validators/semantic/abstract_methods/validator.rb

@@ -11,15 +11,14 @@ module Yard
 
             # Runs YARD list query to find abstract methods with implementation
             # @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 run YARD
+            # @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}")

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

@@ -11,15 +11,14 @@ module Yard
 
             # Runs yard list query to find objects missing or with invalid @api 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}")

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

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

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module CollectionType
+          # Builds human-readable messages for CollectionType violations
+          class MessagesBuilder
+            class << self
+              # Formats a violation message
+              # @param offense [Hash] the offense details
+              # @return [String] formatted message
+              def call(offense)
+                type_string = offense[:type_string]
+                tag_name = offense[:tag_name]
+
+                # Extract the corrected version
+                corrected = suggest_correction(type_string)
+
+                "Use YARD collection syntax #{corrected} instead of #{type_string} " \
+                  "in @#{tag_name} tag. YARD uses Hash{K => V} syntax for hashes."
+              end
+
+              private
+
+              # Suggests the corrected YARD syntax
+              # @param type_string [String] the incorrect type string
+              # @return [String] the suggested correction
+              def suggest_correction(type_string)
+                # Convert Hash<K, V> to Hash{K => V}
+                type_string.gsub(/Hash<(.+?)>/) do
+                  types = ::Regexp.last_match(1)
+                  # Split on comma, handle nested types
+                  "Hash{#{types.sub(/,\s*/, ' => ')}}"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module CollectionType
+          # Parses YARD output for CollectionType violations
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses YARD query output into structured violation data
+            # @param yard_output [String] raw output from YARD query
+            # @param _kwargs [Hash] additional keyword arguments (unused)
+            # @return [Array<Hash>] array of violation hashes
+            def call(yard_output, **_kwargs)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+              violations = []
+
+              lines.each_slice(2) do |location_line, details_line|
+                next unless location_line && details_line
+
+                # Parse location: "file.rb:10: ClassName#method_name"
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # Parse details: "tag_name|type_string"
+                details = details_line.split('|', 2)
+                next unless details.size == 2
+
+                tag_name, type_string = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  tag_name: tag_name,
+                  type_string: type_string
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module CollectionType
+          # Validates Hash collection type syntax in YARD tags
+          class Validator < Base
+            private
+
+            # Runs YARD query to find incorrect Hash<K, V> syntax
+            # @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("#{shell_arguments} -b #{Shellwords.escape(dir)}\n")
+                f.flush
+                f.chmod(0o755)
+
+                shell("bash #{Shellwords.escape(f.path)}")
+              end
+            end
+
+            # YARD query that finds Hash<K, V> syntax in type annotations
+            # Format output as two lines per violation:
+            #   Line 1: file.rb:LINE: ClassName#method_name
+            #   Line 2: tag_name|type_string
+            # @return [String] YARD query string
+            def query
+              <<~QUERY.strip
+                '
+                docstring
+                  .tags
+                  .select { |tag| #{validated_tags_array}.include?(tag.tag_name) }
+                  .each do |tag|
+                    next unless tag.types
+
+                    tag.types.each do |type_str|
+                      # Check for Hash<...> syntax (should be Hash{...})
+                      if type_str =~ /Hash<.*>/
+                        puts object.file + ":" + object.line.to_s + ": " + object.title
+                        puts tag.tag_name + "|" + type_str
+                        break
+                      end
+                    end
+                  end
+
+                false
+                '
+              QUERY
+            end
+
+            # Array of tag names to validate, formatted for YARD query
+            # @return [String] Ruby array literal string
+            def validated_tags_array
+              tags = config.validator_config('Tags/CollectionType', 'ValidatedTags') || %w[
+                param option return yieldreturn
+              ]
+              "[#{tags.map { |t| "\"#{t}\"" }.join(',')}]"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # CollectionType validator module
+        # Detects incorrect Hash collection syntax (Hash<K, V> instead of Hash{K => V})
+        module CollectionType
+        end
+      end
+    end
+  end
+end

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

@@ -24,17 +24,17 @@ 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)
               # Write query to a temporary file to avoid shell escaping issues
-              require 'tempfile'
+              squery = Shellwords.escape(query)
+              cmd = "cat #{Shellwords.escape(file_list_path)} | xargs yard list --query #{squery} "
 
               Tempfile.create(['yard_query', '.sh']) do |f|
                 f.write("#!/bin/bash\n")
-                f.write("yard list --query #{Shellwords.escape(query)} ")
-                f.write("--private --protected -b #{Shellwords.escape(dir)} ")
-                f.write("#{escaped_file_names}\n")
+                f.write(cmd)
+                f.write("--private --protected -b #{Shellwords.escape(dir)}\n")
                 f.flush
                 f.chmod(0o755)
 

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Configuration for MeaninglessTag validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :meaningless_tag
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning',
+              'CheckedTags' => %w[param option],
+              'InvalidObjectTypes' => %w[class module constant]
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Builds human-readable messages for MeaninglessTag violations
+          class MessagesBuilder
+            class << self
+              # Formats a meaningless tag violation message
+              # @param offense [Hash] offense details with :object_type, :tag_name, :object_name
+              # @return [String] formatted message
+              def call(offense)
+                object_type = offense[:object_type]
+                tag_name = offense[:tag_name]
+                object_name = offense[:object_name]
+
+                "The @#{tag_name} tag is meaningless on a #{object_type} " \
+                  "(#{object_name}). This tag only makes sense on methods."
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MeaninglessTag
+          # Parser for MeaninglessTag validator output
+          # Parses YARD query output that reports meaningless tags on non-methods
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses YARD output and extracts meaningless tag violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ClassName
+            #   object_type|tag_name
+            # @param yard_output [String] raw YARD query results
+            # @param _kwargs [Hash] unused keyword arguments (for compatibility)
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **_kwargs)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+              violations = []
+
+              lines.each_slice(2) do |location_line, details_line|
+                next unless location_line && details_line
+
+                # Parse location: "file.rb:10: ClassName"
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # Parse details: "object_type|tag_name"
+                details = details_line.split('|', 2)
+                next unless details.size == 2
+
+                object_type, tag_name = details
+
+                violations << {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  object_type: object_type,
+                  tag_name: tag_name
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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