explicit 0.1.0

data/lib/explicit/spec/array.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Array
+  extend self
+
+  def build(itemspec, options)
+    itemspec_validator = Explicit::Spec.build(itemspec)
+
+    lambda do |values|
+      return [:error, :array] if !values.is_a?(::Array)
+
+      if options[:empty] == false && values.empty?
+        return [:error, :empty]
+      end
+
+      validated = []
+
+      values.each.with_index do |value, index|
+        case itemspec_validator.call(value)
+        in [:ok, value]  then validated << value
+        in [:error, err] then return [:error, [:array, index, err]]
+        end
+      end
+
+      [:ok, validated]
+    end
+  end
+end

data/lib/explicit/spec/boolean.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Boolean
+  extend self
+
+  VALUES = {
+    "true" => true,
+    "on" => true,
+    "1" => true,
+    "false" => false,
+    "off" => false,
+    "0" => false
+  }.freeze
+
+  def build(options)
+    lambda do |value|
+      value =
+        if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          value
+        elsif value.is_a?(::String)
+          VALUES[value]
+        else
+          nil
+        end
+
+      return [:error, :boolean] if value.nil?
+
+      [:ok, value]
+    end
+  end
+end

data/lib/explicit/spec/date_time_iso8601.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Explicit::Spec::DateTimeISO8601
+  extend self
+
+  def call(value)
+    return [:error, :date_time_iso8601] if !value.is_a?(::String)
+
+    timeval = Time.iso8601(value)
+
+    [:ok, timeval]
+  rescue ArgumentError
+    [:error, :date_time_iso8601]
+  end
+end

data/lib/explicit/spec/date_time_posix.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Explicit::Spec::DateTimePosix
+  extend self
+
+  ERROR_INVALID = [:error, :date_time_posix].freeze
+
+  def call(value)
+    if !value.is_a?(::Integer) && !value.is_a?(::String)
+      return ERROR_INVALID
+    end
+
+    datetimeval = DateTime.strptime(value.to_s, "%s")
+
+    [:ok, datetimeval]
+  rescue Date::Error
+    ERROR_INVALID
+  end
+end

data/lib/explicit/spec/default.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Default
+  extend self
+
+  def build(defaultval, subspec)
+    subspec_validator = Explicit::Spec::build(subspec)
+
+    lambda do |value|
+      value =
+        if value.nil?
+          defaultval.respond_to?(:call) ? defaultval.call : defaultval
+        else
+          value
+        end
+
+      subspec_validator.call(value)
+    end
+  end
+end

data/lib/explicit/spec/error.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Error
+  extend self
+
+  RailsI18n = ->(error, **context) do
+    key = "explicit.errors.#{error}"
+
+    ::I18n.t(key, **context)
+  end
+
+  def translate(error, translator = RailsI18n)
+    case error
+    in :agreement
+      translator.call(:agreement)
+    in [:array, index, suberr]
+      translator.call(:array, index:, error: translate(suberr, translator))
+    in :boolean
+      translator.call(:boolean)
+    in :date_time_iso8601
+      translator.call(:date_time_iso8601)
+    in :date_time_posix
+      translator.call(:date_time_posix)
+    in :hash
+      translator.call(:hash)
+    in [:hash_key, key, suberr]
+      translator.call(:hash_key, key:, error: translate(suberr, translator))
+    in [:hash_value, key, suberr]
+      translator.call(:hash_value, key:, error: translate(suberr, translator))
+    in [:inclusion, values]
+      translator.call(:inclusion, values: values.inspect)
+    in :integer
+      translator.call(:integer)
+    in [:min, min]
+      translator.call(:min, min:)
+    in [:max, max]
+      translator.call(:max, max:)
+    in :negative
+      translator.call(:negative)
+    in :positive
+      translator.call(:positive)
+    in [:literal, value]
+      translator.call(:literal, value: value.inspect)
+    in [:one_of, *errors]
+      errors.map { translate(_1, translator) }.join(" OR ")
+    in :string
+      translator.call(:string)
+    in :empty
+      translator.call(:empty)
+    in [:minlength, minlength]
+      translator.call(:minlength, minlength:)
+    in [:maxlength, maxlength]
+      translator.call(:maxlength, maxlength:)
+    in [:format, regex]
+      translator.call(:format, regex: regex.inspect)
+    in Hash
+      error.to_h { |attr_name, err| [attr_name, translate(err, translator)] }
+    end
+  end
+end

