yard-lint 1.12.0 → 1.13.0

data/lib/yard/lint/formatters/sarif.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'pathname'
+require 'digest'
+
+module Yard
+  module Lint
+    module Formatters
+      # Renders lint results as SARIF 2.1.0 (Static Analysis Results Interchange
+      # Format) - the JSON format GitHub code scanning and other result aggregators
+      # ingest, so yard-lint offenses can surface as PR annotations / Security-tab
+      # alerts instead of being buried in CI logs.
+      #
+      # This is output only: it does not change which offenses are reported, the
+      # exit code, or any configuration - it is an alternative rendering of the
+      # same result. Rule metadata (`rules[]`) is populated from each validator's
+      # own YARD documentation via {Explainer.describe}.
+      class Sarif
+        # SARIF 2.1.0 JSON schema URI, emitted as the document's `$schema`.
+        # @return [String]
+        SCHEMA_URI = 'https://json.schemastore.org/sarif-2.1.0.json'
+
+        # Tool information URI, emitted as the driver's `informationUri`.
+        # @return [String]
+        INFORMATION_URI = 'https://github.com/mensfeld/yard-lint'
+
+        # Help URI for each rule (the wiki validator reference).
+        # @return [String]
+        HELP_URI = 'https://github.com/mensfeld/yard-lint/wiki/Validators'
+
+        # SARIF supports only error/warning/note (plus none). yard-lint's
+        # `convention` maps to note, and `never` (report-only) maps to none.
+        # @return [Hash{String => String}]
+        SEVERITY_LEVELS = {
+          'error' => 'error',
+          'warning' => 'warning',
+          'convention' => 'note',
+          'never' => 'none'
+        }.freeze
+
+        # Fallback SARIF level for any unrecognized severity.
+        # @return [String]
+        DEFAULT_LEVEL = 'warning'
+
+        # partialFingerprints key, versioned so the scheme can evolve without
+        # invalidating history. GitHub uses it to correlate results across runs.
+        # @return [String]
+        FINGERPRINT_KEY = 'yardLintOffense/v1'
+
+        # @param offenses [Array<Hash>] offense hashes (from `result.offenses`)
+        # @param base_dir [String] directory that offense paths are made relative
+        #   to, so GitHub can map them onto the repository (default: current dir)
+        def initialize(offenses, base_dir: Dir.pwd)
+          @offenses = offenses
+          @base_dir = base_dir
+        end
+
+        # @return [String] pretty-printed SARIF 2.1.0 JSON
+        def generate
+          JSON.pretty_generate(document)
+        end
+
+        # @return [Hash] the SARIF document as a Ruby hash
+        def document
+          rule_ids = @offenses.map { |offense| offense[:validator] }.compact.uniq
+          rule_index = rule_ids.each_with_index.to_h
+
+          {
+            '$schema' => SCHEMA_URI,
+            'version' => '2.1.0',
+            'runs' => [
+              {
+                'tool' => { 'driver' => driver(rule_ids) },
+                'results' => @offenses.map { |offense| result(offense, rule_index) }
+              }
+            ]
+          }
+        end
+
+        private
+
+        # @param rule_ids [Array<String>] distinct validator names, in result order
+        # @return [Hash] the SARIF tool driver, including rule metadata
+        def driver(rule_ids)
+          {
+            'name' => 'yard-lint',
+            'informationUri' => INFORMATION_URI,
+            'version' => Yard::Lint::VERSION,
+            'rules' => rule_ids.map { |id| rule(id) }
+          }
+        end
+
+        # @param id [String] validator name (e.g. 'Tags/TypeSyntax')
+        # @return [Hash] a SARIF reportingDescriptor for the validator
+        def rule(id)
+          entry = {
+            'id' => id,
+            'name' => id.split('/').last,
+            'helpUri' => HELP_URI,
+            'defaultConfiguration' => { 'level' => level(default_severity(id)) }
+          }
+
+          described = Explainer.describe(id)
+          if described
+            entry['shortDescription'] = { 'text' => described[:short] }
+            entry['fullDescription'] = { 'text' => described[:full] }
+          end
+
+          entry
+        end
+
+        # @param offense [Hash] an offense hash
+        # @param rule_index [Hash{String => Integer}] validator name to rule index
+        # @return [Hash] a SARIF result
+        def result(offense, rule_index)
+          uri = relative_uri(offense[:location])
+          entry = {}
+
+          # ruleId/ruleIndex are optional in SARIF; omit them (rather than emit
+          # null, which is schema-invalid) for the rare offense with no validator.
+          validator = offense[:validator]
+          if validator
+            entry['ruleId'] = validator
+            entry['ruleIndex'] = rule_index[validator]
+          end
+
+          entry['level'] = level(offense[:severity])
+          entry['message'] = { 'text' => offense[:message].to_s }
+          entry['locations'] = [location(offense, uri)]
+          entry['partialFingerprints'] = { FINGERPRINT_KEY => fingerprint(offense, uri) }
+          entry
+        end
+
+        # @param offense [Hash] an offense hash
+        # @param uri [String] the artifact URI (already made relative)
+        # @return [Hash] a SARIF location
+        def location(offense, uri)
+          {
+            'physicalLocation' => {
+              'artifactLocation' => { 'uri' => uri },
+              'region' => { 'startLine' => start_line(offense) }
+            }
+          }
+        end
+
+        # A line-independent fingerprint so GitHub correlates the same offense
+        # across commits without churn (close/reopen) when unrelated lines shift.
+        # Keys on the validator, file, and offending object, excluding the line
+        # number and (when an object is identified) the message, so a re-worded
+        # message does not churn alerts. Validators that do not identify an object
+        # fall back to a normalized message, so distinct offenses in one file
+        # still get distinct fingerprints instead of collapsing into one alert.
+        # @param offense [Hash] an offense hash
+        # @param uri [String] the artifact URI (already made relative)
+        # @return [String] a stable hex digest
+        def fingerprint(offense, uri)
+          element = offense[:element].to_s
+          # Tag the identity with its source so an element that happens to equal
+          # another offense's normalized message cannot collide.
+          identity = element.empty? ? "m:#{normalized_message(offense[:message])}" : "e:#{element}"
+          parts = [offense[:validator], uri, identity]
+          Digest::SHA256.hexdigest(parts.map(&:to_s).join("\x00"))
+        end
+
+        # Message reduced to a stable identity for offenses with no :element:
+        # whitespace is collapsed so trivial formatting differences do not churn
+        # alerts. Case is preserved - messages embed case-sensitive names (types,
+        # methods, constants), so downcasing could merge genuinely distinct offenses.
+        # @param message [String, nil] the offense message
+        # @return [String] the normalized message
+        def normalized_message(message)
+          message.to_s.gsub(/\s+/, ' ').strip
+        end
+
+        # @param severity [String, nil] a yard-lint severity
+        # @return [String] the SARIF level
+        def level(severity)
+          SEVERITY_LEVELS.fetch(severity.to_s, DEFAULT_LEVEL)
+        end
+
+        # SARIF regions are 1-based; guard against a missing or zero line.
+        # @param offense [Hash] an offense hash
+        # @return [Integer] a 1-based start line
+        def start_line(offense)
+          line = (offense[:location_line] || offense[:line]).to_i
+          line.positive? ? line : 1
+        end
+
+        # Make a path repository-relative so GitHub maps it onto a file. Paths
+        # already relative are kept; a path outside base_dir keeps its original
+        # value rather than emitting a `../` or absolute URI.
+        # @param location [String, nil] the offense location path
+        # @return [String] a relative URI where possible
+        def relative_uri(location)
+          path = location.to_s
+          return path if path.empty?
+
+          absolute = File.absolute_path(path, @base_dir)
+          relative = Pathname.new(absolute).relative_path_from(Pathname.new(@base_dir)).to_s
+          relative.start_with?('..') ? path : relative
+        rescue ArgumentError
+          # relative_path_from raises across platforms/mixed roots; fall back.
+          path
+        end
+
+        # The validator's default severity, from a defaults-only config, for the
+        # rule's defaultConfiguration.level.
+        # @param id [String] validator name
+        # @return [String] default severity
+        def default_severity(id)
+          @default_config ||= Config.new
+          @default_config.validator_severity(id)
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/git.rb

