eco-helpers 3.0.37 → 3.1.2

data/lib/eco/api/usecases/graphql/samples/location/command/dsl.rb

@@ -17,8 +17,8 @@ class Eco::API::UseCases::GraphQL::Samples::Location
     #       end
     #     end
     def inputs(*_args, force_continue: force_continue?, **_kargs, &_block) # rubocop:disable Lint/UnusedMethodArgument
-      msg  = "You should implement this method in your child class.\n'
-      msg << 'Which should yield the input Hash and the stage or descriptor."
+      msg  = "You should implement this method in your child class.\n"
+      msg << 'Which should yield the input Hash and the stage or descriptor.'
       raise Eco::API::UseCases::GraphQL::Base::NotImplementedMethod, msg
     end
 

data/lib/eco/api/usecases/lib/base/env.rb

@@ -1,6 +1,6 @@
 module Eco::API::UseCases::Lib::Base
   # Basic stuff you would need in any use case
-  # @note this is intended to be at the foremost part upfront
+  # @note this is intended to be at the foremost part upfront: with **prepend**.
   module Env
     class << self
       def included(base)
@@ -14,32 +14,30 @@ module Eco::API::UseCases::Lib::Base
     module InstanceMethods
       private
 
-      def config
-        session.config
-      end
-
       def session(required: true)
-        if instance_variable_defined?(:@session) && !@session.nil?
-          @session
-        elsif defined?(super) && !super.nil?
-          super
-        elsif Object.const_defined?(:ASSETS)
-          ASSETS.session
-        elsif required
-          raise 'Missing session object'
-        end
+        return @session       if instance_variable_defined?(:@session) && !@session.nil?
+        return super()        if defined?(super()) && !super().nil?
+        return ASSETS.session if Object.const_defined?(:ASSETS)
+        return                unless required
+
+        raise 'Missing session object'
       end
 
       def options(required: true)
-        if instance_variable_defined?(:@options) && !@options.nil?
-          @options
-        elsif defined?(super) && !super.nil?
-          super
-        elsif Object.const_defined?(:ASSETS)
-          ASSETS.cli.options
-        else
-          raise 'Missing options object'
-        end
+        return @options           if instance_variable_defined?(:@options) && !@options.nil?
+        return super()            if defined?(super()) && !super().nil?
+        return ASSETS.cli.options if Object.const_defined?(:ASSETS)
+        return                    unless required
+
+        raise 'Missing options object'
+      end
+
+      def config
+        session.config
+      end
+
+      def micro
+        session.micro
       end
     end
   end

data/lib/eco/api/usecases/lib/files/file_pattern.rb

@@ -10,7 +10,7 @@ module Eco::API::UseCases::Lib::Files
 
     # Can't pass this via CLI option, as it breaks the regular expression
     def file_pattern(required: true)
-      fpc = file_pattern_const
+      fpc = file_pattern_from_const
       return fpc if fpc
       return     unless required
 
@@ -19,21 +19,48 @@ module Eco::API::UseCases::Lib::Files
       raise WrongConst, msg
     end
 
-    def file_pattern_const
-      if (fpc = options.dig(:sftp, :file_pattern_const))
-        msg = "(#{self.class}) Invalid file pattern const referral: #{fpc}"
-        raise WrongConst, msg unless fpc.match(CONST_REFERRAL)
-
-        begin
-          self.eval(fpc)
-        rescue NameError
-          self.class.const_get(fpc)
-        end
-      elsif self.class.const_defined?(:FILE_PATTERN)
-        self.class::FILE_PATTERN
+    def file_pattern_from_const
+      as_regex(insensitive: true) do
+        value = fetch_pattern_const(file_pattern_const_from_options)
+
+        next value                    unless value.nil?
+        next self.class::FILE_PATTERN if self.class.const_defined?(:FILE_PATTERN)
+      end
+    end
+
+    def file_pattern_const_from_options
+      return unless (fpc = options.dig(:sftp, :file_pattern_const))
+
+      fpc
+    end
+
+    def fetch_pattern_const(name, exception: true)
+      return if name.to_s.strip.empty?
+
+      msg = "(#{self.class}) Invalid file pattern const referral: #{name}"
+      raise WrongConst, msg unless name.match(CONST_REFERRAL)
+
+      begin
+        self.eval(name)
+      rescue NameError
+        self.class.const_get(name)
       end
     rescue NameError
