datashift_journey 0.1.2

data/lib/datashift_journey/state_machines/branch_sequence_map.rb

@@ -0,0 +1,35 @@
+require 'forwardable'
+
+module DatashiftJourney
+
+  module StateMachines
+
+    # Map a Sequence to its ID, created in form
+    #
+    #   branch_sequence :other_sequence, [:other_business]
+    #
+    #       BranchSequenceMap[:branch_sequence] => Sequence([:other_business])
+    #
+    class BranchSequenceMap < ActiveSupport::HashWithIndifferentAccess
+
+      # Create a new Sequence if ID not yet in Map, otherwise
+      # add the state list to the existing Sequence
+
+      def add_or_concat(id, list)
+        key?(id) ? self[id].add_states(list) : add_branch(id, Sequence.new(list.flatten, id: id))
+      end
+
+      def add_branch(id, sequence)
+        # puts "DEBUG: ADDING TO SEQ [#{id}] BRANCH #{sequence.inspect}"
+        self[id] = sequence
+      end
+
+      # Find the matching branch sequences for a parent Split (first state)
+      def branches_for(sequence)
+        values.find_all { |branch| (branch.entry_state && branch.entry_state == sequence.split_entry_state) }
+      end
+
+    end
+
+  end
+end

data/lib/datashift_journey/state_machines/extensions.rb

@@ -0,0 +1,40 @@
+# Decorate a state machine enabled class with a set of extensions to :
+#
+#     https://github.com/state-machines/state_machines
+#     https://github.com/state-machines/state_machines-activerecord
+#
+module DatashiftJourney
+
+  module StateMachines
+
+    module Extensions
+
+      def transitions_for
+        self.class.state_machine.events.transitions_for(self)
+      end
+
+      def pp_state_paths
+        state_paths.each_with_index { |s, i| puts "Event [#{s.events[i]}] from=#{s[i].from} to=#{s[i].to}" }
+      end
+
+      # Expects a symbol
+      # Returns nil when no such state
+      def state_index(state)
+        state.nil? ? nil : state_paths.to_states.index(state.to_sym).to_i
+      end
+
+      def current_state_index
+        state_paths.to_states.index(state_name).to_i
+      end
+
+      def next_state_name
+        transitions_for.find { |t| t.event == :skip_fwd }.try(:to_name)
+      end
+
+      def previous_state_name
+        transitions_for.find { |t| t.event == :back }.try(:to_name)
+      end
+
+    end
+  end
+end

data/lib/datashift_journey/state_machines/planner.rb

