sober_swag 0.21.0 → 0.22.0

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

@@ -0,0 +1,42 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Referenced: An input that will be referred to via reference in the
+      # final schema.
+      class Referenced < Base
+        def initialize(output, reference)
+          @output = output
+          @reference = reference
+        end
+
+        ##
+        # @return [Interface] the actual output type to use
+        attr_reader :output
+
+        ##
+        # @return [String] key in the components hash
+        attr_reader :reference
+
+        def call(input)
+          output.call(input)
+        end
+
+        def serialize_report(input)
+          output.serialize_report(input)
+        end
+
+        def ref_path
+          "#/components/schemas/#{reference}"
+        end
+
+        def swagger_schema
+          [
+            { "$ref": ref_path },
+            { reference => proc { output.swagger_schema } }
+          ]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,262 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # A DSL for building "output object structs."
+      class Struct # rubocop:disable Metrics/ClassLength
+        class << self
+          include Interface
+
+          ##
+          # Define a new field to be serialized.
+          #
+          # @param name [Symbol] name of this field.
+          # @param output [Interface] reporting output to use to serialize.
+          # @param description [String,nil] description for this field.
+          # @param block [Proc, nil]
+          #   If a block is given, it will be defined as a method on the output object struct.
+          #   If the block takes an argument, the object being serialized will be passed to it.
+          #   Otherwise, it will be accessible as `#object_to_serialize` from within the body.
+          #
+          #   You can access other methods from this method.
+          def field(name, output, description: nil, &extract)
+            define_field(name, extract)
+
+            object_fields[name] = Object::Property.new(
+              output.view(:base).via_map(&name.to_proc),
+              description: description
+            )
+          end
+
+          def object_output
+            base = Object.new(object_fields).via_map { |o| new(o) }
+            if description
+              base.described(description)
+            else
+              base
+            end
+          end
+
+          ##
+          # Set a description for the *type* of this output.
+          # It will show up as a description in the component key for this output.
+          # Right now that unfortunately will not render with ReDoc, but it should eventually.
+          #
+          # @param val [String, nil] pass if you want to set, otherwise you will get the current value
+          # @return [String] the description assigned to this object, if any.
+          def description(val = nil)
+            return @description unless val
+
+            @description = val
+          end
+
+          ##
+          # An output for this specific schema type.
+          # If this schema has any views, it will be defined as a map of possible views to the actual views used.
+          # Otherwise, it will directly be the base definition.
+          def single_output
+            single =
+              if view_map.any?
+                Viewed.new(identified_view_map)
+              else
+                inherited_output
+              end
+            identifier ? single.referenced(identifier) : single
+          end
+
+          ##
+          # Used to generate 'allOf' subtyping relationships.
+          # Probably do not call this yourself.
+          #
+          # @return [Interface]
+          def identified_with_base
+            object_output.referenced([identifier, 'Base'].join('.'))
+          end
+
+          ##
+          # Used to generate 'allOf' subtyping relationships.
+          # Probably do not call this yourself.
+          def identified_without_base
+            if parent_struct
+              MergeObjects
+                .new(parent_struct.inherited_output, object_output)
+            else
+              object_output
+            end.referenced(identifier)
+          end
+
+          ##
+          # Used to generate 'allOf' subtyping relationships.
+          # Probably do not call this yourself!
+          # Use {#single_output} instead.
+          #
+          # This allows us to implement *inheritance*.
+          # So, if you inherit from another output object struct, you get its methods and attributes.
+          # Views behave as if they have inherited the base object.
+          #
+          # This means that any views added to any parent output objects *will* be visible in children.
+          # @return [Interface]
+          def inherited_output
+            inherited =
+              if parent_struct
+                MergeObjects
+                  .new(parent_struct.inherited_output, object_output)
+              else
+                object_output
+              end
+
+            identifier ? inherited.referenced([identifier, 'Base'].join('.')) : inherited
+          end
+
+          ##
+          # Schema for this output.
+          # Will include views, if applicable.
+          def swagger_schema
+            single_output.swagger_schema
+          end
+
+          ##
+          # Serialize an object to a hash.
+          #
+          # @param value [Object] value to serialize
+          # @param view [Symbol] which view to use to serialize this output.
+          # @return [Hash] the serialized ruby hash, suitable for passing to JSON.generate
+          def call(value, view: :base)
+            view(view).output.call(value)
+          end
+
+          ##
+          # Serialize an object to a hash, with type-checking.
+          #
+          # @param value [Object] value to serialize
+          # @param view [Symbol] which view to use
+          # @return [Hash] the serialized ruby hash, suitable for passsing to JSON.generate
+          def serialize_report(value, view: :base)
+            view(view).output.serialize_report(value)
+          end
+
+          ##
+          # @return [Hash<Symbol, Object::Property>] the properties defined *directly* on this object.
+          #   Does not include inherited fields!
+          def object_fields
+            @object_fields ||= {}
+          end
+
+          ##
+          # Define a view for this object.
+          #
+          # Views behave like their own output structs, which inherit the parent (or 'base' view).
+          # This means that fields *after* the definition of a view *will be present in the view*.
+          # This enables views to maintain a subtyping relationship.
+          #
+          # Your base view should thus serialize *as little as possible*.
+          #
+          # View classes get defined as child constants.
+          # So, if I write `define_view(:foo)` on a struct called `Person`,
+          # I will get `Person::Foo` as a class I can use if I want!
+          #
+          # @param name [Symbol] name of this view.
+          # @yieldself [self] a block in which you can add more fields to the view.
+          # @return [Class]
+          def define_view(name, &block) # rubocop:disable Metrics/MethodLength
+            raise ArgumentError, "duplicate view #{name}" if name == :base || views.include?(name)
+
+            classy_name = name.to_s.classify
+
+            Class.new(self).tap do |c|
+              c.instance_eval(&block)
+              c.define_singleton_method(:define_view) do |*|
+                raise ArgumentError, 'no nesting views'
+              end
+              c.define_singleton_method(:identifier) do
+                [parent_struct.identifier, classy_name.gsub('::', '.')].join('.')
+              end
+              const_set(classy_name, c)
+              view_map[name] = c
+            end
+          end
+
+          ##
+          # @return Hash<Symbol,Class> map of potential views.
+          #   Does not include the 'base' view.
+          def view_map
+            @view_map ||= {}
+          end
+
+          ##
+          # @return [Set<Symbol>] all applicable views.
+          #   Will always include `:base`.
+          def views
+            [:base, *view_map.keys].to_set
+          end
+
+          ##
+          # @param name [Symbol] which view to use.
+          # @return [Interface] a serializer suitable for this interface.
+          def view(name)
+            return inherited_output if name == :base
+
+            view_map.fetch(name).view(:base)
+          end
+
+          attr_accessor :parent_struct
+
+          ##
+          # When this class is inherited, it sets up a future subtyping relationship.
+          # This gets expressed with 'allOf' in the generated swagger.
+          def inherited(other)
+            other.parent_struct = self unless self == ::SoberSwag::Reporting::Output::Struct
+          end
+
+          ##
+          # Set a new identifier for this output object.
+          #
+          # @param value [String, nil] provide a new identifier to use.
+          #   Stateful operation.
+          # @return [String] identifier key to use in the components hash.
+          #   In rare cases (a class with no name and no set identifier) it can return nil.
+          #   We consider this case "unsupported", IE, please do not do that.
+          def identifier(value = nil)
+            if value
+              @identifier = value
+            else
+              @identifier || name&.gsub('::', '.')
+            end
+          end
+
+          private
+
+          def identified_view_map
+            view_map.transform_values(&:identified_without_base).merge(base: inherited_output)
+          end
+
+          def define_field(method, extractor)
+            e =
+              if extractor.nil?
+                proc { _struct_serialized.public_send(method) }
+              elsif extractor.arity == 1
+                proc { extractor.call(_struct_serialized) }
+              else
+                extractor
+              end
+
+            define_method(method, &e)
+          end
+        end
+
+        def initialize(struct_serialized)
+          @_struct_serialized = struct_serialized
+        end
+
+        attr_reader :_struct_serialized
+
+        ##
+        # The object to serialize.
+        # Use this if you're defining your own methods.
+        def object_to_serialize
+          @_struct_serialized
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Output raw text.
+      class Text < Base
+        def call(input)
+          input
+        end
+
+        def serialize_report(input)
+          result = call(input)
+
+          return Report::Value.new(['was not a string']) unless result.is_a?(String)
+
+          result
+        end
+
+        def swagger_schema
+          [{ type: 'string' }, {}]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Apply a mapping function before calling
+      # a base output.
+      #
+      # Note that this is applied *before* the base output.
+      # This is different than {SoberSwag::Reporting::Input::Mapped}, which does the reverse.
+      # IE, this class does `call block -> pass result to base output`,
+      # while the other does `call serializer -> pass result to block`.
+      #
+      # If you want to get *really* nerdy, this is *contravariant* to `Mapped`.
+      #
+      # This lets you do things like making an output that serializes to strings via `to_s`:
+      #
+      # ```ruby
+      # ToSTextOutput = SoberSwag::Reporting::Output::ViaMap.new(
+      #   SoberSwag::Reporting::Output.text,
+      #   proc { |arg| arg.to_s }
+      # )
+      #
+      # class Person
+      #   def to_s
+      #     'Person'
+      #   end
+      # end
+      #
+      # ToSTextOutput.call(Person.new) # => 'Person'
+      # ```
+      class ViaMap < Base
+        def initialize(output, mapper)
+          @output = output
+          @mapper = mapper
+        end
+
+        ##
+        # @return [Interface] base output
+        attr_reader :output
+
+        ##
+        # @return [#call] mapping function
+        attr_reader :mapper
+
+        def call(input)
+          output.call(mapper.call(input))
+        end
+
+        def serialize_report(input)
+          output.serialize_report(mapper.call(input))
+        end
+
+        def view(view)
+          ViaMap.new(output.view(view), mapper)
+        end
+
+        def views
+          output.views
+        end
+
+        def swagger_schema
+          output.swagger_schema
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+module SoberSwag
+  module Reporting
+    module Output
+      ##
+      # Augment outputs with the ability to select views.
+      # This models a 'oneOf' relationship, where the choice picked is controlled by the 'view' parameter.
+      #
+      # This is "optional choice," in the sense that you *must* provide a default `:base` key.
+      # This key will be used in almost all cases.
+      class Viewed < Base
+        ##
+        # @param views [Hash<Symbol,Interface>] a map of view key to view.
+        #   Note: this map *must* include the base view.
+        def initialize(views)
+          @view_map = views
+
+          raise ArgumentError, 'views must have a base key' unless views.key?(:base)
+        end
+
+        attr_reader :view_map
+
+        ##
+        # Serialize out an object.
+        # If the view key is not provided, use the base view.
+        #
+        # @param input [Object] object to serialize
+        # @param view [Symbol] which view to use.
+        #   If view is not valid, an exception will be thrown
+        # @raise [KeyError] if view is not valid
+        # @return [Object,String,Array,Numeric] JSON-serializable object.
+        #   Suitable for use with #to_json.
+        def call(input, view: :base)
+          view(view).call(input)
+        end
+
+        def serialize_report(input)
+          view(:base).call(input)
+        end
+
+        ##
+        # Get a view with a particular key.
+        def view(view)
+          view_map.fetch(view)
+        end
+
+        ##
+        # @return [Set<Symbol>] all of the views applicable.
+        def views
+          view_map.keys.to_set
+        end
+
+        ##
+        # Add (or override) the possible views.
+        #
+        # @return [Viewed] a new view map, with one more view.
+        def with_view(name, val)
+          Viewed.new(views.merge(name => val))
+        end
+
+        def swagger_schema
+          found = {}
+          possibles = view_map.values.flat_map do |v|
+            view_item, view_found = v.swagger_schema
+            found.merge!(view_found)
+            view_item[:oneOf] || [view_item]
+          end
+          [{ oneOf: possibles }, found]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/output.rb

