bcdd-result 0.12.0 → 0.13.0

data/lib/bcdd/result/transitions/listeners.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Transitions
+  class Listeners
+    class Chain
+      include Listener
+
+      attr_reader :listeners
+
+      def initialize(list)
+        if list.empty? || list.any? { !Listener.kind?(_1) }
+          raise ArgumentError, "listeners must be a list of #{Listener}"
+        end
+
+        around_and_then = list.select(&:around_and_then?)
+        around_transitions = list.select(&:around_transitions?)
+
+        raise ArgumentError, 'only one listener can have around_and_then? == true' if around_and_then.size > 1
+        raise ArgumentError, 'only one listener can have around_transitions? == true' if around_transitions.size > 1
+
+        @listeners = { list: list, around_and_then: around_and_then[0], around_transitions: around_transitions[0] }
+      end
+
+      def new
+        list, around_and_then, around_transitions = listeners[:list], nil, nil
+
+        instances = list.map do |item|
+          instance = item.new
+          around_and_then = instance if listener?(:around_and_then, instance)
+          around_transitions = instance if listener?(:around_transitions, instance)
+
+          instance
+        end
+
+        list.one? ? list[0].new : Listeners.send(:new, instances, around_and_then, around_transitions)
+      end
+
+      private
+
+      def listener?(name, obj)
+        listener = listeners[name]
+
+        !listener.nil? && (obj.is_a?(listener) || obj == listener)
+      end
+    end
+
+    private_class_method :new
+
+    def self.[](*listeners)
+      Chain.new(listeners)
+    end
+
+    attr_reader :listeners, :around_and_then_listener, :around_transitions_listener
+
+    private :listeners, :around_and_then_listener, :around_transitions_listener
+
+    def initialize(listeners, around_and_then_listener, around_transitions_listener)
+      @listeners = listeners
+      @around_and_then_listener = around_and_then_listener || Listener::Null
+      @around_transitions_listener = around_transitions_listener || Listener::Null
+    end
+
+    def on_start(scope:)
+      listeners.each { _1.on_start(scope: scope) }
+    end
+
+    def around_transitions(scope:, &block)
+      around_transitions_listener.around_transitions(scope: scope, &block)
+    end
+
+    def around_and_then(scope:, and_then:, &block)
+      around_and_then_listener.around_and_then(scope: scope, and_then: and_then, &block)
+    end
+
+    def on_record(record:)
+      listeners.each { _1.on_record(record: record) }
+    end
+
+    def on_finish(transitions:)
+      listeners.each { _1.on_finish(transitions: transitions) }
+    end
+
+    def before_interruption(exception:, transitions:)
+      listeners.each { _1.before_interruption(exception: exception, transitions: transitions) }
+    end
+  end
+end

data/lib/bcdd/result/transitions/tracking/disabled.rb

@@ -6,22 +6,10 @@ module BCDD::Result::Transitions
       EnsureResult[yield]
     end
 
-    def self.reset!; end
-
     def self.record(result); end
 
-    def self.record_and_then(_type, _data, _source)
+    def self.record_and_then(_type, _data)
       yield
     end
-
-    def self.reset_and_then!; end
-
-    class << self
-      private
-
-      def start(name, desc); end
-
-      def finish(result); end
-    end
   end
 end

data/lib/bcdd/result/transitions/tracking/enabled.rb

@@ -2,22 +2,36 @@
 
 module BCDD::Result::Transitions
   class Tracking::Enabled
-    attr_accessor :tree, :records, :root_started_at
+    attr_accessor :tree, :records, :root_started_at, :listener
 
-    private :tree, :tree=, :records, :records=, :root_started_at, :root_started_at=
+    private :tree, :tree=, :records, :records=, :root_started_at, :root_started_at=, :listener, :listener=
 
     def exec(name, desc)
-      start(name, desc)
+      transition_node, scope = start(name, desc)
 
-      transition_node = tree.current
+      result = nil
 