@@ -0,0 +1,206 @@
+require 'forwardable'
+require_relative 'sequence'
+
+module DatashiftJourney
+
+  module StateMachines
+
+    # Mixed into the State Machine class, so your JourneyPlan class has access to these methods and
+    # attributes
+    #
+    module Planner
+
+      def init_plan
+        sequence_list.clear                        # In development context where models get reloaded, this could duplicate
+        branch_sequence_map.clear
+      end
+
+      # The complete, Ordered collection of sequences, used to generate the steps (states) of the plan
+      def sequence_list
+        @sequence_list ||= StateList.new
+      end
+
+      # Key - sequence ID
+      def branch_sequence_map
+        @branch_sequence_map ||= BranchSequenceMap.new
+      end
+
+      def sequence(*list)
+        raise PlannerApiError, 'Empty list passed to sequence - check your MachineBuilder syntax' if list.empty?
+        sequence_list << Sequence.new(list.flatten)
+      end
+
+      # Path splits down different branches, based on values stored on the main Journey model
+      # usually collected from from input e.g. radio, text or checkbox
+      #
+      # Requires the starting or parent state, and the routing criteria to each target sequence
+      #
+      #   split_on_equality( :new_or_renew,
+      #                      "what_branch?",             # Helper method on the journey Class
+      #                      branch_1: 'branch_1',
+      #                      branch_2: 'branch_2'
+      #   )
+      #
+      # target_on_value_map is a hash mapping between the value collected from website and the associated named branch.
+      #
+      #   if value collected on parent state == stored target state, journey is routed down that branch
+      #
+      def split_on_equality(state, attr_reader, seq_to_target_value_map, _options = {})
+        unless seq_to_target_value_map.is_a? Hash
+          raise 'BadDefinition - target_on_value_map must be hash map value => associated branch state'
+        end
+
+        sequence_list << Sequence.new(state, split: true)
+
+        seq_to_target_value_map.each do |seq_id, trigger_value|
+          if branch_sequence_map[seq_id]
+            branch_sequence_map[seq_id].entry_state = state
+            branch_sequence_map[seq_id].trigger_method = attr_reader
+            branch_sequence_map[seq_id].trigger_value = trigger_value
+          else
+            seq = Sequence.new(nil, id: seq_id, entry_state: state, trigger_method: attr_reader, trigger_value: trigger_value)
+            branch_sequence_map.add_branch(seq_id, seq)
+          end
+        end
+      end
+
+      def branch_sequence(sequence_id, *list)
+        branch_sequence_map.add_or_concat(sequence_id, list)
+      end
+
+      def self.hash_klass
+        ActiveSupport::HashWithIndifferentAccess
+      end
+
+      protected
+
+      # Based upon the current sequences, events defined build the Complete Plan,
+      # including back and next navigation
+      #
+      def build_journey_plan
+        # The Order of sequences should have been preserved as insertion order
+
+        #puts "DEBUG: START PLAN - Processing SEQUENCES\n#{sequence_list.inspect}"
+
+        sequence_list.each_with_index do |sequence, i|
+          prev_seq = i.zero? ? EmptySequence.new : sequence_list[i - 1]
+
+          next_seq = sequence_list[i + 1] || EmptySequence.new
+
+          if sequence.split?
+            #puts "\nDEBUG: *** BUILDING SPLITTER #{sequence.inspect} (#{i})"
+            build_split_sequence_events(sequence, prev_seq, next_seq)
+          else
+
+            # If previous seq is a branch we need to build conditional back transitions, to the end state
+            # of each branch (based on the same criteria that originally split the branch)
+            if prev_seq.split?
+              begin
+                #puts "\nDEBUG: *** BUILDING SEQ TO SPLIT #{sequence.inspect} (#{i})"
+                build_triggered_back(sequence, prev_seq)
+              rescue => x
+                puts x.inspect
+                puts "Failed in Seq [#{sequence.inspect}] (#{i}) - to create back events to Previous Seq #{prev_seq}"
+                raise x
+              end
+
+            elsif prev_seq.last
+              #puts "\nDEBUG: *** BUILDING SEQ #{sequence.inspect} (#{i})"
+              create_back(sequence.first, prev_seq.last)
+            end
+
+            # The simple navigation through states within the sequence
+            create_pairs sequence
+
+            #puts "\nDEBUG: *** CREATED PAIRS FOR SEQ #{sequence.inspect} (#{i})"
+            create_next(sequence.last, next_seq.first) if next_seq.first.present?
+          end
+        end
+      end
+
+      def build_split_sequence_events(sequence, prev_seq, next_seq)
+        # puts "\n\nDEBUG: PROCESS SPLIT SEQ #{sequence.inspect}"
+        # puts "DEBUG: SPLIT prev_seq #{prev_seq.inspect}"
+        # puts "DEBUG: SPLIT next_seq #{next_seq.inspect}"
+
+        # Create BACK from this entry state to the exit point of any PREVIOUS sequence
+        create_back(sequence.split_entry_state, prev_seq.last) if prev_seq.last
+
+        branch_sequence_map.branches_for(sequence).each do |branch|
+          begin
+            # puts "\n\nDEBUG: Process Branch - #{branch.inspect}"
+
+            # Back and next for any states within the split sequence itself
+            create_pairs branch
+
+            # N.B A split sequence can actually be empty
+            #
+            # i.e Some branches may jump straight from the split point straight to next common sequence
+
+            # Now work out the start and end points for this split.
+            next_state = branch.empty? ? next_seq.first : branch.first
+
+            # back from first seq state (or if empty next sequence) to this decision state
+            split_entry_state = sequence.split_entry_state
+
+            # If branch has no states, a VALUE triggered BACK will be created later
+            create_back(branch.first, split_entry_state) unless branch.empty?
+
+            build_triggered_next(branch, split_entry_state, next_state)
+
+            # N.B When multiple splits occur one after the other, branch.last can equal next_seq.first
+
+            # Not sure if that's reflective that logic not too clever elsewhere but for now
+            # make sure we don't create such a next event to itself
+
+            # LAST item in branch connects to FIRST item of NEXT sequence (unless empty and already built with trigger)
+
+            if !branch.empty? && next_seq.first && (branch.last != next_seq.first)
+              create_next(branch.last, next_seq.first)
+            end
+
+          rescue => x
+            puts x.inspect
+            puts "Failed in Split Sequnce to process Branch #{branch.inspect}"
+            raise x
+          end
+        end
+      end
+
+      def build_triggered_back(sequence, prev_seq)
+        #puts "DEBUG: * BUILD triggered Back for #{sequence.inspect}"
+
+        # Create back from FIRST item of THIS sequence to LAST entry of EACH previous BRANCH
+        branch_sequence_map.branches_for(prev_seq).each do |branch|
+          # Branches can be empty - i.e chain direct to next common sequence
+          # in which case back goes to the split sequence state itself (parent of branch)
+          to_state = branch.last.nil? ? prev_seq.first : branch.last
+
+          create_back(sequence.first, to_state) do
+            lambda do |o|
+              unless o && o.respond_to?(branch.trigger_method)
+                raise PlannerBlockError, "Cannot Go back - No such method #{branch.trigger_method} on Class #{o.class}"
+              end
+              o.send(branch.trigger_method) == branch.trigger_value
+            end
+          end
+        end
+      end
+
+      def build_triggered_next(branch, from, to)
+        # N.B sequences can self terminate i.e no further sequences and end of the journey
+        return unless from && from != to
+
+        create_next(from, to) do
+          lambda do |o|
+            unless o && o.respond_to?(branch.trigger_method)
+              raise PlannerBlockError, "Cannot split - No such method #{branch.trigger_method} on Class #{o.class}"
+            end
+            o.send(branch.trigger_method) == branch.trigger_value
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/datashift_journey/state_machines/sequence.rb

