eco-helpers 3.0.37 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 949959ec22add3fc3f7e78ed155c66a95b8c1d6757eb90ca40bf74918f379170
-  data.tar.gz: 80be5ed4e76e97460857f6c3a9f5afe23b735519e9f4fb2d1822817f84b794d3
+  metadata.gz: 4b81231f7cbb64973d578ac889c8510db4f5db5b9458468c34a56144916d731d
+  data.tar.gz: eb56be6c8c704c7b4b85ac2acdf0fd567ab6322e1257e6ac1442076eebb0aa77
 SHA512:
-  metadata.gz: 730da2f221461b9700eafaef73985e603b0edb0fd2bc89a532c6640d07200462e5fde05048c176dc5caace42114639d4101daf71fbd197356610c86423b45812
-  data.tar.gz: 26eb938cb1967430ee26e8eb0b82a7a1ed9b777ae38087ec0e47ec0b90af0d99a5cecf5ee8b36ccd9353a8ae1f408d342d565b6b1ab645d3e40141f8dae4e458
+  metadata.gz: be7da006d5532c0c66f7130b44da3d0058927f73f9b861dd833fc79c0229f2a710be49d40e0ff4345048c2f6147702f158ec8b5994e8334f8663ea0c41f7d374
+  data.tar.gz: 0aa4345fbaef61362f428cb70d6a2a4719755fba8e9bf2f6436eeddc7eeacf872f79bbbf4e459ac8d7df64cbad129ff2e7c58f4c1d572ecfa4c0340a14825436

data/.rubocop.yml

@@ -33,6 +33,7 @@ Style/BlockDelimiters:
 Style/HashSyntax:
   EnforcedShorthandSyntax: either
   EnforcedStyle: no_mixed_keys
+
 Style/ArgumentsForwarding:
   UseAnonymousForwarding: false
 Style/ClassAndModuleChildren:

data/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.0.37] - 2025-04-xx
+## [3.1.2] - 2025-04-xx
 
 ### Added
 
