yard-lint 1.5.2 → 1.6.0

data/lib/yard/lint/templates/strict_config.yml

@@ -40,21 +40,34 @@ Documentation/UndocumentedObjects:
   ExcludedMethods:
     - 'initialize/0'  # Exclude parameter-less initialize
     - '/^_/'          # Exclude private methods (by convention)
+  # AllowedParentClasses:
+  #   - StandardError           # Skip error subclasses
+  #   - ApplicationRecord       # Skip Rails model subclasses
 
 Documentation/UndocumentedMethodArguments:
   Description: 'Checks for method parameters without @param tags.'
   Enabled: true
   Severity: error
+  # AllowedParentClasses:
+  #   - StandardError
+  # AllowedMethods: skip @param checks for specific methods (exact name, name/arity, /regex/)
+  #   - call
+  #   - perform
+  #   - initialize/1
 
 Documentation/UndocumentedBooleanMethods:
   Description: 'Checks that question mark methods document their boolean return.'
   Enabled: true
   Severity: error
+  # AllowedParentClasses:
+  #   - StandardError
 
 Documentation/UndocumentedOptions:
   Description: 'Detects methods with options hash parameters but no @option tags.'
   Enabled: true
   Severity: error
+  # AllowedParentClasses:
+  #   - StandardError
 
 Documentation/MissingReturn:
   Description: 'Requires @return tags on all methods (opt-in for strict documentation).'
@@ -63,6 +76,13 @@ Documentation/MissingReturn:
   ExcludedMethods:
     - 'initialize'    # Exclude all initialize methods
     # - '/^_/'        # Uncomment to exclude private methods (by convention)
+  # AllowedParentClasses:
+  #   - StandardError
+
+Documentation/OrphanedDocComment:
+  Description: 'Detects YARD comment blocks with tags not attached to any documentable construct.'
+  Enabled: true  # Enabled in strict mode
+  Severity: error
 
 Documentation/MarkdownSyntax:
   Description: 'Detects common markdown syntax errors in documentation.'
@@ -86,6 +106,20 @@ Documentation/BlankLineBeforeDefinition:
     SingleBlankLine: true
     OrphanedDocs: true
 
+Documentation/LineLength:
+  Description: 'Detects documentation comment lines that exceed the configured maximum length.'
+  Enabled: false  # Opt-in validator
+  Severity: error
+  MaxLength: 120
+
+Documentation/TextSubstitution:
+  Description: 'Detects forbidden characters or strings in documentation and suggests replacements.'
+  Enabled: true
+  Severity: warning
+  Substitutions:
+    "—": "-"    # em-dash (U+2014)
+    "–": "-"    # en-dash (U+2013)
+
 # Tags validators
 Tags/Order:
   Description: 'Enforces consistent ordering of YARD tags.'
@@ -135,6 +169,11 @@ Tags/MeaninglessTag:
     - module
     - constant
 
+Tags/MissingYield:
+  Description: 'Detects methods that yield to a block without a @yield, @yieldparam, or @yieldreturn tag.'
+  Enabled: true  # Enabled in strict mode
+  Severity: error
+
 Tags/CollectionType:
   Description: 'Validates Hash collection syntax consistency.'
   Enabled: true

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

@@ -81,7 +81,7 @@ module Yard
         # Collect tags matching the given tag names from a docstring, including
         # tags nested inside @overload blocks. YARD stores @overload inner tags
         # on the overload's own docstring, so they are invisible to
-        # `docstring.tags` — this helper traverses them.
+        # `docstring.tags` - this helper traverses them.
         # @param docstring [YARD::Docstring] the docstring to search
         # @param tag_names [Array<String>] tag names to collect (e.g., %w[param return])
         # @return [Array<YARD::Tags::Tag>] matching tags from the docstring and any overloads
@@ -97,6 +97,112 @@ module Yard
           tags
         end
 