@@ -0,0 +1,86 @@
+require 'forwardable'
+
+module DatashiftJourney
+
+  module StateMachines
+
+    class StateList
+      extend Forwardable
+
+      def_delegators :@states, :each, :clear, :each_with_index, :[], :<<, :<=>, :<<, :==, :[], :[]=
+
+      def initialize
+        @states = []
+      end
+
+    end
+
+    class Sequence
+      extend Forwardable
+
+      attr_reader :id
+
+      attr_reader :entry_state, :exit_state, :states
+
+      attr_accessor :split, :trigger_method, :trigger_value
+
+      def_delegators :@states,
+                     :clear, :drop, :each, :each_with_index,
+                     :empty?, :size,
+                     :first, :last,
+                     :[], :<<, :<=>, :<<, :==, :[], :[]=
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(states, id: '', entry_state: nil, exit_state: nil, trigger_value: nil, trigger_method: nil, split: false)
+        @states = [*states]
+
+        @id = id
+        @entry_state = entry_state
+        @exit_state = exit_state
+        @trigger_method = trigger_method
+        @trigger_value = trigger_value
+        @split = split
+      end
+
+      def add_states(list)
+        @states.concat(list.flatten)
+      end
+
+      def inspect
+        "#{self.class.name}(#{id}) - #{@states.inspect} [splitter = #{split?}]"
+      end
+
+      def split?
+        split == true
+      end
+
+      def branch?
+        !trigger_value.nil?
+      end
+
+      def split_entry_state
+        return nil unless split?
+        states.first
+      end
+
+      def entry_state=(state)
+        @entry_state = state unless entry_state
+      end
+
+      def exit_state=(state)
+        @exit_state = state unless exit_state
+      end
+
+      private
+
+      attr_writer :states
+    end
+
+    class EmptySequence < Sequence
+      def initialize
+        super(nil)
+      end
+    end
+
+  end
+end

data/lib/datashift_journey/state_machines/state_machine_core_ext.rb

