yard-lint 1.11.0 → 1.13.0

data/lib/yard/lint/config_validator.rb

@@ -4,23 +4,9 @@ module Yard
   module Lint
     # Validates configuration structure and values to catch typos and invalid settings
     class ConfigValidator
-      # Valid category names (from ConfigUpdater::CATEGORY_ORDER)
-      VALID_CATEGORIES = %w[Documentation Tags Warnings Semantic].freeze
-
-      # Keys that are valid at the root level but are not validators
-      SPECIAL_KEYS = %w[
-        AllValidators
-        inherit_from
-        inherit_gem
-      ].freeze
-
-      # Valid boolean values
-      BOOLEAN_VALUES = [true, false].freeze
-
       # @param raw_config [Hash] raw configuration hash to validate
       def initialize(raw_config)
         @raw_config = raw_config
-        @errors = []
       end
 
       # Validate configuration and raise error if invalid
@@ -36,191 +22,21 @@ module Yard
       # @return [void]
       # @raise [Errors::InvalidConfigError] if configuration is invalid
       def validate!
-        validate_root_keys!
-        validate_global_settings!
-        validate_validators!
+        result = Contracts::Config.new.call(@raw_config)
 
-        return if @errors.empty?
+        return if result.success?
 
-        raise Errors::InvalidConfigError, build_error_message
+        raise Errors::InvalidConfigError, build_error_message(result.errors.values)
       end
 
       private
 
