yard-lint 1.12.0 → 1.13.0

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

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

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OverloadConsistency
+          # Builds human-readable messages for OverloadConsistency violations
+          class MessagesBuilder
+            class << self
+              # Formats an overload consistency violation message
+              # @param offense [Hash] offense details with :kind, :param and :signature keys
+              # @return [String] formatted message
+              def call(offense)
+                overload = "Overload '#{offense[:signature]}'"
+
+                case offense[:kind]
+                when 'unknown_param'
+                  "#{overload} documents @param '#{offense[:param]}', which is not in its signature"
+                when 'undocumented_param'
+                  "#{overload} has no @param for '#{offense[:param]}'"
+                else
+                  "#{overload} has no @return, while other overloads of this method have one"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OverloadConsistency
+          # Parser for OverloadConsistency validator output
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Offense kinds the validator emits
+            KINDS = %w[unknown_param undocumented_param missing_return].freeze
+
+            # Parses validator output and extracts overload violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ObjectName
+            #   kind|param|signature
+            # @param yard_output [String] raw validator output
+            # @return [Array<Hash>] array with violation details
+            def call(yard_output, **)
+              return [] if yard_output.nil? || yard_output.strip.empty?
+
+              lines = yard_output.split("\n").map(&:strip).reject(&:empty?)
+
+              lines.each_slice(2).filter_map do |location_line, details_line|
+                next unless location_line && details_line
+
+                location_match = location_line.match(/^(.+):(\d+): (.+)$/)
+                next unless location_match
+
+                kind, param, signature = details_line.split('|', 3)
+                next unless KINDS.include?(kind)
+                next if signature.to_s.empty?
+
+                {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  kind: kind,
+                  param: param,
+                  signature: signature
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OverloadConsistency
+          # Result wrapper for OverloadConsistency validator
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'method'
+            self.offense_name = 'OverloadConsistency'
+
+            private
+
+            # Builds a human-readable message for the offense
+            # @param offense [Hash] offense details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module OverloadConsistency
+          # Validates each @overload's tags against that overload's own signature
+          class Validator < 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.type == :method
+              return if object.is_alias?
+              return if module_function_copy?(object)
+
+              overloads = object.tags(:overload)
+              return if overloads.empty?
+
+              shared = object.docstring.tags(:param).map { |tag| tag.name.to_s }
+              offenses = overloads.flat_map { |overload| param_offenses(overload, shared) }
+              offenses.concat(return_offenses(object, overloads))
+
+              offenses.each do |kind, param, overload|
+                collector.puts "#{object.file}:#{object.line}: #{object.title}"
+                collector.puts "#{kind}|#{param}|#{overload.signature}"
+              end
+            end
+
+            private
+
+            # @param overload [YARD::Tags::OverloadTag] overload to check
+            # @param shared [Array<String>] @param names on the method docstring, common to all overloads
+            # @return [Array<Array>] [kind, param name, overload] offenses
+            def param_offenses(overload, shared)
+              documented = overload.docstring.tags(:param).map { |tag| tag.name.to_s }
+              return [] if documented.empty?
+
+              names = overload.parameters.map { |param| param[0].to_s }
+              plain = names.reject { |name| name.start_with?('*', '&', '...') }.map { |name| name.sub(/:\z/, '') }
+
+              offenses = (plain - documented - shared).map { |name| ['undocumented_param', name, overload] }
+
+              # `...`, `*`, `**` and `&` take arguments no @param can name
+              return offenses if names.any? { |name| %w[... * ** &].include?(name) }
+
+              known = names.map { |name| name.delete_prefix('**').delete_prefix('*').delete_prefix('&').sub(/:\z/, '') }
+              (documented.uniq - known).map { |name| ['unknown_param', name, overload] } + offenses
+            end
+
+            # @param object [YARD::CodeObjects::MethodObject] the method
+            # @param overloads [Array<YARD::Tags::OverloadTag>] its overloads
+            # @return [Array<Array>] [kind, param name, overload] offenses
+            def return_offenses(object, overloads)
+              return [] if object.docstring.has_tag?(:return)
+
+              missing = overloads.reject { |overload| overload.docstring.has_tag?(:return) }
+              return [] if missing.size == overloads.size
+
+              missing.map { |overload| ['missing_return', nil, overload] }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # OverloadConsistency validator
+        #
+        # Checks each `@overload` against its own signature. YARD checks `@param`
+        # names only on the method's primary docstring, so tags inside an
+        # overload are never compared with the overload's parameters. This
+        # validator reports:
+        #
+        # - a `@param` that names no parameter of its overload's signature
+        # - a parameter with no `@param` in an overload that documents at least
+        #   one other parameter (splat and block parameters are not required)
+        # - an overload with no `@return` when another overload of the same
+        #   method has one and the method docstring itself has none
+        #
+        # Overloads that use argument forwarding (`...`) or anonymous splat or
+        # block parameters are not checked for unknown names. This validator is
+        # enabled by default.
+        #
+        # @example Bad - @param does not match the overload's signature
+        #   # @overload fetch(key)
+        #   #   @param name [String] the key
+        #   #   @return [Object]
+        #   def fetch(*args)
+        #   end
+        #
+        # @example Good - each overload documents its own parameters
+        #   # @overload fetch(key)
+        #   #   @param key [String] the key
+        #   #   @return [Object]
+        #   # @overload fetch(key, default)
+        #   #   @param key [String] the key
+        #   #   @param default [Object] value when the key is missing
+        #   #   @return [Object]
+        #   def fetch(*args)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To disable this validator:
+        #
+        #     Tags/OverloadConsistency:
+        #       Enabled: false
+        module OverloadConsistency
+        end
+      end
+    end
+  end
+end

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

@@ -27,9 +27,9 @@ module Yard
               tags_to_check = config_checked_tags
               patterns = config_enabled_patterns
 
-              object.docstring.tags.each do |tag|
-                next unless tags_to_check.include?(tag.tag_name)
-
+              # Tags nested inside overload blocks live on the overload's own
+              # docstring, so check those too
+              all_typed_tags(object.docstring, tags_to_check).each do |tag|
                 # Option tags carry their description on the nested pair tag;
                 # the documented name is the option key (e.g. ":mode"), not the
                 # hash parameter name

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

@@ -12,6 +12,8 @@ module Yard
             # Expected format (two lines per violation):
             #   file.rb:LINE: ClassName#method_name
             #   tag_name|type_string|error_message
+            # '|', '%' and newlines inside type_string and error_message are escaped
+            # as %7C, %25 and %0A
             # @param yard_output [String] raw YARD query results
             # @option _kwargs [Object] :unused this parameter accepts no options (reserved for future use)
             # @return [Array<Hash>] array with violation details
@@ -44,13 +46,22 @@ module Yard
                   line: location_match[2].to_i,
                   method_name: location_match[3],
                   tag_name: tag_name,
-                  type_string: type_string,
-                  error_message: error_message
+                  type_string: unescape_field(type_string),
+                  error_message: unescape_field(error_message)
                 }
               end
 
               violations
             end