data/lib/explicit/spec/hash.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Hash
+  extend self
+
+  def build(keyspec, valuespec, options)
+    keyspec_validator = Explicit::Spec.build(keyspec)
+    valuespec_validator = Explicit::Spec.build(valuespec)
+
+    lambda do |value|
+      return [:error, :hash] if !value.is_a?(::Hash)
+      return [:error, :empty] if value.empty? && !options[:empty]
+
+      validated_hash = {}
+
+      value.each do |key, value|
+        case [keyspec_validator.call(key), valuespec_validator.call(value)]
+        in [[:ok, validated_key], [:ok, validated_value]]
+          validated_hash[validated_key] = validated_value
+        in [[:error, err], _]
+          return [:error, [:hash_key, key, err]]
+        in [_, [:error, err]]
+          return [:error, [:hash_value, key, err]]
+        end
+      end
+
+      [:ok, validated_hash]
+    end
+  end
+end

data/lib/explicit/spec/inclusion.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Inclusion
+  extend self
+
+  def build(values)
+    lambda do |value|
+      if values.include?(value)
+        [:ok, value]
+      else
+        [:error, [:inclusion, values]]
+      end
+    end
+  end
+end

data/lib/explicit/spec/integer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Integer
+  extend self
+
+  def build(options)
+    lambda do |value|
+      value =
+        if value.is_a?(::Integer)
+          value
+        elsif value.is_a?(::String) && options[:parse]
+          parse_from_string(value)
+        else
+          nil
+        end
+
+      return [:error, :integer] if value.nil?
+
+      if (min = options[:min]) && !validate_min(value, min)
+        return [:error, [:min, min]]
+      end
+
+      if (max = options[:max]) && !validate_max(value, max)
+        return [:error, [:max, max]]
+      end
+
+      if options[:negative] == false && value < 0
+        return [:error, :negative]
+      end
+
+      if options[:positive] == false && value > 0
+        return [:error, :positive]
+      end
+
+      [:ok, value]
+    end
+  end
+
+  private
+    def parse_from_string(value)
+      Integer(value)
+    rescue ::ArgumentError
+      nil
+    end
+
+    def validate_min(value, min)
+      value >= min
+    end
+
+    def validate_max(value, max)
+      value <= max
+    end
+end

data/lib/explicit/spec/literal.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Literal
+  extend self
+
+  def build(literal_value)
+    lambda do |value|
+      if value == literal_value
+        [:ok, value]
+      else
+        [:error, [:literal, literal_value]]
+      end
+    end
+  end
+end

data/lib/explicit/spec/nilable.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Nilable
+  extend self
+
+  def build(subspec)
+    subspec_validator = Explicit::Spec.build(subspec)
+
+    lambda do |value|
+      return [:ok, nil] if value.nil?
+
+      subspec_validator.call(value)
+    end
+  end
+end

data/lib/explicit/spec/one_of.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::OneOf
+  extend self
+
+  def build(subspecs)
+    subspec_validators = subspecs.map { Explicit::Spec.build(_1) }
+
+    errors = []
+
+    lambda do |value|
+      subspec_validators.each do |subspec_validator|
+        case subspec_validator.call(value)
+        in [:ok, validated_value] then return [:ok, validated_value]
+        in [:error, err] then errors << err
+        end
+      end
+
+      [:error, [:one_of, *errors]]
+    end
+  end
+end

