eco-helpers 2.6.4 → 2.7.1

data/lib/eco/api/usecases/graphql/helpers/base.rb

@@ -1,11 +1,12 @@
 module Eco::API::UseCases::GraphQL::Helpers
   module Base
     require_relative 'base/case_env'
-    include Eco::API::UseCases::GraphQL::Helpers::Base::CaseEnv
+    require_relative 'base/graphql_env'
 
-    def graphql
-      @graphql ||= session.api(version: :graphql)
-    end
+    include CaseEnv
+    include GraphQLEnv
+
+    private
 
     # Keep a copy of the requests/responses for future reference
     def backup(data, type:)

data/lib/eco/api/usecases/graphql/helpers/location/base/classifications_parser.rb

@@ -0,0 +1,60 @@
+module Eco::API::UseCases::GraphQL::Helpers::Location
+  module Base
+    module ClassificationsParser
+      include Eco::API::UseCases::GraphQL::Helpers::Base::CaseEnv
+
+      private
+
+      # @note
+      #   1. It returns `nil` unless there are classifications defined
+      #   2. If the value is wrong, it warns and returns `nil`
+      def to_classification(value)
+        return nil unless node_classifications?
+        raise ArgumentError, "Expecting a single element. Given: #{value.class}" if value.is_a?(Enumerator)
+        return nil unless value.is_a?(String)
+
+        node_classifications.to_id(value).tap do |type|
+          unknown_clasification!(value) unless type
+        end
+      end
+
+      def to_classification_ids(values)
+        values = [values].flatten unless values.is_a?(Array)
+        values.compact.map {|val| to_classification(val)}.compact
+      end
+
+      # @note
+      #   1. It returns `nil` unless there are classifications defined
+      #   2. If the value is wrong, it warns and returns `nil`
+      def to_classification_name(value)
+        return nil unless node_classifications?
+        raise ArgumentError, "Expecting a single element. Given: #{value.class}" if value.is_a?(Enumerator)
+        return nil unless value.is_a?(String)
+
+        node_classifications.to_name(value) do |name|
+          unknown_clasification!(value) unless name
+        end
+      end
+
+      def node_classifications?
+        node_classifications.any?
+      end
+
+      def node_classifications
+        @node_classifications ||= session.node_classifications
+      end
+
+      def unknown_clasification!(value)
+        return if unknown_classifications.include?(value)
+        unknown_classifications << value
+        log(:warn) {
+          "Unknown location node classification '#{value}'"
+        }
+      end
+
+      def unknown_classifications
+        @unknown_classifications ||= []
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/base/tree_tracking.rb

@@ -0,0 +1,72 @@
+module Eco::API::UseCases::GraphQL::Helpers::Location
+  module Base
+    module TreeTracking
+      include Eco::API::UseCases::GraphQL::Helpers::Base::CaseEnv
+
+      TAGTREE_BACKUP = 'cache/tagtree.json'.freeze
+
+      attr_reader :current_tree
+      attr_accessor :previous_tree
+
+      # Allows to override if the @current_tree should be kept
+      # to the latest live version
+      def track_current_tree?
+        true
+      end
+
+      # Back-up the tree everytime that it is retrieved anew.
+      # @note that what is costly operational is to parse the tree. As it comes
+      #   already parsed, we don't lose performance in backing it up.
+      def current_tree=(value)
+        return if current_tree == value
+        return unless value.is_a?(Eco::API::Organization::TagTree)
+
+        @previous_tree = @current_tree
+        @current_tree  = value
+        backup_tree(current_tree)
+      end
+
+      # At any moment we want to know how the live tree is
+      # @note it also does a backup
+      # @return [Eco::API::Organization::TagTree] the latest tree (`current_tree`)
+      def track_current_tree(tree)
+        return if simulate?
+        return if tree.nil?
+
+        latest_tree = tree if tree.is_a?(Eco::API::Organization::TagTree)
+        if tree.respond_to?(:treeify) && track_current_tree?
+          latest_tree ||= Eco::API::Organization::TagTree.new(tree.treeify, id: tree.id, name: tree.name)
+        end
+
+        latest_tree.tap do
+          next unless latest_tree.is_a?(Eco::API::Organization::TagTree)
+          next if latest_tree.empty?
+
+          # a backup happens:
+          self.current_tree = latest_tree
+        end
+      end
+
+      # @param tree [Eco::API::Organization::TagTree, Hash, Array]
+      # @return [Boolean] whether or not the backup was created
+      def backup_tree(tree = current_tree || live_tree)
+        return false if simulate?
+        case tree
+        when Eco::API::Organization::TagTree
+          tree = tree.source
+        when Hash, Array
+          # that's alright
+        else
+          log(:error) {
+            "Can't back up tagtree. Expecting TagTree, Hash or Array. Given: #{tree.class}"
+          }
+          return false
+        end
+
+        file = session.file_manager.save_json(tree, self.class::TAGTREE_BACKUP, :timestamp)
+        log(:debug) { "Backed-up tagtree saved locally to #{file}." }
+        true
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/base.rb

