pdk 1.10.0 → 1.11.0

data/lib/pdk/cli/new/class.rb

@@ -24,6 +24,8 @@ module PDK::CLI
         raise PDK::CLI::ExitWithError, _("'%{name}' is not a valid class name") % { name: class_name }
       end
 
+      PDK::CLI::Util.analytics_screen_view('new_class', opts)
+
       PDK::Generate::PuppetClass.new(module_dir, class_name, opts).run
     end
   end

data/lib/pdk/cli/new/defined_type.rb

@@ -22,6 +22,8 @@ module PDK::CLI
         raise PDK::CLI::ExitWithError, _("'%{name}' is not a valid defined type name") % { name: defined_type_name }
       end
 
+      PDK::CLI::Util.analytics_screen_view('new_defined_type', opts)
+
       PDK::Generate::DefinedType.new(module_dir, defined_type_name, opts).run
     end
   end

data/lib/pdk/cli/new/module.rb

@@ -21,6 +21,8 @@ module PDK::CLI
 
       PDK::CLI::Util.validate_template_opts(opts)
 
+      PDK::CLI::Util.analytics_screen_view('new_module', opts)
+
       if opts[:'skip-interview'] && opts[:'full-interview']
         PDK.logger.info _('Ignoring --full-interview and continuing with --skip-interview.')
         opts[:'full-interview'] = false

data/lib/pdk/cli/new/provider.rb

@@ -19,6 +19,8 @@ module PDK::CLI
         raise PDK::CLI::ExitWithError, _("'%{name}' is not a valid provider name") % { name: provider_name }
       end
 
+      PDK::CLI::Util.analytics_screen_view('new_provider', opts)
+
       PDK::Generate::Provider.new(module_dir, provider_name, opts).run
     end
   end

data/lib/pdk/cli/new/task.rb

@@ -24,6 +24,8 @@ module PDK::CLI
         raise PDK::CLI::ExitWithError, _("'%{name}' is not a valid task name") % { name: task_name }
       end
 
+      PDK::CLI::Util.analytics_screen_view('new_task', opts)
+
       PDK::Generate::Task.new(module_dir, task_name, opts).run
     end
   end

data/lib/pdk/cli/test.rb

@@ -1,4 +1,3 @@
-
 module PDK::CLI
   @test_cmd = @base_cmd.define_command do
     name 'test'

data/lib/pdk/cli/test/unit.rb

@@ -33,10 +33,22 @@ module PDK::CLI
 
       PDK::CLI::Util.module_version_check
 
+      PDK::CLI::Util.analytics_screen_view('test_unit', opts)
+
+      # Ensure that the bundled gems are up to date and correct Ruby is activated before running or listing tests.
+      puppet_env = PDK::CLI::Util.puppet_from_opts_or_env(opts)
+      PDK::Util::PuppetVersion.fetch_puppet_dev if opts[:'puppet-dev']
+      PDK::Util::RubyVersion.use(puppet_env[:ruby_version])
+
+      opts.merge!(puppet_env[:gemset])
+
+      PDK::Util::Bundler.ensure_bundle!(puppet_env[:gemset])
+
       report = nil
 
       if opts[:list]
-        examples = PDK::Test::Unit.list
+        examples = PDK::Test::Unit.list(opts)
+
         if examples.empty?
           puts _('No unit test files with examples were found.')
         else
@@ -66,15 +78,6 @@ module PDK::CLI
                            }]
                          end
 
-        # Ensure that the bundled gems are up to date and correct Ruby is activated before running tests.
-        puppet_env = PDK::CLI::Util.puppet_from_opts_or_env(opts)
-        PDK::Util::PuppetVersion.fetch_puppet_dev if opts.key?(:'puppet-dev')
-        PDK::Util::RubyVersion.use(puppet_env[:ruby_version])
-
-        opts.merge!(puppet_env[:gemset])
-
-        PDK::Util::Bundler.ensure_bundle!(puppet_env[:gemset])
-
         exit_code = PDK::Test::Unit.invoke(report, opts)
 
         report_formats.each do |format|

data/lib/pdk/cli/update.rb

@@ -26,6 +26,27 @@ module PDK::CLI
         raise PDK::CLI::ExitWithError, _('You can not specify --noop and --force when updating a module')
       end
 