@@ -10,6 +10,121 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+## [3.1.1] - 2025-04-30
+
+This release mostly aims a **refactoring** on _**Files Handling**_.
+
+- There are different helper libraries in this regard. The client scripts, end up re-defining its own input/output file handling.
+- While it is challenging to keep a unique access point that shows up to be functional to all the client scrits/usecases, some tidy up on time should be attempted with the aim of gathering some functions that can further simply code on the client scrits, while keeping internal consistency in the gem itself.
+
+It also sets the basics for having **multiple workflows** to choose among. This aims to have different workflows (depending the case we deal with).
+
+This release also aims to be able to run automated tests against test environment. Where notifications are sent.
+
+### Added
+
+- **Option** `-notify` (to force email to be sent)
+  - This skips safeguard of `dry-run` and non remote runs (it notifies anyway).
+- **`Eco::Language::Klass`**:
+  - **Added** `Eco::Language::Klass::Uid` generator.
+  - **Added** `Eco::Language::Klass::Const` helpers (`redef_without_warning`).
+- **Added** `Eco::API::UseCases::Lib::Files::InputFile` (for **standardization**)
+  - This aims to address proliferation of cases that try to define it.
+  - And unify code under one single lib.
+- **Added** `Eco::API::UseCases::Lib::People::Base`
+  - Some cases need to lookup people.
+- `Eco::Data::Files::Folder`:
+  - **Added** method `#ensure_file_path!`
+  - **Added** method `#archive_file`
+  - **Added** function `#clear_folder`
+    - **Safe-guard**: files matching `PRESERVED_FILES` regexp patterns will be excluded. For example, it could be that the folder was the root `.`, or it could be a gitignored folder with scripts.
+  - for `#folder_files`:
+    - **Added** named argument `newer_than`
+    - **Added** `newer_than` argument to `#clear_folder` and `#csv_files`
+    - It **logs** whether it found files and which ones (these logs are with the **relative** path to the working folder).
+- `Eco::Data::Files::RelativePath`:
+  - To mask the absolute path of the file, and make it relative to the working directory.
+- **Added** `Eco::Language::Methods::AccessModifier`
+  - To help in moving private methods to be public in some service classes that reuse modules where methods are defined as private.
+- `Eco::API::Session::Config#locations_mapper`
+  - **Added**: ability to specify case sensitive & order of column mappings.
+- `Eco::Language::Klass::Resolver#resolve_class`
+  - **Added** named argument `source_class:`, provided that look ups are performed in that space.
+- `Eco::Language::Klass::Const`
+  - **Added** `if_const`
+- `Eco::API::Session::Config#locations_mapper`
+  - **Added** argument to specify the `maps_file`
+  - **Improved** provided that it is **caching** _based on arguments_
+- **Added** `Eco::Data::Mapper#empty?`
+- **Added** `Eco::Data::CountTrace`
+  - Helpful to track how many times a value has been found.
+- **Added** `Eco::API::UseCases::Lib::Locations` with module helpers:
+  - `Base` (i.e. `#tagtree`)
+  - `Mapping` (i.e. `#to_location` / `#to_tag`)
+- `Eco::API::Common::Loaders::Config::Block` (moved from `Loaders::Config`)
+  - **Added** methods:
+    - `#config_apply!`
+    - `#config_copy`
+- `Eco::Language::Models::Workflow`
+  - **moved** most logic from `Session::Config::Workflow`, provided we can build different workflows.
+  - **added** workflow builder: `Eco::API::UseCases::Workflow`
+  - **simplified** `Eco::API::Session::Config::Workflow` via **inheritance**.
+- `Eco::API::Common::Session::Mailer::ProviderBase`
+  - **Fetch** `ENV` vars `MAILER_FROM` and `MAILER_TO`
+
+### Changed
+
+- **Changed** `Eco::API::Session::Batch::Launcher#launch_batch`
+  - It **won't** use the `batch/job` endpoint, unless `MIN_JOB_SIZE` is reached.
+- **Refactored** `Eco::API::UseCases::Service::Sftp`
+  - Making public methods of `Eco::API::UseCases::Lib::Files::Sftp` by rather using `Eco::Language::Methods::AccessModifier`
+- `Eco::API::UseCases::Lib::Files::Sftp` method `sftp_archive_file!`
+  - **Changed** named argument `folder:` to `subfolder:`
+- **Moved** class **auto loader** to **Language** namespace
+- `Eco::API:Common::Loaders::Base`
+  - Redefined `#options` as per `Loaders::Parser` definition
+- **Decoupled** `Eco::Data::Files::Helpers` into:
+  - **`Eco::Data::Files::Folder`**
+    - `#folder_files`: argument `pattern` that comes as a `Symbol` is now interpreted as the file **extension** that should be matched in `folder`.
+  - **`Eco::Data::Files::Content`** (instance methods)
+  - **`Eco::Data::Files::Timestamp`**
+    - **Renamed** constant `DEFAULT_TIMESTAMP_PATTERN` to `DEFAULT_TIMESTAMP`
+  - **Made Explicit** _`included`_ logic on `Data::Files` itself
+    - **Removed** `Files::Helpers` module completely.
+  - _Files helpers_ **changes**
+    - **Removed** `#file_exists?` and `#dir_exists?` in favor of **native** `ruby`.
+    - **Removed** (unused methods)`#file_basename`, `#file_fullpath` and `#file_name` in favor of **native** `ruby`.
+    - **Moved** `#script_subfolder` to be class method for `Files::Directory`
+    - **Changed** method name `#has_bom?` to `bom?` (`Eco::Data::Files::Encoding`)
+    - **Removed** `Eco::Data::Files::Directory.create` in favour of **native** `ruby`
+      - This adds requirement onto **`fileutils`** (for `FileUtils.mkdir_p`)
+    - **Changed** `Eco::Data::Files::Directory#create` to rather use **native** `ruby` when ensuring folder to exist. It now **returns** `Boolean` instead.
+    - **Renamed** `exists?` to `Eco::Data::Files::Directory#exist?`
+- **Refactored** `Eco::API::UseCases::Lib::Files::FilePattern`
+  - renamed and decoupled some functions to better reflect their role.
+  - regex patterns comming from consts that are strings, would get converted to `Regexp`
+- **Moved** class **ClassHierarchy** to `Eco::Language::Models` namespace
+- **Removed** class **`ClassHelpers`**
+  - **Moved** to  `Eco::Language::Klass::HelpersBuilt`
+- `Eco::Language::Klass::Naming#to_constant`: included case where a full namespace is provided
+- `Eco::Language::Class::Builder`
+  - **Changed** parameter name from `parent_space` to `namespace`
+- `Eco::API::Session::Config#locations_mapper`
+  - When no file specified, it will return `nil`
+- `Eco::API::Common::Loaders::Config`
+  - **Decoupled** `Block` and **added** parameter `section` to be able to have multiple configurations.
+  - `@config_block` is now **inheritable**
+- `Eco::Language::Klass::WhenInherited`
+  - Allows to define multiple blocks to be called on inheritance.
+  - It now passes the `subclass` to the called block.
+- `Eco::CliDefault::Workflow` split/decoupled into module workflow configurations (one per stage).
+
+### Fixed
+
+- `Eco::API::UseCases::Lib::Base::Env`
+  - Call to `super` shouldn't carry the arguments for `session` and `options`
+- `one_off?` to be cli based
+
 ## [3.0.37] - 2025-04-15
 
 ### Fixed

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

