bcdd-result 0.9.1 → 0.11.0

data/lib/bcdd/result/config/switchers/features.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    module Features
+      OPTIONS = {
+        expectations: {
+          default: true,
+          affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+        },
+        transitions: {
+          default: true,
+          affects: %w[BCDD::Result BCDD::Result::Context]
+        }
+      }.transform_values!(&:freeze).freeze
+
+      Listener = ->(option_name, _bool) do
+        Thread.current[Transitions::THREAD_VAR_NAME] = nil if option_name == :transitions
+      end
+
+      def self.switcher
+        Switcher.new(options: OPTIONS, listener: Listener)
+      end
+    end
+
+    private_constant :Features
+  end
+end

data/lib/bcdd/result/config/switchers/pattern_matching.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  class Config
+    module PatternMatching
+      OPTIONS = {
+        nil_as_valid_value_checking: {
+          default: false,
+          affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
+        }
+      }.transform_values!(&:freeze).freeze
+
+      def self.switcher
+        Switcher.new(options: OPTIONS)
+      end
+    end
+
+    private_constant :PatternMatching
+  end
+end

data/lib/bcdd/result/config.rb

@@ -4,40 +4,22 @@ require 'singleton'
 
 require_relative 'config/options'
 require_relative 'config/switcher'
-require_relative 'config/constant_alias'
+require_relative 'config/switchers/addons'
+require_relative 'config/switchers/constant_aliases'
+require_relative 'config/switchers/features'
+require_relative 'config/switchers/pattern_matching'
 
 class BCDD::Result
   class Config
     include Singleton
 
-    ADDON = {
-      continue: {
-        default: false,
-        affects: %w[BCDD::Result BCDD::Result::Context BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-      }
-    }.transform_values!(&:freeze).freeze
-
-    FEATURE = {
-      expectations: {
-        default: true,
-        affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-      }
-    }.transform_values!(&:freeze).freeze
-
-    PATTERN_MATCHING = {
-      nil_as_valid_value_checking: {
-        default: false,
-        affects: %w[BCDD::Result::Expectations BCDD::Result::Context::Expectations]
-      }
-    }.transform_values!(&:freeze).freeze
-
     attr_reader :addon, :feature, :constant_alias, :pattern_matching
 
     def initialize
-      @addon = Switcher.new(options: ADDON)
-      @feature = Switcher.new(options: FEATURE)
-      @constant_alias = ConstantAlias.switcher
-      @pattern_matching = Switcher.new(options: PATTERN_MATCHING)
+      @addon = Addons.switcher
+      @feature = Features.switcher
+      @constant_alias = ConstantAliases.switcher
+      @pattern_matching = PatternMatching.switcher
     end
 
     def freeze
@@ -65,7 +47,5 @@ class BCDD::Result
     def inspect
       "#<#{self.class.name} options=#{options.keys.sort.inspect}>"
     end
-
-    private_constant :ADDON, :FEATURE, :PATTERN_MATCHING
   end
 end

data/lib/bcdd/result/context/expectations/mixin.rb

@@ -7,13 +7,21 @@ class BCDD::Result::Context
     Methods = BCDD::Result::Expectations::Mixin::Methods
 
     module Addons
-      module Continuable
+      module Continue
         private def Continue(**value)
           Success.new(type: :continued, value: value, subject: self)
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          Success.new(type: :given, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/context/mixin.rb

@@ -13,15 +13,15 @@ class BCDD::Result::Context
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, subject: self, terminal: terminal)
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         def Success(type, **value)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(**value)
@@ -29,7 +29,15 @@ class BCDD::Result::Context
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(*values)
+          value = values.map(&:to_h).reduce({}) { |acc, val| acc.merge(val) }
+
+          _ResultAs(Success, :given, value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         ::BCDD::Result::Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/context/success.rb

@@ -3,13 +3,13 @@
 class BCDD::Result::Context::Success < BCDD::Result::Context
   include ::BCDD::Result::Success::Methods
 
-  def and_expose(type, keys, halted: true)
+  def and_expose(type, keys, terminal: true)
     unless keys.is_a?(::Array) && !keys.empty? && keys.all?(::Symbol)
       raise ::ArgumentError, 'keys must be an Array of Symbols'
     end
 
     exposed_value = acc.merge(value).slice(*keys)
 
-    self.class.new(type: type, value: exposed_value, subject: subject, halted: halted)
+    self.class.new(type: type, value: exposed_value, subject: subject, terminal: terminal)
   end
 end

data/lib/bcdd/result/context.rb

@@ -15,7 +15,7 @@ class BCDD::Result
       Failure.new(type: type, value: value)
     end
 
-    def initialize(type:, value:, subject: nil, expectations: nil, halted: nil)
+    def initialize(type:, value:, subject: nil, expectations: nil, terminal: nil)
       value.is_a?(::Hash) or raise ::ArgumentError, 'value must be a Hash'
 
       @acc = {}
@@ -40,25 +40,20 @@ class BCDD::Result
       -1
     end
 
-    def call_and_then_subject_method(method_name, context)
-      method = subject.method(method_name)
+    def call_and_then_subject_method!(method, context_data)
+      acc.merge!(value.merge(context_data))
 
-      acc.merge!(value.merge(context))
-
-      result =
-        case SubjectMethodArity[method]
-        when 0 then subject.send(method_name)
-        when 1 then subject.send(method_name, **acc)
-        else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 1)
-        end
-
-      ensure_result_object(result, origin: :method)
+      case SubjectMethodArity[method]
+      when 0 then subject.send(method.name)
+      when 1 then subject.send(method.name, **acc)
+      else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 1)
+      end
     end
 