+
+            private
+
+            # Reverts the validator's escaping of '|', '%' and newlines
+            # @param text [String] escaped field text
+            # @return [String] raw field text
+            def unescape_field(text)
+              text.gsub(/%(?:25|7C|0A)/, '%25' => '%', '%7C' => '|', '%0A' => "\n")
+            end
           end
         end
       end

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

@@ -49,12 +49,22 @@ module Yard
                     # YARD's parser may generate malformed error messages for non-ASCII input
                     error_msg = e.message.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?')
                     collector.puts "#{object.file}:#{object.line}: #{object.title}"
-                    collector.puts "#{tag.tag_name}|#{type_str}|#{error_msg}"
+                    collector.puts "#{tag.tag_name}|#{escape_field(type_str)}|#{escape_field(error_msg)}"
                     break
                   end
                 end
               end
             end
+
+            private
+
+            # Escapes '|' (the field separator), newlines (YARD keeps them in
+            # multi-line types) and '%' (the escape character)
+            # @param text [String] raw field text
+            # @return [String] escaped field text
+            def escape_field(text)
+              text.gsub(/[%|\n]/, '%' => '%25', '|' => '%7C', "\n" => '%0A')
+            end
           end
         end
       end

data/lib/yard/lint/version.rb

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

data/lib/yard/lint.rb

@@ -5,6 +5,7 @@ require 'shellwords'
 require 'open3'
 require 'tempfile'
 require 'tmpdir'
+require 'pathname'
 require 'digest'
 require 'did_you_mean'
 require 'yard'
@@ -73,9 +74,6 @@ module Yard
       # @param config [Yard::Lint::Config] configuration object
       # @return [Array<String>] array of absolute file paths
       def get_diff_files(diff, path, config)
-        # Determine the base directory for relative path calculations
-        base_dir = determine_base_dir(path)
-
         # Get changed files from git based on mode
         git_files = case diff[:mode]
                     when :ref
@@ -92,7 +90,7 @@ module Yard
                     end
 
         # Apply exclusion patterns
-        git_files.reject { |file| excluded_file?(file, config.exclude, base_dir) }
+        git_files.reject { |file| config.excluded_path?(file, config.exclude) }
       end
 
       # Expand path/glob patterns into an array of files
@@ -100,16 +98,13 @@ module Yard
       # @param config [Yard::Lint::Config] configuration object
       # @return [Array<String>] array of absolute file paths
       def expand_path(path, config)
