yard-lint 0.2.1 → 1.1.0

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/documentation/undocumented_objects.rb

@@ -4,8 +4,137 @@ module Yard
   module Lint
     module Validators
       module Documentation
-        # UndocumentedObjects validator module
-        # This validator checks for missing documentation on objects
+        # UndocumentedObjects validator
+        #
+        # Checks for missing documentation on classes, modules, and methods.
+        # This validator supports flexible method exclusions through the `ExcludedMethods`
+        # configuration option.
+        #
+        # ## Pattern Types
+        #
+        # The `ExcludedMethods` feature supports three pattern types for maximum flexibility:
+        #
+        # ### 1. Exact Name Matching
+        #
+        # Excludes methods with the specified name, regardless of arity:
+        #
+        #     ExcludedMethods:
+        #       - 'to_s'           # Excludes ALL to_s methods regardless of parameters
+        #       - 'inspect'        # Excludes ALL inspect methods
+        #
+        # Note: Exact name matching excludes the method with **any arity**. If you need
+        # arity-specific exclusions, use arity notation instead.
+        #
+        # ### 2. Arity Notation (method_name/N)
+        #
+        # Excludes methods with specific parameter counts:
+        #
+        #     ExcludedMethods:
+        #       - 'initialize/0'   # Only excludes initialize with NO parameters (default)
+        #       - 'call/1'         # Only excludes call methods with exactly 1 parameter
+        #       - 'initialize/2'   # Only excludes initialize with exactly 2 parameters
+        #
+        # Note: Arity counts total parameters (required + optional) excluding splat (*)
+        # and block (&) parameters.
+        #
+        # ### 3. Regex Patterns
+        #
+        # Excludes methods matching a regular expression:
+        #
+        #     ExcludedMethods:
+        #       - '/^_/'           # Excludes all methods starting with underscore (private convention)
+        #       - '/^test_/'       # Excludes all test methods
+        #       - '/_(helper|util)$/' # Excludes methods ending with _helper or _util
+        #
+        # ## Configuration Examples
+        #
+        # ### Minimal setup - Only exclude parameter-less initialize
+        #
+        #     Documentation/UndocumentedObjects:
+        #       ExcludedMethods:
+        #         - 'initialize/0'
+        #
+        # ### Common Rails/Ruby patterns
+        #
+        #     Documentation/UndocumentedObjects:
+        #       ExcludedMethods:
+        #         - 'initialize/0'       # Parameter-less constructors
+        #         - '/^_/'               # Private methods (by convention)
+        #         - 'to_s'               # String conversion
+        #         - 'inspect'            # Object inspection
+        #         - 'hash'               # Hash code generation
+        #         - 'eql?'               # Equality comparison
+        #         - '=='                 # Binary equality operator
+        #         - '<=>'                # Spaceship operator (comparison)
+        #         - '+'                  # Addition operator
+        #         - '-'                  # Subtraction operator
+        #         - '+@'                 # Unary plus operator
+        #         - '-@'                 # Unary minus operator
+        #
+        # ### Test framework exclusions
+        #
+        #     Documentation/UndocumentedObjects:
+        #       ExcludedMethods:
+        #         - '/^test_/'           # Minitest methods
+        #         - '/^should_/'         # Shoulda methods
+        #         - 'setup/0'            # Setup with no params
+        #         - 'teardown/0'         # Teardown with no params
+        #
+        # ## Pattern Validation & Edge Cases
+        #
+        # The `ExcludedMethods` feature includes robust validation and error handling:
+        #
+        # **Automatic Pattern Sanitization:**
+        # - **Nil values** are automatically removed
+        # - **Empty strings** and whitespace-only patterns are filtered out
+        # - **Whitespace trimming** is applied to all patterns
+        # - **Empty regex patterns** (`//`) are rejected (would match everything)
+        # - **Non-array values** are automatically converted to arrays
+        #
+        # **Invalid Pattern Handling:**
+        # - **Invalid regex patterns** (e.g., `/[/`, `/(unclosed`) are silently skipped without crashing
+        # - **Invalid arity notation** (e.g., `method/abc`, `method/`) is silently skipped
+        # - **Pattern matching is case-sensitive** for both exact names and regex
+        #
+        # **Operator Method Support:**
+        # YARD-Lint fully supports Ruby operator methods including:
+        # - Binary operators: `+`, `-`, `*`, `/`, `%`, `**`, `==`, `!=`, `===`, `<`, `>`,
+        #   `<=`, `>=`, `<=>`, `&`, `|`, `^`, `<<`, `>>`
+        # - Unary operators: `+@`, `-@`, `!`, `~`
+        # - Other special methods: `[]`, `[]=`, `=~`
+        #
+        # **Pattern Matching Behavior:**
+        # - **Any match excludes**: If a method matches any pattern, it is excluded from validation
+        # - **Patterns are evaluated in order** as defined in the configuration
+        # - **Exact names have no arity restriction**: `'initialize'` excludes all initialize
+        #   methods, regardless of parameters
+        # - **Arity notation is strict**: `'initialize/0'` only excludes initialize with
+        #   exactly 0 parameters
+        #
+        # ## Troubleshooting
+        #
+        # ### Methods still showing as undocumented
+        #
+        # 1. Verify the method name matches exactly (case-sensitive)
+        # 2. Check if you're using arity notation - ensure the arity count is correct
+        # 3. For regex patterns, test your regex independently to ensure it matches
+        # 4. Remember: Arity counts `required + optional` parameters, **excluding**
+        #    splat (`*args`) and block (`&block`)
+        #
+        # ### Regex patterns not working
+        #
+        # 1. Ensure you're using `/pattern/` format with forward slashes
+        # 2. Test the regex in Ruby: `Regexp.new('your_pattern').match?('method_name')`
+        # 3. Escape special regex characters: `\.`, `\(`, `\)`, `\[`, `\]`, etc.
+        # 4. Invalid regex patterns are silently skipped - check for syntax errors
+        #
+        # ### Arity not matching
+        #
+        # 1. Count parameters correctly: `def method(a, b = 1)` has arity 2 (required + optional)
+        # 2. Splat parameters don't count: `def method(a, *rest)` has arity 1
+        # 3. Block parameters don't count: `def method(a, &block)` has arity 1
+        # 4. Keyword arguments count as individual parameters: `def method(a:, b:)` has arity 2
+        #
         module UndocumentedObjects
         end
       end