@@ -3,7 +3,7 @@ module Eco
     module Common
       module Loaders
         class Base
-          extend Eco::API::Common::ClassHelpers
+          extend Eco::Language::Klass::HelpersBuilt
           include Eco::Language::AuxiliarLogger
 
           class << self
@@ -54,7 +54,7 @@ module Eco
           end
 
           def options
-            @options ||= {}
+            @options ||= ASSETS.cli.options
           end
 
           def config

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

@@ -28,6 +28,8 @@ module Eco
             end
           end
 
+          # Instance Methods
+
           def name
             self.class.name
           end

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

@@ -0,0 +1,78 @@
+class Eco::API::Common::Loaders::Config
+  module Block
+    class << self
+      def included(base)
+        super
+
+        base.extend ClassMethods
+        base.extend Eco::Language::Klass::InheritableClassVars
+
+        base.inheritable_class_vars :config_block
+      end
+    end
+
+    module ClassMethods
+      # To create samples of configurations
+      def config_block(section = nil, *keys, &block)
+        section       ||= :general
+        key             = [section, *keys]
+        @config_block ||= {}
+
+        return @config_block[key] unless block_given?
+
+        unless @config_block[key].nil?
+          msg = "Reconfiguring config_block (#{key}) on #{self}"
+          session.log(:warn) { msg }
+        end
+
+        @config_block[key] = block
+      end
+
+      # Applies the configuration to the target `on`.
+      def config_apply!(*key, on: self, all: false) # rubocop:disable Naming/MethodParameterName
+        if all
+          @config_block ||= {}
+
+          @config_block.each_key do |k|
+            config_apply!(*k, on: on)
+          end
+        else
+          on.instance_exec(&config_block(*key))
+        end
+
+        self
+      rescue LocalJumpError => err
+        puts "Missing config block for key '#{key}': #{err}"
+        raise
+      end
+
+      def config_copy(*key, to:, all: false)
+        @config_block ||= {}
+
+        if all
+          @config_block.dup.each do |keys, block|
+            to.config_block(*keys, &block)
+          end
+        else
+          to.config_block(*key, &config_block(*key))
+        end
+
+        self
+      end
+
+      private
+
+      def config(...)
+        ASSETS.config(...)
+      end
+
+      def cli
+        ASSETS.cli
+      end
+
+      def active_enviro
+        config.active_enviro
+      end
+    end
+  end
+end

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

@@ -1,9 +1,14 @@
 class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::Workflow
-  ORG = 'your organization'.freeze
+  ORG         = 'your organization'.freeze
   TRACE_COUNT = 3
+  ALT_TO      = %w[
+    oscar@ecoportal.co.nz
+    travis@ecoportal.co.nz
+  ].freeze
 
   inheritable_class_vars :config_block
 
+  # @todo different emailing, depending on case type and/or preference
   config_block do
     #puts "running from class #{self}"
     exception do |err, io|
@@ -12,11 +17,10 @@ class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::W
       workflow.run(:close, io: io)
     end
 
-    after(:close) do |_wf, io|
-      next if     options.dig(:workflow, :no_email)
-      next unless session.mailer?
-      next if     session.config.dry_run?
-      next unless session.config.run_mode_remote?
+    after(:close) do
+      env_based_mailer!(io)
+
+      next unless notify?(io)
 
       # temporary contingency: maybe_error_or_tree_updates?
       next unless some_update_case?(io) || maybe_error_pages_or_tree_updates?(io)
@@ -25,7 +29,7 @@ class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::W
       subject = "#{subject} & Errors"     if session.job_groups.errors?
       subject = "#{subject} - Exception!" if error?
 
-      body    = general_messages(io) || ''
+      body    = general_messages || ''
       body   << "\n#{session.summary}" unless session.job_groups.empty? && error?
       body   << "\n#{errors_n_warnings(io)}"
 
@@ -40,6 +44,34 @@ class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::W
       self::ORG
     end
 
+    def notify?(io)
+      return false if     io.options.dig(:workflow, :no_email)
+      return false unless io.session.mailer?
+      return true  if     io.options.dig(:workflow, :notify)
+      return false if     io.session.config.dry_run?
+      return false if     io.session.config.run_mode_remote?
+
+      true
+    end
+
+    def env_based_mailer!(io)
+      return if live?(io) || !io.session.config.dry_run?
+
+      # redirect mailing to eP Staff when not in `live` env.
+      # or when in `dry-run`
+      io.session.config.mailer.to = alternative_emails
+    end
+
+    def live?(io)
+      host(io).downcase.start_with?('live.')
+    end
+
+    def host(io)
+      io.session.api.client.host
+    end
+
+    # @todo: add whether it is a dry-run and if we are on certain enviro.
+    #   - The target env could probably be added as a :general message.
     def base_subject
       "#{org_name} (#{active_enviro_desc}) at #{Time.now.iso8601}"
     end

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

