action_spec 0.1.0

data/lib/action_spec/doc/endpoint.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Doc
+    class Endpoint
+      attr_reader :action, :summary, :options, :request, :responses
+
+      def initialize(action, summary: nil, options: {})
+        @action = action.to_sym
+        @summary = summary
+        @options = options
+        @request = Request.new
+        @responses = {}
+      end
+
+      def dsl
+        @dsl ||= Dsl.new(self)
+      end
+
+      def apply(block)
+        dsl.instance_exec(&block)
+        self
+      end
+
+      def add_response(code, response)
+        @responses[code.to_s] = response
+      end
+
+      def copy
+        self.class.new(action, summary:, options: options.deep_dup).tap do |endpoint|
+          endpoint.request.replace_with(request.copy)
+          responses.each do |code, response|
+            endpoint.add_response(code, response.copy)
+          end
+        end
+      end
+    end
+
+    class Request
+      attr_reader :header, :path, :query, :cookie, :body, :body_media_types
+
+      def initialize
+        @header = Location.new(:header)
+        @path = Location.new(:path)
+        @query = Location.new(:query)
+        @cookie = Location.new(:cookie)
+        @body = Location.new(:body)
+        @body_media_types = {}
+      end
+
+      def location(name)
+        public_send(name)
+      end
+
+      def add_param(location_name, field)
+        location(location_name).add(field)
+      end
+
+      def add_body(media_type, field)
+        body.add(field)
+        (@body_media_types[media_type.to_sym] ||= Location.new(media_type.to_sym)).add(field.copy)
+      end
+
+      def replace_with(other)
+        @header = other.header
+        @path = other.path
+        @query = other.query
+        @cookie = other.cookie
+        @body = other.body
+        @body_media_types = other.body_media_types
+      end
+
+      def copy
+        self.class.new.tap do |request|
+          request.instance_variable_set(:@header, header.copy)
+          request.instance_variable_set(:@path, path.copy)
+          request.instance_variable_set(:@query, query.copy)
+          request.instance_variable_set(:@cookie, cookie.copy)
+          request.instance_variable_set(:@body, body.copy)
+          request.instance_variable_set(
+            :@body_media_types,
+            body_media_types.transform_values(&:copy)
+          )
+        end
+      end
+    end
+
+    class Location
+      include Enumerable
+
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+        @fields = ActiveSupport::OrderedHash.new
+      end
+
+      def add(field)
+        @fields[field.name] = field
+      end
+
+      def field(name)
+        @fields[name.to_sym]
+      end
+
+      def [](name)
+        field(name)
+      end
+
+      def fields
+        @fields.values
+      end
+
+      def each(&block)
+        fields.each(&block)
+      end
+
+      def copy
+        self.class.new(name).tap do |location|
+          fields.each { |field| location.add(field.copy) }
+        end
+      end
+    end
+
+    class Response
+      attr_reader :code, :description, :media_type, :options
+
+      def initialize(code:, description:, media_type:, options:)
+        @code = code.to_s
+        @description = description
+        @media_type = media_type
+        @options = options
+      end
+
+      def copy
+        self.class.new(code:, description:, media_type:, options: options.deep_dup)
+      end
+    end
+  end
+end

