yard-lint 1.2.3 → 1.3.0.rc1

data/lib/yard/lint/runner.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Require executor components for in-process execution
+require_relative 'executor/in_process_registry'
+require_relative 'executor/result_collector'
+require_relative 'executor/query_executor'
+require_relative 'executor/warning_dispatcher'
+
 module Yard
   module Lint
     # Main runner class that orchestrates the YARD validation process
@@ -26,8 +32,8 @@ module Yard
 
       private
 
-      # Run all validators
-      # Automatically runs all validators from ConfigLoader::ALL_VALIDATORS if enabled
+      # Run all validators using in-process YARD execution.
+      # Parses files once and shares the registry across all validators.
       # @return [Hash] hash with raw results from all validators
       def run_validators
         results = {}
@@ -37,50 +43,55 @@ module Yard
 
         @progress_formatter&.start(enabled_validators.size)
 
-        # Iterate through all registered validators
+        # Initialize in-process infrastructure
+        registry = Executor::InProcessRegistry.new
+        registry.parse(selection)
+
+        query_executor = Executor::QueryExecutor.new(registry)
+        warning_dispatcher = Executor::WarningDispatcher.new
+        dispatched_warnings = warning_dispatcher.dispatch(registry.warnings)
+
+        # Process each enabled validator
         enabled_validators.each_with_index do |validator_name, index|
-          # Get the validator namespace and config
           validator_namespace = ConfigLoader.validator_module(validator_name)
           validator_cfg = ConfigLoader.validator_config(validator_name)
 
-          # Show progress before running validator
           @progress_formatter&.update(index + 1, validator_name)
 
-          # Run the validator if it has a module
-          # (validators with modules have Validator classes)
-          if validator_namespace
-            run_and_store_validator(validator_namespace, validator_cfg, results, validator_name)
-          end
+          next unless validator_namespace
+
+          validator_class = validator_namespace::Validator
+          validator_selection = filter_files_for_validator(validator_name, selection)
+
+          result = if warning_dispatcher.warning_validator?(validator_name)
+                     # Use dispatched warnings for warning validators
+                     warning_dispatcher.format_for_validator(
+                       dispatched_warnings[validator_name] || []
+                     )
+                   else
+                     # Use in-process execution
+                     validator = validator_class.new(config, validator_selection)
+                     in_process_result = query_executor.execute(validator, file_selection: validator_selection)
+
+                     # Tags/Order requires special result wrapping for its parser
+                     if validator_name == 'Tags/Order'
+                       tags_order = config.validator_config('Tags/Order', 'EnforcedOrder')
+                       in_process_result[:stdout] = {
+                         result: in_process_result[:stdout],
+                         tags_order: tags_order
+                       }
+                     end
+
+                     in_process_result
+                   end
+
+          results[validator_cfg.id] = result
         end
 
         @progress_formatter&.finish
-
         results
       end
 
-      # Run a validator and store its result using the module's ID
-      # @param validator_namespace [Module] validator namespace module (e.g., Validators::Tags::Order)
-      # @param validator_config [Class] validator config class
-      # @param results [Hash] hash to store results in
-      # @param validator_name [String] full validator name for per-validator exclusions
-      def run_and_store_validator(
-        validator_namespace, validator_config, results, validator_name
-      )
-        results[validator_config.id] = run_validator(
-          validator_namespace::Validator,
-          validator_name
-        )
-      end
-
-      # Run a single validator with per-validator file filtering
-      # @param validator_class [Class] validator class to instantiate and run
-      # @param validator_name [String] full validator name for exclusions
-      # @return [Hash] hash with stdout, stderr and exit_code keys
-      def run_validator(validator_class, validator_name)
-        validator_selection = filter_files_for_validator(validator_name, selection)
-        validator_class.new(config, validator_selection).call
-      end
-
       # Filter files for a specific validator based on per-validator exclusions
       # @param validator_name [String] full validator name
       # @param files [Array<String>] array of file paths
@@ -106,7 +117,6 @@ module Yard
         return result if validator_excludes.empty?
 
         working_dir = Dir.pwd
