yard-lint 0.2.1 → 1.1.0

data/lib/yard/lint/result_builder.rb

@@ -109,7 +109,16 @@ module Yard
         return [] unless stdout
 
         parsers = discover_parsers(validator_module)
-        parsers.flat_map { |parser| parser.new.call(stdout) }
+        parsers.flat_map do |parser|
+          parser_instance = parser.new
+          # Try passing config to parser if it accepts it (for filtering)
+          # Otherwise, call without config for backwards compatibility
+          begin
+            parser_instance.call(stdout, config: config)
+          rescue ArgumentError
+            parser_instance.call(stdout)
+          end
+        end
       end
 
       # Auto-discover parser classes in a validator module

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

@@ -17,12 +17,11 @@ module Yard
           '--no-progress'
         ].freeze
 
-        # String with a temp dir to store the YARD database
-        # @note We run YARD multiple times and in order not to rebuild db over and over
-        #   again but reuse the same one, we have a single tmp dir for it
-        YARDOC_TEMP_DIR = Dir.mktmpdir.freeze
+        # Base temp directory for YARD databases
+        # Each unique set of arguments gets its own subdirectory to prevent contamination
+        YARDOC_BASE_TEMP_DIR = Dir.mktmpdir.freeze
 
-        private_constant :YARDOC_TEMP_DIR
+        private_constant :YARDOC_BASE_TEMP_DIR
 
         attr_reader :config, :selection
 
@@ -42,12 +41,12 @@ module Yard
             Base.instance_variable_set(:@shared_command_cache, nil)
           end
 
-          # Clear the YARD database (primarily for testing)
+          # Clear all YARD databases (primarily for testing)
           # @return [void]
           def clear_yard_database!
-            return unless defined?(YARDOC_TEMP_DIR)
+            return unless defined?(YARDOC_BASE_TEMP_DIR)
 
-            FileUtils.rm_rf(Dir.glob(File.join(YARDOC_TEMP_DIR, '*')))
+            FileUtils.rm_rf(Dir.glob(File.join(YARDOC_BASE_TEMP_DIR, '*')))
           end
         end
 
@@ -66,21 +65,51 @@ module Yard
           return raw if selection.nil? || selection.empty?
 
           # Anything that goes to shell needs to be escaped
-          escaped_file_names = escape(selection).join(' ')
+          escaped_file_names = escape(selection)
 
-          yard_cmd(YARDOC_TEMP_DIR, escaped_file_names)
+          # Use a unique YARD database per set of arguments to prevent contamination
+          # between validators with different file selections or options
+          yardoc_dir = yardoc_temp_dir_for_arguments(escaped_file_names.join(' '))
+
+          # For large file lists, use a temporary file to avoid ARG_MAX limits
+          # Write file paths to temp file, one per line
+          Tempfile.create(['yard_files', '.txt']) do |f|
+            escaped_file_names.each { |file| f.puts(file) }
+            f.flush
+
+            yard_cmd(yardoc_dir, f.path)
+          end
         end
 
         private
 
+        # Returns a unique YARD database directory for the given arguments
+        # Uses SHA256 hash of the normalized arguments to ensure different file sets
+        # get separate databases, preventing contamination
+        # @param escaped_file_names [String] escaped file names to process
+        # @return [String] path to the YARD database directory
+        def yardoc_temp_dir_for_arguments(escaped_file_names)
+          # Combine all arguments that affect YARD output
+          all_args = "#{shell_arguments} #{escaped_file_names}"
+
+          # Create a hash of the arguments for a unique directory name
+          args_hash = Digest::SHA256.hexdigest(all_args)
+
+          # Create subdirectory under base temp dir
+          dir = File.join(YARDOC_BASE_TEMP_DIR, args_hash)
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+          dir
+        end
+
         # @return [String] all arguments with which YARD command should be executed
         def shell_arguments
-          validator_name = self.class.name.split('::').then do |parts|
+          validator_name = self.class.name&.split('::')&.then do |parts|
             idx = parts.index('Validators')
             next config.options unless idx && parts[idx + 1] && parts[idx + 2]
 
             "#{parts[idx + 1]}/#{parts[idx + 2]}"
-          end
+          end || config.options
 
           yard_options = config.validator_yard_options(validator_name)
           args = escape(yard_options).join(' ')
@@ -114,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/validator.rb

@@ -9,13 +9,15 @@ module Yard
           # do not have a return type or return description documented
           class Validator < Base
             # Query to find all the boolean methods without proper return documentation
+            # Requires either: no @return tag, OR @return tag with no types specified
+            # Accepts @return [Boolean] without description text as valid documentation
             QUERY = <<~QUERY.tr("\n", ' ')
               '
                 type == :method &&
                 !is_alias? &&
                 is_explicit? &&
                 name.to_s.end_with?("?") &&
-                (tag("return").nil? || tag("return").text.to_s.strip.empty?)
+                (tag("return").nil? || tag("return").types.to_a.empty?)
               '
             QUERY
 
@@ -25,16 +27,15 @@ module Yard
 
             # 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} \
                 -q \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

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

@@ -29,19 +29,18 @@ module Yard
 
             # 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)
               shell_args = shell_arguments
               UNWANTED_OPTIONS.each { |opt| shell_args.gsub!(opt, '') }
 
               cmd = <<~CMD
-                yard list \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
                   #{shell_args} \
                 --query #{QUERY} \
                 -q \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

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

@@ -10,7 +10,8 @@ module Yard
             self.id = :undocumented_objects
             self.defaults = {
               'Enabled' => true,
-              'Severity' => 'warning'
+              'Severity' => 'warning',
+              'ExcludedMethods' => ['initialize/0']
             }.freeze
             self.combines_with = ['Documentation/UndocumentedBooleanMethods'].freeze
           end

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