-      # Validate root-level keys in configuration
-      def validate_root_keys!
-        @raw_config.each_key do |key|
-          # Skip special keys
-          next if SPECIAL_KEYS.include?(key)
-
-          # Skip category-level configs (e.g., 'Documentation', 'Tags')
-          next if VALID_CATEGORIES.include?(key)
-
-          # Validator names must contain a '/' (category/name format)
-          next if key.include?('/')
-
-          # If we get here, it's an unknown validator (missing category prefix)
-          @errors << "Unknown validator: '#{key}'"
-          suggest_validator_name(key)
-        end
-      end
-
-      # Validate AllValidators section
-      def validate_global_settings!
-        all_validators = @raw_config['AllValidators']
-        return unless all_validators
-
-        unless all_validators.is_a?(Hash)
-          @errors << "Invalid AllValidators: must be a Hash, got #{all_validators.class}"
-          return
-        end
-
-        # Only validate specific known settings, allow unknown keys to pass through
-        # This allows users to put custom data in AllValidators
-
-        # Validate FailOnSeverity value
-        fail_on = all_validators['FailOnSeverity']
-        if fail_on && !Config::VALID_SEVERITIES.include?(fail_on.to_s)
-          @errors << "Invalid FailOnSeverity: '#{fail_on}'"
-          @errors << "  Valid values: #{Config::VALID_SEVERITIES.join(', ')}"
-        end
-
-        # Validate MinCoverage value
-        min_cov = all_validators['MinCoverage']
-        if min_cov && (!min_cov.is_a?(Numeric) || min_cov < 0 || min_cov > 100)
-          @errors << "Invalid MinCoverage: '#{min_cov}'"
-          @errors << '  Must be a number between 0 and 100'
-        end
-
-        # Validate Exclude is an array
-        exclude = all_validators['Exclude']
-        if exclude && !exclude.is_a?(Array)
-          @errors << "Invalid Exclude in AllValidators: must be an array, got #{exclude.class}"
-        end
-
-        # Validate YardOptions is an array
-        yard_options = all_validators['YardOptions']
-        if yard_options && !yard_options.is_a?(Array)
-          @errors << "Invalid YardOptions in AllValidators: must be an array, got #{yard_options.class}"
-        end
-      end
-
-      # Validate validator-specific configurations
-      def validate_validators!
-        @raw_config.each do |key, value|
-          # Only process validator keys (containing '/')
-          next unless key.include?('/')
-
-          unless value.is_a?(Hash)
-            @errors << "Invalid configuration for validator '#{key}': expected a Hash, got #{value.class}"
-            next
-          end
-
-          validate_validator_exists!(key)
-          validate_validator_config!(key, value)
-        end
-      end
-
-      # Check if validator name exists
-      # @param validator_name [String] validator name to check
-      # @return [void]
-      def validate_validator_exists!(validator_name)
-        return if ConfigLoader::ALL_VALIDATORS.include?(validator_name)
-
-        @errors << "Unknown validator: '#{validator_name}'"
-        suggest_validator_name(validator_name)
-      end
-
-      # Validate individual validator configuration
-      # @param validator_name [String] validator name
-      # @param config [Hash] validator configuration hash
-      # @return [void]
-      def validate_validator_config!(validator_name, config)
-        # Validate Enabled value
-        enabled = config['Enabled']
-        if enabled && !BOOLEAN_VALUES.include?(enabled)
-          @errors << "Invalid Enabled value for #{validator_name}: '#{enabled}'"
-          @errors << '  Must be true or false'
-        end
-
-        # Validate Severity value
-        severity = config['Severity']
-        if severity && !Config::VALID_SEVERITIES.include?(severity.to_s)
-          @errors << "Invalid Severity for #{validator_name}: '#{severity}'"
-          @errors << "  Valid values: #{Config::VALID_SEVERITIES.join(', ')}"
-          suggest_similar_severity(severity.to_s)
-        end
-
-        # Validate Exclude is an array
-        exclude = config['Exclude']
-        if exclude && !exclude.is_a?(Array)
-          @errors << "Invalid Exclude for #{validator_name}: must be an array, got #{exclude.class}"
-        end
-
-        # Validate YardOptions is an array
-        yard_options = config['YardOptions']
-        if yard_options && !yard_options.is_a?(Array)
-          @errors << "Invalid YardOptions for #{validator_name}: must be an array, got #{yard_options.class}"
-        end
-
-        # Check for unknown validator-specific keys
-        validate_validator_specific_keys!(validator_name, config)
-      end
-
-      # Validate validator-specific configuration keys
-      # @param validator_name [String] validator name
-      # @param config [Hash] validator configuration hash
-      # @return [void]
-      def validate_validator_specific_keys!(validator_name, config)
-        # Skip if validator doesn't exist (already reported)
-        return unless ConfigLoader::ALL_VALIDATORS.include?(validator_name)
-
-        validator_config_class = ConfigLoader.validator_config(validator_name)
-        return unless validator_config_class
-
-        # Base config keys that are valid for all validators
-        base_keys = %w[Enabled Severity Exclude YardOptions]
-        valid_keys = validator_config_class.defaults.keys + Config::METADATA_KEYS + base_keys
-
-        config.each_key do |key|
-          next if valid_keys.include?(key)
-
-          @errors << "Unknown configuration key for #{validator_name}: '#{key}'"
-          @errors << "  Valid keys: #{valid_keys.uniq.sort.join(', ')}"
-        end
-      end
-
-      # Suggest similar validator names using did_you_mean
-      # @param invalid_name [String] invalid validator name
-      # @return [void]
-      def suggest_validator_name(invalid_name)
-        checker = DidYouMean::SpellChecker.new(dictionary: ConfigLoader::ALL_VALIDATORS)
-        suggestions = checker.correct(invalid_name)
-
-        if suggestions.any?
-          @errors << "  Did you mean: #{suggestions.first}?"
-        else
-          @errors << '  See https://github.com/mensfeld/yard-lint/wiki/Validators ' \
-                     'for all available validators'
-        end
-      end
-
-      # Suggest similar severity values
-      # @param invalid_severity [String] invalid severity value
-      # @return [void]
-      def suggest_similar_severity(invalid_severity)
-        checker = DidYouMean::SpellChecker.new(dictionary: Config::VALID_SEVERITIES)
-        suggestions = checker.correct(invalid_severity)
-
-        if suggestions.any?
-          @errors << "  Did you mean: #{suggestions.first}?"
-        end
-      end
-
       # Build comprehensive error message
-      def build_error_message
+      # @param messages [Array<String>] error messages, each one or more lines
+      # @return [String] error message with one indented line per error line
+      def build_error_message(messages)
         header = 'Invalid configuration detected:'
-        errors_text = @errors.map { |e| "  #{e}" }.join("\n")
+        errors_text = messages.flat_map { |message| message.split("\n") }.map { |e| "  #{e}" }.join("\n")
 
         "#{header}\n#{errors_text}"
       end