data/lib/action_spec/doc.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "action_spec/doc/endpoint"
+require "action_spec/doc/dsl"
+
+module ActionSpec
+  module Doc
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def action_specs
+        @action_specs ||= begin
+          parent = superclass.respond_to?(:action_specs) ? superclass.action_specs : {}
+          parent.transform_values(&:copy)
+        end
+      end
+
+      def dry_blocks
+        @dry_blocks ||= begin
+          parent = superclass.respond_to?(:dry_blocks) ? superclass.dry_blocks : {}
+          parent.transform_values { |blocks| blocks.map(&:dup) }
+        end
+      end
+
+      def doc(action_or_summary = nil, summary = nil, **options, &block)
+        action_name, endpoint_summary = normalize_doc_arguments(action_or_summary, summary)
+        action_name ||= infer_action_name(caller_locations(1, 1).first)
+        endpoint = Endpoint.new(action_name, summary: endpoint_summary, options:)
+        action_specs[action_name.to_sym] = apply_dry_blocks(endpoint).apply(block || proc {})
+      end
+
+      def doc_dry(actions = :all, &block)
+        Array(actions).each do |action|
+          (dry_blocks[action.to_sym] ||= []) << block
+        end
+      end
+      alias api_dry doc_dry
+
+      def action_spec_for(action)
+        action_specs[action.to_sym]
+      end
+
+      private
+
+        def normalize_doc_arguments(action_or_summary, summary)
+          return [action_or_summary, summary] if action_or_summary.is_a?(Symbol)
+
+          [nil, action_or_summary]
+        end
+
+        def apply_dry_blocks(endpoint)
+          [*dry_blocks[:all], *dry_blocks[endpoint.action]].compact.each do |dry_block|
+            endpoint.apply(dry_block)
+          end
+          endpoint
+        end
+
+        def infer_action_name(location)
+          file = location.absolute_path || location.path
+          lines = File.readlines(file)
+          method_definition = lines[(location.lineno - 1)..].find { |line| line.match?(/^\s*def\s+(?!self\.)/) }
+          return Regexp.last_match(1).to_sym if method_definition&.match(/^\s*def\s+([a-zA-Z_]\w*[!?=]?)/)
+
+          raise ArgumentError, "ActionSpec could not infer the target action for `doc`; use `doc :action` instead"
+        end
+    end
+  end
+end

data/lib/action_spec/header_hash.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  class HeaderHash < ActiveSupport::HashWithIndifferentAccess
+    private
+
+      def convert_key(key)
+        super.to_s.sub(/\AHTTP_/, "").tr("_", "-").downcase
+      end
+  end
+end

data/lib/action_spec/invalid_parameters.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  class InvalidParameters < ActionController::BadRequest
+    attr_reader :result
+    alias parameters result
+    delegate :errors, :px, to: :result
+
+    def initialize(result)
+      @result = result
+      super(result.errors.full_messages.to_sentence.presence || "Invalid parameters")
+    end
+  end
+end

data/lib/action_spec/railtie.rb

@@ -0,0 +1,14 @@
+module ActionSpec
+  class Railtie < ::Rails::Railtie
+    initializer "action_spec.i18n" do |app|
+      app.config.i18n.load_path += Dir[root.join("config/locales/*.yml")]
+    end
+
+    initializer "action_spec.controller" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include ActionSpec::Doc
+        include ActionSpec::Validator
+      end
+    end
+  end
+end

data/lib/action_spec/schema/array_of.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    class ArrayOf < Base
+      attr_reader :item
+
+      def initialize(item, options = {})
+        super(options)
+        @item = item
+      end
+
+      def cast(value, context:, coerce:, result:, path:)
+        unless value.is_a?(Array)
+          result.add_error(path.join("."), :invalid)
+          return []
+        end
+
+        output = value.each_with_index.map do |entry, index|
+          item.cast(entry, context:, coerce:, result:, path: [*path, index])
+        end
+        validate_constraints(output, result:, path:)
+        output
+      end
+
+      def copy
+        self.class.new(item.copy, default:, enum:, range:, pattern:, allow_nil:, allow_blank:)
+      end
+    end
+  end
+end

data/lib/action_spec/schema/base.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    class Base
+      attr_reader :default, :enum, :range, :pattern, :allow_nil, :allow_blank
+
+      def initialize(options = {})
+        options = options.symbolize_keys
+        @default = options[:default]
+        @enum = options[:enum]
+        @range = options[:range]
+        @pattern = options[:pattern]
+        @allow_nil = options[:allow_nil]
+        @allow_blank = options[:allow_blank]
+      end
+
+      def materialize_missing(_context:, _coerce:, _result:, _path:)
+        Schema::Missing
+      end
+
+      def validate_constraints(value, result:, path:)
+        return if value.nil?
+
+        validate_enum(value, result:, path:)
+        validate_range(value, result:, path:)
+        validate_pattern(value, result:, path:)
+      end
+
+      def copy
+        raise NotImplementedError
+      end
+
+      private
+
+        def add_error(result, path, type, **options)
+          result.add_error(path.join("."), type, **options)
+        end
+
+        def validate_enum(value, result:, path:)
+          return if enum.blank?
+          return if Array(enum).include?(value)
+
+          add_error(result, path, :inclusion)
+        end
+
+        def validate_range(value, result:, path:)
+          return if range.blank?
+
+          rules = range.symbolize_keys
+          add_error(result, path, :greater_than_or_equal_to, count: rules[:ge]) if rules.key?(:ge) && value < rules[:ge]
+          add_error(result, path, :greater_than, count: rules[:gt]) if rules.key?(:gt) && value <= rules[:gt]
+          add_error(result, path, :less_than_or_equal_to, count: rules[:le]) if rules.key?(:le) && value > rules[:le]
+          add_error(result, path, :less_than, count: rules[:lt]) if rules.key?(:lt) && value >= rules[:lt]
+        end
+
+        def validate_pattern(value, result:, path:)
+          return if pattern.blank?
+
+          matcher = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
+          return if value.to_s.match?(matcher)
+
+          add_error(result, path, :invalid)
+        end
+    end
+  end
+end