-        filtered_keys = %i[severity type name message location_line]
 
         filtered_offenses = result.offenses.reject do |offense|
           file_path = offense[:location] || offense[:file]
@@ -128,9 +138,11 @@ module Yard
         # Return nil if no offenses remain after filtering
         return nil if filtered_offenses.empty?
 
-        # Create a new result object with filtered offenses
-        # We need to preserve the result class and config
-        result.class.new(filtered_offenses.map { |o| o.except(*filtered_keys) }, result.config)
+        # Instead of creating a new Result object (which would rebuild messages),
+        # just modify the existing result object's offenses array
+        # This preserves all the processed offense data including enhanced messages
+        result.offenses = filtered_offenses
+        result
       end
 
       # Parse raw results from validators and create Result objects

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

@@ -57,6 +57,23 @@ Documentation/MarkdownSyntax:
   Enabled: true
   Severity: warning
 
+Documentation/EmptyCommentLine:
+  Description: 'Detects empty comment lines at the start or end of documentation blocks.'
+  Enabled: true
+  Severity: convention
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: 'Detects blank lines between YARD documentation and method definition.'
+  Enabled: true
+  Severity: convention
+  OrphanedSeverity: convention
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
 # Tags validators
 Tags/Order:
   Description: 'Enforces consistent ordering of YARD tags.'
@@ -65,9 +82,15 @@ Tags/Order:
   EnforcedOrder:
     - param
     - option
+    - yield
+    - yieldparam
+    - yieldreturn
     - return
     - raise
+    - see
     - example
+    - note
+    - todo
 
 Tags/InvalidTypes:
   Description: 'Validates type definitions in @param, @return, @option tags.'
@@ -136,6 +159,88 @@ Tags/OptionTags:
   Enabled: true
   Severity: warning
 
+Tags/ExampleSyntax:
+  Description: 'Validates Ruby syntax in @example tags.'
+  Enabled: true
+  Severity: warning
+
+Tags/RedundantParamDescription:
+  Description: 'Detects meaningless parameter descriptions that add no value.'
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+    - param
+    - option
+  Articles:
+    - The
+    - the
+    - A
+    - a
+    - An
+    - an
+  MaxRedundantWords: 6
+  GenericTerms:
+    - object
+    - instance
+    - value
+    - data
+    - item
+    - element
+  EnabledPatterns:
+    ArticleParam: true
+    PossessiveParam: true
+    TypeRestatement: true
+    ParamToVerb: true
+    IdPattern: true
+    DirectionalDate: true
+    TypeGeneric: true
+
+Tags/InformalNotation:
+  Description: 'Detects informal tag notation patterns like "Note:" instead of @note.'
+  Enabled: true
+  Severity: warning
+  CaseSensitive: false
+  RequireStartOfLine: true
+  Patterns:
+    Note: '@note'
+    Todo: '@todo'
+    TODO: '@todo'
+    FIXME: '@todo'
+    See: '@see'
+    See also: '@see'
+    Warning: '@deprecated'
+    Deprecated: '@deprecated'
+    Author: '@author'
+    Version: '@version'
+    Since: '@since'
+    Returns: '@return'
+    Raises: '@raise'
+    Example: '@example'
+
+Tags/NonAsciiType:
+  Description: 'Detects non-ASCII characters in type annotations.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+
+Tags/TagGroupSeparator:
+  Description: 'Enforces blank line separators between different YARD tag groups.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  TagGroups:
+    param: [param, option]
+    return: [return]
+    error: [raise, throws]
+    example: [example]
+    meta: [see, note, todo, deprecated, since, version, api]
+    yield: [yield, yieldparam, yieldreturn]
+  RequireAfterDescription: false
+
 # Warnings validators - catches YARD parser errors
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'

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

@@ -61,6 +61,23 @@ Documentation/MarkdownSyntax:
   Enabled: true
   Severity: error
 
+Documentation/EmptyCommentLine:
+  Description: 'Detects empty comment lines at the start or end of documentation blocks.'
+  Enabled: true
+  Severity: error
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: 'Detects blank lines between YARD documentation and method definition.'
+  Enabled: true
+  Severity: error
+  OrphanedSeverity: error
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
 # Tags validators
 Tags/Order:
   Description: 'Enforces consistent ordering of YARD tags.'
