eco-helpers 2.5.3 → 2.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adb24d7f2036b028bdd81302479211ea745e82abdb6b3a69afa2253e3f8fe444
-  data.tar.gz: 4d149fa100a5a661e4b019aa601c0da3af051ba6e019c77e22b6599c312a4fcb
+  metadata.gz: d241b7bc57bd81e9b3a6b1d71ecab5f7530b7b6df176301adc21584722f2b247
+  data.tar.gz: a8beafa1e6cd1e3425291121c55b78fe144f155021ab149148fcc6ce35569984
 SHA512:
-  metadata.gz: 8583dc7689de13744421db380f3193072f754091a1db6434010568907ff2f4e39d5ed3146b045ab47632cdf0bc5bc8c7e3fe326be466e7b4926f8c8c41344b31
-  data.tar.gz: b34c886f7cde59854838a087fcb10442f14835a87bf3a264534a4a4641a3a1ca2b302352a920f37536cb0686a213ce7d2d06949c2c2bc89e31f3c8e7650ab32e
+  metadata.gz: 2bad589998061077bac0f6adb500fdbb9402b77578da68bf43a84f83101a2bf862213acb00707a363f5583c47ec94a876c367360c562043865e573232b272c4c
+  data.tar.gz: 7c33f358f5cbb7ab0b3118d7b0b20e86a9f686f2e1f49216e23bea5ab504ca4bb0bbb2eeab8bb37daf0d11b997af0160212ff7ab2d1fe382fa05a6b354529f48

data/CHANGELOG.md

@@ -1,7 +1,37 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [2.5.3] - 2023-07-xx
+## [2.5.6] - 2023-08-xx
+
+### Added
+### Changed
+### Fixed
+
+## [2.5.5] - 2023-08-03
+
+### Added
+  - `Eco::API::Organization::TagTree` - **added/improved methods**
+    - `#as_json` new parameter `max_depth:` to be able to cut the tree
+    - `#active_tree` new method to exclude archived nodes.
+    - `#truncate` new method to obtain a tree cut to `max_depth:`
+  - `Eco::API::Session::Config::Tagtree`: **exposed** `include_archived:` (a.k.a. `inludeArchivedNodes`).
+    - This change states that `session.tagtree` does not retrieve archived nodes by default, while `session.live_tree` does retrieve archived nodes.
+    - This change required an update on the `ecoportal-api-graphql` **gem**
+
+### Fixed
+  - `Eco::API::Organization::TagTree#path` - dups the result (rather than exposing the internal path array)
+
+## [2.5.4] - 2023-07-27
+
+### Added
+  - SFTP case helpers: `Eco::API::UseCases::GraphQL::Utils::Sftp`
+  - `Eco::Data::Locations::NodeDiff` and `Eco::Data::Locations::NodeDiff::NodeDiffs`
+    - Aim to identify changes in the locations structure
+
+### Changed
+  - Some internal tidy up in `Eco::API::UseCases::GraphQL`
+
+## [2.5.3] - 2023-07-19
 
 ### Added
   - _GraphQL base case_ for **locations structure update**.
@@ -52,7 +82,6 @@ All notable changes to this project will be documented in this file.
   - `Eco::API::Session::Config::Workflow#exit_handle`
     - Allows to define a callback on `SystemExit` (`exit` call).
 
-### Changed
 ### Fixed
   - `Eco::API::Session::Config::Workflow` on `SystemExit` preserve original exit `status` value (i.e. `0`, `1`)
     - It was changing an `exit 1` to be an `exit 0`

data/eco-helpers.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'ecoportal-api', '>= 0.9.4', '< 0.10'
   spec.add_dependency 'ecoportal-api-v2', '>= 1.1.3', '< 1.2'
-  spec.add_dependency 'ecoportal-api-graphql', '>= 0.3.8', '< 0.4'
+  spec.add_dependency 'ecoportal-api-graphql', '>= 0.3.9', '< 0.4'
   spec.add_dependency 'aws-sdk-s3',    '>= 1.83.0', '< 2'
   spec.add_dependency 'aws-sdk-ses',   '>= 1.36.0', '< 2'
   spec.add_dependency 'dotenv',        '>= 2.7.6',  '< 3'

data/lib/eco/api/common/people/person_entry.rb

@@ -523,7 +523,6 @@ module Eco
             call_order = parsing? ? [ext, mad, int, fin] : [fin, int, mad, ext]
             call_order.each {|proc| proc.call}
           end
-
         end
       end
     end

data/lib/eco/api/organization/tag_tree.rb

@@ -76,9 +76,23 @@ module Eco
           @archived
         end
 
+        def active?
+          !archived?
+        end
+
         # @return [Eco::API::Organization::TagTree]
         def dup
