yard-lint 1.5.2 → 1.6.0

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module OrphanedDocComment
+          # Scans source files for YARD-tagged comment blocks that YARD will silently drop.
+          # A comment block is orphaned when it has YARD tags but is immediately followed
+          # by a non-documentable statement or sits at end-of-file.
+          class Validator < Base
+            in_process visibility: :public
+
+            # Derive known tag names from YARD's own registry so we stay in sync with
+            # any tags added by YARD plugins. This avoids false positives from instance
+            # variable mentions in comments (e.g. `# @body.each` or `# @result is nil`).
+            YARD_TAG_PATTERN = begin
+              tags = ::YARD::Tags::Library.labels.keys.map(&:to_s).sort_by(&:length).reverse.join('|')
+              /\A\s*#\s*@(#{tags})\b/
+            end.freeze
+            # @return [Regexp] matches YARD directive lines (@!macro, @!method, etc.)
+            YARD_DIRECTIVE_PATTERN = /\A\s*#\s*@!/.freeze
+            # Matches method/class/module/attribute/alias definitions (with optional visibility prefix)
+            # and constant assignments (uppercase-leading identifier followed by =), both of which
+            # YARD tracks and attaches preceding doc comments to.
+            # Also matches define_method which YARD handles via a built-in dynamic handler.
+            DEFINITION_PATTERN = /
+              \A\s*(private\s+|protected\s+|public\s+)?
+              (def |class |module |attr_reader|attr_writer|attr_accessor|attr_internal|alias_method\b|alias\b|define_method\b)
+              |
+              \A\s*[A-Z][A-Za-z0-9_:]*\s*=
+            /x.freeze
+
+            # @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)
+
+              @scanned_files ||= {}
+              return if @scanned_files[object.file]
+
+              @scanned_files[object.file] = true
+              scan_file(object.file, collector)
+            end
+
+            private
+
+            # @param file [String] absolute path to the source file to scan
+            # @param collector [Executor::ResultCollector] collector for output lines
+            # @return [void]
+            def scan_file(file, collector)
+              lines = File.readlines(file, chomp: true)
+              i = 0
+
+              while i < lines.length
+                if comment_line?(lines[i])
+                  block_start = i
+                  tags = []
+
+                  has_directive = false
+                  while i < lines.length && comment_line?(lines[i])
+                    has_directive = true if directive_line?(lines[i])
+                    tag = extract_yard_tag(lines[i])
+                    tags << tag if tag
+                    i += 1
+                  end
+
+                  # Skip blocks that contain @! directives - they are macro/method definitions,
+                  # not orphaned doc comments.
+                  next if has_directive || tags.empty?
+
+                  # Skip trailing blank lines after the comment block
+                  i += 1 while i < lines.length && lines[i].strip.empty?
+
+                  if i >= lines.length || !definition_line?(lines[i])
+                    collector.puts "#{file}:#{block_start + 1}: #{tags.uniq.join(',')}"
+                  end
+                else
+                  i += 1
+                end
+              end
+            end
+
+            # @param line [String] a raw source line
+            # @return [Boolean] true if the line is a Ruby comment (excluding magic comments)
+            def comment_line?(line)
+              stripped = line.strip
+              stripped.start_with?('#') && !magic_comment?(stripped)
+            end
+
+            # @param stripped_line [String] a comment line with leading/trailing whitespace removed
+            # @return [Boolean] true if the line is a Ruby magic comment (frozen_string_literal, encoding, etc.)
+            def magic_comment?(stripped_line)
+              stripped_line.match?(/\A#\s*(frozen[_-]string[_-]literal|encoding|warn[_-]indent|shareable[_-]constant[_-]value)\s*:/i)
+            end
+
+            # @param line [String] a raw source line
+            # @return [Boolean] true if the line contains a YARD directive (@!macro, @!method, etc.)
+            def directive_line?(line)
+              line.match?(YARD_DIRECTIVE_PATTERN)
+            end
+
+            # @param line [String] a raw source line
+            # @return [String, nil] the tag string (e.g. "@param") or nil if no known YARD tag found
+            def extract_yard_tag(line)
+              match = line.match(YARD_TAG_PATTERN)
+              "@#{match[1]}" if match
+            end
+
+            # @param line [String] a raw source line
+            # @return [Boolean] true if the line starts a YARD-documentable definition
+            def definition_line?(line)
+              line.match?(DEFINITION_PATTERN)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # OrphanedDocComment validator
+        #
+        # Detects YARD documentation comment blocks that contain tags (`@param`,
+        # `@return`, etc.) but are not attached to any documentable Ruby construct.
+        # YARD silently drops these comments - they never appear in the registry and
+        # the documentation is permanently lost.
+        #
+        # This happens when a YARD-tagged comment is immediately followed by a
+        # non-documentable statement (variable assignment, `require`, `include`, etc.)
+        # or sits at the end of a file.
+        #
+        # @note This validator is complementary to `Documentation/BlankLineBeforeDefinition`,
+        #   which catches doc blocks separated from a `def` by blank lines.
+        #   `OrphanedDocComment` catches doc blocks that lead to non-definition code entirely.
+        #
+        # @example Bad - comment before variable assignment
+        #   # @param name [String] the name
+        #   # @return [void]
+        #   MY_CONSTANT = "value"
+        #
+        # @example Bad - comment before require
+        #   # @param name [String] the name
+        #   require "some_gem"
+        #
+        # @example Bad - comment at end of file
+        #   # @param name [String] the name
+        #   # @return [void]
+        #   # (EOF)
+        #
+        # @example Good - comment before def
+        #   # @param name [String] the name
+        #   # @return [void]
+        #   def process(name)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Documentation/OrphanedDocComment:
+        #       Enabled: false
+        module OrphanedDocComment
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module TextSubstitution
+          # Configuration for the TextSubstitution validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :text_substitution
+            self.defaults = {
+              'Enabled' => false,
+              'Severity' => 'warning',
+              'Substitutions' => {
+                "—" => '-', # em-dash (—)
+                "–" => '-'  # en-dash (–)
+              }
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module TextSubstitution
+          # Builds human-readable messages for TextSubstitution violations.
+          class MessagesBuilder
+            class << self
+              # @param offense [Hash] offense details with :forbidden, :replacement, :line_text keys
+              # @return [String] formatted message
+              def call(offense)
+                forbidden   = offense[:forbidden]
+                replacement = offense[:replacement]
+                line_text   = offense[:line_text]
+
+                message = "Replace '#{forbidden}' with '#{replacement}' in documentation"
+
+                if line_text && !line_text.empty?
+                  truncated = line_text.length > 60 ? "#{line_text[0, 57]}..." : line_text
+                  message += ". Found: \"#{truncated}\""
+                end
+
+                message
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module TextSubstitution
+          # Parses TextSubstitution validator output into structured violation hashes.
+          #
+          # Wire format (four lines per violation):
+          #   file.rb:LINE: ObjectTitle
+          #   forbidden
+          #   replacement
+          #   line_offset|line_text
+          #
+          # forbidden and replacement occupy their own lines so they may contain
+          # any character, including the pipe delimiter used in the last field.
+          class Parser < ::Yard::Lint::Parsers::Base
+            # @param yard_output [String] raw collector output from the validator
+            # @option _kwargs [Object] :unused accepts no options (reserved for future use)
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **_kwargs)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              # Do not strip lines — forbidden/replacement may have significant whitespace
+              lines = yard_output.split("\n")
+              violations = []
+
+              lines.each_slice(4) do |location_line, forbidden_line, replacement_line, details_line|
+                next unless location_line && forbidden_line && replacement_line && details_line
+
+                location_match = location_line.strip.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                # line_offset is always numeric; split on first pipe only so line_text may contain pipes
+                line_offset_str, line_text = details_line.split('|', 2)
+                next unless line_offset_str
+
+                violations << {
+                  location:    location_match[1],
+                  line:        location_match[2].to_i,
+                  object_name: location_match[3],
+                  forbidden:   forbidden_line,
+                  replacement: replacement_line,
+                  line_offset: line_offset_str.to_i,
+                  line_text:   line_text || ''
+                }
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module TextSubstitution
+          # Result wrapper for TextSubstitution violations
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type     = 'line'
+            self.offense_name     = 'TextSubstitution'
+
+            # @param offense [Hash]
+            # @return [String]
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module TextSubstitution
+          # Validates that documentation does not contain forbidden strings.
+          # Reports every matching substitution rule on every line independently.
+          class Validator < Base
+            in_process visibility: :public
+
+            # @param object [YARD::CodeObjects::Base]
+            # @param collector [Executor::ResultCollector]
+            # @return [void]
+            def in_process_query(object, collector)
+              docstring_text = object.docstring.to_s
+              return if docstring_text.empty?
+
+              substitutions = config_or_default('Substitutions')
+              return if substitutions.nil? || substitutions.empty?
+
+              violations = find_violations(docstring_text, substitutions)
+              return if violations.empty?
+
+              violations.each do |violation|
+                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                collector.puts violation[:forbidden]
+                collector.puts violation[:replacement]
+                collector.puts "#{violation[:line_offset]}|#{violation[:line_text]}"
+              end
+            end
+
+            private
+
+            # Scans each line of a docstring for forbidden strings, skipping fenced code blocks.
+            # @param docstring_text [String] full docstring text to scan
+            # @param substitutions [Hash{String => String}] map of forbidden string to replacement
+            # @return [Array<Hash>] list of violations with forbidden, replacement, line_offset, line_text
+            def find_violations(docstring_text, substitutions)
+              violations = []
+              in_code_block = false
+
+              docstring_text.lines.each_with_index do |line, line_offset|
+                if line.strip.start_with?('```')
+                  in_code_block = !in_code_block
+                  next
+                end
+                next if in_code_block
+
+                substitutions.each do |forbidden, replacement|
+                  next if forbidden.nil? || forbidden.empty?
+                  next if replacement.nil? || replacement.empty?
+                  next unless line.include?(forbidden)
+
+                  violations << {
+                    forbidden: forbidden,
+                    replacement: replacement,
+                    line_offset: line_offset,
+                    line_text: line.strip
+                  }
+                end
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # TextSubstitution validator
+        #
+        # Detects forbidden characters or strings in YARD documentation comments
+        # and suggests replacements. The primary use case is detecting AI-generated
+        # em-dashes (—, U+2014) and en-dashes (–, U+2013) where a plain hyphen (-)
+        # is preferred, but any string-to-string substitution rule can be configured.
+        #
+        # All substitution rules are checked on every line — multiple violations can
+        # be reported for the same line when more than one forbidden string appears.
+        # Fenced code blocks (``` ... ```) are skipped.
+        #
+        # Disabled by default — enable it and configure Substitutions to taste.
+        #
+        # @example Bad - em-dash used in documentation
+        #   # Connects the start — and end of the range.
+        #   def connect(start, finish)
+        #   end
+        #
+        # @example Good - plain hyphen
+        #   # Connects the start - and end of the range.
+        #   def connect(start, finish)
+        #   end
+        #
+        # ## Configuration
+        #
+        # Enable with built-in defaults (em-dash and en-dash):
+        #
+        #     Documentation/TextSubstitution:
+        #       Enabled: true
+        #
+        # Enable with explicit substitution rules:
+        #
+        #     Documentation/TextSubstitution:
+        #       Enabled: true
+        #       Substitutions:
+        #         "—": "-"    # em-dash (U+2014)
+        #         "–": "-"    # en-dash (U+2013)
+        #         "…": "..."  # ellipsis (U+2026)
+        #
+        # To disable:
+        #
+        #     Documentation/TextSubstitution:
+        #       Enabled: false
+        module TextSubstitution
+        end
+      end
+    end
+  end
+end

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

@@ -10,7 +10,8 @@ module Yard
             self.id = :undocumented_boolean_methods
             self.defaults = {
               'Enabled' => true,
-              'Severity' => 'warning'
+              'Severity' => 'warning',
+              'AllowedParentClasses' => []
             }.freeze
           end
         end

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

@@ -22,6 +22,7 @@ module Yard
               # Skip aliases and implicit methods
               return if object.is_alias?
               return unless object.is_explicit?
+              return if parent_class_allowed?(object)
               # Only check boolean methods (ending with ?)
               return unless object.name.to_s.end_with?('?')
 

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

@@ -10,7 +10,9 @@ module Yard
             self.id = :undocumented_method_arguments
             self.defaults = {
               'Enabled' => true,
-              'Severity' => 'warning'
+              'Severity' => 'warning',
+              'AllowedParentClasses' => [],
+              'AllowedMethods' => []
             }.freeze
           end
         end

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

@@ -21,7 +21,9 @@ module Yard
               # Skip aliases and implicit methods
               return if object.is_alias?
               return unless object.is_explicit?
-              # Skip attribute methods (@!attribute directive) — their setter parameter
+              return if parent_class_allowed?(object)
+              return if method_allowed?(object)
+              # Skip attribute methods (@!attribute directive) - their setter parameter
               # doesn't need explicit @param documentation, matching attr_accessor behavior
               return if object.is_attribute?
 

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

@@ -8,8 +8,7 @@ module Yard
         #
         # 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.
+        # a corresponding `@param` documentation tag. This validator is enabled by default.
         #
         # @example Bad - Missing @param tags
         #   # Does something with data

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

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

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

@@ -16,6 +16,7 @@ module Yard
             # @param collector [Executor::ResultCollector] collector for output
             # @return [void]
             def in_process_query(object, collector)
+              return if parent_class_allowed?(object)
               # Check if docstring is empty
               return unless object.docstring.all.empty?
 

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

@@ -10,7 +10,8 @@ module Yard
             self.id = :undocumented_options
             self.defaults = {
               'Enabled' => true,
-              'Severity' => 'warning'
+              'Severity' => 'warning',
+              'AllowedParentClasses' => []
             }.freeze
           end
         end

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

@@ -18,6 +18,7 @@ module Yard
             def in_process_query(object, collector)
               # Only check method objects
               return unless object.is_a?(YARD::CodeObjects::MethodObject)
+              return if parent_class_allowed?(object)
 
               params = object.parameters || []
 

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

@@ -8,8 +8,7 @@ module Yard
         #
         # 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.
+        # keys should be documented using `@option` tags. This validator is enabled by default.
         #
         # @example Bad - Options parameter without @option tags
         #   # Configures the service

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

@@ -28,6 +28,7 @@ module Yard
                   severity: configured_severity,
                   type: self.class.offense_type,
                   name: offense_data[:name] || self.class.offense_name,
+                  validator: validator_name,
                   message: build_message(offense_data),
                   location: offense_data[:location] || offense_data[:file],
                   location_line: offense_data[:line] || offense_data[:location_line] || 0

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

@@ -29,7 +29,7 @@ module Yard
                 # @!attribute directives, Struct.new and Data.define generated readers/writers).
                 # These are auto-generated accessors where per-method @api tags either flow
                 # through the declaration's docstring automatically or cannot be attached at
-                # all — for example, YARD's Data.define handler creates getters with only a
+                # all - for example, YARD's Data.define handler creates getters with only a
                 # @return tag (hard-replacing their docstring and stripping any inherited @api
                 # from the enclosing class), and @!attribute directives written above a
                 # Data.define constant attach to the enclosing namespace, not the Data class

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

@@ -28,6 +28,7 @@ module Yard
                   severity: configured_severity,
                   type: self.class.offense_type,
                   name: offense_data[:name] || self.class.offense_name,
+                  validator: validator_name,
                   message: build_message(offense_data),
                   location: offense_data[:location] || offense_data[:file],
                   location_line: offense_data[:line] || offense_data[:location_line] || 0

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

@@ -28,6 +28,7 @@ module Yard
                   severity: configured_severity,
                   type: self.class.offense_type,
                   name: offense_data[:name] || self.class.offense_name,
+                  validator: validator_name,
                   message: build_message(offense_data),
                   location: offense_data[:location] || offense_data[:file],
                   location_line: offense_data[:line] || offense_data[:location_line] || 0

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

@@ -67,7 +67,7 @@ module Yard
             # @param type_str [String] the raw type string (e.g., "Array<self>", "Hash{Symbol => String}")
             # @return [Array<String>] individual type names (e.g., ["Array", "self"], ["Hash", "Symbol", "String"])
             def extract_type_names(type_str)
-              type_str.split(/[=><,{}\s()]+/).reject(&:empty?)
+              type_str.split(/[=><,{}\s();]+/).reject(&:empty?)
             end
 
             # Check if a type is defined in Ruby runtime or YARD registry

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

@@ -22,7 +22,7 @@ module Yard
 
               return unless invalid_types.include?(object_type)
 
-              # @param is meaningful on Struct.new / Data.define constants because
+              # The `@param` tag is meaningful on Struct.new / Data.define constants because
               # Solargraph uses those annotations to type the synthesized accessors.
               effective_tags = struct_or_data_class?(object) ? tags_to_check - ['param'] : tags_to_check
               return if effective_tags.empty?

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MissingYield
+          # Builds messages for missing yield tag offenses
+          class MessagesBuilder
+            class << self
+              # @param offense [Hash] offense data with :element key
+              # @return [String] formatted message
+              def call(offense)
+                "Method `#{offense[:element]}` yields to a block but is missing a @yield, @yieldparam, or @yieldreturn tag"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end