yard-lint 1.2.3 → 1.3.0

data/lib/yard/lint/config_updater.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Updates existing .yard-lint.yml configuration files
+    # Adds new validators, removes obsolete ones, preserves user settings
+    class ConfigUpdater
+      # Path to templates directory
+      TEMPLATES_DIR = File.expand_path('templates', __dir__)
+
+      # Category order for output
+      CATEGORY_ORDER = %w[Documentation Tags Warnings Semantic].freeze
+
+      # Category comments for output
+      CATEGORY_COMMENTS = {
+        'Documentation' => '# Documentation validators',
+        'Tags' => '# Tags validators',
+        'Warnings' => '# Warnings validators - catches YARD parser errors',
+        'Semantic' => '# Semantic validators'
+      }.freeze
+
+      class << self
+        # Update an existing config file
+        # @param path [String] path to config file (default: .yard-lint.yml in current dir)
+        # @param strict [Boolean] use strict template as base for new validators
+        # @return [Hash] result hash with :added, :removed, :preserved arrays
+        def update(path: nil, strict: false)
+          new(path: path, strict: strict).update
+        end
+      end
+
+      # @param path [String, nil] path to config file
+      # @param strict [Boolean] use strict template
+      def initialize(path: nil, strict: false)
+        @path = path || File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
+        @strict = strict
+      end
+
+      # Perform the config update
+      # @return [Hash] result with :added, :removed, :preserved arrays
+      def update
+        validate_file_exists!
+
+        existing_config = load_existing_config
+        template_config = load_template_config
+
+        result = merge_configs(existing_config, template_config)
+
+        write_updated_config(result[:config])
+
+        {
+          added: result[:added],
+          removed: result[:removed],
+          preserved: result[:preserved]
+        }
+      end
+
+      private
+
+      # Validate that the config file exists
+      # @raise [Errors::ConfigFileNotFoundError] if file doesn't exist
+      def validate_file_exists!
+        return if File.exist?(@path)
+
+        raise Errors::ConfigFileNotFoundError,
+          "Config file not found: #{@path}. Use --init to create one."
+      end
+
+      # Load the existing user config
+      # @return [Hash] parsed YAML config
+      def load_existing_config
+        YAML.load_file(@path) || {}
+      end
+
+      # Load the template config
+      # @return [Hash] parsed template YAML
+      def load_template_config
+        template_name = @strict ? 'strict_config.yml' : 'default_config.yml'
+        template_path = File.join(TEMPLATES_DIR, template_name)
+        YAML.load_file(template_path)
+      end
+
+      # Merge existing config with template to add new and remove obsolete validators
+      # @param existing [Hash] existing user config
+      # @param template [Hash] template config
+      # @return [Hash] result with :config, :added, :removed, :preserved
+      def merge_configs(existing, template)
+        current_validators = ConfigLoader::ALL_VALIDATORS
+        existing_validators = extract_validator_keys(existing)
+
+        # Calculate changes
+        added = (current_validators - existing_validators).sort
+        removed = (existing_validators - current_validators).sort
+        preserved = (existing_validators & current_validators).sort
+
+        # Build merged config
+        merged = {}
+
+        # Copy AllValidators from existing, falling back to template
+        merged['AllValidators'] = existing['AllValidators'] || template['AllValidators']
+
+        # Process validators in template order (which has proper category grouping)
+        template.each_key do |key|
+          next if key == 'AllValidators'
+          next unless key.include?('/')
+          next unless current_validators.include?(key)
+
+          merged[key] = if existing.key?(key)
+                          # Preserve existing user config, but merge with template defaults
+                          merge_validator_config(template[key], existing[key])
+                        else
+                          # New validator - use template defaults
+                          template[key].dup
+                        end
+        end
+
+        {
+          config: merged,
+          added: added,
+          removed: removed,
+          preserved: preserved
+        }
+      end
+
+      # Extract validator keys (keys containing '/') from config
+      # @param config [Hash] configuration hash
+      # @return [Array<String>] validator keys
+      def extract_validator_keys(config)
+        config.keys.select { |k| k.include?('/') }
+      end
+
+      # Merge template defaults with user config
+      # User config takes precedence
+      # @param template_config [Hash] template validator config
+      # @param user_config [Hash] user validator config
+      # @return [Hash] merged config
+      def merge_validator_config(template_config, user_config)
+        result = template_config.dup
+        user_config.each do |key, value|
+          result[key] = value
+        end
+        result
+      end
+
+      # Write the updated config to file
+      # @param config [Hash] merged config to write
+      def write_updated_config(config)
+        content = generate_yaml_content(config)
+        File.write(@path, content)
+      end
+
+      # Generate YAML content with proper formatting and section comments
+      # @param config [Hash] merged configuration with AllValidators and validator sections
+      # @return [String] formatted YAML content
+      def generate_yaml_content(config)
+        lines = []
+        lines << '# YARD-Lint Configuration'
+        lines << '# See https://github.com/mensfeld/yard-lint for documentation'
+        lines << ''
+
+        # Write AllValidators section
+        if config['AllValidators']
+          lines << '# Global settings for all validators'
+          lines << 'AllValidators:'
+          lines.concat(yaml_hash_lines(config['AllValidators'], indent: 2))
+          lines << ''
+        end
+
+        # Group validators by category
+        categories = group_by_category(config)
+
+        # Write each category in order
+        CATEGORY_ORDER.each do |category|
+          validators = categories[category]
+          next unless validators&.any?
+
+          lines << CATEGORY_COMMENTS[category] if CATEGORY_COMMENTS[category]
+
+          validators.each do |validator_name, validator_config|
+            lines << "#{validator_name}:"
+            lines.concat(yaml_hash_lines(validator_config, indent: 2))
+            lines << ''
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Group validators by their category
+      # @param config [Hash] config with validator keys
+      # @return [Hash{String => Hash}] validators grouped by category
+      def group_by_category(config)
+        categories = Hash.new { |h, k| h[k] = {} }
+
+        config.each do |key, value|
+          next unless key.include?('/')
+
+          category = key.split('/').first
+          categories[category][key] = value
+        end
+
+        categories
+      end
+
+      # Convert a hash to indented YAML lines
+      # @param hash [Hash] validator or AllValidators configuration to format as YAML
+      # @param indent [Integer] number of spaces to indent
+      # @return [Array<String>] indented YAML lines
+      def yaml_hash_lines(hash, indent:)
+        yaml_str = hash.to_yaml
+        # Remove the "---\n" header and convert to indented lines
+        yaml_str.lines[1..].map do |line|
+          if line.strip.empty?
+            ''
+          else
+            "#{' ' * indent}#{line.rstrip}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/errors.rb