-    def call_and_then_block(block)
+    def call_and_then_block!(block)
       acc.merge!(value)
 
-      call_and_then_block!(block, acc)
+      block.call(acc)
     end
 
     def ensure_result_object(result, origin:)

data/lib/bcdd/result/expectations/mixin.rb

@@ -24,25 +24,31 @@ class BCDD::Result
 
       FACTORY = <<~RUBY
         private def _Result
-          @_Result ||= Result.with(subject: self, halted: %<halted>s)
+          @_Result ||= Result.with(subject: self, terminal: %<terminal>s)
         end
       RUBY
 
       def self.to_eval(addons)
-        halted = addons.key?(:continue) ? 'true' : 'nil'
+        terminal = addons.key?(:continue) ? 'true' : 'nil'
 
-        "#{BASE}\n#{format(FACTORY, halted: halted)}"
+        "#{BASE}\n#{format(FACTORY, terminal: terminal)}"
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         private def Continue(value)
           Success.new(type: :continued, value: value, subject: self)
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(value)
+          Success.new(type: :given, value: value, subject: self)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         Config::Options.addon(map: config_flags, from: OPTIONS)

data/lib/bcdd/result/expectations.rb

@@ -38,8 +38,8 @@ class BCDD::Result
 
     private_class_method :mixin!, :mixin_module, :result_factory_without_expectations
 
-    def initialize(subject: nil, contract: nil, halted: nil, **options)
-      @halted = halted
+    def initialize(subject: nil, contract: nil, terminal: nil, **options)
+      @terminal = terminal
 
       @subject = subject
 
@@ -60,16 +60,16 @@ class BCDD::Result
       _ResultAs(Failure, type, value)
     end
 
-    def with(subject:, halted: nil)
-      self.class.new(subject: subject, halted: halted, contract: contract)
+    def with(subject:, terminal: nil)
+      self.class.new(subject: subject, terminal: terminal, contract: contract)
     end
 
     private
 
     def _ResultAs(kind_class, type, value)
-      kind_class.new(type: type, value: value, subject: subject, expectations: contract, halted: halted)
+      kind_class.new(type: type, value: value, subject: subject, expectations: contract, terminal: terminal)
     end
 
-    attr_reader :subject, :halted, :contract
+    attr_reader :subject, :terminal, :contract
   end
 end

data/lib/bcdd/result/mixin.rb

@@ -20,15 +20,15 @@ class BCDD::Result
         _ResultAs(Failure, type, value)
       end
 
-      private def _ResultAs(kind_class, type, value, halted: nil)
-        kind_class.new(type: type, value: value, subject: self, halted: halted)
+      private def _ResultAs(kind_class, type, value, terminal: nil)
+        kind_class.new(type: type, value: value, subject: self, terminal: terminal)
       end
     end
 
     module Addons
-      module Continuable
+      module Continue
         def Success(type, value = nil)
-          _ResultAs(Success, type, value, halted: true)
+          _ResultAs(Success, type, value, terminal: true)
         end
 
         private def Continue(value)
@@ -36,7 +36,13 @@ class BCDD::Result
         end
       end
 
