bolt 1.39.0 → 1.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99b27a1cfbd744e85a99efe9c4785b4ab3a15e9a6fe15af9ac0496bd463736c7
-  data.tar.gz: 530cbd2525700cdaebf9920aebf1ea3b104a2867dfb030a695e0046e162152a2
+  metadata.gz: f796af64ec2860ec9e3fc3809e246bca8ebafa4199c50757c3c63749069c4017
+  data.tar.gz: 7a11411a59cd4c5eb50c9ddc9ed02c5b0838aa6cab860f15ef46d76be7f4a34f
 SHA512:
-  metadata.gz: cf7e5a175d04bf27ad2e2e0b4e464f334be20e4d08e9f0d072a51da695eb00698623eada2153865ec68fe125ace42e4c4939a5ef24513ec9139b1d87d302a6b0
-  data.tar.gz: fedbec2378ba33c83b3cbbb1fce8e3a610c2dbbe66c200ddc72f2e6728b49a2f38a7f60ecebbc4ebb0959227d4402175108ad0da5d15220b3ddc91b52d5ae725
+  metadata.gz: f1365e9a864d04685b3e922d810fbdad173e8f703b28c004c1005032b9666f56bcc3b251c25292e8d3239417a5a9a1b3c53ed49619e23d8f89fed341b6bde2c0
+  data.tar.gz: 2c1700287f8a9879b510d8d2cf91b9f044e44546ef5ec2f72b8e5a6a4ad1871e0f21737b67743971cdb1f8c5df9d9321352726aadaaad5367cd2f7702b89e1f1

data/bolt-modules/boltlib/lib/puppet/functions/catch_errors.rb

@@ -44,9 +44,9 @@ Puppet::Functions.create_function(:catch_errors) do
     rescue Puppet::PreformattedError => e
       if e.cause.is_a?(Bolt::Error)
         if error_types.nil?
-          return e.cause.to_puppet_error
+          e.cause.to_puppet_error
         elsif error_types.include?(e.cause.to_h['kind'])
-          return e.cause.to_puppet_error
+          e.cause.to_puppet_error
         else
           raise e
         end

data/lib/bolt/inventory.rb

@@ -212,7 +212,7 @@ module Bolt
       }
       data = Bolt::Util.deep_merge(defaults, data)
       # If features is an empty array deep_merge won't add the puppet-agent
-      data['features'] << 'puppet-agent' if data['features'].empty?
+      data['features'] += ['puppet-agent'] if data['features'].empty?
       data
     end
 

data/lib/bolt/outputter/human.rb

@@ -257,15 +257,18 @@ module Bolt
         plan_info = +""
         usage = +"bolt plan run #{plan['name']}"
 
-        plan['parameters']&.each do |name, p|
+        plan['parameters'].each do |name, p|
           pretty_params << "- #{name}: #{p['type']}\n"
+          pretty_params << "    Default: #{p['default_value']}\n" unless p['default_value'].nil?
+          pretty_params << "    #{p['description']}\n" if p['description']
           usage << (p.include?('default_value') ? " [#{name}=<value>]" : " #{name}=<value>")
         end
 
         plan_info << "\n#{plan['name']}"
+        plan_info << " - #{plan['description']}" if plan['description']
         plan_info << "\n\n"
         plan_info << "USAGE:\n#{usage}\n\n"
-        plan_info << "PARAMETERS:\n#{pretty_params}\n" if plan['parameters']
+        plan_info << "PARAMETERS:\n#{pretty_params}\n" unless plan['parameters'].empty?
         plan_info << "MODULE:\n"
 
         path = plan['module']

data/lib/bolt/pal.rb

@@ -299,38 +299,78 @@ module Bolt
       end
     end
 
-    # This converts a plan signature object into a format used by the outputter.
-    # Must be called from within bolt compiler to pickup type aliases used in the plan signature.
-    def plan_hash(plan_name, plan)
-      elements = plan.params_type.elements || []
-      parameters = elements.each_with_object({}) do |param, acc|
-        type = if param.value_type.is_a?(Puppet::Pops::Types::PTypeAliasType)
-                 param.value_type.name
-               else
-                 param.value_type.to_s
-               end
-        acc[param.name] = { 'type' => type }
-        acc[param.name]['default_value'] = nil if param.key_type.is_a?(Puppet::Pops::Types::POptionalType)
-      end
-      {
-        'name' => plan_name,
-        'parameters' => parameters
-      }
-    end
-    private :plan_hash
-
     def get_plan_info(plan_name)
