apiwork 0.6.1 → 0.7.1

data/lib/apiwork/reference_generator.rb

@@ -47,6 +47,26 @@ module Apiwork
         .sort_by { |mod| mod[:path] }
     end
 
+    def extract_constants
+      YARD::Registry.all(:constant)
+        .select do |yard_object|
+          yard_object.path.start_with?('Apiwork') &&
+            yard_object.docstring.to_s.strip.present? &&
+            yard_object.docstring.tags(:api).any? { |tag| tag.text == 'public' }
+        end
+        .map { |yard_object| serialize_constant(yard_object) }
+        .sort_by { |constant| constant[:name] }
+    end
+
+    def serialize_constant(yard_object)
+      {
+        docstring: yard_object.docstring.to_s,
+        file: relative_path(yard_object.file),
+        line: yard_object.line,
+        name: yard_object.name.to_s,
+      }
+    end
+
     def public_api?(yard_object)
       api_tag = yard_object.docstring.tags(:api).find { |tag| tag.text == 'public' }
 
@@ -247,6 +267,29 @@ module Apiwork
       end
 
       write_namespace_indexes
+      write_constant_files(extract_constants)
+    end
+
+    def write_constant_files(constants)
+      constants.each.with_index(@modules.size + 1) do |constant, order|
+        filepath = File.join(OUTPUT_DIR, "#{dasherize(constant[:name])}.md")
+        File.write(filepath, render_constant(constant, order))
+      end
+    end
+
+    def render_constant(constant, order)
+      parts = []
+      parts << "---\norder: #{order}\nprev: false\nnext: false\n---\n"
+      parts << "# #{constant[:name]}\n"
+
+      if constant[:file] && constant[:line]
+        github_link = "#{GITHUB_URL}/#{constant[:file]}#L#{constant[:line]}"
+        parts << "[GitHub](#{github_link})\n"
+      end
+
+      parts << "#{linkify_yard_refs(constant[:docstring])}\n" if constant[:docstring].present?
+
+      parts.join("\n")
     end
 
     def write_root_index

data/lib/apiwork/representation/attribute.rb

@@ -21,6 +21,14 @@ module Apiwork
         string: %i[date datetime email hostname ipv4 ipv6 password text url uuid],
       }.freeze
 
+      # @!attribute [r] default
+      #   @api public
+      #   The default for this attribute.
+      #
+      #   Returns `nil` for both "no default" and "default is explicitly `nil`".
+      #   Use {#default?} to distinguish these cases.
+      #
+      #   @return [Object, nil]
       # @!attribute [r] description
       #   @api public
       #   The description for this attribute.
@@ -71,7 +79,8 @@ module Apiwork
       #   The type for this attribute.
       #
       #   @return [Symbol]
-      attr_reader :description,
+      attr_reader :default,
+                  :description,
                   :element,
                   :empty,
                   :enum,
@@ -90,6 +99,7 @@ module Apiwork
         name,
         owner_representation_class,
         decode: nil,
+        default: UNSET,
         deprecated: false,
         description: nil,
         empty: false,
@@ -134,6 +144,24 @@ module Apiwork
             type = :string if detected_enum && type == :integer
             optional = detect_optional(name) if optional.nil?
             nullable = detect_nullable(name) if nullable.nil?
+            default = detect_default(name, empty:, nullable:, optional:) if UNSET.equal?(default)
+
+            if @db_column && type == :string
+              detected_max = detect_string_max_length(name)
+              max = [max, detected_max].compact.min
+            end
+
+            if @db_column && type == :decimal
+              detected_min, detected_max = detect_decimal_bounds(name)
+              min = [min, detected_min].compact.max
+              max = [max, detected_max].compact.min
+            end
+
+            if @db_column && type == :integer
+              detected_min, detected_max = detect_integer_bounds(name)
+              min = [min, detected_min].compact.max
+              max = [max, detected_max].compact.min
+            end
           rescue ActiveRecord::StatementInvalid, ActiveRecord::NoDatabaseError, ActiveRecord::ConnectionNotEstablished
             @db_column = false
           end
@@ -141,6 +169,7 @@ module Apiwork
 
         optional = false if optional.nil?
         nullable = false if nullable.nil?
+        default = '' if UNSET.equal?(default) && empty
 
         @filterable = filterable
         @preload = preload
@@ -160,12 +189,25 @@ module Apiwork
         @format = format
         @deprecated = deprecated
         @write_only = write_only
+        @default_set = !UNSET.equal?(default)
+        @default = @default_set ? default : nil
 
         validate_min_max_range!
         validate_format!
         validate_empty!
       end
 
