grape-oas 1.2.0 → 1.4.0

data/lib/grape_oas/introspectors/entity_introspector_support.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Introspectors
+    # Shared helpers used by multiple classes within EntityIntrospectorSupport.
+    # These are module-level methods to avoid copy-pasting the same logic across
+    # ExposureProcessor, DiscriminatorHandler, and InheritanceBuilder.
+    module EntityIntrospectorSupport
+      # Returns the raw exposure list for an entity class.
+      # Reads root_exposures via internal Grape::Entity ivars, which is
+      # unavoidable given Grape does not expose a stable public API for this.
+      def self.exposures(entity_class)
+        return [] unless entity_class.respond_to?(:root_exposures)
+
+        root = entity_class.root_exposures
+        list = root.instance_variable_get(:@exposures) || []
+        Array(list)
+      rescue NoMethodError
+        []
+      end
+
+      # Resolves the canonical name for an entity class, preferring entity_name
+      # when defined on the class itself (via def self. or extend) and non-blank,
+      # falling back to the Ruby class name. Inherited entity_name is ignored to
+      # avoid collisions between parent and child schemas.
+      def self.resolve_canonical_name(entity_class)
+        if defines_own_entity_name?(entity_class)
+          name = entity_class.entity_name
+          name.is_a?(String) && !name.strip.empty? ? name : entity_class.name
+        else
+          entity_class.name
+        end
+      end
+
+      def self.defines_own_entity_name?(entity_class)
+        return false unless entity_class.respond_to?(:entity_name)
+
+        parent = find_parent_entity(entity_class)
+        return true if parent.nil? || !parent.respond_to?(:entity_name)
+
+        entity_class.method(:entity_name).owner !=
+          parent.method(:entity_name).owner
+      end
+      private_class_method :defines_own_entity_name?
+
+      # Finds the parent entity class if one exists in the Grape::Entity hierarchy.
+      def self.find_parent_entity(entity_class)
+        return nil unless defined?(Grape::Entity)
+
+        parent = entity_class.superclass
+        return nil unless parent && parent < Grape::Entity && parent != Grape::Entity
+
+        parent
+      end
+    end
+  end
+end

data/lib/grape_oas/range_utils.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  # Converts Range values into OpenAPI-compatible representations.
+  class RangeUtils
+    NUMERIC_TYPES = [Constants::SchemaTypes::INTEGER, Constants::SchemaTypes::NUMBER].freeze
+
+    class << self
+      # Expands a non-numeric bounded Range to an enum array.
+      # Returns nil for numeric, unbounded, empty, or oversized ranges.
+      def expand_range_to_enum(range)
+        return nil if range.begin.nil? || range.end.nil?
+        return nil if range.begin.is_a?(Numeric) || range.end.is_a?(Numeric)
+
+        begin
+          array = range.first(Constants::MAX_ENUM_RANGE_SIZE + 1)
+        rescue TypeError
+          return nil
+        end
+
+        return nil if array.empty? || array.size > Constants::MAX_ENUM_RANGE_SIZE
+
+        array
+      end
+
+      # Writes numeric range constraints directly to any object with
+      # minimum=/maximum=/exclusive_maximum= setters (Schema, ConstraintSet, etc).
+      # Skips descending and infinite bounds.
+      def apply_numeric_range(target, range)
+        return unless range
+
+        first_val = range.begin
+        last_val = range.end
+
+        return if descending?(first_val, last_val)
+
+        target.minimum = first_val if finite_numeric?(first_val) && target.respond_to?(:minimum=)
+        return unless finite_numeric?(last_val)
+
+        target.maximum = last_val if target.respond_to?(:maximum=)
+        target.exclusive_maximum = range.exclude_end? if target.respond_to?(:exclusive_maximum=)
+      end
+
+      # Returns true when all non-nil bounds are Numeric (pure numeric range).
+      def numeric_range?(range)
+        bounds = [range.begin, range.end].compact
+        bounds.any? && bounds.all?(Numeric)
+      end
+
+      # Applies a Range to a schema as min/max or enum.
+      # @param schema [ApiModel::Schema]
+      def apply_to_schema(schema, range)
+        bounds = [range.begin, range.end].compact
+        return if bounds.empty?
+
+        all_numeric = numeric_range?(range)
+        any_numeric = bounds.any?(Numeric)
+        mixed_numeric = any_numeric && !all_numeric
+        numeric_range = all_numeric
+        numeric_type = NUMERIC_TYPES.include?(schema.type)
+
+        if mixed_numeric
+          GrapeOAS.logger.warn("Mixed-type range #{range} ignored; endpoints must both be numeric or both non-numeric")
+        elsif numeric_range && numeric_type
+          apply_numeric_range(schema, range)
+        elsif numeric_range
+          GrapeOAS.logger.warn("Numeric range #{range} ignored on non-numeric schema type '#{schema.type}'")
+        elsif !numeric_type
+          expanded = expand_range_to_enum(range)
+          schema.enum = expanded if expanded
+        else
+          GrapeOAS.logger.warn("Non-numeric range #{range} ignored on numeric schema type '#{schema.type}'")
+        end
+      end
+
+      private
+
+      def finite_numeric?(val)
+        val.is_a?(Numeric) && val.finite?
+      end
+
+      def descending?(first_val, last_val)
+        first_val.is_a?(Numeric) && last_val.is_a?(Numeric) && first_val > last_val
+      end
+    end
+  end
+end

