eco-helpers 3.0.20 → 3.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96eaee3dd7897d77b22857cf8f812ce6d0639af324565c54f649c1e8068b7fb4
-  data.tar.gz: c9af686fe8f01d45eb3ea6a0dc89de276b789dfd6e3f64b515e17107b233b2d3
+  metadata.gz: c24fea5e80af03052ddec1ce701651a61e7575d812161ff4f62f8f70c29da1d1
+  data.tar.gz: 2c72186bf780afd1b706eb0fbf44669cd68ac1239e0ba95f923462190a08d85d
 SHA512:
-  metadata.gz: 66bdc8b7c98b2aa0e60e205ac64b47a302e2cd8dbe1efd1720ad36c04a4f4c1a70b2cbb4d4978c67a17bd0f86893d34b47ff809f95a3e06952c002b872872553
-  data.tar.gz: f205d190dc159c0218bc1cafa52f139a6faaa133a01190ae1b189d2b8b6ef2470f49b634169effcf2021023803ec58f1793b8ce4c019db9d1dd025df7bbf5493
+  metadata.gz: 4bf253ab9cc07090b25ffcec1ff853422e292ce4fe1dcddab026bead5ef48d5a4710d55f79b4a16477c6671d764296938374c6f18521e27ac808529eb1435fa7
+  data.tar.gz: 28da9eaed628e6e37c22b5dc3c703867c9941eac6ea2d364142823ffa3e00e86ed54d45648b75231b4e93f86aff666f5a69892cc9255260af4c2c6953b6483bd

data/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# jetbrains IDE
+.idea

data/CHANGELOG.md

@@ -2,7 +2,61 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.0.20] - 2024-12-xx
+## [3.0.22] - 2024-12-xx
+
+### Added
+
+- `Eco::Data::Mapper`
+  - Ability to pair in lower case
+  - `#internal?` and `#external?` would evaluate `true` for a lower case check.
+- `:model` named argument to use cases
+  - To diversify use cases
+- `Contractors` namespace (skeleton) onto `Eco::API::UseCases::GraphQL` within:
+  - `Helpers`
+  - `Samples`
+- Decoupled `Eco::API::Session::Batch::Feedback` into mulitple **modules**
+- Moved `Eco::API::Session::Batch::RequestStats` to be
+  - `Eco::API::Session::Batch::Feedback::RequestStats`
+
+### Changed
+
+- Moved `Cli` class methods out of `Eco::API::Common::Loaders::UseCase` (to `CliIdentify`)
+- Moved `Eco::API::Organization::PeopleSimilarity` to `Eco::API::Organization::People::Similarity`
+- **IMPORTANT** refactor to base UseCase and IO related classes on `data` (rather than `people`).
+  - This change aims for re-usability of existing use case logic.
+  - The changes have had impact on the workflow definitions.
+  - There is a **todo** list in the default_cli workflow implementation.
+- **Refactor** of `MicroCases` to be based on data model.
+- Upgrade dependencies:
+  - `ecoportal-api` gem upgrade.
+  - `ecoportal-api-v2` gem upgrade.
+  - `ecoportal-api-graphql` gem upgrade.
+
+### Fixed
+
+- Workflow should raise exception when referring to an unknown stage
+
+## [3.0.21] - 2024-12-16
+
+### Added
+
+- `Eco::API::Common::Session::Logger`
+  - Implement **channels** logging.
+
+### Changed
+
+- Moved `input` and `people` **cli_default configurations** to a class definition
+- `Eco::Language::AuxiliarLogger#log`
+  - Allow for multiple levels
+  - Return `NilClass`
+
+### Fixed
+
+- `Eco::API::Session::Batch::Job#summary`
+  - Ensure a summary of pending jobs can be handled, even if `#launch` was NOT explicitly called.
+  - As we don't consolidate, it may give more actual updates than pending, yet this is better than providing the `count` of entries in the job's queue.
+
+## [3.0.20] - 2024-12-07
 
 ### Added
 
@@ -16,8 +70,6 @@ All notable changes to this project will be documented in this file.
 
 - On failure, `Eco::API::Session::Job#summary` to give precise estimates on what is pending to be run.
 
-### Fixed
-
 ## [3.0.19] - 2024-11-21
 
 ### Added
@@ -162,8 +214,6 @@ All notable changes to this project will be documented in this file.
 
 ## [3.0.6] - 2024-08-26
 
-### Added
-
 ### Changed
 
 - `Eco::API::Microcases#people_search`