+      # @api public
+      # Whether this attribute 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?
+        @default_set
+      end
+
       # @api public
       # Whether this attribute is deprecated.
       #
@@ -276,6 +318,32 @@ module Apiwork
         end
       end
 
+      def detect_string_max_length(name)
+        column = column_for(name)
+        return nil unless column
+
+        column.limit
+      end
+
+      def detect_decimal_bounds(name)
+        column = column_for(name)
+        return [nil, nil] unless column
+        return [nil, nil] unless column.precision
+
+        scale = column.scale || 0
+        max = (10**(column.precision - scale) - 10.0**(-scale)).to_f
+        [-max, max]
+      end
+
+      def detect_integer_bounds(name)
+        column = column_for(name)
+        return [nil, nil] unless column
+
+        limit = column.limit || 4
+        max = 2**(8 * limit - 1) - 1
+        [-max - 1, max]
+      end
+
       def detect_optional(name)
         return false unless @model_class
         return false unless db_column?
@@ -283,11 +351,28 @@ module Apiwork
         column = column_for(name)
         return false unless column
 
-        return true if column.default.present?
+        return true unless column.default.nil?
 
         column.null
       end
 
+      def detect_default(name, empty:, nullable:, optional:)
+        return UNSET unless @model_class
+        return UNSET unless db_column?
+
+        column = column_for(name)
+        return UNSET unless column
+        return UNSET if column.default_function
+
+        default = @model_class.column_defaults[name.to_s]
+        return default unless default.nil?
+
+        return '' if empty && nullable && optional
+        return nil if nullable && optional
+
+        UNSET
+      end
+
       def detect_nullable(name)
         return false unless @model_class
         return false unless db_column?

data/lib/apiwork/representation/base.rb

@@ -184,6 +184,8 @@ module Apiwork
         #   The attribute name.
         # @param decode [Proc, nil] (nil)
         #   Transform for request input (API to database). Must preserve the attribute type.
+        # @param default [Object] (UNSET)
+        #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. If omitted and name maps to a database column, auto-detected from the column's static default.
         # @param deprecated [Boolean] (false)
         #   Whether deprecated. Metadata included in exports.
         # @param description [String, nil] (nil)
