apiwork 0.6.1 → 0.7.1

data/lib/apiwork/export/apiwork_mapper.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Export
+    class ApiworkMapper
+      class << self
+        def map(export, surface)
+          new(export).map(surface)
+        end
+      end
+
+      def initialize(export)
+        @export = export
+      end
+
+      def map(surface)
+        {
+          base_path: @export.api.base_path,
+          enums: serialize_enums(surface.enums),
+          error_codes: serialize_error_codes,
+          fingerprint: @export.api.fingerprint,
+          info: serialize_info,
+          locales: @export.api.locales.map(&:to_s),
+          resources: serialize_resources(@export.api.resources),
+          types: serialize_types(surface.types),
+        }
+      end
+
+      private
+
+      def serialize_enums(enums)
+        enums.map do |name, enum|
+          {
+            deprecated: enum.deprecated?,
+            description: enum.description,
+            example: enum.example,
+            name: name.to_s,
+            scope: enum.scope,
+            values: enum.values,
+          }
+        end
+      end
+
+      def serialize_error_codes
+        @export.api.error_codes.map do |name, error_code|
+          {
+            description: error_code.description,
+            name: name.to_s,
+            status: error_code.status,
+          }
+        end
+      end
+
+      def serialize_info
+        info = @export.api.info
+        return unless info
+
+        {
+          contact: info.contact && {
+            email: info.contact.email,
+            name: info.contact.name,
+            url: info.contact.url,
+          },
+          description: info.description,
+          license: info.license && {
+            name: info.license.name,
+            url: info.license.url,
+          },
+          servers: info.servers.map do |server|
+            { description: server.description, url: server.url }
+          end,
+          summary: info.summary,
+          terms_of_service: info.terms_of_service,
+          title: info.title,
+          version: info.version,
+        }
+      end
+
+      def serialize_types(types)
+        type_hashes = types.transform_values(&:to_h)
+        sorted = TypeAnalysis.topological_sort_types(type_hashes)
+        recursive = TypeAnalysis.cycle_breaking_types(type_hashes)
+
+        sorted.map { |name, _| serialize_type(name, types[name], recursive: recursive.include?(name)) }
+      end
+
+      def serialize_type(name, type, recursive:)
+        result = {
+          recursive:,
+          deprecated: type.deprecated?,
+          description: type.description,
+          example: type.example,
+          name: name.to_s,
+          scope: type.scope,
+          type: type.type.to_s,
+        }
+
+        if type.object?
+          result[:extends] = type.extends.map(&:to_s)
+          result[:shape] = serialize_shape(type.shape)
+        else
+          result[:discriminator] = transform_key(type.discriminator)
+          result[:variants] = type.variants.map do |variant|
+            serialized = serialize_param(variant)
+            serialized[:tag] = variant.tag if variant.respond_to?(:tag) && variant.tag
+            serialized
+          end
+        end
+
+        result
+      end
+
+      def serialize_resources(resources, prefix: nil)
+        resources.map do |name, resource|
+          qualified_name = prefix ? "#{prefix}.#{name}" : name.to_s
+
+          {
+            actions: resource.actions.map do |action_name, action|
+              serialize_action(action, name: "#{qualified_name}.#{action_name}")
+            end,
+            identifier: resource.identifier.to_s,
+            name: name.to_s,
+            parent_identifiers: resource.parent_identifiers.map(&:to_s),
+            path: transform_path(resource.path),
+            resources: serialize_resources(resource.resources, prefix: qualified_name),
+            scope: resource.scope,
+          }
+        end
+      end
+
+      def serialize_action(action, name:)
+        {
+          name:,
+          deprecated: action.deprecated?,
+          description: action.description,
+          method: action.method.to_s,
+          operation_id: action.operation_id,
+          path: transform_path(action.path),
+          raises: action.raises.map(&:to_s),
+          request: {
+            body: serialize_shape(action.request.body),
+            description: action.request.description,
+            query: serialize_shape(action.request.query),
+          },
+          response: {
+            body: serialize_response_body(action.response),
+            description: action.response.description,
+            no_content: action.response.no_content?,
+          },
+          summary: action.summary,
+          tags: action.tags,
+        }
+      end
+
+      def serialize_response_body(response)
+        return unless response.body?
+
+        serialize_param(response.body)
+      end
+
+      def serialize_shape(params)
+        params.sort_by { |name, _| name.to_s }.map do |name, param|
+          { name: transform_key(name) }.merge(serialize_param(param))
+        end
+      end
+
+      def serialize_param(param)
+        result = {
+          deprecated: param.deprecated?,
+          description: param.description,
+          nullable: param.nullable?,
+          optional: param.optional?,
+          type: param.type.to_s,
+        }
+
+        case param.type
+        when :string, :integer
+          result[:default] = param.default if param.default?
+          result[:enum] = param.enum.to_s if param.enum?
+          result[:example] = param.example
+          result[:format] = param.format
+          result[:max] = param.max
+          result[:min] = param.min
+        when :number, :decimal
+          result[:default] = param.default if param.default?
+          result[:enum] = param.enum.to_s if param.enum?
+          result[:example] = param.example
+          result[:max] = param.max
+          result[:min] = param.min
+        when :boolean, :date, :datetime, :time, :uuid, :binary
+          result[:default] = param.default if param.default?
+          result[:enum] = param.enum.to_s if param.enum?
+          result[:example] = param.example
+        when :literal
+          result[:value] = param.value
+        when :array
+          result[:default] = param.default if param.default?
+          result[:example] = param.example
+          result[:max] = param.max
+          result[:min] = param.min
+          result[:of] = param.of ? serialize_param(param.of) : nil
+        when :record
+          result[:default] = param.default if param.default?
+          result[:example] = param.example
+          result[:of] = param.of ? serialize_param(param.of) : nil
+        when :object
+          result[:partial] = param.partial?
+          result[:shape] = serialize_shape(param.shape)
+        when :union
+          result[:discriminator] = transform_key(param.discriminator)
+          result[:variants] = param.variants.map do |variant|
+            serialized = serialize_param(variant)
+            serialized[:tag] = variant.tag if variant.respond_to?(:tag) && variant.tag
+            serialized
+          end
+        when :reference
+          result[:reference] = param.reference.to_s
+        end
+
+        result
+      end
+
+      def transform_path(path)
+        path.to_s.gsub(/:(\w+)/) { ":#{transform_key(::Regexp.last_match(1))}" }
+      end
+
+      def transform_key(key)
+        @export.transform_key(key)
+      end
+    end
+  end
+end

