yard-lint 1.3.0 → 1.5.0

data/Rakefile

@@ -3,8 +3,15 @@
 require 'bundler/setup'
 require 'bundler/gem_tasks'
 require 'etc'
+require 'rake/testtask'
 
-namespace :spec do
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.ruby_opts << '-r test_helper'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+namespace :test do
   # Determine optimal number of parallel processes
   # Use all CPUs if less than 8, otherwise cap at 8
   def parallel_process_count
@@ -12,13 +19,9 @@ namespace :spec do
     [cpus, 8].min
   end
 
-  desc 'Run integration specs in parallel'
-  task :integrations do
-    sh "bundle exec parallel_rspec -n #{parallel_process_count} spec/integrations/"
-  end
-
-  desc 'Run all specs in parallel'
+  desc 'Run all tests in parallel'
   task :parallel do
-    sh "bundle exec parallel_rspec -n #{parallel_process_count} spec/"
+    executable = 'ruby -Itest -r test_helper'
+    sh "PARALLEL_TESTS_EXECUTABLE='#{executable}' bundle exec parallel_test -n #{parallel_process_count} test/"
   end
 end

data/bin/yard-lint

@@ -78,6 +78,22 @@ OptionParser.new do |opts|
     options[:force] = true
   end
 
+  opts.separator ''
+  opts.separator 'Todo file generation:'
+
+  opts.on('--auto-gen-config', 'Generate .yard-lint-todo.yml to silence existing violations') do
+    options[:auto_gen_config] = true
+  end
+
+  opts.on('--regenerate-todo', 'Regenerate .yard-lint-todo.yml (overwrites existing)') do
+    options[:auto_gen_config] = true
+    options[:force] = true
+  end
+
+  opts.on('--exclude-limit COUNT', Integer, 'Min files before grouping into pattern (default: 15)') do |count|
+    options[:exclude_limit] = count
+  end
+
   opts.on('-v', '--version', 'Show version') do
     puts "yard-lint #{Yard::Lint::VERSION}"
     exit
@@ -98,6 +114,9 @@ OptionParser.new do |opts|
     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'
     exit
   end
 end.parse!
@@ -142,6 +161,41 @@ if options[:update]
   end
 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
+
+    # Get path argument
+    path = ARGV[0] || '.'
+
+    # Generate todo file
+    result = Yard::Lint::TodoGenerator.generate(
+      path: path,
+      config: config,
+      force: options[:force] || false,
+      exclude_limit: options[:exclude_limit] || 15
+    )
+
+    puts result[:message]
+    exit 0
+  rescue Yard::Lint::Errors::InvalidConfigError => e
+    puts "Configuration Error:\n#{e.message}"
+    exit 1
+  rescue Yard::Lint::Errors::TodoFileExistsError => e
+    puts "Error: #{e.message}"
+    exit 1
+  rescue Yard::Lint::Git::Error, Yard::Lint::Errors::FileNotFoundError => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+end
+
 # Get path argument (defaults to current directory)
 path = ARGV[0] || '.'
 
@@ -149,11 +203,16 @@ path = ARGV[0] || '.'
 YARD::Registry.clear
 
 # Load config and apply CLI overrides
-config = if config_file
-           Yard::Lint::Config.from_file(config_file)
-         else
-           Yard::Lint::Config.load || Yard::Lint::Config.new
-         end
+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::InvalidConfigError => e
+  puts "Configuration Error:\n#{e.message}"
+  exit 1
+end
 
 # Apply CLI min_coverage override if provided
 config.min_coverage = options[:min_coverage] if options[:min_coverage]

data/lib/yard/lint/config.rb

@@ -20,6 +20,10 @@ module Yard
       # @param raw_config [Hash] raw configuration hash (new hierarchical format)
       def initialize(raw_config = {})
         @raw_config = raw_config
+
+        # Validate configuration structure and values
+        ConfigValidator.validate!(@raw_config) unless raw_config.empty?
+
         @validators = build_validators_config
         @only_validators = []
 

data/lib/yard/lint/config_validator.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+# YARD Lint - comprehensive linter for YARD documentation
+module Yard
+  # YARD Lint module providing linting functionality for YARD documentation
+  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
+      # @param raw_config [Hash] raw configuration hash to validate
+      # @return [void]
+      # @raise [Errors::InvalidConfigError] if configuration is invalid
+      def self.validate!(raw_config)
+        validator = new(raw_config)
+        validator.validate!
+      end
+
+      # Perform validation
+      # @return [void]
+      # @raise [Errors::InvalidConfigError] if configuration is invalid
+      def validate!
+        validate_root_keys!
+        validate_global_settings!
+        validate_validators!
+
+        return if @errors.empty?
+
+        raise Errors::InvalidConfigError, build_error_message
+      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 << '  Run `yard-lint --list-validators` to see 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
+        header = 'Invalid configuration detected:'
+        errors_text = @errors.map { |e| "  #{e}" }.join("\n")
+
+        "#{header}\n#{errors_text}"
+      end
+    end
+  end
+end