@@ -69,9 +86,15 @@ Tags/Order:
   EnforcedOrder:
     - param
     - option
+    - yield
+    - yieldparam
+    - yieldreturn
     - return
     - raise
+    - see
     - example
+    - note
+    - todo
 
 Tags/InvalidTypes:
   Description: 'Validates type definitions in @param, @return, @option tags.'
@@ -140,6 +163,88 @@ Tags/OptionTags:
   Enabled: true
   Severity: error
 
+Tags/ExampleSyntax:
+  Description: 'Validates Ruby syntax in @example tags.'
+  Enabled: true
+  Severity: error
+
+Tags/RedundantParamDescription:
+  Description: 'Detects meaningless parameter descriptions that add no value.'
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  Articles:
+    - The
+    - the
+    - A
+    - a
+    - An
+    - an
+  MaxRedundantWords: 6
+  GenericTerms:
+    - object
+    - instance
+    - value
+    - data
+    - item
+    - element
+  EnabledPatterns:
+    ArticleParam: true
+    PossessiveParam: true
+    TypeRestatement: true
+    ParamToVerb: true
+    IdPattern: true
+    DirectionalDate: true
+    TypeGeneric: true
+
+Tags/InformalNotation:
+  Description: 'Detects informal tag notation patterns like "Note:" instead of @note.'
+  Enabled: true
+  Severity: error
+  CaseSensitive: false
+  RequireStartOfLine: true
+  Patterns:
+    Note: '@note'
+    Todo: '@todo'
+    TODO: '@todo'
+    FIXME: '@todo'
+    See: '@see'
+    See also: '@see'
+    Warning: '@deprecated'
+    Deprecated: '@deprecated'
+    Author: '@author'
+    Version: '@version'
+    Since: '@since'
+    Returns: '@return'
+    Raises: '@raise'
+    Example: '@example'
+
+Tags/NonAsciiType:
+  Description: 'Detects non-ASCII characters in type annotations.'
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+
+Tags/TagGroupSeparator:
+  Description: 'Enforces blank line separators between different YARD tag groups.'
+  Enabled: false  # Opt-in validator
+  Severity: error
+  TagGroups:
+    param: [param, option]
+    return: [return]
+    error: [raise, throws]
+    example: [example]
+    meta: [see, note, todo, deprecated, since, version, api]
+    yield: [yield, yieldparam, yieldreturn]
+  RequireAfterDescription: false
+
 # Warnings validators - catches YARD parser errors
 Warnings/UnknownTag:
   Description: 'Detects unknown YARD tags.'

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

@@ -6,47 +6,52 @@ module Yard
     module Validators
       # Base YARD validator class
       class Base
-        # Class-level cache shared across ALL validator classes
-        # Must be stored on Base itself, not on subclasses
-        @shared_command_cache = nil
-
-        # Default YARD command options that we need to use
-        DEFAULT_OPTIONS = [
-          '--charset utf-8',
-          '--markup markdown',
-          '--no-progress'
-        ].freeze
-
-        # Base temp directory for YARD databases
-        # Each unique set of arguments gets its own subdirectory to prevent contamination
-        YARDOC_BASE_TEMP_DIR = Dir.mktmpdir.freeze
-
-        private_constant :YARDOC_BASE_TEMP_DIR
+        # Class-level settings for in-process execution
+        # These must be set on each subclass, not on Base
+        @in_process_enabled = nil
+        @in_process_visibility = nil
 
         attr_reader :config, :selection
 
         class << self
-          # Lazy-initialized command cache shared across all validator instances
-          # This allows different validators to reuse results from identical YARD commands
-          # @return [CommandCache] the command cache instance
-          def command_cache
-            # Use Base's cache, not subclass's cache
-            Base.instance_variable_get(:@shared_command_cache) ||
-              Base.instance_variable_set(:@shared_command_cache, CommandCache.new)
+          # Declare that this validator supports in-process execution
+          # @param visibility [Symbol] visibility filter for objects (:public or :all)
+          #   :public - only include public methods (default, no --private/--protected)
+          #   :all - include all methods (equivalent to --private --protected)
+          # @return [void]
+          # @example
+          #   class Validator < Base
+          #     in_process visibility: :all
+          #   end
+          def in_process(visibility: :public)
+            @in_process_enabled = true
+            @in_process_visibility = visibility
           end
 
