yard-lint 1.0.0 → 1.1.0

data/lib/yard/lint/validators/base.rb

@@ -143,6 +143,42 @@ module Yard
         def shell(cmd)
           self.class.command_cache.execute(cmd)
         end
+
+        # Retrieves configuration value with fallback to default
+        # Automatically determines the validator name from the class namespace
+        #
+        # @param key [String] the configuration key to retrieve
+        # @return [Object] the configured value or default value from the validator's Config.defaults
+        # @note The validator name is automatically extracted from the class namespace.
+        #   For example, Yard::Lint::Validators::Tags::RedundantParamDescription::Validator
+        #   becomes 'Tags/RedundantParamDescription'
+        # @example Usage in a validator (e.g., Tags::RedundantParamDescription)
+        #   def config_articles
+        #     config_or_default('Articles')
+        #   end
+        def config_or_default(key)
+          validator_name = self.class.name&.split('::')&.then do |parts|
+            idx = parts.index('Validators')
+            next nil unless idx && parts[idx + 1] && parts[idx + 2]
+
+            "#{parts[idx + 1]}/#{parts[idx + 2]}"
+          end
+
+          # Get the validator module's Config class
+          validator_config_class = begin
+            # Get parent module (e.g., Yard::Lint::Validators::Tags::RedundantParamDescription)
+            parent_module = self.class.name.split('::')[0..-2].join('::')
+            Object.const_get("#{parent_module}::Config")
+          rescue NameError
+            nil
+          end
+
+          defaults = validator_config_class&.defaults || {}
+
+          return defaults[key] unless validator_name
+
+          config.validator_config(validator_name, key) || defaults[key]
+        end
       end
     end
   end

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

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

data/lib/yard/lint/validators/documentation/markdown_syntax/messages_builder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MarkdownSyntax
+          # Builds human-readable messages for MarkdownSyntax violations
+          class MessagesBuilder
+            # Maps markdown syntax error types to human-readable descriptions
+            ERROR_DESCRIPTIONS = {
+              'unclosed_backtick' => 'Unclosed backtick in documentation',
+              'unclosed_code_block' => 'Unclosed code block (```) in documentation',
+              'unclosed_bold' => 'Unclosed bold formatting (**) in documentation',
+              'invalid_list_marker' => 'Invalid list marker (use - or * instead)'
+            }.freeze
+
+            class << self
+              # Formats a violation message
+              # @param offense [Hash] the offense details
+              # @return [String] formatted message
+              def call(offense)
+                object_name = offense[:object_name]
+                errors = offense[:errors]
+
+                error_messages = errors.map do |error|
+                  if error.start_with?('invalid_list_marker:')
+                    line_num = error.split(':').last
+                    "#{ERROR_DESCRIPTIONS['invalid_list_marker']} at line #{line_num}"
+                  else
+                    ERROR_DESCRIPTIONS[error] || error
+                  end
+                end
+
+                "Markdown syntax errors in '#{object_name}': " \
+                  "#{error_messages.join(', ')}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MarkdownSyntax
+          # Parses YARD output for markdown syntax 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 error types
+                  i += 1
+                  next unless i < lines.size
+
+                  errors = lines[i].split('|')
+
+                  violations << {
+                    location: file_path,
+                    line: line_number,
+                    object_name: object_name,
+                    errors: errors
+                  }
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MarkdownSyntax
+          # Result object for markdown syntax validation
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'MarkdownSyntax'
+
+            # Build human-readable message for markdown syntax offense
+            # @param offense [Hash] offense data with :object_name and :errors
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module MarkdownSyntax
+          # Validates markdown syntax in documentation
+          class Validator < Validators::Base
+            # YARD query to extract docstrings and check for markdown errors
+            # @return [String] YARD Ruby query code
+            def query
+              <<~QUERY.strip
+                'docstring_text = object.docstring.to_s; unless docstring_text.empty?; errors = []; backtick_count = docstring_text.scan(/\\x60/).count; errors << "unclosed_backtick" if backtick_count.odd?; code_block_count = docstring_text.scan(/^```/).count; errors << "unclosed_code_block" if code_block_count.odd?; non_code_text = docstring_text.gsub(/\\x60[^\\x60]*\\x60/, ""); bold_count = non_code_text.scan(/\\*\\*/).count; errors << "unclosed_bold" if bold_count.odd?; lines = docstring_text.lines; lines.each_with_index do |line, line_idx|; stripped = line.strip; errors << "invalid_list_marker:" + (line_idx + 1).to_s if stripped =~ /^[•·]/; end; unless errors.empty?; puts object.file + ":" + object.line.to_s + ": " + object.title; puts errors.join("|"); end; end; false'
+              QUERY
+            end
+
+            # Builds and executes the YARD command to detect markdown syntax errors
+            # @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/markdown_syntax.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # MarkdownSyntax validator
+        #
+        # Validates markdown syntax in documentation comments. This validator checks
+        # for common markdown errors and formatting issues in YARD documentation
+        # strings. This validator is enabled by default.
+        #
+        # @example Bad - Invalid markdown syntax
+        #   # This is [broken markdown
+        #   # Another line with `unclosed code
+        #   def process
+        #   end
+        #
+        # @example Good - Valid markdown syntax
+        #   # This is [valid markdown](https://example.com)
+        #   # Another line with `closed code`
+        #   def process
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/MarkdownSyntax:
+        #       Enabled: false
+        #
+        module MarkdownSyntax
+        end
+      end
+    end
+  end
+end

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

@@ -4,7 +4,32 @@ module Yard
   module Lint
     module Validators
       module Documentation
-        # UndocumentedBooleanMethods validator module
+        # UndocumentedBooleanMethods validator
+        #
+        # Ensures that boolean methods (methods ending with `?`) have an explicit
+        # `@return [Boolean]` tag. Boolean methods should clearly document that they
+        # return true or false values. This validator is enabled by default.
+        #
+        # @example Bad - Missing @return tag on boolean method
+        #   # Checks if the user is active
+        #   def active?
+        #     @active
+        #   end
+        #
+        # @example Good - Boolean return documented
+        #   # Checks if the user is active
+        #   # @return [Boolean] true if the user is active
+        #   def active?
+        #     @active
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/UndocumentedBooleanMethods:
+        #       Enabled: false
+        #
         module UndocumentedBooleanMethods
         end
       end

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

@@ -4,7 +4,32 @@ module Yard
   module Lint
     module Validators
       module Documentation
-        # UndocumentedMethodArguments validator module
+        # UndocumentedMethodArguments validator
+        #
+        # Ensures that all method parameters are documented with `@param` tags.
+        # This validator checks that every parameter in a method signature has
+        # a corresponding `@param` documentation tag. This validator is enabled
+        # by default.
+        #
+        # @example Bad - Missing @param tags
+        #   # Does something with data
+        #   def process(name, options)
+        #   end
+        #
+        # @example Good - All parameters documented
+        #   # Does something with data
+        #   # @param name [String] the name to process
+        #   # @param options [Hash] configuration options
+        #   def process(name, options)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/UndocumentedMethodArguments:
+        #       Enabled: false
+        #
         module UndocumentedMethodArguments
         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