eco-helpers 2.6.4 → 2.7.0

data/lib/eco/data/locations/node_diff/nodes_diff/diffs_tree.rb

@@ -0,0 +1,99 @@
+class Eco::Data::Locations::NodeDiff::NodesDiff
+  # Helper class to wrap into a tree a set of diffs
+  class DiffsTree
+    class CyclicHierarchy < StandardError
+    end
+    class CyclicAncestorsChain < CyclicHierarchy
+    end
+
+    MAX_ITERATIONS = 16
+
+    attr_reader :id
+    attr_reader :diff
+    attr_reader :children, :parent
+
+    def initialize(diff = nil, id:)
+      @diff      = diff
+      @id        = id
+      @children  = []
+    end
+
+    # @note added explicit setter so we can warn
+    def diff=(value)
+      puts "WARNING (DiffsTree#diff=) was already present (for '#{id}')" if diff
+      @diff = value
+    end
+
+    def diff?
+      !!diff
+    end
+
+    def parent_present?
+      !!parent && parent.diff?
+    end
+
+    # @note that the abscense of `parent_id` (i.e. `nil`) does NOT
+    #   mean that this node does not have an actual parent. This class
+    #   supports building partial trees (clusters), where some parents
+    #   may not have presence.
+    def parent_id
+      return nil unless parent
+      parent.id
+    end
+
+    def add_child(child_tree)
+      raise ArgumentError, "Expecting #{self.class}. Given: #{child_tree.class}" unless child_tree.is_a?(self.class)
+      prevent_cyclic_chain(child_tree)
+      children.push(child_tree)
+      child_tree.link_parent(self)
+    end
+
+    def ancestors(iteration: 0)
+      msg = "Node '#{id}' can't be the #{iteration}th ancestor of any other node."
+      raise CyclicAncestorsChain, msg if max_iterations?(iteration)
+
+      return [] unless parent
+      [parent].concat(parent.ancestors(iteration: iteration + 1))
+    end
+
+    def all_descendants(iteration: 0)
+      msg = "Node '#{id}' can't be the #{iteration}th offspring of any other node."
+      raise CyclicAncestorsChain, msg if max_iterations?(iteration)
+
+      children.each_with_object([]) do |child, out|
+        out.push(child)
+        out.concat(child.all_descendants(iteration: iteration + 1))
+      end
+    end
+
+    protected
+
+    def link_parent(parent_node)
+      raise ArgumentError, "Expecting #{self.class}. Given: #{parent_node.class}" unless parent_node.is_a?(self.class)
+      return (@parent = parent_node) unless parent
+      msg = "Node '#{id}' already has a parent (#{parent.id}). "
+      msg << "Can't make it child of '#{parent_node.id}' as well."
+      raise CyclicHierarchy, msg
+    end
+
+    private
+
+    def prevent_cyclic_chain(child)
+      msg = "Can't make '#{id}' child of itself."
+      raise CyclicHierarchy, msg if child == self
+
+      msg << " A duplicated node got created somehow (review code)"
+      raise CyclicHierarchy, msg if child.id == id
+
+      return true unless ancestors.include?(child)
+
+      msg  = "Can't add '#{child.id}' as children of '#{id}' "
+      msg << "because the child is ancestor"
+      raise CyclicHierarchy, msg
+    end
+
+    def max_iterations?(value)
+      value >= self.class::MAX_ITERATIONS
+    end
+  end
+end

data/lib/eco/data/locations/node_diff/{selectors.rb → nodes_diff/selectors.rb}

@@ -1,4 +1,4 @@
-class Eco::Data::Locations::NodeDiff
+class Eco::Data::Locations::NodeDiff::NodesDiff
   module Selectors
     # Creates selector methods on `diffs` (nodes that changed)
     # It also creates a method with question mark that evaluates true if **any** diff matches.

data/lib/eco/data/locations/node_diff/nodes_diff.rb

@@ -1,10 +1,19 @@
 class Eco::Data::Locations::NodeDiff
   # Adjusts ArrayDiff for Nodes diffs in a location structure
   class NodesDiff < Eco::Data::Hashes::ArrayDiff
