sober_swag 0.21.0 → 0.24.0

data/lib/sober_swag/reporting/output.rb

@@ -0,0 +1,56 @@
+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(:InRange, 'sober_swag/reporting/output/in_range')
+      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(:Enum, 'sober_swag/reporting/output/enum')
+      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

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

@@ -0,0 +1,29 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Report on problems with an object.
+      class Object < Base
+        ##
+        # @param problems [Hash<Symbol, Report::Base>] the problems with each value.
+        def initialize(problems)
+          @problems = problems
+        end
+
+        ##
+        # @return [Hash] the hash being reported on
+        attr_reader :problems
+
+        def each_error
+          return enum_for(:each_error) unless block_given?
+
+          problems.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/output.rb

@@ -0,0 +1,14 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Output suitable to serialize an instance of {SoberSwag::Reporting::Report::Base} to
+      # a nice key-value thing.
+      Output = SoberSwag::Reporting::Output::Dictionary.of(
+        SoberSwag::Reporting::Output::List.new(
+          SoberSwag::Reporting::Output.text
+        )
+      ).via_map(&:path_hash)
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Report for a single value.
+      # Basically a wrapper around an array of strings.
+      class Value < Base
+        ##
+        # @param problems [Array<String>] problems with it
+        def initialize(problems)
+          @problems = problems
+        end
+
+        ##
+        # @return [Array<String>] the problems the value had
+        attr_reader :problems
+
+        def each_error
+          return enum_for(:each_error) unless block_given?
+
+          problems.each do |problem|
+            yield nil, problem
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/report.rb

@@ -0,0 +1,16 @@
+module SoberSwag
+  module Reporting
+    ##
+    # Namespace modules for the various "reporters," or things that provide error handling.
+    module Report
+      autoload :Base, 'sober_swag/reporting/report/base'
+      autoload :Either, 'sober_swag/reporting/report/either'
+      autoload :Error, 'sober_swag/reporting/report/error'
+      autoload :Object, 'sober_swag/reporting/report/object'
+      autoload :Output, 'sober_swag/reporting/report/output'
+      autoload :MergedObject, 'sober_swag/reporting/report/merged_object'
+      autoload :Value, 'sober_swag/reporting/report/value'
+      autoload :List, 'sober_swag/reporting/report/list'
+    end
+  end
+end

data/lib/sober_swag/reporting.rb

@@ -0,0 +1,11 @@
+module SoberSwag
+  ##
+  # A new module for parsers with better error reporting.
+  module Reporting
+    autoload :Input, 'sober_swag/reporting/input'
+    autoload :Report, 'sober_swag/reporting/report'
+    autoload :Output, 'sober_swag/reporting/output'
+    autoload :Compiler, 'sober_swag/reporting/compiler'
+    autoload :InvalidSchemaError, 'sober_swag/reporting/invalid_schema_error'
+  end
+end

data/lib/sober_swag/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SoberSwag
-  VERSION = '0.21.0'
+  VERSION = '0.24.0'
 end

data/lib/sober_swag.rb

@@ -24,6 +24,7 @@ module SoberSwag
   autoload :InputObject, 'sober_swag/input_object'
   autoload :Server, 'sober_swag/server'
   autoload :Type, 'sober_swag/type'
+  autoload :Reporting, 'sober_swag/reporting'
 
   ##
   # Define a struct of something.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sober_swag
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Anthony Super
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-02 00:00:00.000000000 Z
+date: 2022-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -193,6 +193,7 @@ files:
 - bin/console
 - bin/rspec
 - bin/setup
+- docs/reporting.md
 - docs/serializers.md
 - example/.gitignore
 - example/.rspec
@@ -210,12 +211,15 @@ files:
 - example/app/models/concerns/.keep
 - example/app/models/person.rb
 - example/app/models/post.rb
+- example/app/output_objects/identified_output.rb
 - example/app/output_objects/person_errors_output_object.rb
 - example/app/output_objects/person_output_object.rb
 - example/app/output_objects/post_output_object.rb
+- example/app/output_objects/reporting_post_output.rb
 - example/bin/bundle
 - example/bin/rails
 - example/bin/rake