@@ -1,75 +1,28 @@
+require_relative 'base/tree_tracking'
+require_relative 'base/classifications_parser'
 module Eco::API::UseCases::GraphQL::Helpers::Location
   module Base
     include Eco::API::UseCases::GraphQL::Helpers::Base
-
-    TAGTREE_BACKUP = 'cache/tagtree.json'.freeze
-
-    attr_reader :current_tree
-    attr_accessor :previous_tree
-
-    # Back-up the tree everytime that it is retrieved anew.
-    def current_tree=(value)
-      return current_tree if current_tree == value
-      @current_tree = value
-      backup_tree(current_tree)
-      value
-    end
-
-    # At any moment we want to know how the live tree is
-    # @note it also does a backup
-    # @return [Eco::API::Organization::TagTree] the latest tree (`current_tree`)
-    def track_current_tree(tree)
-      return if simulate?
-      return unless tree
-      latest_tree = tree if tree.is_a?(Eco::API::Organization::TagTree)
-      if tree.respond_to?(:treeify)
-        latest_tree ||= Eco::API::Organization::TagTree.new(tree.treeify, id: tree.id, name: tree.name)
-      end
-      latest_tree.tap do |_tree|
-        next unless latest_tree
-        @previous_tree     = @current_tree
-        self.current_tree  = latest_tree
-      end
-    end
-
-    # @param tree [Eco::API::Organization::TagTree, Hash, Array]
-    # @return [Boolean] whether or not the backup was created
-    def backup_tree(tree = current_tree || live_tree)
-      return false if simulate?
-      case tree
-      when Eco::API::Organization::TagTree
-        tagtree = tree.source
-      when Hash, Array
-        # that's allright
-      else
-        log(:error) {
-          "Can't back up tagtree. Expecting TagTree, Hash or Array. Given: #{tree.class}"
-        }
-        return false
-      end
-      file = session.file_manager.save_json(tree, self.class::TAGTREE_BACKUP, :timestamp)
-      logger.debug("Backed up tagtree saved locally to #{file}.")
-      true
-    end
-
-    def tagtree_id
-      %i[target_structure_id tagtree_id structure_id].find {|key| options.dig(:source, key)}
-    end
+    include TreeTracking
+    include ClassificationsParser
 
     # Scopes the target structure `id`.
     # @note it is basic that the `id` is correctly identified.
     def target_structure_id
       @target_structure_id ||= tagtree_id
-      @target_structure_id ||= self.class.const_get(:TARGET_STRUCTURE_ID) if self.class.const_defined?(:TARGET_STRUCTURE_ID)
-      @target_structure_id ||= current_tree.id                            if current_tree.respond_to?(:id)
+      @target_structure_id ||= target_structure_id_const
+      @target_structure_id ||= current_tree.id if current_tree.respond_to?(:id)
       return @target_structure_id if @target_structure_id