-          self.class.new(as_json)
+          self.class.new(as_json, name: name, id: id)
+        end
+
+        # @return [Eco::API::Organization::TagTree] with **non** `archived` nodes only
+        def active_tree
+          self.class.new(as_json(include_archived: false), name: name, id: id)
+        end
+
+        # @return [Eco::API::Organization::TagTree] with nodes up to `max_depth`
+        def truncate(max_depth: total_depth)
+          self.class.new(as_json(max_depth: max_depth), name: name, id: id)
         end
 
         # Iterate through all the nodes of this tree
@@ -161,11 +175,26 @@ module Eco
         # Returns a tree of Hashes form nested via `nodes` (or just a list of hash nodes)
         # @yield [node_json, node] block for custom output json model
         # @yiledreturn [Hash] the custom json model.
-        # @include_children [Boolean] whether it should return a tree hash or just a list of hash nodes.
+        # @param include_children [Boolean] whether it should return a tree hash or just a list of hash nodes.
+        # @param include_archived [Boolean] whether it should include archived nodes.
+        # @param max_depth [Boolean] up to what level `depth` nodes should be included.
         # @return [Array[Hash]] where `Hash` is a `node` (i.e. `{"tag" => TAG, "nodes": Array[Hash]}`)
-        def as_json(include_children: true, &block)
-          return [] if top? && !include_children
-          children_json = nodes.map {|nd| nd.as_json(include_children: true, &block)} if include_children
+        def as_json(include_children: true, include_archived: true, max_depth: total_depth, &block)
+          max_depth ||= total_depth
+          return nil if max_depth < depth
+          return []  if top? && !include_children
+          return nil if archived? && !include_archived
+
+          if include_children
+            child_nodes   = nodes
+            child_nodes   = child_nodes.select(&:active?) unless include_archived
+            kargs         = {
+              include_children: include_children,
+              include_archived: include_archived,
+              max_depth:        max_depth
+            }
+            children_json = child_nodes.map {|nd| nd.as_json(**kargs, &block)}.compact
+          end
 
           if top?
             children_json
@@ -180,8 +209,8 @@ module Eco
 
         # Returns a plain list form of hash nodes.
         # @return [Array[Hash]] where `Hash` is a plain `node`
-        def as_nodes_json
-          all_nodes.map {|nd| nd.as_json(include_children: false)}
+        def as_nodes_json(&block)
+          all_nodes.map {|nd| nd.as_json(include_children: false, &block)}
         end
 
         # @return [Boolean] `true` if there are tags in the node, `false` otherwise.
@@ -287,8 +316,8 @@ module Eco
         # @param key [String] tag to find the path to.
         # @return [Array<String>]
         def path(key = nil)
-          return @path if !key
-          @hash_paths[key.upcase]
+          return @path.dup if !key
+          @hash_paths[key.upcase].dup
         end
 
         # Helper to assign tags to a person account.

data/lib/eco/api/session/config/tagtree.rb

@@ -3,18 +3,30 @@ module Eco
     class Session
       class Config
         class TagTree < BaseConfig
+          class MissingTagtree < StandardError
+          end
+
           attr_key :file
 
-          def scope_tree(enviro: nil)
+          # @param include_archived [Boolean] whether or not it should include archived nodes.
+          # @return [Eco::API::Organization::TagTree]
+          def scope_tree(enviro: nil, include_archived: true, raise_on_missing: true)
             return @tagtree if instance_variable_defined?(:@tagtree) && @tagtree.enviro == enviro
             if tree_file = self.file
               if (tree = file_manager.load_json(tree_file)) && !tree.empty?
                 @tagtree  = Eco::API::Organization::TagTree.new(tree, enviro: enviro)
               end
             end
-            @tagtree ||= live_tree(enviro: enviro).tap do |tree|
+
+            kargs = {
+              enviro:               enviro,
+              includeArchivedNodes: include_archived
+            }
+
+            @tagtree ||= live_tree(**kargs).tap do |tree|
               unless tree && !tree.empty?
-                raise "Could not find a locations structure."
+                msg = "Could not find a local or live locations structure."
+                raise MissingTagtree, msg
               end
             end
           end
@@ -23,13 +35,18 @@ module Eco
           # If `id` is provided, it only retrieves this locations structure.
           def live_tree(id: nil, enviro: nil, include_archived: false, **kargs, &block)
             return @live_tree if instance_variable_defined?(:@live_tree) && @live_tree.enviro == enviro
+
+            kargs = {
+              enviro:               enviro,
+              includeArchivedNodes: include_archived
+            }.merge(kargs)
+
             if id