-    extend Eco::Data::Locations::NodeDiff::Selectors
+    require_relative 'nodes_diff/selectors'
+    require_relative 'nodes_diff/diffs_tree'
+    require_relative 'nodes_diff/clustered_treeify'
 
-    SELECTORS = %i[id name id_name insert unarchive update move archive]
-    selector *SELECTORS
+    extend Eco::Data::Locations::NodeDiff::NodesDiff::Selectors
+
+    SELECTORS = %i[
+      id name id_name classifications
+      insert unarchive
+      update move
+      archive
+    ].freeze
+    selector(*SELECTORS)
 
     class_resolver :diff_result_class, Eco::Data::Locations::NodeDiff
     attr_reader :original_tree
@@ -15,78 +24,84 @@ class Eco::Data::Locations::NodeDiff
     end
 
     def diffs
-      @diffs ||= super.select do |res|
-        res.unarchive? || res.id_name? || res.insert? || res.move? || res.archive?
+      @diffs ||= super.select do |dff|
+        # discard entries that are to be inserted and archived at the same time
+        next false if dff.insert? && dff.archive?(validate: false)
+        dff.unarchive? || dff.id_name? || dff.insert? ||
+          dff.move?    || dff.archive?
       end
     end
 
-    def diffs_details
+    def diffs_details # rubocop:disable Metrics/AbcSize
       section = '#' * 10
-      msg  = ''
+      msg     = ''
+
       if insert?
         msg << " #{section}  I N S E R T S  #{section}\n"
-        msg << insert.map {|d| d.diff_hash.pretty_inspect}.join('')
+        msg << insert.map {|dff| dff.diff_hash.pretty_inspect}.join
       end
 
       if update?
         msg << "\n #{section}  U P D A T E S  #{section}\n"
-        update.each do |d|
+        update.each do |dff|
           flags  = ''
-          #flags << 'i' if d.id?
-          flags << 'n' if d.diff_name?
-          flags << 'm' if d.move?
-          flags << 'u' if d.unarchive?
+          flags << 'i' if dff.id?
+          flags << 'n' if dff.name?
+          flags << 'c' if dff.classifications?
+          flags << 'm' if dff.move?
+          flags << 'u' if dff.unarchive?
           msg << "<< #{flags} >> "
-          msg << d.diff_hash.pretty_inspect
+          msg << dff.diff_hash.pretty_inspect
         end
       end
 
       if archive?
         msg << "\n #{section}  A R C H I V E S  #{section}\n"
-        msg << archive.map {|d| d.diff_hash.pretty_inspect}.join('')
+        msg << archive.map {|dff| dff.diff_hash.pretty_inspect}.join
       end
 
       msg
     end
 
-    def diffs_summary
-      comp = "(#{source2.count} vs #{source1.count} nodes)"
+    def diffs_summary # rubocop:disable Metrics/AbcSize
+      comp = "(#{source_2.count} input nodes VS #{source_1.count} live nodes)"
       return "There were no differences identified #{comp}" if diffs.empty?
       msg  = []
-      msg << "Identified #{diffs.count} differences  #{comp}:"
-      msg << when_present(insert, '') do |count|
+      msg << "Identified #{diffs.count} differences #{comp}:"
+      msg << when_present(insert) do |count|
         "  • #{count} nodes to insert"
       end
-      msg << when_present(update, '') do |count|
+      msg << when_present(update) do |count|
         "  • #{count} nodes to update"
       end
-      # msg << when_present(id, '') do |count|
-      #   "    • #{count} nodes to change id\n"
-      # end
-      msg << when_present(name, '') do |count|
+      msg << when_present(unarchive) do |count|
+        "    • #{count} nodes to unarchive (includes ancestors of target nodes)"
+      end
+      msg << when_present(id) do |count|
+        "    • #{count} nodes to change id\n"
+      end
+      msg << when_present(name) do |count|
         "    • #{count} nodes to change name"
       end
