yard-lint 1.2.2 → 1.3.0.rc1

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/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

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
@@ -96,6 +107,44 @@ module Yard
         end
       end
 
+      # Filter result offenses based on per-validator exclusions
+      # Removes offenses where the file path matches exclusion patterns
+      # @param validator_name [String] full validator name
+      # @param result [Results::Base] result object with offenses
+      # @return [Results::Base, nil] result with filtered offenses, or nil if no offenses remain
+      def filter_result_offenses(validator_name, result)
+        validator_excludes = config.validator_all_excludes(validator_name)
+        return result if validator_excludes.empty?
+
+        working_dir = Dir.pwd
+
+        filtered_offenses = result.offenses.reject do |offense|
+          file_path = offense[:location] || offense[:file]
+          next true unless file_path
+
+          # Convert to relative path for pattern matching
+          relative_path = if file_path.start_with?(working_dir)
+                            file_path.sub(%r{^#{Regexp.escape(working_dir)}/}, '')
+                          else
+                            file_path
+                          end
+
+          # Check if file matches any exclusion pattern
+          validator_excludes.any? do |pattern|
+            File.fnmatch(pattern, relative_path, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+          end
+        end
+
+        # Return nil if no offenses remain after filtering
+        return nil if filtered_offenses.empty?
+
+        # 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
       # Delegates result building to ResultBuilder
       # @param raw [Hash] hash with raw results from all validators
@@ -108,7 +157,11 @@ module Yard
           next unless config.validator_enabled?(validator_name)
 
           result = @result_builder.build(validator_name, raw)
-          results << result if result
+          next unless result
+
+          # Filter offenses based on per-validator exclusions
+          filtered_result = filter_result_offenses(validator_name, result)
+          results << filtered_result if filtered_result
         end
 
         results

data/lib/yard/lint/stats_calculator.rb

@@ -8,7 +8,7 @@ module Yard
       attr_reader :config, :files
 
       # @param config [Yard::Lint::Config] configuration object
-      # @param files [Array<String>] files to analyze
+      # @param files [Array<String>] Ruby source files whose YARD documentation will be checked for coverage statistics
       def initialize(config, files)
         @config = config
         @files = Array(files).compact

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

@@ -0,0 +1,279 @@
+# 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
+
+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.'
+  Enabled: true
+  Severity: convention
+  EnforcedOrder:
+    - param
+    - option
+    - yield
+    - yieldparam
+    - yieldreturn
+    - return
+    - raise
+    - see
+    - example
+    - note
+    - todo
+
+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
+
+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.'
+  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