sober_swag 0.18.0 → 0.22.0

data/lib/sober_swag/reporting/input/format.rb

@@ -0,0 +1,39 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Specify that something must match a particular format.
+      # Note: said format is just a string.
+      class Format < Base
+        def initialize(input, format)
+          @input = input
+          @format = format
+        end
+
+        ##
+        # @return [Interface]
+        attr_reader :input
+
+        ##
+        # @return [String]
+        attr_reader :format
+
+        def call(object)
+          input.call(object)
+        end
+
+        def swagger_schema
+          schema, found = input.swagger_schema
+
+          merged =
+            if schema.key?(:$ref)
+              { allOf: [schema] }
+            else
+              schema
+            end.merge(format: format)
+          [merged, found]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/interface.rb

@@ -0,0 +1,87 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Module for interface methods.
+      module Interface
+        ##
+        # Make a new input that is either this type or the argument.
+        #
+        # @argument other [Interface] other input type
+        # @return [Either] this input, or some other input.
+        def or(other)
+          Either.new(self, other)
+        end
+
+        ##
+        # @see {#or}
+        def |(other)
+          Either.new(self, other)
+        end
+
+        ##
+        # This, or null.
+        #
+        # @return [Either] an either type of this or nil.
+        def optional
+          self | Null.new
+        end
+
+        ##
+        # A list of this input.
+        #
+        # @return [List] the new input.
+        def list
+          List.new(self)
+        end
+
+        def referenced(name)
+          Referenced.new(self, name)
+        end
+
+        def format(format)
+          Format.new(self, format)
+        end
+
+        def described(desc)
+          Described.new(self, desc)
+        end
+
+        def enum(*cases)
+          Enum.new(self, cases)
+        end
+
+        ##
+        # Map a function after this input runs.
+        #
+        # @return [Mapped] the new input.
+        def mapped(&block)
+          Mapped.new(self, block)
+        end
+
+        def call!(value)
+          res = call(value)
+          raise Report::Error.new(res) if res.is_a?(Report::Base) # rubocop:disable Style/RaiseArgs
+
+          res
+        end
+
+        def swagger_path_schema
+          raise InvalidSchemaError::InvalidForPathError.new(self) # rubocop:disable Style/RaiseArgs
+        end
+
+        def swagger_query_schema
+          raise InvalidSchemaError::InvalidForQueryError.new(self) # rubocop:disable Style/RaiseArgs
+        end
+
+        def add_schema_key(base, addition)
+          if base.key?(:$ref)
+            { allOf: [base] }.merge(addition)
+          else
+            base.merge(addition)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/list.rb

@@ -0,0 +1,44 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Class to parse an array, where each element has the same type.
+      #
+      # Called List to avoid name conflicts.
+      class List < Base
+        ##
+        # @param element [Base] the parser for elements
+        def initialize(element)
+          @element = element
+        end
+
+        ##
+        # @return [Base] the parser for elements
+        attr_reader :element
+
+        def call(value)
+          return Report::Value.new(['was not an array']) unless value.is_a?(Array)
+
+          # obtain a hash of indexes => errors
+          errs = {}
+          # yes, side effects in a map are evil, but we avoid traversal twice
+          mapped = value.map.with_index do |item, idx|
+            element.call(item).tap { |e| errs[idx] = e if e.is_a?(Report::Base) }
+          end
+
+          if errs.any?
+            Report::List.new(errs)
+          else
+            mapped
+          end
+        end
+
+        def swagger_schema
+          schema, found = element.swagger_schema
+
+          [{ type: 'list', items: schema }, found]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/mapped.rb

@@ -0,0 +1,36 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Apply a mapping function over an input.
+      class Mapped < Base
+        ##
+        # @param mapper [#call] the mapping function
+        # @param input [Base] the base input
+        def initialize(input, mapper)
+          @mapper = mapper
+          @input = input
+        end
+
+        ##
+        # @return [#call] mapping function
+        attr_reader :mapper
+        ##
+        # @return [Base] base input
+        attr_reader :input
+
+        def call(value)
+          val = input.call(value)
+
+          return val if val.is_a?(Report::Base)
+
+          mapper.call(val)
+        end
+
+        def swagger_schema
+          input.swagger_schema
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/merge_objects.rb

