eco-helpers 2.5.10 → 2.6.1

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

@@ -11,7 +11,8 @@ module Eco
             :usecases, :launch_jobs,
             {post_launch: [:usecases, :launch_jobs]},
             :report,
-            :end, :close
+            :end,
+            :close
           ]
 
           class << self
@@ -34,12 +35,10 @@ module Eco
                 klass.model = model[key]
               end
             end
-
           end
 
           self.model = WORKFLOW_MODEL
           attr_reader :config
-          attr_reader :name
 
           def initialize(name = nil, _parent: self, config:)
             @config   = config
@@ -55,6 +54,11 @@ module Eco
             @after    = []
           end
 
+          def name(with_path: false)
+            return @name if !with_path || root?
+            [@_parent.name(with_path: true), @name].compact.join('.')
+          end
+
           # Has this stage run yet?
           # @note it does **not** include _sub-stages_ that run `before`
           # @return [Boolean] `true` if it has run, `false` otherwise
@@ -80,22 +84,26 @@ module Eco
           end
 
           # Used in **configuration** time **to configure** the _workflow_ of the target (sub)stage `key`
-          # @note if a `block` is provided it will `yield` the target stage immediately
+          # @note
+          #   1. if a `block` is provided it will `yield` the target stage immediately
+          #   2. a `block` is only required when `key` has not been specified.
           # @param key [Symbol, nil] cases:
           #   - if `key` is not provided, it targets the _current stage_
           #   - if `key` is provided, it targets the specific _sub-stage_
           # @yield [stage_workflow] further _workflow_ configuration `for` the target stage `key`
           # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
-          # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
-          def for(key = nil)
-            raise "A block should be given." unless block_given?
-            if !key
-              yield(self)
-            else
-              stage(key).for(&Proc.new)
+          # @return [Eco::API::Session::Config::Workflow]
+          #   1. if block is provided provided, it returns the **current stage** object (to ease chainig).
+          #   2. if block is not provided, it returns the **stage** referred by `key`
+          def for(key = nil, &block)
+            raise ArgumentError, "With no 'key', a block should be given." unless key || block_given?
+            self.tap do
+              next yield(self)            unless key
+              next stage(key).for(&block) if block_given?
+              return stage(key)
             end
-            self
           end
+          alias_method :with, :for
 
           # Used in **configuration** time **to define** the **behaviour**  the target (sub)stage `key`
           # @note if a `block` is provided it will **not** `yield` the target stage immediately, but when the _workflow_ reaches the stage
@@ -108,7 +116,7 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] the `io` input/output object carried througout all the _workflow_
           # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def on(key = nil, &block)
-            raise "A block should be given." unless block
+            raise ArgumentError, "A block should be given." unless block_given?
             if !key
               @on = block
             else
@@ -128,7 +136,10 @@ module Eco
             @rescue = block
             self
           end
+          # Prevent reserved word clash on DSL
+          alias_method :exception, :rescue
 
+          # Called on `SystemExit` exception
           def exit_handle(&block)
             return @exit_handle unless block
             @exit_handle = block
@@ -148,7 +159,7 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] `io` the input/output object carried througout all the _workflow_
           # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def before(key = nil, &block)
-            raise "A block should be given." unless block
+            raise ArgumentError, "A block should be given." unless block_given?
             if !key
               @before.push(block)
             else
@@ -170,7 +181,7 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] `io` the input/output object carried througout all the _workflow_
           # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def after(key = nil, &block)
-            raise "A block should be given." unless block
+            raise ArgumentError, "A block should be given." unless block_given?
             if !key
               @after.push(block)
             else
@@ -191,7 +202,8 @@ module Eco
           #   - it will **not** run the `callback` for `on` defined during the configuration time
           #   - it will rather `yield` the target stage after all the `before` _callbacks_ have been run
           #   - aside of this, the rest will be the same as when the _block_ is provided (see previous note)