data/lib/grape_oas/schema_constraints.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  # Applies numeric and string constraints from documentation to a schema.
+  #
+  # Accepts both symbol-keyed and string-keyed doc hashes; keys are normalized
+  # internally so callers need not pre-convert them.
+  module SchemaConstraints
+    def self.apply(schema, doc)
+      doc = doc.transform_keys(&:to_sym) unless doc.empty?
+      if doc.key?(:minimum)
+        schema.minimum = doc[:minimum] if schema.respond_to?(:minimum=)
+        # Clear stale exclusive_minimum; re-set below if also provided
+        schema.exclusive_minimum = nil if schema.respond_to?(:exclusive_minimum=) && !doc.key?(:exclusive_minimum)
+      end
+      if doc.key?(:maximum)
+        schema.maximum = doc[:maximum] if schema.respond_to?(:maximum=)
+        # Clear stale exclusive_maximum; re-set below if also provided
+        schema.exclusive_maximum = nil if schema.respond_to?(:exclusive_maximum=) && !doc.key?(:exclusive_maximum)
+      end
+      set_if_present(schema, :exclusive_minimum=, doc, :exclusive_minimum)
+      set_if_present(schema, :exclusive_maximum=, doc, :exclusive_maximum)
+      set_if_present(schema, :min_length=, doc, :min_length)
+      set_if_present(schema, :max_length=, doc, :max_length)
+      set_if_present(schema, :pattern=, doc, :pattern)
+    end
+
+    def self.set_if_present(schema, setter, doc, key)
+      return unless doc.key?(key) && schema.respond_to?(setter)
+
+      schema.public_send(setter, doc[key])
+    end
+
+    private_class_method :set_if_present
+  end
+end

data/lib/grape_oas/type_resolvers/array_resolver.rb

@@ -20,15 +20,13 @@ module GrapeOAS
     class ArrayResolver
       extend Base
 