data/lib/yard/lint/contractable/contract.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Rule based data validation, copied from karafka-core
+    module Contractable
+      # Base contract for all the contracts that check data format
+      #
+      # Copied from karafka-core (`Karafka::Core::Contractable`), without its `Configurable`
+      # dependency: `error_messages` is a plain class-level accessor.
+      #
+      # @note This contract does NOT support rules inheritance
+      class Contract
+        # Constant representing a miss during dig
+        # We use it as a result value not to return an array with found object and a state to
+        # prevent additional array allocation
+        DIG_MISS = Object.new
+
+        # Empty array for scope default to avoid allocating a new Array on each
+        # `#call` / `#validate!` invocation. Safe because scope is never mutated - it is only
+        # used in `scope + rule.path` which creates a new Array.
+        EMPTY_ARRAY = [].freeze
+
+        private_constant :DIG_MISS, :EMPTY_ARRAY
+
+        # Class level API definitions
+        class << self
+          # @return [Array<Rule>] all the validation rules defined for a given contract
+          attr_reader :rules
+
+          attr_writer :error_messages
+
+          # @return [Hash{String => String}] error messages for error keys that rules return
+          #   instead of custom message Strings
+          def error_messages
+            @error_messages || {}
+          end
+
+          # Allows for definition of a scope/namespace for nested validations
+          #
+          # @param path [Symbol] path in the hash for nesting
+          #
+          # @example
+          #   nested(:key) do
+          #     required(:inside) { |inside| inside.is_a?(String) }
+          #   end
+          def nested(path, &)
+            init_accu
+            @nested << path
+            begin
+              instance_eval(&)
+            ensure
+              # Always pop, even if the block raises. Otherwise a rescued exception during
+              # contract definition would leave `path` on @nested and prefix it onto every rule
+              # defined afterwards.
+              @nested.pop
+            end
+          end
+
+          # Defines a rule for a required field (required means, that will automatically create an
+          # error if missing)
+          #
+          # @param keys [Array<Symbol>] single or full path
+          # @param block [Proc] validation rule
+          def required(*keys, &block)
+            init_accu
+            @rules << Rule.new(@nested + keys, :required, block).freeze
+          end
+
+          # @param keys [Array<Symbol>] single or full path
+          # @param block [Proc] validation rule
+          def optional(*keys, &block)
+            init_accu
+            @rules << Rule.new(@nested + keys, :optional, block).freeze
+          end
+
+          # Defines a virtual rule that validates the whole data rather than a single key. Unlike
+          # `required`/`optional`, the block receives the full data and returns its own errors.
+          #
+          # @param block [Proc] validation rule, called with `(data, errors, contract)`. It must
+          #   return either a non-Array (`true`/`nil`/`false`) for "no errors", or an `Array` of
+          #   `[path, message]` error pairs (where `path` is itself an `Array` of symbols).
+          #
+          # @note The returned error `Array` is owned by the contract: `#call` prepends the current
+          #   scope onto each pair in place and collects them, so a rule must return a freshly
+          #   built `Array` on every call. Returning a memoized, shared or frozen `Array` is not
+          #   supported -- in-place scoping would accumulate the prefix across validations (or
+          #   raise `FrozenError`). Build the result in the block (e.g. `[[%i[id], :invalid]]`)
+          #   rather than returning a constant.
+          def virtual(&block)
+            init_accu
+            @rules << Rule.new([], :virtual, block).freeze
+          end
+
+          private
+
+          # Initializes nestings and rules building accumulator
+          def init_accu
+            @nested ||= []
+            @rules ||= []
+          end
+        end
+
+        # Runs the validation
+        #
+        # The per-rule handling is inlined instead of dispatching to per-type methods because
+        # this runs per rule per validation. Required and optional rules share the whole flow
+        # except the missing-key handling. `DIG_MISS` is compared via `#equal?` so we never dispatch `#==` to the
+        # validated (user-provided) values.
+        #
+        # @param data [Hash] hash with data we want to validate
+        # @param scope [Array<String>] scope of this contract (if any) or empty array if no parent
+        #   scope is needed if contract starts from root
+        # @return [Result] validation result
+        def call(data, scope: EMPTY_ARRAY)
+          errors = []
+
+          # A non-Hash root has no keys to dig; resolve it once here so #dig stays on its lean
+          # fast path and is only invoked with a Hash. Non-Hash data makes every required rule
+          # report missing, consistent with the non-Hash intermediate handling inside #dig.
+          data_is_hash = data.is_a?(Hash)
+
+          self.class.rules.each do |rule|
+            if rule.type == :virtual
+              result = rule.validator.call(data, errors, self)
+
+              # A virtual rule signals "no errors" with any non-Array result (true, but also a
+              # falsy `nil`/`false` returned by e.g. `condition && [[...], :err]`). Only an Array
+              # of error pairs is iterated.
+              next unless result.is_a?(Array)
+
+              # Apply the scope prefix in place on the rule's returned pairs and collect them
+              # directly. Per the `virtual` contract the rule hands back a freshly built Array
+              # each call (see `.virtual`), so mutating it here is safe and avoids allocating a
+              # new pair per error.
+              result.each do |sub_result|
+                sub_result[0] = scope + sub_result[0]
+              end
+
+              errors.push(*result)
+            else
+              for_checking = data_is_hash ? dig(data, rule.path) : DIG_MISS
+
+              if DIG_MISS.equal?(for_checking)
+                errors << [scope + rule.path, :missing] if rule.type == :required
+              else
+                result = rule.validator.call(for_checking, data, errors, self)
+
+                next if result == true
+
+                errors << [scope + rule.path, result || :format]
+              end
+            end
+          end
+
+          return Result.success if errors.empty?
+
+          Result.new(errors, self)
+        end
+
+        # Runs the validation like `#call`, but raises instead of returning a failed `Result`
+        #
+        # @param data [Hash] data for validation
+        # @param error_class [Class] error class that should be used when validation fails
+        # @param scope [Array<String>] scope of this contract (if any) or empty array if no parent
+        #   scope is needed if contract starts from root
+        # @return [Boolean] true
+        # @raise [StandardError] any error provided in the error_class that inherits from the
+        #   standard error
+        def validate!(data, error_class, scope: EMPTY_ARRAY)
+          result = call(data, scope: scope)
+
+          return true if result.success?
+
+          raise error_class, result.errors
+        end
+
+        private
+
+        # Tries to dig for a given key in a hash and returns it with indication whether or not it
+        # was possible to find it (dig returns nil and we don't know if it wasn't the digged key
+        # value)
+        #
+        # Uses `Hash#fetch` with the `DIG_MISS` sentinel as the default, which resolves presence
+        # and value in a single hash lookup instead of a `key?` check followed by `[]`.
+        # `fetch` with a default ignores `default_proc`.
+        #
+        # @param data [Hash]
+        # @param keys [Array<Symbol>]
+        # @return [DIG_MISS, Object] found element or DIG_MISS indicating that not found
+        def dig(data, keys)
+          case keys.length
+          when 1
+            data.fetch(keys[0], DIG_MISS)
+          when 2
+            mid = data.fetch(keys[0], DIG_MISS)
+
+            return DIG_MISS if DIG_MISS.equal?(mid)
+            return DIG_MISS unless mid.is_a?(Hash)
+
+            mid.fetch(keys[1], DIG_MISS)
+          else
+            current = data
+
+            keys.each do |nesting|
+              return DIG_MISS unless current.is_a?(Hash)
+
+              current = current.fetch(nesting, DIG_MISS)
+
+              return DIG_MISS if DIG_MISS.equal?(current)
+            end
+
+            current
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/contractable/result.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Contractable
+      # Representation of a validation result with resolved error messages
+      class Result
+        attr_reader :errors
+
+        # Empty hash that we use when no errors to save on allocations
+        EMPTY_HASH = {}.freeze
+
+        private_constant :EMPTY_HASH
+
+        class << self
+          # @return [Result] cached frozen success result to avoid allocating a new Result on
+          #   every successful contract validation. Safe because successful results are
+          #   identical regardless of contract (they all have @errors = EMPTY_HASH).
+          def success
+            @success ||= new([], nil).freeze
+          end
+        end
+
+        # Builds a result object and remaps (if needed) error keys to proper error messages
+        #
+        # @param errors [Array<Array>] array with sub-arrays with paths and error keys
+        # @param contract [Object] contract that generated the error
+        def initialize(errors, contract)
+          # Short track to skip object allocation for the happy path
+          if errors.empty?
+            @errors = EMPTY_HASH
+            return
+          end
+
+          hashed = {}
+
+          errors.each do |error|
+            scope = error.first.map(&:to_s).join('.').to_sym
+
+            # This will allow for usage of custom messages instead of yaml keys if needed
+            hashed[scope] = if error.last.is_a?(String)
+              error.last
+            else
+              build_message(contract, scope, error.last)
+            end
+          end
+
+          @errors = hashed
+        end
+
+        # @return [Boolean] true if no errors
+        def success?
+          errors.empty?
+        end
+
+        private
+
+        # Builds message based on the error messages and scope
+        #
+        # @param contract [Object] contract for which we build the result
+        # @param scope [Symbol] path to the key that has an error
+        # @param error_key [Symbol] error key for yaml errors lookup
+        # @return [String] error message
+        def build_message(contract, scope, error_key)
+          messages = contract.class.error_messages
+
+          # Split scope into parts for progressive checking
+          scope_parts = scope.to_s.split('.')
+
+          # Try full scope first, then progressively remove from beginning
+          # This allows us to have full path scoped errors but can also be used as a fallback,
+          # when scopes are dynamic. For example 'consumer_group_name.topic_name.name_format'
+          (0..scope_parts.length).each do |i|
+            current_scope_parts = scope_parts[i..]
+
+            key = if current_scope_parts.empty?
+              error_key.to_s
+            else
+              "#{current_scope_parts.join('.')}_#{error_key}"
+            end
+
+            return messages[key] if messages.key?(key)
+          end
+
+          # If nothing found, raise the original error
+          messages.fetch(error_key.to_s) do
+            messages.fetch("#{scope}_#{error_key}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/contractable/rule.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Contractable
+      # Representation of a single validation rule
+      Rule = Struct.new(:path, :type, :validator)
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Contracts that validate the configuration structure and values
+    module Contracts
+      # Base for the configuration contracts with the helpers that build their error messages
+      class Base < Contractable::Contract
+        # Valid boolean values
+        BOOLEAN_VALUES = [true, false].freeze
+
+        class << self
+          private
+
+          # Builds an error message out of its lines
+          # @param lines [Array<String, nil>] message lines, nil lines are skipped
+          # @return [String] multi-line error message
+          def message(*lines)
+            lines.compact.join("\n")
+          end
+
+          # Converts errors of a nested contract into virtual rule errors of the parent contract
+          # @param result [Contractable::Result] nested contract validation result
+          # @return [Array<Array>] error pairs with the nested error scope as their path
+          def nested_errors(result)
+            result.errors.map { |scope, error| [[scope], error] }
+          end
+
+          # Suggest similar validator names using did_you_mean
+          # @param invalid_name [String] invalid validator name
+          # @return [String] suggestion line
+          def suggest_validator_name(invalid_name)
+            checker = DidYouMean::SpellChecker.new(dictionary: ConfigLoader::ALL_VALIDATORS)
+            suggestions = checker.correct(invalid_name)
+
+            if suggestions.any?
+              "  Did you mean: #{suggestions.first}?"
+            else
+              '  See https://github.com/mensfeld/yard-lint/wiki/Validators ' \
+                'for all available validators'
+            end
+          end
+
+          # Suggest similar severity values
+          # @param invalid_severity [String] invalid severity value
+          # @return [String, nil] suggestion line or nil when there is no similar value
+          def suggest_similar_severity(invalid_severity)
+            checker = DidYouMean::SpellChecker.new(dictionary: Lint::Config::VALID_SEVERITIES)
+            suggestions = checker.correct(invalid_severity)
+
+            "  Did you mean: #{suggestions.first}?" if suggestions.any?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/contracts/category.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Contracts
+      # Validates a category-level configuration (e.g. `Documentation: { Severity: ... }`)
+      class Category < Base
+        # Keys that are valid in a category-level configuration
+        KEYS = %w[Enabled Exclude Severity].freeze
+
+        # @return [String] category name
+        attr_reader :name
+
+        class << self
+          private
+
+          # Suggest similar category configuration keys
+          # @param invalid_key [String] invalid category key
+          # @return [String, nil] suggestion line or nil when there is no similar key
+          def suggest_category_key(invalid_key)
+            checker = DidYouMean::SpellChecker.new(dictionary: KEYS)
+            suggestions = checker.correct(invalid_key)
+
+            "  Did you mean: #{suggestions.first}?" if suggestions.any?
+          end
+        end
+
+        # @param name [String] category name used in error messages
+        def initialize(name)
+          super()
+          @name = name
+        end
+
+        optional('Enabled') do |enabled, _data, _errors, contract|
+          BOOLEAN_VALUES.include?(enabled) ||
+            message(
+              "Invalid Enabled value for category #{contract.name}: '#{enabled}'",
+              '  Must be true or false'
+            )
+        end
+
+        optional('Exclude') do |exclude, _data, _errors, contract|
+          !exclude || exclude.is_a?(Array) ||
+            "Invalid Exclude for category #{contract.name}: must be an array, got #{exclude.class}"
+        end
+
+        optional('Severity') do |severity, _data, _errors, contract|
+          !severity || Lint::Config::VALID_SEVERITIES.include?(severity.to_s) ||
+            message(
+              "Invalid Severity for category #{contract.name}: '#{severity}'",
+              "  Valid values: #{Lint::Config::VALID_SEVERITIES.join(', ')}",
+              suggest_similar_severity(severity.to_s)
+            )
+        end
+
+        virtual do |data, _errors, contract|
+          (data.keys - KEYS).map do |key|
+            [
+              [key],
+              message(
+                "Unknown configuration key for category #{contract.name}: '#{key}'",
+                "  Valid keys: #{KEYS.join(', ')}",
+                suggest_category_key(key.to_s)
+              )
+            ]
+          end
+        end
+      end
+    end
+  end
+end