apiwork 0.0.0.pre → 0.1.2

data/lib/apiwork/introspection/dump/type.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    module Dump
+      class Type
+        def initialize(api_class)
+          @api_class = api_class
+        end
+
+        def to_h
+          {
+            enums: enums,
+            types: types,
+          }
+        end
+
+        def types
+          @api_class.type_registry.each_pair
+            .reject { |_, type_definition| type_definition.fragment? }
+            .sort_by do |name, _type_definition|
+              name.to_s
+          end.each_with_object({}) do |(qualified_name, type_definition), result|
+            result[qualified_name] = build_type(qualified_name, type_definition)
+          end
+        end
+
+        def enums
+          @api_class.enum_registry.each_pair.sort_by do |name, _enum_definition|
+            name.to_s
+          end.each_with_object({}) do |(qualified_name, enum_definition), result|
+            result[qualified_name] = build_enum(qualified_name, enum_definition)
+          end
+        end
+
+        def build_type(qualified_name, type_definition)
+          if type_definition.union?
+            {
+              deprecated: type_definition.deprecated?,
+              description: resolve_type_description(qualified_name, type_definition),
+              discriminator: type_definition.discriminator,
+              example: type_definition.example,
+              extends: [],
+              shape: {},
+              type: :union,
+              variants: build_variants(type_definition),
+            }
+          else
+            {
+              deprecated: type_definition.deprecated?,
+              description: resolve_type_description(qualified_name, type_definition),
+              discriminator: nil,
+              example: type_definition.example,
+              extends: resolve_extends(type_definition.shape.extends, type_definition.scope),
+              shape: build_params(type_definition),
+              type: :object,
+              variants: [],
+            }
+          end
+        end
+
+        def resolve_extends(extends, scope)
+          extends.map { |name| resolve_scoped_type_name(name, scope) || name }
+        end
+
+        def build_params(type_definition)
+          return {} unless type_definition.params
+
+          result = {}
+
+          expand_merged_types(type_definition, result)
+
+          type_definition.params.sort_by { |name, _| name.to_s }.each do |name, param_options|
+            result[name] = build_param(name, param_options, type_definition.scope)
+          end
+          result
+        end
+
+        def expand_merged_types(type_definition, result)
+          return unless type_definition.shape.respond_to?(:merged)
+
+          type_definition.shape.merged.each do |merged_name|
+            resolved_name = resolve_scoped_type_name(merged_name, type_definition.scope) || merged_name
+            merged_type = @api_class.type_registry[resolved_name]
+            next unless merged_type&.params
+
+            merged_type.params.each do |name, param_options|
+              result[name] = build_param(name, param_options, type_definition.scope)
+            end
+          end
+        end
+
+        def build_variants(type_definition)
+          return [] unless type_definition.variants
+
+          type_definition.variants.map do |variant|
+            build_variant(variant, type_definition.scope)
+          end
+        end
+
+        def build_param(name, options, scope)
+          reference = resolve_type_reference(options[:type], scope)
+
+          {
+            reference:,
+            as: options[:as],
+            default: options[:default],
+            deprecated: options[:deprecated] == true,
+            description: resolve_param_description(name, options, scope),
+            discriminator: nil,
+            enum: resolve_enum(options, scope),
+            example: options[:example],
+            format: options[:format],
+            max: options[:max],
+            min: options[:min],
+            nullable: options[:nullable] == true,
+            of: resolve_of(options, scope),
+            optional: options[:optional] == true,
+            partial: options[:partial] == true,
+            shape: resolve_param_shape(options),
+            tag: nil,
+            type: reference ? :reference : (options[:type] || :unknown),
+            value: options[:type] == :literal ? options[:value] : nil,
+            variants: build_nested_variants(options[:shape]),
+          }
+        end
+
+        def build_variant(variant, scope)
+          reference = resolve_type_reference(variant[:custom_type] || variant[:type], scope)
+          resolved_type = reference ? :reference : (variant[:type] || :unknown)
+
+          {
+            reference:,
+            as: nil,
+            default: nil,
+            deprecated: false,
+            description: nil,
+            discriminator: nil,
+            enum: resolve_variant_enum(variant, scope),
+            example: nil,
+            format: nil,
+            max: nil,
+            min: nil,
+            nullable: false,
+            of: resolve_variant_of(variant, scope),
+            optional: false,
+            partial: variant[:partial] == true,
+            shape: build_nested_shape(variant[:shape]),
+            tag: variant[:tag],
+            type: resolved_type,
+            value: variant[:value],
+            variants: [],
+          }
+        end
+
+        def build_nested_shape(shape)
+          return {} unless shape
+          return {} unless shape.respond_to?(:params)
+
+          result = {}
+          shape.params.sort_by { |name, _| name.to_s }.each do |name, param_options|
+            result[name] = build_param(name, param_options, nil)
+          end
+          result
+        end
+
+        def build_nested_variants(shape)
+          return [] unless shape
+          return [] unless shape.respond_to?(:variants)
+
+          shape.variants.map { |variant| build_variant(variant, nil) }
+        end
+
+        def resolve_param_shape(options)
+          return build_nested_shape(options[:shape]) if options[:shape]
+
+          of = options[:of]
+          return {} unless of
+          return {} unless of.respond_to?(:shape)
+
+          of.shape ? build_nested_shape(of.shape) : {}
+        end
+
+        def resolve_type_reference(type_value, scope)
+          return nil unless type_value
+
+          resolve_scoped_type_name(type_value, scope)
+        end
+
+        def resolve_enum(options, scope)
+          return nil unless options[:enum]
+
+          if options[:enum].is_a?(Symbol)
+            @api_class.scoped_enum_name(scope, options[:enum])
+          else
+            options[:enum]
+          end
+        end
+
+        def resolve_of(options, scope)
+          of = options[:of]
+          return nil unless of
+
+          type_value = of.type
+          scoped_name = resolve_scoped_type_name(type_value, scope)
+          resolved_shape = of.shape ? build_nested_shape(of.shape) : {}
+
+          result = {
+            enum: of.enum,
+            format: of.format,
+            max: of.max,
+            min: of.min,
+            reference: scoped_name,
+            shape: resolved_shape,
+            type: scoped_name ? :reference : type_value,
+          }
+          result[:of] = resolve_of({ of: of.inner }, scope) if of.type == :array && of.inner
+          result
+        end
+
+        def resolve_variant_enum(variant, scope)
+          return nil unless variant[:enum]
+
+          if variant[:enum].is_a?(Symbol)
+            @api_class.scoped_enum_name(scope, variant[:enum])
+          else
+            variant[:enum]
+          end
+        end
+
+        def resolve_variant_of(variant, scope)
+          of = variant[:of]
+          return nil unless of
+
+          type_value = of.type
+          scoped_name = resolve_scoped_type_name(type_value, scope)
+          resolved_shape = of.shape ? build_nested_shape(of.shape) : {}
+
+          result = {
+            enum: of.enum,
+            format: of.format,
+            max: of.max,
+            min: of.min,
+            reference: scoped_name,
+            shape: resolved_shape,
+            type: scoped_name ? :reference : type_value,
+          }
+          result[:of] = resolve_variant_of({ of: of.inner }, scope) if of.type == :array && of.inner
+          result
+        end
+
+        def build_enum(qualified_name, enum_definition)
+          {
+            deprecated: enum_definition.deprecated?,
+            description: resolve_enum_description(qualified_name, enum_definition),
+            example: enum_definition.example,
+            values: enum_definition.values || [],
+          }
+        end
+
+        private
+
+        def resolve_param_description(name, options, scope)
+          return options[:description] if options[:description]
+          return nil unless scope
+          return nil unless scope.respond_to?(:representation_class)
+
+          representation_class = scope.representation_class
+          return nil unless representation_class
+
+          if (attribute = representation_class.attributes[name])
+            description = i18n_attribute_description(attribute)
+            return description if description
+          end
+
+          if (association = representation_class.associations[name])
+            description = i18n_association_description(association)
+            return description if description
+          end
+
+          nil
+        end
+
+        def i18n_attribute_description(attribute)
+          representation_name = attribute.representation_class_name
+          attribute_name = attribute.name
+
+          @api_class.translate(:representations, representation_name, :attributes, attribute_name, :description)
+        end
+
+        def i18n_association_description(association)
+          representation_name = association.representation_class_name
+          association_name = association.name
+
+          @api_class.translate(:representations, representation_name, :associations, association_name, :description)
+        end
+
+        def resolve_type_description(type_name, type_definition)
+          return type_definition.description if type_definition.description
+
+          result = @api_class.translate(:types, type_name, :description)
+          return result if result
+
+          I18n.translate(:"apiwork.types.#{type_name}.description", default: nil)
+        end
+
+        def resolve_enum_description(enum_name, enum_definition)
+          return enum_definition.description if enum_definition.description
+
+          result = @api_class.translate(:enums, enum_name, :description)
+          return result if result
+
+          I18n.translate(:"apiwork.enums.#{enum_name}.description", default: nil)
+        end
+
+        def resolve_scoped_type_name(type_name, scope)
+          return nil unless type_name.is_a?(Symbol)
+          return nil unless @api_class
+
+          return type_name if @api_class.type_registry.key?(type_name) || @api_class.enum_registry.key?(type_name)
+
+          return nil unless scope
+
+          scoped_name = @api_class.scoped_type_name(scope, type_name)
+          return scoped_name if @api_class.type_registry.key?(scoped_name) || @api_class.enum_registry.key?(scoped_name)
+
+          nil
+        end
+
+        def registered_type?(type_name)
+          return false unless type_name.is_a?(Symbol)
+          return false unless @api_class
+
+          @api_class.type_registry.key?(type_name) || @api_class.enum_registry.key?(type_name)
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/dump.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    module Dump
+      class << self
+        def api(api_class)
+          API.new(api_class).to_h
+        end
+
+        def contract(contract_class, expand: false)
+          Contract.new(contract_class, expand:).to_h
+        end
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/enum.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    # @api public
+    # Wraps enum type definitions.
+    #
+    # @example
+    #   api.enums[:status].values # => ["draft", "published", "archived"]
+    #   api.enums[:status].description # => "Document status"
+    #   api.enums[:status].deprecated? # => false
+    class Enum
+      def initialize(dump)
+        @dump = dump
+      end
+
+      # @api public
+      # The values for this enum.
+      #
+      # @return [Array<String>]
+      def values
+        @dump[:values]
+      end
+
+      # @api public
+      # The description for this enum.
+      #
+      # @return [String, nil]
+      def description
+        @dump[:description]
+      end
+
+      # @api public
+      # The example for this enum.
+      #
+      # @return [String, nil]
+      def example
+        @dump[:example]
+      end
+
+      # @api public
+      # Whether this enum is deprecated.
+      #
+      # @return [Boolean]
+      def deprecated?
+        @dump[:deprecated]
+      end
+
+      # @api public
+      # Converts this enum to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          deprecated: deprecated?,
+          description: description,
+          example: example,
+          values: values,
+        }
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/error_code.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    # @api public
+    # Wraps error code definitions.
+    #
+    # @example
+    #   api.error_codes[:not_found].status # => 404
+    #   api.error_codes[:not_found].description # => "Resource not found"
+    class ErrorCode
+      def initialize(dump)
+        @dump = dump
+      end
+
+      # @api public
+      # The description for this error code.
+      #
+      # @return [String, nil]
+      def description
+        @dump[:description]
+      end
+
+      # @api public
+      # The status for this error code.
+      #
+      # @return [Integer]
+      def status
+        @dump[:status]
+      end
+
+      # @api public
+      # Converts this error code to a hash.
+      #
+      # @return [Hash]
+      def to_h
+        {
+          description: description,
+          status: status,
+        }
+      end
+    end
+  end
+end