+
       msg  = "Const TARGET_STRUCTURE_ID has not been defined, "
       msg << "nor options(:source, :structure_id). "
       msg << "Infering active locations structure."
       log(:warn) { msg }
-      if self.current_tree = session_live_tree
-        @target_structure_id = current_tree.id
-      end
+
+      # a backup happens:
+      return nil unless (self.current_tree = session_live_tree)
+
+      @target_structure_id = current_tree.id
     end
 
     # Retrieves the live tree only if `current_tree` hasn't been just retrieved.
@@ -80,6 +33,8 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
       tree_init = current_tree
       target_id = target_structure_id
       return current_tree if current_tree != tree_init
+
+      # a backup happens:
       self.current_tree = session_live_tree(id: target_id)
     end
 
@@ -88,5 +43,16 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
     def session_live_tree(id: nil)
       session.live_tree(id: id, include_archived: true)
     end
+
+    def tagtree_id
+      %i[target_structure_id tagtree_id structure_id].map do |key|
+        options.dig(:source, key)
+      end.compact.first
+    end
+
+    def target_structure_id_const
+      return nil unless self.class.const_defined?(:TARGET_STRUCTURE_ID)
+      self.class.const_get(:TARGET_STRUCTURE_ID)
+    end
   end
 end

data/lib/eco/api/usecases/graphql/helpers/location/command/diff/as_update.rb

@@ -0,0 +1,59 @@
+class Eco::API::UseCases::GraphQL::Helpers::Location::Command::Diff
+  module AsUpdate
+    # Unique access point to generate an update
+    def as_update(operation, after_id_update: false)
+      update_hash = diff_hash(after_id_update: after_id_update)
+      update_hash.slice(*update_attrs(operation))
+    end
+
+    # Adjustments to be able to generate correct updates
+    # @note it transforms the method on a very effective helper
+    def diff_hash(after_id_update: true) # rubocop:disable Metrics/AbcSize
+      super().tap do |h|
+        h.delete('archived')
+        h['classificationIds'] = h.delete('classifications') if h.key?('classifications')
+
+        if archive? || insert?
+          # We assume archives do not have `move` nor update `id` or `name`
+          h['nodeId']   = node_id || node_id_prev
+          h['parentId'] = parent_id if insert?
+        elsif update?
+          if id? && !after_id_update
+            h['nodeId'] = node_id_prev
+            h['newId']  = node_id
+          elsif id? # after id update
+            h['nodeId'] = node_id
+          else # no id? change , and before the id_update stage
+            h['nodeId'] = node_id_prev
+          end
+          if move?
+            h['parentId'] = after_id_update ? parent_id : parent_id_prev
+          end
+        else
+          # Something is wrong (not expected to be any other category)
+          raise "Unexpected condition, please review code base"
+        end
+      end
+    end
+
+    # List of attributes that can be part of an operation
+    def update_attrs(operation)
+      ['nodeId'].tap do |attrs|
+        plus =
+          case operation
+          when :id_name, :update
+            %w[newId name classificationIds]
+          when :id
+            %w[newId]
+          when :insert
+            %w[name parentId classificationIds]
+          when :move
+            %w[parentId]
+          else
+            []
+          end
+        attrs.push(*plus)
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/command/diff/compare.rb