-          # @raise [ArgumentError] if the object returned by `before` and `after` callbacks is not an `Eco::API::UseCases::BaseIO`.
+          # @note [if the object returned by `before`, `after` and `run` callbacks is not an `Eco::API::UseCases::BaseIO`,
+          #   the original `io` object will be returned instead.
           # @param key [Symbol, nil] cases:
           #   - if `key` is not provided, it targets the _current stage_
           #   - if `key` is provided, it targets the specific _sub-stage_
@@ -203,62 +215,87 @@ module Eco
           # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def run(key = nil, io:, &block)
             raise "Missing BaseIO object" unless io.is_a?(Eco::API::UseCases::BaseIO)
-            begin
-              if key
-                io = stage(key).run(io: io, &block)
-              elsif pending?
-                @before.each do |c|
-                  io = c.call(self, io).tap do |i_o|
-                    unless i_o.is_a?(Eco::API::UseCases::BaseIO)
-                      msg  = "Workflow callaback before('#{name}') should return Eco::API::UseCases::BaseIO object."
-                      msg += " Given #{i_o.class}"
-                      msg += " • Callback source location: '#{c.source_location}'"
-                      raise ArgumentError.new(msg)
-                    end
-                  end
-                end
 
-                unless skip?
-                  io.session.logger.debug("(Workflow: #{path}) running now")
-                  if block
-                    io = block.call(self, io)
-                  else
-                    existing_stages.each {|stg| io = stg.run(io: io)}
+            if key
+              io = io_result(io: io) do
+                stage(key).run(io: io, &block)
+              end
+            elsif pending?
+              @before.each do |c|
+                io = io_result(io: io) do
+                  io.evaluate(self, io, &c)
+                end
+              end
 
-                    unless ready?
-                      msg = "(Workflow: #{path}) 'on' callback is not defined, nor block given"
-                      io.session.logger.debug(msg)
+              unless skip?
+                io.session.logger.debug("(Workflow: #{path}) running now")
+                if block
+                  io = io_result(io: io) do
+                    io.evaluate(self, io, &block)
+                  end
+                else
+                  existing_stages.each do |stg|
+                    io = io_result(io: io) do
+                      stg.run(io: io)
                     end
-                    io = @on.call(self, io) if ready?
                   end
-                  @pending = false
-                end
 
-                @after.each do |c|
-                  io = c.call(self, io).tap do |i_o|
-                    unless i_o.is_a?(Eco::API::UseCases::BaseIO)
-                      msg  = "Workflow callaback after('#{name}') should return Eco::API::UseCases::BaseIO object."
-                      msg += " Given #{i_o.class}"
-                      msg += " • Callback source location: '#{c.source_location}'"
-                      raise ArgumentError.new(msg)
-                    end
+                  unless ready?
+                    msg = "(Workflow: #{path}) 'on' callback is not defined, nor block given"
+                    io.session.logger.debug(msg)
                   end
+                  io = io_result(io: io) do
+                    io.evaluate(self, io, &@on)
+                  end
+                end
+                @pending = false
+              end
+
+              @after.each do |c|
+                io = io_result(io: io) do
+                  io.evaluate(self, io, &c)
                 end
               end
-            rescue SystemExit => e
-              self.exit_handle.call(e, io) if self.exit_handle
-              exit e.status
-            rescue Interrupt => i
-              raise
-            rescue Exception => e
-              self.rescue.call(e, io) if self.rescue
-              raise
             end
             io
+          rescue SystemExit => e
+            io = io_result(io: io) do
+              io.evaluate(e, io, &self.exit_handle)
+            end
+            exit e.status
+          rescue Interrupt => i
+            raise
+          rescue Exception => e
+            # raise unless self.rescue
+            io = io_result(io: io) do
+              io.evaluate(e, io, &self.rescue)
+            end
+            raise
+          ensure
+            @pending = false
           end
 
           protected
 