+      if Gem::Version.new(PDK::VERSION) < Gem::Version.new(PDK::Util.module_pdk_version)
+        PDK.logger.warn _(
+          'This module has been updated to PDK %{module_pdk_version} which ' \
+          'is newer than your PDK version (%{user_pdk_version}), proceed ' \
+          'with caution!',
+        ) % {
+          module_pdk_version: PDK::Util.module_pdk_version,
+          user_pdk_version:   PDK::VERSION,
+        }
+
+        unless opts[:force]
+          raise PDK::CLI::ExitWithError, _(
+            'Please update your PDK installation and try again. ' \
+            'You may also use the --force flag to override this and ' \
+            'continue at your own risk.',
+          )
+        end
+      end
+
+      PDK::CLI::Util.analytics_screen_view('update', opts)
+
       updater = PDK::Module::Update.new(opts)
 
       updater.run

data/lib/pdk/cli/util.rb

@@ -198,6 +198,41 @@ module PDK
         raise PDK::CLI::ExitWithError, _('--template-url may not be used to specify paths containing #\'s.')
       end
       module_function :validate_template_opts
+
+      def analytics_screen_view(screen_name, opts = {})
+        dimensions = {
+          ruby_version: RUBY_VERSION,
+        }
+
+        cmd_opts = opts.dup.reject do |_, v|
+          v.nil? || (v.respond_to?(:empty?) && v.empty?)
+        end
+
+        if (format_args = cmd_opts.delete(:format))
+          formats = PDK::CLI::Util::OptionNormalizer.report_formats(format_args)
+          dimensions[:output_format] = formats.map { |r| r[:method].to_s.gsub(%r{\Awrite_}, '') }.sort.uniq.join(',')
+        else
+          dimensions[:output_format] = 'default'
+        end
+
+        safe_opts = [:'puppet-version', :'pe-version']
+        redacted_opts = cmd_opts.map do |k, v|
+          value = if [true, false].include?(v) || safe_opts.include?(k)
+                    v
+                  else
+                    'redacted'
+                  end
+          "#{k}=#{value}"
+        end
+        dimensions[:cli_options] = redacted_opts.join(',') unless redacted_opts.empty?
+
+        ignored_env_vars = %w[PDK_ANALYTICS_CONFIG PDK_DISABLE_ANALYTICS]
+        env_vars = ENV.select { |k, _| k.start_with?('PDK_') && !ignored_env_vars.include?(k) }.map { |k, v| "#{k}=#{v}" }
+        dimensions[:env_vars] = env_vars.join(',') unless env_vars.empty?
+
+        PDK.analytics.screen_view(screen_name, dimensions)
+      end
+      module_function :analytics_screen_view
     end
   end
 end

data/lib/pdk/cli/util/interview.rb

@@ -30,7 +30,13 @@ module PDK
             @prompt.print pastel.bold(_('[Q %{current_number}/%{questions_total}]') % { current_number: i, questions_total: num_questions }) + ' '
             @prompt.puts pastel.bold(question[:question])
             @prompt.puts question[:help] if question.key?(:help)
-            if question.key?(:choices)
+
+            case question[:type]
+            when :yes
+              yes?(_('-->')) do |q|
+                q.default(question[:default]) if question.key?(:default)
+              end
+            when :multi_select
               multi_select(_('-->'), per_page: question[:choices].count) do |q|
                 q.enum ')'
                 q.default(*question[:default]) if question.key?(:default)

data/lib/pdk/cli/validate.rb

@@ -31,6 +31,7 @@ module PDK::CLI
       targets = []
 
       if opts[:list]
+        PDK::CLI::Util.analytics_screen_view('validate', opts)
         PDK.logger.info(_('Available validators: %{validator_names}') % { validator_names: validator_names.join(', ') })
         exit 0
       end
@@ -71,6 +72,12 @@ module PDK::CLI
         PDK.logger.info(_('Running all available validators...'))
       end
 
+      if validators == PDK::Validate.validators
+        PDK::CLI::Util.analytics_screen_view('validate', opts)
+      else
+        PDK::CLI::Util.analytics_screen_view(['validate', validators.map(&:name).sort].flatten.join('_'), opts)
+      end
+
       # Subsequent arguments are targets.
       targets.concat(args.to_a[1..-1]) if args.length > 1
 
@@ -85,11 +92,11 @@ module PDK::CLI
                        end
 
       options = targets.empty? ? {} : { targets: targets }
-      options[:auto_correct] = true if opts.key?(:'auto-correct')
+      options[:auto_correct] = true if opts[:'auto-correct']
 
       # Ensure that the bundled gems are up to date and correct Ruby is activated before running any validations.
       puppet_env = PDK::CLI::Util.puppet_from_opts_or_env(opts)
