pdk 1.9.0 → 3.2.0

data/lib/pdk/generate/puppet_object.rb

@@ -1,18 +1,9 @@
-require 'fileutils'
-
 require 'pdk'
-require 'pdk/logger'
-require 'pdk/module/metadata'
-require 'pdk/module/templatedir'
-require 'pdk/template_file'
-require 'pdk/util/filesystem'
 
 module PDK
   module Generate
     class PuppetObject
-      attr_reader :module_dir
-      attr_reader :object_name
-      attr_reader :options
+      attr_reader :context, :object_name, :options
 
       # Initialises the PDK::Generate::PuppetObject object.
       #
@@ -23,170 +14,127 @@ module PDK
       # OBJECT_TYPE constant and implement the {#template_data},
       # {#target_object_path} and {#target_spec_path} methods.
       #
-      # @param module_dir [String] The path to the module directory that the
+      # @param module_dir [String] The path to the root of module that the
       #   will contain the object.
       # @param object_name [String] The name of the object.
       # @param options [Hash{Symbol => Object}]
-      #
-      # @api public
-      def initialize(module_dir, object_name, options = {})
-        @module_dir = module_dir
+      def initialize(context, object_name, options)
+        raise ArgumentError, format('Expected PDK::Context::AbstractContext but got \'%{klass}\' for context', klass: context.class) unless context.is_a?(PDK::Context::AbstractContext)
+
+        @context = context
         @options = options
         @object_name = object_name
-
-        if [:class, :defined_type].include?(object_type) # rubocop:disable Style/GuardClause
-          object_name_parts = object_name.split('::')
-
-          @object_name = if object_name_parts.first == module_name
-                           object_name
-                         else
-                           [module_name, object_name].join('::')
-                         end
-        end
       end
 
-      # @abstract Subclass and implement {#template_data} to provide data to
-      #   the templates during rendering. Implementations of this method should
-      #   return a Hash!{Symbol => Object}.
-      def template_data
-        raise NotImplementedError
+      # Whether the generator should only return test (spec) files
+      # @return [Boolean]
+      def spec_only?
+        @options[:spec_only]
       end
 
-      # @abstract Subclass and implement {#target_object_path}. Implementations
-      #   of this method should return a String containing the destination path
-      #   of the object being generated.
-      def target_object_path
+      # Subclass and implement {#friendly_name} to provide a nice name to show users in CLI
+      # @abstract
+      # @return String
+      def friendly_name
         raise NotImplementedError
       end
 
-      # @abstract Subclass and implement {#target_type_path}. Implementations
-      #   of this method should return a String containing the destination path
-      #   of the additional object file being generated.
-      # @return [String] returns nil if there is no additional object file
-      def target_type_path
-        nil
+      # Subclass and implement {#template_files} to provide the template files to
+      #   render. Implementations of this method should return a Hash!{String => String}.
+      # @abstract
+      # @return Hash{String => String} Hash key is the source template file and the Hash value is
+      #                                the relative destination path
+      def template_files
+        raise NotImplementedError
       end
 
-      # @abstract Subclass and implement {#target_spec_path}. Implementations
-      #   of this method should return a String containing the destination path
-      #   of the tests for the object being generated.
-      def target_spec_path
+      #  Subclass and implement {#template_data} to provide data to the templates during rendering.
+      # @abstract
+      # @return Hash{Symbol => Object}
+      def template_data
         raise NotImplementedError
       end
 
-      # @abstract Subclass and implement {#target_type_spec_path}. Implementations
-      #   of this method should return a String containing the destination path
-      #   of the tests for the object being generated.
-      def target_type_spec_path
-        nil
+      # Raises an error if any pre-conditions are not met
+      #
+      # @return [void]
+      # @abstract
+      def check_preconditions
+        raise ArgumentError, format('Expected a module context but got %{context_name}', context_name: context.display_name) unless context.is_a?(PDK::Context::Module)
       end
 
-      # Retrieves the type of the object being generated, e.g. :class,
-      # :defined_type, etc. This is specified in the subclass' OBJECT_TYPE
-      # constant.
-      #
-      # @return [Symbol] the type of the object being generated.
+      # Check the preconditions of this template group, behaving as a predicate rather than raising an exception.
       #