@@ -0,0 +1,49 @@
+class Eco::API::UseCases::GraphQL::Helpers::Location::Command::Diff
+  module Compare
+    # Sorts from top to bottom (parents go first)
+    # @note
+    #   1. The analysis below will assume that NO `nodeId` has changed. Which is what
+    #     this class helper tries to somehow ensure/emmulate.
+    #   2. The below has been thought for NodesDiff::STAGES order:
+    #     [:unarchive,  :id_name, :insert, :move, :archive]
+    # @note
+    #   - If there was a change of id involved in child or parent, the method used
+    #     on each (attr vs prev_attr) could be different. We would need to know at
+    #     what stage we are in the general update.
+    #   - If MOVE has yet to come, `attr_prev` is alright, as we are interested
+    #     in the current parent-to-child order in the locations structure.
+    #     UNARCHIVE nodes have `attr_prev` and, therefore, this can be used to sort.
+    #   - If MOVE has happened, then `attr_prev` is missleading (order could be different),
+    #     so `attr` should be used, which refers to the final parents. However,
+    #     ARCHIVE nodes only have `attr_prev`, which could refer to the previous parent. And yet
+    #     as there's no current data, they have NOT been moved, which makes `prev_attr` reliable.
+    # @note
+    #   - One thing is still to be resolved. `unarchive?` could entail a later `move?` (same NodeDiff).
+    #     Therefore, the STAGE when the comparison is done is relevant.
+    #   - This has been resolved with `sort_before_move` & `sort_after_move` methods.
+    def <=>(other)
+      if archive? || unarchive?
+        return -1 if node_id_prev   == other.parent_id_prev
+        return  1 if parent_id_prev == other.node_id_prev
+      elsif insert? || move?
+        return -1 if node_id        == other.parent_id
+        return  1 if parent_id      == other.node_id
+      end
+      0
+    end
+
+    def sort_before_move(other)
+      self <=> other
+    end
+
+    def sort_after_move(other)
+      if move?
+        return -1 if node_id   == other.parent_id
+        return  1 if parent_id == other.node_id
+        0
+      else
+        self <=> other
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/command/diff.rb

@@ -0,0 +1,11 @@
+module Eco::API::UseCases::GraphQL::Helpers::Location
+  # To prepend to class Custom::UseCase::TagtreeDiff::NodeDiff
+  # Currently, name and id are the same thing, so we make some adjustments.
+  class Command::Diff < Eco::Data::Locations::NodeDiff
+    require_relative 'diff/compare'
+    require_relative 'diff/as_update'
+
+    include Compare
+    include AsUpdate
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/command/diffs/stages/commandable.rb

@@ -0,0 +1,46 @@
+class Eco::API::UseCases::GraphQL::Helpers::Location::Command::Diffs
+  module Stages
+    module Commandable
+      class << self
+        def included(base)
+          super
+          base.extend(ClassMethods)
+          base.send(:include, DiffSortable)
+        end
+      end
+
+      module ClassMethods
+        def stage_command(stage)
+          return :update if stage == :id_name
+          stage
+        end
+      end
+
+      # builds up the particular graphql location commands
+      def stage_commands(stage)
+        stage_command = self.class.stage_command(stage)
+        stage_updates(stage).map do |update|
+          {}.tap do |comm|
+            comm[stage_command] = symbolize_keys(update)
+          end
+        end
+      end
+
+      private
+
+      def stage_updates(stage)
+        aiu = self.class.after_id_update?(stage)
+        stage_diffs(stage).map do |dfs|
+          dfs.as_update(stage, after_id_update: aiu)
+        end
+      end
+
+      def stage_diffs(stage)
+        raise "There is NO support for stage '#{stage}'. Please review" unless respond_to?(stage)
+        sort_diffs(stage) do
+          send(stage)
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/command/diffs/stages/diff_sortable/for_archive.rb

@@ -0,0 +1,23 @@
+class Eco::API::UseCases::GraphQL::Helpers::Location::Command::Diffs
+  module Stages
+    module DiffSortable
+      module ForArchive
+
+        private
+
+        def only_first_ancestor_in_chains(raw_diffs)
+          parents = raw_diffs.each_with_object({}) do |dff, prs|
+            (prs[dff.parent_id_prev] ||= []) << dff
+          end
+
+          present_parent_prev_ids = raw_diffs.select do |dff|
+            parents.key?(dff.node_id_prev)
+          end.map(&:node_id_prev)
+
+          children_with_parents = parents.values_at(*present_parent_prev_ids).flatten(1).uniq
+          raw_diffs - children_with_parents
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/command/diffs/stages/diff_sortable/for_unarchive.rb