-      raise WrongConst, "(#{self.class}) Unknown constant: #{fpc}"
+      raise WrongConst, "(#{self.class}) Unknown constant: #{name}" if exception
+    end
+
+    def as_regex(value = nil, insensitive: true)
+      value = yield if block_given?
+
+      case value
+      when Regexp
+        value
+      when String
+        esub = Regexp.escape(value)
+        return /#{esub}/i if insensitive
+
+        /#{esub}/
+      end
     end
   end
 end

data/lib/eco/api/usecases/lib/files/input_file.rb

@@ -0,0 +1,110 @@
+module Eco::API::UseCases::Lib::Files
+  # @note Assumes that, if **Cli** invoked, there could be **Cli** `options` defined
+  # under `:input` `:file`:
+  #   - `:name`
+  #   - `:format` (overriding `INPUT_FORMAT` const)
+  #   - `:encoding`
+  #   - `:pattern` (target pattern const)
+  # @note it includes and extends `FilePattern`:
+  #   - `file_pattern_from_const` would prioritize constants as accepted
+  #     in `INPUT_FILENAME_CONSTS`
+  #   - `file_pattern_const_from_options` would prioritize `:input` `:file` `:pattern`
+  module InputFile
+    INPUT_FILENAME_CONSTS = %i[
+      INPUT_FILENAME IN_FILENAME INPUT_FILE_PATTERN IN_FILE_PATTERN
+    ].freeze
+
+    class << self
+      def included(base)
+        super
+
+        base.send :include, Eco::API::UseCases::Lib::Base::Env unless base.include?(Eco::API::UseCases::Lib::Base::Env)
+        base.send :extend, Eco::Data::Files::Folder
+        base.send :include, Eco::API::UseCases::Lib::Files::FilePattern
+        base.send :include, InstanceMethods
+      end
+    end
+
+    module InstanceMethods
+      private
+
+      # @todo REVIEW: in practice, it collides with Sftp#local_folder
+      # @todo it is not clear if it should join onto `config.active_enviro`
+      def input_folder
+        File.join(
+          config.active_enviro,
+          self.class::IN_FOLDER
+        )
+      end
+
+      def input_file
+        @input_file ||= (input_file_from_options || newest_file).tap do |file|
+          if file
+            log(:info) { "Using input file '#{file}'" }
+          else
+            log(:warn) { 'Could not find any input file' }
+            exit 0
+          end
+        end
+      end
+
+      def input_file_from_options
+        options.dig(:input, :file, :name)
+      end
+
+      # @note assuming filenames hold a name pattern `YYYY-MM-dd`.
+      def newest_file
+        @newest_file ||= input_files.last
+      end
+
+      # @note based on `input_folder` && `input_file_pattern`
+      # @todo it some cases it has been used/defined as csv_files
+      def input_files(&block)
+        self.class.folder_files(
+          input_folder,
+          input_format,
+          regexp: input_file_pattern,
+          &block
+        )
+      end
+
+      def input_encoding
+        options.dig(:input, :file, :encoding) || 'utf-8'
+      end
+
+      # It helps to identify the extension of the input file.
+      # @note it may not be essential, but good practice as a safe-guard.
+      def input_format
+        frm = options.dig(:input, :file, :format)
+        return frm                             if frm
+        return self.class::INPUT_FORMAT.to_sym if self.class.const_defined?(:INPUT_FORMAT)
+
+        :csv
+      end
+
+      def input_file_pattern
+        file_pattern
+      end
+
+      # Overrides to FilePattern
+
+      def file_pattern_from_const
+        as_regex(insensitive: true) do
+          value = INPUT_FILENAME_CONSTS.detect do |const|
+            next self.class.const_get(const) if self.class.const_defined?(const)
+          end
+
+          next value if value
+
+          super
+        end
+      end
+
+      def file_pattern_const_from_options
+        return super unless (fpc = options.dig(:input, :file, :pattern))
+
+        fpc
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/lib/files/sftp.rb

