flows 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3408a7cfa09415262d76e3cdc1d2d28529103928bbbc379dc0c02a14b1f25eee
-  data.tar.gz: 55b10a5f99d6c0b33185a9e0ba193ab39abd3f43ae88b39b5cb7b48c30fbe23d
+  metadata.gz: 8910a47890a3e15f9a79dbb3f7e6255f57cdf2232b9257e05dbdfd39b252d4f7
+  data.tar.gz: bb71db93b1128f3c9f7a7dfb5e705c4ec4e6bd3615a19479bb5f68ba97d63b05
 SHA512:
-  metadata.gz: 23ef64c88317d77233cf9eb837d3318a73523fd8ac270ec7166eb42c57b0310a015af887bab0018423290eba49f7fb9d735b4c079940bbb1c2cb394857155779
-  data.tar.gz: fa7baaa93dc8836ab470e873624feaa15a3a6a29a25e483d2efe2b34e228bb2ad88c1c31ed0905c5635aa51b8cb9760fcd76bc2fdc62806ff61ff72eba737e6d
+  metadata.gz: ea2894cb2a0472d84968d89c8f7ea3d0013e89fa1d7fc0864ba0cec223683c29950e24cff43b161204da0aa3aadf3969eb848539e828471de82a6b4beef500f1
+  data.tar.gz: b12a300213344b4baab7a0f112931018a3a6f74bfee143687111261d692478bd6f2edf1436fb4f8819aae0afca4d4172d194b22e672a1cf9b3838d1b2b749002

data/.mdlrc

@@ -1 +1 @@
-rules "~MD013", "~MD033"
+rules "~MD013", "~MD033", "~MD024"

data/.reek.yml

@@ -22,6 +22,7 @@ detectors:
   DataClump:
     exclude:
       - Flows::Result::Helpers
+      - Flows::SharedContextPipeline::DSL::Tracks
   IrresponsibleModule:
     exclude:
       - Flows::SharedContextPipeline
@@ -29,14 +30,25 @@ detectors:
     exclude:
       - Flows::SharedContextPipeline#call
       - Flows::Contract # too many false positives here
+      - Flows::Plugin::Profiler::Report#events
   TooManyStatements:
     exclude:
       - Flows::SharedContextPipeline#call
+      - Flows::Plugin::Profiler::Wrapper#make_instance_wrapper
+      - Flows::Plugin::Profiler::Wrapper#make_singleton_wrapper
       - initialize
   DuplicateMethodCall:
     exclude:
       - Flows::SharedContextPipeline#call
+      - Flows::Plugin::Profiler::Wrapper#make_instance_wrapper
+      - Flows::Plugin::Profiler::Wrapper#make_singleton_wrapper
       - 'length'
   MissingSafeMethod:
     exclude:
       - Flows::Contract
+  BooleanParameter:
+    exclude:
+      - Flows::Plugin::OutputContract::DSL
+  TooManyMethods:
+    exclude:
+      - Flows::Plugin::Profiler::Report::Tree::Node

data/CHANGELOG.md

@@ -16,6 +16,21 @@ Types of changes:
 
 ## [Unreleased]
 