@@ -0,0 +1,72 @@
+require_relative 'planner'
+
+# rubocop:disable Metrics/BlockLength
+
+StateMachines::Machine.class_eval do
+  include DatashiftJourney::StateMachines::Planner
+  extend DatashiftJourney::StateMachines::Planner
+
+  # Create both a next link from lhs to rhs, and a back link from rhs to lhs
+
+  def create_pair(lhs, rhs)
+    create_back(lhs, rhs)
+    create_next(rhs, lhs)
+  end
+
+  def create_pairs(sequence)
+    create_back_transitions sequence
+    create_next_transitions sequence
+  end
+
+  def create_back(from, to)
+    raise "Bad transitions supplied for Back - FROM #{from} - TO #{to}" if from.nil? || to.nil?
+    if block_given?
+      #puts "DEBUG: Creating BACK transition from #{from} to #{to} with Block"
+      transition(from => to, on: :back, if: yield)
+    else
+      #puts "DEBUG: Creating BACK transition from #{from} to #{to}"
+      transition(from => to, on: :back)
+    end
+  end
+
+  # We use skip_fwd as the event type to avoid keyword next
+  #
+  # This will add usual helpers like
+  #
+  #   vehicle.skip_fwd?                 # => true
+  #   vehicle.can_skip_fwd?             # => true
+  #
+  def create_next(from, to)
+    raise "Bad transitions supplied for Next - FROM #{from} - TO #{to}" if from.nil? || to.nil?
+    if block_given?
+      #puts "DEBUG: Creating NEXT transition from #{from} to #{to} with Block "
+      transition(from => to, on: :skip_fwd, if: yield)
+    else
+      #puts "DEBUG: Creating NEXT transition from #{from} to #{to}"
+      transition(from => to, on: :skip_fwd)
+    end
+  end
+
+  # BACK - Create a 'back' event for each step in list
+  # Automatically removes first state, as nothing to go back to from that state
+  # You can exclude any other steps with the except list
+  #
+  def create_back_transitions(journey, except = [])
+    journey.drop(1).each_with_index do |t, i|
+      next if except.include?(t)
+      create_back(t, journey[i]) # n.b previous index is actually i not (i-1) due to the drop
+    end
+  end
+
+  # NEXT - Create a 'next' event for each step (apart from last) in journey
+  # You can exclude  any other steps with the except list
+  #
+  def create_next_transitions(journey, except = [])
+
+    #puts "DEBUG: Creating NEXT transitions for #{journey.inspect}"
+    journey[0...-1].each_with_index do |t, i|
+      next if except.include?(t)
+      create_next(t, journey[i + 1])
+    end
+  end
+end

data/lib/datashift_journey/version.rb

@@ -0,0 +1,3 @@
+module DatashiftJourney
+  VERSION = '0.1.2'
+end

data/lib/datashift_journey.rb

@@ -0,0 +1,57 @@
+require 'rails'
+require 'state_machines-activerecord'
+require 'reform'
+require 'reform/form'
+
+require_relative 'datashift_journey/state_machines/planner'
+require_relative 'datashift_journey/state_machines/extensions'
+require_relative 'datashift_journey/state_machines/state_machine_core_ext'
+require_relative 'datashift_journey/engine'
+
+module DatashiftJourney
+
+  def self.library_path
+    File.expand_path("#{File.dirname(__FILE__)}/../lib")
+  end
+
+  # Load all the datashift Thor commands and make them available throughout app
+  #
+  def self.load_commands
+    base = File.join(library_path, 'tasks', '**')
+
+    Dir["#{base}/*.thor"].each do |f|
+      next unless File.file?(f)
+      load(f)
+    end
+  end
+
+  # Set the main model class that contains the plan and associated state engine
+  #
+  def self.journey_plan_class=(x)
+    raise 'DSJ - journey_plan_class MUST be String or Symbol, not a Class.' if x.is_a?(Class)
+
+    @journey_plan_class = x
+
+    class << self
+      define_method :"concern_file" do
+        "#{@journey_plan_class.underscore}_journey.rb"
+      end
+    end
+
+    # This is called from an initializer, we dont want to trigger the machine building till
+    # the model class itself is loaded so do NOT do this here
+    # @journey_plan_class = x.to_s.constantize if x.is_a?(String) || x.is_a?(Symbol)
+
+    @journey_plan_class
+  end
+
+  def self.journey_plan_class
+    @journey_plan_class = @journey_plan_class.to_s.constantize if @journey_plan_class.is_a?(String) || @journey_plan_class.is_a?(Symbol)
+    @journey_plan_class
+  end
+
+  def self.state_names(machine: :state)
+    DatashiftJourney.journey_plan_class.state_machine(machine).states.map(&:name)
+  end
+
+end

data/lib/generators/datashift_journey/collector/collector_generator.rb

@@ -0,0 +1,43 @@
+require_relative '../generate_common'
+
+module DatashiftJourney
+  class CollectorGenerator < Rails::Generators::Base
+
+    source_root File.expand_path('templates', __dir__)
+
+    include Rails::Generators::Migration
+
+    include DatashiftJourney::GenerateCommon
+    extend DatashiftJourney::GenerateCommon
+
+    desc 'Copies over migrations enabling use of our generic data collection facilities'
+
+    def create_collector
+      @migration_version = '6.1'   # TODO: how can we get this dynamically from Rails version ?
+
+      migration_template 'collector_migration.rb', 'db/migrate/datashift_journey_create_collector.rb'#, migration_version: migration_version
+
+      code = <<-EOS
+  has_many :data_nodes, class_name: 'DatashiftJourney::Collector::DataNode', as: :plan, foreign_key: :plan_id, dependent: :destroy
+  accepts_nested_attributes_for :data_nodes
+
+EOS
+
+      inject_into_file model_path, :after => /class.* < ApplicationRecord/ do
+        "\n#{code}"
+      end
+
+      route(%(
+          # This mounts Datashift Journey's Collector routes
+          #
+          scope :api, constraints: { format: 'json' } do
+            scope :v1 do
+              resources :page_states, only: [:create], controller: 'datashift_journey/page_states'
+            end
+          end
+        )
+      )
+    end
+
+  end
+end