data/lib/yard/lint/errors.rb

@@ -18,6 +18,12 @@ module Yard
 
       # Raised when a specified file or directory does not exist
       class FileNotFoundError < BaseError; end
+
+      # Raised when .yard-lint-todo.yml already exists without force flag
+      class TodoFileExistsError < BaseError; end
+
+      # Raised when configuration is invalid
+      class InvalidConfigError < BaseError; end
     end
   end
 end

data/lib/yard/lint/executor/in_process_registry.rb

@@ -33,6 +33,15 @@ module Yard
             original_level = YARD::Logger.instance.level
             YARD::Logger.instance.level = 4 # Only show fatal errors
 
+            # First pass: parse all files to process directive definitions
+            YARD.parse(files)
+
+            # Clear checksums to force reparsing without clearing the registry.
+            # This allows macro definitions from the first pass to be available
+            # during the second pass, enabling proper directive expansion regardless of parse order.
+            YARD::Registry.checksums.clear
+
+            # Second pass: reparse files now that all directive definitions are available
             @warnings = capture_warnings { YARD.parse(files) }
             @parsed = true
 

data/lib/yard/lint/path_grouper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Groups file paths into patterns when beneficial
+    class PathGrouper
+      # Coverage threshold for directory-level grouping (80%)
+      DIRECTORY_COVERAGE_THRESHOLD = 0.8
+
+      class << self
+        # Group file paths into patterns
+        # @param files [Array<String>] array of file paths
+        # @param limit [Integer] minimum files to trigger grouping (default: 15)
+        # @return [Array<String>] array of paths or patterns
+        def group(files, limit: 15)
+          return files.uniq.sort if files.size < limit
+
+          grouped = find_common_directories(files, limit)
+          grouped.sort
+        end
+
+        private
+
+        # Find directories where files can be grouped into patterns
+        # @param files [Array<String>] unique file paths to analyze
+        # @param limit [Integer] minimum file count threshold for grouping
+        # @return [Array<String>] array of file paths or directory patterns
+        def find_common_directories(files, limit)
+          # Deduplicate files first
+          unique_files = files.uniq
+          by_dir = unique_files.group_by { |f| File.dirname(f) }
+          result = []
+
+          by_dir.each do |dir, dir_files|
+            if should_group_directory?(dir, dir_files.uniq, limit)
+              result << "#{dir}/**/*"
+            else
+              result.concat(dir_files.uniq)
+            end
+          end
+
+          result.uniq
+        end
+
+        # Determine if a directory should be grouped
+        # @param dir [String] directory path to evaluate
+        # @param dir_files [Array<String>] files in this directory
+        # @param limit [Integer] minimum file count threshold
+        # @return [Boolean] true if directory should be grouped into pattern
+        def should_group_directory?(dir, dir_files, limit)
+          # Must have enough files and more than just one file
+          return false if dir_files.size < limit || dir_files.size == 1
+
+          # Check coverage: do we have most Ruby files in this directory?
+          begin
+            all_ruby_files = Dir.glob("#{dir}/**/*.rb")
+            # Don't group if directory doesn't exist or is empty
+            return false if all_ruby_files.empty?
+
+            coverage = dir_files.size.to_f / all_ruby_files.size
+            coverage >= DIRECTORY_COVERAGE_THRESHOLD
+          rescue StandardError
+            # If glob fails (directory doesn't exist), don't group
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/result_builder.rb

@@ -91,7 +91,15 @@ module Yard
         return nil if parsers.empty?
 
         # Parse output with all parsers (single or multiple)
-        parsed = parsers.flat_map { |parser| parser.new.call(stdout) }
+        # Check if parser accepts config keyword argument and pass it if supported
+        parsed = parsers.flat_map do |parser|
+          parser_instance = parser.new
+          if parser_accepts_config?(parser_instance)
+            parser_instance.call(stdout, config: config)
+          else
+            parser_instance.call(stdout)
+          end
+        end
         return nil if parsed.nil? || parsed.empty?
 
         validator_module::Result.new(parsed, config)
@@ -111,16 +119,22 @@ module Yard
         parsers = discover_parsers(validator_module)
         parsers.flat_map do |parser|
           parser_instance = parser.new
-          # Try passing config to parser if it accepts it (for filtering)
-          # Otherwise, call without config for backwards compatibility
-          begin
+          if parser_accepts_config?(parser_instance)
             parser_instance.call(stdout, config: config)
-          rescue ArgumentError
+          else
             parser_instance.call(stdout)
           end
         end
       end
 