@@ -74,10 +74,10 @@ module Eco::API::UseCases::Lib::Files
       end
     end
 
-    def sftp_archive_file!(filename, folder: 'Archive')
+    def sftp_archive_file!(filename, subfolder: 'Archive')
       basename       = File.basename(filename)
       remote_file    = to_remote_path(basename)
-      archive_folder = to_remote_path(folder)
+      archive_folder = to_remote_path(subfolder)
       archived_file  = "#{archive_folder}/#{basename}"
 
       sftp_move_file(remote_file, archived_file)
@@ -124,6 +124,9 @@ module Eco::API::UseCases::Lib::Files
       end
     end
 
+    # @note it can be used for both:
+    #   - for pulling files to
+    #   - and for pushing files from
     def local_folder
       return super if defined?(super) && !super.nil?
 

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

@@ -5,3 +5,4 @@ end
 
 require_relative 'files/sftp'
 require_relative 'files/file_pattern'
+require_relative 'files/input_file'

data/lib/eco/api/usecases/lib/locations/base.rb

@@ -0,0 +1,23 @@
+module Eco::API::UseCases::Lib::Locations
+  module Base
+    class << self
+      def included(base)
+        super
+
+        base.send :include, Eco::API::UseCases::Lib::Base::Env unless base.included?(Eco::API::UseCases::Lib::Base::Env)
+      end
+    end
+
+    private
+
+    def location?(value)
+      locations.tag?(value)
+    end
+    alias_method :tag?, :location?
+
+    def locations
+      config.tagtree
+    end
+    alias_method :tagtree, :locations
+  end
+end

data/lib/eco/api/usecases/lib/locations/mapping.rb

@@ -0,0 +1,94 @@
+module Eco::API::UseCases::Lib::Locations
+  module Mapping
+    LOCATION_MAPPING          = true
+    LOCATION_MAPS_FILE        = nil
+    LOCATION_MAPS_INTERNAL    = :first
+    LOCATION_MAPS_INSENSITIVE = true
+
+    class << self
+      def included(base)
+        super
+
+        base.send :include, Locations::Base
+      end
+    end
+
+    def unknown_locations
+      @unknown_locations ||=
+        Eco::Data::CountTrace.new(self)
+    end
+
+    def report_unknown_locations!(msg: nil, level: :warn)
+      unknown_locations.report!(msg: msg, level: level)
+    end
+
+    private
+
+    def to_location(value)
+      value = value.to_s.strip
+      return if value.empty?
+
+      if location_mapping? && locations_mapper.external?(value)
+        locations_mapper.to_internal(value)
+      elsif location?(value)
+        value
+      else
+        unknown_locations.trace!(value)
+      end
+    end
+    alias_method :to_tag, :to_location
+
+    def to_location_code(value)
+      value = value.to_s.strip
+      return if value.empty?
+
+      if location_mapping? && locations_mapper.internal?(value)
+        locations_mapper.to_external(value)
+      else
+        value
+      end
+    end
+
+    def locations_mapper(
+      internal:    loc_maps_internal_order,
+      insensitive: loc_maps_insensitive,
+      maps_file:   loc_maps_file
+    )
+      return @locations_mapper if instance_variable_defined?(:@locations_mapper)
+
+      @locations_mapper = config.locations_mapper(
+        internal:    internal,
+        insensitive: insensitive,
+        maps_file:   maps_file
+      )
+    end
+
+    def location_mapping?
+      return false unless self.class::LOCATION_MAPPING
+      return false unless loc_maps_file
+      return false unless locations_mapper
+      return false unless locatoins_mapper.empty?
+
+      true
+    end
+
+    def loc_maps_file
+      return @loc_maps_file if instance_variable_defined?(:@loc_maps_file)
+
+      @loc_maps_file   = loc_maps_file_const
+      @loc_maps_file ||= config.locations_map_file
+    end
+
+    def loc_maps_file_const
+      self.class::LOCATION_MAPS_FILE if self.class.const_defined?(:MAPS_FILE)
+    end
+
+    def loc_maps_internal_order
+      self.class::LOCATION_MAPS_INTERNAL
+    end
+
+    def loc_maps_insensitive
+      self.class::LOCATION_MAPS_INSENSITIVE
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::Lib
+  module Locations
+  end
+end
+
+require_relative 'locations/base'
+require_relative 'locations/mapping'