-      PDK::Util::PuppetVersion.fetch_puppet_dev if opts.key?(:'puppet-dev')
+      PDK::Util::PuppetVersion.fetch_puppet_dev if opts[:'puppet-dev']
       PDK::Util::RubyVersion.use(puppet_env[:ruby_version])
 
       options.merge!(puppet_env[:gemset])

data/lib/pdk/config.rb

@@ -0,0 +1,94 @@
+require 'pdk/config/errors'
+require 'pdk/config/json'
+require 'pdk/config/namespace'
+require 'pdk/config/validator'
+require 'pdk/config/value'
+require 'pdk/config/yaml'
+
+module PDK
+  def self.config
+    @config ||= PDK::Config.new
+  end
+
+  class Config
+    def user
+      @user ||= PDK::Config::JSON.new('user', file: PDK::Config.user_config_path) do
+        mount :module_defaults, PDK::Config::JSON.new(file: PDK.answers.answer_file_path)
+
+        mount :analytics, PDK::Config::YAML.new(file: PDK::Config.analytics_config_path) do
+          value :disabled do
+            validate PDK::Config::Validator.boolean
+            default_to { PDK::Config.bolt_analytics_config.fetch('disabled', true) }
+          end
+
+          value 'user-id' do
+            validate PDK::Config::Validator.uuid
+            default_to do
+              require 'securerandom'
+
+              PDK::Config.bolt_analytics_config.fetch('user-id', SecureRandom.uuid)
+            end
+          end
+        end
+      end
+    end
+
+    def self.bolt_analytics_config
+      PDK::Config::YAML.new(file: File.expand_path('~/.puppetlabs/bolt/analytics.yaml'))
+    end
+
+    def self.analytics_config_path
+      ENV['PDK_ANALYTICS_CONFIG'] || File.join(File.dirname(PDK::Util.configdir), 'puppet', 'analytics.yml')
+    end
+
+    def self.user_config_path
+      File.join(PDK::Util.configdir, 'user_config.json')
+    end
+
+    def self.analytics_config_exist?
+      PDK::Util::Filesystem.file?(analytics_config_path)
+    end
+
+    def self.analytics_config_interview!
+      return unless PDK::CLI::Util.interactive?
+
+      pre_message = _(
+        'PDK collects anonymous usage information to help us understand how ' \
+        'it is being used and make decisions on how to improve it. You can ' \
+        'find out more about what data we collect and how it is used in the ' \
+        "PDK documentation at %{url}.\n",
+      ) % { url: 'https://puppet.com/docs/pdk/latest/pdk_install.html' }
+      post_message = _(
+        'You can opt in or out of the usage data collection at any time by ' \
+        'editing the analytics configuration file at %{path} and changing ' \
+        "the '%{key}' value.",
+      ) % {
+        path: PDK::Config.analytics_config_path,
+        key:  'disabled',
+      }
+
+      questions = [
+        {
+          name:     'enabled',
+          question: _('Do you consent to the collection of anonymous PDK usage information?'),
+          type:     :yes,
+        },
+      ]
+
+      PDK.logger.info(text: pre_message, wrap: true)
+      prompt = TTY::Prompt.new(help_color: :cyan)
+      interview = PDK::CLI::Util::Interview.new(prompt)
+      interview.add_questions(questions)
+      answers = interview.run
+
+      if answers.nil?
+        PDK.logger.info _('No answer given, opting out of analytics collection.')
+        PDK.config.user['analytics']['disabled'] = true
+      else
+        PDK.config.user['analytics']['disabled'] = !answers['enabled']
+      end
+
+      PDK.logger.info(text: post_message, wrap: true)
+    end
+  end
+end

data/lib/pdk/config/errors.rb

@@ -0,0 +1,5 @@
+module PDK
+  class Config
+    class LoadError < StandardError; end
+  end
+end

data/lib/pdk/config/json.rb

@@ -0,0 +1,23 @@
+require 'pdk/config/namespace'
+
+module PDK
+  class Config
+    class JSON < Namespace
+      def parse_data(data, _filename)
+        return {} if data.nil? || data.empty?
+
+        require 'json'
+
+        ::JSON.parse(data)
+      rescue ::JSON::ParserError => e
+        raise PDK::Config::LoadError, e.message
+      end
+
+      def serialize_data(data)
+        require 'json'
+
+        ::JSON.pretty_generate(data)
+      end
+    end
+  end
+end

data/lib/pdk/config/namespace.rb