-          # Reset the command cache (primarily for testing)
-          # @return [void]
-          def reset_command_cache!
-            Base.instance_variable_set(:@shared_command_cache, nil)
+          # Check if this validator supports in-process execution
+          # @return [Boolean]
+          def in_process?
+            @in_process_enabled == true
           end
 
-          # Clear all YARD databases (primarily for testing)
-          # @return [void]
-          def clear_yard_database!
-            return unless defined?(YARDOC_BASE_TEMP_DIR)
+          # Get the visibility setting for in-process execution
+          # @return [Symbol, nil] :public, :all, or nil if not set
+          def in_process_visibility
+            @in_process_visibility
+          end
 
-            FileUtils.rm_rf(Dir.glob(File.join(YARDOC_BASE_TEMP_DIR, '*')))
+          # Get the validator name from the class namespace
+          # @return [String, nil] validator name like 'Tags/Order' or nil
+          # @example
+          #   Yard::Lint::Validators::Tags::Order::Validator.validator_name
+          #   # => 'Tags/Order'
+          def validator_name
+            name&.split('::')&.then do |parts|
+              idx = parts.index('Validators')
+              return nil unless idx && parts[idx + 1] && parts[idx + 2]
+
+              "#{parts[idx + 1]}/#{parts[idx + 2]}"
+            end
           end
         end
 
@@ -57,105 +62,34 @@ module Yard
           @selection = selection
         end
 
-        # Performs the validation and returns raw results
-        # @return [Hash] hash with stdout, stderr and exit_code keys
-        def call
-          # There might be a case when there were no files because someone ignored all
-          # then we need to return empty result
-          return raw if selection.nil? || selection.empty?
-
-          # Anything that goes to shell needs to be escaped
-          escaped_file_names = escape(selection)
-
-          # Use a unique YARD database per set of arguments to prevent contamination
-          # between validators with different file selections or options
-          yardoc_dir = yardoc_temp_dir_for_arguments(escaped_file_names.join(' '))
-
-          # For large file lists, use a temporary file to avoid ARG_MAX limits
-          # Write file paths to temp file, one per line
-          Tempfile.create(['yard_files', '.txt']) do |f|
-            escaped_file_names.each { |file| f.puts(file) }
-            f.flush
-
-            yard_cmd(yardoc_dir, f.path)
-          end
+        # Execute query for a single object during in-process execution.
+        # Override this method in validators that support in-process execution.
+        # @param object [YARD::CodeObjects::Base] the code object to query
+        # @param collector [Executor::ResultCollector] collector for output
+        # @return [void]
+        # @example
+        #   def in_process_query(object, collector)
+        #     return unless object.docstring.all.empty?
+        #     collector.puts "#{object.file}:#{object.line}: #{object.title}"
+        #   end
+        def in_process_query(object, collector)
+          raise NotImplementedError, "#{self.class} must implement in_process_query for in-process execution"
         end
 
         private
 