@@ -0,0 +1,72 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Merge two object types together, in an allof stype relationship
+      class MergeObjects < Base
+        def initialize(parent, child)
+          @parent = parent
+          @child = child
+        end
+
+        ##
+        # @return [Interface] parent type
+        attr_reader :parent
+
+        ##
+        # @return [Interface] child type
+        attr_reader :child
+
+        def call(value)
+          parent_attrs = parent.call(value)
+
+          return parent_attrs if parent_attrs.is_a?(Report::Value)
+
+          # otherwise, object type, so we want to get a full error report
+
+          child_attrs = child.call(value)
+
+          return child_attrs if child_attrs.is_a?(Report::Value)
+
+          merge_results(parent_attrs, child_attrs)
+        end
+
+        def swagger_schema
+          parent_schema, parent_found = parent.swagger_schema
+          child_schema, child_found = child.swagger_schema
+
+          [
+            {
+              allOf: (parent_schema[:allOf] || [parent_schema]) + (child_schema[:allOf] || [child_schema])
+            },
+            parent_found.merge(child_found)
+          ]
+        end
+
+        def swagger_path_schema
+          parent.swagger_path_schema + child.swagger_path_schema
+        end
+
+        def swagger_query_schema
+          parent.swagger_query_schema + child.swagger_query_schema
+        end
+
+        private
+
+        def merge_results(par, chi) # rubocop:disable Metrics/MethodLength
+          if par.is_a?(Report::Base)
+            if chi.is_a?(Report::Base)
+              Report::MergedObject.new(par, chi)
+            else
+              par
+            end
+          elsif chi.is_a?(Report::Base)
+            chi
+          else
+            par.to_h.merge(chi.to_h)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/null.rb