data/lib/explicit/spec/record.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::Record
+  extend self
+
+  def build(attributes)
+    attributes_validators = attributes.map do |attribute_name, attribute_spec|
+      [attribute_name, Explicit::Spec.build(attribute_spec)]
+    end
+
+    lambda do |data|
+      validated_data = {}
+      errors = {}
+
+      attributes_validators.each do |attribute_name, attribute_validator|
+        value = data[attribute_name]
+
+        case attribute_validator.call(value)
+        in [:ok, validated_value]
+          validated_data[attribute_name] = validated_value
+        in [:error, err]
+          errors[attribute_name] = err
+        end
+      end
+
+      return [:error, errors] if errors.any?
+
+      [:ok, validated_data]
+    end
+  end
+end

data/lib/explicit/spec/string.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Explicit::Spec::String
+  extend self
+
+  def build(options)
+    lambda do |value|
+      return [:error, :string] if !value.is_a?(::String)
+
+      value = value.strip if options[:strip]
+
+      if options.key?(:empty) && !validate_empty(value, options[:empty])
+        return [:error, :empty]
+      end
+
+      if (minlength = options[:minlength]) && !validate_minlength(value, minlength)
+        return [:error, [:minlength, minlength:]]
+      end
+
+      if (maxlength = options[:maxlength]) && !validate_maxlength(value, maxlength)
+        return [:error, [:maxlength, maxlength:]]
+      end
+
+      if (format = options[:format]) && !validate_format(value, format)
+        return [:error, [:format, format]]
+      end
+
+      [:ok, value]
+    end
+  end
+
+  private
+    def validate_empty(value, allow_empty)
+      return true if allow_empty
+
+      !value.empty?
+    end
+
+    def validate_minlength(value, minlength)
+      value.length >= minlength
+    end
+
+    def validate_maxlength(value, maxlength)
+      value.length <= maxlength
+    end
+
+    def validate_format(value, format)
+      format.match?(value)
+    end
+end

data/lib/explicit/spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Explicit::Spec
+  extend self
+
+  def build(spec)
+    case spec
+    in :agreement
+      Explicit::Spec::Agreement.build({})
+    in [:agreement, options]
+      Explicit::Spec::Agreement.build(options)
+
+    in [:array, itemspec]
+      Explicit::Spec::Array.build(itemspec, {})
+    in [:array, itemspec, options]
+      Explicit::Spec::Array.build(itemspec, options)
+
+    in :boolean
+      Explicit::Spec::Boolean.build({})
+    in [:boolean, options]
+      Explicit::Spec::Boolean.build(options)
+
+    in :date_time_iso8601
+      Explicit::Spec::DateTimeISO8601
+    in :date_time_posix
+      Explicit::Spec::DateTimePosix
+
+    in [:default, defaultval, subspec]
+      Explicit::Spec::Default.build(defaultval, subspec)
+
+    in [:hash, keyspec, valuespec]
+      Explicit::Spec::Hash.build(keyspec, valuespec, {})
+    in [:hash, keyspec, valuespec, options]
+      Explicit::Spec::Hash.build(keyspec, valuespec, options)
+
+    in [:inclusion, options]
+      Explicit::Spec::Inclusion.build(options)
+
+    in :integer
+      Explicit::Spec::Integer.build({})
+    in [:integer, options]
+      Explicit::Spec::Integer.build(options)
+
+    in [:literal, value]
+      Explicit::Spec::Literal.build(value)
+    in ::String
+      Explicit::Spec::Literal.build(spec)
+
+    in [:nilable, options]
+      Explicit::Spec::Nilable.build(options)
+
+    in [:one_of, *subspecs]
+      Explicit::Spec::OneOf.build(subspecs)
+
+    in :string
+      Explicit::Spec::String.build({})
+    in [:string, options]
+      Explicit::Spec::String.build(options)
+
+    in ::Hash
+      Explicit::Spec::Record.build(spec)
+    end
+  end
+end