-        # Determine the base directory for relative path calculations
-        base_dir = determine_base_dir(path)
-
         files = discover_ruby_files(path)
 
         # Convert to absolute paths for YARD
         files = files.map { |file| File.expand_path(file) }
 
         # Filter out excluded files
-        files.reject { |file| excluded_file?(file, config.exclude, base_dir) }
+        files.reject { |file| config.excluded_path?(file, config.exclude) }
       end
 
       # Discover Ruby files from path/glob patterns
@@ -139,55 +134,6 @@ module Yard
 
         raise Errors::FileNotFoundError, "No such file or directory: #{path}"
       end
-
-      # Determine base directory for relative path calculations
-      # @param path [String, Array<String>] path or array of paths
-      # @return [String] absolute base directory path
-      def determine_base_dir(path)
-        first_path = Array(path).first
-        return Dir.pwd unless first_path
-
-        absolute_path = File.expand_path(first_path)
-        File.directory?(absolute_path) ? absolute_path : File.dirname(absolute_path)
-      end
-
-      # Check if a file matches any exclusion pattern
-      # Patterns are matched against both absolute and relative paths
-      # @param file [String] absolute file path
-      # @param patterns [Array<String>] exclusion patterns
-      # @param base_dir [String] base directory for relative path calculation
-      # @return [Boolean] true if file should be excluded
-      def excluded_file?(file, patterns, base_dir)
-        relative_path = relative_path_from(file, base_dir)
-
-        patterns.any? do |pattern|
-          match_path?(pattern, file, relative_path)
-        end
-      end
-
-      # Calculate relative path from base directory
-      # @param file [String] absolute file path
-      # @param base_dir [String] base directory
-      # @return [String] relative path
-      def relative_path_from(file, base_dir)
-        if file.start_with?("#{base_dir}/")
-          file.sub("#{base_dir}/", '')
-        else
-          file
-        end
-      end
-
-      # Check if a pattern matches a file path
-      # Tries matching against both relative and absolute paths
-      # @param pattern [String] glob pattern
-      # @param absolute_path [String] absolute file path
-      # @param relative_path [String] relative file path
-      # @return [Boolean] true if pattern matches
-      def match_path?(pattern, absolute_path, relative_path)
-        flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
-
-        File.fnmatch(pattern, relative_path, flags) || File.fnmatch(pattern, absolute_path, flags)
-      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -57,6 +57,13 @@ files:
 - lib/yard/lint/config_loader.rb
 - lib/yard/lint/config_updater.rb
 - lib/yard/lint/config_validator.rb
+- lib/yard/lint/contractable/contract.rb
+- lib/yard/lint/contractable/result.rb
+- lib/yard/lint/contractable/rule.rb
+- lib/yard/lint/contracts/base.rb
+- lib/yard/lint/contracts/category.rb
+- lib/yard/lint/contracts/config.rb
+- lib/yard/lint/contracts/validator.rb
 - lib/yard/lint/errors.rb
 - lib/yard/lint/executor/in_process_registry.rb
 - lib/yard/lint/executor/query_executor.rb
@@ -65,6 +72,7 @@ files:
 - lib/yard/lint/explainer.rb
 - lib/yard/lint/ext/irb_notifier_shim.rb
 - lib/yard/lint/formatters/progress.rb
+- lib/yard/lint/formatters/sarif.rb
 - lib/yard/lint/git.rb
 - lib/yard/lint/parsers/base.rb
 - lib/yard/lint/parsers/one_line_base.rb
@@ -122,6 +130,12 @@ files:
 - 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/reference_typo.rb
+- lib/yard/lint/validators/documentation/reference_typo/config.rb
+- lib/yard/lint/validators/documentation/reference_typo/messages_builder.rb
+- lib/yard/lint/validators/documentation/reference_typo/parser.rb
+- lib/yard/lint/validators/documentation/reference_typo/result.rb
+- lib/yard/lint/validators/documentation/reference_typo/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
@@ -236,6 +250,12 @@ files:
 - lib/yard/lint/validators/tags/order/parser.rb
 - lib/yard/lint/validators/tags/order/result.rb
 - lib/yard/lint/validators/tags/order/validator.rb
+- lib/yard/lint/validators/tags/overload_consistency.rb
+- lib/yard/lint/validators/tags/overload_consistency/config.rb
+- lib/yard/lint/validators/tags/overload_consistency/messages_builder.rb
+- lib/yard/lint/validators/tags/overload_consistency/parser.rb
+- lib/yard/lint/validators/tags/overload_consistency/result.rb
+- lib/yard/lint/validators/tags/overload_consistency/validator.rb
 - lib/yard/lint/validators/tags/redundant_param_description.rb
 - lib/yard/lint/validators/tags/redundant_param_description/config.rb
 - lib/yard/lint/validators/tags/redundant_param_description/messages_builder.rb