+## [0.5.0] - 2020-05-18
+
+### Added
+
+* `Flows::SharedContextPipeline` wrap DSL, [issue](https://github.com/ffloyd/flows/issues/7)
+* `Flows::Flow` routing integrity check on initialization
+* `Flows::Plugin::OutputContract` skip contract DSL method
+* `Flows::Plugin::Profiler` introduced. Report types: raw, tree and flat.
+
+### Changed
+
+* `Flows::SharedContextPipeline` callback API, [issue](https://github.com/ffloyd/flows/issues/6)
+* `Flows::Util` modules API, [issue](https://github.com/ffloyd/flows/issues/11)
+* `Flows::Contract::CaseEq` default error expanded to present more context
+
 ## [0.4.0] - 2020-04-21
 
 ### Added
@@ -39,4 +54,5 @@ Types of changes:
   target module did not included directly into class.
 
 [unreleased]: https://github.com/ffloyd/flows/compare/v0.4.0...HEAD
+[0.5.0]: https://github.com/ffloyd/flows/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/ffloyd/flows/compare/v0.3.0...v0.4.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    flows (0.4.0)
+    flows (0.5.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,6 +1,6 @@
 # Flows
 
-[![Build Status](https://github.com/ffloyd/flows/workflows/Build/badge.svg)](https://github.com/ffloyd/flows/actions)
+[![Build Status](https://github.com/ffloyd/flows/workflows/Test/badge.svg)](https://github.com/ffloyd/flows/actions)
 [![codecov](https://codecov.io/gh/ffloyd/flows/branch/master/graph/badge.svg)](https://codecov.io/gh/ffloyd/flows)
 [![Gem Version](https://badge.fury.io/rb/flows.svg)](https://badge.fury.io/rb/flows)
 
@@ -19,7 +19,7 @@ Also `flows` is faster than Ruby's alternatives.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'flows', '~> 0.4'
+gem 'flows', '~> 0.5'
 ```
 
 And then execute:
@@ -251,6 +251,16 @@ version. _No exceptions._
 
 Commit with a version bump should contain _only_ version bump and CHANGELOG.md update.
 
+### GitHub Flow
+
+Since `v0.4.0` this repo strictly follow [GitHub
+Flow](https://guides.github.com/introduction/flow/) with some additions:
+
+* branch naming using dash: `improved-contexts`
+* use [references to
+  issues](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)
+  in commit messages and make links to issues in CHANGELOG.md
+
 ### Planned features for v1.0.0
 
 * validation framework

data/Rakefile

@@ -14,7 +14,7 @@ Reek::Rake::Task.new
 Inch::Rake::Suggest.new
 
 PATHS_TO_SPELLCHECK = ['.'].freeze
-PATHS_FOR_MDL = ['README.md', Dir.glob('docs/**/*.md')].flatten.freeze
+PATHS_FOR_MDL = ['README.md', 'CHANGELOG.md', Dir.glob('docs/**/*.md')].flatten.freeze
 
 desc 'Run self spellchecking'
 task :spellcheck do |_task|

data/bin/all_the_errors

@@ -45,3 +45,11 @@ echo "Shared Context Pipeline"
 echo "---------------------------"
 "${BASH_SOURCE%/*}/errors" scp no_steps
 "${BASH_SOURCE%/*}/errors" scp no_step_impl
+
+echo
+echo
+echo "---------------------------"
+echo "Flow"
+echo "---------------------------"
+"${BASH_SOURCE%/*}/errors" flow invalid_node_route
+"${BASH_SOURCE%/*}/errors" flow no_first_node

data/bin/errors

@@ -16,6 +16,7 @@ require_relative 'errors_cli/oc_error_demo'
 require_relative 'errors_cli/railway_error_demo'
 require_relative 'errors_cli/result_error_demo'
 require_relative 'errors_cli/scp_error_demo'
+require_relative 'errors_cli/flow_error_demo'
 
 class ErrorsCLI
   extend GLI::App
@@ -113,6 +114,17 @@ class ErrorsCLI
       SCPErrorDemo.no_step_impl
     end
   end
+
+  desc 'Flow errors'
+  command :flow do |cmd|
+    make_cmd cmd, 'No first node', :no_first_node do
+      FlowErrorDemo.no_first_node
+    end
+
+    make_cmd cmd, 'Invalid Node route', :invalid_node_route do
+      FlowErrorDemo.invalid_node_route
+    end
+  end
 end
 
 exit ErrorsCLI.run(ARGV)

data/bin/errors_cli/flow_error_demo.rb

@@ -0,0 +1,22 @@
+module FlowErrorDemo
+  class << self
+    def no_first_node
+      Flows::Flow.new(
+        start_node: :first,
+        node_map: {}
+      )
+    end
+
+    def invalid_node_route
+      Flows::Flow.new(
+        start_node: :first,
+        node_map: {
+          first: Flows::Flow::Node.new(
+            body: ->(_) {},
+            router: Flows::Flow::Router::Custom.new(a: :b)
+          )
+        }
+      )
+    end
+  end
+end

data/docs/README.md

@@ -1,6 +1,6 @@
 # Flows
 
-[![Build Status](https://github.com/ffloyd/flows/workflows/Build/badge.svg)](https://github.com/ffloyd/flows/actions)
+[![Build Status](https://github.com/ffloyd/flows/workflows/Test/badge.svg)](https://github.com/ffloyd/flows/actions)
 [![codecov](https://codecov.io/gh/ffloyd/flows/branch/master/graph/badge.svg)](https://codecov.io/gh/ffloyd/flows)
 [![Gem Version](https://badge.fury.io/rb/flows.svg)](https://badge.fury.io/rb/flows)
 

data/lib/flows/contract/case_eq.rb

@@ -30,7 +30,9 @@ module Flows
       # @see Contract#check!
       def check!(other)
         unless @object === other
-          value_error = @error_message || "must match `#{@object.inspect}`"
+          value_error =
+            @error_message ||
+            "must match `#{@object.inspect}`, but has class `#{other.class.inspect}` and value `#{other.inspect}`"
           raise Error.new(other, value_error)
         end
 

data/lib/flows/flow/errors.rb

@@ -0,0 +1,29 @@
+module Flows
+  class Flow
+    # Base class for {Flow} error
+    class Error < StandardError; end
+
+    # Raised when router has an impossible route.
+    class InvalidNodeRouteError < Error
+      def initialize(node_name, route_destination)
+        @node_name = node_name.inspect
+        @route_destination = route_destination.inspect
+      end
+
+      def message
+        "Node `#{@node_name}` has a route to `#{@route_destination}`, but node `#{@route_destination}` is missing."
+      end
+    end
+
+    # Raised when router has an impossible route.
+    class InvalidFirstNodeError < Error
+      def initialize(node_name)
+        @node_name = node_name.inspect
+      end
+
+      def message
+        "`#{@node_name}` is a first node name, but node `#{@node_name}` is missing."
+      end
+    end
+  end
+end

data/lib/flows/flow/node.rb

@@ -82,6 +82,7 @@ module Flows
     class Node
       # Node metadata, a frozen Ruby Hash.
       attr_reader :meta
+      attr_reader :router
 
       # @param body [Proc] node body
       # @param router [Router] node router

data/lib/flows/flow/router/custom.rb

@@ -48,6 +48,11 @@ module Flows
 
           raise NoRouteError, "no route found for: `#{result.inspect}`"
         end
+
+        # @see Flows::Flow::Router#destinations
+        def destinations
+          @routes.values
+        end
       end
     end
   end

data/lib/flows/flow/router/simple.rb

@@ -14,6 +14,11 @@ module Flows
         def call(result)
           result.ok? ? @success_route : @failure_route
         end
+
+        # @see Flows::Flow::Router#destinations
+        def destinations
+          [@success_route, @failure_route]
+        end
       end
     end
   end

data/lib/flows/flow/router.rb

@@ -15,6 +15,10 @@ module Flows
     #   @param result [Flows::Result] Result Object, output of a {Node} execution.
     #   @return [Symbol] name of the next node or  a special symbol `:end`.
     #   @raise [NoRouteError] if cannot determine a route.
+    #
+    # @!method destinations
+    #   @abstract
+    #   @return [Array<Symbol>] names of all the possible destination nodes
     class Router
     end
   end

data/lib/flows/flow.rb

@@ -1,3 +1,4 @@
+require_relative 'flow/errors'
 require_relative 'flow/node'
 require_relative 'flow/router'
 
@@ -66,9 +67,13 @@ module Flows
   class Flow
     # @param start_node [Symbol] name of the entry node.
     # @param node_map [Hash<Symbol, Node>] keys are node names, values are nodes.
+    # @raise [Flows::Flow::InvalidNodeRouteError] when some node has invalid routing destination.
+    # @raise [Flows::Flow::InvalidFirstNodeError] when first node is not presented in node map.
     def initialize(start_node:, node_map:)
       @start_node = start_node
       @node_map = node_map
+
+      check_routing_integrity
     end
 
     # Executes a flow.
@@ -85,5 +90,21 @@ module Flows
 
       input
     end
+
+    private
+
+    def check_routing_integrity
+      raise InvalidFirstNodeError, @start_node unless @node_map.key?(@start_node)
+
+      @node_map.each { |node_name, node| check_node_routing_integrity(node_name, node) }
+    end
+
+    def check_node_routing_integrity(node_name, node)
+      node.router.destinations.each do |destination_name|
+        if destination_name != :end && !@node_map.key?(destination_name)
+          raise InvalidNodeRouteError.new(node_name, destination_name)
+        end
+      end
+    end
   end
 end

data/lib/flows/plugin/dependency_injector.rb

@@ -88,11 +88,12 @@ module Flows
       # Placeholder for empty value. We cannot use `nil` because value can be `nil`.
       NO_VALUE = :__no_value__
 
-      Flows::Util::InheritableSingletonVars::DupStrategy.call(
-        self,
+      SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
         '@dependencies' => {}
       )
 
+      include SingletonVarsSetup
+
       # @api private
       module DSL
         attr_reader :dependencies
@@ -133,8 +134,7 @@ module Flows
 
       singleton_class.prepend InheritanceCallback
 
-      # @api private
-      module InitializePatch
+      InitializerWrapper = Util::PrependToClass.make_module do
         def initialize(*args, **kwargs, &block) # rubocop:disable Metrics/MethodLength
           klass = self.class
           DependencyList.new(
@@ -153,7 +153,7 @@ module Flows
         end
       end
 
-      Flows::Util::PrependToClass.call(self, InitializePatch)
+      include InitializerWrapper
     end
   end
 end

data/lib/flows/plugin/output_contract/dsl.rb

@@ -9,12 +9,17 @@ module Flows
         # Hash of contracts for failure results.
         attr_reader :failure_contracts
 
-        Flows::Util::InheritableSingletonVars::DupStrategy.call(
-          self,
+        # Is contract check and transformation disabled
+        attr_reader :skip_output_contract_flag
+
+        SingletonVarsSetup = Flows::Util::InheritableSingletonVars::DupStrategy.make_module(
           '@success_contracts' => {},
-          '@failure_contracts' => {}
+          '@failure_contracts' => {},
+          '@skip_output_contract_flag' => false
         )
 
+        include SingletonVarsSetup
+
         # Defines a contract for a successful result with specific status.
         #
         # @param status [Symbol] Corresponding result status.
@@ -30,6 +35,13 @@ module Flows
         def failure_with(status, &contract_block)
           failure_contracts[status] = Flows::Contract.make(&contract_block)
         end
+
+        # Disables contract check and transformation for current class and children.
+        #
+        # @param enable [Boolean] if true - contracts are disabled
+        def skip_output_contract(enable = true)
+          @skip_output_contract_flag = enable
+        end
       end
     end
   end

data/lib/flows/plugin/output_contract/wrapper.rb

@@ -8,16 +8,16 @@ module Flows
         def initialize(*args, &block)
           super(*args, &block)
           klass = self.class
-          raise NoContractError, klass if klass.success_contracts.empty?
+          raise NoContractError, klass if klass.success_contracts.empty? && !klass.skip_output_contract_flag
         end
 
         def call(*args, &block)
           result = super(*args, &block)
           klass = self.class
 
-          contract = Util.contract_for(klass, result)
+          return result if klass.skip_output_contract_flag
 
-          Util.transform_result(klass, contract, result)
+          Util.transform_result(klass, result)
 
           result
         end
@@ -28,16 +28,9 @@ module Flows
         # @api private
         module Util
           class << self
-            def contract_for(klass, result)
-              raise ResultTypeError.new(klass, result) unless result.is_a?(Flows::Result)
-
-              status = result.status
-              contracts = result.ok? ? klass.success_contracts : klass.failure_contracts
+            def transform_result(klass, result)
+              contract = Util.contract_for(klass, result)
 
-              contracts[status] || raise(StatusError.new(klass, result, contracts.keys))
-            end
-
-            def transform_result(klass, contract, result)
               data = result.send(:data)
 
               transformed_result = contract.transform(data)
@@ -45,6 +38,15 @@ module Flows
 
               result.send(:'data=', transformed_result.unwrap)
             end
+
+            def contract_for(klass, result)
+              raise ResultTypeError.new(klass, result) unless result.is_a?(Flows::Result)
+
+              status = result.status
+              contracts = result.ok? ? klass.success_contracts : klass.failure_contracts
+
+              contracts[status] || raise(StatusError.new(klass, result, contracts.keys))
+            end
           end
         end
       end