data/lib/action_spec/schema/field.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    class Field
+      attr_reader :name, :schema
+
+      def initialize(name:, required:, schema:)
+        @name = name.to_sym
+        @required = required
+        @schema = schema
+      end
+
+      def required?
+        @required
+      end
+
+      def default_value
+        schema.default
+      end
+
+      def copy
+        self.class.new(name:, required: required?, schema: schema.copy)
+      end
+    end
+  end
+end

data/lib/action_spec/schema/object_of.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    class ObjectOf < Base
+      attr_reader :fields
+
+      def initialize(fields, options = {})
+        super(options)
+        @fields = fields
+      end
+
+      def cast(value, context:, coerce:, result:, path:)
+        source = normalize_source(value, result:, path:)
+        return Schema::Missing if source.equal?(Schema::Missing)
+
+        output = ActiveSupport::HashWithIndifferentAccess.new
+        fields.each_value do |field|
+          resolved = Resolver.new(
+            field:,
+            source:,
+            context:,
+            coerce:,
+            result:,
+            path:
+          ).resolve
+          output[field.name] = resolved unless resolved.equal?(Schema::Missing)
+        end
+        output.presence || (source.present? ? output : Schema::Missing)
+      end
+
+      def materialize_missing(context:, coerce:, result:, path:)
+        cast({}, context:, coerce:, result:, path:)
+      end
+
+      def copy
+        self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, allow_nil:, allow_blank:)
+      end
+
+      private
+
+        def normalize_source(value, result:, path:)
+          return {} if value.nil?
+          return value.to_unsafe_h.with_indifferent_access if value.is_a?(ActionController::Parameters)
+          return value.with_indifferent_access if value.is_a?(Hash)
+
+          result.add_error(path.join("."), :invalid)
+          Schema::Missing
+        end
+    end
+  end
+end

data/lib/action_spec/schema/resolver.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    class Resolver
+      def initialize(field:, source:, context:, coerce:, result:, path:)
+        @field = field
+        @source = source
+        @context = context
+        @coerce = coerce
+        @result = result
+        @path = [*path, field.name]
+      end
+
+      def resolve
+        return resolve_missing unless present?
+
+        schema.cast(value, context:, coerce:, result:, path:)
+      end
+
+      private
+
+        attr_reader :field, :source, :context, :coerce, :result, :path
+
+        def schema
+          field.schema
+        end
+
+        def value
+          source[field.name]
+        end
+
+        def present?
+          source.key?(field.name)
+        end
+
+        def resolve_missing
+          if schema.default.respond_to?(:call)
+            return schema.cast(evaluate_default(schema.default), context:, coerce:, result:, path:)
+          end
+          return schema.cast(schema.default, context:, coerce:, result:, path:) unless schema.default.nil?
+          return schema.materialize_missing(context:, coerce:, result:, path:) unless field.required?
+
+          result.add_error(path.join("."), :required)
+          Schema::Missing
+        end
+
+        def evaluate_default(default_proc)
+          return context.instance_exec(&default_proc) if context && default_proc.arity.zero?
+          return default_proc.call(context) if context && default_proc.arity == 1
+
+          default_proc.call
+        end
+    end
+  end
+end