data/lib/generators/datashift_journey/collector/install_collector_generator.rb

@@ -0,0 +1,61 @@
+require 'rails/generators/active_record'
+require_relative '../initializer_common'
+
+module DatashiftJourney
+
+  class InstallCollectorGenerator < Rails::Generators::Base
+
+    include Rails::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    desc 'This generator copies over DSJ migrations to use the generic Collector data collector'
+
+    def copy_collector_migration
+      migration_template "migration.rb", "db/migrate/add_foo_to_bar.rb"
+      migration_template 'collector_migration.rb', 'db/migrate/datashift_journey_create_collector.rb', migration_version: migration_version
+    end
+
+    extend DatashiftJourney::InitializerCommon
+    include DatashiftJourney::InitializerCommon
+
+    # Hmm bit odd but to get thor to work appears we need to wrap calls to our common methods
+    def install_common
+      create_initializer_file(klass)
+
+      notify_about_routes
+
+      insert_into_file File.join('config', 'routes.rb'), before: "end\n" do
+        %(
+          # This line mounts Datashift Journey's Collector routes
+          #
+          scope :api, constraints: { format: 'json' } do
+            scope :v1 do
+              resources :page_states, only: [:create], controller: 'datashift_journey/page_states'
+            end
+          end
+        )
+      end
+
+      journey_plan_host_file(klass)
+
+      model_journey_code(klass)
+    end
+
+    private
+
+    def rails5?
+      Rails.version.start_with? '5'
+    end
+
+    def klass
+      'DatashiftJourney::Collector::Collector'
+    end
+
+    def migration_version
+      "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if rails5?
+    end
+
+  end
+
+end

data/lib/generators/datashift_journey/collector/install_mongo_collector_generator.rb

@@ -0,0 +1,44 @@
+require_relative '../initializer_common'
+
+module DatashiftJourney
+
+  class InstallMongoCollectorGenerator < Rails::Generators::Base
+
+    desc 'This generator copies over DSJ migrations to use the generic Collector data collector'
+
+    def install_migrations
+      say_status :copying, 'migrations'
+      `rake railties:install:migrations`
+    end
+
+    extend DatashiftJourney::InitializerCommon
+    include DatashiftJourney::InitializerCommon
+
+    # Hmm bit odd but to get thor to work appears we need to wrap calls to our common methods
+    def install_common
+      create_initializer_file(klass)
+
+      notify_about_routes
+
+      journey_decorator(klass)
+
+      model_journey_code(klass)
+    end
+
+    def migration_data
+      <<RUBY
+      field :form, type: String
+      field :field , type: String
+      field :value, type: String
+RUBY
+    end
+
+    private
+
+    def klass
+      'DatashiftJourney::MongoCollector::MongoCollector'
+    end
+
+  end
+
+end

data/lib/generators/datashift_journey/collector/templates/collector_concern.rb.tt

@@ -0,0 +1,34 @@
+module DatashiftJourney
+  module Collector
+
+    extend ActiveSupport::Concern
+
+    included do
+        include DatashiftJourney::ReferenceGenerator.new(prefix: 'C')
+
+        # See app/models/datashift_journey/collector/data_node.rb
+        has_many :data_nodes, class_name: 'DatashiftJourney::Collector::DataNode', foreign_key: :plan_id, dependent: :destroy, as: :plan
+
+        has_many :form_fields, through: :data_nodes, source: :form_field
+
+        has_many :page_states, through: :form_fields
+    end
+
+    def node_for_form_and_field(form_name, field_name)
+      form_field = DatashiftJourney::Collector::FormBackingModel.for_form_and_field(form_name, field_name)
+      return nil unless form_field
+      data_nodes.where(form_field: form_field).first
+    end
+
+    def node_for_form_field(form_field)
+      data_nodes.find(form_field).first
+    end
+
+    def nodes_for_form(form_name)
+      form = page_states.where(form_name: form_name).first
+      return [] unless form
+      form.data_nodes.all.to_a
+    end
+
+  end
+end