apiwork 0.0.0.pre → 0.1.1

data/lib/apiwork/union.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Apiwork
+  class Union
+    attr_reader :discriminator,
+                :variants
+
+    def initialize(discriminator: nil)
+      @discriminator = discriminator
+      @variants = []
+    end
+
+    # @api public
+    # Defines a union variant.
+    #
+    # @param deprecated [Boolean] (false)
+    #   Whether deprecated. Metadata included in exports.
+    # @param description [String, nil] (nil)
+    #   The description. Metadata included in exports.
+    # @param partial [Boolean] (false)
+    #   Whether partial. Partial variants include only the specified fields.
+    # @param tag [String, nil] (nil)
+    #   The discriminator tag value. Required when union has a discriminator.
+    # @yield block defining the variant type
+    # @yieldparam variant [Element]
+    # @return [void]
+    #
+    # @example instance_eval style
+    #   variant tag: 'card' do
+    #     object do
+    #       string :last_four
+    #     end
+    #   end
+    #
+    # @example yield style
+    #   variant tag: 'card' do |variant|
+    #     variant.object do |object|
+    #       object.string :last_four
+    #     end
+    #   end
+    def variant(deprecated: false, description: nil, partial: false, tag: nil, &block)
+      validate_tag!(tag)
+      raise ConfigurationError, 'variant requires a block' unless block
+
+      element = build_element
+      block.arity.positive? ? yield(element) : element.instance_eval(&block)
+      element.validate!
+
+      data = {
+        deprecated:,
+        description:,
+        partial:,
+        tag:,
+        custom_type: element.custom_type,
+        enum: element.enum,
+        format: element.format,
+        max: element.max,
+        min: element.min,
+        of: element.inner,
+        shape: element.shape,
+        type: element.type,
+        value: element.value,
+      }.compact
+
+      append_or_merge_variant(data, tag)
+    end
+
+    private
+
+    def build_element
+      raise NotImplementedError, "#{self.class} must implement #build_element"
+    end
+
+    def append_or_merge_variant(data, tag)
+      if tag && (index = @variants.find_index { |variant| variant[:tag] == tag })
+        existing = @variants[index]
+        merge_variant_shapes(existing, data[:shape]) if data[:shape] && existing[:shape]
+        data.delete(:shape) if data[:shape] && existing[:shape]
+        @variants[index] = existing.merge(data)
+      else
+        @variants << data
+      end
+    end
+
+    def merge_variant_shapes(existing_variant, new_shape)
+      return unless new_shape.respond_to?(:params)
+
+      new_shape.params.each do |name, param_options|
+        existing_variant[:shape].params[name] =
+          (existing_variant[:shape].params[name] || {}).merge(param_options)
+      end
+    end
+
+    def validate_tag!(tag)
+      raise ConfigurationError, 'tag can only be used when union has a discriminator' if tag.present? && @discriminator.nil?
+
+      return unless @discriminator.present? && tag.blank?
+
+      raise ConfigurationError, 'tag is required for all variants when union has a discriminator'
+    end
+  end
+end

data/lib/apiwork/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apiwork
-  VERSION = "0.0.0.pre"
-end
+  VERSION = '0.1.1'
+end

data/lib/apiwork.rb

@@ -1,8 +1,66 @@
 # frozen_string_literal: true
 
-require_relative "apiwork/version"
+require 'zeitwerk'
+require_relative 'apiwork/version'
 
 module Apiwork
-  class Error < StandardError; end
-  # Your code goes here...
+  class << self
+    def call(env)
+      routes.call(env)
+    end
+
+    def prepare!(eager_load: false)
+      API.clear!
+      Adapter.clear!
+      ErrorCode.clear!
+      Export.clear!
+
+      Adapter.register_defaults!
+      ErrorCode.register_defaults!
+      Export.register_defaults!
+
+      load_api_definitions!
+      eager_load_representations! if eager_load
+    end
+
+    private
+
+    def routes
+      return draw_routes if Rails.env.development?
+
+      @routes ||= draw_routes
+    end
+
+    def draw_routes
+      API::Router.draw
+    end
+
+    def eager_load_representations!
+      Dir[Rails.root.join('app/representations/**/*.rb')].sort.each(&method(:require_dependency))
+    end
+
+    def load_api_definitions!
+      Dir[Rails.root.join('config/apis/**/*.rb')].sort.each(&method(:load))
+    end
+  end
 end