+      # @return [Boolean] true if the generator is safe to run, otherwise false.
+      def can_run?
+        check_preconditions
+        true
+      rescue StandardError
+        false
+      end
+
+      # Creates an instance of an update manager
       # @api private
-      def object_type
-        self.class::OBJECT_TYPE
+      def update_manager_instance
+        require 'pdk/module/update_manager'
+        PDK::Module::UpdateManager.new
       end
 
-      # Check preconditions of this template group. By default this only makes sure that the target files do not
-      # already exist. Override this (and call super) to add your own preconditions.
-      #
-      # @raise [PDK::CLI::ExitWithError] if the target files already exist.
+      # Stages and then executes the changes for the templates to be rendereed.
+      # This is the main entry point for the class.
       #
+      # @see #stage_changes
+      # @return [PDK::Module::UpdateManager] The update manager which implemented the changes
       # @api public
-      def check_preconditions
-        [target_object_path, target_type_path, target_spec_path, target_type_spec_path].compact.each do |target_file|
-          next unless File.exist?(target_file)
-
-          raise PDK::CLI::ExitWithError, _("Unable to generate %{object_type}; '%{file}' already exists.") % {
-            file:        target_file,
-            object_type: object_type,
-          }
-        end
+      def run(update_manager = update_manager_instance)
+        stage_changes(update_manager).sync_changes!
+        update_manager
       end
 
       # Check that the templates can be rendered. Find an appropriate template
-      # and create the target files from the template. This is the main entry
+      # and stages the target files from the template. This is the main entry
       # point for the class.
       #
       # @raise [PDK::CLI::ExitWithError] if the target files already exist.
       # @raise [PDK::CLI::FatalError] (see #render_file)
-      #
+      # @return [PDK::Module::UpdateManager] The update manager with the staged changes
       # @api public
-      def run
+      def stage_changes(update_manager)
         check_preconditions
 
-        with_templates do |template_path, config_hash|
-          data = template_data.merge(configs: config_hash)
+        with_templates do |template_dir|
+          template_files.each do |source_file, relative_dest_path|
+            new_content = template_dir.render_single_item(source_file, template_data)
+            next if new_content.nil?
 
-          render_file(target_object_path, template_path[:object], data)
-          render_file(target_type_path, template_path[:type], data) if template_path[:type]
-          render_file(target_spec_path, template_path[:spec], data) if template_path[:spec]
-          render_file(target_type_spec_path, template_path[:type_spec], data) if template_path[:type_spec]
+            stage_change(relative_dest_path, new_content, update_manager)
+          end
         end
+        non_template_files.each { |relative_dest_path, content| stage_change(relative_dest_path, content, update_manager) }
+
+        update_manager
       end
 
-      # Render a file using the provided template and write it to disk.
-      #
-      # @param dest_path [String] The path that the rendered file should be
-      #   written to. Any necessary directories will be automatically created.
-      # @param template_path [String] The path on disk to the file containing
-      #   the template.
-      # @param data [Hash{Object => Object}] The data to be provided to the
-      #   template when rendering.
-      #
-      # @raise [PDK::CLI::FatalError] if the parent directories to `dest_path`
-      #   do not exist and could not be created.
-      # @raise [PDK::CLI::FatalError] if the rendered file could not be written
-      #   to `dest_path`.
-      #
+      # Stages a single file into the Update Manager.
       # @return [void]
-      #
       # @api private
-      def render_file(dest_path, template_path, data)
-        write_file(dest_path) do
-          PDK::TemplateFile.new(template_path, data).render
+      def stage_change(relative_dest_path, content, update_manager)
+        absolute_file_path = File.join(context.root_path, relative_dest_path)
+        if PDK::Util::Filesystem.exist?(absolute_file_path)
+          raise PDK::CLI::ExitWithError, format("Unable to generate %{object_type}; '%{file}' already exists.", file: absolute_file_path, object_type: spec_only? ? 'unit test' : friendly_name)
         end
+
+        update_manager.add_file(absolute_file_path, content)
       end
 