@@ -89,15 +89,17 @@ module Yard
           filter_ruby_files(files.uniq, path)
         end
 
-        private
-
-        # Absolute path to the repository root (git reports paths relative to it)
+        # Absolute path to the repository root (git reports paths relative to it).
+        # Used to make report paths repository-relative; falls back to the current
+        # directory outside a git repo.
         # @return [String] repo root, or the current directory if it can't be determined
         def repository_root
           stdout, _stderr, status = Open3.capture3('git', 'rev-parse', '--show-toplevel')
           status.success? ? stdout.strip : Dir.pwd
         end
 
+        private
+
         # Ensure we're in a git repository
         # @raise [Error] if not in a git repository
         def ensure_git_repository!

data/lib/yard/lint/result_builder.rb

@@ -22,8 +22,7 @@ module Yard
         validator_cfg = ConfigLoader.validator_config(validator_name)
         return nil unless validator_module && validator_cfg
 
-        # Skip if this validator is a child of a composite
-        return nil if composite_child?(validator_name)
+        return nil if reported_by_composite?(validator_name)
 
         # Handle composite validators (those that combine multiple validators)
         unless validator_cfg.combines_with.empty?
@@ -36,15 +35,17 @@ module Yard
 
       private
 
-      # Check if a validator is a child of a composite validator
+      # Check if a composite parent reports this validator's offenses
+      # A child reports on its own only when --only selects it without its parent
       # @param validator_name [String] validator name to check
-      # @return [Boolean] true if this is a composite child
-      def composite_child?(validator_name)
+      # @return [Boolean] true if a composite parent reports it
+      def reported_by_composite?(validator_name)
         ConfigLoader::ALL_VALIDATORS.any? do |parent_name|
           parent_cfg = ConfigLoader.validator_config(parent_name)
           next unless parent_cfg
+          next unless parent_cfg.combines_with.include?(validator_name)
 
-          parent_cfg.combines_with.include?(validator_name)
+          config.only_validators.empty? || config.only_validators.include?(parent_name)
         end
       end
 

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

@@ -155,6 +155,9 @@ module Yard
         #   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,

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