+      # Check if a parser instance accepts a config keyword argument
+      # @param parser_instance [Object] parser instance to check
+      # @return [Boolean] true if parser accepts config keyword
+      def parser_accepts_config?(parser_instance)
+        params = parser_instance.method(:call).parameters
+        params.any? { |type, name| [:key, :keyreq].include?(type) && name == :config }
+      end
+
       # Auto-discover parser classes in a validator module
       # Finds all classes that inherit from Parsers::Base
       # @param validator_module [Module] validator module to search

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

@@ -8,9 +8,9 @@ module Yard
       #
       # @example Creating a validator result class
       #   class MyValidator::Result < Results::Base
-      #     self.default_severity = 'warning'
-      #     self.offense_type = 'method'
-      #     self.offense_name = 'MyOffense'
+      #     self.default_severity = "warning"
+      #     self.offense_type = "method"
+      #     self.offense_name = "MyOffense"
       #
       #     def build_message(offense)
       #       "Found issue in #{offense[:location]}"

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

@@ -52,6 +52,14 @@ Documentation/UndocumentedOptions:
   Enabled: true
   Severity: warning
 
+Documentation/MissingReturn:
+  Description: 'Requires @return tags on all methods (opt-in for strict documentation).'
+  Enabled: false  # Opt-in validator
+  Severity: warning
+  ExcludedMethods:
+    - 'initialize'    # Exclude all initialize methods
+    # - '/^_/'        # Uncomment to exclude private methods (by convention)
+
 Documentation/MarkdownSyntax:
   Description: 'Detects common markdown syntax errors in documentation.'
   Enabled: true
@@ -164,6 +172,15 @@ Tags/ExampleSyntax:
   Enabled: true
   Severity: warning
 
+Tags/ExampleStyle:
+  Description: 'Validates code style in @example tags using RuboCop/StandardRB.'
+  Enabled: false  # Opt-in validator (requires RuboCop or StandardRB)
+  Severity: convention
+  # Linter: auto  # Uncomment to explicitly configure: 'auto', 'rubocop', 'standard', 'none'
+  # SkipPatterns:  # Uncomment to skip examples matching patterns
+  #   - '/skip-lint/i'
+  #   - '/bad code/i'
+
 Tags/RedundantParamDescription:
   Description: 'Detects meaningless parameter descriptions that add no value.'
   Enabled: true
@@ -241,6 +258,20 @@ Tags/TagGroupSeparator:
     yield: [yield, yieldparam, yieldreturn]
   RequireAfterDescription: false
 
+Tags/ForbiddenTags:
+  Description: 'Detects forbidden tag and type combinations.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  ForbiddenPatterns: []
+  # Example patterns:
+  # - Tag: return
+  #   Types:
+  #     - void
+  # - Tag: param
+  #   Types:
+  #     - Object
+  # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
+
 # Warnings validators - catches YARD parser errors
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'

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

@@ -56,6 +56,14 @@ Documentation/UndocumentedOptions:
   Enabled: true
   Severity: error
 
+Documentation/MissingReturn:
+  Description: 'Requires @return tags on all methods (opt-in for strict documentation).'
+  Enabled: true  # Enabled in strict mode
+  Severity: error
+  ExcludedMethods:
+    - 'initialize'    # Exclude all initialize methods
+    # - '/^_/'        # Uncomment to exclude private methods (by convention)
+
 Documentation/MarkdownSyntax:
   Description: 'Detects common markdown syntax errors in documentation.'
   Enabled: true
@@ -168,6 +176,15 @@ Tags/ExampleSyntax:
   Enabled: true
   Severity: error
 
+Tags/ExampleStyle:
+  Description: 'Validates code style in @example tags using RuboCop/StandardRB.'
+  Enabled: false  # Opt-in validator (requires RuboCop or StandardRB)
+  Severity: convention
+  # Linter: auto  # Uncomment to explicitly configure: 'auto', 'rubocop', 'standard', 'none'
+  # SkipPatterns:  # Uncomment to skip examples matching patterns
+  #   - '/skip-lint/i'
+  #   - '/bad code/i'
+
 Tags/RedundantParamDescription:
   Description: 'Detects meaningless parameter descriptions that add no value.'
   Enabled: true
@@ -245,6 +262,20 @@ Tags/TagGroupSeparator:
     yield: [yield, yieldparam, yieldreturn]
   RequireAfterDescription: false
 
+Tags/ForbiddenTags:
+  Description: 'Detects forbidden tag and type combinations.'
+  Enabled: false  # Opt-in validator
+  Severity: error
+  ForbiddenPatterns: []
+  # Example patterns:
+  # - Tag: return
+  #   Types:
+  #     - void
+  # - Tag: param
+  #   Types:
+  #     - Object
+  # - Tag: api  # Forbids @api tag entirely (no Types = any occurrence)
+
 # Warnings validators - catches YARD parser errors
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'