data/lib/yard/lint/validators/documentation/undocumented_options/config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedOptions
+          # Configuration for UndocumentedOptions validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :undocumented_options
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'warning'
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedOptions
+          # Parses YARD output for undocumented options violations
+          class Parser < Parsers::Base
+            # Parse YARD output into structured violations
+            # @param output [String] raw YARD output
+            # @return [Array<Hash>] array of violation hashes
+            def call(output)
+              return [] if output.nil? || output.empty?
+
+              violations = []
+              lines = output.lines.map(&:chomp)
+
+              i = 0
+              while i < lines.size
+                line = lines[i]
+
+                # Match location line: "file:line: object_name"
+                if (location_match = line.match(/^(.+):(\d+): (.+)$/))
+                  file_path = location_match[1]
+                  line_number = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  # Next line contains parameter list
+                  i += 1
+                  next unless i < lines.size
+
+                  params = lines[i]
+
+                  violations << {
+                    location: file_path,
+                    line: line_number,
+                    object_name: object_name,
+                    params: params
+                  }
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_options/result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedOptions
+          # Result object for undocumented options validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'UndocumentedOptions'
+
+            # Build human-readable message for undocumented options offense
+            # @param offense [Hash] offense data with :object_name and :params
+            # @return [String] formatted message
+            def build_message(offense)
+              object_name = offense[:object_name]
+              params = offense[:params]
+
+              "Method '#{object_name}' has options parameter (#{params}) " \
+                'but no @option tags in documentation.'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module UndocumentedOptions
+          # Validates that methods with options hash parameters have @option tags
+          class Validator < Validators::Base
+            # YARD query to detect methods with options parameters but no @option tags
+            # @return [String] YARD Ruby query code
+            def query
+              <<~QUERY.strip
+                'if object.is_a?(YARD::CodeObjects::MethodObject); params = object.parameters || []; has_options_param = params.any? { |p| p[0] =~ /^(options?|opts?|kwargs)$/ || p[0] =~ /^\\*\\*/ || (p[0] =~ /^(options?|opts?|kwargs)$/ && p[1] =~ /^\\{\\}/) }; if has_options_param; option_tags = object.tags(:option); if option_tags.empty?; puts object.file + ":" + object.line.to_s + ": " + object.title; puts params.map { |p| p.join(" ") }.join(", "); end; end; end; false'
+              QUERY
+            end
+
+            # Builds and executes the YARD command to detect undocumented options
+            # @param dir [String] the directory containing the .yardoc database
+            # @param file_list_path [String] path to file containing list of files to analyze
+            # @return [String] command output
+            def yard_cmd(dir, file_list_path)
+              cmd = <<~CMD
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
+                  #{shell_arguments} \
+                --query #{query} \
+                -q \
+                -b #{Shellwords.escape(dir)}
+              CMD
+              cmd = cmd.tr("\n", ' ')
+              shell(cmd)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/undocumented_options.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # UndocumentedOptions validator
+        #
+        # Checks that options hashes have detailed documentation about their keys.
+        # When a method accepts an options hash parameter, the individual option
+        # keys should be documented using `@option` tags. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Options parameter without @option tags
+        #   # Configures the service
+        #   # @param options [Hash] configuration options
+        #   def configure(options)
+        #   end
+        #
+        # @example Good - Options keys documented with @option tags
+        #   # Configures the service
+        #   # @param options [Hash] configuration options
+        #   # @option options [Boolean] :enabled Whether to enable the feature
+        #   # @option options [Integer] :timeout Connection timeout in seconds
+        #   def configure(options)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/UndocumentedOptions:
+        #       Enabled: false
+        #
+        module UndocumentedOptions
+        end
+      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/semantic/abstract_methods.rb