+        # Checks whether the object's enclosing class (or the object itself if it is
+        # a class) has a superclass that appears in the validator's AllowedParentClasses
+        # configuration list. When true, validators skip the object so that classes
+        # inheriting from common base classes (e.g. StandardError, ApplicationRecord)
+        # are not flagged.
+        #
+        # Matching is done on YARD's resolved superclass path, which is always the
+        # fully-qualified name (e.g. "ActiveRecord::Base"). Entries in
+        # AllowedParentClasses are matched exactly, so callers must use the same form
+        # (e.g. "ActiveRecord::Base", not "Base").
+        #
+        # For method objects the enclosing namespace's superclass is checked. For
+        # class objects the class itself is checked. Other object types always return
+        # false so that modules and constants are unaffected.
+        #
+        # @param object [YARD::CodeObjects::Base] the code object to check
+        # @return [Boolean] true if the object should be skipped
+        def parent_class_allowed?(object)
+          allowed = Array(config_or_default('AllowedParentClasses'))
+          return false if allowed.empty?
+
+          klasses = case object.type
+                    when :class
+                      # Check the class's own superclass; also check the enclosing class's
+                      # superclass so that nested classes and constants inside an allowed
+                      # parent class are exempted as well.
+                      [object, object.namespace].select { |k| k.respond_to?(:superclass) }
+                    when :method, :constant
+                      ns = object.namespace
+                      ns.respond_to?(:superclass) ? [ns] : []
+                    else
+                      []
+                    end
+
+          return false if klasses.empty?
+
+          klasses.any? do |klass|
+            superclass = klass.superclass
+            next false if superclass.nil?
+
+            superclass_path = superclass.respond_to?(:path) ? superclass.path.to_s : superclass.to_s
+            next false if superclass_path.empty?
+            # Every Ruby class without an explicit parent implicitly inherits from Object,
+            # so matching it would exempt all classes — never the intent.
+            # BasicObject is the root of the hierarchy and is guarded for the same reason.
+            next false if superclass_path == 'Object' || superclass_path == 'BasicObject'
+
+            allowed.any? { |a| superclass_path == a.to_s }
+          end
+        end
+
+        # Checks whether the method object's name matches any entry in the validator's
+        # AllowedMethods configuration list. When true, the validator should skip the
+        # object without reporting an offense.
+        #
+        # Three pattern forms are supported (matching ExcludedMethods convention):
+        #   - Exact name:    'call'          — matches any arity
+        #   - Arity:         'initialize/1'  — matches only the given parameter count
+        #                                      (required + optional, excluding * and &)
+        #   - Regex:         '/^perform/'    — matches against the bare method name
+        #
+        # Invalid regex patterns are silently ignored. The empty regex '//' is always
+        # rejected (it would match every method, making the option useless).
+        #
+        # @param object [YARD::CodeObjects::Base] the code object to check
+        # @return [Boolean] true if the method should be skipped
+        def method_allowed?(object)
+          return false unless object.type == :method
+
+          allowed = Array(config_or_default('AllowedMethods'))
+            .compact
+            .map { |p| p.to_s.strip }
+            .reject(&:empty?)
+            .reject { |p| p == '//' }
+          return false if allowed.empty?
+
+          method_name = object.name.to_s
+          arity = object.parameters.reject { |p| p[0].to_s.start_with?('*', '&') }.size
+
+          allowed.any? { |pattern| matches_method_pattern?(method_name, arity, pattern) }
+        end
+
+        # Matches a single AllowedMethods/ExcludedMethods pattern against a method.
+        # @param method_name [String] bare method name (e.g. "call")
+        # @param arity [Integer] parameter count (required + optional, no * or &)
+        # @param pattern [String] one entry from the AllowedMethods list
+        # @return [Boolean]
+        def matches_method_pattern?(method_name, arity, pattern)
+          case pattern
+          when %r{^/(.+)/$}
+            regex_str = Regexp.last_match(1)
+            return false if regex_str.empty?
+
+            begin
+              Regexp.new(regex_str).match?(method_name)
+            rescue RegexpError
+              false
+            end
+          when %r{^[^/]+/\d+$}
+            pattern_name, pattern_arity_str = pattern.split('/', 2)
+            method_name == pattern_name && arity == pattern_arity_str.to_i
+          else
+            method_name == pattern
+          end
+        end
+
         # Retrieves configuration value with fallback to default
         # Automatically determines the validator name from the class namespace
         #

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module LineLength
+          # Configuration for LineLength validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :line_length
+            self.defaults = {
+              'Enabled' => false,
+              'Severity' => 'convention',
+              'MaxLength' => 120
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module LineLength
+          # Builds human-readable messages for LineLength violations.
+          class MessagesBuilder
+            class << self
+              # @param offense [Hash] offense details with :length, :object_name, and config :max_length
+              # @return [String] formatted message
+              def call(offense)
+                length = offense[:length]
+                object_name = offense[:object_name]
+                max_length = offense[:max_length]
+
+                "Documentation line is too long [#{length} > #{max_length}] for '#{object_name}'"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module LineLength
+          # Parses LineLength validator output into structured violation hashes.
+          #
+          # Expected format (two lines per object with violations):
+          #   file.rb:OBJECT_LINE: ObjectName
+          #   MAX_LENGTH|LINE_NO:LENGTH|LINE_NO:LENGTH|...
+          class Parser < Parsers::Base
+            # @param output [String] raw validator 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]
+
+                if (location_match = line.match(/^(.+):(\d+): (.+)$/))
+                  file_path = location_match[1]
+                  object_line = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  i += 1
+                  next unless i < lines.size
+
+                  parts = lines[i].split('|')
+                  next if parts.empty?
+
+                  # First token is max_length, remainder are line_no:length pairs
+                  max_length = parts.shift.to_i
+
+                  parts.each do |part|
+                    line_no, length = part.split(':', 2)
+                    next unless line_no && length
+
+                    violations << {
+                      location: file_path,
+                      line: line_no.to_i,
+                      object_line: object_line,
+                      object_name: object_name,
+                      length: length.to_i,
+                      max_length: max_length
+                    }
+                  end
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module LineLength
+          # Result wrapper for LineLength validator.
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'line'
+            self.offense_name = 'LineLength'
+
+            private
+
+            # @param offense [Hash] offense details including :max_length from the validator
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module LineLength
+          # Validates that documentation comment lines do not exceed the configured maximum length.
+          #
+          # Uses YARD's `docstring.line_range` to locate the exact source lines belonging to
+          # each docstring block. This handles block comments, wrapped tag descriptions, and
+          # macro expansion correctly — no arithmetic reconstruction needed.
+          class Validator < Validators::Base
+            in_process visibility: :all
+
+            # Execute query for a single object during in-process execution.
+            # @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)
+              return if object.docstring.all.empty?
+
+              line_range = object.docstring.line_range
+              return unless line_range
+
+              max_length = config_or_default('MaxLength').to_i
+              source_lines = cached_lines(object.file)
+
+              violations = []
+              line_range.each do |line_no|
+                raw_line = source_lines[line_no - 1].to_s.rstrip
+                next if raw_line.length <= max_length
+
+                violations << "#{line_no}:#{raw_line.length}"
+              end
+
+              return if violations.empty?
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts "#{max_length}|#{violations.join('|')}"
+            end
+
+            private
+
+            # Returns the lines of a source file, reading from disk only on the first call
+            # for each unique path.
+            # @param file [String] absolute path to the source file
+            # @return [Array<String>] lines of the file, memoized per path
+            def cached_lines(file)
+              @file_cache ||= {}
+              @file_cache[file] ||= File.readlines(file)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        # LineLength validator
+        #
+        # Detects documentation comment lines that exceed a configured maximum length.
+        # Only checks lines belonging to YARD docstring blocks (comment lines directly
+        # above a documentable Ruby construct). YARD's parsed docstring is used to
+        # determine which lines belong to a docstring, avoiding fragile backwards-scanning.
+        #
+        # Disabled by default — enable it and set MaxLength to taste.
+        #
+        # @example Bad - line exceeds MaxLength (120)
+        #   # This documentation line is too long and exceeds the configured maximum length.
+        #   def process(value)
+        #   end
+        #
+        # @example Good - line within MaxLength
+        #   # Process the given value.
+        #   def process(value)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To enable with a custom limit:
+        #
+        #     Documentation/LineLength:
+        #       Enabled: true
+        #       MaxLength: 100
+        #
+        # To disable:
+        #
+        #     Documentation/LineLength:
+        #       Enabled: false
+        module LineLength
+        end
+      end
+    end
+  end
+end

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

@@ -13,7 +13,8 @@ module Yard
               'Severity' => 'warning',
               'ExcludedMethods' => [
                 'initialize' # Exclude all initialize methods by default
-              ]
+              ],
+              'AllowedParentClasses' => []
             }.freeze
           end
         end

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