-      result = EnsureResult[yield]
+      listener.around_transitions(scope: scope) do
+        result = EnsureResult[yield]
+      end
 
       tree.move_to_root! if transition_node.root?
 
       finish(result)
 
       result
+    rescue ::Exception => e
+      err!(e, transition_node)
+    end
+
+    def err!(exception, transition_node)
+      if transition_node.root?
+        listener.before_interruption(exception: exception, transitions: map_transitions)
+
+        reset!
+      end
+
+      raise exception
     end
 
     def reset!
@@ -30,17 +44,23 @@ module BCDD::Result::Transitions
       track(result, time: ::Time.now.getutc)
     end
 
-    def record_and_then(type_arg, arg, source)
+    def record_and_then(type_arg, arg)
+      return yield if tree.frozen?
+
       type = type_arg.instance_of?(::Method) ? :method : type_arg
 
-      unless tree.frozen?
-        current_and_then = { type: type, arg: arg, source: source }
-        current_and_then[:method_name] = type_arg.name if type == :method
+      current_and_then = { type: type, arg: arg }
+      current_and_then[:method_name] = type_arg.name if type == :method
 
-        tree.current.value[1] = current_and_then
-      end
+      tree.current.value[1] = current_and_then
 
-      yield
+      scope, and_then = tree.current_value
+
+      result = nil
+
+      listener.around_and_then(scope: scope, and_then: and_then) { result = yield }
+
+      result
     end
 
     def reset_and_then!
@@ -55,6 +75,12 @@ module BCDD::Result::Transitions
       name_and_desc = [name, desc]
 
       tree.frozen? ? root_start(name_and_desc) : tree.insert!(name_and_desc)
+
+      scope = tree.current.value[0]
+
+      listener.on_start(scope: scope)
+
+      [tree.current, scope]
     end
 
     def finish(result)
@@ -64,11 +90,11 @@ module BCDD::Result::Transitions
 
       return unless node.root?
 
-      duration = (now_in_milliseconds - root_started_at)
+      transitions = map_transitions
 
-      metadata = { duration: duration, tree_map: tree.nested_ids }
+      result.send(:transitions=, transitions)
 
-      result.send(:transitions=, version: Tracking::VERSION, records: records, metadata: metadata)
+      listener.on_finish(transitions: transitions)
 
       reset!
     end
@@ -78,23 +104,56 @@ module BCDD::Result::Transitions
     def root_start(name_and_desc)
       self.root_started_at = now_in_milliseconds
 
+      self.listener = build_listener
+
       self.records = []
 
       self.tree = Tree.new(name_and_desc, normalizer: TreeNodeValueNormalizer)
     end
 
     def track(result, time:)
-      result = result.data.to_h
+      record = track_record(result, time)
+
+      records << record
+
+      listener.on_record(record: record)
+
+      record
+    end
+
+    def track_record(result, time)
+      result_data = result.data.to_h
+      result_data[:source] = result.send(:source)
 
       root, = tree.root_value
       parent, = tree.parent_value
       current, and_then = tree.current_value
 
-      records << { root: root, parent: parent, current: current, result: result, and_then: and_then, time: time }
+      { root: root, parent: parent, current: current, result: result_data, and_then: and_then, time: time }
     end
 
     def now_in_milliseconds
       ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
     end
+
+    def map_transitions
+      duration = (now_in_milliseconds - root_started_at)
+
+      trace_id = Config.instance.trace_id.call
+
+      metadata = { duration: duration, ids_tree: tree.nested_ids, ids_matrix: tree.ids_matrix, trace_id: trace_id }
+
+      { version: Tracking::VERSION, records: records, metadata: metadata }
+    end
+
+    def build_listener
+      Config.instance.listener.new
+    rescue ::StandardError => e
+      err = "#{e.message} (#{e.class}); Backtrace: #{e.backtrace&.join(', ')}"
+
+      warn("Fallback to #{Listener::Null} because registered listener raised an exception: #{err}")
+
+      Listener::Null.new
+    end
   end
 end