-      msg << when_present(move, '') do |count|
-        "    • #{count} nodes to move"
+      msg << when_present(classifications) do |count|
+        "    • #{count} nodes to change classifications"
       end
-      msg << when_present(unarchive, '') do |count|
-        "    • #{count} nodes to unarchive"
+      msg << when_present(move) do |count|
+        "    • #{count} nodes to move"
       end
-      msg << when_present(archive, '') do |count|
+      msg << when_present(archive) do |count|
         "  • #{count} nodes to archive"
       end
-      msg.join("\n")
+      msg.compact.join("\n")
     end
 
     private
 
     def when_present(list, default = nil)
+      raise ArgumentError, "Expecting block but not given" unless block_given?
       count = list.count
-      if count > 0
-        yield(count)
-      else
-        default
-      end
+      return yield(count) if count&.positive?
+      default
     end
   end
 end

data/lib/eco/data/locations/node_diff.rb

@@ -7,49 +7,77 @@ module Eco::Data::Locations
   #   - `archived`
   # @note other properties can be part of the `Hash` although
   #   they may not influence the results.
+  # @note that for special `exposed` methods question mark `?` on a
+  #   property of the model checks if that property changed
+  #   (it has nothing to do with checking the boolean value of that property)
   class NodeDiff < Eco::Data::Hashes::DiffResult
     require_relative 'node_diff/accessors'
-    require_relative 'node_diff/selectors'
     require_relative 'node_diff/nodes_diff'
 
     include Eco::Data::Locations::NodeDiff::Accessors
 
     key     :nodeId
-    compare :parentId, :name, :archived
-    case_sensitive false
+    # it also adds the snake_methods
+    # i.e. `parent_id`, `parent_id_prev`, `parent_id?` (to check if updated)
+    attr_expose :nodeId, :name, :parentId, :archived, :archivedToken, :classifications
 
-    attr_expose :nodeId, :name, :parentId, :archived
+    compare :parentId, :name, :archived
+    compare :classifications #, when_present: true
 
-    alias_method :insert?, :new?
+    case_sensitive false
 
-    alias_method :diff_name_src?, :diff_name?
+    # move method, to redefine it
+    alias_method :name_src?, :name?
     # Has the property `name` changed?
-    def diff_name?
-      diff_name_src? && update?
+    # @note should not be part of an insert
+    def name?
+      name_src? && update?
     end
-    alias_method :name?, :diff_name?
-    alias_method :id? , :diff_name? # currently a change of name is a change of id (tag)
-    #alias_method :id? , :key?
-    #alias_method :nodeId? , :id?
+
+    alias_method :classifications_src?, :classifications?
+    # @note should not be part of an insert
+    def classifications?
+      classifications_src? && update?
+    end
+
+    alias_method :insert?,  :new?
+    # node id diff? check should be performed as a `key`
+    alias_method :id?,      :key?
+    alias_method :nodeId?,  :id?
+    alias_method :node_id?, :nodeId?
 
     # Has any of `id` or `name` properties changed?
     def id_name?
-      id? || diff_name?
+      return true if id?
+      return true if name?
+      classifications?
     end
 
     # Has the parent id changed?
     def move?
-      update? && diff_parentId?
+      return false unless update?
+      parent_id?
     end
 
     # Has the `archived` property changed and it was `true`?
     def unarchive?
-      !archived && update? && diff_archived?
+      return false if     archived
+      return false unless update?
+      archived?
     end
 
     # Has the `archived` property changed and it was `false`?
-    def archive?
-      !prev_archived && (del? || archived)
+    def archive?(validate: true)
+      return false if archived_prev
+
+      msg  = "Value of archived shouldn't be true, "
+      msg << "because node '#{node_id}' doesn't exist "
+      msg << "(it's being inserted). "
+      msg << "It should have been discarded as a diff"
+      raise msg    if validate && archived && insert?
+
+      return true  if del?
+      archived
     end
   end
 end

data/lib/eco/data/locations/node_level/parsing.rb