-        # Returns a unique YARD database directory for the given arguments
-        # Uses SHA256 hash of the normalized arguments to ensure different file sets
-        # get separate databases, preventing contamination
-        # @param escaped_file_names [String] escaped file names to process
-        # @return [String] path to the YARD database directory
-        def yardoc_temp_dir_for_arguments(escaped_file_names)
-          # Combine all arguments that affect YARD output
-          all_args = "#{shell_arguments} #{escaped_file_names}"
-
-          # Create a hash of the arguments for a unique directory name
-          args_hash = Digest::SHA256.hexdigest(all_args)
-
-          # Create subdirectory under base temp dir
-          dir = File.join(YARDOC_BASE_TEMP_DIR, args_hash)
-          FileUtils.mkdir_p(dir) unless File.directory?(dir)
-
-          dir
-        end
-
-        # @return [String] all arguments with which YARD command should be executed
-        def shell_arguments
-          validator_name = self.class.name&.split('::')&.then do |parts|
-            idx = parts.index('Validators')
-            next config.options unless idx && parts[idx + 1] && parts[idx + 2]
-
-            "#{parts[idx + 1]}/#{parts[idx + 2]}"
-          end || config.options
-
-          yard_options = config.validator_yard_options(validator_name)
-          args = escape(yard_options).join(' ')
-          "#{args} #{DEFAULT_OPTIONS.join(' ')}"
-        end
-
-        # @param array [Array] escape all elements in an array
-        # @return [Array] array with escaped elements
-        def escape(array)
-          array.map { |cmd| Shellwords.escape(cmd) }
-        end
-
-        # Builds a raw hash that can be used for further processing
-        # @param stdout [String, Hash, Array] anything that we want to return as stdout
-        # @param stderr [String, Hash, Array] any errors that occurred
-        # @param exit_code [Integer, false] result exit code or false if we want to decide it based
-        #   on the stderr content
-        # @return [Hash] hash with stdout, stderr and exit_code keys
-        def raw(stdout = '', stderr = '', exit_code = false)
-          {
-            stdout: stdout,
-            stderr: stderr,
-            exit_code: exit_code || (stderr.empty? ? 0 : 1)
-          }
-        end
-
-        # Executes a shell command and returns the result
-        # Routes through command cache to avoid duplicate executions
-        # @param cmd [String] shell command to execute
-        # @return [Hash] hash with stdout, stderr and exit_code keys
-        def shell(cmd)
-          self.class.command_cache.execute(cmd)
-        end
-
         # Retrieves configuration value with fallback to default
         # Automatically determines the validator name from the class namespace
         #
         # @param key [String] the configuration key to retrieve
         # @return [Object] the configured value or default value from the validator's Config.defaults
-        # @note The validator name is automatically extracted from the class namespace.
-        #   For example, Yard::Lint::Validators::Tags::RedundantParamDescription::Validator
-        #   becomes 'Tags/RedundantParamDescription'
         # @example Usage in a validator (e.g., Tags::RedundantParamDescription)
         #   def config_articles
         #     config_or_default('Articles')
         #   end
+        # @note The validator name is automatically extracted from the class namespace.
+        #   For example, Yard::Lint::Validators::Tags::RedundantParamDescription::Validator
+        #   becomes 'Tags/RedundantParamDescription'
         def config_or_default(key)
           validator_name = self.class.name&.split('::')&.then do |parts|
             idx = parts.index('Validators')

data/lib/yard/lint/validators/documentation/blank_line_before_definition/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module BlankLineBeforeDefinition
+          # Configuration for BlankLineBeforeDefinition validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :blank_line_before_definition
+            self.defaults = {
+              'Enabled' => true,
+              'Severity' => 'convention',
+              'OrphanedSeverity' => 'convention',
+              'EnabledPatterns' => {
+                'SingleBlankLine' => true,
+                'OrphanedDocs' => true
+              }
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/documentation/blank_line_before_definition/messages_builder.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module BlankLineBeforeDefinition
+          # Builds human-readable messages for blank line before definition violations
+          class MessagesBuilder
+            # Maps violation types to human-readable descriptions
+            ERROR_DESCRIPTIONS = {
+              'single' => 'Blank line between documentation and definition',
+              'orphaned' => 'Documentation is orphaned (YARD ignores it due to blank lines)'
+            }.freeze
+
+            class << self
+              # Formats a violation message
+              # @param offense [Hash] the offense details
+              # @return [String] formatted message
+              def call(offense)
+                type = offense[:violation_type]
+                object_name = offense[:object_name]
+                blank_count = offense[:blank_count]
+
+                description = ERROR_DESCRIPTIONS[type] || 'Blank line before definition'
+
+                if type == 'orphaned'
+                  "#{description} for '#{object_name}' (#{blank_count} blank lines)"
+                else
+                  "#{description} for '#{object_name}'"
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end