@@ -1,33 +1,10 @@
+require_relative 'config/block'
+
 class Eco::API::Common::Loaders::Config
+  include Block
   include Eco::Language::Delegation::DelegatingMissingOnClass
 
   delegating_missing_on_class_to :config
-
-  class << self
-    # To create samples of configurations
-    def config_block(&block)
-      return @config_block unless block_given?
-
-      unless @config_block.nil?
-        msg = "Reconfiguring config_block on #{self}"
-        session.log(:warn) { msg }
-      end
-
-      @config_block = block
-    end
-
-    def config(...)
-      ASSETS.config(...)
-    end
-
-    def cli
-      ASSETS.cli
-    end
-
-    def active_enviro
-      config.active_enviro
-    end
-  end
 end
 
 require_relative 'config/cli'

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

@@ -18,6 +18,8 @@ module Eco
 
           inheritable_class_vars :error
 
+          # Instance Methods
+
           def initialize(handlers) # rubocop:disable Lint/MissingSuper
             msg = "Expected Eco::API::Policies. Given #{handlers.class}"
             raise msg unless handlers.is_a?(Eco::API::Error::Handlers)

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

@@ -18,6 +18,7 @@ module Eco
 
               match = input_attrs & attrs
               miss  = attrs - match
+
               return []    if miss.empty?
               return attrs if match.empty?
               return miss  if type == :all
@@ -154,10 +155,6 @@ module Eco
 
           private
 
-          def options
-            ASSETS.cli.options
-          end
-
           def _define_parser(attr_parser)
             if (active_when = self.class.active_when)
               attr_parser.def_parser(

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

@@ -40,7 +40,9 @@ module Eco
 
             def candidates_summary
               lines = ["The following entries have the same '#{property}':"]
-              lines.concat(identify_candidates(with_index: true)).join("\n  ")
+              lines.concat(
+                identify_candidates(with_index: true)
+              ).join("\n  ")
             end
           end
 
@@ -129,7 +131,13 @@ module Eco
             id          = attr_value(object, 'id')
             external_id = attr_value(object, 'external_id')
             email       = attr_value(object, 'email')
-            entry(id: id, external_id: external_id, email: email, strict: strict)
+
+            entry(
+              id:          id,
+              external_id: external_id,
+              email:       email,
+              strict:      strict
+            )
           end
           # @!endgroup
 
@@ -150,6 +158,7 @@ module Eco
             discarded = list.map do |person|
               find(person)
             end.compact
+
             newFrom to_a - discarded
           end
 
@@ -159,11 +168,14 @@ module Eco
           # @param parsing_phase [Symbol] data as per specific parsing stage.
           def export(filename, parsing_phase: :internal)
             header = each_with_object([]) do |entry, hds|
-              hds.push(*entry.entry(parsing_phase).keys).uniq!
+              hds.push(
+                *entry.entry(parsing_phase).keys
+              ).uniq!
             end
 
             CSV.open(filename, 'w') do |csv|
               csv << header
+
               each do |entry|
                 csv << entry.entry(parsing_phase).values_at(*header)
               end
@@ -194,14 +206,18 @@ module Eco
           private
 
           def entry_by_email(email, prevent_multiple_match: false)
-            return nil unless email
+            return unless email
 
             candidates = @by_email[email] || []
             return candidates.first if candidates.length == 1
 
             if prevent_multiple_match && !candidates.empty?
               msg = 'Multiple search results match the criteria.'
-              raise MultipleSearchResults.new(msg, candidates: candidates, property: 'email')
+              raise MultipleSearchResults.new(
+                msg,
+                candidates: candidates,
+                property:   'email'
+              )
             end
 
             @by_external_id[email]&.first
@@ -209,10 +225,11 @@ module Eco
 
           def init_caches
             return if @caches_init
+
             @by_id          = no_nil_key(to_h)
             @by_external_id = no_nil_key(to_h('external_id'))
             @by_email       = no_nil_key(to_h('email'))
-            @caches_init = true
+            @caches_init    = true
           end
 
           def no_nil_key(hash)

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

@@ -250,7 +250,7 @@ module Eco
             fatal msg unless @person_parser.defined?(format)
 
             run = true
-            if self.class.file_exists?(file)
+            if File.exist?(file)
               prompt_user(
                 'Do you want to overwrite it? (Y/n):',
                 explanation: "The file '#{file}' already exists.",