eco-helpers 2.5.2 → 2.5.3

data/lib/eco/data/hashes/array_diff.rb

@@ -34,14 +34,15 @@ module Eco
           end
         end
 
+        include Eco::Language::AuxiliarLogger
+
         attr_reader :source1, :source2
         attr_reader :src_h1,  :src_h2
-        attr_reader :logger
 
         class_resolver :diff_result_class, "Eco::Data::Hash::DiffResult"
 
-        def initialize(source1, source2, logger: ::Logger.new(IO::NULL), **kargs)
-          @logger  = logger
+        def initialize(source1, source2, logger: nil, **kargs)
+          @logger  = logger if logger
           @options = kargs
           @source1 = source1
           @source2 = source2
@@ -84,7 +85,8 @@ module Eco
         #   - It also ensures they are in their Hash form (with string keys)
         #   - This will merge entries of the same source that hold the same `key` attr value (latest wins)
         def paired_sources
-          keys1 = src_h1.keys; keys2 = src_h2.keys
+          keys1    = src_h1.keys
+          keys2    = src_h2.keys
           all_keys = keys1 | keys2
           all_keys.map {|key| [src_h1[key], src_h2[key]]}
         end
@@ -149,11 +151,15 @@ module Eco
             when Hash, Array, ::CSV::Row
               Eco::CSV::Table.new(content).to_array_of_hashes
             else
-              logger.error("Input content 'Array' of '#{sample.class}' is not supported.")
+              log(:error) {
+                "Input content 'Array' of '#{sample.class}' is not supported."
+              }
               exit(1)
             end
           else
-            logger.error("Could not obtain any data out content: '#{content.class}'")
+            log(:error) {
+              "Could not obtain any data out content: '#{content.class}'"
+            }
             exit(1)
           end
         end

data/lib/eco/data/hashes/diff_result.rb

@@ -2,11 +2,10 @@ module Eco
   module Data
     module Hashes
       class DiffResult
-
         attr_reader :key
         attr_reader :src1, :src2
 
-        # @param [Array<String>, sym]
+        # @param compare [Array<String>, sym]
         #   - `:all` compares the matching attrs between both hashes only
         def initialize(src1, src2, key:, compare: :all, case_sensitive: false)
           @key     = key

data/lib/eco/data/locations/convert.rb