data/lib/apiwork/export/open_api.rb

@@ -324,6 +324,8 @@ module Apiwork
 
         schema[:format] = param.format.to_s if param.formattable? && param.format
 
+        schema[:default] = param.default if param.respond_to?(:default) && param.default?
+
         apply_nullable(schema, param.nullable?)
       end
 

data/lib/apiwork/export/registry.rb

@@ -2,7 +2,7 @@
 
 module Apiwork
   module Export
-    class Registry < Apiwork::Registry
+    class Registry < ::Apiwork::Registry
       class << self
         def register(export_class)
           raise ArgumentError, 'Export must inherit from Apiwork::Export::Base' unless export_class < Base

data/lib/apiwork/export/sorbus.rb

@@ -7,12 +7,8 @@ module Apiwork
       output :string
       file_extension '.ts'
 
-      option :builders, default: false, type: :boolean
-
       def generate
-        output = SorbusMapper.map(self, surface)
-        output += "\n\n#{BuilderMapper.map(self, surface)}" if options[:builders]
-        output
+        SorbusMapper.map(self, surface)
       end
 
       private

data/lib/apiwork/export/type_script.rb

@@ -7,13 +7,10 @@ module Apiwork
       output :string
       file_extension '.ts'
 
-      option :builders, default: false, type: :boolean
       option :version, default: '5', enum: %w[4 5], type: :string
 
       def generate