-      # Write the result of the block to disk.
-      #
-      # @param dest_path [String] The path that the rendered file should be
-      #   written to. Any necessary directories will be automatically created.
-      # @param &block [String] The content to be written
-      #
-      # @raise [PDK::CLI::FatalError] if the parent directories to `dest_path`
-      #   do not exist and could not be created.
-      # @raise [PDK::CLI::FatalError] if the rendered file could not be written
-      #   to `dest_path`.
-      #
-      # @return [void]
+      # A subclass may wish to stage files into the Update Manager, but the content is not templated. Subclasses
+      # can override this method to stage arbitrary files
       #
       # @api private
-      def write_file(dest_path)
-        PDK.logger.info(_("Creating '%{file}' from template.") % { file: dest_path })
-
-        file_content = yield
-
-        begin
-          FileUtils.mkdir_p(File.dirname(dest_path))
-        rescue SystemCallError => e
-          raise PDK::CLI::FatalError, _("Unable to create directory '%{path}': %{message}") % {
-            path:    File.dirname(dest_path),
-            message: e.message,
-          }
-        end
-
-        PDK::Util::Filesystem.write_file(dest_path, file_content)
-      rescue SystemCallError => e
-        raise PDK::CLI::FatalError, _("Unable to write to file '%{path}': %{message}") % {
-          path:    dest_path,
-          message: e.message,
-        }
+      # @return [Hash{String => String}] A Hash with the relative file path as the key and the new file content as the value.
+      # @abstract
+      def non_template_files
+        {}
       end
 
       # Search the possible template directories in order of preference to find
@@ -204,24 +152,24 @@ module PDK
       #
       # @api private
       def with_templates
+        require 'pdk/logger'
+        require 'pdk/util/template_uri'
+
         templates.each do |template|
-          if template[:url].nil?
-            PDK.logger.debug(_('No %{dir_type} template specified; trying next template directory.') % { dir_type: template[:type] })
+          if template[:uri].nil?
+            PDK.logger.debug(format('No %{dir_type} template found; trying next template directory.', dir_type: template[:type]))
             next
           end
 
-          PDK::Module::TemplateDir.new(template[:url]) do |template_dir|
-            template_paths = template_dir.object_template_for(object_type)
-
-            if template_paths
-              config_hash = template_dir.object_config
-              yield template_paths, config_hash
+          PDK::Template.with(PDK::Util::TemplateURI.new(template[:uri]), context) do |template_dir|
+            if template_files.any? { |source_file, _| template_dir.has_single_item?(source_file) }
+              yield template_dir
               # TODO: refactor to a search-and-execute form instead
               return # work is done # rubocop:disable Lint/NonLocalExitFromIterator
             elsif template[:allow_fallback]
-              PDK.logger.debug(_('Unable to find a %{type} template in %{url}; trying next template directory.') % { type: object_type, url: template[:url] })
+              PDK.logger.debug(format('Unable to find a %{type} template in %{url}; trying next template directory.', type: friendly_name, url: template[:uri]))
             else
-              raise PDK::CLI::FatalError, _('Unable to find the %{type} template in %{url}.') % { type: object_type, url: template[:url] }
+              raise PDK::CLI::FatalError, format('Unable to find the %{type} template in %{url}.', type: friendly_name, url: template[:uri])
             end
           end
         end
@@ -250,38 +198,31 @@ module PDK
       #
       # @api private
       def templates
-        @templates ||= [
-          { type: 'CLI', url: @options[:'template-url'], allow_fallback: false },
-          { type: 'metadata', url: module_metadata.data['template-url'], allow_fallback: true },
-          { type: 'default', url: PDK::Util.default_template_url, allow_fallback: false },
-        ]
+        require 'pdk/util/template_uri'
+
+        @templates ||= PDK::Util::TemplateURI.templates(@options)
       end
 
       # Retrieves the name of the module (without the forge username) from the
       # module metadata.
       #
-      # @raise (see #module_metadata)
       # @return [String] The name of the module.
       #
       # @api private
       def module_name
-        @module_name ||= module_metadata.data['name'].rpartition('-').last
+        return nil unless context.is_a?(PDK::Context::Module)
+
+        require 'pdk/util'
+        @module_name ||= PDK::Util.module_metadata(context.root_path)['name'].rpartition('-').last
+      rescue ArgumentError => e
+        raise PDK::CLI::FatalError, e
       end
 