@@ -12,6 +12,12 @@ module Yard
 
       # Raised when a circular dependency is detected in configuration inheritance
       class CircularDependencyError < BaseError; end
+
+      # Raised when an unknown validator name is specified via --only
+      class UnknownValidatorError < BaseError; end
+
+      # Raised when a specified file or directory does not exist
+      class FileNotFoundError < BaseError; end
     end
   end
 end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # In-process execution components for YARD validation.
+    # Provides registry management, query execution, and result collection
+    # for running validators within the same Ruby process.
+    module Executor
+      # Manages shared YARD::Registry for in-process execution.
+      # Ensures files are parsed once and shared across all validators.
+      class InProcessRegistry
+        # @return [Array<String>] warnings captured during parsing
+        attr_reader :warnings
+
+        def initialize
+          @parsed = false
+          @warnings = []
+          @mutex = Mutex.new
+        end
+
+        # Parse Ruby source files and populate the YARD registry.
+        # Captures any warnings emitted by YARD during parsing for later dispatch.
+        # @param files [Array<String>] absolute or relative paths to Ruby source files
+        # @return [void]
+        def parse(files)
+          @mutex.synchronize do
+            return if @parsed
+
+            YARD::Registry.clear
+
+            # Suppress YARD's default output by setting log level high
+            # YARD uses its own logging levels, 4 is ERROR/FATAL level
+            original_level = YARD::Logger.instance.level
+            YARD::Logger.instance.level = 4 # Only show fatal errors
+
+            @warnings = capture_warnings { YARD.parse(files) }
+            @parsed = true
+
+            YARD::Logger.instance.level = original_level
+          end
+        end
+
+        # Check if registry has been parsed
+        # @return [Boolean]
+        def parsed?
+          @parsed
+        end
+
+        # Get all objects from the registry
+        # @return [Array<YARD::CodeObjects::Base>]
+        def all_objects
+          YARD::Registry.all
+        end
+
+        # Get objects filtered for a specific validator
+        # @param visibility [Symbol] visibility filter, either :all or :public
+        # @param file_excludes [Array<String>] glob patterns for files to exclude
+        # @param file_selection [Array<String>, nil] specific files to include (nil = all files)
+        # @return [Array<YARD::CodeObjects::Base>]
+        def objects_for_validator(visibility:, file_excludes: [], file_selection: nil)
+          objects = all_objects
+
+          # Filter by visibility
+          unless visibility == :all
+            objects = objects.select do |obj|
+              !obj.respond_to?(:visibility) || obj.visibility == :public
+            end
+          end
+
+          # Filter by file selection (if provided)
+          if file_selection && !file_selection.empty?
+            expanded_selection = file_selection.to_set { |f| File.expand_path(f) }
+            objects = objects.select do |obj|
+              obj.file && expanded_selection.include?(File.expand_path(obj.file))
+            end
+          end
+
+          # Filter by file excludes
+          unless file_excludes.empty?
+            objects = objects.reject do |obj|
+              next false unless obj.file
+
+              file_excludes.any? do |pattern|
+                File.fnmatch(pattern, obj.file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+              end
+            end
+          end
+
+          objects
+        end
+
+        # Clear the registry and reset state
+        # @return [void]
+        def clear!
+          @mutex.synchronize do
+            YARD::Registry.clear
+            @parsed = false
+            @warnings = []
+          end
+        end
+
+        private
+
+        # Capture warnings during a block execution
+        # @yield Block to execute while capturing warnings
+        # @return [Array<String>] captured warnings
+        def capture_warnings
+          captured = []
+
+          # Store original warn method
+          original_warn = YARD::Logger.instance.method(:warn)
+
+          # Override warn to capture warnings
+          YARD::Logger.instance.define_singleton_method(:warn) do |*args|
+            message = args.first.to_s
+            captured << message
+            original_warn.call(*args)
+          end
+
+          yield
+
+          captured
+        ensure
+          # Restore original warn method
+          YARD::Logger.instance.define_singleton_method(:warn, original_warn) if original_warn
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Executor
+      # Executes validator queries against the shared registry.
+      # Handles visibility filtering and file exclusions per validator.
+      class QueryExecutor
+        # @param registry [InProcessRegistry] the shared registry instance
+        def initialize(registry)
+          @registry = registry
+        end
+
+        # Execute a validator's query against the registry
+        # @param validator [Validators::Base] validator instance with in_process_query method
+        # @param file_selection [Array<String>] files to include in the query
+        # @return [Hash] result hash with :stdout, :stderr, :exit_code keys
+        def execute(validator, file_selection: nil)
+          validator_name = validator.class.validator_name
+
+          # Determine visibility: if config has --private/--protected, use :all
+          visibility = determine_visibility(validator)
+
+          # Get file excludes from config
+          excludes = if validator_name && validator.config
+                       validator.config.validator_exclude(validator_name)
+                     else
+                       []
+                     end
+
+          objects = @registry.objects_for_validator(
+            visibility: visibility,
+            file_excludes: excludes,
+            file_selection: file_selection
+          )
+
+          collector = ResultCollector.new
+
+          objects.each do |object|
+            # Skip objects without file/line info
+            next unless object.file && object.line
+
+            execute_query_for_object(validator, object, collector)
+          end
+
+          build_result(collector)
+        end
+
+        private
+
+        # Execute query for a single object, handling errors gracefully
+        # @param validator [Validators::Base] validator instance
+        # @param object [YARD::CodeObjects::Base] code object to query
+        # @param collector [ResultCollector] output collector
+        # @return [void]
+        def execute_query_for_object(validator, object, collector)
+          validator.in_process_query(object, collector)
+        rescue NotImplementedError, NoMethodError
+          # These indicate bugs in validator implementation - re-raise them
+          raise
+        rescue StandardError => e
+          # Skip objects that cause data-related errors (mirrors YARD CLI behavior).
+          # Some code objects may have malformed data that causes errors during validation.
+          # We log these in debug mode but don't fail the entire validator run.
+          return unless ENV['DEBUG']
+
+          warn "[YARD::Lint] Validator #{validator.class} error on #{object.path}: #{e.class}: #{e.message}"
+        end
+
+        # Build the result hash matching shell command output format
+        # @param collector [ResultCollector] output collector
+        # @return [Hash] result hash with :stdout, :stderr, :exit_code keys
+        def build_result(collector)
+          {
+            stdout: collector.to_stdout,
+            stderr: '',
+            exit_code: 0
+          }
+        end
+
+        # Determine visibility setting based on validator and config
+        # If config has --private or --protected in YardOptions, use :all
+        # If config explicitly sets empty YardOptions, use :public (override validator default)
+        # Otherwise use the validator's declared visibility
+        # @param validator [Validators::Base] validator instance
+        # @return [Symbol] visibility setting (:public or :all)
+        def determine_visibility(validator)
+          return validator.class.in_process_visibility || :public unless validator.config
+
+          validator_name = validator.class.validator_name
+          yard_options = validator.config.validator_yard_options(validator_name)
+
+          # If YardOptions contains --private or --protected, use :all visibility
+          if yard_options.any? { |opt| opt.include?('--private') || opt.include?('--protected') }
+            return :all
+          end
+
+          # Check if validator has explicit YardOptions set in config
+          # If explicitly set (even to empty), respect that choice and use :public
+          validator_cfg = validator.config.validators[validator_name] || {}
+          return :public if validator_cfg.key?('YardOptions')
+
+          # No explicit YardOptions - fall back to validator's declared visibility
+          validator.class.in_process_visibility || :public
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Executor
+      # Collects query output in a format matching shell stdout.
+      # Used by validators to write their results during in-process execution.
+      class ResultCollector
+        def initialize
+          @lines = []
+          @mutex = Mutex.new
+        end
+
+        # Add a single line to the output
+        # @param line [String, Object] content to add (will be converted to string)
+        # @return [void]
+        def puts(line)
+          @mutex.synchronize { @lines << line.to_s }
+        end
+
+        # Add multiple lines by splitting content on newlines.
+        # Each line is added separately to the output buffer.
+        # @param content [String] multiline string to split and add
+        # @return [void]
+        def print(content)
+          content.to_s.each_line { |line| puts(line.chomp) }
+        end
+
+        # Get the collected output as a single string
+        # @return [String] all lines joined with newlines
+        def to_stdout
+          @lines.join("\n")
+        end
+
+        # Check if any output has been collected
+        # @return [Boolean]
+        def empty?
+          @lines.empty?
+        end
+
+        # Get the number of lines collected
+        # @return [Integer]
+        def size
+          @lines.size
+        end
+
+        # Clear all collected output
+        # @return [void]
+        def clear!
+          @mutex.synchronize { @lines.clear }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Executor
+      # Routes captured YARD warnings to appropriate warning validators.
+      # Uses the same regex patterns as the existing parsers to ensure consistency.
+      class WarningDispatcher
+        # Patterns matching the 'general' regexps from each warning validator's parser.
+        # These patterns identify which validator should handle each warning.
+        PATTERNS = {
+          'Warnings/UnknownTag' => /^\[warn\]: Unknown tag.*@.*near line/,
+          'Warnings/UnknownParameterName' => /^\[warn\]: @param tag has unknown parameter name/,
+          'Warnings/DuplicatedParameterName' => /^\[warn\]: @param tag has duplicate parameter name/,
+          'Warnings/UnknownDirective' => /^\[warn\]: Unknown directive.*@!.*near line/,
+          'Warnings/InvalidTagFormat' => /^\[warn\]: Invalid tag format/,
+          'Warnings/InvalidDirectiveFormat' => /^\[warn\]: Invalid directive format/
+        }.freeze
+
+        # Dispatch warnings to appropriate validators
+        # @param warnings [Array<String>] raw warning messages from YARD
+        # @return [Hash{String => Array<String>}] warnings grouped by validator name
+        def dispatch(warnings)
+          grouped = Hash.new { |h, k| h[k] = [] }
+
+          warnings.each do |warning|
+            # Format the warning as YARD outputs it
+            formatted = format_warning(warning)
+
+            PATTERNS.each do |validator_name, pattern|
+              if formatted.match?(pattern)
+                grouped[validator_name] << formatted
+                break
+              end
+            end
+          end
+
+          grouped
+        end
+
+        # Format a raw warning to match YARD's stderr output format
+        # @param warning [String] raw warning message
+        # @return [String] formatted warning
+        def format_warning(warning)
+          # If the warning already has [warn]: prefix, return as-is
+          return warning if warning.start_with?('[warn]:')
+
+          "[warn]: #{warning}"
+        end
+
+        # Build result hash for a validator from its dispatched warnings
+        # The warnings are put in stdout because the ResultBuilder reads from stdout
+        # (in shell mode, YARD outputs warnings to stderr but they get combined)
+        # @param warnings [Array<String>] warnings for this validator
+        # @return [Hash] result hash with :stdout, :stderr, :exit_code keys
+        def format_for_validator(warnings)
+          {
+            stdout: warnings.join("\n"),
+            stderr: '',
+            exit_code: 0
+          }
+        end
+
+        # Check if a validator is a warning validator (handled by dispatcher)
+        # @param validator_name [String] full validator name
+        # @return [Boolean]
+        def warning_validator?(validator_name)
+          PATTERNS.key?(validator_name)
+        end
+
+        # Get all warning validator names
+        # @return [Array<String>]
+        def warning_validator_names
+          PATTERNS.keys
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/ext/irb_notifier_shim.rb

@@ -1,16 +1,29 @@
 # frozen_string_literal: true
 
-# Shim for IRB::Notifier to avoid IRB dependency in Ruby 3.5+
+# Shim for IRB::Notifier to avoid IRB dependency in Ruby 3.5+/4.0+
 #
-# YARD's legacy parser vendors old IRB code that depends on IRB::Notifier.
+# WHY THIS SHIM IS NEEDED:
 # In Ruby 3.5+, IRB is no longer part of the default gems and must be explicitly installed.
-# This shim provides just enough functionality to keep YARD's legacy parser working
-# without requiring the full IRB gem as a dependency.
+# YARD's codebase has a dependency chain that triggers `require "irb/notifier"` even when
+# using the modern Ripper-based parser:
 #
-# The notifier is only used for debug output in YARD's legacy parser, which we don't need.
+#   @!attribute directive parsing
+#     → YARD::Tags::OverloadTag#parse_signature
+#       → YARD::Parser::Ruby::Legacy::TokenList
+#         → ruby_lex.rb
+#           → irb/slex.rb
+#             → require "irb/notifier"  ← FAILS without IRB gem or this shim
+#
+# This happens because YARD uses its legacy TokenList for parsing attribute signatures,
+# regardless of which main parser is selected. Until YARD removes this dependency,
+# this shim is required for Ruby 3.5+/4.0+ compatibility.
+#
+# WHAT THIS SHIM DOES:
+# Provides a minimal no-op implementation of IRB::Notifier that satisfies YARD's
+# requirements. The notifier is only used for debug output which we don't need.
 #
 # IMPORTANT: This shim only loads if IRB::Notifier is not already defined.
-# If IRB gem is present, we use the real implementation instead.
+# If the IRB gem is present, we use the real implementation instead.
 
 # Only load the shim if IRB::Notifier is not already defined
 unless defined?(IRB::Notifier)

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

@@ -55,7 +55,8 @@ module Yard
         # Set default values for base class
         self.offense_type = 'line'
 
-        attr_reader :offenses, :config
+        attr_accessor :offenses
+        attr_reader :config
 
         # Initialize a result object with parsed validator data
         # @param parsed_data [Array<Hash>] Array of offense hashes from validator parser