data/lib/explicit/test_helper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Explicit::TestHelper
+  Response = ::Data.define(:status, :data) do
+    def dig(...) = data.dig(...)
+  end
+
+  def fetch(request, params:, headers: nil)
+    route = request.send(:routes).first
+
+    if route.nil?
+      raise <<-DESC
+      The request #{request} must define at least one route. For example:
+
+        get "/customers/:customer_id"
+        post "/article/:article_id/comments"
+        put "/user/preferences"
+
+      Important: adding a route to the request does not substitute the entry
+      on `routes.rb`.
+      DESC
+    end
+
+    process(route.method, route.path, params:, headers:)
+
+    response = Response.new(
+      status: @response.status,
+      data: @response.parsed_body.deep_symbolize_keys
+    )
+
+    ensure_response_matches_spec!(request, response)
+
+    response
+  end
+
+  def ensure_response_matches_spec!(request, response)
+    allowed_responses = request.send(:responses)
+    response_validator = Explicit::Spec.build([:one_of, *allowed_responses])
+
+    case response_validator.call({ status: response.status, data: response.data.with_indifferent_access })
+    in [:ok, _] then :all_good
+    in [:error, err] then raise Explicit::Request::InvalidResponseError.new(response, err)
+    end
+  end
+end

data/lib/explicit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Explicit
+  VERSION = "0.1.0"
+end

data/lib/explicit.rb

@@ -0,0 +1,28 @@
+require "explicit/documentation"
+require "explicit/engine"
+require "explicit/test_helper"
+require "explicit/version"
+
+require "explicit/request"
+require "explicit/request/invalid_params"
+require "explicit/request/invalid_response_error"
+
+require "explicit/spec"
+require "explicit/spec/agreement"
+require "explicit/spec/array"
+require "explicit/spec/boolean"
+require "explicit/spec/date_time_iso8601"
+require "explicit/spec/date_time_posix"
+require "explicit/spec/default"
+require "explicit/spec/error"
+require "explicit/spec/hash"
+require "explicit/spec/inclusion"
+require "explicit/spec/integer"
+require "explicit/spec/literal"
+require "explicit/spec/nilable"
+require "explicit/spec/one_of"
+require "explicit/spec/record"
+require "explicit/spec/string"
+
+module Explicit
+end

data/lib/tasks/schema/api_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :schema_api do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: explicit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Luiz Vasconcellos
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-12-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+description: explicit allows you to document, test and specify requests and responses
+  schemas
+email:
+- luizpvasc@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/explicit/application_controller.rb
+- app/helpers/explicit/application_helper.rb
+- app/views/explicit/application/_documentation.html.erb
+- config/locales/en.yml
+- config/routes.rb
+- lib/explicit.rb
+- lib/explicit/documentation.rb
+- lib/explicit/engine.rb
+- lib/explicit/request.rb
+- lib/explicit/request/invalid_params.rb
+- lib/explicit/request/invalid_response_error.rb
+- lib/explicit/spec.rb
+- lib/explicit/spec/agreement.rb
+- lib/explicit/spec/array.rb
+- lib/explicit/spec/boolean.rb
+- lib/explicit/spec/date_time_iso8601.rb
+- lib/explicit/spec/date_time_posix.rb
+- lib/explicit/spec/default.rb
+- lib/explicit/spec/error.rb
+- lib/explicit/spec/hash.rb
+- lib/explicit/spec/inclusion.rb
+- lib/explicit/spec/integer.rb
+- lib/explicit/spec/literal.rb
+- lib/explicit/spec/nilable.rb
+- lib/explicit/spec/one_of.rb
+- lib/explicit/spec/record.rb
+- lib/explicit/spec/string.rb
+- lib/explicit/test_helper.rb
+- lib/explicit/version.rb
+- lib/tasks/schema/api_tasks.rake
+homepage: https://github.com/luizpvas/explicit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/luizpvas/explicit
+  source_code_uri: https://github.com/luizpvas/explicit
+  changelog_uri: https://github.com/luizpvas/explicit
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key: 
+specification_version: 4
+summary: explicit is a documentation and validation library for JSON APIs
+test_files: []