data/lib/bcdd/result/transitions/tracking.rb

@@ -6,14 +6,19 @@ class BCDD::Result
       require_relative 'tracking/enabled'
       require_relative 'tracking/disabled'
 
+      VERSION = 1
+
       EMPTY_ARRAY = [].freeze
       EMPTY_HASH = {}.freeze
       EMPTY_TREE = Tree.new(nil).freeze
-      VERSION = 1
-      EMPTY = { version: VERSION, records: EMPTY_ARRAY, metadata: { duration: 0, tree_map: EMPTY_ARRAY } }.freeze
+      EMPTY = {
+        version: VERSION,
+        records: EMPTY_ARRAY,
+        metadata: { duration: 0, ids_tree: EMPTY_ARRAY, ids_matrix: EMPTY_HASH, trace_id: nil }.freeze
+      }.freeze
 
       def self.instance
-        Config.instance.feature.enabled?(:transitions) ? Tracking::Enabled.new : Tracking::Disabled
+        ::BCDD::Result::Config.instance.feature.enabled?(:transitions) ? Tracking::Enabled.new : Tracking::Disabled
       end
     end
   end

data/lib/bcdd/result/transitions/tree.rb

@@ -94,6 +94,32 @@ class BCDD::Result
       def nested_ids
         NestedIds[root]
       end
+
+      IdsMatrix = ->(tree, row, col, ids, previous) do
+        last_row = previous[0]
+
+        tree.each_with_index do |node, index|
+          row = [(index + 1), last_row].max
+
+          id, leaf = node
+
+          ids[id] = previous == [row, col] ? [row, col + 1] : [row, col]
+
+          previous = ids[id]
+
+          IdsMatrix[leaf, row, col + 1, ids, previous]
+        end
+      end
+
+      def ids_matrix
+        current = [0, 0]
+
+        ids = { 0 => current }
+
+        IdsMatrix[nested_ids[1], 1, 1, ids, current]
+
+        ids
+      end
     end
   end
 end

data/lib/bcdd/result/transitions.rb

@@ -2,6 +2,9 @@
 
 class BCDD::Result
   module Transitions
+    require_relative 'transitions/listener'
+    require_relative 'transitions/listeners'
+    require_relative 'transitions/config'
     require_relative 'transitions/tree'
     require_relative 'transitions/tracking'
 
@@ -20,9 +23,5 @@ class BCDD::Result
 
   def self.transitions(name: nil, desc: nil, &block)
     Transitions.tracking.exec(name, desc, &block)
-  rescue ::Exception => e
-    Transitions.tracking.reset!
-
-    raise e
   end
 end

data/lib/bcdd/result/version.rb

@@ -2,6 +2,6 @@
 
 module BCDD
   class Result
-    VERSION = '0.12.0'
+    VERSION = '0.13.0'
   end
 end

data/lib/bcdd/result.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require 'set'
 require 'singleton'
 
 require_relative 'result/version'
 require_relative 'result/error'
+require_relative 'result/ignored_types'
 require_relative 'result/transitions'
 require_relative 'result/callable_and_then'
 require_relative 'result/data'
@@ -29,10 +31,10 @@ class BCDD::Result
     Config.instance
   end
 
-  def self.configuration
+  def self.configuration(freeze: true)
     yield(config)
 
-    config.freeze
+    freeze and config.freeze
   end
 
   def initialize(type:, value:, source: nil, expectations: nil, terminal: nil)
@@ -40,7 +42,7 @@ class BCDD::Result
 
     @type_checker = Contract.evaluate(data, expectations)
     @source = source
-    @terminal = terminal || kind == :failure
+    @terminal = kind == :failure || (terminal && !IgnoredTypes.include?(type))
     @data = data
 
     self.unknown = true
@@ -153,7 +155,7 @@ class BCDD::Result
   def call_and_then_source_method(method_name, injected_value)
     method = source.method(method_name)
 