data/lib/eco/api/usecases/lib/people/base.rb

@@ -0,0 +1,20 @@
+module Eco::API::UseCases::Lib::People
+  module Base
+    class << self
+      def included(base)
+        super
+
+        base.send :include, Eco::API::UseCases::Lib::Base::Env unless base.included?(Eco::API::UseCases::Lib::Base::Env)
+      end
+    end
+
+    private
+
+    def people
+      return @people if instance_variable_defined?(:@people) && !@people.nil?
+      return super   if defined?(super) && !super.nil?
+
+      @people ||= micro.people_load(modifier: %i[newest save])
+    end
+  end
+end

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

@@ -0,0 +1,6 @@
+module Eco::API::UseCases::Lib
+  module People
+  end
+end
+
+require_relative 'people/base'

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

@@ -10,3 +10,5 @@ end
 require_relative 'lib/error_handling'
 require_relative 'lib/base'
 require_relative 'lib/files'
+require_relative 'lib/locations'
+require_relative 'lib/people'

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

@@ -1,7 +1,7 @@
 module Eco
   module API
     class UseCases
-      class OozeCases
+      class OozeCases # rubocop:disable Lint/EmptyClass
       end
     end
   end

data/lib/eco/api/usecases/ooze_samples/ooze_base_case.rb

@@ -190,7 +190,7 @@ class Eco::API::UseCases::OozeSamples::OozeBaseCase < Eco::API::Common::Loaders:
   def new_target(object, warn_pending_changes: true)
     if dirty?(target)
       if warn_pending_changes
-        msg  =  "You you are switching to a new target #{object_reference(object)}"
+        msg  = "You you are switching to a new target #{object_reference(object)}"
         msg << " after doing unsaved changes to #{object_reference(target)}"
         log(:warn) { msg }
       end

data/lib/eco/api/usecases/ooze_samples/ooze_from_doc_case.rb

@@ -1,6 +1,6 @@
 # Use case to abstract FORM from word document
 class Eco::API::UseCases::OozeSamples::OozeFromDocCase < Eco::API::UseCases::OozeSamples::OozeUpdateCase
-  name "ooze-forms-case"
+  name 'ooze-forms-case'
   type :other
 
   private
@@ -16,7 +16,7 @@ class Eco::API::UseCases::OozeSamples::OozeFromDocCase < Eco::API::UseCases::Ooz
   end
 
   def with_tables
-    raise "There are no tables in the doc" unless table_count > 0
+    raise "There are no tables in the doc" unless table_count.positive?
     i = 0
     doc.tables.each do |table|
       yield(table, i) if block_given?
@@ -29,7 +29,7 @@ class Eco::API::UseCases::OozeSamples::OozeFromDocCase < Eco::API::UseCases::Ooz
   end
 
   def tables?
