sober_swag 0.21.0 → 0.22.0

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

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

@@ -0,0 +1,271 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Base class of input structs.
+      #
+      # These allow you to define both an input type and a ruby type at once.
+      # They provide a fluid interface for doing so.
+      #
+      # Classes which inherit from {Struct} "quack like" an {Interface}, so you can use them as input type definitions.
+      #
+      # You should add attributes using the {.attribute} or {.attribute?} methods.
+      # These also let you nest definitions, so this is okay:
+      #
+      # ```ruby
+      # class Person < SoberSwag::Reporting::Input::Struct
+      #   attribute :first_name, SoberSwag::Reporting::Input.text
+      #   attribute :stats do
+      #     attribute :average_score, SoberSwag::Reporting::Input.number
+      #   end
+      # end
+      # ```
+      class Struct # rubocop:disable Metrics/ClassLength
+        class << self
+          ##
+          # @overload attribute(name, input, description: nil)
+          #   Define a new attribute, which will be required.
+          #   @param name [Symbol] the name of this attribute
+          #   @param input [Interface] input reporting type
+          #   @param description [String,nil] description for this attribute
+          # @overload attribute(name, description: nil, &block)
+          #   Define a new nested attribute, which will be required, using a block to describe
+          #   a sub-struct. This block will immediately be evaluated to create a child struct.
+          #   @param name [Symbol] the name of the attribute.
+          #     The sub-struct defined will be stored in a constant on this class,
+          #     under this name, classified.
+          #
+          #     So if the name is :first_name, then the constant will be FirstName
+          #   @param description [String, nil] describe this attribute
+          #   @yieldself [SoberSwag::Reporting::Input::Struct] yields
+          def attribute(name, input = nil, description: nil, &block)
+            input_type = make_input_type(name, input, block)
+            add_attribute!(name, input_type, required: true, description: description)
+          end
+
+          ##
+          # @overload attribute?(name, input, description: nil)
+          #   Define a new attribute, which will be not required.
+          #   @param name [Symbol] the name of this attribute
+          #   @param input [Interface] input reporting type
+          #   @param description [String,nil] description for this attribute
+          # @overload attribute?(name, description: nil, &block)
+          #   Define a new nested attribute, which will not be required, using a block to describe
+          #   a sub-struct. This block will immediately be evaluated to create a child struct.
+          #   @param name [Symbol] the name of the attribute.
+          #     The sub-struct defined will be stored in a constant on this class,
+          #     under this name, classified.
+          #
+          #     So if the name is :first_name, then the constant will be FirstName
+          #   @param description [String, nil] describe this attribute
+          #   @yieldself [SoberSwag::Reporting::Input::Struct] yields
+          def attribute?(name, input = nil, description: nil, &block)
+            input_type = make_input_type(name, input, block)
+
+            add_attribute!(name, input_type, required: false, description: description)
+          end
+
+          ##
+          # Add an attribute, specifying if it is required or not via an argument.
+          # You should use {#attribute} or {#attribute?} instead of this almost always.
+          #
+          # @param name [Symbol] name of this attribute
+          # @param input [Interface] type fot this attribue
+          # @param required [true,false] if this attribute is required
+          # @param description [String,nil] optional description for this attribute
+          #
+          def add_attribute!(name, input, required:, description: nil)
+            raise ArgumentError, 'name must be a symbol' unless name.is_a?(Symbol)
+
+            define_attribute(name) # defines an instance method to access this attribute
+
+            object_properties[name] = Object::Property.new(
+              input,
+              required: required,
+              description: description
+            )
+          end
+
+          ##
+          # Get a list of properties defined by *this instance*.
+          #
+          # Please do not mutate this, it will break everything.
+          #
+          # @return [Hash<Symbol, Object::Property>]
+          def object_properties
+            @object_properties ||= {}
+          end
+
+          ##
+          # @return [SoberSwag::Reporting::Input::Struct,nil] the struct we inherit from.
+          #   Used to implement `allOf` style inheritance.
+          attr_accessor :parent_struct
+
+          ##
+          # @param other [Class] the inheriting class
+          #
+          # Used to implement `allOf` style inheritance by setting {#parent_struct} on the object that is inheriting from us.
+          def inherited(other)
+            other.parent_struct = self unless self == SoberSwag::Reporting::Input::Struct
+          end
+
+          include Interface
+
+          ##
+          # @return [SoberSwag::Reporting::Input::Base] the type to use for input.
+          def input_type
+            object_type.mapped { |x| new(x) }.referenced(identifier)
+          end
+
+          ##
+          # @overload identifier()
+          #   @return [String,nil] the identifier for this object, used for its reference path.
+          # @overload identifier(val)
+          #   Sets an identifier for this struct.
+          #   @param val [String] the identifier to set
+          #   @return [String] the set identifier.
+          def identifier(val = nil)
+            if val
+              @identifier = val
+            else
+              @identifier || name&.gsub('::', '.')
+            end
+          end
+
+          ##
+          # @return [SoberSwag::Reporting::Input::Struct, SoberSwag::Reporting::Report::Base] the struct class,
+          #   or a report of what went wrong.
+          def call(attrs)
+            input_type.call(attrs)
+          end
+
+          ##
+          # @see #call
+          def parse(json)
+            call(json)
+          end
+
+          ##
+          # @see call!
+          def parse!(json)
+            call!(json)
+          end
+
+          ##
+          # @return [Array[Hash, Hash]] swagger schema type.
+          def swagger_schema
+            input_type.swagger_schema
+          end
+
+          def swagger_query_schema
+            object_type.swagger_query_schema
+          end
+
+          def swagger_path_schema
+            object_type.swagger_path_schema
+          end
+
+          private
+
+          def make_input_type(name, input, block)
+            raise ArgumentError, 'cannot pass a block to make a sub-struct and a field type' if input && block
+
+            return input if input
+
+            raise ArgumentError, 'must pass an input type OR a block to make a sub-struct' unless block
+
+            const_name = name.to_s.camelize
+
+            raise ArgumentError, 'cannot define struct sub-type, constant already exists!' if const_defined?(const_name)
+
+            Class.new(SoberSwag::Reporting::Input::Struct, &block).tap { |c| const_set(const_name, c) }
+          end
+
+          ##
+          # Quick method which defines an accessor method for this struct.
+          def define_attribute(name)
+            define_method(name) do
+              struct_properties[name]
+            end
+            define_method("#{name}_present?") do
+              struct_properties.key?(name)
+            end
+          end
+
+          def object_type
+            if parent_struct.nil?
+              Object.new(object_properties)
+            else
+              MergeObjects.new(parent_struct, Object.new(object_properties))
+            end
+          end
+        end
+
+        def initialize(props)
+          @struct_properties = props
+        end
+
+        attr_reader :struct_properties
+
+        def [](name)
+          @struct_properties[name]
+        end
+
+        ##
+        # Hash code for this struct.
+        def hash
+          [self.class.hash, *ordered_values.hash].hash
+        end
+
+        ##
+        # Return an array of the values of this, in order.
+        def ordered_values
+          self.class.object_properties.keys.map { |k| @struct_properties[k] }
+        end
+
+        ##
+        # Allow structs to be compared like values.
+        def eql?(other)
+          return false unless other.is_a?(self.class)
+
+          ordered_values.eql?(other.ordered_values)
+        end
+
+        ##
+        # Allow structs to be ordered like values.
+        def <=>(other)
+          return nil unless other.is_a?(self.class)
+
+          ordered_values <=> other.ordered_values
+        end
+
+        include Comparable
+
+        ##
+        # Extracts the transformed struct properties.
+        #
+        # Keys not present in the input will also not be present in this hash.
+        def to_h
+          @struct_properties.transform_values do |value|
+            if value.is_a?(SoberSwag::Reporting::Input::Struct)
+              value.to_h
+            else
+              value
+            end
+          end
+        end
+
+        def to_s
+          inspect
+        end
+
+        def inspect
+          keys = self.class.object_properties.keys.each.with_object([]) do |k, obj|
+            obj << "#{k}=#{public_send(k).inspect}" if public_send(:"#{k}_present?")
+          end
+          "#<#{self.class.name || self.class.inspect[2..-2]} #{keys.join(' ')}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Input for a single text value.
+      class Text < Base
+        def call(value)
+          return value if value.is_a?(String)
+
+          Report::Value.new(['was not a string'])
+        end
+
+        ##
+        # Get a new input value which requires a regexp.
+        #
+        # @paran regexp [Regexp] regular expression to match on
+        # @return [Pattern] pattern-based input.
+        def with_pattern(regexp)
+          Pattern.new(self, regexp)
+        end
+
+        include Comparable
+
+        def eql?(other)
+          other.class == self.class
+        end
+
+        def <=>(other)
+          eql?(other) ? 0 : 1
+        end
+
+        def hash
+          [self.class.hash, 1].hash
+        end
+
+        def swagger_schema
+          [{ type: 'string' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input.rb

@@ -0,0 +1,54 @@
+module SoberSwag
+  module Reporting
+    ##
+    # Module for SoberSwag reporting inputs.
+    module Input
+      autoload :Base, 'sober_swag/reporting/input/base'
+      autoload :Bool, 'sober_swag/reporting/input/bool'
+      autoload :Converting, 'sober_swag/reporting/input/converting'
+      autoload :Described, 'sober_swag/reporting/input/described'
+      autoload :Dictionary, 'sober_swag/reporting/input/dictionary'
+      autoload :Defer, 'sober_swag/reporting/input/defer'
+      autoload :Enum, 'sober_swag/reporting/input/enum'
+      autoload :Either, 'sober_swag/reporting/input/either'
+      autoload :Format, 'sober_swag/reporting/input/format'
+      autoload :Number, 'sober_swag/reporting/input/number'
+      autoload :Interface, 'sober_swag/reporting/input/interface'
+      autoload :List, 'sober_swag/reporting/input/list'
+      autoload :Mapped, 'sober_swag/reporting/input/mapped'
+      autoload :MergeObjects, 'sober_swag/reporting/input/merge_objects'
+      autoload :Null, 'sober_swag/reporting/input/null'
+      autoload :Object, 'sober_swag/reporting/input/object'
+      autoload :Pattern, 'sober_swag/reporting/input/pattern'
+      autoload :Referenced, 'sober_swag/reporting/input/referenced'
+      autoload :Struct, 'sober_swag/reporting/input/struct'
+      autoload :Text, 'sober_swag/reporting/input/text'
+
+      class << self
+        ##
+        # @return [SoberSwag::Reporting::Input::Bool]
+        def bool
+          Bool.new
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Input::Text]
+        def text
+          Text.new
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Input::Number]
+        def number
+          Number.new
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Input::Null]
+        def null
+          Null.new
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/invalid_schema_error.rb

@@ -0,0 +1,21 @@
+module SoberSwag
+  module Reporting
+    ##
+    # Thrown we cannot generate a swagger schema for some reason.
+    #
+    # This typically only occurs if you use types that are too complicated.
+    # For example, an object type cannot be used as part of the path params.
+    class InvalidSchemaError < StandardError
+      def initialize(input)
+        @input = input
+
+        super("Could not generate schema for #{input}")
+      end
+
+      attr_reader :input
+
+      class InvalidForPathError < InvalidSchemaError; end
+      class InvalidForQueryError < InvalidSchemaError; end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/base.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Base type for simple outputs.
+      class Base
+        include Interface
+
+        ##
+        # Acceptable views to use with this output.
+        #
+        # @return [Set<Symbol>] the views
+        def views
+          %i[base].to_set
+        end
+
+        def view(view_key)
+          return self if view_key == :base
+
+          raise ArgumentError, "#{view_key} is not a view" unless views.include?(view_key)
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output/bool.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output booleans.
+      class Bool < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not a boolean']) unless [true, false].include?(result)
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'boolean' }, {}]
+        end
+      end
+    end
+  end
+end