data/eco-helpers.gemspec

@@ -40,9 +40,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'bcrypt_pbkdf',  '~> 1.0'
   spec.add_dependency 'docx',          '>= 0.8.0', '< 0.9'
   spec.add_dependency 'dotenv',        '~> 3'
-  spec.add_dependency 'ecoportal-api',         '~> 0.10', '>= 0.10.7'
-  spec.add_dependency 'ecoportal-api-graphql', '~> 0.4',  '>= 0.4.3'
-  spec.add_dependency 'ecoportal-api-v2',      '~> 2.0',  '>= 2.0.12'
+  spec.add_dependency 'ecoportal-api',         '~> 0.10', '>= 0.10.8'
+  spec.add_dependency 'ecoportal-api-graphql', '~> 0.4',  '>= 0.4.4'
+  spec.add_dependency 'ecoportal-api-v2',      '~> 2.0',  '>= 2.0.15'
   spec.add_dependency 'ed25519',       '~> 1.2'
   spec.add_dependency 'fast_excel',    '>= 0.5.0',  '< 0.6'
   spec.add_dependency 'fuzzy_match',   '>= 2.1.0',  '< 2.2'

data/lib/eco/api/common/class_hierarchy.rb

@@ -15,7 +15,7 @@ module Eco
 
         # @return [Array<String>] the `keys` of the current class' `model`
         def model_attrs
-          (model && model.keys) || []
+          model&.keys || []
         end
 
         # Thanks to this step the format on the declaration of the model is flexible
@@ -24,24 +24,21 @@ module Eco
         def parse_model(model)
           case model
           when String
-            return parse_model(model.to_sym)
+            parse_model(model.to_sym)
           when Symbol
-            return {model => nil}
+            {model => nil}
           when Hash
-            return model.each_with_object({}) do |(k,v), hash|
-              hash[k.to_sym] = v
-            end
+            model.transform_keys(&:to_sym)
           when Enumerable
-            return model.each_with_object({}) do |sub, hash|
+            model.each_with_object({}) do |sub, hash|
               hash.merge!(parse_model(sub))
             end
           when NilClass
-            return nil
+            nil
           else
             raise "Incorrect model declaration, allowed String, Symbol, Hash and Enumerable. Given: #{model.class}"
           end
         end
-
       end
     end
   end

data/lib/eco/api/common/loaders/case_base.rb

@@ -6,17 +6,25 @@ module Eco
           class << self
             attr_writer :name, :type
 
+            alias_method :original_name, :name
+
             # The name that this case, policy or error handler will have.
             def name(value = nil)
-              name_only_once! if value
-              set_created_at!
-              return @name ||= to_s unless value
+              name_only_once!      if value
+              set_created_at!      unless @name
+              return original_name unless @name || value
+              return @name         unless value
+
               @name = value
             end
 
             # Prevent the same class to be re-opened/re-named
             def name_only_once!
-              raise "You have already declared #{self} or you are trying to give it a name twice" if @name
+              return unless @name
+
+              msg  = "You have already declared #{self} "
+              msg << "or you are trying to give it a name twice"
+              raise msg if @name
             end
           end
 

data/lib/eco/api/common/loaders/config/cli.rb

@@ -0,0 +1,9 @@
+class Eco::API::Common::Loaders::CliConfig < Eco::API::Common::Loaders::Config
+  class << self
+    def config
+      ASSETS.cli.config
+    end
+  end
+
+  delegate_missing_to :config
+end

data/lib/eco/api/common/loaders/config/workflow/cases_extension.rb

@@ -0,0 +1,53 @@
+class Eco::API::Common::Loaders::Workflow
+  module CasesExtension
+    private
+
+    def cli_usecases
+      cli.config.usecases
+    end
+
+    def cli_active_cases(io)
+      cli_usecases.active(io: io)
+    end
+
+    def cli_update_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        %i[transform sync].any? { |type| usecase.type == type }
+      end
+    end
+
+    def cli_other_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        %i[other].any? { |type| usecase.type == type }
+      end
+    end
+
+    def cli_input_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        io.class.input_required?(usecase.type)
+      end
+    end
+
+    def cli_data_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        io.class.data_required?(usecase.type)
+      end
+    end
+
+    def some_update_case?(io)
+      cli_update_cases(io).any?
+    end
+
+    def some_other_case?(io)
+      cli_other_cases(io).any?
+    end
+
+    def some_input_case?(io)
+      cli_input_cases(io).any?
+    end
+
+    def some_data_case?(io)
+      cli_data_cases(io).any?
+    end
+  end
+end