-              args       = {id: id, enviro: enviro, include_archived: include_archived}.merge(kargs)
+              args       = { id: id }.merge(kargs)
               @live_tree = live_tree_get(**args, &block)
             else
-              # note that `include_archived` nodes is NOT the same as including archived structures
-              # => In `live_tree` the paramter refers to nodes
-              trees      = live_trees(enviro: enviro, &block)
+              kargs
+              trees      = live_trees(**kargs, &block)
               @live_tree = trees.reject do |tree|
                 tree.empty?
               end.max do |a,b|
@@ -45,26 +62,33 @@ module Eco
 
           # Gets a single locations structure
           # @note it does not memoize
+          # @param include_archived [Boolean] whether or not to include archived **nodes**
+          # @return [Eco::API::Organization::TagTree, NilClass]
           def live_tree_get(id: nil, enviro: nil, include_archived: false, **kargs, &block)
             return nil unless apis.active_api.version_available?(:graphql)
             return nil unless graphql = apis.api(version: :graphql)
-            #kargs = { includeArchived: include_archived }.merge(kargs).slice(:includeArchived)
-            # For now, this endpoint only accepts `id` as a parameter. It is pending to
-            # expose further parameters via query
-            return nil unless tree = graphql.currentOrganization.locationStructure(id: id, &block)
+
+            kargs = {
+              id:                   id,
+              includeArchivedNodes: include_archived
+            }.merge(kargs)
+
+            return nil unless tree = graphql.currentOrganization.locationStructure(**kargs, &block)
             args = { enviro: enviro, id: tree.id, name: tree.name }
             Eco::API::Organization::TagTree.new(tree.treeify, **args)
           end
 
           # Retrieves all the location structures of the organisation
+          # @param include_archived [Boolean] whether or not to include archived **nodes**
+          # @return [Array<Eco::API::Organization::TagTree>]
           def live_trees(enviro: nil, include_archived: false, **kargs, &block)
             [].tap do |eco_trees|
               next unless apis.active_api.version_available?(:graphql)
               next unless graphql = apis.api(version: :graphql)
+
               kargs = {
-                includeArchived:    include_archived,
-                includeUnpublished: false
-              }.merge(kargs).slice(:includeArchived, :includeUnpublished)
+                includeArchivedNodes: include_archived
+              }.merge(kargs)
 
               next unless trees = graphql.currentOrganization.locationStructures(**kargs, &block)
               trees.each do |tree|

data/lib/eco/api/session/config.rb

@@ -235,9 +235,15 @@ module Eco
         end
 
         # It uses the `tagtree.json` file and in its absence, if `graphql` enabled, the largest `life_tagtree`
+        # @note it does NOT include archived nodes by default.
+        #   - This is for legacy (most usecases don't)
+        # @param include_archived [Boolean] whether or not it should include archived nodes.
         # @return [Eco::API::Organization::TagTree]
-        def tagtree(enviro: nil)
-          @tagtree ||= tagtree_config.scope_tree(enviro: enviro)
+        def tagtree(enviro: nil, include_archived: false, raise_on_missing: true)
+          kargs = {
+            enviro: enviro, include_archived: include_archived, raise_on_missing: raise_on_missing
+          }
+          @tagtree ||= tagtree_config.scope_tree(**kargs)
         end
 
         # It obtains the first of the live tagtree in the org

data/lib/eco/api/usecases/default_cases/reinvite_trans_case.rb

@@ -12,9 +12,9 @@ class Eco::API::UseCases::DefaultCases::ReinviteTransCase < Eco::API::Common::Lo
     invite   = session.new_job("main", "invite", :update, usecase, :account)
     users.each do |person|
       if force_invite?
-        person.account.send_invites = true
-      else
         person.account.force_send_invites = true
+      else
+        person.account.send_invites = true
       end
       invite.add(person)
     end

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

@@ -0,0 +1,15 @@
+module Eco::API::UseCases::GraphQL::Helpers::Base
+  # Basic stuff you would need in any use case
+  module CaseEnv
+    include Eco::Language::AuxiliarLogger
+    attr_reader :session, :options
+
+    def config
+      session.config
+    end
+
+    def simulate?
+      options.dig(:simulate)
+    end
+  end
+end

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

@@ -1,20 +1,12 @@
 module Eco::API::UseCases::GraphQL::Helpers
   module Base
-    include Eco::Language::AuxiliarLogger
-    attr_reader :session, :options
+    require_relative 'base/case_env'
+    include Eco::API::UseCases::GraphQL::Helpers::Base::CaseEnv
 
     def graphql
       @graphql ||= session.api(version: :graphql)
     end
 
-    def config
-      session.config
-    end
-
-    def simulate?
-      options.dig(:simulate)
-    end
-
     # Keep a copy of the requests/responses for future reference
     def backup(data, type:)
       dry_run   = simulate? ? "_dry_run" : ""