@@ -28,34 +28,28 @@ class Eco::Data::Locations::NodeLevel
     def nodes_from_csv(csv)
       raise ArgumentError, "Expecting CSV::Table. Given: #{csv.class}" unless csv.is_a?(::CSV::Table)
 
-      prev_level = nil
-      prev_node  = nil
+      possible_classifications = csv.headers
 
       # Convert to Eco::CSV::Table for a fresh start
       csv = Eco::CSV.parse(csv.to_csv).nil_blank_cells.add_index_column(:row_num)
 
-      first = true
-      nodes = csv.each_with_object([]) do |row, out|
+      prev_node = nil
+      nodes     = csv.each_with_object([]) do |row, out|
         row_num, *values = row.fields
-        node = node_class.new(row_num, *values)
-        prev_node ||= node
 
-        # If node is nested in prev_node or is a sibling thereof
-        if prev_node.raw_level <= node.raw_level
-          # Make sure upper level tags are there (including parent)
-          # This normalizes input to all upper level tags always filled in
-          # which allows to node#actual_level to work
-          node.set_high_levels(prev_node)
-        else
-          if node.raw_level == 1
-            # It is expected not to have parent (as it's top level tag)
-          elsif prev_node
-            node.set_high_levels(prev_node)
-          else
-            raise "Node '#{node.raw_tag}' (#{node.row_num} row) doesn't have parent"
-          end
+        node = node_class.new(row_num, *values).tap do |nd|
+          nd.original_headers = possible_classifications
         end
-        out << node
+
+        out        << node
+        prev_node ||= node
+
+        # unless top level
+        # Make sure upper level tags are there (including parent)
+        # This normalizes input to all upper level tags always filled in
+        # which allows to node#actual_level to work
+        node.set_high_levels(prev_node) unless node.raw_level == 1
+
         prev_node = node
       end
       tidy_nodes(nodes)

data/lib/eco/data/locations/node_level.rb

@@ -1,5 +1,6 @@
+# rubocop:disable Naming/AccessorMethodName
 module Eco::Data::Locations
-  NODE_LEVEL_ATTRS = %i[row_num l1 l2 l3 l4 l5 l6 l7 l8 l9 l10 l11]
+  NODE_LEVEL_ATTRS = %i[row_num l1 l2 l3 l4 l5 l6 l7 l8 l9 l10 l11].freeze
   NodeLevelStruct  = Struct.new(*NODE_LEVEL_ATTRS)
   # Class to treat input csv in a form of levels, where each column is one level,
   # and children are placed in higher columns right below the parent.
@@ -13,28 +14,69 @@ module Eco::Data::Locations
     extend Eco::Data::Locations::NodeLevel::Builder
 
     ALL_ATTRS          = NODE_LEVEL_ATTRS
-    ADDITIONAL_ATTRS   = %i[row_num]
-    TAGS_ATTRS         = ALL_ATTRS - ADDITIONAL_ATTRS
+    ADDITIONAL_ATTRS   = %i[row_num].freeze
+    TAGS_ATTRS         = (ALL_ATTRS - ADDITIONAL_ATTRS).freeze
+
+    # @yield [node, json] optional custom serializer
+    # @yieldparam node [Node] self
+    # @yieldparam json [Hash] the default serialization
+    # @yieldreturn [Hash] the serialized Node
+    def node_hash(stringify_keys: true)
+      json = to_h(:id, :name, :parent_id, :classifications, :classification_names)
+      json.transform_keys!(&:to_s)   if stringify_keys
+      json.merge!(yield(self, json)) if block_given?
+      json
+    end
+
+    def copy
+      super.tap do |cp|
+        cp.highest_levels_set!
+        cp.original_headers = original_headers
+      end
+    end
 
-    attr_accessor :parentId
+    # In node level the parent id is set via parsing
+    attr_accessor :parentId # rubocop:disable Naming/MethodName
+    alias_method :parent_id=, :parentId=
+    alias_method :parent_id,  :parentId
 
     def id
       tag.upcase
     end