-      # Parses the metadata.json file for the module.
-      #
-      # @raise [PDK::CLI::FatalError] if the metadata.json file does not exist,
-      #   can not be read, or contains invalid metadata.
-      #
-      # @return [PDK::Module::Metadata] the parsed module metadata.
-      #
-      # @api private
-      def module_metadata
-        @module_metadata ||= begin
-          PDK::Module::Metadata.from_file(File.join(module_dir, 'metadata.json'))
-        rescue ArgumentError => e
-          raise PDK::CLI::FatalError, _("'%{dir}' does not contain valid Puppet module metadata: %{msg}") % { dir: module_dir, msg: e.message }
-        end
+      private
+
+      # Transform an object name into a ruby class name
+      def class_name_from_object_name(object_name)
+        object_name.to_s.split('_').map(&:capitalize).join
       end
     end
   end

data/lib/pdk/generate/task.rb

@@ -1,46 +1,24 @@
-require 'pdk/generate/puppet_object'
+require 'pdk'
 
 module PDK
   module Generate
     class Task < PuppetObject
-      OBJECT_TYPE = :task
-
-      # Prepares the data needed to render the new task template.
-      #
-      # @return [Hash{Symbol => Object}] a hash of information that will be
-      # provided to the task template during rendering. Additionally, this hash
-      # (with the :name key removed) makes up the task metadata.
-      def template_data
-        {
-          name:                object_name,
-          puppet_task_version: 1,
-          supports_noop:       false,
-          description:         options.fetch(:description, 'A short description of this task'),
-          parameters:          {},
-        }
+      def friendly_name
+        'Task'
       end
 
-      # Calculates the path to the file where the new task will be written.
-      #
-      # @return [String] the path to the task file.
-      def target_object_path
-        @target_object_path ||= File.join(module_dir, 'tasks', "#{task_name}.sh")
-      end
+      def template_files
+        return {} if spec_only?
 
-      # Calculates the path to the file where the tests for the new task will
-      # be written.
-      #
-      # @return [nil] as there is currently no test framework for Tasks.
-      def target_spec_path
-        nil
+        {
+          'task.erb' => File.join('tasks', "#{task_name}.sh")
+        }
       end
 
-      def run
-        check_if_task_already_exists
-
-        super
-
-        write_task_metadata
+      def template_data
+        {
+          name: object_name
+        }
       end
 
       # Checks that the task has not already been defined with a different
@@ -48,30 +26,26 @@ module PDK
       #
       # @raise [PDK::CLI::ExitWithError] if files with the same name as the
       # task exist in the <module>/tasks/ directory
-      #
-      # @api private
-      def check_if_task_already_exists
-        error = _("A task named '%{name}' already exists in this module; defined in %{file}")
-        allowed_extensions = %w[.md .conf]
+      def check_preconditions
+        super
+
+        error = "A task named '%{name}' already exists in this module; defined in %{file}"
+        allowed_extensions = ['.md', '.conf']
 
-        Dir.glob(File.join(module_dir, 'tasks', "#{task_name}.*")).each do |file|
+        PDK::Util::Filesystem.glob(File.join(context.root_path, 'tasks', "#{task_name}.*")).each do |file|
           next if allowed_extensions.include?(File.extname(file))
 
-          raise PDK::CLI::ExitWithError, error % { name: task_name, file: file }
+          raise PDK::CLI::ExitWithError, format(error, name: task_name, file: file)
         end
       end
 
-      # Writes the <module>/tasks/<task_name>.json metadata file for the task.
-      #
-      # @api private
-      def write_task_metadata
-        write_file(File.join(module_dir, 'tasks', "#{task_name}.json")) do
-          task_metadata = template_data.dup
-          task_metadata.delete(:name)
-          JSON.pretty_generate(task_metadata)
-        end
+      def non_template_files
+        task_metadata_file = File.join('tasks', "#{task_name}.json")
+        { task_metadata_file => JSON.pretty_generate(task_metadata) }
       end
 
+      private
+
       # Calculates the file name of the task files ('init' if the task has the
       # same name as the module, otherwise use the specified task name).
       #
@@ -79,7 +53,16 @@ module PDK
       #
       # @api private
       def task_name