+- example/bin/rspec
 - example/bin/setup
 - example/bin/spring
 - example/config.ru
@@ -283,6 +287,69 @@ files:
 - lib/sober_swag/output_object/field_syntax.rb
 - lib/sober_swag/output_object/view.rb
 - lib/sober_swag/parser.rb
+- lib/sober_swag/reporting.rb
+- lib/sober_swag/reporting/compiler.rb
+- lib/sober_swag/reporting/input.rb
+- lib/sober_swag/reporting/input/base.rb
+- lib/sober_swag/reporting/input/bool.rb
+- lib/sober_swag/reporting/input/converting.rb
+- lib/sober_swag/reporting/input/converting/bool.rb
+- lib/sober_swag/reporting/input/converting/date.rb
+- lib/sober_swag/reporting/input/converting/date_time.rb
+- lib/sober_swag/reporting/input/converting/decimal.rb
+- lib/sober_swag/reporting/input/converting/integer.rb
+- lib/sober_swag/reporting/input/defer.rb
+- lib/sober_swag/reporting/input/described.rb
+- lib/sober_swag/reporting/input/dictionary.rb
+- lib/sober_swag/reporting/input/either.rb
+- lib/sober_swag/reporting/input/enum.rb
+- lib/sober_swag/reporting/input/format.rb
+- lib/sober_swag/reporting/input/in_range.rb
+- lib/sober_swag/reporting/input/interface.rb
+- lib/sober_swag/reporting/input/list.rb
+- lib/sober_swag/reporting/input/mapped.rb
+- lib/sober_swag/reporting/input/merge_objects.rb
+- lib/sober_swag/reporting/input/multiple_of.rb
+- lib/sober_swag/reporting/input/null.rb
+- lib/sober_swag/reporting/input/number.rb
+- lib/sober_swag/reporting/input/object.rb
+- lib/sober_swag/reporting/input/object/property.rb
+- lib/sober_swag/reporting/input/pattern.rb
+- lib/sober_swag/reporting/input/referenced.rb
+- lib/sober_swag/reporting/input/struct.rb
+- lib/sober_swag/reporting/input/text.rb
+- lib/sober_swag/reporting/invalid_schema_error.rb
+- lib/sober_swag/reporting/output.rb
+- lib/sober_swag/reporting/output/base.rb
+- lib/sober_swag/reporting/output/bool.rb
+- lib/sober_swag/reporting/output/defer.rb
+- lib/sober_swag/reporting/output/described.rb
+- lib/sober_swag/reporting/output/dictionary.rb
+- lib/sober_swag/reporting/output/enum.rb
+- lib/sober_swag/reporting/output/in_range.rb
+- lib/sober_swag/reporting/output/interface.rb
+- lib/sober_swag/reporting/output/list.rb
+- lib/sober_swag/reporting/output/merge_objects.rb
+- lib/sober_swag/reporting/output/null.rb
+- lib/sober_swag/reporting/output/number.rb
+- lib/sober_swag/reporting/output/object.rb
+- lib/sober_swag/reporting/output/object/property.rb
+- lib/sober_swag/reporting/output/partitioned.rb
+- lib/sober_swag/reporting/output/pattern.rb
+- lib/sober_swag/reporting/output/referenced.rb
+- lib/sober_swag/reporting/output/struct.rb
+- lib/sober_swag/reporting/output/text.rb
+- lib/sober_swag/reporting/output/via_map.rb
+- lib/sober_swag/reporting/output/viewed.rb
+- lib/sober_swag/reporting/report.rb
+- lib/sober_swag/reporting/report/base.rb
+- lib/sober_swag/reporting/report/either.rb
+- lib/sober_swag/reporting/report/error.rb
+- lib/sober_swag/reporting/report/list.rb
+- lib/sober_swag/reporting/report/merged_object.rb
+- lib/sober_swag/reporting/report/object.rb
+- lib/sober_swag/reporting/report/output.rb
+- lib/sober_swag/reporting/report/value.rb
 - lib/sober_swag/serializer.rb
 - lib/sober_swag/serializer/array.rb
 - lib/sober_swag/serializer/base.rb