@@ -0,0 +1,92 @@
+module Eco::Data::Locations
+  module Convert
+    include Eco::Language::AuxiliarLogger
+
+    # Helper to open a csv
+    # @note this is a shortcut helper.
+    # @param filename [String] the csv file.
+    # @return [Eco::CSV::Table]
+    def csv_from(filename, encoding: 'utf-8')
+      raise ArgumentError, "Expecting String filename. Given: #{filename.class}" unless filename.is_a?(String)
+      raise "Missing #{filename}" unless File.exists?(filename)
+      Eco::CSV.read(filename, encoding: encoding)
+    rescue CSV::MalformedCSVError => e
+      if match = e.message.match(/line (?<line>\d+)/i)
+        log(:error) {"An encoding problem was found on line #{match[:line]}"}
+      end
+      raise
+    end
+
+    # Generic converter/helper to generate the csv data export for a hierarchical csv tree
+    # @note The steps of usage would be:
+    #   1. First **treeify** your input (i.e. `Eco::API::Organization::TagTree#as_json`,
+    #     or `treeify(nodes)`
+    # @param hash_nodes [Array<Hash>] a hierarchical tree of Hash nodes, nested via `nodes`
+    # @return [CSV::Table] ready to be made a hierarchical csv tree (i.e. out.to_csv)
+    def hash_tree_to_tree_csv(hash_nodes, out: [], done_ids: [], repeated_ids: [], level: 0)
+      lev  = level + 1
+      base = empty_array(level)
+
+      hash_nodes.each_with_object(out) do |node, out|
+        if done_ids.include?(id = node["id"])
+          repeated_ids << id
+        else
+          has_offspring = (children = node["nodes"]) && !children.empty?
+          done_ids << id
+          out      << (base.dup << node["id"])
+          hash_tree_to_tree_csv(node["nodes"], out: out, done_ids: done_ids, repeated_ids: repeated_ids, level: lev)
+        end
+      end.tap do |out|
+        if level == 0
+          report_repeated_node_ids(repeated_ids)
+          return Eco::CSV::Table.new(normalize_arrays(out))
+        end
+      end
+    end
+
+    # It normalizes the size of the arrays to the max size among the arrays
+    # @param rows [Array<Array>] where arrays may not have the same length
+    # @return [Array<Array>] where arrays have all the same length
+    def normalize_arrays(rows)
+      max_row = rows.max {|a, b| a.length <=> b.length}
+      holder  = empty_array(max_row.length)
+      rows.map do |row|
+        row.dup.concat(holder[0..-(row.length+1)])
+      end
+    end
+
+    # @param count [Integer] number of possitions of the new array
+    # @return [Array<NilClass>] with `count` positions.
+    def empty_array(count)
+      Array.new(count, nil)
+    end
+
+    # @note
+    #   1. Initially it has as many keys as levels `count`
+    #   2. It serves the purpose to track the lastest seen node
+    #     for a given level, during a loop.
+    # @return [Hash] with integer level counts as keys and
+    #   nodes as values.
+    def empty_level_tracker_hash(count = 11)
+      Array(1..count).zip(empty_array(count)).to_h
+    end
+
+    # It logs a message from `yield` and appends a `pretty_inspect` on object.
+    # @note it only works where `object` is `Enumberable`
+    def log_pretty_inspect(object, lev = :info)
+      return unless object.is_a?(Enumerable)
+      return if object.empty?
+      msg  = ''
+      msg << "#{yield(object)}\n" if block_given?
+      msg << object.pretty_inspect
+      log(lev) { msg }
+    end
+
+    # Prints a common message
+    def report_repeated_node_ids(repeated)
+      log_pretty_inspect(repeated, :warn) do
+        "There were #{repeated.length} repeated node ids. Only one included. These excluded:"
+      end
+    end
+  end
+end

data/lib/eco/data/locations/dsl.rb

@@ -0,0 +1,35 @@
+module Eco::Data::Locations
+  # It allows to create your own helper
+  # @example of usage:
+  #     module LocHelp
+  #       include Eco::Data::Locations::DSL
+  #     end
+  #
+  #     nodes_list = LocHelp.csv_nodes_from(csv_list_filename)
+  #     csv_tree   = LocHelp.nodes_to_csv_tree(nodes_list)
+  #     File.open(output_filename, 'w') { |fd| fd.write(csv_tree.to_csv) }
+  #
+  # @example of usage:
+  #     class Foo
+  #       include Eco::Data::Locations::DSL
+  #
+  #       def csv_tree_to_csv_list(csv_tree_filename)
+  #         csv_list = nodes_to_csv_list(csv_nodes_from(csv_tree_filename))
+  #         File.open(output_filename, 'w') { |fd| fd.write(csv_list.to_csv) }
+  #       end
+  #
+  #       def live_tree_to_csv_tree(org_tagtree)
+  #         File.open(output_filename, 'w') { |fd| fd.write(csv_tree(org_tagtree).to_csv) }
+  #       end
+  #     end
+  #
+  module DSL
+    class << self
+      def included(base)
+        super(base)
+        base.extend Eco::Data::Locations::NodeBase::Builder
+        base.send :include, Eco::Data::Locations::NodeBase::Builder
+      end
+    end
+  end
+end

data/lib/eco/data/locations/node_base/builder.rb