@@ -0,0 +1,34 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Null input values.
+      # Validates that the input is null.
+      class Null < Base
+        def call(value)
+          return nil if value.nil?
+
+          Report::Value.new(['was not nil'])
+        end
+
+        def hash
+          [self.class.hash, 1].hash
+        end
+
+        def eql?(other)
+          other.class == self.class
+        end
+
+        def <=>(other)
+          eql?(other) ? 0 : nil
+        end
+
+        include Comparable
+
+        def swagger_schema
+          [{ type: 'null' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/number.rb

@@ -0,0 +1,19 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Parse some kind of number.
+      class Number < Base
+        def call(input)
+          return Report::Value.new(['is not a number']) unless input.is_a?(Numeric)
+
+          input
+        end
+
+        def swagger_schema
+          [{ type: 'number' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/object/property.rb

@@ -0,0 +1,53 @@
+module SoberSwag
+  module Reporting
+    module Input
+      class Object
+        ##
+        # Describe a single property key in an object.
+        class Property
+          def initialize(value, required:, description: '')
+            @value = value
+            @required = required
+            @description = description
+          end
+
+          ##
+          # @return [SoberSwag::Reporting::Input::Interface] value type
+          attr_reader :value
+
+          def required?
+            @required
+          end
+
+          ##
+          # @return [String, nil] description
+          attr_reader :description
+
+          def property_schema
+            direct, refined = value.swagger_schema
+
+            if description
+              [add_description(direct), refined]
+            else
+              [direct, refined]
+            end
+          end
+
+          private
+
+          def add_description(dir)
+            t =
+              if dir.key?(:$ref)
+                # workaround: we have to do this if we want to allow
+                # descriptions in reference types
+                { allOf: [dir] }
+              else
+                dir
+              end
+            t.merge(description: description)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/object.rb

@@ -0,0 +1,100 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Input object values
+      class Object < Base
+        autoload :Property, 'sober_swag/reporting/input/object/property'
+        ##
+        # @param fields [Hash<Symbol, Property>]
+        def initialize(fields)
+          @fields = fields
+        end
+
+        ##
+        # @return [Hash<String,#call>]
+        attr_reader :fields
+
+        def call(value)
+          return Report::Value.new(['was a not a JSON object']) unless value.is_a?(Hash)
+
+          bad, good = fields.map { |k, prop|
+            extract_value(k, prop, value)
+          }.compact.partition { |(_, v)| v.is_a?(Report::Base) }
+
+          return Report::Object.new(bad.to_h) if bad.any?
+
+          good.to_h
+        end
+
+        def swagger_schema
+          fields, found = field_schemas
+
+          obj = {
+            type: 'object',
+            properties: fields
+          }.merge(required_portion)
+
+          [obj, found]
+        end
+
+        def swagger_query_schema
+          swagger_parameter_schema.map do |param|
+            param.merge({ in: :query, style: :deepObject, explode: true })
+          end
+        end
+
+        def swagger_path_schema
+          swagger_parameter_schema.map do |param|
+            param.merge({ in: :path })
+          end
+        end
+
+        private
+
+        def swagger_parameter_schema
+          fields.map do |name, field|
+            key_schema, = field.property_schema
+            base = {
+              name: name,
+              schema: key_schema,
+              required: field.required?
+            }
+            field.description ? base.merge(description: field.description) : base
+          end
+        end
+
+        def field_schemas
+          fields.reduce([{}, Set.new]) do |(field_schemas, found), (k, v)|
+            key_schema, key_found = v.property_schema
+            [
+              field_schemas.merge(k => key_schema),
+              found.merge(key_found)
+            ]
+          end
+        end
+
+        ##
+        # Either the list of required keys, or something stating "provide at least one key."
+        # This is needed because you can't have an empty list of keys.
+        def required_portion
+          required_fields = fields.map { |k, v| k if v.required? }.compact
+
+          if required_fields.empty?
+            {}
+          else
+            { required: required_fields }
+          end
+        end
+
+        def extract_value(key, property, input)
+          if input.key?(key)
+            [key, property.value.call(input[key])]
+          elsif property.required?
+            [key, Report::Value.new(['is required'])]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/pattern.rb

@@ -0,0 +1,46 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Input values that validate against a pattern
+      class Pattern < Base
+        def initialize(input, pattern)
+          @input = input
+          @pattern = pattern
+        end
+
+        ##
+        # @return [#call] input type
+        attr_reader :input
+
+        ##
+        # @return [#matches] regexp matcher
+        attr_reader :pattern
+
+        def call(value)
+          val = input.call(value)
+
+          return val if val.is_a?(Report::Base)
+
+          if pattern.match?(value)
+            value
+          else
+            Report::Value.new(["did not match pattern #{pattern}"])
+          end
+        end
+
+        def swagger_schema
+          single, found = input.swagger_schema
+
+          [add_schema_key(single, { pattern: formatted_pattern }), found]
+        end
+
+        ##
+        # Try to format a pattern so it'll work nicely with JS.
+        def formatted_pattern
+          pattern.to_s.gsub('?-mix:', '')
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/referenced.rb

@@ -0,0 +1,38 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # An input that should be "referenced" in the final schema.
+      class Referenced < Base
+        def initialize(value, reference)
+          @value = value
+          @reference = reference
+        end
+
+        ##
+        # @return [Interface] the actual input
+        attr_reader :value
+        ##
+        # @return [String] key in the components hash
+        attr_reader :reference
+
+        def call(input)
+          @value.call(input)
+        end
+
+        def swagger_schema
+          [
+            { "$ref": ref_path },
+            { reference => proc { value.swagger_schema } }
+          ]
+        end
+
+        private
+
+        def ref_path
+          "#/components/schemas/#{reference}"
+        end
+      end
+    end
+  end
+end