@@ -101,7 +101,6 @@ module Yard
 
               Regexp.new(regex_pattern).match?(method_name)
             rescue RegexpError
-              # Invalid regex - skip this pattern
               false
             end
 

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

@@ -21,6 +21,7 @@ module Yard
               # Skip aliases and implicit methods
               return if object.is_alias?
               return unless object.is_explicit?
+              return if parent_class_allowed?(object)
 
               # Check if @return tag is missing
               return_tag = object.tag(:return)

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

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

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module OrphanedDocComment
+          # Builds messages for orphaned documentation comment offenses
+          class MessagesBuilder
+            class << self
+              # @param offense [Hash] offense data with :tags key
+              # @return [String] formatted message
+              def call(offense)
+                tags = Array(offense[:tags]).join(', ')
+                "Documentation comment with #{tags} is orphaned - YARD will ignore it"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module OrphanedDocComment
+          # Parses validator output into structured offense hashes.
+          # @example Output format (one line per orphaned block)
+          #   # "path/to/file.rb:10: @param,@return"
+          class Parser < ::Yard::Lint::Parsers::Base
+            # @return [Regexp] parses "file:line: @tag1,@tag2" collector output lines
+            LINE_REGEX = /^(.+):(\d+): ([@a-z,_]+)$/.freeze
+
+            # @param validator_output [String] raw validator results string
+            # @return [Array<Hash>] array of orphaned comment offense hashes
+            def call(validator_output)
+              validator_output
+                .split("\n")
+                .map(&:strip)
+                .reject(&:empty?)
+                .filter_map do |line|
+                  match = line.match(LINE_REGEX)
+                  next unless match
+
+                  {
+                    location: match[1],
+                    line: match[2].to_i,
+                    tags: match[3].split(',')
+                  }
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module OrphanedDocComment
+          # Result object for orphaned documentation comment offenses
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'OrphanedDocComment'
+
+            # @param offense [Hash] offense data
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end