@@ -0,0 +1,26 @@
+module Eco::Data::Locations::NodeBase
+  module Builder
+    include Eco::Data::Locations::NodeBase::Parsing
+    include Eco::Data::Locations::NodeBase::Serial
+    include Eco::Data::Locations::NodeBase::CsvConvert
+    include Eco::Data::Locations::NodeBase::Treeify
+
+    # @param data [CSV::Table, NodeBase, Array<NodeBase>]
+    # @return [NodeBase::Class] the Node class we can use.
+    def node_class(data)
+      case data
+      when ::CSV::Table
+        return Eco::Data::Locations::NodePlain if Eco::Data::Locations::NodePlain.csv_matches_format?(csv)
+        return Eco::Data::Locations::NodeLevel if Eco::Data::Locations::NodeLevel.csv_matches_format?(csv)
+      when Array
+        return nil unless sample = data.first
+        node_class(sample)
+      when Eco::Data::Locations::NodeBase
+        return nil unless data.class < Eco::Data::Locations::NodeBase
+        data.class
+      else
+        raise ArgumentError, "Expecting CSV::Table. Given: #{csv.class}" unless csv.is_a?(::CSV::Table)
+      end
+    end
+  end
+end

data/lib/eco/data/locations/node_base/csv_convert.rb

@@ -0,0 +1,57 @@
+module Eco::Data::Locations::NodeBase
+  module CsvConvert
+    include Eco::Data::Locations::NodeBase::Parsing
+
+    def tree_class
+      Eco::API::Organization::TagTree
+    end
+
+    # @yield [Node] optional custom serializer
+    # @yieldreturn [Hash] the serialized Node
+    # @param value [CSV::Table, Eco::API::Organization::TagTree]
+    # @return [Array<Hash>] a plain list of hash nodes
+    def hash_list(value, &block)
+      return hash_list(org_tree(value)) if value.is_a?(::CSV::Table)
+      return value.as_nodes_json        if value.is_a?(tree_class)
+      raise ArgumentError, "Expecting Eco::API::Organization::TagTree or CSV::Table. Given: #{value.class}"
+    end
+
+    # @yield [Node] optional custom serializer
+    # @yieldreturn [Hash] the serialized Node
+    # @param value [CSV::Table, Eco::API::Organization::TagTree]
+    # @return [Array<Hash>] a hierarchical tree of hash nodes,
+    #   ready to be parsed as an organization tagtree
+    def hash_tree(value, &block)
+      return hash_tree_from_csv(value, &block) if value.is_a?(::CSV::Table)
+      return value.as_json                     if value.is_a?(tree_class)
+      raise ArgumentError, "Expecting Eco::API::Organization::TagTree or CSV::Table. Given: #{value.class}"
+    end
+
+    # @yield [Node] optional custom serializer
+    # @yieldreturn [Hash] the serialized Node
+    # @param value [CSV::Table, Eco::API::Organization::TagTree]
+    # @return [Eco::API::Organization::TagTree]
+    def org_tree(value, &block)
+      return tree_class.new(hash_tree(value), &block) if value.is_a?(::CSV::Table)
+      return tree_class.new(value.as_json)            if value.is_a?(tree_class)
+      raise ArgumentError, "Expecting Eco::API::Organization::TagTree or CSV::Table. Given: #{value.class}"
+    end
+
+    # @yield [Node] optional custom serializer
+    # @yieldreturn [Hash] the serialized Node
+    # @return [CSV::Table] a table with L1 to Ln columns ready for dump to csv
+    def csv_tree(value, encoding: 'utf-8', &block)
+      Eco::CSV::Table.new(hash_tree_to_tree_csv(hash_tree(value, &block)))
+    end
+
+    # @note it just converts to an organizational tagtree and uses a helper method.
+    # @yield [Node] optional custom serializer
+    # @yieldreturn [Hash] the serialized Node
+    # @param value [CSV::Table, Eco::API::Organization::TagTree]
+    # @return [CSV::Table] a table with a list of nodes and their parents
+    def csv_list(value, &block)
+      value = org_tree(value, &block) unless value.is_a?(tree_class)
+      Eco::CSV.Table.new(hash_list(value))
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Eco::Data::Locations::NodeBase
+  module Parsing
+    include Eco::Data::Locations::Convert
+    include Eco::Data::Locations::NodeBase::Treeify
+
+    # @param csv [CSV::Table]
+    # @return [Array<NodePlain>, Array<NodeLevel>] with integrity issues resolved.
+    def nodes_from_csv(csv)
+      raise ArgumentError, "Expecting CSV::Table. Given: #{csv.class}" unless csv.is_a?(::CSV::Table)
+      return Eco::Data::Locations::NodePlain.nodes_from_csv(csv) if Eco::Data::Locations::NodePlain.csv_matches_format?(csv)
+      return Eco::Data::Locations::NodeLevel.nodes_from_csv(csv) if Eco::Data::Locations::NodeLevel.csv_matches_format?(csv)
+      raise ArgumentError, "The input csv does not have the required format to read a locations structure."
+    end
+
+    # @yield [Node] optional custom serializer
+    # @yieldreturn [Hash] the serialized Node
+    # @return [Array<Hash>] a hierarchical tree of nested Hashes via `nodes` key.
+    def hash_tree_from_csv(csv, &block)
+      raise ArgumentError, "Expecting CSV::Table. Given: #{csv.class}" unless csv.is_a?(::CSV::Table)
+      treeify(nodes_from_csv(csv), &block)
+    end
+
+    # Shortcut to obtain a list of parsed nodes out of a file
+    # @param filename [String] the csv file.
+    # @return [Array<NodePlain>, Array<NodeLevel>] with integrity issues resolved.
+    def csv_nodes_from(filename, encoding: 'utf-8')
+      nodes_from_csv(csv_from(filename, encoding: 'utf-8'))
+    end
+  end
+end

data/lib/eco/data/locations/node_base/serial.rb

@@ -0,0 +1,26 @@
+module Eco::Data::Locations::NodeBase
+  module Serial
+    include Eco::Data::Locations::NodeBase::Treeify
+    include Eco::Data::Locations::Convert
+
+    # @param item [Eco::Data::Locations::NodeBase] an instance object of a child class.
+    # @return [Proc] the serializer to be used.
+    def serializer(item)
+      raise "Execting a chidren of NodeBase. Given: #{item.class}" unless item.class < Eco::Data::Locations::NodeBase
+      item.serializer
+    end
+
+    # @paran nodes [Array<NodeBase>]
+    # @return [CSV::Table] ready to dump into a hierarhical **csv** (columns are tree levels)
+    def nodes_to_csv_tree(nodes)
+      hash_tree_to_tree_csv(treeify(nodes))
+    end
+
+    # @paran nodes [Array<NodeBase>]
+    # @return [CSV::Table] ready to dump into a nodes list **csv** (rows are nodes; a column holds `parent_id`)
+    def nodes_to_csv_list(nodes)
+      tree = Eco::API::Organization::TagTree.new(treeify(nodes))
+      Eco::CSV::Table.new(tree.as_nodes_json)
+    end
+  end
+end

data/lib/eco/data/locations/node_base/tag_validations.rb