@@ -273,6 +275,7 @@ module Apiwork
         def attribute(
           name,
           decode: nil,
+          default: UNSET,
           deprecated: false,
           description: nil,
           empty: nil,
@@ -297,6 +300,7 @@ module Apiwork
               name,
               self,
               decode:,
+              default:,
               deprecated:,
               description:,
               empty:,

data/lib/apiwork/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apiwork
-  VERSION = '0.6.1'
+  VERSION = '0.7.1'
 end

data/lib/apiwork.rb

@@ -4,6 +4,10 @@ require 'zeitwerk'
 require_relative 'apiwork/version'
 
 module Apiwork
+  # @api public
+  # Sentinel for an unset value. Distinguishes from explicit `nil`.
+  UNSET = Object.new.freeze
+
   class << self
     def call(env)
       routes.call(env)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.1
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,20 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
-- !ruby/object:Gem::Dependency
-  name: bundler-audit
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: lefthook
   requirement: !ruby/object:Gem::Requirement
@@ -260,8 +246,9 @@ files:
 - lib/apiwork/error_code/definition.rb
 - lib/apiwork/error_code/registry.rb
 - lib/apiwork/export.rb
+- lib/apiwork/export/apiwork.rb
+- lib/apiwork/export/apiwork_mapper.rb
 - lib/apiwork/export/base.rb
-- lib/apiwork/export/builder_mapper.rb
 - lib/apiwork/export/open_api.rb
 - lib/apiwork/export/pipeline.rb
 - lib/apiwork/export/pipeline/writer.rb

data/lib/apiwork/export/builder_mapper.rb

@@ -1,184 +0,0 @@
-# frozen_string_literal: true
-
-module Apiwork
-  module Export
-    class BuilderMapper
-      class << self
-        def map(export, surface)
-          new(export).map(surface)
-        end
-      end
-
-      def initialize(export)
-        @export = export
-      end
-
-      def map(surface)
-        build_builders(surface.types)
-      end
-
-      def build_builders(types)
-        builders = types.sort_by { |name, _type| name.to_s }.flat_map do |name, type|
-          if type.union?
-            build_union_builders(name, type, types)
-          elsif type.object?
-            [build_object_builder(name, type)]
-          end
-        end.compact
-
-        builders.join("\n\n")
-      end
-
-      private
-
-      def build_object_builder(name, type)
-        type_name = pascal_case(name)
-        defaulted, required = classify_fields(type.shape)
-
-        if defaulted.empty?
-          build_passthrough_builder(type_name)
-        elsif required.empty?
-          build_all_defaulted_builder(type_name, defaulted)
-        else
-          build_mixed_builder(type_name, defaulted, required)
-        end
-      end
-
-      def build_passthrough_builder(type_name)
-        "export function build#{type_name}(fields: #{type_name}): #{type_name} {\n" \
-          "  return fields;\n" \
-          '}'
-      end
-
-      def build_all_defaulted_builder(type_name, defaulted)
-        defaults = build_defaults_body(defaulted)
-
-        "export function build#{type_name}(fields?: Partial<#{type_name}>): #{type_name} {\n" \
-          "  return {\n" \
-          "#{defaults}\n" \
-          "    ...fields,\n" \
-          "  };\n" \
-          '}'
-      end
-
-      def build_mixed_builder(type_name, defaulted, required)
-        required_keys = required.keys.map { |name| "'#{@export.transform_key(name)}'" }.sort.join(' | ')
-        fields_type = "Pick<#{type_name}, #{required_keys}> & Partial<#{type_name}>"
-        defaults = build_defaults_body(defaulted)
-
-        "export function build#{type_name}(fields: #{fields_type}): #{type_name} {\n" \
-          "  return {\n" \
-          "#{defaults}\n" \
-          "    ...fields,\n" \
-          "  };\n" \
-          '}'
-      end
-
-      def build_defaults_body(defaulted)
-        defaulted.sort_by { |name, _param| name.to_s }.map do |name, param|
-          "    #{@export.transform_key(name)}: #{serialize_default(param)},"
-        end.join("\n")
-      end
-
-      def build_union_builders(name, type, types)
-        type_name = pascal_case(name)
-        builders = [build_passthrough_builder(type_name)]
-
-        if type.discriminator
-          type.variants.each do |variant|
-            next unless variant.tag
-            next if variant.reference? && types.key?(variant.reference)
-
-            builders << build_variant_builder(type_name, type.discriminator, variant)
-          end
-        end
-
-        builders
-      end
-
-      def build_variant_builder(type_name, discriminator, variant)
-        discriminator_key = @export.transform_key(discriminator)
-        builder_name = variant.reference? ? "build#{pascal_case(variant.reference)}" : "build#{type_name}#{pascal_case(variant.tag)}"
-        extract_type = "Extract<#{type_name}, { #{discriminator_key}: '#{variant.tag}' }>"
-
-        variant_defaults = {}
-        variant_required = {}
-
-        variant_defaults, variant_required = classify_fields(variant.shape) if variant.object? && variant.shape.any?
-
-        fields_type = build_variant_fields_type(extract_type, discriminator_key, variant_defaults, variant_required)
-
-        body_lines = ["    #{discriminator_key}: '#{variant.tag}',"]
-        variant_defaults.sort_by { |name, _param| name.to_s }.each do |name, param|
-          body_lines << "    #{@export.transform_key(name)}: #{serialize_default(param)},"
-        end
-        body_lines << '    ...fields,'
-
-        "export function #{builder_name}(fields: #{fields_type}): #{type_name} {\n" \
-          "  return {\n" \
-          "#{body_lines.join("\n")}\n" \
-          "  };\n" \
-          '}'
-      end
-
-      def build_variant_fields_type(extract_type, discriminator_key, defaulted, required)
-        omitted_type = "Omit<#{extract_type}, '#{discriminator_key}'>"
-
-        if required.empty? && defaulted.empty?
-          omitted_type
-        elsif required.empty?
-          "Partial<#{omitted_type}>"
-        else
-          required_keys = required.keys.map { |name| "'#{@export.transform_key(name)}'" }.sort.join(' | ')
-          "Pick<#{omitted_type}, #{required_keys}> & Partial<#{omitted_type}>"
-        end
-      end
-
-      def classify_fields(shape)
-        defaulted = {}
-        required = {}
-
-        shape.sort_by { |name, _param| name.to_s }.each do |name, param|
-          if defaulted_field?(param)
-            defaulted[name] = param
-          else
-            required[name] = param
-          end
-        end
-
-        [defaulted, required]
-      end
-
-      def defaulted_field?(param)
-        return true if param.nullable?
-        return true if param.respond_to?(:default) && !param.default.nil?
-
-        false
-      end
-
-      def serialize_default(param)
-        if param.respond_to?(:default) && !param.default.nil?
-          serialize_value(param.default)
-        elsif param.nullable?
-          'null'
-        end
-      end
-
-      def serialize_value(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 '{}'
-        else value.to_s
-        end
-      end
-
-      def pascal_case(name)
-        name.to_s.camelize(:upper)
-      end
-    end
-  end
-end