@@ -0,0 +1,273 @@
+module PDK
+  class Config
+    class Namespace
+      # @param value [String] the new name of this namespace.
+      attr_writer :name
+
+      # @return [String] the path to the file associated with the contents of
+      #   this namespace.
+      attr_reader :file
+
+      # @return [self] the parent namespace of this namespace.
+      attr_accessor :parent
+
+      # Initialises the PDK::Config::Namespace object.
+      #
+      # @param name [String] the name of the namespace (defaults to nil).
+      # @param params [Hash{Symbol => Object}] keyword parameters for the
+      #   method.
+      # @option params [String] :file the path to the file associated with the
+      #   contents of the namespace (defaults to nil).
+      # @option params [self] :parent the parent {self} that this namespace is
+      #   a child of (defaults to nil).
+      # @param block [Proc] a block that is evaluated within the new instance.
+      def initialize(name = nil, file: nil, parent: nil, &block)
+        @file = File.expand_path(file) unless file.nil?
+        @values = {}
+        @name = name.to_s
+        @parent = parent
+
+        instance_eval(&block) if block_given?
+      end
+
+      # Pre-configure a value in the namespace.
+      #
+      # Allows you to specify validators and a default value for value in the
+      # namespace (see PDK::Config::Value#initialize).
+      #
+      # @param key [String,Symbol] the name of the value.
+      # @param block [Proc] a block that is evaluated within the new [self].
+      #
+      # @return [nil]
+      def value(key, &block)
+        @values[key.to_s] ||= PDK::Config::Value.new(key.to_s)
+        @values[key.to_s].instance_eval(&block) if block_given?
+      end
+
+      # Mount a provided [self] (or subclass) into the namespace.
+      #
+      # @param key [String,Symbol] the name of the namespace to be mounted.
+      # @param obj [self] the namespace to be mounted.
+      # @param block [Proc] a block to be evaluated within the instance of the
+      #   newly mounted namespace.
+      #
+      # @raise [ArgumentError] if the object to be mounted is not a {self} or
+      #   subclass thereof.
+      #
+      # @return [self] the mounted namespace.
+      def mount(key, obj, &block)
+        raise ArgumentError, _('Only PDK::Config::Namespace objects can be mounted into a namespace') unless obj.is_a?(PDK::Config::Namespace)
+        obj.parent = self
+        obj.name = key.to_s
+        obj.instance_eval(&block) if block_given?
+        data[key.to_s] = obj
+      end
+
+      # Create and mount a new child namespace.
+      #
+      # @param name [String,Symbol] the name of the new namespace.
+      # @param block [Proc]
+      def namespace(name, &block)
+        mount(name, PDK::Config::Namespace.new, &block)
+      end
+
+      # Get the value of the named key.
+      #
+      # If there is a value for that key, return it. If not, follow the logic
+      # described in {#default_config_value} to determine the default value to
+      # return.
+      #
+      # @note Unlike a Ruby Hash, this will not return `nil` in the event that
+      #   the key does not exist (see #fetch).
+      #
+      # @param key [String,Symbol] the name of the value to retrieve.
+      #
+      # @return [Object] the requested value.
+      def [](key)
+        data[key.to_s]
+      end
+
+      # Get the value of the named key or the provided default value if not
+      # present.
+      #
+      # This differs from {#[]} in an important way in that it allows you to
+      # return a default value, which is not possible using `[] || default` as
+      # non-existent values when accessed normally via {#[]} will be defaulted
+      # to a new Hash.
+      #
+      # @param key [String,Symbol] the name of the value to fetch.
+      # @param default_value [Object] the value to return if the namespace does
+      #   not contain the requested value.
+      #
+      # @return [Object] the requested value.
+      def fetch(key, default_value)
+        data.fetch(key.to_s, default_value)
+      end
+
+      # Set the value of the named key.
+      #
+      # If the key has been pre-configured with {#value}, then the value of the
+      # key will be validated against any validators that have been configured.
+      #
+      # After the value has been set in memory, the value will then be
+      # persisted to disk.
+      #
+      # @param key [String,Symbol] the name of the configuration value.
+      # @param value [Object] the value of the configuration value.
+      #
+      # @return [nil]
+      def []=(key, value)
+        @values[key.to_s].validate!([name, key.to_s].join('.'), value) if @values.key?(key.to_s)
+
+        data[key.to_s] = value
+        save_data
+      end
+
+      # Convert the namespace into a Hash of values, suitable for serialising
+      # and persisting to disk.
+      #
+      # Child namespaces that are associated with their own files are excluded
+      # from the Hash (as their values will be persisted to their own files)
+      # and nil values are removed from the Hash.
+      #
+      # @return [Hash{String => Object}] the values from the namespace that
+      #   should be persisted to disk.
+      def to_h
+        data.inject({}) do |new_hash, (key, value)|
+          new_hash[key] = if value.is_a?(PDK::Config::Namespace)
+                            value.include_in_parent? ? value.to_h : nil
+                          else
+                            value
+                          end
+          new_hash.delete_if { |_, v| v.nil? }
+        end
+      end
+
+      # @return [Boolean] true if the namespace has a parent, otherwise false.
+      def child_namespace?
+        !parent.nil?
+      end
+
+      # Determines the fully qualified name of the namespace.
+      #
+      # If this is a child namespace, then fully qualified name for the
+      # namespace will be "<parent>.<child>".
+      #
+      # @return [String] the fully qualifed name of the namespace.
+      def name
+        child_namespace? ? [parent.name, @name].join('.') : @name
+      end
+
+      # Determines if the contents of the namespace should be included in the
+      # parent namespace when persisting to disk.
+      #
+      # If the namespace has been mounted into a parent namespace and is not
+      # associated with its own file on disk, then the values in the namespace
+      # should be included in the parent namespace when persisting to disk.
+      #
+      # @return [Boolean] true if the values should be included in the parent
+      #   namespace.
+      def include_in_parent?
+        child_namespace? && file.nil?
+      end
+
+      private
+
+      # @abstract Subclass and override {#parse_data} to implement parsing logic
+      #   for a particular config file format.
+      #
+      # @param data [String] The content of the file to be parsed.
+      # @param filename [String] The path to the file to be parsed.
+      #
+      # @return [Hash{String => Object}] the data to be loaded into the
+      #   namespace.
+      def parse_data(_data, _filename)
+        {}
+      end
+
+      # Read the file associated with the namespace.
+      #
+      # @raise [PDK::Config::LoadError] if the file is removed during read.
+      # @raise [PDK::Config::LoadError] if the user doesn't have the
+      #   permissions needed to read the file.
+      # @return [String,nil] the contents of the file or nil if the file does
+      #   not exist.
+      def load_data
+        return if file.nil?
+        return unless PDK::Util::Filesystem.file?(file)
+
+        PDK::Util::Filesystem.read_file(file)
+      rescue Errno::ENOENT => e
+        raise PDK::Config::LoadError, e.message
+      rescue Errno::EACCES
+        raise PDK::Config::LoadError, _('Unable to open %{file} for reading') % {
+          file: file,
+        }
+      end
+
+      # @abstract Subclass and override {#save_data} to implement generating
+      #   logic for a particular config file format.
+      #
+      # @param data [Hash{String => Object}] the data stored in the namespace
+      #
+      # @return [String] the serialized contents of the namespace suitable for
+      #   writing to disk.
+      def serialize_data(_data); end
+
+      # Persist the contents of the namespace to disk.
+      #
+      # Directories will be automatically created and the contents of the
+      # namespace will be serialized automatically with {#serialize_data}.
+      #
+      # @raise [PDK::Config::LoadError] if one of the intermediary path components
+      #   exist but is not a directory.
+      # @raise [PDK::Config::LoadError] if the user does not have the
+      #   permissions needed to write the file.
+      #
+      # @return [nil]
+      def save_data
+        return if file.nil?
+
+        FileUtils.mkdir_p(File.dirname(file))
+
+        PDK::Util::Filesystem.write_file(file, serialize_data(to_h))
+      rescue Errno::EACCES
+        raise PDK::Config::LoadError, _('Unable to open %{file} for writing') % {
+          file: file,
+        }
+      rescue SystemCallError => e
+        raise PDK::Config::LoadError, e.message
+      end
+
+      # Memoised accessor for the loaded data.
+      #
+      # @return [Hash<String => Object>] the contents of the namespace.
+      def data
+        @data ||= parse_data(load_data, file).tap do |h|
+          h.default_proc = default_config_value
+        end
+      end
+
+      # The default behaviour of the namespace when the requested value does
+      # not exist.
+      #
+      # If the value has been pre-configured with {#value} to have a default
+      # value, resolve the default value and set it in the namespace
+      # (triggering a call to {#save_data}. Otherwise, set the value to a new
+      # Hash to allow for arbitrary level of nested values.
+      #
+      # @return [Proc] suitable for use by {Hash#default_proc}.
+      def default_config_value
+        ->(hash, key) do
+          if @values.key?(key) && @values[key].default?
+            self[key] = @values[key].default
+          else
+            hash[key] = {}.tap do |h|
+              h.default_proc = default_config_value
+            end
+          end
+        end
+      end
+    end
+  end
+end