+          def root?
+            @_parent == self
+          end
+
+          # It ensures an `Eco::API::UseCases::BaseIO` is returned
+          # @note it always brings the IO to be a `BaseIO`.
+          #   As the `output` and the type is captured, it just cleans usecase related
+          #   logic from the object.
+          # @raise ArgumentError if `klass` isn't child of `Eco::API::UseCases::BaseIO`
+          # @return [Eco::API::UseCases::BaseIO] the `io` input/output object carried througout the _workflow_
+          def io_result(io:, klass: Eco::API::UseCases::BaseIO)
+            msg = "Expecting class to be child of Eco::API::UseCases::BaseIO. Given: #{klass}"
+            raise ErrorArgument, msg unless klass <= Eco::API::UseCases::BaseIO
+
+            result = yield
+            io = result if result.is_a?(klass)
+            io.instance_of?(klass) ? io : io.base
+          end
+
           def path
             return name if root?
             "#{@_parent.path}:#{name}"

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

@@ -257,6 +257,13 @@ module Eco
           tagtree_config.live_tree(id: id, enviro: enviro, **kargs, &block)
         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(**kargs, &block)
+          tagtree_config.live_trees(**kargs, &block)
+        end
+
         # @return [Eco::API::Organization::PolicyGroups]
         def policy_groups
           return @policy_groups if instance_variable_defined?(:@policy_groups)
@@ -360,10 +367,10 @@ module Eco
         end
 
         # @return [Eco::API::Session::Batch::Policies]
-        def batch_policies
+        def batch_policies(&block)
           @batch_policies = self["batch_policies"] ||= Eco::API::Session::Batch::Policies.new("batch_policy")
           if block_given?
-            yield(@batch_policies)
+            @batch_policies.evaluate(@batch_policies, &block)
             self
           else
             @batch_policies

data/lib/eco/api/session.rb

@@ -39,16 +39,31 @@ module Eco
         config.login_providers
       end
 
+      # @param live [Boolean] states preference of `live` tree if available over file.
+      # @param merge [Boolean] when in `live` mode, if mulitple trees, merge into one.
       # @see Eco::API::Session::Config#tagtree
-      def tagtree
-        config.tagtree(enviro: enviro)
+      # @see Eco::API::Session#live_trees
+      # @return [Eco::API::Organization::TagTree]
+      def tagtree(live: false, merge: false, include_archived: false, **kargs, &block)
+        if live && api?(version: :graphql)
+          return live_tree(include_archived: include_archived, **kargs, &block) unless merge
+          live_trees(include_archived: include_archived, **kargs, &block).inject(&:merge)
+        else
+          config.tagtree(enviro: enviro)
+        end
       end
 
       # @see Eco::API::Session::Config#live_tree
+      # @return [Eco::API::Organization::TagTree]
       def live_tree(id: nil, include_archived: false, **kargs, &block)
         config.live_tree(id: id, include_archived: include_archived, enviro: enviro, **kargs, &block)
       end
 
+      # @see Eco::API::Session::Config#live_tree
+      def live_trees(include_archived: false, **kargs, &block)
+        config.live_trees(include_archived: include_archived, **kargs, &block)
+      end
+
       # @see Eco::API::Session::Config#schemas
       def schemas
         config.schemas

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

@@ -5,6 +5,9 @@ module Eco
       class BaseIO < BaseCase
         @types  = BaseCase.types
 
+        include Eco::Language::Methods::DslAble
+        include Eco::Language::AuxiliarLogger
+
         class MissingParameter < StandardError
           attr_reader :type, :required, :given
 
@@ -37,14 +40,14 @@ module Eco
         # @param people [Eco::API::Organization::People] people object.
         # @param session [Eco::API:Session]
         # @param options [Hash] hash with symbol keys (i.e. behaviour modifiers, cli trackers, filters, etc.)
-        def initialize(type: nil, input: nil, people: nil, session:, options: {}, validate: true)
-          @output      = nil
+        def initialize(type: nil, input: nil, people: nil, session:, options: {}, output: nil, validate: true)
           self.type    = type if type
 
           if self.type && validate
             validate_args(input: input, people: people, session: session, options: options)
           end
 
+          @output      = output
           @input       = input
           @people      = people
           @session     = session
@@ -57,10 +60,13 @@ module Eco
           @type = value
         end
 