-      plan_info = in_bolt_compiler do |compiler|
-        plan = compiler.plan_signature(plan_name)
-        hash = plan_hash(plan_name, plan) if plan
-        hash['module'] = plan.instance_variable_get(:@plan_func).loader.parent.path if plan
-        hash
+      plan_sig = in_bolt_compiler do |compiler|
+        compiler.plan_signature(plan_name)
       end
 
-      if plan_info.nil?
+      if plan_sig.nil?
         raise Bolt::Error.unknown_plan(plan_name)
       end
-      plan_info
+
+      mod = plan_sig.instance_variable_get(:@plan_func).loader.parent.path
+
+      # If it's a Puppet language plan, use strings to extract data. The only
+      # way to tell is to check which filename exists in the module.
+      plan_file = plan_name.split('::', 2)[1] || 'init'
+      pp_path = File.join(mod, 'plans', "#{plan_file}.pp")
+      if File.exist?(pp_path)
+        require 'puppet-strings'
+        require 'puppet-strings/yard'
+        PuppetStrings::Yard.setup!
+        YARD::Logger.instance.level = :error
+        YARD.parse(pp_path)
+
+        plan = YARD::Registry.at("puppet_plans::#{plan_name}")
+
+        description = if plan.tag(:summary)
+                        plan.tag(:summary).text
+                      elsif !plan.docstring.empty?
+                        plan.docstring
+                      end
+
+        defaults = plan.parameters.reject { |_, value| value.nil? }.to_h
+        parameters = plan.tags(:param).each_with_object({}) do |param, params|
+          name = param.name
+          params[name] = { 'type' => param.types.first }
+          params[name]['default_value'] = defaults[name] if defaults.key?(name)
+          params[name]['description'] = param.text unless param.text.empty?
+        end
+
+        {
+          'name' => plan_name,
+          'description' => description,
+          'parameters' => parameters,
+          'module' => mod
+        }
+
+      # If it's a YAML plan, fall back to limited data
+      else
+        yaml_path = File.join(mod, 'plans', "#{plan_file}.yaml")
+        plan_content = File.read(yaml_path)
+        plan = Bolt::PAL::YamlPlan::Loader.from_string(plan_name, plan_content, yaml_path)
+
+        parameters = plan.parameters.each_with_object({}) do |param, params|
+          name = param.name
+          type_str = case param.type_expr
+                     when Puppet::Pops::Types::PTypeReferenceType
+                       param.type_expr.type_string
+                     when nil
+                       'Any'
+                     else
+                       param.type_expr
+                     end
+          params[name] = { 'type' => type_str }
+          params[name]['default_value'] = param.value
+          params[name]['description'] = param.description if param.description
+        end
+        {
+          'name' => plan_name,
+          'description' => plan.description,
+          'parameters' => parameters,
+          'module' => mod
+        }
+      end
     end
 
     def convert_plan(plan_path)

data/lib/bolt/pal/yaml_plan.rb

@@ -6,16 +6,17 @@ require 'bolt/pal/yaml_plan/step'
 module Bolt
   class PAL
     class YamlPlan
-      PLAN_KEYS = Set['parameters', 'steps', 'return', 'version']
+      PLAN_KEYS = Set['parameters', 'steps', 'return', 'version', 'description']
       VAR_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/.freeze
 
-      attr_reader :name, :parameters, :steps, :return
+      attr_reader :name, :parameters, :steps, :return, :description
 
       def initialize(name, plan)
         # Top-level plan keys aren't allowed to be Puppet code, so force them
         # all to strings.
         plan = Bolt::Util.walk_keys(plan) { |key| stringify(key) }
         @name = name.freeze
+        @description = stringify(plan['description']) if plan['description']
 
         params_hash = stringify(plan.fetch('parameters', {}))
         # Ensure params is a hash

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

@@ -53,7 +53,7 @@ module Bolt
           PuppetVisitor.create_visitor.accept(parse_tree)
         end
 
-        def self.create(loader, typed_name, source_ref, yaml_string)
+        def self.from_string(name, yaml_string, source_ref)
           result = parse_plan(yaml_string, source_ref)
           unless result.is_a?(Hash)
             type = result.class.name
@@ -61,11 +61,14 @@ module Bolt
           end
 
           begin
-            plan_definition = YamlPlan.new(typed_name, result).freeze
+            YamlPlan.new(name, result).freeze
           rescue Bolt::Error => e
             raise Puppet::ParseError.new(e.message, source_ref)
           end
+        end
 
+        def self.create(loader, typed_name, source_ref, yaml_string)
+          plan_definition = from_string(typed_name.name, yaml_string, source_ref)
           created = create_function_class(plan_definition)
           closure_scope = nil
 

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

@@ -4,7 +4,7 @@ module Bolt
   class PAL
     class YamlPlan
       class Parameter