@@ -24,7 +16,7 @@ module Eco::API::UseCases::GraphQL::Helpers
     end
 
     def exit_error(msg)
-      logger.error(msg)
+      log(:error) { msg }
       exit(1)
     end
   end

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

@@ -68,7 +68,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
       msg << "nor options(:source, :structure_id). "
       msg << "Infering active locations structure."
       log(:warn) { msg }
-      if self.current_tree = session.live_tree
+      if self.current_tree = session_live_tree
         @target_structure_id = current_tree.id
       end
     end
@@ -81,7 +81,13 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
       tree_init = current_tree
       target_id = target_structure_id
       return current_tree if current_tree != tree_init
-      self.current_tree = session.live_tree(id: target_id, include_archived: true)
+      self.current_tree = session_live_tree(id: target_id)
+    end
+
+    # Unique access point to retrieve the live tree
+    # @note ensures archived nodes are retrieved.
+    def session_live_tree(id: nil)
+      session.live_tree(id: id, include_archived: true)
     end
   end
 end

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

@@ -3,17 +3,25 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
     include Eco::Language::AuxiliarLogger
     include Eco::API::UseCases::GraphQL::Helpers::Location::Base
 
-    # Prevents each request from timing out
-    COMMANDS_PER_PAGE  = 45
-    # Whether to stop or continue on command fail
-    FORCE_CONTINUE     = false
+    DEFAULT_COMMANDS_PER_PAGE = 45
+    DEFAULT_FORCE_CONTINUE    = false
 
+    # Prevents each request from timing out
     def commands_per_page
-      self.class::COMMANDS_PER_PAGE
+      if self.class.const_defined?(:COMMANDS_PER_PAGE)
+        self.class::COMMANDS_PER_PAGE
+      else
+        DEFAULT_COMMANDS_PER_PAGE
+      end
     end
 
+    # Whether to stop or continue on command fail
     def force_continue?
-      self.class::FORCE_CONTINUE
+      if self.class.const_defined?(:FORCE_CONTINUE)
+        self.class::FORCE_CONTINUE
+      else
+        DEFAULT_FORCE_CONTINUE
+      end
     end
 
     # With given the commands, it generates the input of the endpoint mutation.

data/lib/eco/api/usecases/graphql/utils/sftp.rb

@@ -0,0 +1,74 @@
+module Eco::API::UseCases::GraphQL::Utils
+  module Sftp
+    include Eco::API::UseCases::GraphQL::Helpers::Base::CaseEnv
+
+
+    def remote_subfolder
+      nil
+    end
+
+    def remote_folder(subfolder = remote_subfolder)
+      "#{sftp_config.remote_folder}/#{subfolder || ''}"
+    end
+
+    def sftp_group_id
+      if self.class.const_defined?(:SFTP_GROUP)
+        self.class.const_get(:TARGET_STRUCTURE_ID)
+      elsif group_id = options.dig(:sftp, :group)
+        group_id
+      end
+    end
+
+    def upload(local_file, remote_folder: self.remote_folder, gid: sftp_group_id)
+      return false unless local_file && File.exists?(local_file)
+      dest_file = "#{remote_folder}/#{File.basename(local_file)}"
+      res       = sftp_session.upload!(local_file, dest_file)
+      attrs     = sftp_session.stat!(dest_file)
+      if gid && gid != attrs.gid
+        stat_res = sftp_session.setstat!(dest_file, {permissions: 0660, uid: attrs.uid, gid: gid})
+      end
+      logger.info("Uploaded '#{local_file}' (#{res})")
+    end
+
+    def ensure_remote_empty
+      files = with_remote_files
+      unless files.empty?
+        msg  = "There are still files in the remote folder that will be deleted: '#{remote_folder}':\n"
+        msg += "  • " + files.map do |file|
+          file.longname
+        end.join("\n  • ") + "\n"
+        session.prompt_user("Do you want to proceed to delete? (Y/n):", explanation: msg, default: "Y", timeout: 3) do |response|
+          if response.upcase.start_with?("Y")
+            files.each do |file|
+              remote_full_path = to_remote_path(file.name)
+              res = sftp_session.remove(remote_full_path)
+              logger.info("Deleted remote file: '#{remote_full_path}' (#{res})")
+            end
+          end
+        end
+      end
+    end
+
+    def with_remote_files
+      sftp.files(remote_folder).each do |remote_file|
+        yield(remote_file) if block_given?
+      end
+    end
+
+    def to_remote_path(file, subfolder: nil)
+      remote_folder(subfolder) + "/" + file
+    end
+
+    def sftp_config
+      session.config.sftp
+    end
+
+    def sftp_session
+      sftp.sftp_session
+    end
+
+    def sftp
+      session.sftp
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/utils.rb

@@ -0,0 +1,6 @@
+module Eco::API::UseCases::GraphQL
+  module Utils
+  end
+end
+
+require_relative 'utils/sftp'

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

@@ -8,5 +8,6 @@ module Eco
 end
 
 require_relative 'graphql/helpers'
+require_relative 'graphql/utils'
 require_relative 'graphql/base'
 require_relative 'graphql/samples'

data/lib/eco/data/files/helpers.rb

@@ -75,11 +75,11 @@ module Eco
           Dir.exist?(path) || Dir.exist?(File.expand_path(path))
         end
 
-        def timestamp(timestamp_pattern = DEFAULT_TIMESTAMP_PATTERN)
-          Time.now.strftime(timestamp_pattern)
+        def timestamp(timestamp_pattern = DEFAULT_TIMESTAMP_PATTERN, date = Time.now)
+          date.strftime(timestamp_pattern)
         end
 
-        def timestamp_file(filename, timestamp_pattern = DEFAULT_TIMESTAMP_PATTERN)
+        def timestamp_file(filename, timestamp_pattern =DEFAULT_TIMESTAMP_PATTERN)
           file_pattern = Eco::Data::Files::FilePattern.new(filename)
           file_pattern.resolve(start: timestamp(timestamp_pattern) + '_')
         end

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

@@ -3,47 +3,16 @@ module Eco
     module Hashes
       class ArrayDiff
         extend Eco::Language::Models::ClassHelpers
-
-        class << self
-          def key(value = nil)
-            return @key unless value
-            @key = value.to_s
-          end
-
-          def key?
-            !!@key
-          end
-
-          def compare(*attrs)
-            compared_attrs.push(*attrs.map(&:to_s)).uniq!
-          end
-
-          def case_sensitive(value = nil)
-            @case_sensitive = false unless instance_variable_defined?(:@case_sensitive)
-            return @case_sensitive unless value
-            @case_sensitive = !!value
-          end
-
-          def case_sensitive?
-            !!@case_sensitive
-          end
-
-          def compared_attrs
-            @compared_attrs ||= []
-            @compared_attrs
-          end
-        end
+        # We can change the `DiffResult` class (items)
+        class_resolver :diff_result_class, "Eco::Data::Hash::DiffResult"
 
         include Eco::Language::AuxiliarLogger
 
         attr_reader :source1, :source2
         attr_reader :src_h1,  :src_h2
 
-        class_resolver :diff_result_class, "Eco::Data::Hash::DiffResult"
-
-        def initialize(source1, source2, logger: nil, **kargs)
+        def initialize(source1, source2, logger: nil)
           @logger  = logger if logger
-          @options = kargs
           @source1 = source1
           @source2 = source2
           @src_h1  = by_key(source1)
@@ -67,14 +36,11 @@ module Eco
           !diffs.empty?
         end
 
+        # All the items that contain the diff of a node.
+        # @return [Array<Eco::Data::Hash::DiffResult>]
         def source_results
           @source_results ||= paired_sources.each_with_object([]) do |(src1, src2), res|
-            args = {
-              key:            key,
-              compare:        compared_attrs,
-              case_sensitive: case_sensitive?
-            }
-            res << diff_result_class.new(src1, src2, **args)
+            res << diff_result_class.new(src1, src2)
           end
         end
 
@@ -91,35 +57,23 @@ module Eco
           all_keys.map {|key| [src_h1[key], src_h2[key]]}
         end
 
+        # @return [String] the `key` attribute of `diff_result_class`
         def key
-          @key ||= options_or(:key) do
-            self.class.key
-          end.tap do |k|
-            raise "missing main key attr to pair records. Given: #{k}" unless k.is_a?(String)
+          diff_result_class.key.tap do |k|
+            raise "#{diff_result_class}: missing main key attr to pair records. Given: #{k}" unless k.is_a?(String)
           end
         end
 
         def case_sensitive?
-          @case_sensitive ||= options_or(:case_sensitive) { self.class.case_sensitive? }
+          diff_result_class.case_sensitive?
         end
 
         def compared_attrs
-          @compared_attrs ||= options_or(:compared_attrs) do
-            self.class.compared_attrs
-          end.yield_self do |attrs|
-            raise "compared_attrs should be an array" unless attrs.is_a?(Array)
-            attrs.map(&:to_s)
-          end
+          diff_result_class.compared_attrs.map(&:to_s)
         end
 
         private
 
-        def options_or(opt)
-          opt = opt.to_sym
-          return @options[opt] if @options.key?(opt)
-          yield
-        end
-
         def symbolize_keys(hash)
           hash.each_with_object({}) do |(k, v), h|
             h[k.to_sym] = v

data/lib/eco/data/hashes/diff_meta.rb

@@ -0,0 +1,52 @@
+module Eco
+  module Data
+    module Hashes
+      module DiffMeta
+        class << self
+          def included(base)
+            super(base)
+            base.extend ClassMethods
+          end
+        end
+
+        module ClassMethods
+          # @param value [String, NilClass]
+          # @return [String] the attribute that is key of the node diff elements.
+          def key(value = nil)
+            return @key unless value
+            @key = value.to_s
+          end
+
+          # @return [Boolean] is there a `key` attribute defined?
+          def key?
+            !!@key
+          end
+
+          # @param attrs [Array<Symbol>, Array<String>]
+          # @return [Array<String>] the comparable attributes
+          def compare(*attrs)
+            compared_attrs.push(*attrs.map(&:to_s)).uniq!
+            compared_attrs
+          end
+
+          # Whether or not the diff calc of a node should be done case sensitive or insensitive.
+          def case_sensitive(value = nil)
+            @case_sensitive = false unless instance_variable_defined?(:@case_sensitive)
+            return @case_sensitive unless value
+            @case_sensitive = !!value
+          end
+
+          # @return [Boolean] are comparisons of values done case sensitive?
+          def case_sensitive?
+            !!@case_sensitive
+          end
+
+          # @return [Array<String>] the comparable attributes
+          def compared_attrs
+            @compared_attrs ||= []
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,19 +2,32 @@ module Eco
   module Data
     module Hashes
       class DiffResult
-        attr_reader :key
+        extend Eco::Language::Models::ClassHelpers
+        include Eco::Data::Hashes::DiffMeta
+
+        inheritable_class_vars :key, :compared_attrs, :case_sensitive
+
         attr_reader :src1, :src2
 
-        # @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
-          @compare = compare
-          @case_sensitive = case_sensitive
+        def initialize(src1, src2)
           @src1 = src1
           @src2 = src2
         end
 
+        def key
+          self.class.key
+        end
+
+        def case_sensitive?
+          self.class.case_sensitive?
+        end
+
+        def dup(src1: nil, src2: nil)
+          src1 ||= self.src1
+          src2 ||= self.src2
+          self.class.new(src1.dup, src2.dup)
+        end
+
         def new?
           !src1 && !!src2
         end
@@ -27,35 +40,39 @@ module Eco
           !new? && !del? && diff?
         end
 
+        # @note `diff_attrs` may not include the `key` attribute
+        #   This is always included via `new?` (new key value) and `del?` (missing key value)
+        # @return [Boolean] was there any change?
         def diff?
           new? || del? || !diff_attrs.empty?
         end
 
-        # Is the key attr value changing?
+        # Is the `key` attr value changing?
         def key?
           !(new? || del?) && diff_attr?(key)
         end
 
+        # Is `attr` part of the attributes that change?
         def diff_attr?(attr)
           return true if new?
           return true if del?
           diff_attrs.include?(attr.to_s)
         end
 
+        # @return [Value] the current value of `attr` (in `src2`)
         def attr(attr)
           return nil unless src2
           src2[attr.to_s]
         end
 
+        # @return [Value] the previous value of `attr` (in `src1`)
         def attr_prev(attr)
           return nil unless src1
           src1[attr.to_s]
         end
 
-        def previous(attr)
-          src1 && src1[attr.to_s]
-        end
-
+        # @note the `key` attribute will always be added (even if there's no change)
+        # @return [Hash] hash with the differences as per `src2`
         def diff_hash
           target_attrs = [key] | compared_attrs
           return src2.slice(*target_attrs) if new?
@@ -63,12 +80,14 @@ module Eco
           src2.slice(key, *diff_attrs)
         end
 
+        # @return [Array<Symbol>] hash with the differences as per `src2`
         def diff_attrs
           @diff_attrs ||= comparable_attrs.each_with_object([]) do |attr, out|
             out << attr unless eq?(src1[attr], src2[attr])
           end
         end
 
+        # @return [Boolean] whether `val1` is equal to `val2`
         def eq?(val1, val2)
           return true  if val1 == val2
           return false if case_sensitive?
@@ -76,25 +95,18 @@ module Eco
           val1.upcase == val2.upcase
         end
 
-        def case_sensitive?
-          !!@case_sensitive
-        end
-
+        # @note when is `new?` or to be deleted (`del?`), it returns empty array.
+        # @return [Array<String>] the set of attributes that are comparable in this instance.
         def comparable_attrs
           return [] if new? || del?
           compared_attrs
         end
 