+
+loader = Zeitwerk::Loader.for_gem
+
+loader.inflector.inflect(
+  'api' => 'API',
+  'api_builder' => 'APIBuilder',
+  'api_serializer' => 'APISerializer',
+  'json_pointer' => 'JSONPointer',
+  'json' => 'JSON',
+  'open_api' => 'OpenAPI',
+  'type_script_mapper' => 'TypeScriptMapper',
+  'uuid' => 'UUID',
+)
+
+loader.ignore("#{__dir__}/rubocop")
+loader.ignore("#{__dir__}/generators")
+
+loader.setup
+
+require_relative 'apiwork/engine' if defined?(Rails::Engine)

data/lib/generators/apiwork/api_generator.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Generators
+    class ApiGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates/api', __dir__)
+
+      argument :mount_path, desc: 'The API mount path (e.g., /api/v1 or /)', type: :string
+
+      desc 'Creates an Apiwork API definition'
+
+      def create_api_definition
+        template 'api.rb.tt', "config/apis/#{file_name}.rb"
+      end
+
+      private
+
+      def file_name
+        path_segments.empty? ? 'root' : path_segments.join('_')
+      end
+
+      def api_mount_path
+        path_segments.empty? ? '/' : "/#{path_segments.join('/')}"
+      end
+
+      def path_segments
+        @path_segments ||= normalize(mount_path)
+      end
+
+      def normalize(input)
+        normalized = input.to_s.gsub('::', '/').underscore.delete_prefix('/').strip
+        return [] if normalized.empty?
+
+        normalized.split('/')
+      end
+    end
+  end
+end

data/lib/generators/apiwork/contract_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Generators
+    class ContractGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates/contract', __dir__)
+
+      desc 'Creates an Apiwork contract'
+
+      def create_contract
+        template 'contract.rb.tt', contract_path
+      end
+
+      private
+
+      def contract_path
+        File.join('app/contracts', class_path, "#{file_name}_contract.rb")
+      end
+
+      def parent_class_name
+        'ApplicationContract'
+      end
+    end
+  end
+end

data/lib/generators/apiwork/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates/install', __dir__)
+
+      desc 'Creates the Apiwork directory structure'
+
+      def create_application_contract
+        template 'application_contract.rb.tt', 'app/contracts/application_contract.rb'
+      end
+
+      def create_application_representation
+        template 'application_representation.rb.tt', 'app/representations/application_representation.rb'
+      end
+
+      def create_apis_directory
+        empty_directory 'config/apis'
+      end
+
+      def add_route
+        route "mount Apiwork => '/'"
+      end
+    end
+  end
+end

data/lib/generators/apiwork/representation_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Generators
+    class RepresentationGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates/representation', __dir__)
+
+      desc 'Creates an Apiwork representation'
+
+      def create_representation
+        template 'representation.rb.tt', representation_path
+      end
+
+      private
+
+      def representation_path
+        File.join('app/representations', class_path, "#{file_name}_representation.rb")
+      end
+
+      def parent_class_name
+        'ApplicationRepresentation'
+      end
+    end
+  end
+end

data/lib/generators/apiwork/templates/api/api.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+Apiwork::API.define '<%= api_mount_path %>' do
+end

data/lib/generators/apiwork/templates/contract/contract.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= class_name %>Contract < <%= parent_class_name %>
+end
+<% end -%>

data/lib/generators/apiwork/templates/install/application_contract.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationContract < Apiwork::Contract::Base
+  abstract!
+end