-        output = TypeScriptMapper.map(self, surface)
-        output += "\n\n#{BuilderMapper.map(self, surface)}" if options[:builders]
-        output
+        TypeScriptMapper.map(self, surface)
       end
 
       private

data/lib/apiwork/export/type_script_mapper.rb

@@ -28,7 +28,7 @@ module Apiwork
         properties = type.shape.sort_by { |name, _param| name.to_s }.map do |name, param|
           key = @export.transform_key(name)
           ts_type = map_field(param)
-          optional_marker = param.optional? ? '?' : ''
+          optional_marker = optional_in_output?(param) ? '?' : ''
 
           prop_jsdoc = jsdoc(description: param.description, example: param.concrete? ? param.example : nil)
           if prop_jsdoc
@@ -85,7 +85,7 @@ module Apiwork
         properties = query_params.sort_by { |name, _param| name.to_s }.map do |param_name, param|
           key = @export.transform_key(param_name)
           ts_type = map_field(param)
-          optional_marker = param.optional? ? '?' : ''
+          optional_marker = optional_in_output?(param) ? '?' : ''
           "  #{key}#{optional_marker}: #{ts_type};"
         end.join("\n")
 
@@ -96,7 +96,7 @@ module Apiwork
         properties = body_params.sort_by { |name, _param| name.to_s }.map do |param_name, param|
           key = @export.transform_key(param_name)
           ts_type = map_field(param)
-          optional_marker = param.optional? ? '?' : ''
+          optional_marker = optional_in_output?(param) ? '?' : ''
           "  #{key}#{optional_marker}: #{ts_type};"
         end.join("\n")
 
@@ -186,7 +186,7 @@ module Apiwork
         properties = param.shape.sort_by { |name, _field| name.to_s }.map do |name, field|
           key = @export.transform_key(name)
           ts_type = map_field(field)
-          optional_marker = partial || field.optional? ? '?' : ''
+          optional_marker = partial || optional_in_output?(field) ? '?' : ''
           "#{key}#{optional_marker}: #{ts_type}"
         end.join('; ')
 
@@ -252,6 +252,14 @@ module Apiwork
         'unknown'
       end
 
+      def optional_in_output?(param)
+        return false unless param.optional?
+        return false if param.respond_to?(:default) && param.default?
+        return false if param.nullable?
+
+        true
+      end
+
       def type_reference(symbol)
         pascal_case(symbol)
       end

data/lib/apiwork/export/zod.rb

@@ -7,7 +7,6 @@ module Apiwork
       output :string
       file_extension '.ts'
 
-      option :builders, default: false, type: :boolean
       option :version, default: '4', enum: %w[4], type: :string
 
       def generate
@@ -27,14 +26,6 @@ module Apiwork
           parts << ''
         end
 
-        if options[:builders]
-          builder_output = BuilderMapper.map(self, surface)
-          if builder_output.present?
-            parts << builder_output
-            parts << ''
-          end
-        end
-
         parts.join("\n")
       end
 

data/lib/apiwork/export/zod_mapper.rb

@@ -458,10 +458,31 @@ module Apiwork
 
       def apply_modifiers(type, param, force_optional: nil)
         type += '.nullable()' if param.nullable?
+
+        has_default = param.respond_to?(:default) && param.default?
         optional = force_optional.nil? ? param.optional? : force_optional
-        type += '.optional()' if optional
+
+        if has_default
+          type += ".default(#{serialize_default(param.default)})"
+        elsif optional
+          type += '.optional()'
+        end
+
         type
       end
+
+      def serialize_default(value)
+        case value
+        when String then "'#{value.gsub("'", "\\\\'")}'"
+        when Integer, Float then value.to_s
+        when BigDecimal then value.to_s('F')
+        when TrueClass, FalseClass then value.to_s
+        when Array then '[]'
+        when Hash then '{}'
+        when NilClass then 'null'
+        else value.to_s
+        end
+      end
     end
   end
 end

data/lib/apiwork/export.rb

@@ -71,6 +71,7 @@ module Apiwork
       end
 
       def register_defaults!
