yard-lint 1.2.2 → 1.3.0.rc1

data/lib/yard/lint/config_generator.rb

@@ -4,194 +4,23 @@ module Yard
   module Lint
     # Generates default .yard-lint.yml configuration file
     class ConfigGenerator
-      # Default configuration template
-      DEFAULT_CONFIG = <<~YAML
-        # YARD-Lint Configuration
-        # See https://github.com/mensfeld/yard-lint for documentation
-
-        # Global settings for all validators
-        AllValidators:
-          # YARD command-line options (applied to all validators by default)
-          YardOptions:
-            - --private
-            - --protected
-
-          # Global file exclusion patterns
-          Exclude:
-            - '\\.git'
-            - 'vendor/**/*'
-            - 'node_modules/**/*'
-            - 'spec/**/*'
-            - 'test/**/*'
-
-          # Exit code behavior (error, warning, convention, never)
-          FailOnSeverity: warning
-
-          # Minimum documentation coverage percentage (0-100)
-          # Fails if coverage is below this threshold
-          # MinCoverage: 80.0
-
-          # Diff mode settings
-          DiffMode:
-            # Default base ref for --diff (auto-detects main/master if not specified)
-            DefaultBaseRef: ~
-
-        # Documentation validators
-        Documentation/UndocumentedObjects:
-          Description: 'Checks for classes, modules, and methods without documentation.'
-          Enabled: true
-          Severity: warning
-          ExcludedMethods:
-            - 'initialize/0'  # Exclude parameter-less initialize
-            - '/^_/'          # Exclude private methods (by convention)
-
-        Documentation/UndocumentedMethodArguments:
-          Description: 'Checks for method parameters without @param tags.'
-          Enabled: true
-          Severity: warning
-
-        Documentation/UndocumentedBooleanMethods:
-          Description: 'Checks that question mark methods document their boolean return.'
-          Enabled: true
-          Severity: warning
-
-        Documentation/UndocumentedOptions:
-          Description: 'Detects methods with options hash parameters but no @option tags.'
-          Enabled: true
-          Severity: warning
-
-        Documentation/MarkdownSyntax:
-          Description: 'Detects common markdown syntax errors in documentation.'
-          Enabled: true
-          Severity: warning
-
-        # Tags validators
-        Tags/Order:
-          Description: 'Enforces consistent ordering of YARD tags.'
-          Enabled: true
-          Severity: convention
-          EnforcedOrder:
-            - param
-            - option
-            - return
-            - raise
-            - example
-
-        Tags/InvalidTypes:
-          Description: 'Validates type definitions in @param, @return, @option tags.'
-          Enabled: true
-          Severity: warning
-          ValidatedTags:
-            - param
-            - option
-            - return
-
-        Tags/TypeSyntax:
-          Description: 'Validates YARD type syntax using YARD parser.'
-          Enabled: true
-          Severity: warning
-          ValidatedTags:
-            - param
-            - option
-            - return
-            - yieldreturn
-
-        Tags/MeaninglessTag:
-          Description: 'Detects @param/@option tags on classes, modules, or constants.'
-          Enabled: true
-          Severity: warning
-          CheckedTags:
-            - param
-            - option
-          InvalidObjectTypes:
-            - class
-            - module
-            - constant
-
-        Tags/CollectionType:
-          Description: 'Validates Hash collection syntax consistency.'
-          Enabled: true
-          Severity: convention
-          EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
-          ValidatedTags:
-            - param
-            - option
-            - return
-            - yieldreturn
-
-        Tags/TagTypePosition:
-          Description: 'Validates type annotation position in tags.'
-          Enabled: true
-          Severity: convention
-          CheckedTags:
-            - param
-            - option
-          # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
-          #                or 'type_first' (@param [Type] name)
-          EnforcedStyle: type_after_name
-
-        Tags/ApiTags:
-          Description: 'Enforces @api tags on public objects.'
-          Enabled: false  # Opt-in validator
-          Severity: warning
-          AllowedApis:
-            - public
-            - private
-            - internal
-
-        Tags/OptionTags:
-          Description: 'Requires @option tags for methods with options parameters.'
-          Enabled: true
-          Severity: warning
-
-        # Warnings validators - catches YARD parser errors
-        Warnings/UnknownTag:
-          Description: 'Detects unknown YARD tags.'
-          Enabled: true
-          Severity: error
-
-        Warnings/UnknownDirective:
-          Description: 'Detects unknown YARD directives.'
-          Enabled: true
-          Severity: error
-
-        Warnings/InvalidTagFormat:
-          Description: 'Detects malformed tag syntax.'
-          Enabled: true
-          Severity: error
-
-        Warnings/InvalidDirectiveFormat:
-          Description: 'Detects malformed directive syntax.'
-          Enabled: true
-          Severity: error
-
-        Warnings/DuplicatedParameterName:
-          Description: 'Detects duplicate @param tags.'
-          Enabled: true
-          Severity: error
-
-        Warnings/UnknownParameterName:
-          Description: 'Detects @param tags for non-existent parameters.'
-          Enabled: true
-          Severity: error
-
-        # Semantic validators
-        Semantic/AbstractMethods:
-          Description: 'Ensures @abstract methods do not have real implementations.'
-          Enabled: true
-          Severity: warning
-      YAML
+      # Path to templates directory
+      TEMPLATES_DIR = File.expand_path('templates', __dir__)
 
       # Generate .yard-lint.yml file in current directory
       # @param force [Boolean] overwrite existing file if true
+      # @param strict [Boolean] generate strict configuration (all errors, 100% coverage)
       # @return [Boolean] true if file was created, false if already exists
-      def self.generate(force: false)
+      def self.generate(force: false, strict: false)
         config_path = File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
 
         if File.exist?(config_path) && !force
           false
         else
-          File.write(config_path, DEFAULT_CONFIG)
+          template_name = strict ? 'strict_config.yml' : 'default_config.yml'
+          template_path = File.join(TEMPLATES_DIR, template_name)
+          content = File.read(template_path)
+          File.write(config_path, content)
           true
         end
       end

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