yard-lint 1.12.0 → 1.13.0

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

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Contracts
+      # Validates the whole configuration: root keys, AllValidators, categories and validators
+      class Config < Base
+        # 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
+
+        # Validator names must contain a '/' (category/name format)
+        virtual do |data|
+          data.keys.filter_map do |key|
+            next if SPECIAL_KEYS.include?(key)
+            next if VALID_CATEGORIES.include?(key)
+            next if key.include?('/')
+
+            [[key], message("Unknown validator: '#{key}'", suggest_validator_name(key))]
+          end
+        end
+
+        optional('AllValidators') do |all_validators|
+          !all_validators || all_validators.is_a?(Hash) ||
+            "Invalid AllValidators: must be a Hash, got #{all_validators.class}"
+        end
+
+        # Only specific known settings are validated, unknown keys pass through
+        # This allows users to put custom data in AllValidators
+        nested('AllValidators') do
+          optional('FailOnSeverity') do |fail_on|
+            !fail_on || Lint::Config::VALID_SEVERITIES.include?(fail_on.to_s) ||
+              message("Invalid FailOnSeverity: '#{fail_on}'", "  Valid values: #{Lint::Config::VALID_SEVERITIES.join(', ')}")
+          end
+
+          optional('MinCoverage') do |min_cov|
+            !min_cov || (min_cov.is_a?(Numeric) && !(min_cov < 0 || min_cov > 100)) ||
+              message("Invalid MinCoverage: '#{min_cov}'", '  Must be a number between 0 and 100')
+          end
+
+          optional('Exclude') do |exclude|
+            !exclude || exclude.is_a?(Array) ||
+              "Invalid Exclude in AllValidators: must be an array, got #{exclude.class}"
+          end
+
+          optional('YardOptions') do |yard_options|
+            !yard_options || yard_options.is_a?(Array) ||
+              "Invalid YardOptions in AllValidators: must be an array, got #{yard_options.class}"
+          end
+        end
+
+        virtual do |data|
+          data.flat_map do |key, value|
+            next [] unless VALID_CATEGORIES.include?(key)
+            next [] unless value.is_a?(Hash)
+
+            nested_errors(Category.new(key).call(value, scope: [key]))
+          end
+        end
+
+        virtual do |data|
+          data.flat_map do |key, value|
+            next [] unless key.include?('/')
+
+            unless value.is_a?(Hash)
+              next [[[key], "Invalid configuration for validator '#{key}': expected a Hash, got #{value.class}"]]
+            end
+
+            nested_errors(Validator.new(key).call(value, scope: [key]))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Contracts
+      # Validates a single validator configuration (e.g. `Tags/Order: { Enabled: ... }`)
+      class Validator < Base
+        # Base config keys that are valid for all validators
+        BASE_KEYS = %w[Enabled Severity Exclude YardOptions].freeze
+
+        # @return [String] validator name
+        attr_reader :name
+
+        # @param name [String] validator name used in error messages
+        def initialize(name)
+          super()
+          @name = name
+        end
+
+        virtual do |_data, _errors, contract|
+          next if ConfigLoader::ALL_VALIDATORS.include?(contract.name)
+
+          [[[], message("Unknown validator: '#{contract.name}'", suggest_validator_name(contract.name))]]
+        end
+
+        optional('Enabled') do |enabled, _data, _errors, contract|
+          !enabled || BOOLEAN_VALUES.include?(enabled) ||
+            message("Invalid Enabled value for #{contract.name}: '#{enabled}'", '  Must be true or false')
+        end
+
+        optional('Severity') do |severity, _data, _errors, contract|
+          !severity || Lint::Config::VALID_SEVERITIES.include?(severity.to_s) ||
+            message(
+              "Invalid Severity for #{contract.name}: '#{severity}'",
+              "  Valid values: #{Lint::Config::VALID_SEVERITIES.join(', ')}",
+              suggest_similar_severity(severity.to_s)
+            )
+        end
+
+        optional('Exclude') do |exclude, _data, _errors, contract|
+          !exclude || exclude.is_a?(Array) ||
+            "Invalid Exclude for #{contract.name}: must be an array, got #{exclude.class}"
+        end
+
+        optional('YardOptions') do |yard_options, _data, _errors, contract|
+          !yard_options || yard_options.is_a?(Array) ||
+            "Invalid YardOptions for #{contract.name}: must be an array, got #{yard_options.class}"
+        end
+
+        # Unknown validator-specific keys (an unknown validator is already reported)
+        virtual do |data, _errors, contract|
+          next unless ConfigLoader::ALL_VALIDATORS.include?(contract.name)
+
+          validator_config_class = ConfigLoader.validator_config(contract.name)
+          next unless validator_config_class
+
+          valid_keys = (validator_config_class.defaults.keys + Lint::Config::METADATA_KEYS + BASE_KEYS).uniq.sort
+
+          (data.keys - valid_keys).map do |key|
+            [
+              [key],
+              message(
+                "Unknown configuration key for #{contract.name}: '#{key}'",
+                "  Valid keys: #{valid_keys.join(', ')}"
+              )
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/errors.rb

@@ -22,6 +22,9 @@ module Yard
       # Raised when .yard-lint-todo.yml already exists without force flag
       class TodoFileExistsError < BaseError; end
 
+      # Raised when .yard-lint-todo.yml is required but does not exist
+      class TodoFileNotFoundError < BaseError; end
+
       # Raised when configuration is invalid
       class InvalidConfigError < BaseError; end
     end

data/lib/yard/lint/executor/in_process_registry.rb

@@ -112,7 +112,7 @@ module Yard
               next false unless obj.file
 
               file_excludes.any? do |pattern|
-                File.fnmatch(pattern, obj.file, File::FNM_PATHNAME | File::FNM_EXTGLOB)
+                File.fnmatch(pattern, obj.file, Config::EXCLUDE_FLAGS)
               end
             end
           end

data/lib/yard/lint/explainer.rb

@@ -24,11 +24,34 @@ module Yard
         new(name).call
       end
 
+      # Structured description of a validator for programmatic consumers such as
+      # the SARIF formatter's rule metadata (as opposed to #call's terminal text).
+      # @param name [String] validator name (e.g. 'Tags/TypeSyntax')
+      # @return [Hash{Symbol => String}, nil] { short:, full: }, or nil when the
+      #   name is unknown or the validator has no docstring
+      def self.describe(name)
+        new(name).describe
+      end
+
       # @param name [String] validator name (e.g. 'Tags/TypeSyntax')
       def initialize(name)
         @name = name
       end
 
+      # @return [Hash{Symbol => String}, nil] { short:, full: } description of the
+      #   validator, or nil when unknown or undocumented
+      def describe
+        return nil unless ConfigLoader::ALL_VALIDATORS.include?(@name)
+
+        doc = documentation
+        return nil unless doc
+
+        full = prose_only(doc[:description])
+        return nil if full.empty?
+
+        { short: first_sentence(full), full: full }
+      end
+
       # @return [String] formatted, terminal-ready explanation
       # @raise [ArgumentError] if name is not a known validator
       def call
@@ -114,6 +137,25 @@ module Yard
         end
       end
 
+      # The human description of a validator: its docstring prose with the leading
+      # "<Name> validator" title line and any trailing "## ..." sections (e.g.
+      # Configuration) removed, leaving just the explanation.
+      # @param description [String] the raw docstring text
+      # @return [String] the trimmed prose (may be empty)
+      def prose_only(description)
+        lines = description.to_s.lines.take_while { |line| !line.start_with?('## ') }
+        text = lines.join
+        text = text.sub(/\A.*validator[ \t]*\n+/i, '') if text.match?(/\A.*validator[ \t]*\n/i)
+        text.strip
+      end
+
+      # @param text [String] prose text
+      # @return [String] the first sentence, for a concise one-line summary
+      def first_sentence(text)
+        flat = text.tr("\n", ' ').squeeze(' ').strip
+        flat[/.*?[.!?](?=\s|\z)/] || flat
+      end
+
       # @return [String] the fully-qualified code object path (e.g.
       #   'Yard::Lint::Validators::Tags::TypeSyntax')
       def object_path