+        register(Apiwork)
         register(OpenAPI)
         register(TypeScript)
         register(Zod)

data/lib/apiwork/introspection/api/resource.rb

@@ -23,6 +23,14 @@ module Apiwork
           @dump = dump
         end
 
+        # @api public
+        # The scope for this resource.
+        #
+        # @return [String, nil]
+        def scope
+          @dump[:scope]
+        end
+
         # @api public
         # The identifier for this resource.
         #
@@ -75,6 +83,7 @@ module Apiwork
             parent_identifiers: parent_identifiers,
             path: path,
             resources: resources.transform_values(&:to_h),
+            scope: scope,
           }
         end
       end

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

@@ -33,10 +33,9 @@ module Apiwork
 
           reference = resolve_type_reference(options[:type])
 
-          {
+          result = {
             reference:,
             as: options[:as],
-            default: options[:default],
             deprecated: options[:deprecated] == true,
             description: resolve_attribute_description(options),
             discriminator: nil,
@@ -55,14 +54,15 @@ module Apiwork
             value: options[:type] == :literal ? options[:value] : nil,
             variants: [],
           }
+          result[:default] = options[:default] if options.key?(:default)
+          result
         end
 
         def build_union_param(options)
           union_dump = build_union(options[:union])
 
-          {
+          result = {
             as: options[:as],
-            default: options[:default],
             deprecated: options[:deprecated] == true,
             description: resolve_attribute_description(options),
             discriminator: union_dump[:discriminator],
@@ -82,15 +82,16 @@ module Apiwork
             value: nil,
             variants: union_dump[:variants],
           }
+          result[:default] = options[:default] if options.key?(:default)
+          result
         end
 
         def build_custom_type_param(options)
           custom_type_name = options[:custom_type]
           custom_type_name = qualified_name(custom_type_name, @contract_param) if @contract_param.contract_class.resolve_custom_type(custom_type_name)
 
-          {
+          result = {
             as: options[:as],
-            default: options[:default],
             deprecated: options[:deprecated] == true,
             description: resolve_attribute_description(options),
             discriminator: nil,
@@ -110,6 +111,8 @@ module Apiwork
             value: nil,
             variants: [],
           }
+          result[:default] = options[:default] if options.key?(:default)
+          result
         end
 
         def resolve_type_reference(type_value)
@@ -163,7 +166,6 @@ module Apiwork
           result = {
             reference:,
             as: nil,
-            default: nil,
             deprecated: false,
             description: nil,
             discriminator: nil,
@@ -205,7 +207,6 @@ module Apiwork
           {
             reference:,
             as: nil,
-            default: nil,
             deprecated: false,
             description: nil,
             discriminator: nil,
@@ -312,7 +313,6 @@ module Apiwork
 
           result = {
             as: nil,
-            default: nil,
             deprecated: false,
             description: nil,
             discriminator: union ? of.discriminator : nil,
@@ -343,7 +343,6 @@ module Apiwork
         def build_api_variant(variant)
           {
             as: nil,
-            default: nil,
             deprecated: false,
             description: nil,
             discriminator: nil,

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

@@ -19,13 +19,15 @@ module Apiwork
           )
 
           resource_path = build_resource_path(formatted_segment)
+          contract_class = resolve_contract_class
 
           {
-            actions: build_actions(resolve_contract_class, resource_path),
+            actions: build_actions(contract_class, resource_path),
             identifier: @resource.name.to_s,
             parent_identifiers: @parent_identifiers,
             path: resource_path,
             resources: build_nested_resources(resource_path),
+            scope: contract_class&.scope_prefix&.to_s,
           }
         end
 

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

@@ -39,8 +39,11 @@ module Apiwork
         end
 
         def build_type(qualified_name, type_definition)
+          scope = resolve_scope(type_definition.scope)
+
           if type_definition.union?
             {
+              scope:,
               deprecated: type_definition.deprecated?,
               description: resolve_type_description(qualified_name, type_definition),
               discriminator: type_definition.discriminator,
@@ -52,6 +55,7 @@ module Apiwork
             }
           else
             {
+              scope:,
               deprecated: type_definition.deprecated?,
               description: resolve_type_description(qualified_name, type_definition),
               discriminator: nil,
@@ -110,10 +114,9 @@ module Apiwork
                         resolve_type_reference(options[:type], scope)
                       end
 
-          {
+          result = {
             reference:,
             as: options[:as],
-            default: options[:default],
             deprecated: options[:deprecated] == true,
             description: resolve_param_description(name, options, scope),
             discriminator: nil,
@@ -132,6 +135,8 @@ module Apiwork
             value: options[:type] == :literal ? options[:value] : nil,
             variants: build_nested_variants(options[:shape]),
           }
+          result[:default] = options[:default] if options.key?(:default)
+          result
         end
 
         def build_variant(variant, scope)
@@ -141,7 +146,6 @@ module Apiwork
           {
             reference:,
             as: nil,
-            default: nil,
             deprecated: false,
             description: nil,
             discriminator: nil,
@@ -217,7 +221,6 @@ module Apiwork
 
           result = {
             as: nil,
-            default: nil,
             deprecated: false,
             description: nil,
             discriminator: union ? of.discriminator : nil,
@@ -260,12 +263,20 @@ module Apiwork
             deprecated: enum_definition.deprecated?,
             description: resolve_enum_description(qualified_name, enum_definition),
             example: enum_definition.example,
+            scope: resolve_scope(enum_definition.scope),
             values: enum_definition.values || [],
           }
         end
 
         private
 
+        def resolve_scope(scope)
+          return nil unless scope
+          return nil unless scope.respond_to?(:scope_prefix)
+
+          scope.scope_prefix.to_s
+        end
+
         def resolve_param_description(name, options, scope)
           return options[:description] if options[:description]
           return nil unless scope

data/lib/apiwork/introspection/enum.rb

@@ -38,6 +38,14 @@ module Apiwork
         @dump[:example]
       end
 
+      # @api public
+      # The scope for this enum.
+      #
+      # @return [String, nil]
+      def scope
+        @dump[:scope]
+      end
+
       # @api public
       # Whether this enum is deprecated.
       #
@@ -55,6 +63,7 @@ module Apiwork
           deprecated: deprecated?,
           description: description,
           example: example,
+          scope: scope,
           values: values,
         }
       end

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

@@ -23,6 +23,9 @@ module Apiwork
         # @api public
         # The default for this param.
         #
+        # Returns `nil` for both "no default" and "default is explicitly `nil`".
+        # Use {#default?} to distinguish these cases.
+        #
         # @return [Object, nil]
         def default
           @dump[:default]

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

@@ -48,6 +48,17 @@ module Apiwork
           @dump[:description]
         end
 
+        # @api public
+        # Whether this param has a default value.
+        #
+        # Use this to distinguish "no default" from "default is explicitly `nil`".
+        # The {#default} accessor returns `nil` in both cases.
+        #
+        # @return [Boolean]
+        def default?
+          @dump.key?(:default)
+        end
+
         # @api public
         # The tag for this param.
         #

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

@@ -23,6 +23,9 @@ module Apiwork
         # @api public
         # The default for this param.
         #
+        # Returns `nil` for both "no default" and "default is explicitly `nil`".
+        # Use {#default?} to distinguish these cases.
+        #
         # @return [Object, nil]
         def default
           @dump[:default]

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

@@ -23,6 +23,9 @@ module Apiwork
         # @api public
         # The default for this param.
         #
+        # Returns `nil` for both "no default" and "default is explicitly `nil`".
+        # Use {#default?} to distinguish these cases.
+        #
         # @return [Object, nil]
         def default
           @dump[:default]

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

@@ -23,6 +23,9 @@ module Apiwork
         # @api public
         # The default for this param.
         #
+        # Returns `nil` for both "no default" and "default is explicitly `nil`".
+        # Use {#default?} to distinguish these cases.
+        #
         # @return [Object, nil]
         def default
           @dump[:default]