-        (object_name == module_name) ? 'init' : object_name
+        object_name == module_name ? 'init' : object_name
+      end
+
+      def task_metadata
+        {
+          puppet_task_version: 1,
+          supports_noop: false,
+          description: options.fetch(:description, 'A short description of this task'),
+          parameters: {}
+        }
       end
     end
   end

data/lib/pdk/generate/transport.rb

@@ -0,0 +1,34 @@
+require 'pdk'
+
+module PDK
+  module Generate
+    class Transport < PuppetObject
+      def friendly_name
+        'Resource API Transport'.freeze
+      end
+
+      def template_files
+        # NOTE: Due to how the V1 templates work, the names of the source template files may be mismatched to
+        # their destination, e.g. transport_type.erb is really a transport schema
+        files = {
+          'transport_spec.erb' => "#{File.join('spec', 'unit', 'puppet', 'transport', object_name)}_spec.rb",
+          'transport_type_spec.erb' => "#{File.join('spec', 'unit', 'puppet', 'transport', 'schema', object_name)}_spec.rb"
+        }
+        return files if spec_only?
+
+        files.merge(
+          'transport.erb' => "#{File.join('lib', 'puppet', 'transport', object_name)}.rb",
+          'transport_device.erb' => File.join('lib', 'puppet', 'util', 'network_device', object_name, 'device.rb'),
+          'transport_type.erb' => "#{File.join('lib', 'puppet', 'transport', 'schema', object_name)}.rb"
+        )
+      end
+
+      def template_data
+        {
+          name: object_name,
+          transport_class: class_name_from_object_name(object_name)
+        }
+      end
+    end
+  end
+end

data/lib/pdk/generate.rb

@@ -1,11 +1,24 @@
-require 'pdk/generate/defined_type'
-require 'pdk/generate/module'
-require 'pdk/generate/provider'
-require 'pdk/generate/puppet_class'
-require 'pdk/generate/task'
-require 'pdk/module/metadata'
-require 'pdk/module/templatedir'
+require 'pdk'
 
 module PDK
-  module Generate; end
+  module Generate
+    autoload :DefinedType, 'pdk/generate/defined_type'
+    autoload :Module, 'pdk/generate/module'
+    autoload :Provider, 'pdk/generate/provider'
+    autoload :PuppetClass, 'pdk/generate/puppet_class'
+    autoload :PuppetObject, 'pdk/generate/puppet_object'
+    autoload :Task, 'pdk/generate/task'
+    autoload :Transport, 'pdk/generate/transport'
+
+    def generators
+      @generators ||= [
+        PDK::Generate::DefinedType,
+        PDK::Generate::Provider,
+        PDK::Generate::PuppetClass,
+        PDK::Generate::Task,
+        PDK::Generate::Transport
+      ].freeze
+    end
+    module_function :generators
+  end
 end

data/lib/pdk/logger.rb

@@ -1,22 +1,40 @@
 require 'logger'
+require 'pdk'
 
 module PDK
-  def self.logger
-    @logger ||= PDK::Logger.new
-  end
-
   class Logger < ::Logger
+    WRAP_COLUMN_LIMIT = 78
+
     def initialize
-      super(STDERR)
+      super($stderr)
+      @sent_messages = {}
 
       # TODO: Decide on output format.
       self.formatter = proc do |severity, _datetime, _progname, msg|
-        "pdk (#{severity}): #{msg}\n"
+        prefix = "pdk (#{severity}): "
+        if msg.is_a?(Hash)
+          if msg.fetch(:wrap, false)
+            wrap_pattern = /(.{1,#{WRAP_COLUMN_LIMIT - prefix.length}})(\s+|\Z)/
+            "#{prefix}#{msg[:text].gsub(wrap_pattern, "\\1\n#{' ' * prefix.length}")}\n"
+          else
+            "#{prefix}#{msg[:text]}\n"
+          end
+        else
+          "#{prefix}#{msg}\n"
+        end
       end
 
       self.level = ::Logger::INFO
     end
 
+    def warn_once(*args)
+      hash = args.inspect.hash
+      return if (@sent_messages[::Logger::WARN] ||= {}).key?(hash)
+
+      @sent_messages[::Logger::WARN][hash] = true
+      warn(*args)
+    end
+
     def enable_debug_output
       self.level = ::Logger::DEBUG
     end