-    Transitions.tracking.record_and_then(method, injected_value, source) do
+    Transitions.tracking.record_and_then(method, injected_value) do
       result = call_and_then_source_method!(method, injected_value)
 
       ensure_result_object(result, origin: :method)
@@ -170,7 +172,7 @@ class BCDD::Result
   end
 
   def call_and_then_block(block)
-    Transitions.tracking.record_and_then(:block, nil, source) do
+    Transitions.tracking.record_and_then(:block, nil) do
       result = call_and_then_block!(block)
 
       ensure_result_object(result, origin: :block)

data/sig/bcdd/result/config.rbs

@@ -15,6 +15,7 @@ class BCDD::Result::Config
   def initialize: -> void
 
   def and_then!: () -> BCDD::Result::CallableAndThen::Config
+  def transitions: () -> BCDD::Result::Transitions::Config
 
   def freeze: -> BCDD::Result::Config
   def options: -> Hash[Symbol, BCDD::Result::Config::Switcher]

data/sig/bcdd/result/context.rbs

@@ -28,10 +28,19 @@ class BCDD::Result::Context < BCDD::Result
   def raise_unexpected_outcome_error: (BCDD::Result::Context | untyped, Symbol) -> void
 end
 
+class BCDD::Result::Context
+  class Error < BCDD::Result::Error
+    class InvalidExposure < BCDD::Result::Context::Error
+    end
+  end
+end
+
 class BCDD::Result::Context
   class Success < BCDD::Result::Context
     include BCDD::Result::Success::Methods
 
+    FetchValues: Proc
+
     def and_expose: (Symbol, Array[Symbol], terminal: bool) -> BCDD::Result::Context::Success
   end
 

data/sig/bcdd/result/ignored_types.rbs

@@ -0,0 +1,9 @@
+class BCDD::Result
+  module IgnoredTypes
+    LIST: ::Set[::Symbol]
+    GIVEN: ::Symbol
+    CONTINUE: ::Symbol
+
+    def self.include?: (::Symbol) -> bool
+  end
+end

data/sig/bcdd/result/transitions.rbs

@@ -1,5 +1,82 @@
 class BCDD::Result
   module Transitions
+    module Listener
+      module ClassMethods
+        def around_and_then?: () -> bool
+        def around_transitions?: () -> bool
+      end
+
+      extend ClassMethods
+
+      def around_transitions: (scope: Hash[Symbol, untyped]) { () -> untyped } -> untyped
+
+      def on_start: (scope: Hash[Symbol, untyped]) -> untyped
+
+      def around_and_then: (scope: Hash[Symbol, untyped], and_then: Hash[Symbol, untyped]) { () -> untyped } -> untyped
+
+      def on_record: (record: Hash[Symbol, untyped] ) -> untyped
+
+      def on_finish: (transitions: Hash[Symbol, untyped] ) -> untyped
+
+      def before_interruption: (exception: ::Exception, transitions: Hash[Symbol, untyped]) -> untyped
+    end
+
+    class Listeners
+      class Chain
+        include Listener
+
+        attr_reader listeners: Hash[Symbol, untyped]
+
+        def initialize: (Array[untyped]) -> void
+
+        def new: () -> Listeners
+
+        private
+
+        def listener?: (untyped, untyped) -> bool
+      end
+
+      def self.[]: (*untyped) -> Chain
+
+      private attr_reader listeners: Array[Listener]
+      private attr_reader around_and_then_listener: untyped
+      private attr_reader around_transitions_listener: untyped
+
+      def initialize: (Array[Listener], untyped, untyped) -> void
+
+      def around_transitions: (scope: Hash[Symbol, untyped]) { () -> untyped } -> untyped
+
+      def on_start: (scope: Hash[Symbol, untyped]) -> untyped
+
+      def around_and_then: (scope: Hash[Symbol, untyped], and_then: Hash[Symbol, untyped]) { () -> untyped } -> untyped
+
+      def on_record: (record: Hash[Symbol, untyped] ) -> untyped
+
+      def on_finish: (transitions: Hash[Symbol, untyped] ) -> untyped
+
+      def before_interruption: (exception: ::Exception, transitions: Hash[Symbol, untyped]) -> untyped
+    end
+
+    module Listener::Null
+      extend Listener
+
+      def self.new: () -> untyped
+    end
+
+    class Config
+      include ::Singleton
+
+      attr_reader listener: untyped
+      attr_reader trace_id: ::Proc
+
+      def self.instance: -> Config
+
+      def initialize: -> void
+
+      def listener=: (Listener) -> void
+      def trace_id=: (::Proc) -> void
+    end
+
     class Tree
       class Node
         attr_reader id: Integer