@@ -4,7 +4,37 @@ module Yard
   module Lint
     module Validators
       module Semantic
-        # AbstractMethods validator module
+        # AbstractMethods validator
+        #
+        # Ensures that methods marked with `@abstract` are actually abstract (not
+        # implemented). Abstract methods should either raise NotImplementedError or
+        # be empty stubs, not contain actual implementation logic. This validator
+        # is enabled by default.
+        #
+        # @example Bad - @abstract tag on implemented method
+        #   # @abstract
+        #   def process
+        #     puts "This is actually implemented!"
+        #   end
+        #
+        # @example Good - @abstract method raises NotImplementedError
+        #   # @abstract
+        #   def process
+        #     raise NotImplementedError
+        #   end
+        #
+        # @example Good - @abstract method is empty
+        #   # @abstract
+        #   def process
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Semantic/AbstractMethods:
+        #       Enabled: false
+        #
         module AbstractMethods
         end
       end

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/api_tags.rb

@@ -4,7 +4,40 @@ module Yard
   module Lint
     module Validators
       module Tags
-        # ApiTags validator module
+        # ApiTags validator
+        #
+        # Enforces that all public classes, modules, and methods have an `@api` tag
+        # to explicitly document their API visibility level. This validator is disabled
+        # by default and must be explicitly enabled.
+        #
+        # ## Configuration
+        #
+        # To enable this validator (it's disabled by default):
+        #
+        #     Tags/ApiTags:
+        #       Enabled: true
+        #       AllowedApis:
+        #         - public
+        #         - private
+        #
+        # @example Good - Methods and classes have @api tags
+        #   # @api public
+        #   class MyClass
+        #     # @api public
+        #     def public_method
+        #     end
+        #
+        #     # @api private
+        #     def internal_helper
+        #     end
+        #   end
+        #
+        # @example Bad - Missing @api tags
+        #   class AnotherClass
+        #     def some_method
+        #     end
+        #   end
+        #
         module ApiTags
         end
       end

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

@@ -0,0 +1,22 @@
+# 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],
+              'EnforcedStyle' => 'long' # 'long' (Hash{K => V}) or 'short' ({K => V})
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# 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]
+                detected_style = offense[:detected_style]
+
+                # Extract the corrected version based on detected style
+                corrected = suggest_correction(type_string, detected_style)
+                style_description = detected_style == 'short' ? 'long' : 'short'
+
+                "Use #{style_description} collection syntax #{corrected} instead of " \
+                  "#{type_string} in @#{tag_name} tag."
+              end
+
+              private
+
+              # Suggests the corrected YARD syntax based on detected style
+              # @param type_string [String] the incorrect type string
+              # @param detected_style [String] the detected style ('short' or 'long')
+              # @return [String] the suggested correction
+              def suggest_correction(type_string, detected_style)
+                if detected_style == 'short'
+                  # Convert short to long: Hash<K, V> -> Hash{K => V} or {K => V} -> Hash{K => V}
+                  convert_to_long(type_string)
+                else
+                  # Convert long to short: Hash{K => V} -> {K => V}
+                  convert_to_short(type_string)
+                end
+              end
+
+              # Converts short syntax to long syntax
+              # @param type_string [String] the type string
+              # @return [String] the converted type string
+              def convert_to_long(type_string)
+                if type_string.start_with?('{')
+                  # {K => V} -> Hash{K => V}
+                  "Hash#{type_string}"
+                else
+                  # Hash<K, V> -> 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
+
+              # Converts long syntax to short syntax
+              # @param type_string [String] the type string
+              # @return [String] the converted type string
+              def convert_to_short(type_string)
+                # Hash{K => V} -> {K => V}
+                type_string.sub(/^Hash/, '')
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# 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|detected_style"
+                details = details_line.split('|', 3)
+                next unless details.size == 3
+
+                tag_name, type_string, detected_style = 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,
+                  detected_style: detected_style
+                }
+              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