@@ -0,0 +1,65 @@
+class Eco::API::UseCases::GraphQL::Helpers::Location::Command::Diffs
+  module Stages
+    module DiffSortable
+      module ForUnarchive
+        # we require the original tree to be able to track what ancestors
+        # should be unarchived, with the aim of unarchiving a node that
+        # is target of update (i.e. revive and move somewhere else)
+        def original_tree
+          defined?(super)? super : @original_tree
+        end
+
+        def original_tree_node(id)
+          original_tree.node(id)
+        end
+
+        private
+
+        # Uses method of core class ArrayDiff
+        def results_by_node_id_prev
+          @results_by_node_id_prev ||= source_results.each_with_object({}) do |diff_result, out|
+            out[diff_result.node_id_prev] = diff_result
+          end
+        end
+
+        # Generates result diffs where archied ancestors are being unarchived
+        # It ensures unique diff results for nodeId where `raw_diffs` takes precedence
+        def include_unarchive_of_archived_ancestors(raw_diffs)
+          ancestors_diffs = raw_diffs.each_with_object([]) do |diff_result, out|
+            ans_diff_results = archived_ancestors_as_unarchive_diffs(diff_result.node_id_prev)
+            out.concat(ans_diff_results)
+          end
+          (raw_diffs + ancestors_diffs).uniq(&:node_id_prev)
+        end
+
+        # Unarchive comes with a bad joke. You need to unarchive archived parents
+        # even if they should remain archived.
+        def archived_ancestors_as_unarchive_diffs(id)
+          archived_tree_node_ancestors(id).map do |node|
+            if (dff = results_by_node_id_prev[node.id])
+              # generate a node diff with no changes
+              dff.dup(src_2: dff.src_1).tap do |nres|
+                nres.src_2['archived'] = false
+              end
+            else
+              # Some trouble -> can re-use
+              puts "Couldn't find diff_res for archived ancestor '#{node.id}'"
+            end
+          end.compact
+        end
+
+        def archived_tree_node_ancestors(id)
+          original_tree_node_ancestors(id).select(&:archived)
+        end
+
+        def original_tree_node_ancestors(id)
+          if (node = original_tree_node(id))
+            node.ancestors
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/command/diffs/stages/diff_sortable.rb

@@ -0,0 +1,49 @@
+require_relative 'diff_sortable/for_unarchive'
+require_relative 'diff_sortable/for_archive'
+
+class Eco::API::UseCases::GraphQL::Helpers::Location::Command::Diffs
+  module Stages
+    module DiffSortable
+      class << self
+        def included(base)
+          super
+          base.send(:include, Sortable)
+        end
+      end
+
+      include ForUnarchive
+      include ForArchive
+
+      private
+
+      # @yield
+      # @yieldreturn [Array<Diff>] the raw diffs of `stage`
+      def sort_diffs(stage)
+        raise ArgumentError, "Expecting block but not given" unless block_given?
+        raw_diffs = yield
+
+        case stage
+        when :archive
+          only_first_ancestor_in_chains(sort_top_to_bottom(raw_diffs, stage))
+        when :unarchive
+          raw_diffs = include_unarchive_of_archived_ancestors(raw_diffs)
+          sort_top_to_bottom(uniq_archive_token(raw_diffs, stage), stage)
+        when :move
+          sort_bottom_to_top(raw_diffs, stage)
+        else
+          sort_top_to_bottom(raw_diffs, stage)
+        end
+      end
+
+      # It should also include archived ancestors !!
+      # @note this will translate to the unarchive of a wider range of nodes.
+      #   - Please notice that the design is correct (there's no way around it)
+      def uniq_archive_token(raw_diffs, stage)
+        raw_diffs.group_by(&:archived_token_prev).each_with_object([]) do |(token, token_diffs), out|
+          next out.concat(token_diffs) unless token
+          out << sort_top_to_bottom(token_diffs, stage).first
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/helpers/location/command/diffs/stages/sortable/relation_safe_sort.rb