data/lib/apiwork/introspection/param/array.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    module Param
+      # @api public
+      # Array param representing ordered collections.
+      #
+      # @example Basic usage
+      #   param.type # => :array
+      #   param.array? # => true
+      #   param.scalar? # => false
+      #
+      # @example Element type
+      #   param.of # => Param (element type) or nil
+      #   param.shape # => {} or { field: Param, ... }
+      #
+      # @example Constraints
+      #   param.min # => 1 or nil
+      #   param.max # => 10 or nil
+      #   param.boundable? # => true
+      class Array < Base
+        # @api public
+        # The of for this param.
+        #
+        # @return [Param::Base, nil]
+        def of
+          @of ||= @dump[:of] ? Param.build(@dump[:of]) : nil
+        end
+
+        # @api public
+        # The shape for this param.
+        #
+        # @return [Hash{Symbol => Param::Base}]
+        def shape
+          return @shape if defined?(@shape)
+
+          @shape = @dump[:shape]&.transform_values { |dump| Param.build(dump) } || {}
+        end
+
+        # @api public
+        # The minimum for this param.
+        #
+        # @return [Integer, nil]
+        def min
+          @dump[:min]
+        end
+
+        # @api public
+        # The maximum for this param.
+        #
+        # @return [Integer, nil]
+        def max
+          @dump[:max]
+        end
+
+        # @api public
+        # Whether this param is an array.
+        #
+        # @return [Boolean]
+        def array?
+          true
+        end
+
+        # @api public
+        # Whether this param is boundable.
+        #
+        # @return [Boolean]
+        def boundable?
+          true
+        end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:max] = max
+          result[:min] = min
+          result[:of] = of&.to_h
+          result[:shape] = shape.transform_values(&:to_h)
+          result
+        end
+      end
+    end
+  end
+end