yard-lint 1.5.2 → 1.6.0

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/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.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.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.2'
+    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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.6.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -91,6 +91,12 @@ files:
 - lib/yard/lint/validators/documentation/empty_comment_line/parser.rb
 - lib/yard/lint/validators/documentation/empty_comment_line/result.rb
 - lib/yard/lint/validators/documentation/empty_comment_line/validator.rb
+- lib/yard/lint/validators/documentation/line_length.rb
+- lib/yard/lint/validators/documentation/line_length/config.rb
+- lib/yard/lint/validators/documentation/line_length/messages_builder.rb
+- lib/yard/lint/validators/documentation/line_length/parser.rb
+- lib/yard/lint/validators/documentation/line_length/result.rb
+- lib/yard/lint/validators/documentation/line_length/validator.rb
 - lib/yard/lint/validators/documentation/markdown_syntax.rb
 - lib/yard/lint/validators/documentation/markdown_syntax/config.rb
 - lib/yard/lint/validators/documentation/markdown_syntax/messages_builder.rb
@@ -103,6 +109,18 @@ files:
 - lib/yard/lint/validators/documentation/missing_return/parser.rb
 - lib/yard/lint/validators/documentation/missing_return/result.rb
 - lib/yard/lint/validators/documentation/missing_return/validator.rb
+- lib/yard/lint/validators/documentation/orphaned_doc_comment.rb
+- lib/yard/lint/validators/documentation/orphaned_doc_comment/config.rb
+- lib/yard/lint/validators/documentation/orphaned_doc_comment/messages_builder.rb
+- lib/yard/lint/validators/documentation/orphaned_doc_comment/parser.rb
+- lib/yard/lint/validators/documentation/orphaned_doc_comment/result.rb
+- lib/yard/lint/validators/documentation/orphaned_doc_comment/validator.rb
+- lib/yard/lint/validators/documentation/text_substitution.rb
+- lib/yard/lint/validators/documentation/text_substitution/config.rb
+- lib/yard/lint/validators/documentation/text_substitution/messages_builder.rb
+- lib/yard/lint/validators/documentation/text_substitution/parser.rb
+- lib/yard/lint/validators/documentation/text_substitution/result.rb
+- lib/yard/lint/validators/documentation/text_substitution/validator.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/config.rb
 - lib/yard/lint/validators/documentation/undocumented_boolean_methods/parser.rb
@@ -181,6 +199,12 @@ files:
 - lib/yard/lint/validators/tags/meaningless_tag/parser.rb
 - lib/yard/lint/validators/tags/meaningless_tag/result.rb
 - lib/yard/lint/validators/tags/meaningless_tag/validator.rb
+- lib/yard/lint/validators/tags/missing_yield.rb
+- lib/yard/lint/validators/tags/missing_yield/config.rb
+- lib/yard/lint/validators/tags/missing_yield/messages_builder.rb
+- lib/yard/lint/validators/tags/missing_yield/parser.rb
+- lib/yard/lint/validators/tags/missing_yield/result.rb
+- lib/yard/lint/validators/tags/missing_yield/validator.rb
 - lib/yard/lint/validators/tags/non_ascii_type.rb
 - lib/yard/lint/validators/tags/non_ascii_type/config.rb
 - lib/yard/lint/validators/tags/non_ascii_type/messages_builder.rb