-      OPTIONS = { continue: Continuable }.freeze
+      module Given
+        private def Given(value)
+          _ResultAs(Success, :given, value)
+        end
+      end
+
+      OPTIONS = { continue: Continue, given: Given }.freeze
 
       def self.options(config_flags)
         Config::Options.addon(map: config_flags, from: OPTIONS)

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Transitions
+  module Tracking::Disabled
+    def self.start(name:, desc:); end
+
+    def self.finish(result:); end
+
+    def self.reset!; end
+
+    def self.record(result); end
+
+    def self.record_and_then(_type, _data, _subject)
+      yield
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BCDD::Result::Transitions
+  class Tracking::Enabled
+    attr_accessor :tree, :records, :root_started_at
+
+    private :tree, :tree=, :records, :records=, :root_started_at, :root_started_at=
+
+    def start(name:, desc:)
+      name_and_desc = [name, desc]
+
+      tree.frozen? ? root_start(name_and_desc) : tree.insert!(name_and_desc)
+    end
+
+    def finish(result:)
+      node = tree.current
+
+      tree.move_up!
+
+      return unless node.root?
+
+      duration = (now_in_milliseconds - root_started_at)
+
+      metadata = { duration: duration, tree_map: tree.nested_ids }
+
+      result.send(:transitions=, version: Tracking::VERSION, records: records, metadata: metadata)
+
+      reset!
+    end
+
+    def reset!
+      self.tree = Tracking::EMPTY_TREE
+    end
+
+    def record(result)
+      return if tree.frozen?
+
+      track(result, time: ::Time.now.getutc)
+    end
+
+    def record_and_then(type_arg, arg, subject)
+      type = type_arg.instance_of?(::Method) ? :method : type_arg
+
+      unless tree.frozen?
+        current_and_then = { type: type, arg: arg, subject: subject }
+        current_and_then[:method_name] = type_arg.name if type == :method
+
+        tree.current.value[1] = current_and_then
+      end
+
+      yield
+    end
+
+    private
+
+    TreeNodeValueNormalizer = ->(id, (nam, des)) { [{ id: id, name: nam, desc: des }, Tracking::EMPTY_HASH] }
+
+    def root_start(name_and_desc)
+      self.root_started_at = now_in_milliseconds
+
+      self.records = []
+
+      self.tree = Tree.new(name_and_desc, normalizer: TreeNodeValueNormalizer)
+    end
+
+    def track(result, time:)
+      result = result.data.to_h
+
+      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 }
+    end
+
+    def now_in_milliseconds
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Transitions
+    module Tracking
+      require_relative 'tracking/enabled'
+      require_relative 'tracking/disabled'
+
+      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
+
+      def self.instance
+        Config.instance.feature.enabled?(:transitions) ? Tracking::Enabled.new : Tracking::Disabled
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Transitions
+    class Tree
+      class Node
+        attr_reader :id, :value, :parent, :normalizer, :children
+
+        def initialize(value, parent:, id:, normalizer:)
+          @normalizer = normalizer
+
+          @id = id
+          @value = normalizer.call(id, value)
+          @parent = parent
+
+          @children = []
+        end
+
+        def insert(value, id:)
+          node = self.class.new(value, parent: self, id: id, normalizer: normalizer)
+
+          @children << node
+
+          node
+        end
+
+        def root?
+          parent.nil?
+        end
+
+        def leaf?
+          children.empty?
+        end
+
+        def node?
+          !leaf?
+        end
+
+        def inspect
+          "#<#{self.class.name} id=#{id} children.size=#{children.size}>"
+        end
+      end
+
+      attr_reader :size, :root, :current
+
+      def initialize(value, normalizer: ->(_id, val) { val })
+        @size = 0
+
+        @root = Node.new(value, parent: nil, id: @size, normalizer: normalizer)
+
+        @current = @root
+      end
+
+      def root_value
+        root.value
+      end
+
+      def parent_value
+        current.parent&.value || root_value
+      end
+
+      def current_value
+        current.value
+      end
+
+      def insert(value)
+        @size += 1
+
+        current.insert(value, id: size)
+      end
+
+      def insert!(value)
+        @current = insert(value)
+      end
+
+      def move_up!(level = 1)
+        tap { level.times { @current = current.parent || root } }
+      end
+
+      def move_down!(level = 1, index: -1)
+        tap { level.times { current.children[index].then { |child| @current = child if child } } }
+      end
+
+      def move_to_root!
+        tap { @current = root }
+      end
+
+      NestedIds = ->(node) { [node.id, node.children.map(&NestedIds)] }
+
+      def nested_ids
+        NestedIds[root]
+      end
+    end
+  end
+end

data/lib/bcdd/result/transitions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Transitions
+    require_relative 'transitions/tree'
+    require_relative 'transitions/tracking'
+
+    THREAD_VAR_NAME = :bcdd_result_transitions_tracking
+
+    def self.tracking
+      Thread.current[THREAD_VAR_NAME] ||= Tracking.instance
+    end
+  end
+
+  def self.transitions(name: nil, desc: nil)
+    Transitions.tracking.start(name: name, desc: desc)
+
+    result = yield
+
+    result.is_a?(::BCDD::Result) or raise Error::UnexpectedOutcome.build(outcome: result, origin: :transitions)
+
+    Transitions.tracking.finish(result: result)
+
+    result
+  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.9.1'
+    VERSION = '0.11.0'
   end
 end