-    table_count > 0
+    table_count.positive?
   end
 
   def doc

data/lib/eco/api/usecases/ooze_samples/ooze_run_base_case.rb

@@ -57,7 +57,10 @@ class Eco::API::UseCases::OozeSamples::OozeRunBaseCase < Eco::API::UseCases::Ooz
   end
 
   def prompt_to_confirm!
-    micro.prompt_user('Do you want to proceed (y/N)?', default: 'Y') do |response|
+    micro.prompt_user(
+      'Do you want to proceed (y/N)?',
+      default: 'Y'
+    ) do |response|
       exit(1) unless response.upcase.start_with?('Y')
     end
   end

data/lib/eco/api/usecases/ooze_samples/ooze_update_case.rb

@@ -8,7 +8,7 @@ class Eco::API::UseCases::OozeSamples::OozeUpdateCase < Eco::API::UseCases::Ooze
     fld   = nil
     fld ||= value if value.is_a?(Ecoportal::API::V2::Page::Component)
     fld ||= target.components.get_by_id(value)
-    fld ||= target.components.select {|fld| same_name?(fld.label, value)}
+    fld ||= target.components.select {|field| same_name?(field.label, value)} # rubocop:disable Lint/UselessAssignment
     #fld ||= value.reference if value.is_a?(Ecoportal::API::V2::Page::Force::Binding)
   end
 end

data/lib/eco/api/usecases/ooze_samples/register_export_case.rb

@@ -9,6 +9,7 @@ class Eco::API::UseCases::OozeSamples::RegisterExportCase < Eco::API::Common::Lo
     def batch_size(size = nil)
       @batch_size ||= 25
       return @batch_size unless size
+
       @batch_size = size
     end
   end
@@ -34,7 +35,9 @@ class Eco::API::UseCases::OozeSamples::RegisterExportCase < Eco::API::Common::Lo
 
   # Write here your script
   def process_ooze(ooze = target)
-    raise "You need to inherit from this class ('#{self.class}') and call super with a block" unless block_given?
+    msg = "You need to inherit from this class ('#{self.class}') and call super with a block"
+    raise ArgumentError, msg unless block_given?
+
     yield(ooze)
   end
 
@@ -94,7 +97,7 @@ class Eco::API::UseCases::OozeSamples::RegisterExportCase < Eco::API::Common::Lo
 
   def batched_search_results
     msg = "Missing block. It yields in slices of #{self.class.batch_size} results"
-    raise msg unless block_given?
+    raise ArgumentError, msg unless block_given?
 
     results_preview
     results = []
@@ -145,6 +148,7 @@ class Eco::API::UseCases::OozeSamples::RegisterExportCase < Eco::API::Common::Lo
         end
       end
     end
+
     exit_error "Stage '#{id_name}' doesn't exist in ooze '#{ooze_id}'"
   end
 

data/lib/eco/api/usecases/ooze_samples/register_migration_case.rb

@@ -1,7 +1,8 @@
 # Use case to offer the basics to migrate a register by creating new entries
 # @note
 #   - You can define methods `filters` and `search` to change the target entries of the register
-#   - You can define a json file named after your use case file (i.e. new_training.json) to pair source-destination fields:
+#   - You can define a json file named after your use case file (i.e. new_training.json)
+#     to pair source-destination fields:
 #     - This file format expects an object {} where keys are field types (i.e. "select", "plain_text")
 #       and the value is an array with either:
 #         1. field label name (String or RegExp body/source),
@@ -20,7 +21,7 @@
 #     - This is specially useful to discard rich text field guidelines (i.e. `{"rich_text" => [".*guideline:"]}`)
 # This case expects `options[:source][:register_id]`
 class Eco::API::UseCases::OozeSamples::RegisterMigrationCase < Eco::API::UseCases::OozeSamples::RegisterUpdateCase
-  name "register-migration-case"
+  name 'register-migration-case'
   type :other
 
   #batch_size 2