@@ -0,0 +1,119 @@
+class Eco::API::UseCases::GraphQL::Helpers::Location::Command::Diffs
+  module Stages
+    module Sortable
+      # Class that provided elements that may have a relationship
+      # with a provided `block` that compares two single elements (`<==>`)
+      # it returns the sorted list of the elements in a safe way
+      # and by keeping the original order when `<==>` returns `0`
+      class RelationSafeSort
+        attr_reader :list
+        attr_reader :cluster_mode
+
+        # @param cluster_mode [Boolean] whether it should optimize by trying to
+        #   first treeify and only trying to resolve the by pairings (one to one)
+        #   the diffs that are hanging from now where.
+        #   Possible values are `:prev` or `:curr`
+        def initialize(list, cluster_mode: nil, &block)
+          @list         = list
+          @cluster_mode = clusterer_class.mode(cluster_mode) if cluster_mode
+          @comparer     = block
+        end
+
+        def clustered?
+          !!@cluster_mode
+        end
+
+        # @yield [a, b] elements to be sorted
+        # When the comparer `<=>` returns `0`, it still ensures the order is correct
+        # Please notice that native `sort` is not stable when `<=>` can return `0`
+        def sort
+          return list.dup if list.count <= 1
+
+          # treeifying we ensure correct order (parent, children)
+          pending      = parents_hash.dup
+          treeify      = proc do |item|
+            next item unless (children = pending.delete(item))
+            {item => children.map {|child| treeify.call(child)}}
+          end
+
+          sorted_tree = top_parents.each_with_object(unpaired) do |item, tree|
+            next unless pending.key?(item)
+            tree << treeify.call(item)
+          end
+
+          flatten(sorted_tree)
+        end
+
+        private
+
+        attr_reader :comparer
+
+        def compare_two(a, b)
+          comparer.call(a, b)
+        end
+
+        def unpaired
+          list - paired
+        end
+
+        def paired
+          parents_hash.keys | all_children
+        end
+
+        def parents_hash
+          @parents_hash ||=
+            if clustered?
+              clusterer.clusters
+            else
+              paired_related_nodes.group_by(&:shift).transform_values(&:flatten)
+            end
+        end
+
+        def clusterer
+          @clusterer ||= clusterer_class.new(list, mode: cluster_mode)
+        end
+
+        def top_parents
+          @top_parents ||= parents_hash.keys.reject {|item| all_children.include?(item)}
+        end
+
+        def all_children
+          @all_children ||= parents_hash.values.flatten(1).uniq
+        end
+
+        # @yield [a, b] elements to be sorted
+        # Pairs one to one relationships in order
+        # @note on relationship, parent comes first
+        def paired_related_nodes
+          paired_combinations.each_with_object([]) do |pair, chained|
+            next if (result = compare_two(*pair)).zero?
+            chained << (result.negative?? pair : pair.reverse)
+          end
+        end
+
+        def paired_combinations
+          list.combination(2).to_a
+        end
+
+        # Flattens the tree into an Array
+        def flatten(value)
+          case value
+          when Array
+            value.each_with_object([]) do |child, out|
+              out.concat(flatten(child))
+            end.uniq
+          when Hash
+            item, children = value.first
+            [item].concat(flatten(children)).uniq
+          else
+            [value]
+          end
+        end
+
+        def clusterer_class
+          Eco::Data::Locations::NodeDiff::NodesDiff::ClusteredTreeify
+        end
+      end
+    end
+  end
+end