-    alias_method :nodeId, :id
+    alias_method :nodeId,  :id
+    alias_method :node_id, :nodeId
 
     def name
       tag
     end
 
     def tag
-      clean_id(raw_tag, ref: "(Row: #{self.row_num}) ")
+      clean_id(raw_tag, ref: "(Row: #{row_num}) ")
     end
 
     def raw_tag
       values_at(*TAGS_ATTRS.reverse).compact.first
     end
 
+    attr_writer :original_headers
+
+    def original_headers
+      @original_headers ||= []
+    end
+
+    def original_headers?
+      original_headers.any?
+    end
+
+    def classifications
+      return [] unless (al = actual_level).positive?
+      original_headers[al - 1]
+    end
+
+    def classification_names
+      classifications.dup
+    end
+
     def level
       actual_level
     end
@@ -56,7 +98,7 @@ module Eco::Data::Locations
 
     def raw_prev_empty_level?
       lev = raw_prev_empty_level
-      lev && lev > 0
+      lev&.positive?
     end
 
     def raw_latest_consecutive_top_empty_level
@@ -72,10 +114,11 @@ module Eco::Data::Locations
       otags_array = other.tags_array.compact
       stags_array = tags_array.compact
       raise "Missing lower levels for #{other.id}: #{other.tags_array.pretty_inspect}" unless other.highest_levels_set?
-      raise "Missing lower levels for #{self.id}: #{tags_array.pretty_inspect}"        unless highest_levels_set?
+      raise "Missing lower levels for #{id}:      #{tags_array.pretty_inspect}"        unless highest_levels_set?
+
       otags_array.zip(stags_array).each_with_index do |(otag, stag), idx|
-        next if otag&.upcase&.strip == stag&.upcase&.strip
-        return nil if idx == 0
+        next       if otag&.upcase&.strip == stag&.upcase&.strip
+        return nil if idx&.zero?
         return idx # previous idx, which means prev_idx + 1 (so idx itself)
       end
       actual_level
@@ -96,18 +139,12 @@ module Eco::Data::Locations
 
     def previous_idx
       idx = tag_idx - 1
-      idx < 0 ? nil : idx
+      idx&.negative?? nil : idx
     end
 
     def empty_idx
       tary = tags_array
-      tary.index(nil) || tary.length + 1
-    end
-
-    def copy
-      super.tap do |dup|
-        dup.highest_levels_set!
-      end
+      tary.index(nil) || (tary.length + 1)
     end
 
     # We got a missing level that is compacted in one row
@@ -120,8 +157,11 @@ module Eco::Data::Locations
       # must be the last among filled_idxs, so let's use it to verify
       unless with_info.last == tag_idx
         # This can only happen when there are repeated nodes
-        raise "Review this (row #{row_num}; '#{raw_tag}'): tag_idx is #{tag_idx}, while last filled idx is #{with_info.last}"
+        msg  = "Review this (row #{row_num}; '#{raw_tag}'): "
+        msg << "tag_idx is #{tag_idx}, while last filled idx is #{with_info.last}"
+        raise msg
       end
+
       len         = with_info.length
       target_idxs = with_info[len-(num+1)..-2]
       target_idxs.map do |idx|
@@ -142,8 +182,8 @@ module Eco::Data::Locations
     end
 
     # Sets ancestors
-    def set_high_levels(node, override: false, compact: true)
-      update_lower_levels(node.tags_array, override: override)
+    def set_high_levels(node)
+      update_lower_levels(node.tags_array)
       self
     end
 
@@ -159,6 +199,7 @@ module Eco::Data::Locations
         return false
       end
       return false if target.empty?
+
       target.each do |n|
         #puts "clearing 'l#{n}': #{attr("l#{n}")}"
         set_attr("l#{n}", nil)
@@ -169,9 +210,10 @@ module Eco::Data::Locations
     # Ensures parent is among the upper level tags
     # It actually ensures all ancestors are there
     # @param override [Boolean] `false` will only override upmost top consecutive empty levels.
