yard-lint 1.11.0 → 1.13.0

data/lib/yard/lint/runner.rb

@@ -102,11 +102,7 @@ module Yard
         validator_excludes = config.validator_exclude(validator_name)
         return files if validator_excludes.empty?
 
-        files.reject do |file|
-          validator_excludes.any? do |pattern|
-            File.fnmatch(pattern, file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
-          end
-        end
+        files.reject { |file| config.excluded_path?(file, validator_excludes) }
       end
 
       # Filter result offenses based on per-validator exclusions
@@ -124,23 +120,8 @@ module Yard
         return nil if result.offenses.empty?
         return result if validator_excludes.empty?
 
-        working_dir = Dir.pwd
-
         filtered_offenses = result.offenses.reject do |offense|
-          file_path = offense[:location] || offense[:file]
-          next true unless file_path
-
-          # Convert to relative path for pattern matching
-          relative_path = if file_path.start_with?(working_dir)
-                            file_path.sub(%r{^#{Regexp.escape(working_dir)}/}, '')
-                          else
-                            file_path
-                          end
-
-          # Check if file matches any exclusion pattern
-          validator_excludes.any? do |pattern|
-            File.fnmatch(pattern, relative_path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
-          end
+          config.excluded_path?(offense[:location] || offense[:file], validator_excludes)
         end
 
         # Return nil if no offenses remain after filtering

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

@@ -156,6 +156,11 @@ Documentation/DuplicateNamespaceComment:
   Enabled: true
   Severity: warning
 
+Documentation/ReferenceTypo:
+  Description: 'Detects probable typos in method and constant references.'
+  Enabled: true
+  Severity: warning
+
 # Tags validators
 Tags/Order:
   Description: 'Enforces consistent ordering of YARD tags.'
@@ -381,6 +386,11 @@ Tags/ForbiddenTags:
   #     - Object
   # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
 
+Tags/OverloadConsistency:
+  Description: 'Checks the tags of each @overload against its own signature.'
+  Enabled: true
+  Severity: warning
+
 # Warnings validators - catches YARD parser errors
 Warnings/SyntaxError:
   Description: 'Detects Ruby files YARD cannot parse (syntax errors).'

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

@@ -154,6 +154,11 @@ Documentation/DuplicateNamespaceComment:
   Enabled: true
   Severity: error
 
+Documentation/ReferenceTypo:
+  Description: 'Detects probable typos in method and constant references.'
+  Enabled: true
+  Severity: error
+
 # Tags validators
 Tags/Order:
   Description: 'Enforces consistent ordering of YARD tags.'
@@ -379,6 +384,11 @@ Tags/ForbiddenTags:
   #     - Object
   # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
 
+Tags/OverloadConsistency:
+  Description: 'Checks the tags of each @overload against its own signature.'
+  Enabled: true
+  Severity: error
+
 # Warnings validators - catches YARD parser errors
 Warnings/SyntaxError:
   Description: 'Detects Ruby files YARD cannot parse (syntax errors).'

data/lib/yard/lint/todo_generator.rb

@@ -14,12 +14,20 @@ module Yard
         # @param force [Boolean] whether to overwrite existing todo file if present
         # @param exclude_limit [Integer] minimum files in directory before grouping into wildcard patterns
         # @param config_path [String, nil] config file to link the todo into
-        #   (defaults to .yard-lint.yml in the current directory)
+        #   (defaults to .yard-lint.yml in the config directory)
         # @return [Hash] result with :message, :offense_count, :validator_count
         def generate(path:, config:, force: false, exclude_limit: DEFAULT_EXCLUDE_LIMIT, config_path: nil)
           new(path: path, config: config, force: force, exclude_limit: exclude_limit,
               config_path: config_path).generate
         end
+
+        # Report .yard-lint-todo.yml Exclude entries that no longer match any offense
+        # @param path [String] directory or file path containing Ruby files to analyze for violations
+        # @param config [Config] yard-lint configuration object with validator settings
+        # @return [Hash] result with :message and :unused_entries (validator name => unused patterns)
+        def check(path:, config:)
+          new(path: path, config: config, force: false, exclude_limit: DEFAULT_EXCLUDE_LIMIT).check
+        end
       end
 
       # Initialize a new TodoGenerator instance
@@ -33,8 +41,8 @@ module Yard
         @config = config
         @force = force
         @exclude_limit = exclude_limit
-        @todo_path = File.join(Dir.pwd, '.yard-lint-todo.yml')
-        @config_path = config_path || File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
+        @todo_path = File.join(config.base_dir, '.yard-lint-todo.yml')
+        @config_path = config_path || File.join(config.base_dir, Config::DEFAULT_CONFIG_FILE)
       end
 
       # Generate the .yard-lint-todo.yml file with exclusions for current violations
@@ -65,8 +73,130 @@ module Yard
         build_success_result(violations_by_validator, lint_result[:total_offenses])
       end
 
+      # Re-lint without the todo file exclusions and find entries that match no offense
+      # Offenses can depend on the other linted files and on their order, so an entry counts as
+      # used when it matches an offense of a whole-project run or of a run on the path only.
+      # The path only limits which entries are judged: those that cover a file under it,
+      # or no project file at all. The given config is not modified.
+      # @return [Hash] result with :message and :unused_entries (validator name => unused patterns)
+      # @raise [Errors::TodoFileNotFoundError] if the todo file does not exist
+      def check
+        todo_entries = load_todo_entries
+        audit_config = build_audit_config(todo_entries)
+        path_files = Yard::Lint.send(:expand_path, @path, audit_config)
+        files = Yard::Lint.send(:expand_path, '.', audit_config) | path_files
+
+        violations_by_validator = audit_violations([files, path_files], audit_config)
+        files = files.map { |file| make_relative_path(file) }
+        path_files = path_files.map { |file| make_relative_path(file) }
+
+        unused_entries = todo_entries.each_with_object({}) do |(validator_name, patterns), unused|
+          next unless judged?(validator_name, audit_config)
+
+          violating_files = violations_by_validator.fetch(validator_name, [])
+          stale = patterns.select do |pattern|
+            in_scope?(pattern, files, path_files) && violating_files.none? { |file| todo_match?(pattern, file) }
+          end
+          unused[validator_name] = stale if stale.any?
+        end
+
+        { message: build_check_message(unused_entries), unused_entries: unused_entries }
+      end
+
       private
 
+      # Load per-validator Exclude patterns from the todo file
+      # @return [Hash{String => Array<String>}] validator names to their todo Exclude patterns
+      # @raise [Errors::TodoFileNotFoundError] if the todo file does not exist
+      def load_todo_entries
+        unless File.exist?(@todo_path)
+          raise Errors::TodoFileNotFoundError,
+            '.yard-lint-todo.yml not found. Use --auto-gen-config to generate it.'
+        end
+
+        ConfigLoader.load_yaml_file(@todo_path).each_with_object({}) do |(validator_name, settings), entries|
+          next unless settings.is_a?(Hash) && settings['Exclude'].is_a?(Array)
+
+          entries[validator_name] = settings['Exclude'].map(&:to_s)
+        end
+      end
+
+      # Build a copy of the config without the todo file's Exclude lists
+      # A per-validator Exclude replaces an inherited one, so a validator's todo list is in effect
+      # only when it is that validator's whole Exclude. Otherwise the user's Exclude stays as is.
+      # @param todo_entries [Hash{String => Array<String>}] validator names to todo Exclude patterns
+      # @return [Config] configuration for the audit run
+      def build_audit_config(todo_entries)
+        audit_config = Config.new(Marshal.load(Marshal.dump(@config.raw_config)))
+        audit_config.base_dir = @config.base_dir
+        audit_config.only_validators = @config.only_validators.dup
+
+        todo_entries.each do |validator_name, patterns|
+          next unless ConfigLoader::ALL_VALIDATORS.include?(validator_name)
+          next unless audit_config.validator_config(validator_name, 'Exclude') == patterns
+
+          audit_config.set_validator_config(validator_name, 'Exclude', [])
+        end
+
+        audit_config
+      end
+
+      # Lint each file set and merge the violating files per validator
+      # @param file_sets [Array<Array<String>>] file sets to lint separately
+      # @param config [Config] configuration for the audit run
+      # @return [Hash{String => Array<String>}] validator names to files with offenses in any run
+      def audit_violations(file_sets, config)
+        file_sets.uniq(&:sort).each_with_object({}) do |files, merged|
+          run_linting(files: files, config: config)[:violations_by_validator].each do |validator_name, paths|
+            merged[validator_name] = merged.fetch(validator_name, []) | paths
+          end
+        end
+      end
+
+      # Whether the audit can judge a validator's todo entries
+      # Entries of validators left out by only_validators are not judged, as they were not run.
+      # @param validator_name [String] validator name from the todo file
+      # @param config [Config] configuration for the audit run
+      # @return [Boolean] true unless only_validators leaves the validator out
+      def judged?(validator_name, config)
+        config.only_validators.empty? || config.only_validators.include?(validator_name)
+      end
+
+      # Whether a todo pattern belongs to the checked path
+      # @param pattern [String] todo Exclude pattern
+      # @param files [Array<String>] relative paths of all linted files
+      # @param path_files [Array<String>] relative paths of the files under the checked path
+      # @return [Boolean] true if the pattern covers a file under the path, or no linted file at all
+      def in_scope?(pattern, files, path_files)
+        path_files.any? { |file| todo_match?(pattern, file) } ||
+          files.none? { |file| todo_match?(pattern, file) }
+      end
+
+      # Whether a todo Exclude pattern matches a file
+      # @param pattern [String] todo Exclude pattern
+      # @param file [String] relative file path
+      # @return [Boolean] true if the pattern matches the file
+      def todo_match?(pattern, file)
+        File.fnmatch(pattern, file, Config::EXCLUDE_FLAGS)
+      end
+
+      # Build the summary message for a todo check
+      # @param unused_entries [Hash{String => Array<String>}] validator names to unused patterns
+      # @return [String] human-readable summary
+      def build_check_message(unused_entries)
+        return 'No unused entries found in .yard-lint-todo.yml' if unused_entries.empty?
+
+        count = unused_entries.values.sum(&:size)
+        lines = ["Found #{count} unused entr#{count == 1 ? 'y' : 'ies'} in .yard-lint-todo.yml:"]
+        unused_entries.each do |validator_name, patterns|
+          lines << "  #{validator_name}:"
+          patterns.each { |pattern| lines << "    - '#{pattern}'" }
+        end
+        lines << ''
+        lines << 'Remove these entries, or run yard-lint --regenerate-todo to rebuild the file.'
+        lines.join("\n")
+      end
+
       # Validate that the todo file doesn't already exist
       # @return [void]
       # @raise [Errors::TodoFileExistsError] if todo file exists and force is false
@@ -78,23 +208,25 @@ module Yard
       end
 
       # Run linting and collect violations per validator
+      # @param files [Array<String>, nil] files to lint (defaults to the files under the path)
+      # @param config [Config] configuration to lint with
       # @return [Hash] hash with :violations_by_validator and :total_offenses keys
-      def run_linting
+      def run_linting(files: nil, config: @config)
         # Run each validator individually to track violations per validator
         # This is more reliable than trying to infer validator from offense name
-        files = Yard::Lint.send(:expand_path, @path, @config)
-        runner = Runner.new(files, @config)
+        files ||= Yard::Lint.send(:expand_path, @path, config)
+        runner = Runner.new(files, config)
 
         # Run validators and collect raw results
         raw_results = runner.send(:run_validators)
-        result_builder = ResultBuilder.new(@config)
+        result_builder = ResultBuilder.new(config)
 
         violations_by_validator = {}
         total_offenses = 0
 
         # Process each validator's results
         ConfigLoader::ALL_VALIDATORS.each do |validator_name|
-          next unless @config.validator_enabled?(validator_name)
+          next unless config.validator_enabled?(validator_name)
 
           validator_result = result_builder.build(validator_name, raw_results)
           next unless validator_result
@@ -137,14 +269,13 @@ module Yard
         end
       end
 
-      # Convert absolute path to relative path from current directory
+      # Convert a path to the form Exclude patterns match (relative to the config directory)
       # @param path [String, nil] absolute or relative file path
-      # @return [String, nil] relative path from current directory, or nil if path is nil
+      # @return [String, nil] path relative to the config directory, or nil if path is nil
       def make_relative_path(path)
         return path if path.nil?
 
-        pwd = Dir.pwd
-        path.start_with?(pwd) ? path.sub("#{pwd}/", '') : path
+        @config.relative_path(path)
       end
 
       # Build YAML content for the todo file

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

@@ -110,6 +110,69 @@ module Yard
           !@scanned_docstrings.add?(key)
         end
 
+        # Whether the object is a synthesized copy whose docstring has been
+        # normalized and should not be linted.
+        #
+        # `module_function` makes YARD register one definition twice: as a public
+        # class method and as a private instance method.
+        #
+        # One of the two is built with `CodeObjects::Base#copy_to` which assigns a
+        # docstring which is a normalized copy of the original, authored docstring
+        # that preserves content but not layout.
+        #
+        # The normalized docstring drops the blank lines between tags, moves param
+        # types ahead of param names, and folds in tags inherited from the enclosing
+        # namespace (such as an api tag). Linting the normalized docstring reports
+        # layout offenses against text no one wrote.
+        #
+        # The authored docstring is the one YARD tracks back to a range of source
+        # lines.
+        #
+        # For `module_function def name` neither the original object nor its copy
+        # carries a line range. For this form, the instance method holds the original
+        # docstring (YARD::Handlers::Ruby::ModuleFunctionHandler copies it to the
+        # class method).
+        #
+        # @param object [YARD::CodeObjects::Base] the code object to check
+        # @return [Boolean] true if the object's docstring is a normalized copy
+        def module_function_copy?(object)
+          return false unless object.type == :method
+          # Checked before the twin lookup, which scans the namespace's children:
+          # an object YARD tracked back to source lines is authored, whatever it
+          # is paired with, and most objects are
+          return false if object.docstring.line_range
+
+          twin = module_function_twin(object)
+          return false unless twin
+          return true if twin.docstring.line_range
+
+          object.scope == :class
+        end
+
+        # Finds the other object registered for a module_function definition.
+        # @param object [YARD::CodeObjects::Base] one half of the pair
+        # @return [YARD::CodeObjects::MethodObject, nil] the other half, or nil
+        #   when the object does not come from module_function
+        def module_function_twin(object)
+          return nil unless object.respond_to?(:scope)
+          # `def CONST.name` leaves a Proxy or ConstantObject namespace with no
+          # children; Proxy#is_a? answers for the resolved object
+          return nil unless object.namespace.is_a?(YARD::CodeObjects::NamespaceObject)
+
+          twin = object.namespace.child(
+            name: object.name,
+            scope: (object.scope == :class) ? :instance : :class
+          )
+
+          return nil unless twin
+          return nil unless twin.file == object.file && twin.line == object.line
+          # Both halves point at the same definition, but only the class method
+          # is flagged as a module function by YARD.
+          return nil unless [object, twin].any? { |o| o.respond_to?(:module_function?) && o.module_function? }
+
+          twin
+        end
+
         # Converts a zero-based line offset within a docstring's text into an
         # absolute line number in the source file, so offenses can point at
         # the offending documentation line instead of the definition line.

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

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

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module ReferenceTypo
+          # Builds human-readable messages for ReferenceTypo violations
+          class MessagesBuilder
+            class << self
+              # Formats a reference typo violation message
+              # @param offense [Hash] offense details with :reference and :suggestion keys
+              # @return [String] formatted message
+              def call(offense)
+                "Reference '#{offense[:reference]}' does not resolve " \
+                  "(did you mean '#{offense[:suggestion]}'?)"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module ReferenceTypo
+          # Parser for ReferenceTypo validator output
+          class Parser < ::Yard::Lint::Parsers::Base
+            # Parses validator output and extracts reference typo violations
+            # Expected format (two lines per violation):
+            #   file.rb:LINE: ObjectName
+            #   reference|suggestion
+            # @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
+
+                reference, suggestion = details_line.split('|', 2)
+                next if reference.to_s.empty? || suggestion.to_s.empty?
+
+                {
+                  location: location_match[1],
+                  line: location_match[2].to_i,
+                  object_name: location_match[3],
+                  reference: reference,
+                  suggestion: suggestion
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module ReferenceTypo
+          # Result wrapper for ReferenceTypo validator
+          class Result < Results::Base
+            self.default_severity = 'warning'
+            self.offense_type = 'line'
+            self.offense_name = 'ReferenceTypo'
+
+            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