-        attr_reader :name, :value, :type_expr
+        attr_reader :name, :value, :type_expr, :description
 
         PARAMETER_KEYS = Set['type', 'default', 'description']
 
@@ -15,6 +15,7 @@ module Bolt
           @name = param
           @value = definition['default']
           @type_expr = Puppet::Pops::Types::TypeParser.singleton.parse(definition['type']) if definition['type']
+          @description = definition['description']
         end
 
         def validate_param(param, definition)

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

@@ -48,7 +48,6 @@ module Bolt
           plan_string
         end
 
-        # Save me from all these rescue statements...
         def parse_plan
           begin
             file_contents = File.read(@plan_path)
@@ -57,18 +56,7 @@ module Bolt
             raise Bolt::FileError.new(msg, @plan_path)
           end
 
-          begin
-            result = Bolt::PAL::YamlPlan::Loader.parse_plan(file_contents, @plan_path)
-          rescue Error => e
-            raise ConvertError.new("Failed to convert yaml plan: #{e.message}", @plan_path)
-          end
-
-          unless result.is_a?(Hash)
-            type = result.class.name
-            raise ArgumentError, "The data loaded from #{source_ref} does not contain an object - its type is #{type}"
-          end
-
-          Bolt::PAL::YamlPlan.new(@modulename, result).freeze
+          Bolt::PAL::YamlPlan::Loader.from_string(@modulename, file_contents, @plan_path)
         end
 
         def validate_path

data/lib/bolt/plugin.rb

@@ -63,7 +63,7 @@ module Bolt
         if defined?(Puppet)
           begin
             compiler = Puppet.lookup(:pal_compiler)
-          rescue Puppet::Context::UndefinedBindingError; end # rubocop:disable Lint/HandleExceptions
+          rescue Puppet::Context::UndefinedBindingError; end # rubocop:disable Lint/SuppressedException
         end
 
         if compiler

data/lib/bolt/plugin/puppetdb.rb

@@ -11,7 +11,8 @@ module Bolt
         end
       end
 
-      TARGET_OPTS = %w[uri name config].freeze
+      TEMPLATE_OPTS = %w[uri name config].freeze
+      PLUGIN_OPTS = %w[_plugin query target_mapping].freeze
 
       def initialize(pdb_client)
         @puppetdb_client = pdb_client
@@ -45,8 +46,19 @@ module Bolt
         targets = @puppetdb_client.query_certnames(opts['query'])
         facts = []
 
-        target_opts = opts.select { |k, _| TARGET_OPTS.include?(k) }
-        Bolt::Util.walk_vals(target_opts) do |value|
+        template = opts.delete('target_mapping') || {}
+
+        keys = Set.new(TEMPLATE_OPTS) & opts.keys
+        unless keys.empty?
+          raise Bolt::ValidationError, "PuppetDB plugin expects keys #{keys.to_a} to be set under 'target_mapping'"
+        end
+
+        keys = Set.new(opts.keys) - PLUGIN_OPTS
+        unless keys.empty?
+          raise Bolt::ValidationError, "Unknown keys in PuppetDB plugin: #{keys.to_a}"
+        end
+
+        Bolt::Util.walk_vals(template) do |value|
           # This is done in parts instead of in place so that we only need to
           # make one puppetDB query
           if value.is_a?(String)
@@ -61,7 +73,7 @@ module Bolt
 
         targets.map do |certname|
           target_data = fact_values[certname]
-          target = resolve_facts(target_opts, certname, target_data) || {}
+          target = resolve_facts(template, certname, target_data) || {}
           target['uri'] = certname unless target['uri'] || target['name']
 
           target

data/lib/bolt/util.rb

@@ -176,7 +176,7 @@ module Bolt
         rescue TypeError
           # unclonable (TrueClass, Fixnum, ...)
           cloned[obj.object_id] = obj
-          return obj
+          obj
         else
           cloned[obj.object_id] = cl
           cloned[cl.object_id] = cl
@@ -195,7 +195,7 @@ module Bolt
             cl.instance_variable_set(var, v_cl)
           end
 
-          return cl
+          cl
         end
       end
 

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '1.39.0'
+  VERSION = '1.40.0'
 end

data/modules/canary/plans/init.pp

@@ -24,7 +24,7 @@
 #
 # @example Run a command
 #   run_plan(canary, command => 'whoami', nodes => $mynodes)
-
+#
 plan canary(
   Optional[String[0]] $task = undef,
   Optional[String[0]] $command = undef,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 1.39.0
+  version: 1.40.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-22 00:00:00.000000000 Z
+date: 2019-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -184,6 +184,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.8.1
+- !ruby/object:Gem::Dependency
+  name: puppet-strings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: r10k
   requirement: !ruby/object:Gem::Requirement