+        # @return [Array<String>] the set of attributes that are comparable in this class.
         def compared_attrs
-          return @compared_attrs if instance_variable_defined?(:@compared_attrs)
-          @compared_attrs = \
-            if @compare == :all
-              src1.keys & src2.keys
-            elsif @compare.is_a?(Array)
-              @compare.map(&:to_s)
-            else
-              raise "Expecting 'compare' to be sym (:all) or Array<String>. Given: #{@compare.class}"
-            end
+          comp_attrs = self.class.compared_attrs.map(&:to_s).uniq
+          return comp_attrs unless comp_attrs.empty?
+          (src1&.keys || []) & (src2&.keys || [])
         end
       end
     end

data/lib/eco/data/hashes.rb

@@ -5,5 +5,6 @@ module Eco
   end
 end
 
+require_relative 'hashes/diff_meta'
 require_relative 'hashes/diff_result'
 require_relative 'hashes/array_diff'

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

@@ -0,0 +1,46 @@
+class Eco::Data::Locations::NodeDiff
+  module Accessors
+    class << self
+      def included(base)
+        super(base)
+        base.extend Eco::Language::Models::ClassHelpers
+        base.extend ClassMethods
+        base.inheritable_class_vars :exposed_attrs
+      end
+    end
+
+    module ClassMethods
+      # Creates the defined accessor attributes against `NodeDiff`
+      # It also creates a method with question mark that evaluates true if **any** the attr changed.
+      # @note the defined attributes are expected to be the keys within
+      #   the source Hashes that are being compared.
+      # @note accessing `src1` (prev) attributes, will have it's method as `prev_[attrName]`
+      def attr_expose(*attrs)
+        attrs.each do |attr|
+          meth  = attr.to_sym
+          methp = "prev_#{meth}".to_sym
+          methq = "diff_#{meth}?".to_sym
+
+          define_method meth do
+            attr(meth)
+          end
+
+          define_method methp do
+            attr_prev(meth)
+          end
+
+          exposed_attrs |= [meth]
+
+          define_method methq do
+            diff_attr?(meth)
+          end
+        end
+      end
+
+      # Keeps track on what attributes have been exposed.
+      def exposed_attrs
+        @exposed_attrs ||= []
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+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
+
+    SELECTORS = %i[id name id_name insert unarchive update move archive]
+    selector *SELECTORS
+
+    class_resolver :diff_result_class, Eco::Data::Locations::NodeDiff
+    attr_reader :original_tree
+
+    def initialize(*args, original_tree:, **kargs, &block)
+      super(*args, **kargs, &block)
+      @original_tree = original_tree
+    end
+
+    def diffs
+      @diffs ||= super.select do |res|
+        res.unarchive? || res.id_name? || res.insert? || res.move? || res.archive?
+      end
+    end
+
+    def diffs_details
+      section = '#' * 10
+      msg  = ''
+      if insert?
+        msg << " #{section}  I N S E R T S  #{section}\n"
+        msg << insert.map {|d| d.diff_hash.pretty_inspect}.join('')
+      end
+
+      if update?
+        msg << "\n #{section}  U P D A T E S  #{section}\n"
+        update.each do |d|
+          flags  = ''
+          #flags << 'i' if d.id?
+          flags << 'n' if d.diff_name?
+          flags << 'm' if d.move?
+          flags << 'u' if d.unarchive?
+          msg << "<< #{flags} >> "
+          msg << d.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('')
+      end
+
+      msg
+    end
+
+    def diffs_summary
+      return "There were no differences identified" if diffs.empty?
+      msg  = "Identified #{diffs.count} differences:\n"
+      msg << when_present(insert, '') do |count|
+        "  • #{count} nodes to insert\n"
+      end
+      msg << when_present(update, '') do |count|
+        "  • #{count} nodes to update\n"
+      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\n"
+      end
+      msg << when_present(move, '') do |count|
+        "    • #{count} nodes to move\n"
+      end
+      msg << when_present(unarchive, '') do |count|
+        "    • #{count} nodes to unarchive\n"
+      end
+      msg << when_present(archive, '') do |count|
+        "  • #{count} nodes to archive\n"
+      end
+      msg
+    end
+
+    private
+
+    def when_present(list, default = nil)
+      count = list.count
+      if count > 0
+        yield(count)
+      else
+        default
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+class Eco::Data::Locations::NodeDiff
+  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.
+    # @note the selector method name with a question mark should exist in the `diff_result_class`
+    def selector(*attrs)
+      attrs.each do |attr|
+        meth  = attr.to_sym
+        methq = "#{meth}?".to_sym
+        define_method meth do
+          diffs.select(&methq)
+        end
+
+        define_method methq do
+          diffs.any(&methq)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module Eco::Data::Locations
+  # Differences between node before and after
+  # @note this works with `Hash` object where basic keys are:
+  #   - `nodeId`
+  #   - `name`
+  #   - `parentId`
+  #   - `archived`
+  # @note other properties can be part of the `Hash` although
+  #   they may not influence the results.
+  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
+
+    attr_expose :nodeId, :name, :parentId, :archived
+
+    alias_method :insert?, :new?
+
+    alias_method :diff_name_src?, :diff_name?
+    # Has the property `name` changed?
+    def diff_name?
+      diff_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?
+
+    # Has any of `id` or `name` properties changed?
+    def id_name?
+      id? || diff_name?
+    end
+
+    # Has the parent id changed?
+    def move?
+      update? && diff_parentId?
+    end
+
+    # Has the `archived` property changed and it was `true`?
+    def unarchive?
+      !archived && update? && diff_archived?
+    end
+
+    # Has the `archived` property changed and it was `false`?
+    def archive?
+      !prev_archived && (del? || archived)
+    end
+  end
+end

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