data/lib/eco/api/common/loaders/config/workflow/mailer.rb

@@ -19,7 +19,7 @@ class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::W
       next unless session.config.run_mode_remote?
 
       # temporary contingency: maybe_error_or_tree_updates?
-      next unless some_update?(io) || maybe_error_pages_or_tree_updates?(io)
+      next unless some_update_case?(io) || maybe_error_pages_or_tree_updates?(io)
 
       subject = base_subject
 
@@ -57,25 +57,13 @@ class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::W
       "#{active_enviro}#{space_desc}"
     end
 
-    def some_update?(io)
-      cli.config.usecases.active(io: io).any? do |usecase, _data|
-        %i[transform sync].any? { |type| usecase.type == type }
-      end
-    end
-
-    def other_case?(io)
-      cli.config.usecases.active(io: io).any? do |usecase, _data|
-        %i[other].any? { |type| usecase.type == type }
-      end
-    end
-
     def error?
       !!error
     end
 
     # @note at some stage, tree cases should have their own case type
     def maybe_error_pages_or_tree_updates?(io)
-      other_case?(io) && error?
+      some_other_case?(io) && error?
     end
 
     def errors_n_warnings(io)

data/lib/eco/api/common/loaders/config/workflow.rb

@@ -1,10 +1,14 @@
 class Eco::API::Common::Loaders::Workflow < Eco::API::Common::Loaders::Config
+  require_relative 'workflow/cases_extension'
+
   class << self
     def workflow
       config.workflow
     end
   end
 
+  extend CasesExtension
+
   delegate_missing_to :workflow
 end
 

data/lib/eco/api/common/loaders/config.rb

@@ -33,5 +33,6 @@ class Eco::API::Common::Loaders::Config
   delegate_missing_to :config
 end
 
+require_relative 'config/cli'
 require_relative 'config/workflow'
 require_relative 'config/session'

data/lib/eco/api/common/loaders/error_handler.rb

@@ -25,12 +25,13 @@ module Eco
             handlers.on(error, &method(:main))
           end
 
-          # @param people [Eco::API::Organization::People] the people in the queue of the current `job`
+          # @param data [Variant]
+          #   - people [Eco::API::Organization::People] the people in the queue of the current `job`
           # @param session [Eco::API::Session] the current session where the usecase kicks in.
           # @param options [Hash] the options that modify the case behaviour or bring some dependencies.
           # @param handler [Eco::API::Error::Hanlder] the `error handler` instance object.
           # @param job [Eco::API::Session::Batch::Job] the `Batch::Job` made on purpose for this handler.
-          def main(people, session, options, handler, job) # rubocop:disable Lint/UnusedMethodArgument
+          def main(data, session, options, handler, job) # rubocop:disable Lint/UnusedMethodArgument
             raise "You should implement this method"
           end
 

data/lib/eco/api/common/loaders/policy.rb

@@ -10,12 +10,13 @@ module Eco
             policies.define(name, &method(:main))
           end
 
-          # @param people [Eco::API::Organization::People] the people in the queue of the current `job`
+          # @param data [Variant]
+          #   - people [Eco::API::Organization::People] the people in the queue of the current `job`
           # @param session [Eco::API::Session] the current session where the usecase kicks in.
           # @param options [Hash] the options that modify the case behaviour or bring some dependencies.
           # @param policy [Eco::API::Policies::Policy] the `policy` instance object.
           # @param job [Eco::API::Session::Batch::Job] the `Batch::Job` that these `people` belong to the queue thereof.
-          def main(people, session, options, policy, job) # rubocop:disable Lint/UnusedMethodArgument
+          def main(data, session, options, policy, job = nil) # rubocop:disable Lint/UnusedMethodArgument
             raise "You should implement this method"
           end
         end

data/lib/eco/api/common/loaders/use_case/cli_identify.rb

@@ -0,0 +1,28 @@
+class Eco::API::Common::Loaders::UseCase
+  module CliIdentify
+    def cli!
+      cli&.apply!
+    end
+
+    def cli(cli_class = nil)
+      if cli_class.is_a?(Class)
+        msg = 'cli_class should inherit from Eco::API::UseCases::Cli'
+        raise ArgumentError, msg unless cli_class < Eco::API::UseCases::Cli
+
+        @cli = cli_class
+      elsif cli_class.nil?
+        return @cli if instance_variable_defined?(:@cli) && !@cli.nil?
+
+        # try to see if it's namespaced after the use case it provisions cli integration
+        begin
+          try_class = [to_s, 'Cli'].join('::')
+          @cli = Kernel.const_get(try_class)
+        rescue NameError
+          nil
+        end
+      else
+        raise ArgumentError, "Expecting a class. Given: #{cli_class.class} object"
+      end
+    end
+  end
+end