data/lib/action_spec/schema/scalar.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    class Scalar < Base
+      attr_reader :type
+
+      def initialize(type, options = {})
+        super(options)
+        @type = type
+      end
+
+      def cast(value, context: nil, coerce:, result:, path:)
+        candidate = TypeCaster.cast(type, value)
+      rescue TypeCaster::CastError => error
+        result.add_error(path.join("."), :invalid_type, expected: error.expected)
+        nil
+      else
+        return candidate if candidate.nil?
+
+        validate_constraints(candidate, result:, path:)
+        coerce ? candidate : value
+      end
+
+      def copy
+        self.class.new(type, default:, enum:, range:, pattern:, allow_nil:, allow_blank:)
+      end
+    end
+  end
+end

data/lib/action_spec/schema/type_caster.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    class TypeCaster
+      class CastError < StandardError
+        attr_reader :expected
+
+        def initialize(expected)
+          @expected = expected
+          super()
+        end
+      end
+
+      class << self
+        def cast(type, value)
+          return value if value.nil?
+
+          normalized = normalize(type)
+          return value if normalized == :object
+          return cast_file(value) if normalized == :file
+          return cast_boolean(value) if normalized == :boolean
+          return cast_integer(value) if normalized == :integer
+          return cast_float(value) if normalized == :float
+          return cast_decimal(value) if normalized == :decimal
+
+          active_model_type_for(normalized).cast(value).tap do |casted|
+            raise CastError, normalized if casted.nil? && value.present?
+          end
+        end
+
+        def normalize(type)
+          return :boolean if boolean_type?(type)
+          return :string if type == String
+          return :integer if type == Integer
+          return :float if type == Float
+          return :decimal if type == BigDecimal
+          return :date if type == Date
+          return :datetime if [DateTime, ActiveSupport::TimeWithZone].include?(type)
+          return :time if type == Time
+          return :string if type == Symbol
+          return :file if type == File
+          return :object if [Hash, Object].include?(type)
+
+          type
+        end
+
+        private
+
+          def active_model_type_for(type)
+            case type
+            when :string then ActiveModel::Type::String.new
+            when :integer then ActiveModel::Type::Integer.new
+            when :float then ActiveModel::Type::Float.new
+            when :decimal then ActiveModel::Type::Decimal.new
+            when :boolean then ActiveModel::Type::Boolean.new
+            when :date then ActiveModel::Type::Date.new
+            when :datetime then ActiveModel::Type::DateTime.new
+            when :time then ActiveModel::Type::Time.new
+            else ActiveModel::Type::Value.new
+            end
+          end
+
+          def cast_file(value)
+            return value if file_like?(value)
+
+            raise CastError, :file
+          end
+
+          def cast_integer(value)
+            return value if value.is_a?(Integer)
+            raise CastError, :integer unless value.is_a?(String) && value.match?(/\A[+-]?\d+\z/)
+
+            active_model_type_for(:integer).cast(value)
+          end
+
+          def cast_float(value)
+            return value.to_f if value.is_a?(Numeric)
+            raise CastError, :float unless value.is_a?(String) && value.match?(/\A[+-]?\d+(\.\d+)?\z/)
+
+            active_model_type_for(:float).cast(value)
+          end
+
+          def cast_decimal(value)
+            return value if value.is_a?(BigDecimal)
+            raise CastError, :decimal unless value.is_a?(Numeric) || (value.is_a?(String) && value.match?(/\A[+-]?\d+(\.\d+)?\z/))
+
+            active_model_type_for(:decimal).cast(value)
+          end
+
+          def cast_boolean(value)
+            return value if value == true || value == false
+            return true if value.in?([1, "1", "true", "t", "yes", "on"])
+            return false if value.in?([0, "0", "false", "f", "no", "off"])
+
+            raise CastError, :boolean
+          end
+
+          def boolean_type?(type)
+            type == :boolean ||
+              type.to_s == "boolean" ||
+              (Object.const_defined?(:Boolean) && type == ::Boolean)
+          end
+
+          def file_like?(value)
+            value.is_a?(File) ||
+              value.is_a?(Tempfile) ||
+              value.respond_to?(:read) ||
+              value.is_a?(ActionDispatch::Http::UploadedFile) ||
+              (value.is_a?(Hash) && (value.key?(:tempfile) || value.key?("tempfile")))
+          end
+      end
+    end
+  end
+end