yard-lint 1.12.0 → 1.13.0

data/README.md

@@ -114,8 +114,14 @@ yard-lint --auto-gen-config
 yard-lint lib/
 
 # Fix violations incrementally by removing exclusions from .yard-lint-todo.yml
+
+# Fail (exit 1) when .yard-lint-todo.yml has entries that no longer match any offense
+# (use the PATH of your normal run; a PATH only limits which entries are reported)
+yard-lint --check-todo lib/
 ```
 
+`.yard-lint-todo.yml` is written and read next to the loaded `.yard-lint.yml` (or in the current directory without one), and its entries are relative to that directory, so the baseline works from any directory you run yard-lint in.
+
 **Learn more:** [Incremental Adoption Guide](https://github.com/mensfeld/yard-lint/wiki/Incremental-Adoption)
 
 ### Check Documentation Coverage
@@ -208,6 +214,26 @@ Then `:make` lints the current file and `:cnext` / `:cprev` jump between offense
 
 Then `M-x compile` and `M-g n` / `M-g p` navigate between offenses.
 
+### SARIF Output (GitHub Code Scanning)
+
+Use `--format sarif` to emit [SARIF 2.1.0](https://sarifweb.azurewebsites.net/), the format GitHub code scanning and most result aggregators ingest. Uploading it makes yard-lint offenses appear as annotations in the PR "Files changed" view and the repository Security tab, instead of being buried in CI logs:
+
+```bash
+yard-lint --format sarif lib/ > yard-lint.sarif
+```
+
+Each rule carries its description (from the validator's own YARD docs), and severities map to SARIF levels (`error` → error, `warning` → warning, `convention` → note). Artifact paths are emitted repository-relative so GitHub maps them onto your files. In GitHub Actions, upload the file with `github/codeql-action/upload-sarif`:
+
+```yaml
+- run: bundle exec yard-lint --format sarif lib/ > yard-lint.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: yard-lint.sarif
+```
+
+(Run yard-lint from the repository root so paths resolve correctly; `continue-on-error` lets the upload step run even when offenses are found.)
+
 ## Configuration Basics
 
 Create a `.yard-lint.yml` file in your project root:
@@ -322,10 +348,35 @@ Documentation/UnderfilledLines:
 
 **Key features:**
 - Per-validator control (enable/disable, severity, exclusions)
+- Category-level defaults (enable/disable, severity, exclusions) for a whole department
 - Configuration inheritance with `inherit_from` and `inherit_gem`
 - Automatic configuration validation with helpful error messages
 - Per-validator YARD options and file exclusions
 
+**Category-level defaults:** set `Enabled` or `Severity` on a category (`Documentation`, `Tags`, `Warnings`, `Semantic`) to apply it to every validator in that department. A per-validator setting always wins over the category, which in turn wins over the validator's built-in default:
+
+```yaml
+# Make every Tags/* offense an error...
+Tags:
+  Severity: error
+
+# ...except Tags/Order, which stays a convention
+Tags/Order:
+  Severity: convention
+```
+
+A category-level `Exclude` is combined with each validator's own `Exclude` (it is not replaced by it), so these files are skipped by every `Documentation/*` validator, including one that sets its own `Exclude`:
+
+```yaml
+Documentation:
+  Exclude:
+    - 'lib/generated/**/*'
+```
+
+A category accepts only the keys `Enabled` (`true` or `false`), `Severity` and `Exclude`; an unknown key or a non-boolean `Enabled` fails configuration validation.
+
+`Exclude` patterns at every level are relative to the directory of the loaded `.yard-lint.yml` (or the current directory without one), whatever PATH or directory you run yard-lint from. A file outside that directory is matched as `../...` (with `--config config/yard-lint.yml`, write `../lib/generated/**/*`); absolute patterns also work.
+
 **Learn more:** [Complete Configuration Guide](https://github.com/mensfeld/yard-lint/wiki/Configuration)
 
 ## Catching Orphaned Documentation Comments
@@ -434,6 +485,47 @@ The validator reports one offense per wasteful paragraph and is deliberately con
 
 Unlike `LineLength` (which measures an objective property), "this line should have been longer" is a stylistic judgement. Projects that use **semantic line breaks** (one sentence or clause per line, see [sembr.org](https://sembr.org)) are never flagged - any paragraph whose non-final lines all end at a sentence boundary (`.?!:;`) is treated as intentional. Leave the validator off, or add `,` to `SentenceEndChars`, if that style is used heavily.
 
+## Catching Typos in References
+
+The `Documentation/ReferenceTypo` validator (enabled by default, severity `warning`) checks `{Foo#bar}` links in docstrings and tag text, and `@see` targets. When a reference does not resolve and a close match exists in its namespace, it reports the reference and suggests the closest name:
+
+```ruby
+# Bad - reports: Reference 'Parser#prase' does not resolve (did you mean 'Parser#parse'?)
+# Delegates to {Parser#prase}
+def call; end
+
+# Good
+# Delegates to {Parser#parse}
+def call; end
+```
+
+To keep false positives low, it skips references into namespaces YARD does not know (stdlib, other gems), methods that a loaded Ruby ancestor may define (e.g. `{#to_s}`), names with no close match, and code spans and code blocks. A bare constant such as `{Kafka}` is only compared with constants of the enclosing namespaces, never with top-level ones, so a constant of a gem YARD did not parse is not reported as a typo of a similar project name.
+
+## Checking @overload Tags
+
+YARD checks `@param` names only against the method's own signature, never the tags inside an `@overload`. The `Tags/OverloadConsistency` validator (enabled by default, severity `warning`) checks each overload against its own signature and reports:
+
+- a `@param` that names no parameter of that overload
+- a parameter with no `@param`, when the overload documents at least one other parameter (splat and block parameters are not required; a `@param` on the method docstring counts for every overload)
+- an overload with no `@return`, when another overload of the method has one and the method docstring has none
+
+```ruby
+# Bad - reports: Overload 'fetch(key)' documents @param 'name', which is not in its signature
+#                Overload 'fetch(key)' has no @param for 'key'
+# @overload fetch(key)
+#   @param name [String] the key
+#   @return [Object]
+def fetch(*args); end
+
+# Good
+# @overload fetch(key)
+#   @param key [String] the key
+#   @return [Object]
+def fetch(*args); end
+```
+
+Overloads that forward arguments (`...`) or take anonymous `*`, `**` or `&` parameters are not checked for unknown names.
+
 ## Handling Non-Standard Types
 
 By default `Tags/InvalidTypes` accepts all built-in Ruby classes, constants, and a set of YARD pseudo-types (`nil`, `true`, `false`, `self`, `void`, `Boolean`, `undefined`, `unspecified`, `unknown`). If your project uses additional type names that are not real Ruby classes - project-specific aliases, LSP extensions, or informal conventions - you can declare them via `ExtraTypes` so yard-lint does not report them as `InvalidTagType` offenses.
@@ -530,7 +622,7 @@ Configuration:
   -c, --config FILE       Path to config file (default: .yard-lint.yml)
 
 Output:
-  -f, --format FORMAT     Output format (text, json, quickfix)
+  -f, --format FORMAT     Output format (text, json, quickfix, sarif)
   -q, --quiet             Quiet mode (only show summary)
       --stats             Show documentation coverage statistics
       --[no-]progress     Show progress indicator (default: auto-detect TTY)
@@ -555,6 +647,7 @@ Configuration Generation:
       --force             Force overwrite when using --init
       --auto-gen-config   Generate .yard-lint-todo.yml to silence existing violations
       --regenerate-todo   Regenerate .yard-lint-todo.yml (overwrites existing)
+      --check-todo        Report .yard-lint-todo.yml entries that no longer match any offense
       --exclude-limit N   Min files before grouping into pattern (default: 15)
 
 Information:

data/bin/yard-lint

@@ -18,7 +18,7 @@ begin
     config_file = file
   end
 
-  opts.on('-f', '--format FORMAT', 'Output format (text, json, quickfix)') do |format|
+  opts.on('-f', '--format FORMAT', 'Output format (text, json, quickfix, sarif)') do |format|
     options[:format] = format
   end
 
@@ -99,6 +99,10 @@ begin
     options[:force] = true
   end
 
+  opts.on('--check-todo', 'Report .yard-lint-todo.yml entries that no longer match any offense') do
+    options[:check_todo] = true
+  end
+
   opts.on('--exclude-limit COUNT', Integer, 'Min files before grouping into pattern (default: 15)') do |count|
     options[:exclude_limit] = count
   end
@@ -122,12 +126,14 @@ begin
     puts '  yard-lint --changed                            # Lint only uncommitted files'
     puts '  yard-lint --format json lib/                   # Output in JSON format'
     puts '  yard-lint --format quickfix lib/               # Output in quickfix format (Vim/Emacs)'
+    puts '  yard-lint --format sarif lib/                  # Output SARIF 2.1.0 (GitHub code scanning)'
     puts '  yard-lint --init                               # Generate default config'
     puts '  yard-lint --init --strict                      # Generate strict config'
     puts '  yard-lint --update                             # Update config with new validators'
     puts '  yard-lint --auto-gen-config                    # Generate todo file for existing violations'
     puts '  yard-lint --regenerate-todo                    # Regenerate todo file'
     puts '  yard-lint --auto-gen-config --exclude-limit 10 # Custom grouping threshold'
+    puts '  yard-lint --check-todo                         # Fail if todo file has unused entries'
     puts '  cat lib/foo.rb | yard-lint --stdin lib/foo.rb  # Lint source piped from stdin'
     exit
   end
@@ -154,6 +160,35 @@ report_unknown_validators = lambda do |names|
   puts "\nRun `yard-lint --explain VALIDATOR` to see what a validator checks."
 end
 
+# Apply --only filter if provided, exiting on unknown validator names
+apply_only = lambda do |config|
+  next unless options[:only]
+
+  unknown = options[:only] - Yard::Lint::ConfigLoader::ALL_VALIDATORS
+  if unknown.any?
+    report_unknown_validators.call(unknown)
+    exit 1
+  end
+  config.only_validators = options[:only]
+end
+
+# Load the config (-c file or auto-discovered), exiting with a configuration error
+# instead of a backtrace when it is missing, invalid or inherits in a cycle.
+# Shared by the normal run, --auto-gen-config and --check-todo.
+load_config = lambda do
+  if config_file
+    Yard::Lint::Config.from_file(config_file)
+  else
+    Yard::Lint::Config.load || Yard::Lint::Config.new
+  end
+rescue Yard::Lint::Errors::ConfigFileNotFoundError, Yard::Lint::Errors::CircularDependencyError => e
+  puts "Configuration Error: #{e.message}"
+  exit 1
+rescue Yard::Lint::Errors::InvalidConfigError => e
+  puts "Configuration Error:\n#{e.message}"
+  exit 1
+end
+
 # Handle --explain flag (early exit; needs no config or path)
 if options[:explain]
   name = options[:explain]
@@ -221,12 +256,7 @@ end
 # Handle --auto-gen-config flag
 if options[:auto_gen_config]
   begin
-    # Load config
-    config = if config_file
-               Yard::Lint::Config.from_file(config_file)
-             else
-               Yard::Lint::Config.load || Yard::Lint::Config.new
-             end
+    config = load_config.call
 
     # Get path argument
     path = ARGV[0] || '.'
@@ -254,6 +284,26 @@ if options[:auto_gen_config]
   end
 end
 
+# Handle --check-todo flag
+if options[:check_todo]
+  begin
+    config = load_config.call
+    apply_only.call(config)
+
+    result = Yard::Lint::TodoGenerator.check(path: ARGV[0] || '.', config: config)
+
+    puts result[:message]
+    exit result[:unused_entries].empty? ? 0 : 1
+  rescue Yard::Lint::Errors::TodoFileNotFoundError, Yard::Lint::Errors::FileNotFoundError,
+         Yard::Lint::Git::Error => e
+    puts "Error: #{e.message}"
+    exit 1
+  rescue Yard::Lint::Errors::InvalidConfigError => e
+    puts "Configuration Error:\n#{e.message}"
+    exit 1
+  end
+end
+
 # Get path argument (defaults to current directory)
 path = ARGV[0] || '.'
 
@@ -271,43 +321,23 @@ end
 YARD::Registry.clear
 
 # Load config and apply CLI overrides
-begin
-  config = if config_file
-             Yard::Lint::Config.from_file(config_file)
-           else
-             Yard::Lint::Config.load || Yard::Lint::Config.new
-           end
-rescue Yard::Lint::Errors::ConfigFileNotFoundError => e
-  puts "Configuration Error: #{e.message}"
-  exit 1
-rescue Yard::Lint::Errors::InvalidConfigError => e
-  puts "Configuration Error:\n#{e.message}"
-  exit 1
-end
+config = load_config.call
 
 # Apply CLI min_coverage override if provided
 config.min_coverage = options[:min_coverage] if options[:min_coverage]
 
-# Apply --only filter if provided
-if options[:only]
-  unknown = options[:only] - Yard::Lint::ConfigLoader::ALL_VALIDATORS
-  if unknown.any?
-    report_unknown_validators.call(unknown)
-    exit 1
-  end
-  config.only_validators = options[:only]
-end
+apply_only.call(config)
 
 # Validate the output format before doing any (potentially long) work, rather
 # than running the whole lint and only then rejecting an unknown format.
-valid_formats = %w[text json quickfix]
+valid_formats = %w[text json quickfix sarif]
 if options[:format] && !valid_formats.include?(options[:format])
   puts "Error: Unknown format '#{options[:format]}'. Valid formats: #{valid_formats.join(', ')}"
   exit 1
 end
 
-# Suppress progress for quickfix to avoid contaminating machine-readable output
-options[:progress] = false if options[:format] == 'quickfix' && options[:progress].nil?
+# Suppress progress for machine-readable formats to avoid contaminating output
+options[:progress] = false if %w[quickfix sarif].include?(options[:format]) && options[:progress].nil?
 
 # Run the linter
 begin
@@ -356,6 +386,12 @@ when 'quickfix'
     puts "#{offense[:location]}:#{offense[:location_line]}: #{char}: #{offense[:validator]}: #{message}"
   end
   exit result.exit_code
+when 'sarif'
+  # Base paths on the repository root so GitHub can map offense URIs onto files
+  # even when yard-lint is run from a subdirectory.
+  sarif = Yard::Lint::Formatters::Sarif.new(result.offenses, base_dir: Yard::Lint::Git.repository_root)
+  puts sarif.generate
+  exit result.exit_code
 when 'text', nil
   # Calculate coverage stats if requested or configured
   coverage = result.documentation_coverage if options[:stats] || options[:min_coverage] || config.min_coverage

data/lib/yard/lint/config.rb

@@ -6,6 +6,7 @@ module Yard
     class Config
       attr_reader :raw_config, :validators
       attr_accessor :only_validators
+      attr_writer :base_dir
 
       # Default YAML config file name
       DEFAULT_CONFIG_FILE = '.yard-lint.yml'
@@ -16,6 +17,9 @@ module Yard
       # Metadata keys to skip when merging validator configs
       METADATA_KEYS = %w[Description StyleGuide VersionAdded VersionChanged].freeze
 
+      # File.fnmatch flags used for Exclude patterns
+      EXCLUDE_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
       # @param raw_config [Hash] raw configuration hash (new hierarchical format)
       def initialize(raw_config = {})
         @raw_config = raw_config
@@ -42,7 +46,7 @@ module Yard
           # Load with inheritance support
           merged_yaml = ConfigLoader.load(path)
 
-          new(merged_yaml)
+          new(merged_yaml) { |config| config.base_dir = File.dirname(File.expand_path(path)) }
         end
 
         # Search for and load config file from current directory upwards
@@ -173,29 +177,101 @@ module Yard
       end
 
       # Get validator severity
+      #
+      # Resolution order (highest priority first):
+      #   1. an explicit per-validator Severity in the user's config
+      #   2. a category-level Severity (e.g. `Documentation: { Severity: convention }`),
+      #      matching how category-level Enabled cascades in #validator_enabled?
+      #   3. the validator's built-in default Severity
+      #   4. the global 'warning' default
+      #
       # @param validator_name [String] full validator name
       # @return [String] severity level for this validator
       def validator_severity(validator_name)
+        # An explicit per-validator Severity in the user's config wins.
+        raw_validator = @raw_config[validator_name]
+        if raw_validator.is_a?(Hash) && raw_validator['Severity']
+          return raw_validator['Severity'].to_s
+        end
+
+        # Otherwise honor a category-level Severity, which previously validated
+        # but was ignored (the category-level Enabled key already cascades).
+        category = validator_name.split('/').first
+        raw_category = @raw_config[category]
+        if raw_category.is_a?(Hash) && raw_category['Severity']
+          return raw_category['Severity'].to_s
+        end
+
+        # Fall back to the validator's built-in default, then the global default.
         validator_config = validators[validator_name] || {}
         validator_config['Severity'] || 'warning'
       end
 
       # Get validator-specific exclude patterns
+      #
+      # A category-level Exclude (e.g. `Documentation: { Exclude: [...] }`) is
+      # unioned with the per-validator one rather than replaced by it, so a
+      # validator that sets its own Exclude still skips its category's files.
+      #
       # @param validator_name [String] full validator name
-      # @return [Array<String>] exclusion patterns for this validator
+      # @return [Array<String>] exclusion patterns for this validator (category + per-validator)
       def validator_exclude(validator_name)
         validator_config = validators[validator_name] || {}
-        validator_config['Exclude'] || []
+        raw_category = @raw_config[validator_name.split('/').first]
+        category_exclude = raw_category.is_a?(Hash) ? Array(raw_category['Exclude']) : []
+
+        (category_exclude + (validator_config['Exclude'] || [])).uniq
       end
 
-      # Combined global and per-validator exclusions
+      # Combined global, category and per-validator exclusions
       # Returns all exclusion patterns that apply to this validator
       # @param validator_name [String] full validator name
-      # @return [Array<String>] combined exclusion patterns (global + per-validator)
+      # @return [Array<String>] combined exclusion patterns (global + category + per-validator)
       def validator_all_excludes(validator_name)
         exclude + validator_exclude(validator_name)
       end
 
+      # Directory that Exclude patterns are relative to
+      # @return [String] directory of the loaded config file, or the current directory without one
+      def base_dir
+        @base_dir || Dir.pwd
+      end
+
+      # Whether a file matches any of the given Exclude patterns
+      # A pattern matches the path relative to {#base_dir} or the absolute path
+      # @param file [String] absolute file path, or one relative to the current directory
+      # @param patterns [Array<String>] glob patterns
+      # @return [Boolean] true if any pattern matches
+      def excluded_path?(file, patterns)
+        absolute = File.expand_path(file)
+        relative = relative_path(absolute)
+
+        patterns.any? do |pattern|
+          File.fnmatch(pattern, relative, EXCLUDE_FLAGS) || File.fnmatch(pattern, absolute, EXCLUDE_FLAGS)
+        end
+      end
+
+      # Path of a file relative to {#base_dir}
+      # Symlinks are resolved when the plain paths do not nest (/var is /private/var on macOS)
+      # @param file [String] absolute file path, or one relative to the current directory
+      # @return [String] relative path (with ../ for a file outside {#base_dir}), or the absolute
+      #   path when there is no relative one (another drive)
+      def relative_path(file)
+        absolute = File.expand_path(file)
+        base = File.expand_path(base_dir)
+        return absolute.delete_prefix("#{base}/") if absolute.start_with?("#{base}/")
+
+        from, to = begin
+          [File.realpath(absolute), File.realpath(base)]
+        rescue SystemCallError
+          [absolute, base]
+        end
+
+        Pathname.new(from).relative_path_from(Pathname.new(to)).to_s
+      rescue ArgumentError
+        absolute
+      end
+
       # Get validator-specific configuration value
       # @param validator_name [String] full validator name
       # @param key [String] configuration key

data/lib/yard/lint/config_validator.rb

@@ -4,23 +4,9 @@ module Yard
   module Lint
     # Validates configuration structure and values to catch typos and invalid settings
     class ConfigValidator
-      # Valid category names (from ConfigUpdater::CATEGORY_ORDER)
-      VALID_CATEGORIES = %w[Documentation Tags Warnings Semantic].freeze
-
-      # Keys that are valid at the root level but are not validators
-      SPECIAL_KEYS = %w[
-        AllValidators
-        inherit_from
-        inherit_gem
-      ].freeze
-
-      # Valid boolean values
-      BOOLEAN_VALUES = [true, false].freeze
-
       # @param raw_config [Hash] raw configuration hash to validate
       def initialize(raw_config)
         @raw_config = raw_config
-        @errors = []
       end
 
       # Validate configuration and raise error if invalid
@@ -36,191 +22,21 @@ module Yard
       # @return [void]
       # @raise [Errors::InvalidConfigError] if configuration is invalid
       def validate!
-        validate_root_keys!
-        validate_global_settings!
-        validate_validators!
+        result = Contracts::Config.new.call(@raw_config)
 
-        return if @errors.empty?
+        return if result.success?
 
-        raise Errors::InvalidConfigError, build_error_message
+        raise Errors::InvalidConfigError, build_error_message(result.errors.values)
       end
 
       private
 
-      # Validate root-level keys in configuration
-      def validate_root_keys!
-        @raw_config.each_key do |key|
-          # Skip special keys
-          next if SPECIAL_KEYS.include?(key)
-
-          # Skip category-level configs (e.g., 'Documentation', 'Tags')
-          next if VALID_CATEGORIES.include?(key)
-
-          # Validator names must contain a '/' (category/name format)
-          next if key.include?('/')
-
-          # If we get here, it's an unknown validator (missing category prefix)
-          @errors << "Unknown validator: '#{key}'"
-          suggest_validator_name(key)
-        end
-      end
-
-      # Validate AllValidators section
-      def validate_global_settings!
-        all_validators = @raw_config['AllValidators']
-        return unless all_validators
-
-        unless all_validators.is_a?(Hash)
-          @errors << "Invalid AllValidators: must be a Hash, got #{all_validators.class}"
-          return
-        end
-
-        # Only validate specific known settings, allow unknown keys to pass through
-        # This allows users to put custom data in AllValidators
-
-        # Validate FailOnSeverity value
-        fail_on = all_validators['FailOnSeverity']
-        if fail_on && !Config::VALID_SEVERITIES.include?(fail_on.to_s)
-          @errors << "Invalid FailOnSeverity: '#{fail_on}'"
-          @errors << "  Valid values: #{Config::VALID_SEVERITIES.join(', ')}"
-        end
-
-        # Validate MinCoverage value
-        min_cov = all_validators['MinCoverage']
-        if min_cov && (!min_cov.is_a?(Numeric) || min_cov < 0 || min_cov > 100)
-          @errors << "Invalid MinCoverage: '#{min_cov}'"
-          @errors << '  Must be a number between 0 and 100'
-        end
-
-        # Validate Exclude is an array
-        exclude = all_validators['Exclude']
-        if exclude && !exclude.is_a?(Array)
-          @errors << "Invalid Exclude in AllValidators: must be an array, got #{exclude.class}"
-        end
-
-        # Validate YardOptions is an array
-        yard_options = all_validators['YardOptions']
-        if yard_options && !yard_options.is_a?(Array)
-          @errors << "Invalid YardOptions in AllValidators: must be an array, got #{yard_options.class}"
-        end
-      end
-
-      # Validate validator-specific configurations
-      def validate_validators!
-        @raw_config.each do |key, value|
-          # Only process validator keys (containing '/')
-          next unless key.include?('/')
-
-          unless value.is_a?(Hash)
-            @errors << "Invalid configuration for validator '#{key}': expected a Hash, got #{value.class}"
-            next
-          end
-
-          validate_validator_exists!(key)
-          validate_validator_config!(key, value)
-        end
-      end
-
-      # Check if validator name exists
-      # @param validator_name [String] validator name to check
-      # @return [void]
-      def validate_validator_exists!(validator_name)
-        return if ConfigLoader::ALL_VALIDATORS.include?(validator_name)
-
-        @errors << "Unknown validator: '#{validator_name}'"
-        suggest_validator_name(validator_name)
-      end
-
-      # Validate individual validator configuration
-      # @param validator_name [String] validator name
-      # @param config [Hash] validator configuration hash
-      # @return [void]
-      def validate_validator_config!(validator_name, config)
-        # Validate Enabled value
-        enabled = config['Enabled']
-        if enabled && !BOOLEAN_VALUES.include?(enabled)
-          @errors << "Invalid Enabled value for #{validator_name}: '#{enabled}'"
-          @errors << '  Must be true or false'
-        end
-
-        # Validate Severity value
-        severity = config['Severity']
-        if severity && !Config::VALID_SEVERITIES.include?(severity.to_s)
-          @errors << "Invalid Severity for #{validator_name}: '#{severity}'"
-          @errors << "  Valid values: #{Config::VALID_SEVERITIES.join(', ')}"
-          suggest_similar_severity(severity.to_s)
-        end
-
-        # Validate Exclude is an array
-        exclude = config['Exclude']
-        if exclude && !exclude.is_a?(Array)
-          @errors << "Invalid Exclude for #{validator_name}: must be an array, got #{exclude.class}"
-        end
-
-        # Validate YardOptions is an array
-        yard_options = config['YardOptions']
-        if yard_options && !yard_options.is_a?(Array)
-          @errors << "Invalid YardOptions for #{validator_name}: must be an array, got #{yard_options.class}"
-        end
-
-        # Check for unknown validator-specific keys
-        validate_validator_specific_keys!(validator_name, config)
-      end
-
-      # Validate validator-specific configuration keys
-      # @param validator_name [String] validator name
-      # @param config [Hash] validator configuration hash
-      # @return [void]
-      def validate_validator_specific_keys!(validator_name, config)
-        # Skip if validator doesn't exist (already reported)
-        return unless ConfigLoader::ALL_VALIDATORS.include?(validator_name)
-
-        validator_config_class = ConfigLoader.validator_config(validator_name)
-        return unless validator_config_class
-
-        # Base config keys that are valid for all validators
-        base_keys = %w[Enabled Severity Exclude YardOptions]
-        valid_keys = validator_config_class.defaults.keys + Config::METADATA_KEYS + base_keys
-
-        config.each_key do |key|
-          next if valid_keys.include?(key)
-
-          @errors << "Unknown configuration key for #{validator_name}: '#{key}'"
-          @errors << "  Valid keys: #{valid_keys.uniq.sort.join(', ')}"
-        end
-      end
-
-      # Suggest similar validator names using did_you_mean
-      # @param invalid_name [String] invalid validator name
-      # @return [void]
-      def suggest_validator_name(invalid_name)
-        checker = DidYouMean::SpellChecker.new(dictionary: ConfigLoader::ALL_VALIDATORS)
-        suggestions = checker.correct(invalid_name)
-
-        if suggestions.any?
-          @errors << "  Did you mean: #{suggestions.first}?"
-        else
-          @errors << '  See https://github.com/mensfeld/yard-lint/wiki/Validators ' \
-                     'for all available validators'
-        end
-      end
-
-      # Suggest similar severity values
-      # @param invalid_severity [String] invalid severity value
-      # @return [void]
-      def suggest_similar_severity(invalid_severity)
-        checker = DidYouMean::SpellChecker.new(dictionary: Config::VALID_SEVERITIES)
-        suggestions = checker.correct(invalid_severity)
-
-        if suggestions.any?
-          @errors << "  Did you mean: #{suggestions.first}?"
-        end
-      end
-
       # Build comprehensive error message
-      def build_error_message
+      # @param messages [Array<String>] error messages, each one or more lines
+      # @return [String] error message with one indented line per error line
+      def build_error_message(messages)
         header = 'Invalid configuration detected:'
-        errors_text = @errors.map { |e| "  #{e}" }.join("\n")
+        errors_text = messages.flat_map { |message| message.split("\n") }.map { |e| "  #{e}" }.join("\n")
 
         "#{header}\n#{errors_text}"
       end