data/lib/generators/apiwork/templates/install/application_representation.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationRepresentation < Apiwork::Representation::Base
+  abstract!
+end

data/lib/generators/apiwork/templates/representation/representation.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= class_name %>Representation < <%= parent_class_name %>
+end
+<% end -%>

data/lib/tasks/apiwork.rake

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+namespace :apiwork do
+  namespace :docs do
+    desc 'Generate API reference documentation from YARD comments'
+    task reference: :environment do
+      require 'apiwork/reference_generator'
+      Apiwork::ReferenceGenerator.generate
+      puts 'Reference documentation generated in docs/reference/'
+    end
+  end
+
+  namespace :export do
+    desc 'Write exports to files'
+    task write: :environment do
+      # Load API definitions
+      Dir[Rails.root.join('config/apis/**/*.rb')].sort.each { |file| load file }
+
+      api_base_path = ENV['API_PATH']
+      export_name = ENV['EXPORT_NAME']&.to_sym
+      format = ENV['FORMAT']&.to_sym
+      output = ENV['OUTPUT']
+
+      unless output
+        puts 'Error: OUTPUT required'
+        puts ''
+        puts 'Usage: rake apiwork:export:write OUTPUT=path [API_PATH=/api/v1] [EXPORT_NAME=openapi] [OPTIONS...]'
+        puts ''
+        puts 'Examples:'
+        puts '  rake apiwork:export:write OUTPUT=public/exports'
+        puts '  rake apiwork:export:write API_PATH=/api/v1 OUTPUT=public/exports'
+        puts '  rake apiwork:export:write API_PATH=/api/v1 EXPORT_NAME=openapi OUTPUT=public/openapi.json'
+        puts '  rake apiwork:export:write EXPORT_NAME=openapi FORMAT=yaml OUTPUT=public/openapi.yaml'
+        puts '  rake apiwork:export:write EXPORT_NAME=zod KEY_FORMAT=camel OUTPUT=public/exports'
+        puts '  rake apiwork:export:write OUTPUT=public/exports LOCALE=sv'
+        puts ''
+        puts 'Available exports:'
+        puts "  #{Apiwork::Export.keys.join(', ')}"
+        puts ''
+        puts 'Built-in options (uppercase ENV vars):'
+        puts '  FORMAT: json, yaml (only for data exports like openapi)'
+        puts '  KEY_FORMAT: keep, camel, underscore'
+        puts "  LOCALE: #{I18n.available_locales.join(', ')}"
+        puts ''
+        puts 'Custom export options are also supported via ENV vars.'
+        exit 1
+      end
+
+      custom_options = if export_name
+                         Apiwork::Export.find!(export_name).extract_options_from_env
+                       else
+                         {}
+                       end
+
+      begin
+        Apiwork::Export::Pipeline.write(
+          api_base_path:,
+          export_name:,
+          format:,
+          output:,
+          **custom_options,
+        )
+      rescue ArgumentError => e
+        puts "Error: #{e.message}"
+        exit 1
+      rescue Apiwork::ConfigurationError => e
+        puts "Error: #{e.message}"
+        exit 1
+      rescue StandardError => e
+        puts "Error: #{e.message}"
+        puts e.backtrace.first(5).join("\n") if ENV['VERBOSE']
+        exit 1
+      end
+    end
+
+    desc 'Clean generated export files'
+    task clean: :environment do
+      output = ENV['OUTPUT']
+
+      unless output
+        puts 'Error: OUTPUT required'
+        puts ''
+        puts 'Usage: rake apiwork:export:clean OUTPUT=path'
+        puts ''
+        puts 'Examples:'
+        puts '  rake apiwork:export:clean OUTPUT=public/exports'
+        puts '  rake apiwork:export:clean OUTPUT=public/openapi.json'
+        exit 1
+      end
+
+      begin
+        Apiwork::Export::Pipeline.clean(output:)
+      rescue ArgumentError => e
+        puts "Error: #{e.message}"
+        exit 1
+      rescue StandardError => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+    end
+  end
+end