yard-lint 1.5.1 → 1.6.0

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

@@ -11,7 +11,7 @@ module Yard
             self.defaults = {
               'Enabled' => true,
               'Severity' => 'warning',
-              'ValidatedTags' => %w[param option return yieldreturn],
+              'ValidatedTags' => %w[param option return yieldreturn yieldparam raise],
               'ExtraTypes' => []
             }.freeze
           end

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

@@ -9,11 +9,22 @@ module Yard
           class MessagesBuilder
             class << self
               # Build message for invalid tag types
-              # @param offense [Hash] offense data with :method_name key
+              # @param offense [Hash] offense data with :method_name and :tag_violations keys
               # @return [String] formatted message
               def call(offense)
-                "The `#{offense[:method_name]}` has at least one tag " \
-                  'with an invalid type definition.'
+                violations = offense[:tag_violations]
+
+                if violations&.any?
+                  details = violations.map do |v|
+                    label = v[:param] ? "#{v[:tag]} #{v[:param]}" : v[:tag]
+                    types = v[:types].map { |t| "`#{t}`" }.join(', ')
+                    "#{label}: #{types}"
+                  end.join('; ')
+
+                  "The `#{offense[:method_name]}` has invalid type(s): #{details}"
+                else
+                  "The `#{offense[:method_name]}` has at least one tag with an invalid type definition."
+                end
               end
             end
           end

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

@@ -5,9 +5,69 @@ module Yard
     module Validators
       module Tags
         module InvalidTypes
-          # Parser for invalid tags types output
-          # Reuses location parsing logic from undocumented method arguments
-          class Parser < Validators::Documentation::UndocumentedMethodArguments::Parser
+          # Parser for invalid tag types output.
+          # The validator emits two lines per offense:
+          #   /path/to/file.rb:10: ClassName#method_name
+          #   @tagname param_name:BadType1,BadType2|@tagname2:BadType3
+          class Parser < Parsers::Base
+            # @return [Regexp] matches "file:line: ClassName#method"
+            LOCATION_REGEX = /^(.+):(\d+):\s+(.+)[#.](.+)$/
+            # @return [Regexp] matches the tag violations line (starts with @)
+            TAG_VIOLATIONS_REGEX = /^@/
+
+            # @param yard_output [String] raw validator output
+            # @return [Array<Hash>] parsed offenses
+            def call(yard_output)
+              lines = yard_output.split("\n").reject(&:empty?)
+              results = []
+              i = 0
+
+              while i < lines.size
+                match = lines[i].match(LOCATION_REGEX)
+
+                unless match
+                  i += 1
+                  next
+                end
+
+                offense = {
+                  location: match[1],
+                  line: match[2].to_i,
+                  class_name: match[3],
+                  method_name: match[4],
+                  tag_violations: []
+                }
+
+                next_line = lines[i + 1]
+                if next_line&.match?(TAG_VIOLATIONS_REGEX)
+                  offense[:tag_violations] = parse_tag_violations(next_line)
+                  i += 2
+                else
+                  i += 1
+                end
+
+                results << offense
+              end
+
+              results
+            end
+
+            private
+
+            # Parse "tagname param:Type1,Type2|tagname2:Type3" into structured data
+            # @param line [String] the violations line
+            # @return [Array<Hash>] each entry has :tag, :param (may be nil), :types
+            def parse_tag_violations(line)
+              line.split('|').map do |entry|
+                label, types_str = entry.split(':', 2)
+                parts = label.split(' ', 2)
+                {
+                  tag: parts[0],
+                  param: parts[1],
+                  types: (types_str || '').split(',').reject(&:empty?)
+                }
+              end
+            end
           end
         end
       end

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

@@ -19,6 +19,9 @@ module Yard
               nil
               self
               void
+              undefined
+              unspecified
+              unknown
             ].freeze
 
             private_constant :ALLOWED_DEFAULTS
@@ -33,35 +36,47 @@ module Yard
               extra_types = config_or_default('ExtraTypes')
               allowed_types = ALLOWED_DEFAULTS + extra_types
 
-              # Sanitize type string (remove type syntax characters)
-              sanitize = ->(type) { type.tr('=><>,{} ()', '') }
+              # Collect per-tag violations to surface in the offense message.
+              # Each entry is "tagname param_name:Type1,Type2" (param_name omitted when nil).
+              tag_violations = all_typed_tags(object.docstring, checked_tags).filter_map do |tag|
+                bad = (tag.types || [])
+                        .compact
+                        .flat_map { |type| extract_type_names(type) }
+                        .uniq
+                        .reject { |type| allowed_types.include?(type) }
+                        .reject { |type| type_defined?(type) }
+                        .reject { |type| type.include?('#') }
+                next if bad.empty?
 
-              # Check for invalid types
-              invalid_types = object.docstring.tags
-                                    .select { |tag| checked_tags.include?(tag.tag_name) }
-                                    .flat_map(&:types)
-                                    .compact
-                                    .uniq
-                                    .map(&sanitize)
-                                    .reject { |type| allowed_types.include?(type) }
-                                    .reject { |type| type_defined?(type) }
-                                    .reject { |type| type.include?('#') }
+                label = tag.name ? "@#{tag.tag_name} #{tag.name}" : "@#{tag.tag_name}"
+                "#{label}:#{bad.join(',')}"
+              end
 
-              return if invalid_types.empty?
+              return if tag_violations.empty?
 
               collector.puts "#{object.file}:#{object.line}: #{object.title}"
+              collector.puts tag_violations.join('|')
             end
 
             private
 
+            # Extract individual type names from a compound type string.
+            # Instead of stripping all syntax characters and concatenating (which
+            # turns "Array<self>" into "Arrayself"), this splits on syntax boundaries
+            # and returns each type name individually.
+            # @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?)
+            end
+
             # Check if a type is defined in Ruby runtime or YARD registry
             # In in-process mode, parsed classes are in YARD registry but not loaded into Ruby
             # @param type [String] type name to check
             # @return [Boolean] true if type is defined (or at least recognized as a valid type)
             def type_defined?(type)
-              # Symbol types like :foo are valid YARD documentation notations
-              # They document that a method accepts specific symbol values
-              return true if type.start_with?(':')
+              # Symbol and string literal types (:foo, "bar") are valid hash key notations
+              return true if type.start_with?(':', '"', "'")
 
               # Check Ruby runtime first
               # The shell query uses: !(Kernel.const_defined?(type) rescue nil).nil?

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

@@ -22,8 +22,13 @@ module Yard
 
               return unless invalid_types.include?(object_type)
 
+              # 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?
+
               object.docstring.tags.each do |tag|
-                next unless tags_to_check.include?(tag.tag_name)
+                next unless effective_tags.include?(tag.tag_name)
 
                 collector.puts "#{object.file}:#{object.line}: #{object.title}"
                 collector.puts "#{object_type}|#{tag.tag_name}"
@@ -42,6 +47,16 @@ module Yard
             def invalid_object_types
               config_or_default('InvalidObjectTypes')
             end
+
+            # @param object [YARD::CodeObjects::Base] the code object to inspect
+            # @return [Boolean] true when the object is a class synthesised by Struct.new
+            #   or Data.define, where @param documents the generated accessors
+            def struct_or_data_class?(object)
+              return false unless object.type == :class
+
+              sc_path = object.superclass&.path
+              sc_path == 'Struct' || sc_path == 'Data'
+            end
           end
         end
       end

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

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MissingYield
+          # Parses validator output into structured offense hashes.
+          # @example Output format (one offense per line)
+          #   # "path/to/file.rb:10: ClassName#method_name"
+          class Parser < ::Yard::Lint::Parsers::Base
+            # @return [Regexp] parses "file:line: element" collector output lines
+            LINE_REGEX = /^(.+):(\d+): (.+)$/.freeze
+
+            # @param validator_output [String] raw collector output
+            # @param config [Yard::Lint::Config, nil] configuration (unused)
+            # @return [Array<Hash>] parsed offense hashes
+            def call(validator_output, config: nil)
+              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,
+                    element: match[3]
+                  }
+                end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module MissingYield
+          # Detects methods that call `yield` but lack @yield/@yieldparam/@yieldreturn documentation
+          class Validator < Base
+            # Enable in-process execution with all visibility (private methods can yield too)
+            in_process visibility: :all
+
+            # Matches the `yield` keyword. The negative lookbehind `(?<![:.])`
+            # prevents matching method calls like `Fiber.yield` or `yielder.yield`
+            # and symbol literals like `:yield`. Word boundaries ensure `yield_self`
+            # and similar identifiers are not matched.
+            # Known limitation: `yield` inside regex literals (e.g. /yield/) is
+            # not stripped before scanning; it is rare enough to be acceptable.
+            YIELD_PATTERN = /(?<![:.])\byield\b/.freeze
+
+            # @return [Regexp] matches full-line Ruby comments
+            COMMENT_LINE_PATTERN = /\A\s*#/.freeze
+
+            # Matches simple single- and double-quoted string literals to strip before
+            # scanning for the yield keyword, reducing false positives from strings
+            # that contain the word "yield".
+            STRING_LITERAL_PATTERN = /("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')/.freeze
+
+            # Matches user-written @yield, @yieldparam, or @yieldreturn tags in raw
+            # docstring text. YARD infers @yield automatically for bare `yield expr`
+            # statements and adds it to object.tags(), so we check docstring.all (the
+            # raw source text) rather than the parsed tag list to avoid counting
+            # YARD-inferred tags as explicit documentation.
+            YIELD_TAG_PATTERN = /^\s*@yield(?:param|return)?(?:\s|$)/.freeze
+
+            # Execute query for a single object during in-process execution.
+            # Flags methods that yield without a @yield, @yieldparam, or @yieldreturn tag.
+            # @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.type == :method
+              return if object.is_alias?
+              return unless object.is_explicit?
+              return unless object.source
+              return if yield_documented?(object)
+              return unless source_contains_yield?(object.source)
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+            end
+
+            private
+
+            # @param object [YARD::CodeObjects::MethodObject] the method to check
+            # @return [Boolean] true if the user explicitly wrote a yield-related tag
+            def yield_documented?(object)
+              object.docstring.all.match?(YIELD_TAG_PATTERN)
+            end
+
+            # @param source [String] raw method source code
+            # @return [Boolean] true if the source contains the `yield` keyword
+            def source_contains_yield?(source)
+              source.each_line.any? do |line|
+                next false if line.match?(COMMENT_LINE_PATTERN)
+
+                sanitized = line.gsub(STRING_LITERAL_PATTERN, '""')
+                sanitized = sanitized.sub(/#.*$/, '')
+                sanitized.match?(YIELD_PATTERN)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # MissingYield validator
+        #
+        # Detects methods that call `yield` in their body but do not document
+        # the block with a `@yield`, `@yieldparam`, or `@yieldreturn` tag.
+        # Callers need to know a method yields so they can pass a block;
+        # undocumented yield is a silent API contract that only source readers discover.
+        #
+        # This validator is disabled by default (opt-in).
+        #
+        # @note Does not flag the inverse case (has `@yield` tag but no actual
+        #   `yield` in source) - that is intentional for abstract/overridable methods.
+        #
+        # @note Known limitation: `yield` appearing inside heredoc bodies or
+        #   multi-line string literals may produce false positives. These cases
+        #   are rare enough in practice that the validator does not attempt to
+        #   handle them.
+        #
+        # @example Bad - method yields but block is undocumented
+        #   # Iterates over items
+        #   # @param items [Array] the items
+        #   def each(items)
+        #     items.each { |item| yield item }
+        #   end
+        #
+        # @example Good - block documented with @yield
+        #   # Iterates over items
+        #   # @param items [Array] the items
+        #   # @yield [item] each item in the collection
+        #   def each(items)
+        #     items.each { |item| yield item }
+        #   end
+        #
+        # @example Good - block documented with @yieldparam
+        #   # @param items [Array] the items
+        #   # @yieldparam item [Object] each item
+        #   def each(items)
+        #     items.each { |item| yield item }
+        #   end
+        #
+        # ## Configuration
+        #
+        #     Tags/MissingYield:
+        #       Enabled: true
+        #       Severity: warning
+        module MissingYield
+        end
+      end
+    end
+  end
+end

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

@@ -11,7 +11,7 @@ module Yard
             self.defaults = {
               'Enabled' => true,
               'Severity' => 'warning',
-              'ValidatedTags' => %w[param option return yieldreturn yieldparam]
+              'ValidatedTags' => %w[param option return yieldreturn yieldparam raise]
             }.freeze
           end
         end

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

@@ -23,9 +23,7 @@ module Yard
               validated_tags = config.validator_config('Tags/NonAsciiType', 'ValidatedTags') ||
                                %w[param option return yieldreturn yieldparam]
 
-              object.docstring.tags
-                    .select { |tag| validated_tags.include?(tag.tag_name) }
-                    .each do |tag|
+              all_typed_tags(object.docstring, validated_tags).each do |tag|
                 next unless tag.types
 
                 tag.types.each do |type_str|

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

@@ -64,7 +64,8 @@ module Yard
             # @param low_value_verbs [Array<String>] low-value verbs
             # @param patterns [Hash] enabled pattern flags
             # @return [String, nil] pattern type or nil
-            # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/ParameterLists
+            # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            # rubocop:disable Metrics/AbcSize, Metrics/ParameterLists
             def detect_pattern(param_name, description, type_name, word_count, articles, generic_terms, connectors, low_value_verbs, patterns)
               desc_parts = description.split
               articles_re = /^(#{articles.join('|')})/i
@@ -136,7 +137,8 @@ module Yard
 
               nil
             end
-            # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/ParameterLists
+            # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+            # rubocop:enable Metrics/AbcSize, Metrics/ParameterLists
 
             private
 

data/lib/yard/lint/validators/tags/redundant_param_description.rb

@@ -68,7 +68,8 @@ module Yard
         #   end
         #
         # @example Good - Long, meaningful descriptions with context
-        #   # @param date [Date, nil] the date that can describe the event starting information or nil if event did not yet start
+        #   # @param date [Date, nil] the date describing when the event starts,
+        #   #   or nil if the event has not yet started
         #   # @param user [User] the user who initiated the request and will receive notifications
         #   # @param data [Hash] configuration options for the API endpoint including timeout and retry settings
         #   def configure(date, user, data)

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

@@ -11,7 +11,7 @@ module Yard
             self.defaults = {
               'Enabled' => true,
               'Severity' => 'warning',
-              'ValidatedTags' => %w[param option return yieldreturn]
+              'ValidatedTags' => %w[param option return yieldreturn yieldparam raise]
             }.freeze
           end
         end

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

@@ -31,9 +31,7 @@ module Yard
               validated_tags = config.validator_config('Tags/TypeSyntax', 'ValidatedTags') ||
                                %w[param option return yieldreturn]
 
-              object.docstring.tags
-                    .select { |tag| validated_tags.include?(tag.tag_name) }
-                    .each do |tag|
+              all_typed_tags(object.docstring, validated_tags).each do |tag|
                 next unless tag.types
 
                 tag.types.each do |type_str|

data/lib/yard/lint/validators/tags/type_syntax.rb

@@ -8,8 +8,7 @@ module Yard
         #
         # Validates YARD type syntax using YARD's TypesExplainer::Parser. This
         # validator ensures that type annotations can be properly parsed by YARD
-        # and follow YARD's type specification format. This validator is enabled
-        # by default.
+        # and follow YARD's type specification format. This validator is enabled by default.
         #
         # @example Bad - Invalid type syntax that YARD cannot parse
         #   # @param data [{String, Integer}] invalid hash syntax

data/lib/yard/lint/validators/warnings/duplicated_parameter_name/parser.rb

@@ -6,13 +6,13 @@ module Yard
       module Warnings
         module DuplicatedParameterName
           # Parser for DuplicatedParameterName warnings
-          class Parser < ::Yard::Lint::Parsers::OneLineBase
+          class Parser < ::Yard::Lint::Parsers::TwoLineBase
             # Set of regexps for detecting warnings reported by YARD stats
             self.regexps = {
               general: /^\[warn\]: @param tag has duplicate parameter name/,
-              message: /\[warn\]: (.*) in file/,
-              location: /in file `(.*)`/,
-              line: /line (\d*)/
+              message: /\[warn\]: (.*)$/,
+              location: /in file `(.*?)'\s*near/,
+              line: /near line (\d+)/
             }.freeze
           end
         end

data/lib/yard/lint/validators/warnings/duplicated_parameter_name.rb

@@ -9,8 +9,7 @@ module Yard
         #
         # Detects duplicate `@param` tags for the same parameter name. If a parameter
         # is documented multiple times, it's unclear which documentation is correct
-        # and can confuse both readers and YARD's parser. This validator is enabled
-        # by default.
+        # and can confuse both readers and YARD's parser. This validator is enabled by default.
         #
         # @example Bad - Duplicate @param tags
         #   # @param name [String] the name

data/lib/yard/lint/validators/warnings/invalid_directive_format.rb

@@ -9,8 +9,7 @@ module Yard
         #
         # Detects malformed YARD directive syntax. Directives have specific format
         # requirements (like `@!attribute [r] name` for read-only attributes), and
-        # this validator ensures those requirements are met. This validator is
-        # enabled by default.
+        # this validator ensures those requirements are met. This validator is enabled by default.
         #
         # @example Bad - Malformed directive syntax
         #   # @!attribute name missing brackets

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.5.1'
+    VERSION = '1.6.0'
   end
 end

data/lib/yard/lint.rb

@@ -23,18 +23,28 @@ module Yard
       # @param diff [Hash, nil] diff mode options
       #   - :mode [Symbol] one of :ref, :staged, :changed
       #   - :base_ref [String, nil] base ref for :ref mode (auto-detects main/master if nil)
+      # @param source [String, nil] in-memory source content; when given, the file is not
+      #   read from disk — `path` must be a single .rb file path (used for config/exclusion
+      #   resolution and offense location reporting only)
       # @return [Yard::Lint::Result] result object with offenses
-      def run(path:, config: nil, config_file: nil, progress: nil, diff: nil)
+      def run(path:, config: nil, config_file: nil, progress: nil, diff: nil, source: nil)
+        if source
+          raise ArgumentError, '`source:` requires `path:` to be a single .rb file, not a directory or glob' \
+            if path.is_a?(Array) || path.to_s.include?('*') || File.directory?(path.to_s)
+        end
+
         config ||= load_config(config_file)
 
-        # Determine files to lint based on diff mode or normal path expansion
-        files = if diff
+        # Determine files to lint based on source, diff mode, or normal path expansion
+        files = if source
+                  [File.expand_path(path)]
+                elsif diff
                   get_diff_files(diff, path, config)
                 else
                   expand_path(path, config)
                 end
 
-        runner = Runner.new(files, config)
+        runner = Runner.new(files, config, source: source)
 
         # Enable progress by default if output is a TTY
         show_progress = progress.nil? ? $stdout.tty? : progress