-      # Pattern to match Grape's array notation: "[Type]" or "[Module::Type]"
-      # Intentionally narrow: avoid treating multi-type strings like "[String, Integer]" as arrays.
-      ARRAY_PATTERN = /\A\[(?<inner>(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*)\]\z/
+      TYPED_ARRAY_PATTERN = Constants::TypePatterns::TYPED_ARRAY
 
       class << self
         def handles?(type)
           return false unless type.is_a?(String)
 
-          type.match?(ARRAY_PATTERN)
+          type.match?(TYPED_ARRAY_PATTERN)
         end
 
         def build_schema(type)
@@ -53,7 +51,7 @@ module GrapeOAS
         private
 
         def extract_inner_type(type)
-          match = type.match(ARRAY_PATTERN)
+          match = type.match(TYPED_ARRAY_PATTERN)
           match[:inner] if match
         end
 

data/lib/grape_oas/values_normalizer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  # Normalizes values from Grape parameter or entity documentation into
+  # Array, Range, or nil for OpenAPI schema generation.
+  module ValuesNormalizer
+    # @param values [Object] raw values from spec or documentation
+    # @param context [String] description for warning messages
+    # @return [Array, Range, nil]
+    def self.normalize(values, context: "values")
+      return nil unless values
+
+      return nil if values.is_a?(Hash) && !values.key?(:value) && !values.key?("value")
+
+      values = values.key?(:value) ? values[:value] : values["value"] if values.is_a?(Hash)
+      return nil unless values
+
+      if values.respond_to?(:call)
+        # Two-stage defense for callable values:
+        # 1) Arity check filters out validators (arity > 0) and objects without arity.
+        #    This is a heuristic — optional-arg procs (proc { |v = nil| ... }) report arity 0.
+        # 2) Post-call type check catches those false positives by verifying the return
+        #    value is a collection type. Both guards are load-bearing; do not remove either.
+        return nil unless values.respond_to?(:arity) && values.arity.zero?
+
+        begin
+          values = values.call
+        rescue StandardError => e
+          GrapeOAS.logger.warn("Proc evaluation failed for #{context} (#{e.class}): #{e.message}")
+          return nil
+        end
+        return nil unless values.is_a?(Array) || values.is_a?(Range) || set_instance?(values)
+      end
+
+      values = values.to_a if set_instance?(values)
+      return nil unless values.is_a?(Array) || values.is_a?(Range)
+      return nil if values.is_a?(Array) && values.empty?
+
+      values
+    end
+
+    def self.set_instance?(value)
+      value.is_a?(Set)
+    end
+    private_class_method :set_instance?
+  end
+end

data/lib/grape_oas/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeOAS
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

data/lib/grape_oas.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "grape"
+require "logger"
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
@@ -41,6 +42,32 @@ module GrapeOAS
   end
   module_function :version
 
+  # Formatter that prepends [grape-oas] and suppresses Logger metadata.
+  # Used by the default logger and the test capture helper.
+  LOG_FORMATTER = proc { |_severity, _datetime, _progname, msg| "[grape-oas] #{msg}\n" }
+
+  # Configurable logger for schema generation warnings.
+  # Defaults to Logger on $stderr. Set to Rails.logger or Logger.new(File::NULL).
+  #
+  # @return [#warn]
+  def logger
+    @logger ||= begin
+      l = Logger.new($stderr, progname: "grape-oas", level: Logger::WARN)
+      l.formatter = LOG_FORMATTER
+      l
+    end
+  end
+
+  # @param value [#warn, nil] a logger-compatible object, or nil to reset
+  #   to the default $stderr logger
+  def logger=(value)
+    raise ArgumentError, "logger must respond to :warn (got #{value.class})" if value && !value.respond_to?(:warn)
+
+    @logger = value
+  end
+
+  module_function :logger, :logger=
+
   # Returns the global introspector registry.
   #
   # The registry manages introspectors that build schemas from various sources

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-oas
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Andrei Subbota
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-02 00:00:00.000000000 Z
+date: 2026-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -81,6 +81,7 @@ files:
 - lib/grape_oas/api_model_builders/response_parsers/documentation_responses_parser.rb
 - lib/grape_oas/api_model_builders/response_parsers/http_codes_parser.rb
 - lib/grape_oas/constants.rb
+- lib/grape_oas/doc_key_normalizer.rb
 - lib/grape_oas/documentation_extension.rb
 - lib/grape_oas/exporter.rb
 - lib/grape_oas/exporter/base/operation.rb
@@ -118,18 +119,24 @@ files:
 - lib/grape_oas/introspectors/dry_introspector_support/type_schema_builder.rb
 - lib/grape_oas/introspectors/dry_introspector_support/type_unwrapper.rb
 - lib/grape_oas/introspectors/entity_introspector.rb
+- lib/grape_oas/introspectors/entity_introspector_support.rb
 - lib/grape_oas/introspectors/entity_introspector_support/cycle_tracker.rb
 - lib/grape_oas/introspectors/entity_introspector_support/discriminator_handler.rb
 - lib/grape_oas/introspectors/entity_introspector_support/exposure_processor.rb
 - lib/grape_oas/introspectors/entity_introspector_support/inheritance_builder.rb
+- lib/grape_oas/introspectors/entity_introspector_support/nesting_merger.rb
 - lib/grape_oas/introspectors/entity_introspector_support/property_extractor.rb
+- lib/grape_oas/introspectors/entity_introspector_support/type_schema_resolver.rb
 - lib/grape_oas/introspectors/registry.rb
 - lib/grape_oas/rake/oas_tasks.rb
+- lib/grape_oas/range_utils.rb
+- lib/grape_oas/schema_constraints.rb
 - lib/grape_oas/type_resolvers/array_resolver.rb
 - lib/grape_oas/type_resolvers/base.rb
 - lib/grape_oas/type_resolvers/dry_type_resolver.rb
 - lib/grape_oas/type_resolvers/primitive_resolver.rb
 - lib/grape_oas/type_resolvers/registry.rb
+- lib/grape_oas/values_normalizer.rb
 - lib/grape_oas/version.rb
 homepage: https://github.com/numbata/grape-oas
 licenses: