bolt 2.44.0 → 3.4.0

data/lib/bolt/pal.rb

@@ -215,6 +215,7 @@ module Bolt
     def with_bolt_executor(executor, inventory, pdb_client = nil, applicator = nil, &block)
       setup
       opts = {
+        bolt_project: @project,
         bolt_executor: executor,
         bolt_inventory: inventory,
         bolt_pdb_client: pdb_client,
@@ -384,7 +385,7 @@ module Bolt
           plan_cache[plan_name] = info
         end
 
-        list << [plan_name] unless info['private']
+        list << [plan_name, info['description']] unless info['private']
       end
 
       File.write(@project.plan_cache_file, plan_cache.to_json) if updated
@@ -445,11 +446,11 @@ module Bolt
             params[name] = { 'type' => param.types.first }
             params[name]['sensitive'] = param.types.first =~ /\ASensitive(\[.*\])?\z/ ? true : false
             params[name]['default_value'] = defaults[name] if defaults.key?(name)
-            params[name]['description'] = param.text unless param.text.empty?
+            params[name]['description'] = param.text if param.text && !param.text.empty?
           else
             Bolt::Logger.warn(
               "missing_plan_parameter",
-              "The documented parameter '#{name}' does not exist in plan signature"
+              "The documented parameter '#{name}' does not exist in signature for plan '#{plan.name}'"
             )
           end
         end
@@ -520,10 +521,30 @@ module Bolt
       end
     end
 
-    def convert_plan(plan_path)
+    def convert_plan(plan)
+      path = File.expand_path(plan)
+
+      # If the path doesn't exist, check if it's a plan name
+      unless File.exist?(path)
+        in_bolt_compiler do |compiler|
+          sig = compiler.plan_signature(plan)
+
+          # If the plan was loaded, look for it on the module loader
+          # There has to be an easier way to do this...
+          if sig
+            type = compiler.list_plans.find { |p| p.name == plan }
+            path = sig.instance_variable_get(:@plan_func)
+                      .loader
+                      .find(type)
+                      .origin
+                      .first
+          end
+        end
+      end
+
       Puppet[:tasks] = true
       transpiler = YamlPlan::Transpiler.new
-      transpiler.transpile(plan_path)
+      transpiler.transpile(path)
     end
 
     # Returns a mapping of all modules available to the Bolt compiler

data/lib/bolt/pal/yaml_plan.rb

@@ -73,8 +73,7 @@ module Bolt
       def duplicate_check(used_names, name, step_number)
         if used_names.include?(name)
           error_message = "Duplicate step name or parameter detected: #{name.inspect}"
-          err = Step.step_error(error_message, name, step_number)
-          raise Bolt::Error.new(err, "bolt/invalid-plan")
+          raise Step::StepError.new(error_message, name, step_number)
         end
       end
 

data/lib/bolt/pal/yaml_plan/evaluator.rb

@@ -12,165 +12,15 @@ module Bolt
           @evaluator = Puppet::Pops::Parser::EvaluatingParser.new
         end
 
-        def dispatch_step(scope, step)
-          step_body = evaluate_code_blocks(scope, step.body)
-
-          # Dispatch based on the step class name
-          step_type = step.class.name.split('::').last.downcase
-          method = "#{step_type}_step"
-
-          send(method, scope, step_body)
-        end
-
-        def task_step(scope, step)
-          task = step['task']
-          targets = step['targets'] || step['target']
-          description = step['description']
-          params = step['parameters'] || {}
-
-          args = if description
-                   [task, targets, description, params]
-                 else
-                   [task, targets, params]
-                 end
-
-          scope.call_function('run_task', args)
-        end
-
-        def plan_step(scope, step)
-          plan = step['plan']
-          parameters = step['parameters'] || {}
-
-          args = [plan, parameters]
-
-          scope.call_function('run_plan', args)
-        end
-
-        def script_step(scope, step)
-          script = step['script']
-          targets = step['targets'] || step['target']
-          description = step['description']
-          arguments = step['arguments'] || []
-
-          options = { 'arguments' => arguments }
-          args = if description
-                   [script, targets, description, options]
-                 else
-                   [script, targets, options]
-                 end
-
-          scope.call_function('run_script', args)
-        end
-
-        def command_step(scope, step)
-          command = step['command']
-          targets = step['targets'] || step['target']
-          description = step['description']
-
-          args = [command, targets]
-          args << description if description
-          scope.call_function('run_command', args)
-        end
-
-        def upload_step(scope, step)
-          source = step['upload'] || step['source']
-          destination = step['destination']
-          targets = step['targets'] || step['target']
-          description = step['description']
-
-          args = [source, destination, targets]
-          args << description if description
-          scope.call_function('upload_file', args)
-        end
-
-        def download_step(scope, step)
-          source = step['download']
-          destination = step['destination']
-          targets = step['targets'] || step['target']
-          description = step['description']
-
-          args = [source, destination, targets]
-          args << description if description
-          scope.call_function('download_file', args)
-        end
-
-        def eval_step(_scope, step)
-          step['eval']
-        end
-
-        def resources_step(scope, step)
-          targets = step['targets'] || step['target']
-
-          # TODO: Only call apply_prep when needed
-          scope.call_function('apply_prep', targets)
-          manifest = generate_manifest(step['resources'])
-
-          apply_manifest(scope, targets, manifest)
-        end
-
-        def message_step(scope, step)
-          scope.call_function('out::message', [step['message']])
-        end
-
-        def generate_manifest(resources)
-          # inspect returns the Ruby representation of the resource hashes,
-          # which happens to be the same as the Puppet representation
-          puppet_resources = resources.inspect
-
-          # Because the :tasks setting globally controls which mode the parser
-          # is in, we need to make this snippet of non-tasks manifest code
-          # parseable in tasks mode. The way to do that is by putting it in an
-          # apply statement and taking the body.
-          <<~MANIFEST
-          apply('placeholder') {
-            $resources = #{puppet_resources}
-            $resources.each |$res| {
-              Resource[$res['type']] { $res['title']:
-                * => $res['parameters'],
-              }
-            }
-
-            # Add relationships if there is more than one resource
-            if $resources.length > 1 {
-              ($resources.length - 1).each |$index| {
-                $lhs = $resources[$index]
-                $rhs = $resources[$index+1]
-                $lhs_resource = Resource[$lhs['type'] , $lhs['title']]
-                $rhs_resource = Resource[$rhs['type'] , $rhs['title']]
-                $lhs_resource -> $rhs_resource
-              }
-            }
-          }
-          MANIFEST
-        end
-
-        def apply_manifest(scope, targets, manifest)
-          ast = @evaluator.parse_string(manifest)
-          apply_block = ast.body.body
-          applicator = Puppet.lookup(:apply_executor)
-          applicator.apply([targets], apply_block, scope)
-        end
-
         # This is the method that Puppet calls to evaluate the plan. The name
         # makes more sense for .pp plans.
+        #
         def evaluate_block_with_bindings(closure_scope, args_hash, plan)
-          if plan.steps.any? { |step| step.body.key?('target') }
-            msg = "The 'target' parameter for YAML plan steps is deprecated and will be removed "\
-                  "in a future version of Bolt. Use the 'targets' parameter instead."
-            Bolt::Logger.deprecate("yaml_plan_target", msg)
-          end
-
-          if plan.steps.any? { |step| step.body.key?('source') }
-            msg = "The 'source' parameter for YAML plan upload steps is deprecated and will be removed "\
-                  "in a future version of Bolt. Use the 'upload' parameter instead."
-            Bolt::Logger.deprecate("yaml_plan_source", msg)
-          end
-
           plan_result = closure_scope.with_local_scope(args_hash) do |scope|
             plan.steps.each do |step|
-              step_result = dispatch_step(scope, step)
+              step_result = step.evaluate(scope, self)
 
-              scope.setvar(step.name, step_result) if step.name
+              scope.setvar(step.body['name'], step_result) if step.body['name']
             end
 
             evaluate_code_blocks(scope, plan.return)
@@ -180,6 +30,7 @@ module Bolt
         end
 
         # Recursively evaluate any EvaluableString instances in the object.
+        #
         def evaluate_code_blocks(scope, value)
           # XXX We should establish a local scope here probably
           case value
@@ -204,6 +55,7 @@ module Bolt
         # Occasionally the Closure will ask us to evaluate what it assumes are
         # AST objects. Because we've sidestepped the AST, they aren't, so just
         # return the values as already evaluated.
+        #
         def evaluate(value, _scope)
           value
         end

data/lib/bolt/pal/yaml_plan/step.rb

@@ -6,41 +6,56 @@ module Bolt
   class PAL
     class YamlPlan
       class Step
-        attr_reader :name, :type, :body, :targets
-
-        def self.allowed_keys
-          Set['name', 'description', 'target', 'targets']
-        end
+        attr_reader :body
 
         STEP_KEYS = %w[
           command
-          destination
           download
           eval
           message
           plan
           resources
           script
-          source
           task
           upload
         ].freeze
 
+        class StepError < Bolt::Error
+          def initialize(message, name, step_number)
+            identifier = name ? name.inspect : "number #{step_number}"
+            error      = "Parse error in step #{identifier}: \n #{message}"
+
+            super(error, 'bolt/invalid-plan')
+          end
+        end
+
+        # Keys that are allowed for the step
+        #
+        def self.allowed_keys
+          required_keys + option_keys + Set['name', 'description', 'targets']
+        end
+
+        # Keys that translate to metaparameters for the plan step's function call
+        #
+        def self.option_keys
+          Set.new
+        end
+
+        # Keys that are required for the step
+        #
+        def self.required_keys
+          Set.new
+        end
+
         def self.create(step_body, step_number)
           type_keys = (STEP_KEYS & step_body.keys)
           case type_keys.length
           when 0
-            raise step_error("No valid action detected", step_body['name'], step_number)
+            raise StepError.new("No valid action detected", step_body['name'], step_number)
           when 1
             type = type_keys.first
           else
-            if [Set['source', 'destination'], Set['upload', 'destination']].include?(type_keys.to_set)
-              type = 'upload'
-            elsif type_keys.to_set == Set['download', 'destination']
-              type = 'download'
-            else
-              raise step_error("Multiple action keys detected: #{type_keys.inspect}", step_body['name'], step_number)
-            end
+            raise StepError.new("Multiple action keys detected: #{type_keys.inspect}", step_body['name'], step_number)
           end
 
           step_class = const_get("Bolt::PAL::YamlPlan::Step::#{type.capitalize}")
@@ -48,15 +63,49 @@ module Bolt
           step_class.new(step_body)
         end
 
-        def initialize(step_body)
-          @name = step_body['name']
-          @description = step_body['description']
-          @targets = step_body['targets'] || step_body['target']
-          @body = step_body
+        def initialize(body)
+          @body = body
         end
 
+        # Transpiles the step into the plan language
+        #
         def transpile
-          raise NotImplementedError, "Step #{@name} does not supported conversion to Puppet plan language"
+          code = String.new("  ")
+          code << "$#{body['name']} = " if body['name']
+          code << function_call(function, format_args(body))
+          code << "\n"
+        end
+
+        # Evaluates the step
+        #
+        def evaluate(scope, evaluator)
+          evaluated = evaluator.evaluate_code_blocks(scope, body)
+          scope.call_function(function, format_args(evaluated))
+        end
+
+        # Formats a list of args from the provided body
+        #
+        private def format_args(_body)
+          raise NotImplementedError, "Step class #{self.class} does not implement #format_args"
+        end
+
+        # Returns the step's corresponding Puppet language function call
+        #
+        private def function_call(function, args)
+          code_args = args.map { |arg| Bolt::Util.to_code(arg) }
+          "#{function}(#{code_args.join(', ')})"
+        end
+
+        # The function that corresponds to the step
+        #
+        private def function
+          raise NotImplementedError, "Step class #{self.class} does not implement #function"
+        end
+
+        # Returns a hash of options formatted for function calls
+        #
+        private def format_options(body)
+          body.slice(*self.class.option_keys).transform_keys { |key| "_#{key}" }
         end
 
         def self.validate(body, step_number)
@@ -65,19 +114,35 @@ module Bolt
           begin
             body.each { |k, v| validate_puppet_code(k, v) }
           rescue Bolt::Error => e
-            raise step_error(e.msg, body['name'], step_number)
+            raise StepError.new(e.msg, body['name'], step_number)
+          end
+
+          if body.key?('parameters')
+            unless body['parameters'].is_a?(Hash)
+              raise StepError.new("Parameters key must be a hash", body['name'], step_number)
+            end
+
+            metaparams = option_keys.map { |key| "_#{key}" }
+
+            if (dups = body['parameters'].keys & metaparams).any?
+              raise StepError.new(
+                "Cannot specify metaparameters when using top-level keys with same name: #{dups.join(', ')}",
+                body['name'],
+                step_number
+              )
+            end
           end
 
           unless body.fetch('parameters', {}).is_a?(Hash)
             msg = "Parameters key must be a hash"
-            raise step_error(msg, body['name'], step_number)
+            raise StepError.new(msg, body['name'], step_number)
           end
 
           if body.key?('name')
             name = body['name']
             unless name.is_a?(String) && name.match?(Bolt::PAL::YamlPlan::VAR_NAME_PATTERN)
               error_message = "Invalid step name: #{name.inspect}"
-              raise step_error(error_message, body['name'], step_number)
+              raise StepError.new(error_message, body['name'], step_number)
             end
           end
         end
@@ -89,30 +154,15 @@ module Bolt
           illegal_keys = body.keys.to_set - allowed_keys
           if illegal_keys.any?
             error_message = "The #{step_type.inspect} step does not support: #{illegal_keys.to_a.inspect} key(s)"
-            err = step_error(error_message, body['name'], step_number)
-            raise Bolt::Error.new(err, "bolt/invalid-plan")
+            raise StepError.new(error_message, body['name'], step_number)
           end
 
           # Ensure all required keys are present
           missing_keys = required_keys - body.keys
 
-          # Handle cases where steps with a required 'targets' key are using the deprecated
-          # 'target' key instead.
-          # TODO: Remove this when 'target' is removed
-          if body.include?('target')
-            missing_keys -= ['targets']
-          end
-
-          # Handle cases where upload step uses deprecated 'source' key instead of 'upload'
-          # TODO: Remove when 'source' is removed
-          if body.include?('source')
-            missing_keys -= ['upload']
-          end
-
           if missing_keys.any?
             error_message = "The #{step_type.inspect} step requires: #{missing_keys.to_a.inspect} key(s)"
-            err = step_error(error_message, body['name'], step_number)
-            raise Bolt::Error.new(err, "bolt/invalid-plan")
+            raise StepError.new(error_message, body['name'], step_number)
           end
         end
 
@@ -144,12 +194,6 @@ module Bolt
           raise Bolt::Error.new("Error parsing #{step_key.inspect}: #{e.basic_message}", "bolt/invalid-plan")
         end
 
-        def self.step_error(message, name, step_number)
-          identifier = name ? name.inspect : "number #{step_number}"
-          error = "Parse error in step #{identifier}: \n #{message}"
-          Bolt::Error.new(error, 'bolt/invalid-plan')
-        end
-
         # Parses the an evaluable string, optionally quote it before parsing
         def self.parse_code_string(code, quote = false)
           if quote
@@ -159,11 +203,6 @@ module Bolt
             Puppet::Pops::Parser::EvaluatingParser.new.parse_string(code)
           end
         end
-
-        def function_call(function, args)
-          code_args = args.map { |arg| Bolt::Util.to_code(arg) }
-          "#{function}(#{code_args.join(', ')})"
-        end
       end
     end
   end