@@ -18,13 +18,10 @@ module Eco::Data::Locations
 
     attr_accessor :parentId
 
-    def nodeId
-      id
-    end
-
     def id
       tag.upcase
     end
+    alias_method :nodeId, :id
 
     def name
       tag

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

@@ -17,6 +17,8 @@ module Eco::Data::Locations
     def id
       clean_id(super)
     end
+    # backwards compatibility
+    alias_method :tag, :id
 
     def name
       super || self.id
@@ -25,10 +27,5 @@ module Eco::Data::Locations
     def parentId
       self.parent_id
     end
-
-    # backwards compatibility
-    def tag
-      id
-    end
   end
 end

data/lib/eco/data/locations.rb

@@ -9,4 +9,5 @@ require_relative 'locations/convert'
 require_relative 'locations/node_base'
 require_relative 'locations/node_plain'
 require_relative 'locations/node_level'
+require_relative 'locations/node_diff'
 require_relative 'locations/dsl'

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = "2.5.3"
+  VERSION = "2.5.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 2.5.3
+  version: 2.5.5
 platform: ruby
 authors:
 - Oscar Segura
@@ -156,7 +156,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.8
+        version: 0.3.9
     - - "<"
       - !ruby/object:Gem::Version
         version: '0.4'
@@ -166,7 +166,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.8
+        version: 0.3.9
     - - "<"
       - !ruby/object:Gem::Version
         version: '0.4'
@@ -592,6 +592,7 @@ files:
 - lib/eco/api/usecases/graphql/base.rb
 - lib/eco/api/usecases/graphql/helpers.rb
 - lib/eco/api/usecases/graphql/helpers/base.rb
+- lib/eco/api/usecases/graphql/helpers/base/case_env.rb
 - lib/eco/api/usecases/graphql/helpers/location.rb
 - lib/eco/api/usecases/graphql/helpers/location/base.rb
 - lib/eco/api/usecases/graphql/helpers/location/command.rb
@@ -603,6 +604,8 @@ files:
 - lib/eco/api/usecases/graphql/samples/location/command/dsl.rb
 - lib/eco/api/usecases/graphql/samples/location/command/results.rb
 - lib/eco/api/usecases/graphql/samples/location/dsl.rb
+- lib/eco/api/usecases/graphql/utils.rb
+- lib/eco/api/usecases/graphql/utils/sftp.rb
 - lib/eco/api/usecases/ooze_cases.rb
 - lib/eco/api/usecases/ooze_cases/export_register_case.rb
 - lib/eco/api/usecases/ooze_samples.rb
@@ -670,6 +673,7 @@ files:
 - lib/eco/data/fuzzy_match/string_helpers.rb
 - lib/eco/data/hashes.rb
 - lib/eco/data/hashes/array_diff.rb
+- lib/eco/data/hashes/diff_meta.rb
 - lib/eco/data/hashes/diff_result.rb
 - lib/eco/data/locations.rb
 - lib/eco/data/locations/convert.rb
@@ -681,6 +685,10 @@ files:
 - lib/eco/data/locations/node_base/serial.rb
 - lib/eco/data/locations/node_base/tag_validations.rb
 - lib/eco/data/locations/node_base/treeify.rb
+- lib/eco/data/locations/node_diff.rb
+- lib/eco/data/locations/node_diff/accessors.rb
+- lib/eco/data/locations/node_diff/nodes_diff.rb
+- lib/eco/data/locations/node_diff/selectors.rb
 - lib/eco/data/locations/node_level.rb
 - lib/eco/data/locations/node_level/builder.rb
 - lib/eco/data/locations/node_level/cleaner.rb