@@ -41,6 +118,10 @@ class BCDD::Result
       NestedIds: ^(Node) -> Array[untyped]
 
       def nested_ids: () -> Array[untyped]
+
+      IdsMatrix: ::Proc
+
+      def ids_matrix: () -> untyped
     end
 
     module Tracking
@@ -53,39 +134,47 @@ class BCDD::Result
       class Enabled
         private attr_accessor tree: Transitions::Tree
         private attr_accessor records: Array[Hash[Symbol, untyped]]
+        private attr_accessor listener: untyped
         private attr_accessor root_started_at: Integer
 
-        def exec: (String, String) { () -> untyped } -> BCDD::Result
+        def exec: (untyped, untyped) { () -> untyped } -> untyped
+        def err!: (::Exception, untyped) -> void
         def reset!: () -> void
         def record: (BCDD::Result) -> void
-        def record_and_then: ((untyped), untyped, untyped) { () -> BCDD::Result } -> BCDD::Result
+        def record_and_then: ((untyped), untyped) { () -> untyped } -> untyped
         def reset_and_then!: () -> void
 
         private
 
-        def start: (String, String) -> void
-        def finish: (BCDD::Result) -> void
+        def start: (String, String) -> [Transitions::Tree::Node, Hash[Symbol, untyped]]
+        def finish: (untyped) -> untyped
 
         TreeNodeValueNormalizer: ^(Integer, Array[untyped]) -> untyped
 
         def root_start: (Array[untyped]) -> void
 
         def track: (BCDD::Result, time: Time) -> void
+        def track_record: (BCDD::Result, Time) -> Hash[Symbol, untyped]
 
         def now_in_milliseconds: () -> Integer
+
+        def map_transitions: () -> Hash[Symbol, untyped]
+
+        def build_listener: () -> Listener
       end
 
       module Disabled
-        def self.exec: (String, String) { () -> untyped } -> BCDD::Result
+        def self.exec: (untyped, untyped) { () -> untyped } -> untyped
+        def self.err!: (::Exception) -> void
         def self.reset!: () -> void
         def self.record: (BCDD::Result) -> void
-        def self.record_and_then: ((untyped), untyped, untyped) { () -> BCDD::Result } -> BCDD::Result
+        def self.record_and_then: ((untyped), untyped) { () -> BCDD::Result } -> BCDD::Result
         def self.reset_and_then!: () -> void
 
         private
 
         def self.start: (String, String) -> void
-        def self.finish: (BCDD::Result) -> void
+        def self.finish: (untyped) -> untyped
       end
 
       def self.instance: () -> (Enabled | singleton(Disabled))

data/sig/bcdd/result.rbs

@@ -9,8 +9,8 @@ class BCDD::Result
   attr_reader transitions: Hash[Symbol, untyped]
 
   def self.config: -> BCDD::Result::Config
-  def self.configuration: { (BCDD::Result::Config) -> void } -> BCDD::Result::Config
-  def self.transitions: { () -> untyped } -> BCDD::Result
+  def self.configuration: (freeze: bool) { (BCDD::Result::Config) -> void } -> (bool | BCDD::Result::Config)
+  def self.transitions: (name: untyped, desc: untyped) { () -> untyped } -> BCDD::Result
 
   def initialize: (
     type: Symbol,