@@ -0,0 +1,54 @@
+module SoberSwag
+  module Reporting
+    ##
+    # Reporting outputs.
+    #
+    # These outputs can tell you what their acceptable views are.
+    module Output
+      autoload(:Base, 'sober_swag/reporting/output/base')
+      autoload(:Bool, 'sober_swag/reporting/output/bool')
+      autoload(:Defer, 'sober_swag/reporting/output/defer')
+      autoload(:Described, 'sober_swag/reporting/output/described')
+      autoload(:Dictionary, 'sober_swag/reporting/output/dictionary')
+      autoload(:Interface, 'sober_swag/reporting/output/interface')
+      autoload(:List, 'sober_swag/reporting/output/list')
+      autoload(:MergeObjects, 'sober_swag/reporting/output/merge_objects')
+      autoload(:Null, 'sober_swag/reporting/output/null')
+      autoload(:Number, 'sober_swag/reporting/output/number')
+      autoload(:Object, 'sober_swag/reporting/output/object')
+      autoload(:Partitioned, 'sober_swag/reporting/output/partitioned')
+      autoload(:Pattern, 'sober_swag/reporting/output/pattern')
+      autoload(:Referenced, 'sober_swag/reporting/output/referenced')
+      autoload(:Struct, 'sober_swag/reporting/output/struct')
+      autoload(:Text, 'sober_swag/reporting/output/text')
+      autoload(:ViaMap, 'sober_swag/reporting/output/via_map')
+      autoload(:Viewed, 'sober_swag/reporting/output/viewed')
+
+      class << self
+        ##
+        # @return [SoberSwag::Reporting::Output::Bool]
+        def bool
+          Bool.new
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Output::Number]
+        def number
+          Number.new
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Output::Text]
+        def text
+          Text.new
+        end
+
+        ##
+        # @return [SoberSwag::Reporting::Output::Null]
+        def null
+          Null.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Base class for SoberSwag reports.
+      #
+      # These reports are what make these serializers and parsers *reporting*: they provide errors.
+      # For outputs, these are errors encountered during serialization, IE,
+      # places where we lied about what type we were going to serialize.
+      # This is mostly used for testing.
+      #
+      # For parsers, these are encountered during *parsing*.
+      # This can be easily converted into a hash of JSON path objects to individual errors,
+      # enabling developers to more easily see what's gone wrong.
+      class Base
+        ##
+        # @return [Array<[String]>]
+        #   An array of error paths and error components, in the form of:
+        #
+        #   ```ruby
+        #     [
+        #       'foo.bar: was bad',
+        #       'foo.bar: was even worse'
+        #     ]
+        #   ```
+        def full_errors
+          each_error.map do |k, v|
+            [k, v].reject(&:blank?).join(': ')
+          end
+        end
+
+        ##
+        # Get a hash where each key is a JSON path, and each value is an array of errors for that path.
+        # @return [Hash<String,Array<String>>] hash of JSON path to errors
+        def path_hash
+          Hash.new { |h, k| h[k] = [] }.tap do |hash|
+            each_error do |k, v|
+              hash["$#{k}"] << v
+            end
+          end
+        end
+
+        ##
+        # @overload each_error() { |path, val| nil }
+        #   Yields each error to the block.
+        #   @yield [path, val] the JSON path to the error, and an error string
+        #   @yieldparam [String, String]
+        # @overload each_error()
+        #   @return [Enumerable<String, String>] an enum of two values: error keys and error values.
+        #     Note: the same key can potentially occur more than once!
+        def each_error
+          return enum_for(:each_error) unless block_given?
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/report/either.rb