-        # Helper to obtain an `BaseIO` objcect from any child class.
+        # Helper to obtain an `BaseIO` object from any child class.
         # @return [Eco::API::UseCases::BaseIO]
         def base
-          kargs = params(keyed: true).merge(type: self.type).slice(:type, :input, :people, :session, :options)
+          kargs = params(keyed: true).merge({
+            type:   self.type,
+            output: self.output,
+          }).slice(:type, :input, :people, :session, :options, :output) # :validate <- ?
           Eco::API::UseCases::BaseIO.new(**kargs)
         end
 
@@ -73,6 +79,7 @@ module Eco
             people:   self.people,
             session:  self.session,
             options:  self.options,
+            output:   self.output,
             validate: true
           }
           self.class.new(**default.merge(kargs))
@@ -87,6 +94,45 @@ module Eco
           keyed ? kargs : kargs.values
         end
 
+        # Shortcut to run a usecase passing this `io` as parameter
+        # @note
+        #   1. It swaps `output` to `input` or `people` depending on `self.type`
+        #   2. does this, **before** the target `case_name` launch and **after
+        # @return [Eco::API::UseCases::BaseIO]
+        def process_case(case_name, case_type, **params)
+          session.process_case(case_name, io: chained, type: case_type, **params).chained
+        end
+
+        # Does the switch from output to result in a new IO object.
+        # @note if there isn't `output` it doesn't do the switch,
+        #   provided that it preserves the target parameter
+        #   (otherise it would blank it)
+        # @return [Eco::API::UseCases::BaseIO]
+        def chained(as: self.type)
+          base.tap do |io_base|
+            next unless io_base.output
+            case as
+            when :import
+              io_base.output_be_input!
+            when :filter
+              io_base.output_be_people!
+            when :transform, :sync, :export, :error_handler, :other
+            end
+          end
+        end
+
+        protected
+
+        def output_be_input!
+          @input, @output = output, nil
+          input
+        end
+
+        def output_be_people!
+          @people, @output = output, nil
+          people
+        end
+
         private
 
         def validate_args(input:, people:, session:, options:)

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