data/lib/eco/api/common/loaders/use_case/target_model.rb

@@ -0,0 +1,25 @@
+class Eco::API::Common::Loaders::UseCase
+  module TargetModel
+    class << self
+      def included(base)
+        super
+
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      #@note it inherently defaults to `:people` (out of backwards compatibility)
+      # @return [String] the `target_model`
+      def target_model(value = nil)
+        return @target_model = value if value
+
+        @target_model                if @target_model
+      end
+    end
+
+    def target_model
+      self.class.target_model
+    end
+  end
+end

data/lib/eco/api/common/loaders/use_case/type.rb

@@ -0,0 +1,37 @@
+class Eco::API::Common::Loaders::UseCase
+  module Type
+    class << self
+      def included(base)
+        super
+
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      # @return [Symbol] the `type` of usecase (i.e. `:sync`, `:transform`, `:import`, `:other`)
+      def type(value = nil)
+        return @type = value if value
+        return @type         if @type
+
+        types_sym_str = available_types.map do |tp|
+          ":#{tp}"
+        end.join(', ')
+
+        msg  = "You should specify a type of case "
+        msg << "[#{types_sym_str}] for #{self}"
+        raise msg
+      end
+
+      private
+
+      def available_types
+        Eco::API::UseCases::BaseCase.types
+      end
+    end
+
+    def type
+      self.class.type
+    end
+  end
+end

data/lib/eco/api/common/loaders/use_case.rb

@@ -3,66 +3,39 @@ module Eco
     module Common
       module Loaders
         class UseCase < Eco::API::Common::Loaders::CaseBase
-          class << self
-            # @return [Symbol] the `type` of usecase (i.e. `:sync`, `:transform`, `:import`, `:other`)
-            def type(value = nil)
-              unless value
-                msg  = "You should specify a type of case "
-                msg << "[:sync, :transform, :import, :other] for #{self}"
-                return @type || (raise msg)
-              end
-              @type = value
-            end
+          require_relative 'use_case/type'
+          require_relative 'use_case/target_model'
+          require_relative 'use_case/cli_identify'
 
-            def cli!
-              cli&.apply!
-            end
+          include Type
+          include TargetModel
+          extend CliIdentify
 
-            def cli(cli_class = nil)
-              if cli_class.is_a?(Class)
-                msg = "cli_class should inherit from Eco::API::UseCases::Cli"
-                raise ArgumentError, msg unless cli_class < Eco::API::UseCases::Cli
-
-                @cli = cli_class
-              elsif cli_class.nil?
-                return @cli if instance_variable_defined?(:@cli) && !@cli.nil?
-
-                # try to see if it's namespaced after the use case it provisions cli integration
-                begin
-                  try_class = [to_s, 'Cli'].join('::')
-                  @cli = Kernel.const_get(try_class)
-                rescue NameError
-                  nil
-                end
-              else
-                raise ArgumentError, "Expecting a class. Given: #{cli_class.class} object"
-              end
-            end
-          end
-
-          inheritable_class_vars :type, :cli
+          inheritable_class_vars :cli, :type, :target_model
 
           def initialize(usecases) # rubocop:disable Lint/MissingSuper
             msg = "Expected Eco::API::UseCases. Given #{usecases.class}"
             raise msg unless usecases.is_a?(Eco::API::UseCases)
 
-            usecases.define(name, type: type, &method(:main))
+            usecases.define(
+              name,
+              type:  type,
+              model: target_model,
+              &method(:main)
+            )
           end
 
           # The parameters of this method will depend on the `type` of usecase.
           # @param entries [Eco::API::Common::People::Entries] the input entries with the data.
-          # @param people [Eco::API::Organization::People] the people in the queue of the current `job`
+          # @param data [Variant]
+          #   - people [Eco::API::Organization::People] the people in the queue of the current `job`
           # @param session [Eco::API::Session] the current session where the usecase kicks in.
           # @param options [Hash] the options that modify the case behaviour or bring some dependencies.
           # @param usecase [Eco::API::Policies::Policy] the `usecase` instance object.