-    def update_lower_levels(src_tags_array, to_level: self.raw_latest_consecutive_top_empty_level, override: false)
+    def update_lower_levels(src_tags_array, to_level: raw_latest_consecutive_top_empty_level)
       highest_levels_set!
       return self unless to_level
+
       target_lev  = Array(1..to_level)
       target_tags = src_tags_array[level_to_idx(1)..level_to_idx(to_level)]
       target_lev.zip(target_tags).each do |(n, tag)|
@@ -214,3 +256,5 @@ module Eco::Data::Locations
     end
   end
 end
+
+# rubocop:enable Naming/AccessorMethodName

data/lib/eco/data/locations/node_plain/parsing.rb

@@ -8,7 +8,7 @@ class Eco::Data::Locations::NodePlain
 
     # Subset of property names expected to be among the headers
     def basic_headers
-      @expected_headers ||= %w[id name parent_id]
+      @basic_headers ||= %w[id name parent_id]
     end
 
     # Checks if the `basic_headers` to process as `NodePlain` are present.

data/lib/eco/data/locations/node_plain.rb

@@ -1,6 +1,13 @@
 module Eco::Data::Locations
-  NODE_PLAIN_ATTRS = %i[row_num id name parent_id weight archived archive_token]
-  NodePlainStruct  = Struct.new(*NODE_PLAIN_ATTRS)
+  NODE_PLAIN_ATTRS = %i[
+    row_num
+    id name parent_id
+    weight
+    archived archive_token
+    classifications
+    classification_names
+  ].freeze
+  NodePlainStruct = Struct.new(*NODE_PLAIN_ATTRS)
   # Class to treat input csv in a form of a list of nodes, where parent is specified.
   class NodePlain < NodePlainStruct
     include Eco::Data::Locations::NodeBase
@@ -11,22 +18,68 @@ module Eco::Data::Locations
     extend Eco::Data::Locations::NodePlain::Builder
 
     ALL_ATTRS          = NODE_PLAIN_ATTRS
-    ADDITIONAL_ATTRS   = %i[row_num]
-    PROP_ATTRS         = ALL_ATTRS - ADDITIONAL_ATTRS
+    ADDITIONAL_ATTRS   = %i[row_num].freeze
+    PROP_ATTRS         = (ALL_ATTRS - ADDITIONAL_ATTRS).freeze
 
     def id
-      clean_id(super, ref: "(Row: #{self.row_num}) ")
+      clean_id(super, ref: "(Row: #{row_num}) ")
     end
     # backwards compatibility
     alias_method :tag, :id
 
     def name
-      super || self.id
+      super || id
     end
 
     def parent_id
-      clean_id(super, notify: false, ref: "(Row: #{self.row_num} - parent_id) ")
+      clean_id(super, notify: false, ref: "(Row: #{row_num} - parent_id) ")
     end
     alias_method :parentId, :parent_id
+
+    def archived
+      value = super
+      return false if value.nil? || value == false
+      return true  if value == true
+      return false if value.to_s.strip.empty?
+      return true  if %w[yes x true].include?(value.downcase)
+      false
+    end
+
+    def classifications
+      into_a(super).map do |value|
+        treat_classication(value)
+      end
+    end
+
+    def classification_names
+      into_a(super)
+    end
+
+    # @yield [node, json] optional custom serializer
+    # @yieldparam node [Node] self
+    # @yieldparam json [Hash] the default serialization
+    # @yieldreturn [Hash] the serialized Node
+    def node_hash(stringify_keys: true)
+      json = to_h.reject {|key, _v| key == :row_num}
+      json.transform_keys!(&:to_s)   if stringify_keys
+      json.merge!(yield(self, json)) if block_given?
+      json
+    end
+
+    private
+
+    def treat_classication(value)
+      return value unless value.is_a?(String)
+      value.strip.gsub(/\W+/, '').downcase
+    end
+
+    # Helper to convert to array
+    def into_a(value)
+      if value.is_a?(String)
+        value.split('|')
+      else
+        [value].flatten
+      end.compact
+    end
   end
 end