@@ -45,7 +46,7 @@ class Eco::API::UseCases::OozeSamples::RegisterMigrationCase < Eco::API::UseCase
   def main(session, options, usecase, &block)
     if options[:dry_run]
       @csv = []
-      super(session, options, usecase, &block)
+      super
     else
       CSV.open(out_csv_filename, 'w') do |csv|
         @csv = csv
@@ -136,7 +137,7 @@ class Eco::API::UseCases::OozeSamples::RegisterMigrationCase < Eco::API::UseCase
 
   def script_fullname
     msg = "You should define this method in the child class with this content:\n"
-    msg << "  @script_fullname||= File.expand_path(__FILE__)"
+    msg << '  @script_fullname||= File.expand_path(__FILE__)'
     raise msg
   end
 
@@ -180,7 +181,7 @@ class Eco::API::UseCases::OozeSamples::RegisterMigrationCase < Eco::API::UseCase
   end
 
   def name_timestamp
-    @name_timestamp ||= Time.now.strftime("%Y%m%d%H%M%S")
+    @name_timestamp ||= Time.now.strftime('%Y%m%d%H%M%S')
   end
 
   def field_maps
@@ -196,7 +197,7 @@ class Eco::API::UseCases::OozeSamples::RegisterMigrationCase < Eco::API::UseCase
   end
 
   def script_basename
-    @script_basename ||= File.basename(script_fullname, "_case.rb")
+    @script_basename ||= File.basename(script_fullname, '_case.rb')
   end
 
   def script_dirname

data/lib/eco/api/usecases/ooze_samples/register_update_case.rb

@@ -11,6 +11,7 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
     def batch_size(size = nil)
       @batch_size ||= 25
       return @batch_size unless size
+
       @batch_size = size
     end
   end
@@ -33,7 +34,9 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
           process_ooze(&block)
         end
       elsif mode == :delegate
-        raise 'You need to pass a block when running main in `:delegate` mode' unless block_given?
+        msg = 'You need to pass a block when running main in `:delegate` mode'
+        raise ArgumentError, msg unless block_given?
+
         yield
       end
     end
@@ -80,8 +83,10 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
 
         if (pending = queue_shift(page_result.id)) && dirty?(pending)
           msg  = 'Inconsistent search results. '
-          msg << "Launching update on '#{object_reference(pending)}' to be able to queue it back"
+          msg << "Launching update on '#{object_reference(pending)}' "
+          msg << 'to be able to queue it back'
           log(:warn) { msg }
+
           update_ooze(pending)
         end
 
@@ -101,11 +106,13 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
     return unless object.respond_to?(:id)
 
     unless object.is_a?(Ecoportal::API::V2::Page) or object.is_a?(Ecoportal::API::V2::Pages::PageStage)
-      raise "Queuing is just for entries. Expecting Page or PageStage. Given: #{object.class}"
+      msg = "Queuing is just for entries. Expecting Page or PageStage. Given: #{object.class}"
+      raise ArgumentError, msg
     end
 
     if (elem = queue_get(object.id))
       msg = "Something is wrong. Native case 'RegisterUpdateCase' is "
+
       if (elem != object) && dirty?(elem)
         msg << "trying to queue different objects with same page id:\n"
         msg << " * already queued (changes will go): #{object_reference(elem)}\n"
@@ -134,11 +141,13 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
   end
 
   def batched_search_results
-    raise "Missing block. It yields in slices of #{self.class.batch_size} results" unless block_given?
+    msg = "Missing block. It yields in slices of #{self.class.batch_size} results"
+    raise ArgumentError, msg unless block_given?
 
     results_preview
 
     results = []
+
     apiv2.registers.search(register_id, search_options) do |page_result|
       results << page_result
       if results.length >= self.class.batch_size
@@ -182,6 +191,7 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
         end
       end
     end
+
     batched_oozes.clear
   end