@@ -0,0 +1,94 @@
+module Eco
+  module API
+    class UseCases
+      class Cli
+        module DSL
+          # Links the usecase to the Cli via `arg_case`
+          def apply!(arg_case = cli_name)
+            #puts "DEFINING CLI for '#{arg_case}' via #{self}"
+            if applied?(arg_case)
+              puts  "Warning: (#{self}) Tried to call again cli.apply! on '#{arg_case}'"
+              return self
+            end
+            cli_config_case(arg_case)
+            apply_options(arg_case)
+            applied!(arg_case)
+            self
+          end
+
+          def applied
+            @applied ||= {}
+          end
+
+          def applied?(arg_case)
+            applied[arg_case] || false
+          end
+
+          def applied!(arg_case)
+            applied[arg_case] = true
+          end
+
+          attr_writer :usecase
+          # Unless specified, assume Cli class hangs from its case namespace
+          def usecase
+            raise "#{self} is to use to extend a class" unless self.is_a?(Class)
+            @usecase ||= Kernel.const_get(self.to_s.split('::')[0..-2].join('::'))
+          end
+
+          def description(value = nil)
+            @description = (value.nil? ? @description : value)
+          end
+          alias_method :desc, :description
+
+          def type
+            usecase.type
+          end
+
+          def name
+            usecase.name
+          end
+
+          # It defaults to the use case preceded by dash
+          def cli_name(arg_name = nil)
+            @cli_name = (arg_name.nil? ? @cli_name : arg_name).yield_self do |value|
+              value = "-#{name}" if value.nil?
+              value
+            end
+          end
+
+          def callback(&block)
+            return @callback unless block_given?
+            @callback = block
+          end
+
+          def options
+            @options ||= {}
+          end
+
+          def add_option(arg, desc = nil, &block)
+            self.tap do
+              "Overriding option '#{arg}' on case '#{name}'" if options.key?(arg)
+              @options[arg] = Eco::API::UseCases::Cli::Option.new(arg, desc, &block)
+            end
+          end
+
+          private
+
+          def apply_options(arg_case)
+            options.each do |_key, option|
+              option.link_case(cli_config_case(arg_case))
+            end
+          end
+
+          def cli_config_case(arg_case = nil)
+            @cli_config_case ||= usecases.add(arg_case, type, desc, case_name: name, &callback)
+          end
+
+          def usecases(&block)
+            ::ASSETS.cli.config.usecases(&block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# Class to delay the case options configuration (declaration vs configuration)
+class Eco::API::UseCases::Cli
+  class Option
+    attr_accessor :name, :desc, :callback
+
+    def initialize(name, desc, &block)
+      @name, @desc, @callback = name, desc, block
+    end
+
+    def dup(name: self.name, desc: self.desc, &block)
+      self.class.new(name, desc, &(block || callback))
+    end
+
+    def link_case(cli_config_case)
+      raise ArgumentError, "cli_config_case must have an 'add_option' method. Given: #{cli_config_case.class}" unless cli_config_case.respond_to?(:add_option)
+      cli_config_case.add_option(name, desc, &callback)
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# Class to integrate with the Cli a use case
+module Eco
+  module API
+    class UseCases
+      class Cli
+        require_relative 'cli/dsl'
+        extend DSL
+      end
+    end
+  end
+end
+
+require_relative 'cli/option'

data/lib/eco/api/usecases/default/locations/cli/tagtree_extract_cli.rb

@@ -0,0 +1,29 @@
+class Eco::API::UseCases::Default::Locations::TagtreeExtract
+  # Class to define the CLI integration of a usecase anywhere it suits.
+  class Cli < Eco::API::UseCases::Cli
+    desc "Exports the tagtree in a specific format"
+
+    add_option("-include-archived", "Whether the archived nodes should be included") do |options|
+      options.deep_merge!(output: {include: {archived: true}})
+    end
+
+    add_option("-format", "Kind of extract (list | json | nodes | csv_tree | excel_tree | excel_nodes )") do |options|
+      format = SCR.get_arg("-format", with_param: true)
+      options.deep_merge!(output: {format: format})
+    end
+
+    add_option("-node-attrs", "Attributes to be dumped (i.e. name|id ). Default: id") do |options|
+      attrs = SCR.get_arg("-node-attrs", with_param: true)
+      options.deep_merge!(output: {attrs: attrs.split('|').map(&:to_sym)})
+    end
+
+    add_option("-with-ancestors", "Include ancestors in tree csv/excel_tree") do |options|
+      options.deep_merge!(output: {include: {ancestors: true}})
+    end
+
+    add_option("-indent", "Custom indentation (i.e. \"++\")") do |options|
+      indent = SCR.get_arg("-indent", with_param: true) || ""
+      options.deep_merge!(output: {indent: indent})
+    end
+  end
+end

data/lib/eco/api/usecases/{default_cases → default/locations}/codes_to_tags_case.rb

@@ -1,4 +1,4 @@
-class Eco::API::UseCases::DefaultCases::CodesToTagsCase < Eco::API::Common::Loaders::UseCase
+class Eco::API::UseCases::Default::Locations::CodesToTagsCase < Eco::API::Common::Loaders::UseCase
   name "codes-to-tags-from"
   type :other
 

data/lib/eco/api/usecases/{default_cases → default/locations}/create_tag_paths_case.rb

@@ -1,4 +1,4 @@
-class Eco::API::UseCases::DefaultCases::TagPaths < Eco::API::Common::Loaders::UseCase
+class Eco::API::UseCases::Default::Locations::TagPaths < Eco::API::Common::Loaders::UseCase
   name "create-tag-paths"
   type :other
 

data/lib/eco/api/usecases/{default_cases → default/locations}/csv_to_tree_case.rb

@@ -1,4 +1,4 @@
-class Eco::API::UseCases::DefaultCases::CsvToTree < Eco::API::Common::Loaders::UseCase
+class Eco::API::UseCases::Default::Locations::CsvToTree < Eco::API::Common::Loaders::UseCase
   name "csv-to-tree"
   type :other