yard-lint 1.2.3 → 1.3.0

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module BlankLineBeforeDefinition
+          # Parses YARD output for blank line before definition 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]
+                  object_line = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  # Next line contains violation details
+                  i += 1
+                  next unless i < lines.size
+
+                  # Parse violation: "single:1" or "orphaned:3"
+                  detail_parts = lines[i].split(':', 2)
+                  next unless detail_parts.size == 2
+
+                  violation_type = detail_parts[0]
+                  blank_count = detail_parts[1].to_i
+
+                  violations << {
+                    location: file_path,
+                    line: object_line,
+                    object_name: object_name,
+                    violation_type: violation_type,
+                    blank_count: blank_count
+                  }
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module BlankLineBeforeDefinition
+          # Result builder for blank line before definition violations
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'line'
+            self.offense_name = 'BlankLineBeforeDefinition'
+
+            # Build human-readable message for blank line violation
+            # @param offense [Hash] offense data with violation details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+
+            private
+
+            # Override to handle per-violation severity based on violation type
+            # @return [Array<Hash>] array of offense hashes
+            def build_offenses
+              @parsed_data.map do |offense_data|
+                severity = severity_for_violation(offense_data[:violation_type])
+
+                offense_data.merge(
+                  severity: severity,
+                  type: self.class.offense_type,
+                  name: computed_offense_name,
+                  message: build_message(offense_data),
+                  location: offense_data[:location] || offense_data[:file],
+                  location_line: offense_data[:line] || offense_data[:location_line] || 0
+                )
+              end
+            end
+
+            # Get severity for a specific violation type
+            # @param violation_type [String] 'single' or 'orphaned'
+            # @return [String] severity level
+            def severity_for_violation(violation_type)
+              default = self.class.default_severity
+              return default unless config
+
+              case violation_type
+              when 'orphaned'
+                config.validator_config(validator_name, 'OrphanedSeverity') ||
+                  config.validator_severity(validator_name) ||
+                  default
+              else
+                config.validator_severity(validator_name) || default
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module BlankLineBeforeDefinition
+          # Validates blank lines between documentation and definitions
+          class Validator < Validators::Base
+            # Enable in-process execution for this validator
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Checks for blank lines between documentation blocks and definitions.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              return unless object.file && File.exist?(object.file) && object.line.to_i > 1
+
+              source_lines = File.readlines(object.file)
+              definition_line = object.line - 1
+
+              blank_count, has_doc_block = analyze_spacing(source_lines, definition_line)
+
+              return if blank_count.zero? || !has_doc_block
+
+              violation_type = blank_count >= 2 ? 'orphaned' : 'single'
+
+              return unless pattern_enabled?(violation_type)
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts "#{violation_type}:#{blank_count}"
+            end
+
+            private
+
+            # Analyze spacing between documentation and definition
+            # @param source_lines [Array<String>] lines of source file
+            # @param definition_line [Integer] 0-indexed line of definition
+            # @return [Array<Integer, Boolean>] blank count and whether doc block exists
+            def analyze_spacing(source_lines, definition_line)
+              blank_count = 0
+              has_doc_block = false
+
+              (definition_line - 1).downto(0) do |i|
+                line = source_lines[i].to_s.rstrip
+                stripped = line.strip
+
+                if stripped.empty?
+                  blank_count += 1
+                elsif stripped.start_with?('#')
+                  # Skip Ruby magic comments - they're not YARD documentation
+                  next if magic_comment?(stripped)
+
+                  has_doc_block = true
+                  break
+                else
+                  # Non-comment, non-blank line - no documentation above
+                  break
+                end
+              end
+
+              [blank_count, has_doc_block]
+            end
+
+            # Check if a comment line is a Ruby magic comment
+            # @param line [String] stripped comment line
+            # @return [Boolean] true if line is a magic comment
+            def magic_comment?(line)
+              # Ruby magic comments: frozen_string_literal, encoding, warn_indent, shareable_constant_value
+              line.match?(/^#\s*(frozen[_-]string[_-]literal|encoding|warn[_-]indent|shareable[_-]constant[_-]value)\s*:/i)
+            end
+
+            # Check if the given pattern is enabled in configuration
+            # @param violation_type [String] 'single' or 'orphaned'
+            # @return [Boolean] whether the pattern is enabled
+            def pattern_enabled?(violation_type)
+              patterns = config_or_default('EnabledPatterns')
+              case violation_type
+              when 'single'
+                patterns['SingleBlankLine']
+              when 'orphaned'
+                patterns['OrphanedDocs']
+              else
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # BlankLineBeforeDefinition validator
+        #
+        # Detects blank lines between YARD documentation and method/class/module definitions.
+        # YARD requires documentation to be immediately adjacent to the definition it documents.
+        #
+        # @example Bad - Single blank line (convention violation)
+        #   # Description of the method
+        #   # @param value [String] the value
+        #
+        #   def process(value)
+        #   end
+        #
+        # @example Bad - Multiple blank lines (orphaned documentation)
+        #   # Description of the method
+        #   # @param value [String] the value
+        #
+        #
+        #   def process(value)
+        #   end
+        #
+        # @example Good - No blank lines
+        #   # Description of the method
+        #   # @param value [String] the value
+        #   def process(value)
+        #   end
+        #
+        # ## Severity Levels
+        #
+        # - **1 blank line**: Convention violation - YARD associates the doc but this
+        #   violates formatting conventions
+        # - **2+ blank lines**: Orphaned documentation - YARD ignores the documentation entirely
+        #
+        # ## Configuration
+        #
+        # To customize severity levels:
+        #
+        #     Documentation/BlankLineBeforeDefinition:
+        #       Severity: warning           # For single blank line
+        #       OrphanedSeverity: error     # For 2+ blank lines
+        #
+        # To check only single blank lines:
+        #
+        #     Documentation/BlankLineBeforeDefinition:
+        #       EnabledPatterns:
+        #         SingleBlankLine: true
+        #         OrphanedDocs: false
+        #
+        # To disable this validator:
+        #
+        #     Documentation/BlankLineBeforeDefinition:
+        #       Enabled: false
+        module BlankLineBeforeDefinition
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module EmptyCommentLine
+          # Configuration for EmptyCommentLine validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :empty_comment_line
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'convention',
+              'EnabledPatterns' => {
+                'Leading' => true,
+                'Trailing' => true
+              }
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module EmptyCommentLine
+          # Builds human-readable messages for empty comment line violations
+          class MessagesBuilder
+            # Maps violation types to human-readable descriptions
+            ERROR_DESCRIPTIONS = {
+              'leading' => 'Empty leading comment line in documentation',
+              'trailing' => 'Empty trailing comment line in documentation'
+            }.freeze
+
+            class << self
+              # Formats a violation message
+              # @param offense [Hash] the offense details
+              # @return [String] formatted message
+              def call(offense)
+                type = offense[:violation_type]
+                object_name = offense[:object_name]
+
+                description = ERROR_DESCRIPTIONS[type] || 'Empty comment line in documentation'
+
+                "#{description} for '#{object_name}'"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module EmptyCommentLine
+          # Parses YARD output for empty comment line 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]
+                  object_line = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  # Next line contains violation details
+                  i += 1
+                  next unless i < lines.size
+
+                  # Parse violations: "leading:5|trailing:10"
+                  violation_parts = lines[i].split('|')
+
+                  violation_parts.each do |part|
+                    type, line_num = part.split(':', 2)
+                    next unless type && line_num
+
+                    violations << {
+                      location: file_path,
+                      line: line_num.to_i,
+                      object_line: object_line,
+                      object_name: object_name,
+                      violation_type: type
+                    }
+                  end
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module EmptyCommentLine
+          # Result builder for empty comment line violations
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'line'
+            self.offense_name = 'EmptyCommentLine'
+
+            # Build human-readable message for empty comment line offense
+            # @param offense [Hash] offense data with violation details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module EmptyCommentLine
+          # Validates empty comment lines at the start/end of documentation blocks
+          class Validator < Validators::Base
+            # Enable in-process execution for this validator
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Checks for empty leading/trailing comment lines in documentation blocks.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              return unless object.file && File.exist?(object.file) && object.line.to_i > 1
+
+              check_leading = check_leading?
+              check_trailing = check_trailing?
+
+              source_lines = File.readlines(object.file)
+              definition_line = object.line - 1
+
+              # Find comment block boundaries
+              comment_end = nil
+              comment_start = nil
+
+              (definition_line - 1).downto(0) do |i|
+                line = source_lines[i].to_s.rstrip
+                stripped = line.strip
+
+                if stripped.empty? && comment_end.nil?
+                  # Skip empty lines before finding comment block
+                  next
+                elsif stripped.start_with?('#')
+                  comment_end ||= i
+                  comment_start = i
+                else
+                  break
+                end
+              end
+
+              return unless comment_start && comment_end
+
+              comment_block = source_lines[comment_start..comment_end]
+
+              # Find first and last content lines
+              first_content_idx = nil
+              last_content_idx = nil
+
+              comment_block.each_with_index do |line, idx|
+                stripped = line.strip
+                has_content = stripped.match?(/^#.+\S/)
+                if has_content
+                  first_content_idx ||= idx
+                  last_content_idx = idx
+                end
+              end
+
+              return unless first_content_idx && last_content_idx
+
+              violations = []
+
+              # Check for leading empty comment lines
+              if check_leading
+                (0...first_content_idx).each do |i|
+                  if comment_block[i].strip.match?(/^#\s*$/)
+                    violations << "leading:#{comment_start + i + 1}"
+                  end
+                end
+              end
+
+              # Check for trailing empty comment lines
+              if check_trailing
+                ((last_content_idx + 1)...comment_block.length).each do |i|
+                  if comment_block[i].strip.match?(/^#\s*$/)
+                    violations << "trailing:#{comment_start + i + 1}"
+                  end
+                end
+              end
+
+              return if violations.empty?
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts violations.join('|')
+            end
+
+            private
+
+            # @return [Boolean] whether to check for leading empty lines
+            def check_leading?
+              patterns = config_or_default('EnabledPatterns')
+              patterns['Leading']
+            end
+
+            # @return [Boolean] whether to check for trailing empty lines
+            def check_trailing?
+              patterns = config_or_default('EnabledPatterns')
+              patterns['Trailing']
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # EmptyCommentLine validator
+        #
+        # Detects empty comment lines at the start or end of YARD documentation blocks.
+        # Empty lines BETWEEN tag groups are allowed for readability.
+        #
+        # @example Bad - Empty leading comment line
+        #   #
+        #   # Description of the method
+        #   # @param value [String] the value
+        #   def process(value)
+        #   end
+        #
+        # @example Bad - Empty trailing comment line
+        #   # Description of the method
+        #   # @param value [String] the value
+        #   #
+        #   def process(value)
+        #   end
+        #
+        # @example Good - No leading or trailing empty lines
+        #   # Description of the method
+        #   # @param value [String] the value
+        #   def process(value)
+        #   end
+        #
+        # @example Good - Empty line between sections (allowed)
+        #   # Description of the method
+        #   #
+        #   # @param value [String] the value
+        #   # @return [Boolean] success
+        #   def process(value)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To check only leading empty lines:
+        #
+        #     Documentation/EmptyCommentLine:
+        #       EnabledPatterns:
+        #         Leading: true
+        #         Trailing: false
+        #
+        # To disable this validator:
+        #
+        #     Documentation/EmptyCommentLine:
+        #       Enabled: false
+        module EmptyCommentLine
+        end
+      end
+    end
+  end
+end

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

@@ -7,28 +7,43 @@ module Yard
         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
+            # Enable in-process execution for this validator
+            in_process visibility: :public
+
+            # Execute query for a single object during in-process execution.
+            # Checks for markdown syntax errors in docstrings.
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            # @return [void]
+            def in_process_query(object, collector)
+              docstring_text = object.docstring.to_s
+              return if docstring_text.empty?
+
+              errors = []
+
+              # Check for unclosed backticks
+              backtick_count = docstring_text.scan(/`/).count
+              errors << 'unclosed_backtick' if backtick_count.odd?
+
+              # Check for unclosed code blocks
+              code_block_count = docstring_text.scan(/^```/).count
+              errors << 'unclosed_code_block' if code_block_count.odd?
+
+              # Check for unclosed bold markers (excluding code sections)
+              non_code_text = docstring_text.gsub(/`[^`]*`/, '')
+              bold_count = non_code_text.scan(/\*\*/).count
+              errors << 'unclosed_bold' if bold_count.odd?
+
+              # Check for invalid list markers
+              docstring_text.lines.each_with_index do |line, line_idx|
+                stripped = line.strip
+                errors << "invalid_list_marker:#{line_idx + 1}" if stripped.match?(/^[•·]/)
+              end
+
+              return if errors.empty?
 
-            # 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)
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts errors.join('|')
             end
           end
         end

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

@@ -28,7 +28,6 @@ module Yard
         #
         #     Documentation/MarkdownSyntax:
         #       Enabled: false
-        #
         module MarkdownSyntax
         end
       end