-          def main(entries, people, session, options, usecase) # rubocop:disable Lint/UnusedMethodArgument
+          def main(*_args)
             raise "You should implement this method"
           end
 
-          def type
-            self.class.type
-          end
-
           def cli_apply!
             self.class.cli!
           end

data/lib/eco/api/common/people/default_parsers/xls_parser.rb

@@ -27,7 +27,7 @@ class Eco::API::Common::People::DefaultParsers::XLSParser < Eco::API::Common::Lo
   end
 
   def expected_headers
-    log(:warn) {
+    log(:info) {
       "Headers detection is using your fields_map.json file (native behaviour)"
     }
     session.fields_mapper.list(:external).uniq

data/lib/eco/api/common/session/logger/cache.rb

@@ -4,7 +4,8 @@ module Eco
       module Session
         class Logger
           class Cache
-            LEVELS = %w[UNKNOWN FATAL ERROR WARN INFO DEBUG].freeze
+            LEVELS   = %w[UNKNOWN FATAL ERROR WARN INFO DEBUG].freeze
+            CHANNELS = Logger::CHANNELS.map(&:to_s).map(&:upcase).freeze
 
             def initialize
               reset
@@ -56,7 +57,8 @@ module Eco
             end
 
             def to_datetime(value)
-              return nil unless value
+              return unless value
+
               Time.parse(value)
             end
 
@@ -64,7 +66,7 @@ module Eco
               levels = [value].flatten.map {|v| to_level(v)}.compact
               return levels unless levels.empty?
 
-              LEVELS
+              valid_levels
             end
 
             def to_level(value)
@@ -75,7 +77,7 @@ module Eco
 
             def valid_level!(str)
               return true unless str
-              return true if LEVELS.any? {|lev| str == lev}
+              return true if valid_levels.any? {|lev| str == lev}
 
               msg = "Unknown level #{str}. Should be one of #{LEVELS}"
               raise ArgumentError, msg
@@ -87,6 +89,10 @@ module Eco
 
               value
             end
+
+            def valid_levels
+              @valid_levels ||= self.class::LEVELS | self.class::CHANNELS
+            end
           end
         end
       end

data/lib/eco/api/common/session/logger/channels.rb

@@ -0,0 +1,41 @@
+module Eco
+  module API
+    module Common
+      module Session
+        class Logger
+          module Channels
+            CHANNELS = %i[general].freeze
+
+            class << self
+              def included(base)
+                super
+                base.extend ClassMethods
+              end
+            end
+
+            module ClassMethods
+              def channels!(&def_block)
+                str = "Block with channel implementation expected. None given."
+                raise ArgumentError, str unless block_given?
+
+                channels.each do |channel|
+                  meth = channel.to_s.downcase.to_sym
+
+                  define_method(meth) do |msg = nil, &block|
+                    def_block.call(meth, msg, &block)
+                  end
+                end
+              end
+
+              private
+
+              def channels
+                self::CHANNELS
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/common/session/logger.rb

@@ -5,6 +5,15 @@ module Eco
         class Logger < Eco::Language::BasicLogger
           TIMESTAMP_PATTERN = '%Y-%m-%dT%H:%M:%S'.freeze
 
+          require_relative 'logger/channels'
+          include Channels
+
+          channels! do |channel, message = nil, &block|
+            format_proc(console: true) do |severity, datetime, msg, formatted_msg|
+              cache.add(severity, datetime, msg, formatted_msg)
+            end.call(channel, Time.now, 'prog_name', message || block.call)
+          end
+
           attr_reader :cache
 
           def initialize(file_level: ::Logger::DEBUG, log_file: nil, enviro: nil, **kargs)

data/lib/eco/api/error/handler.rb

@@ -2,17 +2,19 @@ module Eco
   module API
     class Error
       class Handler < Eco::API::UseCases::UseCase
-        @types = [:error_handler]
+        TYPES = [:error_handler].freeze
 
         def initialize(name, type: :error_handler, root:, &block)
-          super(name, type: type, root: root, &block)
+          super
         end
 
         def root=(value)
-          raise "Root should be a Eco::API::Error::Handlers object. Given: #{value}" if !value.is_a?(Eco::API::Error::Handlers)
+          msg = "Root should be a Eco::API::Error::Handlers object. "
+          msg << "Given: #{value.class}"
+          raise ArgumentError, msg unless value.is_a?(Eco::API::Error::Handlers)
+
           @root = value
         end
-
       end
     end
   end