@@ -0,0 +1,52 @@
+module Eco::Data::Locations::NodeBase
+  module TagValidations
+    ALLOWED_CHARACTERS = "A-Za-z0-9 &_'\/.-"
+    VALID_TAG_REGEX    = /^[#{ALLOWED_CHARACTERS}]+$/
+    INVALID_TAG_REGEX  = /[^#{ALLOWED_CHARACTERS}]+/
+    VALID_TAG_CHARS    = /[#{ALLOWED_CHARACTERS}]+/
+    DOUBLE_BLANKS      = /\s\s+/
+
+    def clean_id(str)
+      blanks_x2 = has_double_blanks?(str)
+      partial   = replace_not_allowed(str)
+      remove_double_blanks(partial).tap do |result|
+        next if invalid_warned?
+        if partial != str
+          invalid_chars = identify_invalid_characters(str)
+          puts "• (Row: #{self.row_num}) Invalid characters _#{invalid_chars}_ (removed): '#{str}' (converted to '#{result}')"
+        elsif blanks_x2
+          puts "• (Row: #{self.row_num}) Double blanks (removed): '#{str}' (converted to '#{result}')"
+        end
+        invalid_warned!
+      end
+    end
+
+    def invalid_warned?
+      @invalid_warned ||= false
+    end
+
+    def invalid_warned!
+      @invalid_warned = true
+    end
+
+    def has_double_blanks?(str)
+      return false if str.nil?
+      str.match(DOUBLE_BLANKS)
+    end
+
+    def remove_double_blanks(str)
+      return nil if str.nil?
+      str.gsub(DOUBLE_BLANKS, ' ').strip
+    end
+
+    def replace_not_allowed(str)
+      return nil if str.nil?
+      return str if str.match(VALID_TAG_REGEX)
+      str.gsub(INVALID_TAG_REGEX, ' ')
+    end
+
+    def identify_invalid_characters(str)
+      str.gsub(VALID_TAG_CHARS, '')
+    end
+  end
+end

data/lib/eco/data/locations/node_base/treeify.rb

@@ -0,0 +1,150 @@
+module Eco::Data::Locations::NodeBase
+  # Generic treeifier
+  # @note expects nodes to have these properties:
+  #   1. `id`, `name` and `parentId`
+  #   2. `parent`
+  #   3. `tracked_level`
+  module Treeify
+    include Eco::Language::AuxiliarLogger
+
+    # @note if block is no given, it auto-detects the `serializer` **block**.
+    # @yield [NodeBase] for each included node
+    # @yieldreturn [Hash] custom hash model when treeifying (allows to set more keys/properties).
+    # @nodes [Array<NodeBase>] list of nodes
+    # @return [Array<Hash>] a hierarchical tree of nested Hashes via `nodes` key.
+    def treeify(nodes, &block)
+      return [] if nodes.empty?
+      block ||= nodes.first.class.serializer
+      get_children(nil, parents_hash(nodes), &block)
+    end
+
+    private
+
+    def parents_hash(nodes)
+      nodes.each_with_object({}) do |node, parents|
+        (parents[node.parentId] ||= []).push(node)
+      end
+    end
+
+    # @note
+    #   1. It tracks the `level` where nodes are discovered
+    #   2. If the node had already a tracked level, it warns and keeps the previous level
+    #   3. The above can translate into some
+    # @yield [node]
+    # @yieldreturn [Hash] custom hash model when treeifying
+    def get_children(node_id, parents, parent: nil, done_ids: {}, level: 0, &block)
+      level_ids = []
+      (parents[node_id] ||= []).each_with_object([]) do |child, results|
+        # Skipping done id. Add proper warnings...
+        # => rely on `done_ids` to identify if an `id` has already been done
+        next report_skipped_node(child, parent, done_ids, level, level_ids, parents) if done_ids[child.id]
+
+        # Fill in tracking data
+        child.parent        = parent
+        child.tracked_level = level + 1
+        level_ids << child.id
+
+        node_hash = {
+          "id"        => child.id,
+          "name"      => child.name,
+          "parent_id" => node_id
+        }
+        node_hash.merge(yield(child)) if block_given?
+        # we must register the `id` before recursing down
+        done_ids[child.id] = child
+        results << node_hash.merge({
+          "nodes" => get_children(child.id, parents, parent: child, done_ids: done_ids, level: level + 1, &block).compact
+        })
+      end
+    end
+
+    def parent_msg(parent)
+      parent ? "child of '#{parent.id}'" : "top level"
+    end
+
+    def level_msg(level)
+      "at lev: #{level}"
+    end
+
+    def indent(level)
+      "#{" " * level}"
+    end
+
+    # Gives different warnings, depending the case
+    def report_skipped_node(node, parent, done_ids, level, level_ids, parents)
+      lev          = level + 1
+      done_node    = done_ids[node.id]
+      prev_parent  = node.parent
+      prev_level   = node.tracked_level
+      node_dup     = done_node && (done_node != node)
+      lev_dup      = level_ids.include?(node.id)
+      multi_parent = (!prev_parent == !!parent) || (prev_parent && (prev_parent.id != parent.id))
+
+      row_num      = node.respond_to?(:row_num) ? node.row_num : nil
+      row_str      = row_num ? "(Row: #{row_num}) " : ''
+      node_str     = "#{row_str}Node '#{node.id}' #{level_msg(lev)} (#{parent_msg(parent)})"
+
+      # Implementation integrity guard
+      # => as we don't register in `done_ids` those that are skipped,
+      #   when a `node` has already a tracked `parent` or `level`,
+      #   it should not happen that the `node.id` retrieves a different node in `node_ids`.
+      if (prev_parent || prev_level) && node_dup # && !done_node
+        str  = "Integrity issue in Treeify. "
+        str << "A Node with tracked level or parent should be present in done_ids, but it isn't."
+        str << "\n • #{node_str}."
+        raise str
+      end
+      # From here on, do NOT expect `node_dup` where `node` has tracked `parent` or `level`.
+
+      # Implementation integrity guard
+      # => as`level_ids` only relates to the current `parent`,
+      #   and as `done_ids` don't get those skipped,
+      #   when we get an ID double-up in `level_ids`,
+      #   there must be a `done_node` AND
+      #   `done_node` can only have `tracked_level` matching the current one
+      #   Moreover, they should have exactly the same parentId.
+      if lev_dup && (multi_parent || !done_node || done_node.tracked_level != lev)
+        str  = "Integrity issue in Treeify. "
+        str << "A Node with ID already in level_ids should have same tracked_level as current level."
+        str << "\n • #{node_str}."
+        raise str
+      end
+      # From here on, do NOT expect `lev_up` where there isn't `done_node` or it has different level or parent.
+
+      cyclic    = multi_parent && done_node == node
+      double_up = node_dup || lev_dup
+
+      msg  = []
+      msg << "#{indent(level)}WARNING: Skipping #{node_str}."
+
+      if cyclic
+        str  = "#{indent(level)+1}Cyclic definition. By skipping the node, "
+        str << "it will remain as #{parent_msg(done_node.parent)} (#{level_msg(prev_level)})."
+        msg << str
+      end
+
+      if double_up
+        str  = "#{indent(level)+1}The node ID has been tracked as #{level_msg(done_node.tracked_level)}, "
+        str << "as #{parent_msg(node_dup.parent)} "
+        str << "(same parent)."      if lev_dup
+        str << "(different parent)." if multi_parent
+        msg << str
+      end
+
+      unless cyclic || double_up
+        str  = "Integrity issue in Treeify. "
+        str  = "Skipping is only applicable to double_ups or cyclic nodes."
+        str << "\n • #{node_str}."
+        raise str
+      end
+
+      if children = parents[node.id]
+        str  = "#{indent(level)+1}Immediate children of skipped node (will probably be missing): "
+        str << children.map {|gc| "'#{gc.id}'"}.join(", ")
+        msg << str
+      end
+
+      log(:warn) { msg.join('\n') }
+    end
+  end
+end

data/lib/eco/data/locations/node_base.rb

@@ -0,0 +1,48 @@
+module Eco::Data::Locations
+  module NodeBase
+    require_relative 'node_base/tag_validations'
+    include Eco::Data::Locations::NodeBase::TagValidations
+
+    require_relative 'node_base/treeify'
+    require_relative 'node_base/parsing'
+    require_relative 'node_base/serial'
+    require_relative 'node_base/csv_convert'
+    require_relative 'node_base/builder'
+    extend Eco::Data::Locations::NodeBase::Builder
+
+    ALL_ATTRS = []
+
+    attr_accessor :tracked_level, :parent
+
+    def copy
+      self.class.new.set_attrs(**self.to_h)
+    end
+
+    def attr(sym)
+      self.send(sym.to_sym)
+    end
+
+    def set_attrs(**kargs)
+      kargs.each {|attr, value| set_attr(attr, value)}
+      self
+    end
+
+    def set_attr(attr, value)
+      self.send("#{attr}=", value)
+    end
+
+    def values_at(*attrs)
+      attrs.map {|a| attr(a)}
+    end
+
+    def to_h(*attrs)
+      attrs = self.class::ALL_ATTRS if attrs.empty?
+      attrs.zip(values_at(*attrs)).to_h
+    end
+
+    def slice(*attrs)
+      return {} if attrs.empty?
+      to_h(*attrs)
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+class Eco::Data::Locations::NodeLevel
+  module Builder
+    include Eco::Data::Locations::NodeLevel::Parsing
+    include Eco::Data::Locations::NodeLevel::Serial
+  end
+end

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

@@ -0,0 +1,74 @@
+class Eco::Data::Locations::NodeLevel
+  module Cleaner
+    include Eco::Language::AuxiliarLogger
+    include Eco::Data::Locations::Convert
+
+    # Prevents repeated node ids/tags, decouples merged levels,
+    # covers gaps (jumping multiple levels)
+    # @note
+    #   1. It first discards node ids/tags that have been already pulled (discard repeated)
+    #   2. For non repeated, it identifies if there's a gap (jump of multiple levels)
+    #   3. It covers the gap if present by decoupling merged parent(s) from the same node (see node.decouple)
+    #   4. Then, it delegates the filling in of parents to `fill_in_parents` function.
+    # @return [Array<NodeLevel>] child to parent relationships solved and no double-ups.
+    def tidy_nodes(nodes, prev_level: 0, main: true)
+      reset_trackers! if main
+      nodes.each_with_object([]) do |node, out|
+        node_id = node.id
+        if done_ids.include?(node_id)
+          repeated_ids << "#{node_id} (level: #{node.level})"
+        else
+          level = node.actual_level
+          if level > prev_level + 1
+            gap = level - (prev_level + 1)
+            msg = "(Row: #{node.row_num}) ID/Tag '#{node_id}' (lev #{level}) jumps #{gap} level(s) (expected #{prev_level + 1})."
+            #puts "  " + node.tags_array.pretty_inspect
+            missing_nodes = node.decouple(gap)
+
+            msg << "\n  Adding missing upper level(s): " + missing_nodes.map(&:raw_tag).pretty_inspect
+            log(:info) { msg }
+
+            out.push(*tidy_nodes(missing_nodes, prev_level: prev_level, main: false))
+            # puts node.actual_level
+            # pp node.tags_array
+            level = prev_level + 1
+          end
+          out       << node
+          done_ids  << node_id
+          prev_level = level
+        end
+      end.yield_self do |out|
+        report_repeated_node_ids(repeated_ids) if main
+        fill_in_parents(out)
+      end
+    end
+
+    # Sets the `parentId` property.
+    def fill_in_parents(nodes)
+      nodes.tap do |nodes|
+        prev_nodes = empty_level_tracker_hash(11)
+        nodes.each do |node|
+          if parent_node = prev_nodes[node.actual_level - 1]
+            node.parentId = parent_node.id
+          end
+          prev_nodes[node.raw_level] = node
+        end
+      end
+    end
+
+    # Tracker helper (those repeated)
+    def repeated_ids
+      @repeated_ids ||= []
+    end
+
+    # Tracker helper (those done)
+    def done_ids
+      @done_ids ||= []
+    end
+
+    def reset_trackers!
+      @done_ids     = []
+      @repeated_ids = []
+    end
+  end
+end