yard-lint 1.2.2 → 1.3.0.rc1

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

@@ -0,0 +1,283 @@
+# YARD-Lint Configuration (Strict Mode)
+# See https://github.com/mensfeld/yard-lint for documentation
+#
+# This is a strict configuration suitable for new projects with high documentation standards.
+# All validators are set to 'error' severity (no warnings or conventions).
+# Minimum coverage is set to 100%.
+
+# 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: error
+
+  # Minimum documentation coverage percentage (0-100)
+  # Fails if coverage is below this threshold
+  MinCoverage: 100.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: error
+  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: error
+
+Documentation/UndocumentedBooleanMethods:
+  Description: 'Checks that question mark methods document their boolean return.'
+  Enabled: true
+  Severity: error
+
+Documentation/UndocumentedOptions:
+  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Enabled: true
+  Severity: error
+
+Documentation/MarkdownSyntax:
+  Description: 'Detects common markdown syntax errors in documentation.'
+  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.'
+  Enabled: true
+  Severity: error
+  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: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax consistency.'
+  Enabled: true
+  Severity: error
+  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: error
+  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: error
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: 'Requires @option tags for methods with options parameters.'
+  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.'
+  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: error

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

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module BlankLineBeforeDefinition
+          # Parses YARD output for blank line before definition violations
+          class Parser < Parsers::Base
+            # Parse YARD output into structured violations
+            # @param output [String] raw YARD output
+            # @return [Array<Hash>] array of violation hashes
+            def call(output)
+              return [] if output.nil? || output.empty?
+
+              violations = []
+              lines = output.lines.map(&:chomp)
+
+              i = 0
+              while i < lines.size
+                line = lines[i]
+
+                # Match location line: "file:line: object_name"
+                if (location_match = line.match(/^(.+):(\d+): (.+)$/))
+                  file_path = location_match[1]
+                  object_line = location_match[2].to_i
+                  object_name = location_match[3]
+
+                  # Next line contains violation details
+                  i += 1
+                  next unless i < lines.size
+
+                  # Parse violation: "single:1" or "orphaned:3"
+                  detail_parts = lines[i].split(':', 2)
+                  next unless detail_parts.size == 2
+
+                  violation_type = detail_parts[0]
+                  blank_count = detail_parts[1].to_i
+
+                  violations << {
+                    location: file_path,
+                    line: object_line,
+                    object_name: object_name,
+                    violation_type: violation_type,
+                    blank_count: blank_count
+                  }
+                end
+
+                i += 1
+              end
+
+              violations
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Documentation
+        module BlankLineBeforeDefinition
+          # Result builder for blank line before definition violations
+          class Result < Results::Base
+            self.default_severity = 'convention'
+            self.offense_type = 'line'
+            self.offense_name = 'BlankLineBeforeDefinition'
+
+            # Build human-readable message for blank line violation
+            # @param offense [Hash] offense data with violation details
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+
+            private
+
+            # Override to handle per-violation severity based on violation type
+            # @return [Array<Hash>] array of offense hashes
+            def build_offenses
+              @parsed_data.map do |offense_data|
+                severity = severity_for_violation(offense_data[:violation_type])
+
+                offense_data.merge(
+                  severity: severity,
+                  type: self.class.offense_type,
+                  name: computed_offense_name,
+                  message: build_message(offense_data),
+                  location: offense_data[:location] || offense_data[:file],
+                  location_line: offense_data[:line] || offense_data[:location_line] || 0
+                )
+              end
+            end
+
+            # Get severity for a specific violation type
+            # @param violation_type [String] 'single' or 'orphaned'
+            # @return [String] severity level
+            def severity_for_violation(violation_type)
+              default = self.class.default_severity
+              return default unless config
+
+              case violation_type
+              when 'orphaned'
+                config.validator_config(validator_name, 'OrphanedSeverity') ||
+                  config.validator_severity(validator_name) ||
+                  default
+              else
+                config.validator_severity(validator_name) || default
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end