@@ -0,0 +1,36 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Models either one set of errors or another.
+      # Will enumerate them in order with #each_error
+      class Either < Base
+        def initialize(lhs, rhs)
+          @lhs = lhs
+          @rhs = rhs
+        end
+
+        ##
+        # @return [Base] left reports
+        attr_reader :lhs
+        ##
+        # @return [Base] right reports
+        attr_reader :rhs
+
+        # rubocop:disable Style/ExplicitBlockArgument
+        def each_error
+          return enum_for(:each_error) unless block_given?
+
+          lhs.each_error do |key, value|
+            yield key, value
+          end
+
+          rhs.each_error do |key, value|
+            yield key, value
+          end
+        end
+        # rubocop:enable Style/ExplicitBlockArgument
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/report/error.rb

@@ -0,0 +1,15 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Exception thrown when used with {Reporting::Input::Interface#call!}.
+      class Error < StandardError
+        def initialize(report)
+          @report = report
+        end
+
+        attr_reader :report
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Report errors that arose while parsing a list.
+      class List < Base
+        ##
+        # @param element [Hash<Int, Base>] a hash of bad element indices to bad
+        #   element values
+        def initialize(elements)
+          @elements = elements
+        end
+
+        attr_reader :elements
+
+        def each_error
+          return enum_for(:each_error) unless block_given?
+
+          elements.each do |k, v|
+            v.each_error do |nested, err|
+              yield ["[#{k}]", nested].reject(&:nil?).join(''), err
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/report/merged_object.rb

@@ -0,0 +1,25 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Report on problems with a merged object.
+      class MergedObject < Base
+        def initialize(parent, child)
+          @parent = parent
+          @child = child
+        end
+
+        attr_reader :parent, :child
+
+        def each_error
+          return enum_for(:each_error) unless block_given?
+
+          # rubocop:disable Style/ExplicitBlockArgument
+          parent.each_error { |k, v| yield k, v }
+          child.each_error { |k, v| yield k, v }
+          # rubocop:enable Style/ExplicitBlockArgument
+        end
+      end
+    end
+  end
+end